@entelekheia/ref-id 0.2.0 → 0.3.0

package/dist/canonical.d.ts

@@ -0,0 +1,17 @@
+import type { ParseResult } from "./types.ts";
+/**
+ * The canonical form of an identifier: the same identifier with its qualifiers sorted by key.
+ *
+ * Sorting is by UTF-16 code unit, the order this specification already uses for its own file, and it is
+ * the cheapest canonicalisation rather than the point. What is load-bearing is that one deterministic
+ * order exists, so any two implementations reach the same answer about whether two identifiers are one.
+ *
+ * Every other part is left exactly as parsed. **Refinements are not sorted** — they sit on the fragment
+ * side and are positional, `lines=1,20` being a range, so reordering them would change what is named.
+ *
+ * A malformed identifier has no canonical form and is refused, for the reason `serialise` gives: there is
+ * no faithful way to write back a string whose failing part was never decomposed.
+ */
+export declare function canonical(identifier: string | ParseResult): string;
+/** Whether two identifiers name one thing. Order of qualifiers does not distinguish; everything else does. */
+export declare function sameIdentifier(a: string | ParseResult, b: string | ParseResult): boolean;

package/dist/canonical.js

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// The form two identifiers are compared in. `;a=1;b=2` and `;b=2;a=1` name one thing, so identity is
+// judged on this rather than on the bytes a producer happened to write.
+import { parse } from "./parse.js";
+import { serialise } from "./serialise.js";
+import { loadSpec, status } from "./spec.js";
+/**
+ * The canonical form of an identifier: the same identifier with its qualifiers sorted by key.
+ *
+ * Sorting is by UTF-16 code unit, the order this specification already uses for its own file, and it is
+ * the cheapest canonicalisation rather than the point. What is load-bearing is that one deterministic
+ * order exists, so any two implementations reach the same answer about whether two identifiers are one.
+ *
+ * Every other part is left exactly as parsed. **Refinements are not sorted** — they sit on the fragment
+ * side and are positional, `lines=1,20` being a range, so reordering them would change what is named.
+ *
+ * A malformed identifier has no canonical form and is refused, for the reason `serialise` gives: there is
+ * no faithful way to write back a string whose failing part was never decomposed.
+ */
+export function canonical(identifier) {
+    const spec = loadSpec();
+    const parsed = typeof identifier === "string" ? parse(identifier) : identifier;
+    if (parsed.status === status(spec, "malformed"))
+        return serialise(parsed); // throws, naming the failing part
+    const sorted = [...parsed.qualifiers].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return serialise({ ...parsed, qualifiers: sorted });
+}
+/** Whether two identifiers name one thing. Order of qualifiers does not distinguish; everything else does. */
+export function sameIdentifier(a, b) {
+    return canonical(a) === canonical(b);
+}
+//# sourceMappingURL=canonical.js.map

package/dist/canonical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.js","sourceRoot":"","sources":["../src/canonical.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,EAAE;AACF,qGAAqG;AACrG,wEAAwE;AAExE,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAG5C;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,SAAS,CAAC,UAAgC;IACxD,MAAM,IAAI,GAAG,QAAQ,EAAE,CAAA;IACvB,MAAM,MAAM,GAAG,OAAO,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAA;IAC9E,IAAI,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,IAAI,EAAE,WAAW,CAAC;QAAE,OAAO,SAAS,CAAC,MAAM,CAAC,CAAA,CAAC,kCAAkC;IAC5G,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IACtF,OAAO,SAAS,CAAC,EAAE,GAAG,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAA;AACrD,CAAC;AAED,8GAA8G;AAC9G,MAAM,UAAU,cAAc,CAAC,CAAuB,EAAE,CAAuB;IAC7E,OAAO,SAAS,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,CAAA;AACtC,CAAC"}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { build } from "./build.ts";
+export { canonical, sameIdentifier } from "./canonical.ts";
 export { digest } from "./digest.ts";
 export { validateEnvelope } from "./envelope.ts";
 export { BuildError, DigestError, RefIdError, SerialiseError } from "./errors.ts";

package/dist/index.js

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 export { build } from "./build.js";
+export { canonical, sameIdentifier } from "./canonical.js";
 export { digest } from "./digest.js";
 export { validateEnvelope } from "./envelope.js";
 export { BuildError, DigestError, RefIdError, SerialiseError } from "./errors.js";

package/dist/index.js.map

