@sdd-method/author-cli 0.0.0-stage → 0.1.0

package/dist/lib/catalogue/engine-validator.js

@@ -0,0 +1,239 @@
+/**
+ * Engine-path FK/PK/enum validation — M-ADR 0205 §4.4 (Phase A2).
+ *
+ * Runs the ddl-generator's queries on the embedded engine and returns
+ * results in the SAME shapes as fk-validator.ts / enum-validator.ts, so
+ * the parity harness can compare count AND list, field for field. The
+ * input is the same rowsByCatalogue map the in-memory validators take:
+ * A2 compares the two VALIDATION implementations on identical parsed
+ * input — CSV-read equivalence is deliberately out of this comparison's
+ * scope and belongs to the cutover evaluation.
+ *
+ * The engine package is a devDependency until cutover (M-ADR 0205 §4.1's
+ * no-fallback rule governs how it eventually ships). It is imported
+ * dynamically inside the entry function so merely loading this module
+ * never requires it: no production path imports the engine today, and an
+ * adopter install without the package only fails if something actually
+ * calls it — loudly.
+ *
+ * PK-duplicate detection has NO in-memory counterpart at validate time
+ * (builders dedupe at emission instead), so pkDuplicates is engine-only
+ * information: reported, never part of the parity claim — you cannot
+ * claim agreement with an instrument that does not exist.
+ */
+import { generateConstraintQueries, generateExternalFindingQueries, generateTableDdl, sqlType, } from "./ddl-generator.js";
+const INSERT_CHUNK = 500;
+function sqlStringLiteral(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/**
+ * One loaded engine: schema DDL applied, every provided catalogue's rows
+ * inserted. Shared by the FK/PK/enum path and the coverage predicates so
+ * there is exactly one load semantics to reason about.
+ */
+export async function createEngineSession(schema, rowsByCatalogue) {
+    const { DuckDBInstance } = await import("@duckdb/node-api");
+    const instance = await DuckDBInstance.create(":memory:");
+    const conn = await instance.connect();
+    for (const ddl of generateTableDdl(schema)) {
+        await conn.run(ddl);
+    }
+    await loadRows(conn, schema, rowsByCatalogue);
+    return { conn, dispose: () => conn.disconnectSync() };
+}
+// @rule engine-fk-validation
+export async function validateWithEngine(schema, rowsByCatalogue, options = {}) {
+    const session = await createEngineSession(schema, rowsByCatalogue);
+    const conn = session.conn;
+    try {
+        const typeNonconformances = await findTypeNonconformances(conn, schema, rowsByCatalogue);
+        const failures = [];
+        const enumViolations = [];
+        const pkDuplicates = [];
+        for (const q of generateConstraintQueries(schema, options)) {
+            const reader = await conn.runAndReadAll(q.sql);
+            for (const row of reader.getRows()) {
+                if (q.kind === "fk") {
+                    failures.push({
+                        catalogue: q.catalogue,
+                        column: q.column,
+                        referencingRow: String(row[0] ?? ""),
+                        value: String(row[1] ?? ""),
+                        target: q.target,
+                    });
+                }
+                else if (q.kind === "enum") {
+                    const enumDef = schema.enums[q.target];
+                    enumViolations.push({
+                        catalogue: q.catalogue,
+                        column: q.column,
+                        rowPk: row[0] === null || row[0] === undefined ? "<no-pk>" : String(row[0]),
+                        value: String(row[1] ?? ""),
+                        allowed: enumDef.values.map((v) => v.value).join(" | "),
+                    });
+                }
+                else {
+                    pkDuplicates.push({
+                        catalogue: q.catalogue,
+                        rowPk: String(row[0] ?? ""),
+                        count: Number(row[1]),
+                    });
+                }
+            }
+        }
+        const externalFindingDetails = [];
+        for (const q of generateExternalFindingQueries(schema, options)) {
+            const reader = await conn.runAndReadAll(q.sql);
+            for (const row of reader.getRows()) {
+                externalFindingDetails.push({
+                    catalogue: q.catalogue,
+                    column: q.column,
+                    target: q.target,
+                    rowPk: row[0] === null || row[0] === undefined ? "?" : String(row[0]),
+                    value: String(row[1] ?? ""),
+                });
+            }
+        }
+        return {
+            fk: {
+                internalPass: failures.length === 0,
+                internalFailures: failures,
+                externalFindings: externalFindingDetails.length,
+            },
+            enums: { pass: enumViolations.length === 0, violations: enumViolations },
+            externalFindingDetails,
+            pkDuplicates,
+            typeNonconformances,
+        };
+    }
+    finally {
+        session.dispose();
+    }
+}
+/**
+ * The A4 cutover surface: runs the engine validation and writes findings
+ * into the caller's FindingsLog with BYTE-IDENTICAL text to what
+ * fk-validator.ts / enum-validator.ts wrote — adopters' committed
+ * findings baselines hold those literal lines, so the text is a
+ * compatibility contract, not a style choice. Line ORDER within a
+ * category follows the engine's total ORDER BY (M-ADR 0205 §4.2) and may
+ * differ from the old file-order rendering; baselines compare by
+ * membership, so ordering is free — declared in the change-set anyway.
+ */
+export async function validateWithEngineToLog(schema, rowsByCatalogue, findings, options = {}, extras = {}) {
+    const logEnumFindings = extras.logEnumFindings !== false;
+    const res = await validateWithEngine(schema, rowsByCatalogue, options);
+    for (const d of res.externalFindingDetails) {
+        findings.add("external", `${d.catalogue}.${d.column} → ${d.target}=${d.value} ` +
+            `(referencing row pk=${d.rowPk}; resolves at aggregation)`);
+    }
+    if (logEnumFindings) {
+        const enumNameByCatalogueColumn = new Map();
+        for (const cat of schema.catalogues) {
+            for (const [column, enumRef] of Object.entries(cat.columnEnums)) {
+                enumNameByCatalogueColumn.set(`${cat.name}.${column}`, enumRef.replace(/^enums\./, ""));
+            }
+        }
+        for (const v of res.enums.violations) {
+            const enumName = enumNameByCatalogueColumn.get(`${v.catalogue}.${v.column}`);
+            findings.add("divergence", `${v.catalogue}.${v.column}: row ${v.rowPk} value "${v.value}" is outside the bound enum ${enumName} (${v.allowed})`, "error");
+        }
+    }
+    return { fk: res.fk, enums: res.enums };
+}
+async function loadRows(conn, schema, rowsByCatalogue) {
+    for (const cat of schema.catalogues) {
+        const rows = rowsByCatalogue.get(cat.name) ?? [];
+        if (rows.length === 0)
+            continue;
+        for (let i = 0; i < rows.length; i += INSERT_CHUNK) {
+            const chunk = rows.slice(i, i + INSERT_CHUNK);
+            const tuples = chunk
+                .map((row) => `(${cat.columns
+                .map((c) => literal(row[c.name], cat.name, c.name, c.type))
+                .join(", ")})`)
+                .join(",\n");
+            await conn.run(`INSERT INTO "${cat.name}" VALUES\n${tuples};`);
+        }
+    }
+}
+/**
+ * Renders one cell. String columns keep the empty string AS an empty
+ * string — the in-memory validators' emptiness predicates see '' from the
+ * CSV reader, and the generated queries test both NULL and ''. Non-string
+ * columns TRY_CAST with '' becoming NULL: one uncastable cell must not
+ * abort a whole run (measured on a real estate: a prose value in a
+ * date-typed column), and the miss is not smoothed either —
+ * findTypeNonconformances re-derives every such cell with the engine's
+ * own cast semantics and reports it.
+ */
+function literal(value, catalogue, column, type) {
+    const s = value === null || value === undefined ? "" : String(value);
+    if (type === "string")
+        return sqlStringLiteral(s);
+    if (s === "")
+        return "NULL";
+    return `TRY_CAST(${sqlStringLiteral(s)} AS ${sqlType(catalogue, column, type)})`;
+}
+/**
+ * Exact engine-semantics detection of the cells TRY_CAST nulled: the
+ * distinct non-empty values of every typed column are re-checked with the
+ * SAME cast the load used — a JS re-implementation of the engine's parsers
+ * would be a second opinion pretending to be the first.
+ */
+async function findTypeNonconformances(conn, schema, rowsByCatalogue) {
+    const out = [];
+    for (const cat of schema.catalogues) {
+        const rows = rowsByCatalogue.get(cat.name) ?? [];
+        if (rows.length === 0)
+            continue;
+        for (const col of cat.columns) {
+            if (col.type === "string")
+                continue;
+            const counts = new Map();
+            for (const row of rows) {
+                const v = row[col.name];
+                const s = v === null || v === undefined ? "" : String(v);
+                if (s === "")
+                    continue;
+                counts.set(s, (counts.get(s) ?? 0) + 1);
+            }
+            if (counts.size === 0)
+                continue;
+            const engineType = sqlType(cat.name, col.name, col.type);
+            const values = [...counts.keys()].sort();
+            const tuples = values.map((v) => `(${sqlStringLiteral(v)})`).join(", ");
+            const reader = await conn.runAndReadAll(`SELECT v FROM (VALUES ${tuples}) t(v) ` +
+                `WHERE TRY_CAST(v AS ${engineType}) IS NULL ORDER BY v;`);
+            for (const row of reader.getRows()) {
+                const value = String(row[0]);
+                out.push({
+                    catalogue: cat.name,
+                    column: col.name,
+                    declaredType: col.type,
+                    value,
+                    rows: counts.get(value) ?? 0,
+                });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * The population a PASS was measured over, for the verdict line. An FK or enum
+ * PASS over zero rows is true of nothing (empty-set sweep, R2): the count makes
+ * the zero visible. The `PASS` token itself is kept for anything that greps it.
+ */
+export function validatedPopulation(rowsByCatalogue) {
+    let rows = 0;
+    let nonEmpty = 0;
+    for (const r of rowsByCatalogue.values()) {
+        rows += r.length;
+        if (r.length > 0)
+            nonEmpty += 1;
+    }
+    return rows === 0
+        ? "0 rows — nothing was validated"
+        : `${rows} row(s) across ${nonEmpty} non-empty catalogue(s)`;
+}
+//# sourceMappingURL=engine-validator.js.map

package/dist/lib/catalogue/ext-id.js

@@ -0,0 +1,76 @@
+// External-system row identity (schema 3.0.0) and the legacy-id migration
+// map — M-ADR 0203 §4.2, completing M-ADR 0189 §4.2.
+//
+// From 3.0.0 a `c4_external_systems` row id derives from the DECLARED
+// diagram entry id (`System_Ext(<entry-id>, …)`), not from a slug of the
+// display name. The declared id is the identity the aggregator resolves
+// (M-ADR 0189 §4.2); keying the row on anything else meant the row's own
+// PK was label-keyed evidence — the exact identity class 0189 measured
+// false-positiving at 14 of 15.
+//
+// The 2.x name-slug ids remain derivable from data every 2.30.0+ catalogue
+// carries (`name`), so the old→new map is a build artefact, not an authored
+// migration: `sdd-cli catalogue migration-map` emits it, and the exemption
+// loader consults it during the cut window (an authored exemption keyed by
+// a mapped old id is regenerable, NOT drift — the F30 rule at schema scale).
+/**
+ * Normalise a declared diagram entry id to slug form. Camel humps split
+ * BEFORE lowercasing (the F11a rule, matching the aggregator's resolver):
+ * most SDD ids are hyphenated, and `bvfmGatewayFramework` must derive the
+ * same identity the adjudicator resolves for it (`bvfm-gateway-framework`).
+ */
+export function normaliseEntryId(entryId) {
+    return entryId
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/** The 3.0.0 row id for a declared diagram entry id, or "" when the entry id normalises to nothing. */
+export function extIdFromEntryId(entryId) {
+    const slug = normaliseEntryId(entryId);
+    return slug === "" ? "" : `ext-${slug}`;
+}
+/**
+ * The 2.x row id for a display name — the pre-3.0.0 derivation, kept
+ * VERBATIM (including the parenthetical strip) so the migration map
+ * reproduces exactly the ids the old builder minted.
+ */
+export function legacyExtIdFromName(name) {
+    const slug = name
+        .toLowerCase()
+        .replace(/\s*\([^)]+\)/g, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return slug === "" ? "" : `ext-${slug}`;
+}
+/**
+ * legacy (2.x, name-derived) id → the 3.0.0 ids it maps to, from built
+ * rows. Usually one; MORE than one means two distinct declared identities
+ * shared a display-name slug and were wrongly merged as one row under 2.x
+ * — the map surfaces the split rather than guessing (the consumer decides,
+ * loudly).
+ */
+export function buildLegacyExtIdMap(rows) {
+    const map = new Map();
+    for (const row of rows) {
+        const legacy = legacyExtIdFromName(String(row["name"] ?? ""));
+        if (legacy === "")
+            continue;
+        const current = String(row["id"] ?? "");
+        if (current === "" || legacy === current)
+            continue;
+        const ids = map.get(legacy);
+        if (ids) {
+            if (!ids.includes(current))
+                ids.push(current);
+        }
+        else {
+            map.set(legacy, [current]);
+        }
+    }
+    for (const ids of map.values())
+        ids.sort((a, b) => a.localeCompare(b));
+    return map;
+}
+//# sourceMappingURL=ext-id.js.map

package/dist/lib/catalogue/feature-grounding-aliases-loader.js

@@ -0,0 +1,65 @@
+/**
+ * Loader for the optional `.sdd/feature-grounding-aliases.yaml` config
+ * per ADR 0143 (schema 2.5.0).
+ *
+ * Adopters use this map to translate display names in
+ * `feature-grounding.md` tables (class names, file basenames, route
+ * fragments) into canonical service / repo ids that resolve against
+ * `services.csv` and `repositories.csv`. Follows the same shape
+ * convention as the existing capability_service alias map.
+ *
+ * File shape:
+ *
+ *     service_aliases:
+ *       AuthHandler: example-service-api
+ *       web-ui: example-web-ui
+ *     repo_aliases:
+ *       camera-bff: global-camera-bff
+ *
+ * Either block is optional. Empty / missing file = no aliases (every
+ * reference must resolve directly against the canonical id).
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+const ALIASES_FILENAME = join(".sdd", "feature-grounding-aliases.yaml");
+/**
+ * Load the optional alias map. Returns `null` when the file is absent
+ * — callers treat that as "no aliases, all references must resolve
+ * directly against the canonical id." Throws on malformed YAML.
+ */
+export async function loadFeatureGroundingAliases(sddPath) {
+    const full = join(sddPath, ALIASES_FILENAME);
+    let text;
+    try {
+        text = await readFile(full, "utf-8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return null;
+        throw err;
+    }
+    const raw = parseYaml(text);
+    if (raw === null || typeof raw !== "object") {
+        throw new Error(`${ALIASES_FILENAME}: expected a mapping at the document root`);
+    }
+    return {
+        serviceAliases: toStringMap(raw.service_aliases),
+        repoAliases: toStringMap(raw.repo_aliases),
+        relPath: ALIASES_FILENAME,
+    };
+}
+function toStringMap(raw) {
+    const out = new Map();
+    if (raw === null || raw === undefined)
+        return out;
+    if (typeof raw !== "object" || Array.isArray(raw))
+        return out;
+    for (const [k, v] of Object.entries(raw)) {
+        if (typeof v === "string" && v !== "")
+            out.set(k, v);
+    }
+    return out;
+}
+//# sourceMappingURL=feature-grounding-aliases-loader.js.map

package/dist/lib/catalogue/feature-repo-zero-resolution-summary.js

@@ -0,0 +1,31 @@
+/**
+ * feature_repo zero-resolution SUMMARY line (M-ADR 0143 §4.4), split against
+ * the final feature_repo table.
+ *
+ * A builder (feature-grounding: Evidence cell; capability-spec:
+ * Implementation cell) fires one per-row finding for every feature row whose
+ * cell is non-empty but resolves to zero repos. That measures the CELL. The
+ * feature may still be anchored by another surface — feature-tree
+ * `## Feature Services`, feature-spec, or the feature_service ⋈
+ * service_repo derivation — and only the build, holding the final
+ * feature_repo, can say so. The summary therefore states both numbers:
+ * how many rows fired, and how many of those fired on features that no
+ * surface anchors.
+ *
+ * Returns null when nothing fired: an absent line is the designed shape
+ * for zero (the per-row lines are absent too), and this keeps the finding
+ * surface identical to pre-1.20.2 in that case.
+ */
+export function zeroResolutionSummary(cellLabel, evidenceRows, firedFeatureIds, anchoredFeatures) {
+    if (firedFeatureIds.length === 0)
+        return null;
+    const distinctFired = new Set(firedFeatureIds);
+    const unanchoredFeatures = new Set([...distinctFired].filter((fid) => !anchoredFeatures.has(fid)));
+    const unanchoredRows = firedFeatureIds.filter((fid) => unanchoredFeatures.has(fid)).length;
+    const anchoredElsewhere = distinctFired.size - unanchoredFeatures.size;
+    return (`feature_repo: ${firedFeatureIds.length} of ${evidenceRows} feature rows with a non-empty ${cellLabel} cell resolved to zero repos, ` +
+        `of which ${unanchoredRows} on ${unanchoredFeatures.size} feature(s) with no anchor from ANY surface in the final feature_repo ` +
+        `(${anchoredElsewhere} of the ${distinctFired.size} named features are anchored by another surface — those rows are cell quality, not coverage) ` +
+        `(member tier; evidence→repo resolution coverage only — a resolved row is not thereby correct; M-ADR 0143 §4.4)`);
+}
+//# sourceMappingURL=feature-repo-zero-resolution-summary.js.map

package/dist/lib/catalogue/finding-identity.js

@@ -0,0 +1,183 @@
+/**
+ * Finding IDENTITY — the stable key a findings baseline is compared on, per
+ * M-ADR 0132 §4.3 as amended, delivering the ruling recorded at ledger §3p.
+ *
+ * THE PROBLEM THIS EXISTS FOR, measured rather than asserted. A findings
+ * baseline stores whole `[finding]` lines, so improving a message invalidates
+ * every baselined line carrying it. Wave №6 added a remedy sentence to one
+ * orphan message: 57 baselined lines went inert and 57 replacements arrived
+ * unbaselined, with ZERO genuinely new findings underneath. At the baseline, a
+ * wave that improves wording is indistinguishable from a wave that introduces
+ * 57 new problems. It recurred at wave №11 (9 lines, one estate) because the
+ * class was understood and the mechanism had not changed.
+ *
+ * WHY IDENTITY IS EMITTED AND NOT RECOVERED. The obvious cheaper fix is to let
+ * a comparator extract (category, subject) from stored lines and leave every
+ * estate file untouched. Measured across every baseline in both estates — 86
+ * files, 74 non-empty, 1,677 body lines — that works for 1,434 lines (85.5%)
+ * and fails for 243 (14.5%), which embed their subject in prose:
+ *
+ *   [finding] orphan: repo integration-calamp resolves to no capability ...
+ *
+ * One renderer template, all orphan class, spread across 62 repos. Recovering
+ * identity there means teaching the comparator the renderer's message
+ * templates — which re-couples identity to message text, the exact coupling
+ * this module removes, and fails SILENTLY the next time a template changes.
+ * Identity that was never emitted cannot be reconstructed from prose after the
+ * fact; it has to be emitted where it is known.
+ *
+ * THE RENDERED FORM keeps the identity in the line a human reads, because a
+ * baseline is reviewed by people and a side-channel nobody sees is a side
+ * channel nobody maintains:
+ *
+ *   [finding] orphan (repo:integration-calamp): repo integration-calamp ...
+ *   [finding] divergence (docs/domains/asset/product/x.traceability.yaml): ...
+ *
+ * A finding with no declared subject renders EXACTLY as it does today. That is
+ * deliberate and load-bearing: migration is per-emission-site rather than
+ * flag-day, an unmigrated site is unchanged rather than broken, and the size of
+ * an estate's re-take is proportional to how many sites have actually moved.
+ */
+/**
+ * A subject is `kind:id` where the finding knows the kind (`repo:x`,
+ * `capability:y`), or a repo-relative path where the subject IS a file. Both
+ * are stable under rewording; neither is a sentence.
+ *
+ * Parentheses are the delimiter because no subject may contain one — asserted
+ * below rather than assumed, since a subject that could contain the delimiter
+ * would make the parse ambiguous exactly when it mattered.
+ */
+export function assertRenderableSubject(subject) {
+    if (subject.includes("(") || subject.includes(")")) {
+        throw new Error(`finding subject may not contain parentheses (they delimit the identity): ${subject}`);
+    }
+    if (subject.trim() !== subject || subject === "") {
+        throw new Error(`finding subject must be non-empty and untrimmed-clean: '${subject}'`);
+    }
+}
+export function renderFindingLine(f) {
+    const err = f.severity === "error" ? " [error]" : "";
+    if (f.subject === undefined || f.subject === null) {
+        return `[finding] ${f.category}${err}: ${f.summary}`;
+    }
+    assertRenderableSubject(f.subject);
+    return `[finding] ${f.category}${err} (${f.subject}): ${f.summary}`;
+}
+const EXPLICIT = /^\[finding\] (\w+)(?: \[error\])? \(([^)]+)\): /;
+const LEGACY = /^\[finding\] (\w+)(?: \[error\])?: /;
+/**
+ * Recovers the identity of a stored baseline line.
+ *
+ * Three outcomes, and the third is the one that matters: an explicit identity
+ * is read exactly; a LEGACY line is keyed on its whole summary, which
+ * reproduces today's whole-line behaviour for lines that have not moved yet;
+ * and a line that is not a finding at all returns null.
+ *
+ * Keying a legacy line on its summary is not a silent approximation of
+ * identity — it IS the old contract, kept deliberately so an unmigrated line
+ * behaves exactly as it does now rather than matching something it should not.
+ */
+export function parseFindingLine(line) {
+    const m = EXPLICIT.exec(line);
+    if (m) {
+        return { identity: { category: m[1], subject: m[2] }, explicit: true };
+    }
+    const l = LEGACY.exec(line);
+    if (!l)
+        return null;
+    return {
+        identity: { category: l[1], subject: null },
+        explicit: false,
+    };
+}
+/**
+ * The comparison key. For an explicit identity that is (category, subject); for
+ * a legacy line it falls back to the whole line, preserving current behaviour.
+ */
+export function findingKey(line) {
+    const parsed = parseFindingLine(line);
+    if (!parsed)
+        return `raw\u0000${line}`;
+    if (parsed.identity.subject === null)
+        return `legacy\u0000${line}`;
+    return `id\u0000${parsed.identity.category}\u0000${parsed.identity.subject}`;
+}
+/**
+ * The MIGRATION BRIDGE: a live identity-carrying line with its identity token
+ * removed, which is byte-identical to how that same finding rendered before its
+ * emission site migrated.
+ *
+ * This is not inference. The token is exactly the ` (subject)` this module's own
+ * renderer inserts, and the summary either side of it is untouched — so removing
+ * it reconstructs the previous rendering deterministically, not plausibly.
+ *
+ * WHY IT EXISTS, measured on a real estate: a baseline dominated by findings
+ * from the FIRST migrated emission sites read 629 unbaselined / 380 closed / 0
+ * REWORDED — one closed and one new, which is the exact outcome §9 was written
+ * to prevent. The rewording bucket could not catch it because rewording is
+ * matched between two identity-carrying lines, and a pre-migration baseline has
+ * no identity on its side. The mechanism worked; the migration boundary sat
+ * underneath it, invisible to any estate whose baseline predates emission.
+ */
+export function strippedOfIdentity(line) {
+    const m = EXPLICIT.exec(line);
+    if (!m)
+        return null;
+    return line.replace(` (${m[2]})`, "");
+}
+/**
+ * Compares live findings against a baseline by identity.
+ *
+ * Only gate-acting categories belong in a baseline (M-ADR 0132 §4.3 — `orphan`
+ * and `divergence`); filtering is the caller's, because a comparator that
+ * silently dropped categories would make an empty result ambiguous between
+ * "nothing gate-acting" and "nothing at all".
+ */
+export function compareToBaseline(live, baseline) {
+    const baseByKey = new Map();
+    let legacyKeyed = 0;
+    for (const b of baseline) {
+        const key = findingKey(b);
+        if (key.startsWith("legacy\u0000") || key.startsWith("raw\u0000"))
+            legacyKeyed++;
+        // First occurrence wins; a baseline holding the same identity twice is a
+        // duplicate, and collapsing it here matches what a re-take does anyway.
+        if (!baseByKey.has(key))
+            baseByKey.set(key, b);
+    }
+    const unbaselined = [];
+    const reworded = [];
+    const matched = new Set();
+    let unchanged = 0;
+    for (const l of live) {
+        const key = findingKey(l);
+        let b = baseByKey.get(key);
+        if (b === undefined) {
+            // MIGRATION BRIDGE: before calling a finding new, ask whether this is the
+            // same finding wearing its pre-migration rendering. Exact match on the
+            // stripped form only — never a fuzzy one.
+            const stripped = strippedOfIdentity(l);
+            if (stripped !== null) {
+                const legacyKey = findingKey(stripped);
+                const legacyMatch = baseByKey.get(legacyKey);
+                if (legacyMatch !== undefined) {
+                    matched.add(legacyKey);
+                    reworded.push({ baseline: legacyMatch, live: l });
+                    continue;
+                }
+            }
+            unbaselined.push(l);
+            continue;
+        }
+        matched.add(key);
+        if (b === l)
+            unchanged++;
+        else
+            reworded.push({ baseline: b, live: l });
+    }
+    const stale = [...baseByKey.entries()]
+        .filter(([k]) => !matched.has(k))
+        .map(([, v]) => v);
+    return { unbaselined, stale, reworded, unchanged, legacyKeyed };
+}
+//# sourceMappingURL=finding-identity.js.map

package/dist/lib/catalogue/findings.js

@@ -0,0 +1,46 @@
+/**
+ * Findings collector for the canonical builder per ADR 0134 / builder-spec
+ * §"Emit findings as it parses".
+ *
+ * Findings are human-readable AND machine-parseable. Format per finding:
+ *   [finding] {category}: {one-line summary}
+ *
+ * Categories are an open set; the canonical catalogue is in the builder
+ * spec. This module hardcodes the well-known ones for type safety; new
+ * categories may be passed as freeform strings if they emerge.
+ */
+import { renderFindingLine } from "./finding-identity.js";
+export class FindingsLog {
+    findings = [];
+    add(category, summary, severity = "warn", subject) {
+        // Spread rather than an explicit `subject: undefined`, which
+        // exactOptionalPropertyTypes rejects — an absent subject and a subject
+        // whose value is undefined are different things here, and the type is
+        // right to insist on the distinction.
+        this.findings.push({
+            category,
+            summary,
+            severity,
+            ...(subject === undefined ? {} : { subject }),
+        });
+    }
+    /** Returns a copy of recorded findings, in insertion order. */
+    all() {
+        return [...this.findings];
+    }
+    /** Count findings, optionally filtered to a single category. */
+    count(category) {
+        if (category === undefined)
+            return this.findings.length;
+        return this.findings.filter((f) => f.category === category).length;
+    }
+    /** Count error-severity findings (these fail the build by default). */
+    errorCount() {
+        return this.findings.filter((f) => f.severity === "error").length;
+    }
+    /** Render every finding as a stdout line. Error-severity findings are marked. */
+    render() {
+        return this.findings.map((f) => renderFindingLine(f)).join("\n");
+    }
+}
+//# sourceMappingURL=findings.js.map