@entelekheia/ref-id 0.1.0

package/README.md

@@ -0,0 +1,38 @@
+# @entelekheia/ref-id
+
+**Parse, serialise, digest and validate `ref:` identifiers — against a specification shipped as data.**
+The package embeds `spec/ref-id.json` and is held to it by that file's conformance vectors.
+
+```text
+ref:[<version>:]<type>:<locator>[;<qualifier>=<value>]*[#<declared-name-path>[;<refinement>=<value>]*]
+```
+
+<!-- PROOF PLACEHOLDER: copy the smallest runnable example from test/ once the vectors pass. -->
+
+## Why
+
+Naming a thing by its file path breaks on the first move; naming it by a content hash breaks on the first
+edit. `ref:` names it by what its format declared — a Package URL when a manifest proves the name, a
+declared corpus name when nothing does — and keeps state (`;at=`), instrument (`;by=`) and population
+(`;over=`) as qualifiers rather than folding them into the name. One regular expression decomposes an
+identifier; each captured part is handed to the validator that already owns that format.
+
+## Install
+
+```sh
+npm install @entelekheia/ref-id
+```
+
+## Usage
+
+The entry points are `parse`, `serialise`, `digest` and `validateEnvelope`; their contracts are the
+vectors in `spec/ref-id.json` (`parse`, `roundtrip`, `digest`, `envelope`). An unknown locator type parses
+and degrades to `uncovered`; it never throws.
+
+## Requirements
+
+Node.js 22 or later. Runtime dependency: `packageurl-js` (pure JavaScript). No native modules.
+
+## License
+
+Apache-2.0 — see the repository's `LICENSE`.

package/dist/build.d.ts

@@ -0,0 +1,3 @@
+import type { BuildParts } from "./types.ts";
+/** Builds a `ref:` identifier string. `parts.location` is ignored — it never reaches the identity. */
+export declare function build(parts: BuildParts): string;

package/dist/build.js

