An npm scope, stored without its leading '@' (the scope of @myorg/pkg is "myorg"). Construct via mkScope, which normalises away a leading '@' so equality is independent of how the scope was written.

A scope is a bulk-stored, equality-only identifier (an allow-list key and part of PackageName identity), so it is held as ShortText: the Text -> ShortText conversion happens once in mkScope and the reverse once in unScope/renderScope, never in a hot loop (see STYLE.md §6).

Build a Scope, tolerating an optional leading '@'.

The bare scope text, without the leading '@'.

Render a scope in npm wire form, with the leading '@'.

A package identity, decoupled from any registry's wire format.

Identity differs by ecosystem -- npm has scopes and is case-sensitive, PyPI normalises per PEP 503, RubyGems is verbatim -- so the type is opaque: build it with mkPackageName, which records the ecosystem, computes a pkgCanonical key used for equality/matching, and keeps a pkgDisplay form for faithful rendering. Equality and ordering are on (pkgEcosystem, pkgNamespace, pkgCanonical) only -- never the display or base form -- so Flask and flask are the same PyPI package but different npm ones.

Build a PackageName, normalising the canonical key for the ecosystem.

The display form is the scope-joined raw name (@scope/name when scoped); the canonical key is that form normalised: PEP 503 lower-casing and [-_.]+→- collapsing for PyPI, verbatim for npm and RubyGems.

The ecosystem this name belongs to.

The scope, if scoped (npm @scope/name). Nothing for PyPI/RubyGems.

The normalised key for equality and matching (PEP 503 for PyPI; verbatim for npm/RubyGems). Held as ShortText: it is an equality/Ord key that is normalised once at mkPackageName and never sliced afterwards.

The name as published, for rendering and round-tripping. Held as ShortText; read it back as Text through renderPackageName.

The unscoped base name: the published name with any @scope/ prefix dropped (@babel/code-frame → code-frame). Stored structurally at mkPackageName (it is exactly the bare name the constructor is given), so the npm tarball/path layer and the mirror queue read it as a field rather than re-slicing the display form. Not part of identity (like pkgDisplay); held as ShortText and read back as Text through unscopedName.

Render a package name in its native wire form (the display name).

The unscoped (base) name as Text (@babel/code-frame → code-frame): the ShortText pkgBaseName field read back. The single home for the bare-name the npm tarball/path layer and the mirror queue all need; it is stored structurally at mkPackageName rather than reconstructed by rendering then string-stripping the scope.

Whether installing a version executes code (the cross-ecosystem unification of npm install scripts, PyPI sdist builds, and RubyGems native extensions).

The trust/provenance signal for a version. The how of trust differs by ecosystem (npm dist.signatures, PyPI PEP 740 attestations, RubyGems signed gems/MFA) but is captured as TrustEvidence so rules stay ecosystem-blind.

A normalised reason a version is trusted; the adapter maps its ecosystem's mechanism onto this vocabulary.

Whether a version is offered, advisory-deprecated, or withdrawn.

One distribution file for a version. A version owns a NonEmpty list of these: npm has exactly one, PyPI has an sdist plus many wheels, RubyGems has one per platform.

What kind of distribution file an artifact is.

An integrity digest of an artifact. Opaque: a Hash is built only through mkHash, which validates that the digest is well-formed, so every value of this type carries the proof that its digest could be a real digest of its algorithm. Read it back through hashAlg and hashValue.

The algorithm the digest was computed with.

The digest itself, in the algorithm's wire encoding (e.g. hex, or the single sha512-… component for SRI).

Build a Hash, validating that the digest is structurally well-formed: cleanly encoded and exactly the byte length its algorithm specifies. This is the only way to construct a Hash, so the type itself is the proof that the digest could be a real digest of that algorithm -- an empty, truncated, over-long, non-hex, or bad-base64 value is unconstructable and so can never reach an integrity gate as a degenerate digest (the fail-open this closes is docs/architecture/security.md invariant 5).

Well-formedness is not admissibility: a well-formed but weak SHA-1 digest builds fine; whether it clears the public-integrity floor is the separate decision of Ecluse.Core.Package.Integrity. mkHash rejects a malformed digest, never a merely weak one.

A hex-tagged algorithm (everything but SRI) takes lower- or upper-case hex of the algorithm's digest length. An SRI takes exactly one <alg>-<base64> component, naming a Subresource-Integrity algorithm (sha256, sha384, sha512) whose base64 body decodes to that algorithm's digest length. A wire string that joins several components with whitespace is malformed here: split it with mkSriHashes, which yields one Hash per component, so no reader ever has to decide which component of a joined string a Hash means.

>>> import Ecluse.Core.Package.Hash (HashAlg (SHA1))
>>> fmap hashAlg (mkHash SHA1 "0a4d55a8d778e5022fab701977c5d840bbc486d0")
Right SHA1

>>> mkHash SHA1 "deadbeef"
Left "malformed sha1 digest"