@@ -1 +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"}
+{"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,SAAS,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC1D,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entelekheia/ref-id",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The ref: identifier scheme — a specification published as data with conformance vectors, and the package that consumes it.",
   "type": "module",
   "license": "Apache-2.0",

package/spec/ref-id.json

@@ -1,5 +1,5 @@
 {
-  "specVersion": "1.2.0",
+  "specVersion": "1.3.0",
   "scheme": "ref",
   "grammar": {
     "dialect": "ecmascript-2018",
@@ -301,6 +301,14 @@
     "dedupe": false,
     "output": "sha256:<64 lowercase hex>"
   },
+  "identifierEquivalence": {
+    "qualifierOrder": "insignificant",
+    "refinementOrder": "significant",
+    "canonicalForm": "re-serialise the parsed identifier with its qualifiers sorted by key in UTF-16 code unit order; every other part verbatim, refinements included",
+    "comparison": "two identifiers name one thing when their canonical forms are equal byte for byte",
+    "reserialisation": "SHOULD preserve the order written; MUST NOT be relied on to tell two identifiers apart",
+    "note": "distinct from `canonicalisation`, which is the form of THIS FILE for its own digest"
+  },
   "canonicalisation": {
     "form": "json-sorted-keys-compact",
     "rules": [
@@ -1395,6 +1403,63 @@
         }
       }
     ],
+    "canonical": [
+      {
+        "name": "one qualifier is already canonical",
+        "input": "ref:eita:structured-output@1/validity;when=2026-08-02T18:31:31.870Z",
+        "expect": "ref:eita:structured-output@1/validity;when=2026-08-02T18:31:31.870Z"
+      },
+      {
+        "name": "two qualifiers written out of order sort by key",
+        "input": "ref:eita:structured-output@1/validity;when=2026-08-02T18:31:31.870Z;over=unknown",
+        "expect": "ref:eita:structured-output@1/validity;over=unknown;when=2026-08-02T18:31:31.870Z"
+      },
+      {
+        "name": "the same qualifiers in the other order reach the same form",
+        "input": "ref:eita:structured-output@1/validity;over=unknown;when=2026-08-02T18:31:31.870Z",
+        "expect": "ref:eita:structured-output@1/validity;over=unknown;when=2026-08-02T18:31:31.870Z"
+      },
+      {
+        "name": "an unknown key sorts beside a declared one, carried through",
+        "input": "ref:eita:citation-fidelity@1/exact;when=2026-08-14T23:38:26.089Z;context-tokens=8000;over=unknown",
+        "expect": "ref:eita:citation-fidelity@1/exact;context-tokens=8000;over=unknown;when=2026-08-14T23:38:26.089Z"
+      },
+      {
+        "name": "sorting is by UTF-16 code unit, so a hyphen precedes a letter",
+        "input": "ref:eita:t@1/o;alphaone=1;alpha-two=2;alpha=3",
+        "expect": "ref:eita:t@1/o;alpha=3;alpha-two=2;alphaone=1"
+      },
+      {
+        "name": "a nested value is not decoded by canonicalisation",
+        "input": "ref:eita:t@1/o;when=2026-08-02T18:31:31.870Z;over=ref:ai-model:Qwen3-4B-Instruct-2507-4bit",
+        "expect": "ref:eita:t@1/o;over=ref:ai-model:Qwen3-4B-Instruct-2507-4bit;when=2026-08-02T18:31:31.870Z"
+      },
+      {
+        "name": "no qualifiers, nothing to sort",
+        "input": "ref:pkg:npm/@acme/scanner-core@0.1.0#Observation",
+        "expect": "ref:pkg:npm/@acme/scanner-core@0.1.0#Observation"
+      },
+      {
+        "name": "an explicit version survives canonicalisation verbatim",
+        "input": "ref:1:pkg:npm/x@1.0.0;state=none;by=sha256:0000000000000000000000000000000000000000000000000000000000000000",
+        "expect": "ref:1:pkg:npm/x@1.0.0;by=sha256:0000000000000000000000000000000000000000000000000000000000000000;state=none"
+      },
+      {
+        "name": "refinements are positional and keep the order they were written",
+        "input": "ref:folder:acme-governance;state=none#AGENTS.md;lines=1,20;item=3",
+        "expect": "ref:folder:acme-governance;state=none#AGENTS.md;lines=1,20;item=3"
+      },
+      {
+        "name": "qualifiers sort while the fragment beside them is untouched",
+        "input": "ref:folder:acme-governance;when=2026-08-02T18:31:31.870Z;state=none#AGENTS.md;lines=1,20",
+        "expect": "ref:folder:acme-governance;state=none;when=2026-08-02T18:31:31.870Z#AGENTS.md;lines=1,20"
+      },
+      {
+        "name": "a malformed identifier has no canonical form",
+        "input": "ref:eita:t@1/o;state=none;state=none",
+        "expect": { "error": "state" }
+      }
+    ],
     "roundtrip": [
       "ref:pkg:npm/@acme/scanner-core@0.1.0#Observation",
       "ref:1:pkg:npm/x@1.0.0",

package/spec/ref-id.json.sha256

@@ -1 +1 @@
-ee34597292d313a7c424d09c050d2e1bf6cc9507b9b2627f63c684131c6fd3c6
+d10d07be0fbf02acef1717de1945ec4a2e2ceef954f80017051127a1c0fb3b0a