@@ -0,0 +1,138 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Assembles a `ref:` identifier string from its parts. A part the grammar cannot carry is refused
+// with a BuildError naming it — the builder never emits a string that means something else, which
+// is proven at the end by parsing what was built and comparing it with what was asked. The
+// nested-value encoding comes from the form's own table; a locator is never encoded.
+import { containsAny, encodeReserved, tableFor } from "./encoding.js";
+import { BuildError } from "./errors.js";
+import { FIELD, FRAGMENT_INTRODUCER, LINE_BREAKS, PAIR, schemePrefix, statePairGrammar, topLevelGrammar } from "./grammar.js";
+import { loadSpec, part, status } from "./spec.js";
+import { parse } from "./parse.js";
+import { foldsType } from "./validators.js";
+/** The form, among a qualifier's declared forms, that nests an identifier — where the encoding table lives. */
+function nestingForm(spec, key) {
+    const declared = spec.qualifiers[key];
+    if (!declared) {
+        return undefined;
+    }
+    return declared.forms.map((name) => spec.forms[name]).find((form) => form?.nested);
+}
+function refuse(spec, failedPart, why) {
+    throw new BuildError(part(spec, failedPart), `cannot build: ${why}`);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Builds a `ref:` identifier string. `parts.location` is ignored — it never reaches the identity. */
+export function build(parts) {
+    const spec = loadSpec();
+    if (!isRecord(parts) || typeof parts.type !== "string") {
+        refuse(spec, "type", "parts must be an object with a string type");
+    }
+    if (typeof parts.locator !== "string") {
+        refuse(spec, "locator", "the locator must be a string");
+    }
+    const separators = [spec.grammar.state.separator, FRAGMENT_INTRODUCER, ...LINE_BREAKS];
+    let locator = parts.locator;
+    const fold = `${parts.type}${FIELD}`;
+    if (foldsType(spec, parts.type) && locator.startsWith(fold)) {
+        locator = locator.slice(fold.length);
+    }
+    if (locator === "" || containsAny(locator, separators)) {
+        refuse(spec, "locator", "a locator is handed to its validator verbatim and cannot carry a reserved character");
+    }
+    let out = `${schemePrefix(spec)}${parts.type}${FIELD}${locator}`;
+    const qualifiers = parts.qualifiers ?? [];
+    if (!Array.isArray(qualifiers)) {
+        refuse(spec, "state", "qualifiers must be an array of pairs");
+    }
+    if (qualifiers.length > 0) {
+        const pairGrammar = statePairGrammar(spec);
+        const rendered = [];
+        for (const entry of qualifiers) {
+            if (!Array.isArray(entry) || typeof entry[0] !== "string") {
+                refuse(spec, "state", "a qualifier is a [key, value] pair with a string key");
+            }
+            const [key, value] = entry;
+            let encoded;
+            if (typeof value === "string") {
+                if (value.startsWith(schemePrefix(spec)) || containsAny(value, separators)) {
+                    refuse(spec, key, "a nested identifier is passed as { nested }, never as a plain string");
+                }
+                encoded = value;
+            }
+            else if (isRecord(value) && typeof value.nested === "string") {
+                const form = nestingForm(spec, key);
+                if (!form) {
+                    refuse(spec, key, "this qualifier declares no nesting form");
+                }
+                encoded = encodeReserved(value.nested, tableFor(spec, form));
+            }
+            else {
+                refuse(spec, key, "a qualifier value is a string or { nested: string }");
+            }
+            const rendering = `${key}${PAIR}${encoded}`;
+            if (!pairGrammar.test(rendering)) {
+                refuse(spec, key, "the key does not fit the pair grammar");
+            }
+            rendered.push(rendering);
+        }
+        out += `${spec.grammar.state.separator}${rendered.join(spec.grammar.state.separator)}`;
+    }
+    let wantedPath;
+    let wantedRefinements = [];
+    if (parts.fragment !== undefined) {
+        const separator = spec.grammar.fragment.separator;
+        if (typeof parts.fragment === "string") {
+            wantedPath = parts.fragment;
+        }
+        else if (isRecord(parts.fragment) && typeof parts.fragment.path === "string") {
+            wantedPath = parts.fragment.path;
+            wantedRefinements = parts.fragment.refinements ?? [];
+            if (!Array.isArray(wantedRefinements)) {
+                refuse(spec, "fragment", "refinements must be an array of pairs");
+            }
+        }
+        else {
+            refuse(spec, "fragment", "a fragment is a string or { path, refinements }");
+        }
+        if (wantedPath === "" || containsAny(wantedPath, [separator, ...LINE_BREAKS])) {
+            refuse(spec, "fragment", "a declared-name path cannot be empty or carry the refinement separator");
+        }
+        for (const entry of wantedRefinements) {
+            if (!Array.isArray(entry) || typeof entry[0] !== "string" || typeof entry[1] !== "string") {
+                refuse(spec, "fragment", "a refinement is a [key, value] pair of strings");
+            }
+            if (containsAny(entry[1], [separator, ...LINE_BREAKS])) {
+                refuse(spec, entry[0], "a refinement value cannot carry the separator");
+            }
+        }
+        out += `${FRAGMENT_INTRODUCER}${wantedPath}`;
+        if (wantedRefinements.length > 0) {
+            out += `${separator}${wantedRefinements.map(([key, value]) => `${key}${PAIR}${value}`).join(separator)}`;
+        }
+    }
+    // The last word is the grammar's: what was built must decompose to exactly what was asked.
+    if (!topLevelGrammar(spec).test(out)) {
+        refuse(spec, "grammar", "the assembled string does not match the grammar");
+    }
+    const check = parse(out);
+    if (check.status === status(spec, "malformed")) {
+        refuse(spec, check.part ?? "grammar", "the assembled string is malformed");
+    }
+    if (check.explicitVersion || check.type !== parts.type) {
+        refuse(spec, "type", "the type re-split into other parts");
+    }
+    if (check.locator !== locator) {
+        refuse(spec, "locator", "the locator re-split into other parts");
+    }
+    if (check.qualifiers.length !== qualifiers.length) {
+        refuse(spec, "state", "a qualifier re-split into other parts");
+    }
+    if ((check.fragment?.path ?? undefined) !== wantedPath || (check.fragment?.refinements.length ?? 0) !== wantedRefinements.length) {
+        refuse(spec, "fragment", "the fragment re-split into other parts");
+    }
+    return out;
+}
+//# sourceMappingURL=build.js.map

package/dist/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,EAAE;AACF,kGAAkG;AAClG,kGAAkG;AAClG,2FAA2F;AAC3F,qFAAqF;AAErF,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,IAAI,EAAE,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAC7H,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAkB,MAAM,WAAW,CAAA;AAClE,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAElC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAE3C,+GAA+G;AAC/G,SAAS,WAAW,CAAC,IAAe,EAAE,GAAW;IAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAA;IACrC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,OAAO,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;AACpF,CAAC;AAED,SAAS,MAAM,CAAC,IAAe,EAAE,UAAkB,EAAE,GAAW;IAC9D,MAAM,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,iBAAiB,GAAG,EAAE,CAAC,CAAA;AACtE,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;AAC7E,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,KAAK,CAAC,KAAiB;IACrC,MAAM,IAAI,GAAG,QAAQ,EAAE,CAAA;IACvB,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACvD,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,4CAA4C,CAAC,CAAA;IACpE,CAAC;IACD,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACtC,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,8BAA8B,CAAC,CAAA;IACzD,CAAC;IACD,MAAM,UAAU,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,EAAE,mBAAmB,EAAE,GAAG,WAAW,CAAC,CAAA;IAEtF,IAAI,OAAO,GAAG,KAAK,CAAC,OAAO,CAAA;IAC3B,MAAM,IAAI,GAAG,GAAG,KAAK,CAAC,IAAI,GAAG,KAAK,EAAE,CAAA;IACpC,IAAI,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5D,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IACtC,CAAC;IACD,IAAI,OAAO,KAAK,EAAE,IAAI,WAAW,CAAC,OAAO,EAAE,UAAU,CAAC,EAAE,CAAC;QACvD,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,qFAAqF,CAAC,CAAA;IAChH,CAAC;IAED,IAAI,GAAG,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,IAAI,GAAG,KAAK,GAAG,OAAO,EAAE,CAAA;IAEhE,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,IAAI,EAAE,CAAA;IACzC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QAC/B,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,sCAAsC,CAAC,CAAA;IAC/D,CAAC;IACD,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,WAAW,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAA;QAC1C,MAAM,QAAQ,GAAa,EAAE,CAAA;QAC7B,KAAK,MAAM,KAAK,IAAI,UAAU,EAAE,CAAC;YAC/B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC;gBAC1D,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,sDAAsD,CAAC,CAAA;YAC/E,CAAC;YACD,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,KAAK,CAAA;YAC1B,IAAI,OAAe,CAAA;YACnB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAC9B,IAAI,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,IAAI,WAAW,CAAC,KAAK,EAAE,UAAU,CAAC,EAAE,CAAC;oBAC3E,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE,sEAAsE,CAAC,CAAA;gBAC3F,CAAC;gBACD,OAAO,GAAG,KAAK,CAAA;YACjB,CAAC;iBAAM,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;gBAC/D,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;gBACnC,IAAI,CAAC,IAAI,EAAE,CAAC;oBACV,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE,yCAAyC,CAAC,CAAA;gBAC9D,CAAC;gBACD,OAAO,GAAG,cAAc,CAAC,KAAK,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAA;YAC9D,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE,qDAAqD,CAAC,CAAA;YAC1E,CAAC;YACD,MAAM,SAAS,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,OAAO,EAAE,CAAA;YAC3C,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;gBACjC,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE,uCAAuC,CAAC,CAAA;YAC5D,CAAC;YACD,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;QAC1B,CAAC;QACD,GAAG,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAA;IACxF,CAAC;IAED,IAAI,UAA8B,CAAA;IAClC,IAAI,iBAAiB,GAAW,EAAE,CAAA;IAClC,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QACjC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAA;QACjD,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACvC,UAAU,GAAG,KAAK,CAAC,QAAQ,CAAA;QAC7B,CAAC;aAAM,IAAI,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,OAAO,KAAK,CAAC,QAAQ,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC/E,UAAU,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAA;YAChC,iBAAiB,GAAG,KAAK,CAAC,QAAQ,CAAC,WAAW,IAAI,EAAE,CAAA;YACpD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE,CAAC;gBACtC,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,uCAAuC,CAAC,CAAA;YACnE,CAAC;QACH,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,iDAAiD,CAAC,CAAA;QAC7E,CAAC;QACD,IAAI,UAAU,KAAK,EAAE,IAAI,WAAW,CAAC,UAAU,EAAE,CAAC,SAAS,EAAE,GAAG,WAAW,CAAC,CAAC,EAAE,CAAC;YAC9E,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,wEAAwE,CAAC,CAAA;QACpG,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,iBAAiB,EAAE,CAAC;YACtC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC;gBAC1F,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,gDAAgD,CAAC,CAAA;YAC5E,CAAC;YACD,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,WAAW,CAAC,CAAC,EAAE,CAAC;gBACvD,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,+CAA+C,CAAC,CAAA;YACzE,CAAC;QACH,CAAC;QACD,GAAG,IAAI,GAAG,mBAAmB,GAAG,UAAU,EAAE,CAAA;QAC5C,IAAI,iBAAiB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACjC,GAAG,IAAI,GAAG,SAAS,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,GAAG,IAAI,GAAG,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAA;QAC1G,CAAC;IACH,CAAC;IAED,2FAA2F;IAC3F,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACrC,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,iDAAiD,CAAC,CAAA;IAC5E,CAAC;IACD,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAA;IACxB,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC,IAAI,EAAE,WAAW,CAAC,EAAE,CAAC;QAC/C,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,SAAS,EAAE,mCAAmC,CAAC,CAAA;IAC5E,CAAC;IACD,IAAI,KAAK,CAAC,eAAe,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,EAAE,CAAC;QACvD,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,oCAAoC,CAAC,CAAA;IAC5D,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;QAC9B,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,uCAAuC,CAAC,CAAA;IAClE,CAAC;IACD,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,KAAK,UAAU,CAAC,MAAM,EAAE,CAAC;QAClD,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,uCAAuC,CAAC,CAAA;IAChE,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,IAAI,SAAS,CAAC,KAAK,UAAU,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,IAAI,CAAC,CAAC,KAAK,iBAAiB,CAAC,MAAM,EAAE,CAAC;QACjI,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,wCAAwC,CAAC,CAAA;IACpE,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/dist/digest.d.ts

@@ -0,0 +1,2 @@
+/** Digests an ordered, non-deduplicated sequence of identifier strings. */
+export declare function digest(members: readonly string[]): string;

package/dist/digest.js

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// sha256 over the UTF-8 bytes of the joined identifier strings, per `spec.digest`: declared order,
+// no deduplication, and a refusal for a member that carries the join character — without it two
+// different sequences could share one digest, and the envelope invariant would admit both.
+import { createHash } from "node:crypto";
+import { DigestError } from "./errors.js";
+import { FIELD } from "./grammar.js";
+import { loadSpec, part } from "./spec.js";
+/** Digests an ordered, non-deduplicated sequence of identifier strings. */
+export function digest(members) {
+    const spec = loadSpec();
+    if (!Array.isArray(members)) {
+        throw new DigestError(part(spec, "member"), "members must be an array of strings");
+    }
+    const snapshot = Array.from(members);
+    for (const member of snapshot) {
+        if (typeof member !== "string" || member.includes(spec.digest.join)) {
+            throw new DigestError(part(spec, "member"), "a member must be a string that does not carry the join character");
+        }
+    }
+    const joined = snapshot.join(spec.digest.join);
+    const hex = createHash(spec.digest.algorithm).update(joined, spec.digest.encoding).digest("hex");
+    return `${spec.digest.algorithm}${FIELD}${hex}`;
+}
+//# sourceMappingURL=digest.js.map

package/dist/digest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"digest.js","sourceRoot":"","sources":["../src/digest.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,EAAE;AACF,mGAAmG;AACnG,gGAAgG;AAChG,2FAA2F;AAE3F,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAE1C,2EAA2E;AAC3E,MAAM,UAAU,MAAM,CAAC,OAA0B;IAC/C,MAAM,IAAI,GAAG,QAAQ,EAAE,CAAA;IACvB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,qCAAqC,CAAC,CAAA;IACpF,CAAC;IACD,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IACpC,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC9B,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YACpE,MAAM,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,kEAAkE,CAAC,CAAA;QACjH,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IAC9C,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,QAA0B,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAClH,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,GAAG,KAAK,GAAG,GAAG,EAAE,CAAA;AACjD,CAAC"}

package/dist/encoding.d.ts

@@ -0,0 +1,18 @@
+import type { RefIdSpec } from "./spec.ts";
+/** The encoding table a form declares, or none when the form declares no encoding. */
+export declare function tableFor(spec: RefIdSpec, form: {
+    encoding?: string;
+}): Record<string, string>;
+/** True when `raw` contains any of the given characters. */
+export declare function containsAny(raw: string, characters: readonly string[]): boolean;
+/**
+ * Encodes each reserved character in `raw` to its declared percent-form, in one left-to-right
+ * pass over the *source* characters (so a percent-form produced by this pass is never itself
+ * re-scanned).
+ */
+export declare function encodeReserved(raw: string, table: Record<string, string>): string;
+/**
+ * Decodes each percent-form declared in `table` back to its single character, in one
+ * left-to-right pass over `encoded` (so decoding `%2523` yields `%23`, never `#`).
+ */
+export declare function decodeReserved(encoded: string, table: Record<string, string>): string;

package/dist/encoding.js

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Percent-encode/decode helpers driven by an `encoding.<name>.table` from the spec — never a
+// hardcoded character list. Which table applies to a form is the form's own `encoding` field.
+/** The encoding table a form declares, or none when the form declares no encoding. */
+export function tableFor(spec, form) {
+    if (!form.encoding) {
+        return {};
+    }
+    return spec.encoding[form.encoding]?.table ?? {};
+}
+/** True when `raw` contains any of the given characters. */
+export function containsAny(raw, characters) {
+    return characters.some((character) => raw.includes(character));
+}
+/**
+ * Encodes each reserved character in `raw` to its declared percent-form, in one left-to-right
+ * pass over the *source* characters (so a percent-form produced by this pass is never itself
+ * re-scanned).
+ */
+export function encodeReserved(raw, table) {
+    if (Object.keys(table).length === 0) {
+        return raw;
+    }
+    let out = "";
+    for (const char of raw) {
+        out += table[char] ?? char;
+    }
+    return out;
+}
+/**
+ * Decodes each percent-form declared in `table` back to its single character, in one
+ * left-to-right pass over `encoded` (so decoding `%2523` yields `%23`, never `#`).
+ */
+export function decodeReserved(encoded, table) {
+    const forms = Object.values(table);
+    if (forms.length === 0) {
+        return encoded;
+    }
+    const reverse = new Map();
+    for (const [char, form] of Object.entries(table)) {
+        reverse.set(form, char);
+    }
+    const pattern = new RegExp(forms.map((form) => form.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|"), "g");
+    return encoded.replace(pattern, (match) => reverse.get(match) ?? match);
+}
+//# sourceMappingURL=encoding.js.map

package/dist/encoding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoding.js","sourceRoot":"","sources":["../src/encoding.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,EAAE;AACF,6FAA6F;AAC7F,8FAA8F;AAI9F,sFAAsF;AACtF,MAAM,UAAU,QAAQ,CAAC,IAAe,EAAE,IAA2B;IACnE,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACnB,OAAO,EAAE,CAAA;IACX,CAAC;IACD,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,KAAK,IAAI,EAAE,CAAA;AAClD,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,UAA6B;IACpE,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAA;AAChE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW,EAAE,KAA6B;IACvE,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpC,OAAO,GAAG,CAAA;IACZ,CAAC;IACD,IAAI,GAAG,GAAG,EAAE,CAAA;IACZ,KAAK,MAAM,IAAI,IAAI,GAAG,EAAE,CAAC;QACvB,GAAG,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,CAAA;IAC5B,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe,EAAE,KAA6B;IAC3E,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAClC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,OAAO,CAAA;IAChB,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAA;IACzC,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IACzB,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAA;IAC3G,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,CAAA;AACzE,CAAC"}

package/dist/envelope.d.ts

@@ -0,0 +1,3 @@
+import type { EnvelopeResult } from "./types.ts";
+/** Refuses an envelope whose self-reference or recomputed digests do not hold. */
+export declare function validateEnvelope(requestedId: string, envelope: unknown): EnvelopeResult;

package/dist/envelope.js

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// The envelope invariant from spec.envelope: an identifier carrying a digest is admissible only
+// with an object whose sets entry for that qualifier recomputes to it, served under its own id.
+import { digest } from "./digest.js";
+import { DigestError } from "./errors.js";
+import { pattern } from "./grammar.js";
+import { parse } from "./parse.js";
+import { loadSpec, SpecVersionError, status } from "./spec.js";
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function ownField(record, field) {
+    return Object.hasOwn(record, field) ? record[field] : undefined;
+}
+/** Refuses an envelope whose self-reference or recomputed digests do not hold. */
+export function validateEnvelope(requestedId, envelope) {
+    const spec = loadSpec();
+    const setsField = spec.envelope.setsField;
+    if (typeof envelope !== "object" || envelope === null || Array.isArray(envelope)) {
+        return { admissible: false, reason: "envelope is not an object" };
+    }
+    const record = envelope;
+    if (ownField(record, spec.envelope.selfReference) !== requestedId) {
+        return { admissible: false, reason: `envelope.${spec.envelope.selfReference} does not match the requested identifier` };
+    }
+    const parsed = parse(requestedId);
+    if (parsed.status === status(spec, "malformed") || parsed.status === status(spec, "unsupported")) {
+        return { admissible: false, reason: `the requested identifier is ${parsed.status}` };
+    }
+    // spec.envelope.digestForms: every form declaring digest: true. One without a pattern cannot be recognised — a spec this package cannot honour.
+    const digestForms = Object.entries(spec.forms)
+        .filter(([, form]) => form.digest)
+        .map(([name, form]) => {
+        if (!form.pattern) {
+            throw new SpecVersionError(`spec.forms.${name} declares digest: true without a pattern; this package cannot recognise it`);
+        }
+        return pattern(spec, form.pattern);
+    });
+    const sets = ownField(record, setsField);
+    for (const [key, value] of parsed.qualifiers) {
+        if (!digestForms.some((form) => form.test(value))) {
+            continue;
+        }
+        const entry = typeof sets === "object" && sets !== null && !Array.isArray(sets) ? ownField(sets, key) : undefined;
+        // One read, then a copy: the members that are checked are the members that are hashed.
+        const members = Array.isArray(entry) ? Array.from(entry) : undefined;
+        if (!isStringArray(members)) {
+            return { admissible: false, reason: `${setsField}.${key} is missing or is not an array of strings` };
+        }
+        let recomputed;
+        try {
+            recomputed = digest(members);
+        }
+        catch (error) {
+            if (error instanceof DigestError) {
+                return { admissible: false, reason: `${setsField}.${key} carries a member with the join character` };
+            }
+            throw error;
+        }
+        if (recomputed !== value) {
+            return { admissible: false, reason: `${setsField}.${key} does not recompute to the declared digest` };
+        }
+    }
+    return { admissible: true };
+}
+//# sourceMappingURL=envelope.js.map

package/dist/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,17 @@
+/** Base of every error that names the part of an identifier it concerns. */
+export declare class RefIdError extends Error {
+    readonly part: string;
+    constructor(name: string, part: string, message: string);
+}
+/** `build` was given a part the grammar cannot carry. */
+export declare class BuildError extends RefIdError {
+    constructor(part: string, message: string);
+}
+/** `digest` was given a member that is not one identifier string. */
+export declare class DigestError extends RefIdError {
+    constructor(part: string, message: string);
+}
+/** `serialise` was given a result that has no faithful string form. */
+export declare class SerialiseError extends RefIdError {
+    constructor(part: string, message: string);
+}

package/dist/errors.js

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// The typed errors the producer-side API raises. `parse` never throws for an identifier problem;
+// `build`, `digest` and `serialise` do, because a producer asked for something the scheme cannot
+// represent, and returning a string that means something else would be the silent failure the
+// specification names.
+/** Base of every error that names the part of an identifier it concerns. */
+export class RefIdError extends Error {
+    part;
+    constructor(name, part, message) {
+        super(message);
+        this.name = name;
+        this.part = part;
+    }
+}
+/** `build` was given a part the grammar cannot carry. */
+export class BuildError extends RefIdError {
+    constructor(part, message) {
+        super("BuildError", part, message);
+    }
+}
+/** `digest` was given a member that is not one identifier string. */
+export class DigestError extends RefIdError {
+    constructor(part, message) {
+        super("DigestError", part, message);
+    }
+}
+/** `serialise` was given a result that has no faithful string form. */
+export class SerialiseError extends RefIdError {
+    constructor(part, message) {
+        super("SerialiseError", part, message);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,EAAE;AACF,iGAAiG;AACjG,iGAAiG;AACjG,8FAA8F;AAC9F,uBAAuB;AAEvB,4EAA4E;AAC5E,MAAM,OAAO,UAAW,SAAQ,KAAK;IAC1B,IAAI,CAAQ;IACrB,YAAY,IAAY,EAAE,IAAY,EAAE,OAAe;QACrD,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF;AAED,yDAAyD;AACzD,MAAM,OAAO,UAAW,SAAQ,UAAU;IACxC,YAAY,IAAY,EAAE,OAAe;QACvC,KAAK,CAAC,YAAY,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;IACpC,CAAC;CACF;AAED,qEAAqE;AACrE,MAAM,OAAO,WAAY,SAAQ,UAAU;IACzC,YAAY,IAAY,EAAE,OAAe;QACvC,KAAK,CAAC,aAAa,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;IACrC,CAAC;CACF;AAED,uEAAuE;AACvE,MAAM,OAAO,cAAe,SAAQ,UAAU;IAC5C,YAAY,IAAY,EAAE,OAAe;QACvC,KAAK,CAAC,gBAAgB,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;IACxC,CAAC;CACF"}

package/dist/grammar.d.ts

@@ -0,0 +1,28 @@
+import { type RefIdSpec } from "./spec.ts";
+/**
+ * The structural literals of the scheme, each written exactly once, here. Their sources are
+ * `spec.grammar.expression` (the field separator after the scheme, the version and the type; the
+ * fragment introducer; the line breaks the character classes exclude) and the two pair grammars (the
+ * key/value separator). `assertStructure` checks the patterns really carry them, so a spec that moved
+ * them is refused rather than misread.
+ */
+export declare const FIELD = ":";
+export declare const FRAGMENT_INTRODUCER = "#";
+export declare const PAIR = "=";
+export declare const LINE_BREAKS: readonly ["\r", "\n"];
+/** `ref:` — the scheme name from the spec followed by the field separator. */
+export declare function schemePrefix(spec: RefIdSpec): string;
+/**
+ * Compiles one pattern string for the spec's declared dialect: every `adaptations[dialect].replace`
+ * pair is applied in order — for `ecmascript-2018` the list is empty, so the pattern compiles
+ * unchanged. A port applies its own dialect's list to every pattern in the file the same way.
+ */
+export declare function compilePattern(spec: RefIdSpec, pattern: string): RegExp;
+/** The top-level `ref:` grammar, compiled for the spec's declared dialect. */
+export declare function topLevelGrammar(spec: RefIdSpec): RegExp;
+/** The `key=value` grammar for one qualifier (state) pair. */
+export declare function statePairGrammar(spec: RefIdSpec): RegExp;
+/** The `key=value` grammar for one refinement pair. */
+export declare function fragmentPairGrammar(spec: RefIdSpec): RegExp;
+/** Any other pattern the spec declares (a form, a dispatch entry, a refinement), compiled once and cached. */
+export declare function pattern(spec: RefIdSpec, source: string): RegExp;

package/dist/grammar.js

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Compiles every pattern the spec declares — the top-level grammar, the two pair grammars, and any
+// form, dispatch or refinement pattern — through the dialect's declared adaptations, and holds the
+// only structural literals this package writes.
+import { SpecVersionError } from "./spec.js";
+/**
+ * The structural literals of the scheme, each written exactly once, here. Their sources are
+ * `spec.grammar.expression` (the field separator after the scheme, the version and the type; the
+ * fragment introducer; the line breaks the character classes exclude) and the two pair grammars (the
+ * key/value separator). `assertStructure` checks the patterns really carry them, so a spec that moved
+ * them is refused rather than misread.
+ */
+export const FIELD = ":";
+export const FRAGMENT_INTRODUCER = "#";
+export const PAIR = "=";
+export const LINE_BREAKS = ["\r", "\n"];
+/** `ref:` — the scheme name from the spec followed by the field separator. */
+export function schemePrefix(spec) {
+    return `${spec.scheme}${FIELD}`;
+}
+const checked = new WeakSet();
+function assertStructure(spec) {
+    if (checked.has(spec)) {
+        return;
+    }
+    const expression = spec.grammar.expression;
+    for (const literal of [`^${schemePrefix(spec)}`, FRAGMENT_INTRODUCER, "\\r", "\\n"]) {
+        if (!expression.includes(literal)) {
+            throw new SpecVersionError(`spec.grammar.expression does not carry ${JSON.stringify(literal)}; this package's structural literals do not match`);
+        }
+    }
+    for (const pair of [spec.grammar.state.pair, spec.grammar.fragment.pair]) {
+        if (!pair.includes(`)${PAIR}(`)) {
+            throw new SpecVersionError(`a pair grammar does not separate key and value with ${JSON.stringify(PAIR)}; this package's structural literals do not match`);
+        }
+    }
+    checked.add(spec);
+}
+/**
+ * Compiles one pattern string for the spec's declared dialect: every `adaptations[dialect].replace`
+ * pair is applied in order — for `ecmascript-2018` the list is empty, so the pattern compiles
+ * unchanged. A port applies its own dialect's list to every pattern in the file the same way.
+ */
+export function compilePattern(spec, pattern) {
+    const replacements = spec.grammar.adaptations[spec.grammar.dialect]?.replace ?? [];
+    let adapted = pattern;
+    for (const [from, to] of replacements) {
+        adapted = adapted.split(from).join(to);
+    }
+    return new RegExp(adapted);
+}
+const compiled = new WeakMap();
+function grammars(spec) {
+    let entry = compiled.get(spec);
+    if (!entry) {
+        assertStructure(spec);
+        entry = {
+            top: compilePattern(spec, spec.grammar.expression),
+            statePair: compilePattern(spec, spec.grammar.state.pair),
+            fragmentPair: compilePattern(spec, spec.grammar.fragment.pair),
+            others: new Map(),
+        };
+        compiled.set(spec, entry);
+    }
+    return entry;
+}
+/** The top-level `ref:` grammar, compiled for the spec's declared dialect. */
+export function topLevelGrammar(spec) {
+    return grammars(spec).top;
+}
+/** The `key=value` grammar for one qualifier (state) pair. */
+export function statePairGrammar(spec) {
+    return grammars(spec).statePair;
+}
+/** The `key=value` grammar for one refinement pair. */
+export function fragmentPairGrammar(spec) {
+    return grammars(spec).fragmentPair;
+}
+/** Any other pattern the spec declares (a form, a dispatch entry, a refinement), compiled once and cached. */
+export function pattern(spec, source) {
+    const cache = grammars(spec).others;
+    let regexp = cache.get(source);
+    if (!regexp) {
+        regexp = compilePattern(spec, source);
+        cache.set(source, regexp);
+    }
+    return regexp;
+}
+//# sourceMappingURL=grammar.js.map

package/dist/grammar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grammar.js","sourceRoot":"","sources":["../src/grammar.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { build } from "./build.ts";
+export { digest } from "./digest.ts";
+export { validateEnvelope } from "./envelope.ts";
+export { BuildError, DigestError, RefIdError, SerialiseError } from "./errors.ts";
+export { parse } from "./parse.ts";
+export { serialise } from "./serialise.ts";
+export { canonicalise, loadSpec, loadSpecFrom, SpecIntegrityError, SpecVersionError, type RefIdSpec } from "./spec.ts";
+export type { BuildParts, EnvelopeResult, NestedQualifierValue, Pair, ParsedFragment, ParseResult, ParseStatus } from "./types.ts";

package/dist/index.js

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: Apache-2.0
+export { build } from "./build.js";
+export { digest } from "./digest.js";
+export { validateEnvelope } from "./envelope.js";
+export { BuildError, DigestError, RefIdError, SerialiseError } from "./errors.js";
+export { parse } from "./parse.js";
+export { serialise } from "./serialise.js";
+export { canonicalise, loadSpec, loadSpecFrom, SpecIntegrityError, SpecVersionError } from "./spec.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACjF,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAkB,MAAM,WAAW,CAAA"}

package/dist/parse.d.ts

@@ -0,0 +1,3 @@
+import type { ParseResult } from "./types.ts";
+/** Parses a `ref:` identifier string against the loaded spec. Never throws for an identifier problem. */
+export declare function parse(input: string): ParseResult;