Split a Subresource-Integrity wire string -- one or more whitespace-separated <alg>-<base64> components (npm's dist.integrity) -- into one SRI Hash per component, each built through the validating mkHash. The whole string is rejected when it carries no component or any component is malformed, so a partially-valid value never yields a partial digest set.

This is the one intended path from wire data to SRI hashes. Because each resulting Hash holds exactly one component, the admission floor, the worker's tamper gate, and the divergence fingerprint all resolve the same algorithm and digest body from it -- there is no joined string left for two consumers to read two different ways.

>>> fmap length (mkSriHashes "sha512-z4PhNX7vuL3xVChQ1m2AB9Yg5AULVxXcg/SpIdNs6c5H0NE8XYXysP+DGNKHfuwvY7kxvUdBeoGlODJ6+SfaPg== sha256-47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=")
Right 2

>>> mkSriHashes "  "
Left "malformed sri digest"

A hash algorithm an integrity digest is computed with.

The Ord instance is the integrity authority order, not constructor order: SRI < MD5 < SHA1 < SHA256 < SHA384 < Blake2b < SHA512. A bare SRI is a wrapper, not an algorithm; callers that care about its embedded algorithm should resolve it first.

The lower-case wire name of an algorithm -- the canonical spelling parseHashAlg reads back. Total and injective, so it doubles as config rendering and error text.

>>> renderHashAlg SHA256
"sha256"

Parse an algorithm name, tolerating surrounding whitespace and case, and a single family-separating '-' (so "SHA-256" and "sha256" both parse). It accepts only the canonical names and their documented single-dash aliases: it does not strip arbitrary internal dashes, so a typo such as "s-h-a--2-5-6" is rejected rather than silently read as sha256. An unrecognised name is reported as such, distinct from a recognised-but-too-weak floor. The sri wrapper is not a config-selectable algorithm and is rejected.

>>> parseHashAlg "SHA-256"
Right SHA256

>>> parseHashAlg "frobnicate"
Left "unknown integrity algorithm: frobnicate"

The algorithm-name token of a Subresource-Integrity string -- the <alg> before the first '-' in <alg>-<base64>. A string with no '-' is all prefix.

>>> sriPrefix "sha512-Zm9vYmFy"
"sha512"

The base64 digest body of a Subresource-Integrity string -- the <base64> after the first '-' in <alg>-<base64>. A string with no '-' has an empty body.

>>> sriBody "sha512-Zm9vYmFy"
"Zm9vYmFy"

The HashAlg a Subresource-Integrity string names, read from its <alg> prefix. The prefixes resolved are the Subresource-Integrity set sha256, sha384 and sha512 (every long digest the model represents and a registry serves); an unrecognised or malformed prefix yields Nothing, so the string asserts no algorithm and clears no floor (the fail-closed reading).

>>> sriAlgorithm "sha512-Zm9vYmFy"
Just SHA512

>>> sriAlgorithm "sha384-Zm9vYmFy"
Just SHA384

Compute the digest of bytes in a given algorithm, as the raw digest bytes, or Nothing for an algorithm Écluse will not verify against. The computable algorithms are exactly the collision-resistant ones: SHA1, SHA256, SHA384, SHA512, and Blake2b-512. MD5 is deliberately uncomputable here (a match on a broken hash cannot prove the bytes were not substituted, so the tamper gate never verifies against it), as is the bare SRI wrapper, which names no algorithm of its own (resolve it with sriAlgorithm first).

This is the sibling of hexDigestOk: both dispatch on the same per-algorithm crypto type, so they live together and a new HashAlg must be given an arm in each (the 'case' is total, and the package builds with -Wincomplete-patterns as an error). It is the one place that defines which algorithms the worker can verify; the integrity floor admits by strength (Ecluse.Core.Package.Integrity), and the invariant that every floor-clearing algorithm is computable here keeps the worker able to verify whatever the floor admits.

Whether the worker can compute (and so verify a digest in) the given algorithm: the predicate form of computeDigest, taken from the same single definition so the computable set cannot drift from what computeDigest actually computes.

>>> isComputable SHA256
True

>>> isComputable MD5
False

A person associated with a package (author, maintainer, or publisher).

The ecosystem-agnostic snapshot of a single package version that the rules engine evaluates. A registry adapter projects its wire format into this; the rules engine never sees anything else, and never branches on the ecosystem.

The packument-level view of a package: the whole-package metadata document (PackageDetails is the per-version snapshot embedded within it). A registry adapter projects a registry's packument (the npm full-metadata document) into this; the proxy core reasons over it without ever seeing the wire format.

A single packument entry a registry projection dropped as malformed rather than failing the entire document, kept so the drop is observable rather than silent (an operator can see that an upstream served a malformed entry, and which). Each ecosystem's projection populates this from its own wire shape, so the drop-and-track contract is the same across npm, PyPI, and RubyGems.

Which kind of registry-document entry a dropped InvalidEntry came from. A version manifest drop removes a serve candidate (fail-closed for that one version); a dist-tag or publish-time drop loses only that advisory datum while the version it referred to still resolves.