@primmel/primmel 1.8.1 → 1.9.0

package/dist/src/export/retrieval.js

@@ -0,0 +1,1156 @@
+"use strict";
+// ─────────────────────────────────────────────────────────────────────
+// Retrieval export (primmel/primmel-ts#65 — the AI-native retrieval
+// projection): the canonical, versioned serialization of a package's
+// typed units for RAG and agent consumers.
+//
+// A Primmel package carries knowledge no document format holds — the
+// machine limits, the applicability filters, the acceptance chains, the
+// subject-intrinsic constraints. Retrieval consumers (the OIML SMART
+// estate's model plane first among them) project every package into
+// typed units and index them next to the prose corpus; today each
+// consumer re-derives that projection and the re-derivation is where
+// the mapping bugs live. This module is the UPSTREAM canonical form of
+// that projection: one export, one contract, versioned as
+// `primmel-retrieval/1`.
+//
+// The contract (the guarantees the issue asks for):
+//
+//   1. CLAUSE URNS FIRST-CLASS, ALWAYS. Every unit's provenance is the
+//      DOCUMENT's own clause numbering plus the document identifier —
+//      `clause: { doc, clause, urn }` with urn = <doc>#clause-<clause>
+//      (e.g. urn:oiml:pub:r:60-1:2021#clause-3.6). A producer-internal
+//      anchor (a metanorma UUID, `_eb46a3a3-…` style) is NOT a clause:
+//      it rides as the optional `anchor` extra, never as the clause,
+//      and units whose only provenance is an anchor are counted in the
+//      stats (anchorOnlyProvenance) — visible debt, never silently
+//      presented as citable provenance.
+//   2. CANONICAL EDITION SEMANTICS. The document block exposes two
+//      distinct, stable fields: `edition` (the PUBLICATION edition the
+//      model corresponds to — the manifest's newest `editions` entry,
+//      the baseUrn's year segment as fallback) and `model_version`
+//      (the package's own `version`). Edition steering reads the first;
+//      freshness gating reads the second; neither ever borrows the
+//      other's value.
+//   3. THE FLAT RETRIEVAL FACET. Every unit carries `facet` — one flat
+//      scalar map (string values only), versioned as
+//      `retrieval-facet/1` on the document's `facet_version`: the
+//      document fields (identifier, doc number, doctype, edition,
+//      language), the clause anchor, the unit kind, the applicability
+//      dimensions (`app_<dim>` keys), and the currency keys (unit_id,
+//      unit_hash, model_version). Retrieval indexes accept only scalar
+//      metadata per vector; the facet is the canonical pre-flattened
+//      form so a consumer's ingestion is a MAPPING, never a
+//      re-derivation. The facet is a derived projection of the unit's
+//      authored content, so it is EXCLUDED from the content_hash input
+//      (identity and currency ride the authored fields; the facet
+//      re-derives from them deterministically).
+//   4. STABLE UNIT IDS + CONTENT DIGESTS. Unit ids are the package's
+//      OWN authored identifiers (requirement `/req/class-a/mpe`, term
+//      `/term/durability`, …) — the stability tier is STABLE PUBLIC
+//      IDENTIFIER: an id moves only when the package re-authors the
+//      identifier, and a rename of display text (name/label/statement)
+//      never moves it. Beside the id rides `content_hash` — sha256 over
+//      the unit's canonical JSON content (sorted keys, compact
+//      separators, UTF-8 — the form every JSON stack reproduces:
+//      `json.dumps(c, sort_keys=True, separators=(",", ":"),
+//      ensure_ascii=False)`). Identity = id; currency = digest. A
+//      rename moves the digest, never the id.
+//   6. THE MACHINE PASSPORT. Every unit carries `passport` — the
+//      compact digest an agent (an MCP server) can carry and verify
+//      without loading the package: kind, id, the headline text
+//      (statement/definition), the machine expression (limit / check /
+//      derivation), the declared units, the applicability summary, the
+//      acceptance summary, the provenance URNs, and the content hash.
+//      `passportCanonical` renders it as the canonical string form.
+//   7. LANGUAGE-TAGGED VARIANTS. Every unit carries `language` — the
+//      package's default spelling, the ISO 24229 tag of the INLINE
+//      prose values — and, when the package ships `text` blocks,
+//      `variants`: the alternate spellings resolved onto the unit by
+//      the C89 address rule (the longest registered dot-boundary
+//      prefix; the kernel element id, not the namespaced unit id),
+//      keyed by the addressed field path, each entry
+//      `{ spelling, via?, value }`. Both are authored content and
+//      participate in the content_hash; a text block addressed at an
+//      element the projection does not ship is counted
+//      (droppedTextBlocks), never silently lost.
+//
+// Congruence with the deployed consumer (oimlsmart/smart
+// derive-model-plane.ts → oimlsmart/rag model_plane.py): the unit ids,
+// the clause { doc, clause, urn } shape, the sha256 currency signal,
+// and the bundle-level `source_hash` (the SAME algorithm — sha256 over
+// every byte of the package directory, sorted walk, path + NUL +
+// file-digest + LF) are deliberately identical so the consumer's pins
+// (`standard → { source_hash, node_count }`) key without translation.
+// The deliberate divergences: the document block nests under `package`
+// (the bundle carries label/base_urn top-level), the digest input is
+// the compact-canonical JSON documented above (the consumer's D1
+// content_hash uses Python's default separators — the input shapes
+// differ regardless), and the kind vocabulary is the kernel's honest
+// one (a calculation with a rule type is `formula`, matching the
+// consumer's calculations/formulas split; a verdict is `characteristic`,
+// matching the deployed plane's characteristics.yaml projection).
+//
+// ONE-WAY PROJECTION, NEVER THE KERNEL'S TRUTH — the same doctrine as
+// the ReqIF/RDF surfaces: the package stays the single source of truth;
+// the export is generated, never authored, never re-imported.
+//
+// The diff-as-data API (the issue's ask 5) is the model diff
+// (src/model-diff.ts), whose id keying this projection shares.
+// ─────────────────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RETRIEVAL_FACET_VERSION = exports.RETRIEVAL_PROJECTION = void 0;
+exports.canonicalJson = canonicalJson;
+exports.retrievalDigest = retrievalDigest;
+exports.passportCanonical = passportCanonical;
+exports.packageSourceHash = packageSourceHash;
+exports.normalizeClause = normalizeClause;
+exports.collectClauses = collectClauses;
+exports.termClauses = termClauses;
+exports.applicabilitySummary = applicabilitySummary;
+exports.retrievalDocParts = retrievalDocParts;
+exports.retrievalFacet = retrievalFacet;
+exports.resolveTextAddress = resolveTextAddress;
+exports.packageEdition = packageEdition;
+exports.exportStandardRetrieval = exportStandardRetrieval;
+exports.exportPackageRetrieval = exportPackageRetrieval;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const package_1 = require("../ser-des/package");
+/**
+ * The projection shape version (semver'd by the document, not the
+ * package): a shape change — a field renamed, removed, or re-typed —
+ * bumps the version and is a re-index signal for every consumer;
+ * additive fields within a version are legal (consumers ignore what
+ * they do not read).
+ */
+exports.RETRIEVAL_PROJECTION = 'primmel-retrieval/1';
+/**
+ * The facet shape version (ask 3 — the pre-flattened retrieval facet):
+ * semver'd independently of the projection — a facet key renamed,
+ * removed, or re-typed bumps it (a re-index signal); additive keys
+ * within a version are legal (indexes ignore what they do not read).
+ */
+exports.RETRIEVAL_FACET_VERSION = 'retrieval-facet/1';
+// ── canonical JSON + the content digest ──────────────────────────────
+/** Recursive key sort — the digest and serialization canonicalizer. */
+function sortDeep(v) {
+    if (Array.isArray(v)) {
+        return v.map(sortDeep);
+    }
+    if (v && typeof v === 'object') {
+        const out = {};
+        for (const k of Object.keys(v).sort()) {
+            const val = sortDeep(v[k]);
+            if (val !== undefined) {
+                out[k] = val;
+            }
+        }
+        return out;
+    }
+    return v;
+}
+/**
+ * The canonical JSON form: sorted keys, compact separators, UTF-8 — the
+ * form every JSON stack reproduces (`json.dumps(c, sort_keys=True,
+ * separators=(",", ":"), ensure_ascii=False)`). The digest input.
+ */
+function canonicalJson(value) {
+    return JSON.stringify(sortDeep(value));
+}
+/** sha256 hex over the canonical JSON of a value — the currency digest. */
+function retrievalDigest(value) {
+    return (0, node_crypto_1.createHash)('sha256')
+        .update(canonicalJson(value), 'utf8')
+        .digest('hex');
+}
+/**
+ * The canonical serialized form of a unit's passport (ask 6): the
+ * string an agent carries and re-hashes to verify the unit.
+ */
+function passportCanonical(passport) {
+    return canonicalJson(passport);
+}
+// ── the package source hash (the bundle freshness signal) ────────────
+function* walkPackage(dir) {
+    for (const entry of (0, node_fs_1.readdirSync)(dir).sort()) {
+        if (entry === '.DS_Store') {
+            continue;
+        }
+        const p = (0, node_path_1.join)(dir, entry);
+        if ((0, node_fs_1.statSync)(p).isDirectory()) {
+            yield* walkPackage(p);
+        }
+        else {
+            yield p;
+        }
+    }
+}
+/**
+ * sha256 over every file of the package (path + bytes), deterministic —
+ * the SAME algorithm the deployed consumer's derive-model-plane.ts runs
+ * (sorted walk, `.DS_Store` skipped, relative path + NUL + the file's
+ * own sha256 + LF), so a source_hash here and a source_hash there are
+ * the same signal and the consumer's pins key without translation. ANY
+ * package change — a constraint re-authored, a clause re-cited — moves
+ * the hash; that byte-sensitivity is deliberate (identity rides the
+ * unit ids, currency rides the digests).
+ */
+function packageSourceHash(dir) {
+    const h = (0, node_crypto_1.createHash)('sha256');
+    for (const file of walkPackage(dir)) {
+        h.update((0, node_path_1.relative)(dir, file));
+        h.update('\0');
+        h.update((0, node_crypto_1.createHash)('sha256').update((0, node_fs_1.readFileSync)(file)).digest());
+        h.update('\n');
+    }
+    return h.digest('hex');
+}
+// ── provenance: the clause-URN normalization (ask 1) ─────────────────
+/**
+ * A producer-internal anchor is never a clause: the metanorma UUID form
+ * (`_eb46a3a3-…` — the shape the consumer strips at ingestion) is
+ * detected exactly like the consumer detects it.
+ */
+const UUID_ANCHOR = /^_?[0-9a-f]{8}-[0-9a-f]{4}-/i;
+const DOC_FRAGMENT = /#([^#]*)$/;
+/**
+ * Normalize one raw provenance edge onto the document's own numbering.
+ * The `doc` slot of a loaded ref may carry an embedded `#fragment` (the
+ * derives-from fold's shape for non-clause anchors — ref.ts); a
+ * `#clause-<n>` fragment restores the clause, any other fragment rides
+ * as the `anchor` extra. A UUID-shaped clause or fragment is an anchor,
+ * never a clause.
+ */
+function normalizeClause(doc, clause, fragment = '') {
+    let rest = doc ?? '';
+    let clauseOut = clause ?? '';
+    let frag = fragment ?? '';
+    let anchor;
+    const hash = DOC_FRAGMENT.exec(rest);
+    if (hash) {
+        rest = rest.slice(0, hash.index);
+        const embedded = hash[1] ?? '';
+        if (!clauseOut && embedded.startsWith('clause-')) {
+            const tail = embedded.slice('clause-'.length);
+            const slash = tail.indexOf('/');
+            if (slash >= 0) {
+                clauseOut = tail.slice(0, slash);
+                if (!frag) {
+                    frag = tail.slice(slash + 1);
+                }
+            }
+            else {
+                clauseOut = tail;
+            }
+        }
+        else if (embedded && !frag) {
+            // A non-clause fragment (a table anchor, a UUID) is an anchor,
+            // never a clause number.
+            anchor = embedded;
+        }
+        else if (embedded) {
+            anchor = embedded;
+        }
+    }
+    if (clauseOut && UUID_ANCHOR.test(clauseOut)) {
+        // A UUID in the clause slot is a producer-internal anchor that lost
+        // its way — demote it, never present it as the document's numbering.
+        anchor = anchor ?? clauseOut;
+        clauseOut = '';
+    }
+    const urn = rest +
+        (clauseOut
+            ? `#clause-${clauseOut}${frag ? `/${frag}` : ''}`
+            : anchor && !UUID_ANCHOR.test(anchor)
+                ? `#${anchor}`
+                : '');
+    const out = { doc: rest, clause: clauseOut, urn };
+    if (anchor !== undefined) {
+        out.anchor = anchor;
+    }
+    if (frag) {
+        out.fragment = frag;
+    }
+    return out;
+}
+/** A ref target that is a document URN folds into provenance (the §18.4
+ *  citation fold's defensive mirror — after a package load the fold has
+ *  already run; a hand-built Standard may carry them unfolded). */
+function refTargetClause(target) {
+    const m = /^(urn:[^#]+)(?:#(.+))?$/.exec(target);
+    if (!m) {
+        return null;
+    }
+    return { doc: m[1], clause: '', fragment: m[2] ?? '' };
+}
+/**
+ * Collect every provenance edge of an element, normalized and
+ * de-duplicated by URN, in authored order: the structured channels
+ * (source / sourceRef / sourceRefs), the scalar reference URN (the
+ * conformance test's v2 channel), and urn-targeted refs not already
+ * folded. The first edge is the unit's primary `clause`.
+ */
+function collectClauses(el) {
+    const out = [];
+    const seen = new Set();
+    const push = (r) => {
+        if (!r || (!r.doc && !r.clause)) {
+            return;
+        }
+        const c = normalizeClause(r.doc ?? '', r.clause ?? '', r.fragment);
+        if (!seen.has(c.urn)) {
+            seen.add(c.urn);
+            out.push(c);
+        }
+    };
+    push(el.source);
+    push(el.sourceRef);
+    for (const r of el.sourceRefs ?? []) {
+        push(r);
+    }
+    // The conformance test's scalar reference (v2) arrives quote-wrapped
+    // from the codec's legacy path — strip before the URN test.
+    const reference = (el.reference ?? '').replace(/^"|"$/g, '');
+    if (reference.startsWith('urn:')) {
+        push(refTargetClause(reference));
+    }
+    for (const r of el.refs ?? []) {
+        if (r && typeof r.target === 'string' && r.target.startsWith('urn:')) {
+            push(refTargetClause(r.target));
+        }
+    }
+    return out;
+}
+/**
+ * A term's provenance (ask 1's sharpest case): the `source` facet is a
+ * plain string carrying whitespace-separated URNs (e.g. the VIML URN
+ * plus the Recommendation's clause URN); each parses onto a normalized
+ * edge. When no parsed edge carries a clause number and the term
+ * declares a `section` (the document's own terminology clause), the
+ * section becomes an edge on the package's base URN — the document's
+ * own numbering, exactly as authored.
+ */
+function termClauses(term, baseUrn) {
+    const out = [];
+    const seen = new Set();
+    const push = (c) => {
+        if (c && !seen.has(c.urn)) {
+            seen.add(c.urn);
+            out.push(c);
+        }
+    };
+    for (const token of (term.source ?? '').split(/\s+/).filter(t => t)) {
+        push(token.startsWith('urn:') ? normalizeClause(token, '') : null);
+    }
+    if (term.section && !out.some(c => c.clause)) {
+        push(normalizeClause(baseUrn, term.section));
+    }
+    return out;
+}
+// ── the passport (ask 6) ─────────────────────────────────────────────
+/** The canonical-compact applicability summary: `dim=v1|v2; …`, sorted. */
+function applicabilitySummary(entries) {
+    return (entries ?? [])
+        .map(e => {
+        const mode = e.match && e.match !== 'any' ? `(${e.match})` : '';
+        return `${e.dimension}${mode}=${[...e.values].sort().join('|')}`;
+    })
+        .sort()
+        .join(';');
+}
+function passportOf(unit) {
+    return {
+        v: 1,
+        kind: unit.kind,
+        id: unit.id,
+        text: unit.statement ?? unit.definition ?? unit.name ?? '',
+        expression: unit.expression ?? '',
+        units: unit.units ?? [],
+        applicability: applicabilitySummary(unit.applicability),
+        acceptance: unit.acceptance ?? '',
+        provenance: (unit.clauses ?? []).map(c => c.urn),
+        content_hash: unit.content_hash,
+    };
+}
+const BASE_URN_PARTS = /^urn:oiml:pub:([rdbge]):(\d[\d-]*)(?::(\d{4}))?$/i;
+function retrievalDocParts(baseUrn) {
+    const m = BASE_URN_PARTS.exec(baseUrn);
+    if (!m) {
+        return { doctype: '', doc_number: '', year: '', label: '' };
+    }
+    const doctype = (m[1] ?? '').toLowerCase();
+    const docNumber = m[2] ?? '';
+    const year = m[3] ?? '';
+    return {
+        doctype,
+        doc_number: docNumber,
+        year,
+        label: `OIML ${doctype.toUpperCase()} ${docNumber}${year ? `:${year}` : ''}`,
+    };
+}
+/**
+ * Build the unit's flat facet (ask 3): the document fields every vector
+ * of this package carries, the unit's kind + currency keys, its primary
+ * clause anchor, and its applicability dimensions flattened to
+ * `app_<dim>` keys (values sorted, `|`-joined; a non-`any` match mode
+ * rides beside as `app_<dim>_match`).
+ *
+ * Key congruence with the deployed consumer's chunk wire schema
+ * (ChunkMetaModel): `doc_id`, `docidentifier`, `doctype`, `doc_number`,
+ * `edition`, `language`, `clause_anchor`, `clause_title`, `status`,
+ * `unit_id`, `block`, `unit_hash` carry the same names and semantics.
+ * The lane constants the schema also carries (`tier`, `corpus`,
+ * `producer`, `text_ref`, `superseded_by`) are DEPLOYMENT stamps, not
+ * package content — the consumer's adapter sets them per lane; the
+ * facet never invents them. Three deliberate value choices:
+ *
+ *   - `language` is the package's authored default spelling (the
+ *     ISO 24229 code, e.g. `eng-Latn`) — the consumer lanes stamp a
+ *     constant two-letter code today; the facet carries the authored
+ *     truth and the adapter maps.
+ *   - `clause_anchor` is the primary edge's document clause number, ''
+ *     when the unit names no clause (never a producer UUID — ask 1
+ *     already demoted those to `anchor`). The consumer's "model"
+ *     fallback for clause-less model units is its lane marker, applied
+ *     at its adapter.
+ *   - `edition` is the package block's canonical edition (ask 2), not
+ *     a re-parse of the base URN — the two coincide on URN-carrying
+ *     packages, and the package block is authoritative when they drift.
+ */
+function retrievalFacet(unit, pkg) {
+    const parts = retrievalDocParts(pkg.base_urn);
+    const facet = {
+        unit_id: unit.id,
+        unit_hash: unit.content_hash,
+        block: unit.kind,
+        doc_id: pkg.id,
+        docidentifier: parts.label || pkg.title,
+        doctype: parts.doctype,
+        doc_number: parts.doc_number,
+        edition: pkg.edition,
+        model_version: pkg.model_version,
+        language: pkg.default_spelling,
+        clause_anchor: unit.clause?.clause ?? '',
+        clause_title: unit.name ?? unit.id,
+        ...(present(pkg.status) ? { status: pkg.status } : {}),
+    };
+    const valuesByDim = new Map();
+    const matchByDim = new Map();
+    for (const entry of unit.applicability ?? []) {
+        const values = entry.values.length > 0 ? entry.values : Object.keys(entry.mapping ?? {});
+        const set = valuesByDim.get(entry.dimension) ?? new Set();
+        for (const v of values) {
+            set.add(v);
+        }
+        valuesByDim.set(entry.dimension, set);
+        if (entry.match &&
+            entry.match !== 'any' &&
+            !matchByDim.has(entry.dimension)) {
+            matchByDim.set(entry.dimension, entry.match);
+        }
+    }
+    for (const dim of [...valuesByDim.keys()].sort()) {
+        facet[`app_${dim}`] = [...valuesByDim.get(dim)].sort().join('|');
+        const match = matchByDim.get(dim);
+        if (match) {
+            facet[`app_${dim}_match`] = match;
+        }
+    }
+    return facet;
+}
+// ── language-tagged variants (ask 7) ─────────────────────────────────
+/**
+ * Resolve a `text` block's address onto its element: the LONGEST
+ * dot-boundary prefix registered in the package (element ids may
+ * themselves carry dots — `r144-3/sec-3.4`); the rest is the path into
+ * the element's structure, the terminal segment the prose field. The
+ * same rule the C89 linter resolves with (check.ts) — the projection
+ * and the linter never disagree about which element a text block
+ * addresses.
+ */
+function resolveTextAddress(address, elementIds) {
+    const segments = address.split('.');
+    if (segments.length < 2 || segments.some(s => s === '')) {
+        return null;
+    }
+    for (let i = segments.length - 1; i >= 1; i--) {
+        const candidate = segments.slice(0, i).join('.');
+        if (elementIds.has(candidate)) {
+            return { elementId: candidate, path: segments.slice(i).join('.') };
+        }
+    }
+    return null;
+}
+/**
+ * The id-keyed collections a text block may address — the mirror of the
+ * C89 linter's element registry (check.ts). Resolution runs against the
+ * FULL registry (not only the projected kinds): an address whose
+ * longest registered prefix is an unprojected element (a form, an
+ * instrument) must NOT fall through to a shorter projected prefix —
+ * that misattribution is worse than a drop, and the drop is counted.
+ */
+const TEXT_ADDRESS_COLLECTIONS = [
+    'requirements',
+    'requirementClasses',
+    'conformanceTests',
+    'conformanceClasses',
+    'terms',
+    'forms',
+    'subforms',
+    'symbols',
+    'tables',
+    'calculations',
+    'notes',
+    'provisions',
+    'processes',
+    'instruments',
+    'attributeDefinitions',
+    'capabilities',
+    'behaviors',
+    'conditionSets',
+    'subjects',
+    'referenceMaterials',
+    'artifactDefinitions',
+    'monitors',
+    'passports',
+    'invariants',
+    'testSequences',
+    'formulasUsed',
+    'stateMachines',
+    'figures',
+    'links',
+];
+/**
+ * Attach the language tag and the variants to the built unit contents
+ * (pre-digest — both are authored content): `language` is the package's
+ * default spelling on every unit; `variants` resolves each `text` block
+ * onto its unit (by the KERNEL element id — a term's text block
+ * addresses `frobnicator`, not `/term/frobnicator`) and keys the
+ * entries by the addressed field path. Returns the count of text blocks
+ * whose variants reached no unit (the droppedTextBlocks honesty tally).
+ */
+function attachVariants(built, standard, pkg) {
+    if (present(pkg.default_spelling)) {
+        for (const b of built) {
+            b.content.language = pkg.default_spelling;
+        }
+    }
+    const texts = standard.texts ?? [];
+    if (texts.length === 0) {
+        return 0;
+    }
+    const registry = new Set();
+    for (const field of TEXT_ADDRESS_COLLECTIONS) {
+        for (const item of standard[field] ?? []) {
+            if (item?.id) {
+                registry.add(item.id);
+            }
+        }
+    }
+    const unitByElement = new Map(built.map(b => [b.elementId, b.content]));
+    let dropped = 0;
+    for (const t of texts) {
+        const resolved = resolveTextAddress(t.id, registry);
+        const content = resolved
+            ? unitByElement.get(resolved.elementId)
+            : undefined;
+        if (!resolved || !content) {
+            dropped++;
+            continue;
+        }
+        const variants = (content.variants ??= {});
+        variants[resolved.path] = [
+            ...(variants[resolved.path] ?? []),
+            ...t.entries,
+        ];
+    }
+    return dropped;
+}
+/**
+ * Attach the provenance edges to a built unit content. The digest,
+ * passport and facet arrive later (`completeUnit`) — the language tag
+ * and variants (ask 7) attach between assembly and digestion, so they
+ * participate in the content_hash like any authored field.
+ */
+function assemble(content, clauses) {
+    if (clauses.length > 0) {
+        content.clause = clauses[0];
+        content.clauses = clauses;
+    }
+    return content;
+}
+/**
+ * Complete an assembled unit content into the shipped unit: the content
+ * digest (over the authored fields — language and variants included),
+ * then the derived projections (passport, facet) that read it.
+ */
+function completeUnit(content, pkg) {
+    const hash = retrievalDigest(content);
+    const unit = {
+        ...content,
+        content_hash: hash,
+    };
+    unit.passport = passportOf(unit);
+    // The facet attaches last (a derived projection of the digested
+    // content — the unit_hash key reads the computed content_hash).
+    unit.facet = retrievalFacet(unit, pkg);
+    return unit;
+}
+/** The parent class/scope id of a scoped id (`/req/a/b` → `/req/a`). */
+function scopeOf(id) {
+    const slash = id.lastIndexOf('/');
+    return slash > 0 ? id.slice(0, slash) : undefined;
+}
+const present = (s) => typeof s === 'string' && s.length > 0;
+const presentList = (xs) => xs && xs.length > 0 ? xs : undefined;
+function requirementUnit(r) {
+    return assemble({
+        id: r.id,
+        kind: 'requirement',
+        ...(scopeOf(r.id) ? { class: scopeOf(r.id) } : {}),
+        ...(present(r.name) ? { name: r.name } : {}),
+        ...(present(r.statement) ? { statement: r.statement } : {}),
+        ...(present(r.guidance) ? { guidance: r.guidance } : {}),
+        ...(present(r.obligation) ? { obligation: r.obligation } : {}),
+        modality: r.limit?.modality || 'shall',
+        ...(r.limit?.expression
+            ? {
+                expression: r.limit.expression,
+                ...(presentList(r.limit.uses)
+                    ? { expression_inputs: r.limit.uses }
+                    : {}),
+            }
+            : {}),
+        ...(presentList(r.applicability)
+            ? { applicability: r.applicability }
+            : {}),
+        ...(presentList(r.bindsTo) ? { binds_to: r.bindsTo } : {}),
+        ...(r.limit?.accepts
+            ? {
+                acceptance: `${r.limit.accepts.verdict} ${r.limit.accepts.op} ${r.limit.accepts.limit}`,
+            }
+            : {}),
+        ...(present(r.acceptanceCriteria)
+            ? { acceptance_criteria: r.acceptanceCriteria }
+            : {}),
+        ...(present(r.verificationMethod)
+            ? {
+                verification: {
+                    method: r.verificationMethod,
+                    description: r.verificationDescription ?? '',
+                },
+            }
+            : {}),
+        ...(present(r.channel) ? { channel: r.channel } : {}),
+        ...(presentList(r.dependencies) ? { dependencies: r.dependencies } : {}),
+    }, collectClauses(r));
+}
+function conformanceTestUnit(t) {
+    const payload = {
+        ...(present(t.kind) ? { test_kind: t.kind } : {}),
+        ...(present(t.methodRef) ? { method_ref: t.methodRef } : {}),
+        ...(presentList(t.preconditions)
+            ? {
+                preconditions: t.preconditions.map(p => ({
+                    id: p.id,
+                    check: p.check,
+                    description: p.description,
+                    on_violation: p.onViolation,
+                })),
+            }
+            : {}),
+    };
+    return assemble({
+        id: t.id,
+        kind: 'conformance_test',
+        ...(scopeOf(t.id) ? { class: scopeOf(t.id) } : {}),
+        ...(present(t.name) ? { name: t.name } : {}),
+        ...(present(t.purpose) ? { statement: t.purpose } : {}),
+        ...(present(t.method) ? { definition: t.method } : {}),
+        ...(present(t.guidance) ? { guidance: t.guidance } : {}),
+        ...(present(t.obligation) ? { obligation: t.obligation } : {}),
+        ...(presentList(t.applicability)
+            ? { applicability: t.applicability }
+            : {}),
+        ...(presentList(t.targets) ? { targets: t.targets } : {}),
+        ...(presentList(t.bindsTo) ? { binds_to: t.bindsTo } : {}),
+        ...(present(t.acceptancePassIf)
+            ? { acceptance: t.acceptancePassIf }
+            : present(t.acceptanceCriteriaDescription)
+                ? { acceptance: t.acceptanceCriteriaDescription }
+                : {}),
+        ...(presentList(t.dependencies) ? { dependencies: t.dependencies } : {}),
+        ...(Object.keys(payload).length > 0 ? { payload } : {}),
+    }, collectClauses(t));
+}
+function termUnit(t, baseUrn) {
+    const payload = {
+        ...(present(t.section) ? { section: t.section } : {}),
+        ...(present(t.language) ? { language: t.language } : {}),
+        ...(t.vocabRef ? { vocab_ref: t.vocabRef } : {}),
+        // The alias family (MN 114 v3.2, clause 13.10.1): the parser folds
+        // the v2 `alt` spelling into the canonical aliases channel; the
+        // payload keeps the deployed `alt` key (contract stability) and adds
+        // the v3.2 facets.
+        ...(presentList(t.aliases ?? t.alt) ? { alt: (t.aliases ?? t.alt) } : {}),
+        ...(presentList(t.colloquial) ? { colloquial: t.colloquial } : {}),
+        ...(t.aliasSpellings && Object.keys(t.aliasSpellings).length > 0
+            ? { alias_spellings: t.aliasSpellings }
+            : {}),
+        ...(presentList(t.abbreviations) ? { abbreviations: t.abbreviations } : {}),
+        ...(presentList(t.seeAlso) ? { see_also: t.seeAlso } : {}),
+    };
+    return assemble({
+        id: `/term/${t.id}`,
+        kind: 'term',
+        ...(present(t.label) ? { name: t.label } : {}),
+        ...(present(t.definition) ? { definition: t.definition } : {}),
+        ...(Object.keys(payload).length > 0 ? { payload } : {}),
+    }, termClauses(t, baseUrn));
+}
+function attributeUnit(a) {
+    const payload = {
+        ...(present(a.symbol) ? { symbol: a.symbol } : {}),
+        ...(present(a.quantityKind) ? { quantity_kind: a.quantityKind } : {}),
+        ...(present(a.valueType) ? { value_type: a.valueType } : {}),
+        ...(present(a.origin) ? { origin: a.origin } : {}),
+        ...(present(a.scope) ? { scope: a.scope } : {}),
+        ...(present(a.category) ? { category: a.category } : {}),
+        ...(present(a.irdi) ? { irdi: a.irdi } : {}),
+        ...(presentList(a.enumValues) ? { enum_values: a.enumValues } : {}),
+    };
+    return assemble({
+        id: `/attribute/${a.id}`,
+        kind: 'attribute',
+        ...(present(a.name) ? { name: a.name } : {}),
+        ...(present(a.definition) ? { definition: a.definition } : {}),
+        ...(present(a.unit) && a.unit !== '1' ? { units: [a.unit] } : {}),
+        ...(Object.keys(payload).length > 0 ? { payload } : {}),
+    }, collectClauses(a));
+}
+function behaviorUnit(b) {
+    const payload = {
+        ...(present(b.kind) ? { behavior_kind: b.kind } : {}),
+        ...(present(b.stimulus) ? { stimulus: b.stimulus } : {}),
+    };
+    return assemble({
+        id: `/behavior/${b.id}`,
+        kind: 'behavior',
+        name: b.id,
+        ...(present(b.response) ? { statement: b.response } : {}),
+        ...(Object.keys(payload).length > 0 ? { payload } : {}),
+    }, collectClauses(b));
+}
+function calculationUnits(c) {
+    const out = new Set();
+    for (const i of c.inputs ?? []) {
+        if (present(i.unit) && i.unit !== '1') {
+            out.add(i.unit);
+        }
+    }
+    if (c.output && present(c.output.unit) && c.output.unit !== '1') {
+        out.add(c.output.unit);
+    }
+    return [...out].sort();
+}
+function calculationUnit(c) {
+    // The consumer's calculations/formulas split: a calculation carrying
+    // an engine rule type projects as a `formula` unit (the operator
+    // signature), the rest as `calculation` (typed IO).
+    const kind = present(c.ruleType)
+        ? 'formula'
+        : 'calculation';
+    const units = calculationUnits(c);
+    const payload = {
+        name: c.name,
+        ...(present(c.ruleType) ? { rule_type: c.ruleType } : {}),
+        ...(present(c.category) ? { category: c.category } : {}),
+        ...(presentList(c.inputs)
+            ? {
+                inputs: c.inputs.map(i => ({
+                    name: i.name,
+                    type: i.type,
+                    ...(present(i.unit) ? { unit: i.unit } : {}),
+                })),
+            }
+            : {}),
+        ...(c.output && present(c.output.type) ? { output: c.output } : {}),
+        ...(c.lookup ? { lookup: c.lookup } : {}),
+        ...(present(c.profile) ? { profile: c.profile } : {}),
+    };
+    return assemble({
+        id: present(c.identifier) ? c.identifier : `/calculation/${c.id}`,
+        kind,
+        name: c.label || c.name || c.id,
+        ...(present(c.description) ? { definition: c.description } : {}),
+        ...(present(c.expression) ? { expression: c.expression } : {}),
+        ...(presentList(c.params) ? { expression_inputs: c.params } : {}),
+        ...(units.length > 0 ? { units } : {}),
+        payload,
+    }, collectClauses({
+        sourceRef: c.sourceRef,
+        sourceRefs: c.sourceRefs,
+        refs: c.refs,
+    }));
+}
+function symbolUnit(s) {
+    const units = present(s.unit) && s.unit !== '1' ? [s.unit] : undefined;
+    const payload = {
+        ...(present(s.type) ? { symbol_type: s.type } : {}),
+        ...(present(s.kind) ? { symbol_kind: s.kind } : {}),
+        ...(present(s.quantityKind) ? { quantity_kind: s.quantityKind } : {}),
+        ...(present(s.origin) ? { origin: s.origin } : {}),
+        ...(present(s.latex) ? { latex: s.latex } : {}),
+        ...(s.formula && present(s.formula.display)
+            ? { display: s.formula.display }
+            : {}),
+        ...(present(s.calculation) ? { calculation: s.calculation } : {}),
+    };
+    return assemble({
+        id: `/symbol/${s.id}`,
+        kind: 'symbol',
+        ...(present(s.name) ? { name: s.name } : {}),
+        ...(present(s.definition) ? { definition: s.definition } : {}),
+        ...(s.formula && present(s.formula.expression)
+            ? {
+                expression: s.formula.expression,
+                ...(presentList(s.formula.inputs)
+                    ? { expression_inputs: s.formula.inputs }
+                    : {}),
+            }
+            : {}),
+        ...(units ? { units } : {}),
+        ...(Object.keys(payload).length > 0 ? { payload } : {}),
+    }, collectClauses({
+        sourceRef: s.sourceRef,
+        sourceRefs: s.sourceRefs,
+        refs: s.refs,
+    }));
+}
+function constraintUnit(c) {
+    return assemble({
+        id: `/constraint/${c.id}`,
+        kind: 'constraint',
+        ...(present(c.name) ? { name: c.name } : {}),
+        ...(present(c.violationMeaning) ? { statement: c.violationMeaning } : {}),
+        ...(present(c.check) ? { expression: c.check } : {}),
+        payload: {
+            ...(present(c.stereotype) ? { stereotype: c.stereotype } : {}),
+            ...(present(c.onViolation) ? { on_violation: c.onViolation } : {}),
+        },
+    }, collectClauses(c));
+}
+function characteristicUnit(v) {
+    // The deployed plane's `characteristic` kind: the canonical verdict
+    // quantity (derive once, reference everywhere).
+    const units = present(v.unit) && v.unit !== '1' ? [v.unit] : undefined;
+    const payload = {
+        ...(present(v.behavior) ? { behavior: v.behavior } : {}),
+        ...(present(v.quantityKind) ? { quantity_kind: v.quantityKind } : {}),
+        ...(v.seriesReduction ? { series_reduction: v.seriesReduction } : {}),
+    };
+    return assemble({
+        id: `/characteristic/${v.id}`,
+        kind: 'characteristic',
+        ...(present(v.symbol) ? { name: v.symbol } : {}),
+        ...(present(v.derive)
+            ? {
+                expression: v.derive,
+                ...(presentList(v.inputs) ? { expression_inputs: v.inputs } : {}),
+            }
+            : {}),
+        ...(units ? { units } : {}),
+        ...(v.acceptance && present(v.acceptance.rule)
+            ? { acceptance: v.acceptance.rule }
+            : {}),
+        ...(Object.keys(payload).length > 0 ? { payload } : {}),
+    }, collectClauses(v));
+}
+function tableUnit(t) {
+    const units = (t.columnDefs ?? [])
+        .map(c => c.unit)
+        .filter(u => present(u) && u !== '1')
+        .sort();
+    const payload = {
+        ...(presentList(t.columnDefs)
+            ? {
+                columns: t.columnDefs.map(c => ({
+                    name: c.name,
+                    type: c.type,
+                    ...(present(c.unit) ? { unit: c.unit } : {}),
+                })),
+            }
+            : present(t.columns)
+                ? { columns: t.columns }
+                : {}),
+        ...(presentList(t.data) ? { rows: t.data } : {}),
+        ...(t.profiles ? { profiles: t.profiles } : {}),
+    };
+    return assemble({
+        id: `/table/${t.id}`,
+        kind: 'table',
+        ...(present(t.title) ? { name: t.title } : {}),
+        ...(present(t.description) ? { definition: t.description } : {}),
+        ...(units.length > 0 ? { units: [...new Set(units)] } : {}),
+        ...(Object.keys(payload).length > 0 ? { payload } : {}),
+    }, collectClauses({
+        sourceRef: t.sourceRef,
+        sourceRefs: t.sourceRefs,
+        refs: t.refs,
+    }));
+}
+function sequenceUnit(s) {
+    const payload = {
+        steps: s.steps.map(st => ({
+            order: st.order,
+            ...(present(st.test) ? { test: st.test } : {}),
+            ...(present(st.phase) ? { phase: st.phase } : {}),
+            ...(present(st.role) ? { role: st.role } : {}),
+            ...(st.dependsOn !== null ? { depends_on: st.dependsOn } : {}),
+        })),
+        ...(present(s.sampleApplicability)
+            ? { sample_applicability: s.sampleApplicability }
+            : {}),
+    };
+    return assemble({
+        id: `/sequence/${s.id}`,
+        kind: 'sequence',
+        ...(present(s.name) ? { name: s.name } : {}),
+        ...(present(s.description) ? { statement: s.description } : {}),
+        payload,
+    }, collectClauses({ sourceRefs: s.sourceRefs, refs: s.refs }));
+}
+function noteUnit(n) {
+    return assemble({
+        id: `/note/${n.id}`,
+        kind: 'note',
+        name: n.type,
+        ...(present(n.message) ? { statement: n.message } : {}),
+    }, []);
+}
+function stateMachineUnit(m) {
+    // The state machine keys by the bound entity's name (the construct
+    // declares no id — the model diff's E12 keying).
+    const id = m.entityName;
+    const payload = {
+        ...(present(m.kind) ? { machine_kind: m.kind } : {}),
+        ...(present(m.initialState) ? { initial: m.initialState } : {}),
+        ...(presentList(m.states) ? { states: m.states.map(s => s.name) } : {}),
+        ...(presentList(m.transitions)
+            ? {
+                transitions: m.transitions.map(t => ({
+                    from: t.from,
+                    to: t.to,
+                    ...(present(t.actionName) ? { action: t.actionName } : {}),
+                    ...(present(t.guard) ? { guard: t.guard } : {}),
+                })),
+            }
+            : {}),
+    };
+    return assemble({
+        id: `/state-machine/${id}`,
+        kind: 'state_machine',
+        name: id,
+        ...(Object.keys(payload).length > 0 ? { payload } : {}),
+    }, []);
+}
+function dimensionUnit(d) {
+    const payload = {
+        ...(present(d.scope) ? { scope: d.scope } : {}),
+        ...(present(d.cardinality) ? { cardinality: d.cardinality } : {}),
+        values: d.values.map(v => ({
+            id: v.id,
+            ...(present(v.label) ? { label: v.label } : {}),
+            ...(presentList(v.implies) ? { implies: v.implies } : {}),
+            ...(present(v.termRef) ? { term_ref: v.termRef } : {}),
+        })),
+    };
+    return assemble({
+        id: `/dimension/${d.id}`,
+        kind: 'dimension',
+        ...(present(d.label) ? { name: d.label } : {}),
+        ...(present(d.description) ? { definition: d.description } : {}),
+        payload,
+    }, collectClauses(d));
+}
+// ── the document block (ask 2) ───────────────────────────────────────
+/**
+ * The publication edition the model corresponds to: the manifest's
+ * newest `editions` entry (the register is newest-first), the base
+ * URN's trailing year segment as fallback. NEVER the package version —
+ * the two fields answer different questions (edition steering vs
+ * freshness gating) and never borrow each other's value.
+ */
+function packageEdition(manifest) {
+    const first = manifest?.editions?.[0];
+    if (present(first)) {
+        return first;
+    }
+    const tail = /:(\d{4})$/.exec(manifest?.baseUrn ?? '');
+    return tail?.[1] ?? '';
+}
+function packageBlock(standard) {
+    const m = standard.packageManifest;
+    if (m) {
+        return {
+            id: m.id,
+            title: m.title,
+            kind: m.kind ?? 'rec',
+            edition: packageEdition(m),
+            model_version: m.version,
+            editions: [...(m.editions ?? [])],
+            base_urn: m.baseUrn,
+            ...(present(m.status) ? { status: m.status } : {}),
+            default_spelling: m.defaultSpelling ?? '',
+            spellings: [
+                ...(m.spellings ?? (m.defaultSpelling ? [m.defaultSpelling] : [])),
+            ],
+            ...(presentList(m.supersedes) ? { supersedes: [...m.supersedes] } : {}),
+        };
+    }
+    // A manifestless Standard (a single-file load): the metadata header
+    // carries what the manifest would.
+    const meta = standard.meta;
+    return {
+        id: meta?.namespace ?? '',
+        title: meta?.title ?? '',
+        kind: '',
+        edition: meta?.edition ?? '',
+        model_version: '',
+        editions: present(meta?.edition) ? [meta.edition] : [],
+        base_urn: '',
+        default_spelling: '',
+        spellings: [],
+    };
+}
+/**
+ * Project a loaded Standard into the retrieval document (pure — no I/O;
+ * the id projection, the clause normalization, the digests).
+ */
+function exportStandardRetrieval(standard, options = {}) {
+    const pkg = packageBlock(standard);
+    // Build the unit contents paired with the KERNEL element id — the
+    // address a `text` block targets (a term's variants address
+    // `frobnicator`, not the namespaced unit id `/term/frobnicator`).
+    const built = [];
+    const push = (content, elementId) => {
+        built.push({ content, elementId });
+    };
+    for (const r of standard.requirements ?? []) {
+        push(requirementUnit(r), r.id);
+    }
+    for (const t of standard.conformanceTests ?? []) {
+        push(conformanceTestUnit(t), t.id);
+    }
+    for (const t of standard.terms ?? []) {
+        push(termUnit(t, pkg.base_urn), t.id);
+    }
+    for (const a of standard.attributeDefinitions ?? []) {
+        push(attributeUnit(a), a.id);
+    }
+    for (const b of standard.behaviors ?? []) {
+        push(behaviorUnit(b), b.id);
+    }
+    for (const c of standard.calculations ?? []) {
+        // The kernel element id is the construct id (`calculation frobIndex`),
+        // never the declared `identifier` path the unit id prefers.
+        push(calculationUnit(c), c.id);
+    }
+    for (const s of standard.symbols ?? []) {
+        push(symbolUnit(s), s.id);
+    }
+    for (const c of standard.constraints ?? []) {
+        push(constraintUnit(c), c.id);
+    }
+    for (const v of standard.verdicts ?? []) {
+        push(characteristicUnit(v), v.id);
+    }
+    for (const t of standard.tables ?? []) {
+        push(tableUnit(t), t.id);
+    }
+    for (const s of standard.testSequences ?? []) {
+        push(sequenceUnit(s), s.id);
+    }
+    for (const n of standard.notes ?? []) {
+        push(noteUnit(n), n.id);
+    }
+    for (const m of standard.stateMachines ?? []) {
+        // The construct declares no id (the unit keys by the bound entity's
+        // name) — C89 registers nothing, so no text block can address it.
+        push(stateMachineUnit(m), m.entityName);
+    }
+    for (const i of standard.instruments ?? []) {
+        for (const d of i.dimensions ?? []) {
+            // Dimensions nest under the instrument in the C89 registry — a
+            // text block addresses them by path through the instrument, which
+            // the projection does not ship as a unit: those blocks count as
+            // dropped, never misattached.
+            push(dimensionUnit(d), d.id);
+        }
+    }
+    // The language tag + variants attach pre-digest (authored content —
+    // they move the content_hash like any authored field).
+    const droppedTextBlocks = attachVariants(built, standard, pkg);
+    const units = built.map(b => completeUnit(b.content, pkg));
+    const byKind = {};
+    let withClause = 0;
+    let anchorOnlyProvenance = 0;
+    let nonUrnDocRefs = 0;
+    let withoutProvenance = 0;
+    let withVariants = 0;
+    for (const u of units) {
+        byKind[u.kind] = (byKind[u.kind] ?? 0) + 1;
+        if (u.variants && Object.keys(u.variants).length > 0) {
+            withVariants++;
+        }
+        const clauses = u.clauses ?? [];
+        if (clauses.some(c => c.clause)) {
+            withClause++;
+        }
+        else if (clauses.length > 0) {
+            anchorOnlyProvenance++;
+        }
+        else {
+            withoutProvenance++;
+        }
+        if (clauses.some(c => c.doc && !c.doc.startsWith('urn:'))) {
+            nonUrnDocRefs++;
+        }
+    }
+    const document = {
+        projection: exports.RETRIEVAL_PROJECTION,
+        facet_version: exports.RETRIEVAL_FACET_VERSION,
+        package: pkg,
+        ...(options.sourceHash !== undefined
+            ? { source_hash: options.sourceHash }
+            : {}),
+        units,
+    };
+    return {
+        document,
+        json: JSON.stringify(sortDeep(document), null, 2) + '\n',
+        stats: {
+            units: units.length,
+            byKind,
+            withClause,
+            anchorOnlyProvenance,
+            nonUrnDocRefs,
+            withoutProvenance,
+            withVariants,
+            droppedTextBlocks,
+        },
+    };
+}
+/**
+ * Export a package directory: load, hash the package bytes (the bundle
+ * freshness signal — the deployed consumer's exact algorithm), project.
+ */
+function exportPackageRetrieval(dir) {
+    const { standard } = (0, package_1.loadPackageWithIssues)(dir);
+    return exportStandardRetrieval(standard, {
+        sourceHash: packageSourceHash(dir),
+    });
+}
+//# sourceMappingURL=retrieval.js.map