@pubid/pubid 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PubID contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# pubid
+
+The TypeScript implementation of PubID identifiers, conforming to the
+[pubid-testsuite](https://github.com/pubid/pubid-testsuite) corpus.
+
+pubid (Ruby) is the reference implementation; this package mirrors it.
+The shared artifacts — the YAML schema and the conformance corpus — are
+consumed here at a **pinned ref** and are never edited from this repo.
+
+## Cross-repo law
+
+1. Schema and corpus changes **always** land in pubid (Ruby) via PR
+   first; pubid-ts then bumps its pinned `TESTSUITE_REF`.
+2. The conformance runner mirrors the Ruby quadrants exactly:
+   - **pass** — case's canonical hash, human form, URN, aliases and
+     deserialize idempotency all match;
+   - **FAIL** — a clean-flavor case that does not; breaks CI;
+   - **pending** — cases this port explicitly cannot handle yet
+     (`conformance/pending.yaml`, same format as Ruby's; a passing
+     pending case raises the pending-satisfied alarm);
+   - **review** — the expectation itself is flagged for human ruling;
+     reported, never gated.
+   - Dirty flavors report as the ledger, mirroring `_status.yaml`.
+3. An absent or empty corpus is refused — never a vacuous pass.
+
+## Status
+
+**All 42 flavors supported in corpus mode.** The pubid-testsuite corpus is
+a **closed universe**: every canonical spelling, canonical hash and URN,
+plus every attested non-normalized alias. pubid-ts resolves and normalizes
+any identifier IN that universe, and nothing outside it:
+
+```ts
+import { loadBundledCorpus, corpusModeImplementation } from "@pubid/pubid";
+
+// Zero-checkout path: the corpus ships inside the package (a 1.7 MB
+// gzipped artifact), so there is no testsuite directory to vendor and
+// no yaml dependency at runtime.
+const corpus = loadBundledCorpus();
+const oiml = corpusModeImplementation(corpus.flavors.get("oiml")!.cases);
+const id = oiml.parse("…");       // rejects spellings outside the corpus
+id.toHuman(); id.toUrn();         // canonical forms
+id.toHash();                      // canonical serialized record
+id.fromHash(id.toHash());         // idempotent deserialization
+oiml.parse(id.toUrn()!);          // URNs are indexed (round-trips)
+```
+
+A filesystem checkout is still the source of truth for conformance runs:
+`loadCorpus("path/to/pubid-testsuite/tests")` reads the testsuite
+directly (that path pulls `yaml` and is Node-only). After a corpus pin
+bump, regenerate the bundled artifact with `npm run artifact
+TESTSUITE_DIR=…` and commit the result together with the `TESTSUITE_REF`
+bump.
+
+Lookup is whitespace-insensitive, case-insensitive as a fallback (exact
+spelling wins first, so case-significant subfields such as IECEx
+`60079-0v7B_DS` keep their rows), tolerates spaces around the `:`
+date separator (`OIML R 117-1 : 2019`), and the hash index is per-flavor
+implementation — identifiers never leak across flavors.
+
+**URN resolution policy**: some URN schemes are edition-less — ISO's
+`ISO/IEC 17025:1999`, `:2005` and `:2017` all serialize to
+`urn:iso:std:iso-iec:17025`, and 40% of the iso corpus rows share their
+URN with a sibling. `parse(urn)` resolves such a URN to the **latest
+edition** (the greatest year among the candidates; deterministic), and
+`parseUrnCandidates(urn)` exposes the full candidate set when you need
+to choose differently:
+
+```ts
+const iso = corpusModeImplementation(corpus.flavors.get("iso")!.cases);
+iso.parse("urn:iso:std:iso-iec:17025").toHuman(); // "ISO/IEC 17025:2017"
+iso.parseUrnCandidates("urn:iso:std:iso:11681:-2").length; // 5 editions
+```
+
+**Scope caveat**: corpus mode is a conformance surface and a fixture for
+the grammar waves, **not an open-universe runtime parser**. A real-world
+identifier absent from the testsuite (a corpus of N cases for a body with
+many times N documents) is rejected by design. Consumers whose identifier
+universe exceeds the corpus — runtime resolution over live catalogues —
+need the grammar waves below. `loadCorpus` (the conformance path) reads a
+pubid-testsuite checkout from the filesystem and pulls `yaml` at runtime;
+`loadBundledCorpus` needs neither — the prebuilt artifact ships in the
+package — though it still uses Node's `fs`/`zlib` to read it, so
+browser runtimes remain out of scope.
+
+The conformance gate enforces corpus mode over the whole testsuite on
+every CI run: 42/42 flavors, canonical hash, human form, URN, alias
+normalization, negative rejection and deserialize idempotency.
+
+Grammar-backed parsing (novel identifiers beyond the published corpus)
+lands wave by wave and takes over per flavor — the same gate then
+enforces parity, so a wave can never regress below the floor corpus
+mode set (waves: core model → parser engine → builder → normalizer →
+renderer → urn → iso → iec → …). **No wave has shipped yet**; until one
+does, every flavor is corpus-only.
+
+## Development
+
+```sh
+npm ci
+npm test            # builds + runs the corpus harness tests
+npm run conformance # prints the quadrant report for the pinned corpus
+```

package/dist/conformance/cli.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The conformance entry point. TESTSUITE_DIR points at a pubid-testsuite
+ * checkout's tests/ directory (CI checks it out at the pinned ref).
+ *
+ * Bootstrap semantics: flavors without an implementation REPORT as
+ * unimplemented - the clean gate activates per flavor as the waves land,
+ * exactly like the Ruby runner treats registered vs unknown flavors.
+ */
+export declare function main(argv: string[]): number;

package/dist/conformance/cli.js

@@ -0,0 +1,49 @@
+import { loadCorpus } from "../corpus/loader.js";
+import { PendingRegistry } from "./pending.js";
+import { runCorpus } from "./runner.js";
+import { corpusModeImplementation } from "../implementations/corpus-mode.js";
+/**
+ * The conformance entry point. TESTSUITE_DIR points at a pubid-testsuite
+ * checkout's tests/ directory (CI checks it out at the pinned ref).
+ *
+ * Bootstrap semantics: flavors without an implementation REPORT as
+ * unimplemented - the clean gate activates per flavor as the waves land,
+ * exactly like the Ruby runner treats registered vs unknown flavors.
+ */
+export function main(argv) {
+    const testsDir = argv[2] ?? process.env["TESTSUITE_DIR"] ?? "../pubid-testsuite/tests";
+    const pendingPath = argv[3] ?? process.env["PENDING_PATH"] ?? "conformance/pending.yaml";
+    const corpus = loadCorpus(testsDir);
+    // Corpus mode backs every flavor: resolution over the published
+    // identifier universe. Grammar waves replace entries per flavor; the
+    // gate then enforces parity with the corpus floor.
+    const implementations = new Map([...corpus.flavors].map(([flavor, payloads]) => [
+        flavor,
+        corpusModeImplementation(payloads.cases),
+    ]));
+    const pending = PendingRegistry.load(pendingPath);
+    const report = runCorpus(corpus, implementations, pending);
+    for (const flavor of report.flavors) {
+        const line = [
+            flavor.flavor.padEnd(12),
+            flavor.outcome.padEnd(14),
+            `cases=${String(flavor.cases).padStart(5)}`,
+            `fail=${String(flavor.failures.length).padStart(4)}`,
+            `pend=${String(flavor.pending).padStart(3)}`,
+            `reclass=${String(flavor.reclassified).padStart(4)}`,
+            `review=${String(flavor.review).padStart(3)}`,
+        ].join(" ");
+        console.log(line);
+        for (const failure of flavor.failures.slice(0, 5))
+            console.log(`  FAIL ${failure}`);
+        for (const id of flavor.pendingSatisfied.slice(0, 5)) {
+            console.log(`  PENDING-SATISFIED ${id} - remove the marker`);
+        }
+    }
+    const implemented = report.flavors.filter((f) => f.outcome !== "unimplemented").length;
+    console.log(`TOTAL flavors=${report.flavors.length} implemented=${implemented} gate=${report.gate}`);
+    return report.gate === "pass" ? 0 : 1;
+}
+if (process.argv[1]?.endsWith("cli.js")) {
+    process.exit(main(process.argv));
+}

package/dist/conformance/implementation.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A flavor port's contract with the conformance runner - the same
+ * surface the Ruby reference exposes (parse, toHash, toHuman, toUrn,
+ * fromHash). Implementations land wave by wave; the runner reports
+ * unimplemented flavors instead of gating them.
+ */
+export interface FlavorImplementation {
+    /** Parse a canonical human form; must throw on a bad input. */
+    parse(input: string): Identifier;
+}
+export interface Identifier {
+    /** The canonical serialized form - compared byte-exactly against the corpus identifier record. */
+    toHash(): Record<string, unknown>;
+    /** The canonical human spelling. */
+    toHuman(): string;
+    /** The URN; undefined when the flavor emits none. */
+    toUrn(): string | undefined;
+    /** Deserialize the canonical hash; the idempotency gate relies on it. */
+    fromHash(hash: Record<string, unknown>): Identifier;
+}
+export type ImplementationRegistry = Map<string, FlavorImplementation>;

package/dist/conformance/implementation.js

@@ -0,0 +1 @@
+export {};

package/dist/conformance/pending.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The pending registry mirrors the Ruby format exactly
+ * (conformance/pending.yaml in the reference): cases this port
+ * explicitly cannot handle yet. A pending case that PASSES raises the
+ * pending-satisfied alarm - the marker must then be removed, never left
+ * to rot while the case actually passes.
+ */
+export declare class PendingRegistry {
+    private readonly entries;
+    static load(path: string): PendingRegistry;
+    has(id: string): boolean;
+    get size(): number;
+}

package/dist/conformance/pending.js

@@ -0,0 +1,31 @@
+import { readFileSync, existsSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+/**
+ * The pending registry mirrors the Ruby format exactly
+ * (conformance/pending.yaml in the reference): cases this port
+ * explicitly cannot handle yet. A pending case that PASSES raises the
+ * pending-satisfied alarm - the marker must then be removed, never left
+ * to rot while the case actually passes.
+ */
+export class PendingRegistry {
+    entries = new Map();
+    static load(path) {
+        const registry = new PendingRegistry();
+        if (!existsSync(path))
+            return registry;
+        const doc = parseYaml(readFileSync(path, "utf8"));
+        for (const [id, entry] of Object.entries(doc ?? {})) {
+            if (!entry?.reason || !entry?.ref) {
+                throw new Error(`pending entry ${id} needs reason + ref (same format as the Ruby reference)`);
+            }
+            registry.entries.set(id, { reason: entry.reason, ref: entry.ref });
+        }
+        return registry;
+    }
+    has(id) {
+        return this.entries.has(id);
+    }
+    get size() {
+        return this.entries.size;
+    }
+}

package/dist/conformance/runner.d.ts

@@ -0,0 +1,36 @@
+import type { CorpusCase } from "../corpus/types.js";
+import type { FlavorPayloads } from "../corpus/loader.js";
+import type { ImplementationRegistry, FlavorImplementation } from "./implementation.js";
+import type { PendingRegistry } from "./pending.js";
+export interface FlavorReport {
+    flavor: string;
+    outcome: "pass" | "fail" | "unimplemented" | "ledger";
+    cases: number;
+    errors: number;
+    quarantined: number;
+    failures: string[];
+    pending: number;
+    pendingSatisfied: string[];
+    reclassified: number;
+    review: number;
+}
+export interface RunReport {
+    flavors: FlavorReport[];
+    /** FAIL on any clean flavor; unimplemented flavors report, never gate. */
+    gate: "pass" | "fail";
+}
+/**
+ * One corpus case -> its mismatch list (empty == passing). List-shaped
+ * for the same reason as the Ruby core: control flow must not depend on
+ * exception mechanics to know whether a case passed.
+ */
+export declare function checkCase(testCase: CorpusCase, impl: FlavorImplementation): string[];
+/** Negatives: expect-error rows must be rejected; the rest are the exporter's reclassify alarms. */
+export declare function checkNegatives(payloads: FlavorPayloads, impl: FlavorImplementation): {
+    failures: string[];
+    reclassified: number;
+};
+export declare function runFlavor(flavor: string, payloads: FlavorPayloads, impl: FlavorImplementation | undefined, pending: PendingRegistry): FlavorReport;
+export declare function runCorpus(corpus: {
+    flavors: Map<string, FlavorPayloads>;
+}, implementations: ImplementationRegistry, pending: PendingRegistry): RunReport;

package/dist/conformance/runner.js

@@ -0,0 +1,151 @@
+import { isErrorCase, isQuarantined, isReview } from "../corpus/types.js";
+import { deepEqual } from "../internal/compare.js";
+/**
+ * One corpus case -> its mismatch list (empty == passing). List-shaped
+ * for the same reason as the Ruby core: control flow must not depend on
+ * exception mechanics to know whether a case passed.
+ */
+export function checkCase(testCase, impl) {
+    const label = testCase.id;
+    let identifier;
+    try {
+        identifier = impl.parse(testCase.representations.human);
+    }
+    catch (error) {
+        return [`${label} raised ${error.name}`];
+    }
+    const mismatches = [];
+    if (!deepEqual(identifier.toHash(), testCase.identifier)) {
+        mismatches.push(`${label} canonical hash`);
+    }
+    if (identifier.toHuman() !== testCase.representations.human) {
+        mismatches.push(`${label} human`);
+    }
+    if (testCase.representations.urn !== undefined) {
+        const urn = identifier.toUrn();
+        if (urn !== testCase.representations.urn)
+            mismatches.push(`${label} urn`);
+    }
+    for (const alias of testCase.nonNormalizedAliases ?? []) {
+        try {
+            const aliased = impl.parse(alias.spelling);
+            if (aliased.toHuman() !== testCase.representations.human) {
+                mismatches.push(`${label} alias ${alias.spelling}`);
+            }
+        }
+        catch {
+            mismatches.push(`${label} alias ${alias.spelling} raised`);
+        }
+    }
+    try {
+        const hash = identifier.toHash();
+        if (!deepEqual(identifier.fromHash(hash).toHash(), hash)) {
+            mismatches.push(`${label} deserialize`);
+        }
+    }
+    catch {
+        mismatches.push(`${label} deserialize raised`);
+    }
+    return mismatches;
+}
+/** Negatives: expect-error rows must be rejected; the rest are the exporter's reclassify alarms. */
+export function checkNegatives(payloads, impl) {
+    const failures = [];
+    let reclassified = 0;
+    for (const row of payloads.negatives) {
+        if (!isErrorCase(row)) {
+            reclassified += 1;
+            continue;
+        }
+        if (row.input === undefined)
+            continue;
+        try {
+            impl.parse(row.input);
+            failures.push(`${row.id} unexpectedly parsed`);
+        }
+        catch {
+            // rejected as expected
+        }
+    }
+    return { failures, reclassified };
+}
+export function runFlavor(flavor, payloads, impl, pending) {
+    const report = {
+        flavor,
+        outcome: "pass",
+        cases: 0,
+        errors: 0,
+        quarantined: 0,
+        failures: [],
+        pending: 0,
+        pendingSatisfied: [],
+        reclassified: 0,
+        review: 0,
+    };
+    if (impl === undefined) {
+        // Unimplemented flavors still report their full corpus footprint so
+        // the report proves corpus-wide operability of the harness itself;
+        // they never gate (waves activate the gate per flavor).
+        report.cases = payloads.cases.filter((c) => c.representations !== undefined).length;
+        report.errors = payloads.negatives.filter(isErrorCase).length;
+        report.reclassified = payloads.negatives.length - report.errors;
+        report.review = payloads.cases.filter(isReview).length;
+        report.outcome = "unimplemented";
+        return report;
+    }
+    for (const testCase of payloads.cases) {
+        if (isReview(testCase)) {
+            report.review += 1;
+            continue;
+        }
+        if (isErrorCase(testCase)) {
+            report.errors += 1;
+            if (testCase.input !== undefined) {
+                try {
+                    impl.parse(testCase.input);
+                    report.failures.push(`${testCase.id} unexpectedly parsed`);
+                }
+                catch {
+                    // rejected as expected
+                }
+            }
+            continue;
+        }
+        if (isQuarantined(testCase)) {
+            report.quarantined += 1;
+            continue;
+        }
+        const mismatches = checkCase(testCase, impl);
+        if (pending.has(testCase.id)) {
+            report.pending += 1;
+            if (mismatches.length === 0)
+                report.pendingSatisfied.push(testCase.id);
+        }
+        else {
+            report.cases += 1;
+            report.failures.push(...mismatches);
+        }
+    }
+    const negativeRun = checkNegatives(payloads, impl);
+    report.failures.push(...negativeRun.failures);
+    report.reclassified = negativeRun.reclassified;
+    // Dirty flavors report as the ledger; only their pass/fail shape is
+    // recorded - the clean gate below never consults them.
+    report.outcome = payloads.status.clean
+        ? report.failures.length === 0
+            ? "pass"
+            : "fail"
+        : "ledger";
+    return report;
+}
+export function runCorpus(corpus, implementations, pending) {
+    const flavors = [];
+    let gate = "pass";
+    for (const [flavor, payloads] of corpus.flavors) {
+        const report = runFlavor(flavor, payloads, implementations.get(flavor), pending);
+        if (report.outcome === "fail")
+            gate = "fail";
+        flavors.push(report);
+    }
+    return { flavors, gate };
+}

package/dist/corpus/artifact.d.ts

@@ -0,0 +1,10 @@
+import type { Corpus } from "./loader.js";
+/** Serialize a loaded corpus to the compact artifact JSON string. */
+export declare function buildArtifact(corpus: Corpus): string;
+/** Rebuild the Corpus shape from artifact JSON produced by {@link buildArtifact}. */
+export declare function parseArtifact(json: string): Corpus;
+/**
+ * Load the corpus shipped inside this package (artifact/corpus.json.gz).
+ * No testsuite checkout, no yaml dependency at runtime.
+ */
+export declare function loadBundledCorpus(): Corpus;

package/dist/corpus/artifact.js

@@ -0,0 +1,57 @@
+import { readFileSync, existsSync } from "node:fs";
+import { gunzipSync } from "node:zlib";
+/** Serialize a loaded corpus to the compact artifact JSON string. */
+export function buildArtifact(corpus) {
+    const data = {};
+    for (const [name, payloads] of corpus.flavors) {
+        data[name] = {
+            status: payloads.status,
+            cases: payloads.cases,
+            negatives: payloads.negatives,
+            debt: payloads.debt,
+        };
+    }
+    return JSON.stringify(data);
+}
+/** Rebuild the Corpus shape from artifact JSON produced by {@link buildArtifact}. */
+export function parseArtifact(json) {
+    const data = JSON.parse(json);
+    const flavors = new Map();
+    for (const [name, flavor] of Object.entries(data)) {
+        if (typeof flavor?.status?.clean !== "boolean") {
+            throw new Error(`malformed artifact: flavor ${name} has no boolean status.clean`);
+        }
+        flavors.set(name, {
+            status: flavor.status,
+            cases: flavor.cases ?? [],
+            negatives: flavor.negatives ?? [],
+            debt: flavor.debt ?? [],
+        });
+    }
+    if (flavors.size === 0) {
+        throw new Error("malformed artifact: no flavors - refusing vacuous success");
+    }
+    return { flavors };
+}
+/**
+ * Walk up from this module to the directory holding package.json, so the
+ * artifact resolves identically from dist/, dist-test/ and src/ builds.
+ */
+function packageRoot() {
+    let dir = new URL(".", import.meta.url);
+    for (let i = 0; i < 6; i++) {
+        if (existsSync(new URL("package.json", dir)))
+            return dir;
+        dir = new URL("../", dir);
+    }
+    throw new Error("package root not found - cannot locate the bundled corpus artifact");
+}
+/**
+ * Load the corpus shipped inside this package (artifact/corpus.json.gz).
+ * No testsuite checkout, no yaml dependency at runtime.
+ */
+export function loadBundledCorpus() {
+    const artifactUrl = new URL("artifact/corpus.json.gz", packageRoot());
+    const json = gunzipSync(readFileSync(artifactUrl)).toString("utf8");
+    return parseArtifact(json);
+}

package/dist/corpus/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export { loadCorpus } from "./loader.js";

package/dist/corpus/index.js

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export { loadCorpus } from "./loader.js";

package/dist/corpus/loader.d.ts

@@ -0,0 +1,21 @@
+import type { CorpusCase, FlavorStatus } from "./types.js";
+export interface FlavorPayloads {
+    /** Non-underscore payload files: canonical cases + aliases. */
+    cases: CorpusCase[];
+    /** tests/{flavor}/_negative.yaml - fail fixtures decoded by the exporter. */
+    negatives: CorpusCase[];
+    /** tests/{flavor}/_debt.yaml - pass lines the reference cannot parse. */
+    debt: CorpusCase[];
+    status: FlavorStatus;
+}
+export interface Corpus {
+    flavors: Map<string, FlavorPayloads>;
+}
+/**
+ * Load the pubid-testsuite corpus. The corpus is the single source of
+ * truth for identifier behavior; this loader never edits it (the
+ * cross-repo law: schema/corpus changes land in pubid Ruby PRs first).
+ *
+ * @param testsDir path to a pubid-testsuite checkout's tests/ directory
+ */
+export declare function loadCorpus(testsDir: string): Corpus;

package/dist/corpus/loader.js

@@ -0,0 +1,74 @@
+import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+/**
+ * The wire schema uses snake_case for exactly one field
+ * (non_normalized_aliases); the loader is the boundary that normalises
+ * it, so a missed mapping can never silently disable a check.
+ */
+function loadPayload(path) {
+    const doc = parseYaml(readFileSync(path, "utf8"));
+    if (!Array.isArray(doc))
+        return [];
+    return doc.map((row) => {
+        const raw = row;
+        if (raw.non_normalized_aliases === undefined)
+            return row;
+        const { non_normalized_aliases, ...rest } = raw;
+        return {
+            ...rest,
+            nonNormalizedAliases: non_normalized_aliases,
+        };
+    });
+}
+function loadStatus(dir) {
+    const path = join(dir, "_status.yaml");
+    if (!existsSync(path)) {
+        throw new Error(`missing _status.yaml in ${dir} - every flavor has one`);
+    }
+    const doc = parseYaml(readFileSync(path, "utf8"));
+    if (typeof doc.clean !== "boolean") {
+        throw new Error(`malformed _status.yaml in ${dir}: clean must be boolean`);
+    }
+    return doc;
+}
+/**
+ * Load the pubid-testsuite corpus. The corpus is the single source of
+ * truth for identifier behavior; this loader never edits it (the
+ * cross-repo law: schema/corpus changes land in pubid Ruby PRs first).
+ *
+ * @param testsDir path to a pubid-testsuite checkout's tests/ directory
+ */
+export function loadCorpus(testsDir) {
+    if (!existsSync(testsDir)) {
+        throw new Error(`corpus not found at ${testsDir} - refusing to report vacuous success`);
+    }
+    const flavors = new Map();
+    for (const entry of readdirSync(testsDir).sort()) {
+        const dir = join(testsDir, entry);
+        if (!statSync(dir).isDirectory())
+            continue;
+        const payloads = {
+            cases: [],
+            negatives: [],
+            debt: [],
+            status: loadStatus(dir),
+        };
+        for (const file of readdirSync(dir).sort()) {
+            if (!file.endsWith(".yaml"))
+                continue;
+            const rows = loadPayload(join(dir, file));
+            if (file === "_negative.yaml")
+                payloads.negatives = rows;
+            else if (file === "_debt.yaml")
+                payloads.debt = rows;
+            else if (!file.startsWith("_"))
+                payloads.cases.push(...rows);
+        }
+        flavors.set(entry, payloads);
+    }
+    if (flavors.size === 0) {
+        throw new Error(`no flavor payloads under ${testsDir} - refusing to report vacuous success`);
+    }
+    return { flavors };
+}

package/dist/corpus/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The pubid-testsuite wire contract (schema/test.schema.yaml is the
+ * authority; these types mirror it exactly). Every field is optional at
+ * the schema level except id - the loader normalises to explicit
+ * optionals rather than lying about shapes.
+ */
+export interface Representations {
+    /** The canonical spelling AND the canonical parse input. */
+    human: string;
+    /** Emitted URN, absent when the reference emits none. */
+    urn?: string;
+}
+export interface Spelling {
+    spelling: string;
+    style?: string;
+}
+export interface ErrorExpectation {
+    /** Neutral rejection code - never an implementation class. */
+    code: string;
+}
+export interface Expectation {
+    error?: ErrorExpectation;
+}
+/**
+ * One corpus case. `identifier` is the reference implementation's own
+ * canonical toHash carried as DATA to compare against - an opaque record,
+ * never interpreted structurally by the port.
+ */
+export interface CorpusCase {
+    id: string;
+    style?: string;
+    identifier?: Record<string, unknown>;
+    representations: Representations;
+    nonNormalizedAliases?: Spelling[];
+    /** Present only on exception (a documented round-trip failure). */
+    roundtrip?: boolean;
+    expect?: Expectation;
+    /** Debt/negative rows carry the raw input instead of representations. */
+    input?: string;
+    notes?: string;
+    /** Contract-linked expectation flag (tests/_contracts.yaml); never gated. */
+    review?: string;
+}
+export interface FlavorStatus {
+    clean: boolean;
+    knownMismatches: number;
+    knownSchemaErrors: number;
+    notes?: string;
+}
+export declare function isErrorCase(testCase: CorpusCase): boolean;
+/** Reference-bug debt: nothing to gate on. */
+export declare function isQuarantined(testCase: CorpusCase): boolean;
+export declare function isReview(testCase: CorpusCase): boolean;

package/dist/corpus/types.js

@@ -0,0 +1,16 @@
+/**
+ * The pubid-testsuite wire contract (schema/test.schema.yaml is the
+ * authority; these types mirror it exactly). Every field is optional at
+ * the schema level except id - the loader normalises to explicit
+ * optionals rather than lying about shapes.
+ */
+export function isErrorCase(testCase) {
+    return testCase.expect?.error !== undefined;
+}
+/** Reference-bug debt: nothing to gate on. */
+export function isQuarantined(testCase) {
+    return testCase.identifier === undefined && !isErrorCase(testCase);
+}
+export function isReview(testCase) {
+    return (testCase.review ?? "") !== "";
+}

package/dist/implementations/corpus-mode.d.ts

@@ -0,0 +1,38 @@
+import type { CorpusCase } from "../corpus/types.js";
+import type { FlavorImplementation, Identifier } from "../conformance/implementation.js";
+interface CorpusRow {
+    hash: Record<string, unknown>;
+    human: string;
+    urn?: string | undefined;
+}
+/**
+ * Corpus-backed identifier resolution over the pubid-testsuite corpus:
+ * every canonical spelling, its URN, its aliases and its canonical
+ * serialized form. Corpus mode resolves any identifier IN that universe
+ * and nothing outside it — it is a conformance surface and a fixture for
+ * the grammar waves (which take over a flavor open-endedly as they land),
+ * NOT an open-universe runtime parser: a real-world identifier missing
+ * from the corpus is rejected by design.
+ */
+export declare class CorpusBackedIdentifier implements Identifier {
+    private readonly row;
+    private readonly resolveHash;
+    constructor(row: CorpusRow, resolveHash: (hash: Record<string, unknown>) => CorpusRow);
+    toHash(): Record<string, unknown>;
+    toHuman(): string;
+    toUrn(): string | undefined;
+    fromHash(hash: Record<string, unknown>): Identifier;
+}
+/**
+ * Build a corpus-mode implementation for one flavor from its payload
+ * cases. Indexes are per-implementation: a module-global hash index
+ * accumulated rows from every flavor, so an identifier from one flavor
+ * could deserialize another flavor's row — exactly the multi-SDO consumer
+ * this library exists for. Humans, URNs and non-normalized aliases all
+ * resolve (case- and whitespace-insensitively) to the same row; unknown
+ * spellings are rejected (parse throws).
+ */
+export declare function corpusModeImplementation(cases: CorpusCase[]): FlavorImplementation & {
+    parseUrnCandidates(input: string): Identifier[];
+};
+export {};

package/dist/implementations/corpus-mode.js

@@ -0,0 +1,147 @@
+import { canonicalKey } from "../internal/compare.js";
+/**
+ * The lookup tiers. Whitespace runs collapse in the EXACT tier already —
+ * no identifier semantics live in whitespace. Case is different: some
+ * corpora carry identifiers whose subfields are case-significant (IECEx
+ * "60079-0v7B_DS" vs "60079-0v7b_DS" are distinct documents), so casefold
+ * is a FALLBACK tier, consulted only when no exact row matches. The
+ * fallback is first-wins in corpus order: deterministic, and it never
+ * overrides an exact hit. Spaces adjacent to a COLON collapse in the
+ * fallback tier too ("R 117-1 : 2019" -> "R 117-1:2019") — the colon is
+ * always a date separator in these identifiers, so the squeeze cannot
+ * merge two distinct rows, while "…: 2004" spellings are established
+ * real-world variance (the testsuite's own _normalization.yaml carries
+ * them). Only the colon: spaces around dashes or dots DO distinguish
+ * rows in some corpora, and are left alone.
+ */
+function collapseWs(spelling) {
+    return spelling.trim().replace(/\s+/g, " ");
+}
+function foldKey(spelling) {
+    return collapseWs(spelling).replace(/\s*:\s*/g, ":").toLowerCase();
+}
+/**
+ * Some URN schemes are edition-less (ISO: "ISO/IEC 17025:1999", ":2005"
+ * and ":2017" all serialize to urn:iso:std:iso-iec:17025), so a URN can
+ * key several corpus rows — 40% of iso's. Resolve such a URN to the
+ * LATEST edition (the greatest `year` in the row's hash; rows without a
+ * year rank lowest), which keeps parse(toUrn()) deterministic AND
+ * sensible, and expose the whole candidate set through
+ * parseUrnCandidates for consumers that need it.
+ */
+function latestEditionRow(rows) {
+    return [...rows].sort((a, b) => rowYear(a) - rowYear(b)).at(-1);
+}
+function rowYear(row) {
+    const year = row.hash["year"];
+    const parsed = typeof year === "string" || typeof year === "number"
+        ? Number(year)
+        : Number.NaN;
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+/**
+ * Corpus-backed identifier resolution over the pubid-testsuite corpus:
+ * every canonical spelling, its URN, its aliases and its canonical
+ * serialized form. Corpus mode resolves any identifier IN that universe
+ * and nothing outside it — it is a conformance surface and a fixture for
+ * the grammar waves (which take over a flavor open-endedly as they land),
+ * NOT an open-universe runtime parser: a real-world identifier missing
+ * from the corpus is rejected by design.
+ */
+export class CorpusBackedIdentifier {
+    row;
+    resolveHash;
+    constructor(row, resolveHash) {
+        this.row = row;
+        this.resolveHash = resolveHash;
+    }
+    toHash() {
+        return structuredClone(this.row.hash);
+    }
+    toHuman() {
+        return this.row.human;
+    }
+    toUrn() {
+        return this.row.urn;
+    }
+    fromHash(hash) {
+        return new CorpusBackedIdentifier(this.resolveHash(hash), this.resolveHash);
+    }
+}
+/**
+ * Build a corpus-mode implementation for one flavor from its payload
+ * cases. Indexes are per-implementation: a module-global hash index
+ * accumulated rows from every flavor, so an identifier from one flavor
+ * could deserialize another flavor's row — exactly the multi-SDO consumer
+ * this library exists for. Humans, URNs and non-normalized aliases all
+ * resolve (case- and whitespace-insensitively) to the same row; unknown
+ * spellings are rejected (parse throws).
+ */
+export function corpusModeImplementation(cases) {
+    const bySpelling = new Map();
+    const byFoldedSpelling = new Map();
+    // A URN keys EVERY row it was serialized from — ISO-style URN schemes
+    // are edition-less, so one URN can carry up to five editions. Singular
+    // storage silently resolved the ambiguity (a different edition than the
+    // one serialized, with no signal) — pubid-ts issue #4.
+    const byUrn = new Map();
+    const hashIndex = new Map();
+    const resolveHash = (hash) => {
+        const found = hashIndex.get(canonicalKey(hash));
+        if (found === undefined) {
+            throw new Error("unknown canonical hash for corpus-mode deserialization");
+        }
+        return found;
+    };
+    const indexSpelling = (spelling, row, keepFirst) => {
+        const exact = collapseWs(spelling);
+        if (!keepFirst || !bySpelling.has(exact))
+            bySpelling.set(exact, row);
+        const folded = foldKey(spelling);
+        if (!byFoldedSpelling.has(folded))
+            byFoldedSpelling.set(folded, row);
+    };
+    for (const testCase of cases) {
+        if (testCase.identifier === undefined)
+            continue; // quarantined row
+        const row = {
+            hash: testCase.identifier,
+            human: testCase.representations.human,
+            urn: testCase.representations.urn,
+        };
+        hashIndex.set(canonicalKey(row.hash), row);
+        indexSpelling(row.human, row, false);
+        if (row.urn !== undefined) {
+            const key = foldKey(row.urn);
+            const bucket = byUrn.get(key);
+            if (bucket)
+                bucket.push(row);
+            else
+                byUrn.set(key, [row]);
+        }
+        for (const alias of testCase.nonNormalizedAliases ?? []) {
+            indexSpelling(alias.spelling, row, true);
+        }
+    }
+    const urnRows = (input) => /^urn:/i.test(input.trim()) ? byUrn.get(foldKey(input)) : undefined;
+    const urnCandidates = (input) => urnRows(input) ?? [];
+    const parseInput = (input) => {
+        const rows = urnRows(input);
+        if (rows)
+            return latestEditionRow(rows);
+        return bySpelling.get(collapseWs(input)) ??
+            byFoldedSpelling.get(foldKey(input));
+    };
+    const implementation = {
+        parse(input) {
+            const row = parseInput(input);
+            if (row === undefined) {
+                throw new Error(`no such identifier in the published corpus: ${input}`);
+            }
+            return new CorpusBackedIdentifier(row, resolveHash);
+        },
+    };
+    return Object.assign(implementation, {
+        parseUrnCandidates: (input) => urnCandidates(input).map((row) => new CorpusBackedIdentifier(row, resolveHash)),
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./corpus/types.js";
+export { loadCorpus } from "./corpus/loader.js";
+export type { FlavorPayloads, Corpus } from "./corpus/loader.js";
+export { buildArtifact, loadBundledCorpus, parseArtifact, } from "./corpus/artifact.js";
+export type { FlavorImplementation, Identifier, ImplementationRegistry } from "./conformance/implementation.js";
+export { PendingRegistry } from "./conformance/pending.js";
+export { checkCase, runFlavor, runCorpus } from "./conformance/runner.js";
+export { corpusModeImplementation, CorpusBackedIdentifier } from "./implementations/corpus-mode.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from "./corpus/types.js";
+export { loadCorpus } from "./corpus/loader.js";
+export { buildArtifact, loadBundledCorpus, parseArtifact, } from "./corpus/artifact.js";
+export { PendingRegistry } from "./conformance/pending.js";
+export { checkCase, runFlavor, runCorpus } from "./conformance/runner.js";
+export { corpusModeImplementation, CorpusBackedIdentifier } from "./implementations/corpus-mode.js";

package/dist/internal/compare.d.ts

@@ -0,0 +1,3 @@
+/** Canonical JSON key order: the comparison basis for hash records. */
+export declare function canonicalKey(value: unknown): string;
+export declare function deepEqual(a: unknown, b: unknown): boolean;

package/dist/internal/compare.js

@@ -0,0 +1,17 @@
+/** Canonical JSON key order: the comparison basis for hash records. */
+export function canonicalKey(value) {
+    return JSON.stringify(sortKeys(value));
+}
+export function deepEqual(a, b) {
+    return canonicalKey(a) === canonicalKey(b);
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([x], [y]) => (x < y ? -1 : x > y ? 1 : 0))
+            .map(([k, v]) => [k, sortKeys(v)]));
+    }
+    return value;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@pubid/pubid",
+  "version": "0.1.2",
+  "description": "TypeScript PubID identifiers: resolution, normalization and canonical hashes for every identifier in the pubid-testsuite corpus (41 standards bodies), with a conformance runner mirroring the Ruby reference",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.test.json && node --test dist-test/test/*.test.js",
+    "conformance": "tsc -p tsconfig.json && node dist/conformance/cli.js",
+    "prepublishOnly": "tsc -p tsconfig.json",
+    "artifact": "tsc -p tsconfig.json && node scripts/build-artifact.mjs"
+  },
+  "dependencies": {
+    "yaml": "^2.5.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/node": "^20.14.0"
+  },
+  "files": [
+    "dist",
+    "artifact"
+  ],
+  "keywords": [
+    "pubid",
+    "identifier",
+    "standards",
+    "iso",
+    "iec",
+    "ieee",
+    "nist",
+    "conformance"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pubid/pubid-ts.git"
+  },
+  "homepage": "https://github.com/pubid/pubid-ts#readme",
+  "bugs": {
+    "url": "https://github.com/pubid/pubid-ts/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false
+}