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

package/dist/lib/catalogue/ddl-generator.js

@@ -0,0 +1,233 @@
+/**
+ * Schema→DDL generator — M-ADR 0205 §4.3 (engine-evolution Phase A1).
+ *
+ * Emits, from the loaded canonical schema:
+ *   (a) CREATE TABLE DDL for every declared catalogue, typed per the
+ *       schema's column types; and
+ *   (b) a deterministic list of constraint-violation queries (fk | pk |
+ *       enum) whose row semantics mirror fk-validator.ts and
+ *       enum-validator.ts EXACTLY — the Phase A2 dual-run comparison
+ *       (old path vs engine path, count AND list) depends on that
+ *       equivalence, so any semantic change here must change there too:
+ *         - fk: a required (non-nullable, non-external) FK fails when
+ *           empty; a non-empty value must resolve against the target
+ *           catalogue's primary keys unless the FK is effective-external
+ *           (declared `external`, or external for the build's profile via
+ *           `externalForProfiles`) — mirroring FkValidationOptions.
+ *         - pk: duplicate non-empty primary-key values.
+ *         - enum: a non-empty (trimmed) bound-column value outside the
+ *           bound enum's declared set. Emptiness is nullability's concern,
+ *           not the enum's, exactly as in enum-validator.ts.
+ *
+ * Determinism per M-ADR 0205 §4.2: emission order is the schema's own
+ * declaration order; every query carries a total ORDER BY.
+ *
+ * Digest coupling per §4.3 is inherited, not re-implemented: this module
+ * reads the schema through loadCanonicalSchema, and the vendored copy it
+ * loads is guarded by canonical-schema-drift.test.ts.
+ *
+ * There is NO hand-maintained DDL anywhere: an unknown column type or a
+ * binding to an unknown enum throws at generation time — loud, never a
+ * silent fallback (the known*Ids.has() lesson).
+ */
+import { PLATFORM_STAMP_COLUMN, isPlatformScopedFk } from "./fk-validator.js";
+/** Closed map from schema column types to engine column types. */
+const TYPE_MAP = {
+    string: "VARCHAR",
+    int: "INTEGER",
+    integer: "INTEGER",
+    number: "DOUBLE",
+    date: "DATE",
+    boolean: "BOOLEAN",
+};
+/** Engine type for a schema column type; throws on an unmapped type. */
+export function sqlType(catalogue, column, type) {
+    const mapped = TYPE_MAP[type];
+    if (!mapped) {
+        throw new Error(`ddl-generator: ${catalogue}.${column} declares unmapped column type "${type}" — extend TYPE_MAP deliberately, never default`);
+    }
+    return mapped;
+}
+/**
+ * The one definition of effective-external, shared with the engine
+ * validator so the three consumers (fk-validator.ts, the query generator,
+ * engine-validator.ts) cannot drift: declared `external`, or external for
+ * the build's profile via `externalForProfiles`.
+ */
+export function isEffectiveExternal(fk, options) {
+    return (fk.external ||
+        (options.profile !== undefined &&
+            (fk.externalForProfiles ?? []).includes(options.profile)));
+}
+function quote(identifier) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(identifier)) {
+        throw new Error(`ddl-generator: identifier "${identifier}" is outside the schema's naming form — refusing to interpolate it into SQL`);
+    }
+    return `"${identifier}"`;
+}
+function sqlStringLiteral(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/**
+ * One CREATE TABLE statement per catalogue, in schema declaration order.
+ * Plain typed columns only: enforcement of PK/FK/enum semantics lives in
+ * the violation queries, whose findings-shaped output (never a load
+ * abort) is what the validators' exit contracts need.
+ */
+export function generateTableDdl(schema) {
+    return schema.catalogues.map((cat) => {
+        const cols = cat.columns
+            .map((c) => `  ${quote(c.name)} ${sqlType(cat.name, c.name, c.type)}`)
+            .join(",\n");
+        return `CREATE TABLE ${quote(cat.name)} (\n${cols}\n);`;
+    });
+}
+/**
+ * The violation-query set for a schema, mirroring the in-memory
+ * validators' semantics under the same options they take.
+ */
+export function generateConstraintQueries(schema, options = {}) {
+    const catalogueNames = new Set(schema.catalogues.map((c) => c.name));
+    const queries = [];
+    const catByName = new Map(schema.catalogues.map((c) => [c.name, c]));
+    for (const cat of schema.catalogues) {
+        queries.push(pkQuery(cat, options));
+        for (const fk of cat.foreignKeys) {
+            const [targetCat, targetCol] = fk.references.split(".");
+            if (!targetCat || !targetCol) {
+                throw new Error(`ddl-generator: malformed FK reference "${fk.references}" on ${cat.name}.${fk.column}`);
+            }
+            if (!catalogueNames.has(targetCat)) {
+                throw new Error(`ddl-generator: FK ${cat.name}.${fk.column} references unknown catalogue "${targetCat}"`);
+            }
+            if (!cat.columns.some((c) => c.name === fk.column)) {
+                throw new Error(`ddl-generator: FK column ${cat.name}.${fk.column} is not a declared column — the schema 3.1.3 vacuous-binding class`);
+            }
+            const effectiveExternal = isEffectiveExternal(fk, options);
+            // Mirrors fk-validator.ts exactly: the required-empty clause is keyed
+            // on the DECLARED external flag; the dangling clause is keyed on
+            // effective-external (unless the aggregator asks for internal
+            // treatment).
+            const checkEmpty = !fk.nullable && !fk.external;
+            const checkDangling = !effectiveExternal || options.treatExternalAsInternal === true;
+            if (!checkEmpty && !checkDangling)
+                continue;
+            const t = quote(cat.name);
+            const col = quote(fk.column);
+            const pk = quote(cat.primaryKey);
+            const clauses = [];
+            if (checkEmpty) {
+                clauses.push(`(t.${col} IS NULL OR t.${col} = '')`);
+            }
+            if (checkDangling) {
+                // M-ADR 0208 §4.4 (F-D): a platform-scoped target resolves on
+                // (platform_sdd_id, pk) — equal stamps, or either side unstamped.
+                // Mirrors fk-validator.ts's `resolved` predicate exactly.
+                const stamp = quote(PLATFORM_STAMP_COLUMN);
+                const scope = isPlatformScopedFk(cat, catByName.get(targetCat), options)
+                    ? ` AND (COALESCE(t.${stamp}, '') = '' OR COALESCE(r.${stamp}, '') = '' OR r.${stamp} = t.${stamp})`
+                    : "";
+                clauses.push(`(t.${col} IS NOT NULL AND t.${col} <> '' AND NOT EXISTS (` +
+                    `SELECT 1 FROM ${quote(targetCat)} r WHERE r.${quote(targetCol)} = t.${col}${scope}))`);
+            }
+            queries.push({
+                catalogue: cat.name,
+                kind: "fk",
+                column: fk.column,
+                target: fk.references,
+                sql: `SELECT t.${pk} AS row_pk, COALESCE(t.${col}, '') AS value FROM ${t} t ` +
+                    `WHERE ${clauses.join(" OR ")} ORDER BY row_pk, value;`,
+            });
+        }
+        for (const [column, enumRef] of Object.entries(cat.columnEnums)) {
+            const enumName = enumRef.replace(/^enums\./, "");
+            const enumDef = schema.enums[enumName];
+            if (!enumDef) {
+                throw new Error(`ddl-generator: ${cat.name}.${column} binds unknown enum "${enumRef}" — a binding that names no enum must not validate as vacuously true`);
+            }
+            if (!cat.columns.some((c) => c.name === column)) {
+                throw new Error(`ddl-generator: ${cat.name}.${column} binds a column the catalogue does not declare — the schema 3.1.3 vacuous-binding class`);
+            }
+            const allowed = enumDef.values
+                .map((v) => sqlStringLiteral(v.value))
+                .join(", ");
+            const t = quote(cat.name);
+            const col = quote(column);
+            const pk = quote(cat.primaryKey);
+            queries.push({
+                catalogue: cat.name,
+                kind: "enum",
+                column,
+                target: enumName,
+                sql: 
+                // TRIM in the projection too: enum-validator.ts records the
+                // TRIMMED value in its violation objects, and A2's count-and-list
+                // parity compares those objects field-for-field.
+                `SELECT t.${pk} AS row_pk, TRIM(t.${col}) AS value FROM ${t} t ` +
+                    `WHERE t.${col} IS NOT NULL AND TRIM(t.${col}) <> '' ` +
+                    `AND TRIM(t.${col}) NOT IN (${allowed}) ORDER BY row_pk, value;`,
+            });
+        }
+    }
+    return queries;
+}
+/**
+ * Dangling-value queries for the FKs the main set SKIPS as
+ * effective-external — one query per skipped FK, returning the rows the
+ * in-memory path logs as `[finding] external` (unresolved non-empty
+ * values; resolution happens at aggregation). Empty when
+ * treatExternalAsInternal is set, exactly as the main set then skips
+ * nothing. Kept separate from generateConstraintQueries because these
+ * rows are FINDINGS, not failures — the exit contracts differ.
+ */
+export function generateExternalFindingQueries(schema, options = {}) {
+    if (options.treatExternalAsInternal === true)
+        return [];
+    const queries = [];
+    for (const cat of schema.catalogues) {
+        for (const fk of cat.foreignKeys) {
+            if (!isEffectiveExternal(fk, options))
+                continue;
+            const [targetCat, targetCol] = fk.references.split(".");
+            if (!targetCat || !targetCol) {
+                throw new Error(`ddl-generator: malformed FK reference "${fk.references}" on ${cat.name}.${fk.column}`);
+            }
+            const t = quote(cat.name);
+            const col = quote(fk.column);
+            const pk = quote(cat.primaryKey);
+            queries.push({
+                catalogue: cat.name,
+                kind: "fk",
+                column: fk.column,
+                target: fk.references,
+                sql: `SELECT t.${pk} AS row_pk, t.${col} AS value FROM ${t} t ` +
+                    `WHERE t.${col} IS NOT NULL AND t.${col} <> '' AND NOT EXISTS (` +
+                    `SELECT 1 FROM ${quote(targetCat)} r WHERE r.${quote(targetCol)} = t.${col}) ` +
+                    `ORDER BY row_pk, value;`,
+            });
+        }
+    }
+    return queries;
+}
+function pkQuery(cat, options = {}) {
+    const t = quote(cat.name);
+    const pk = quote(cat.primaryKey);
+    // M-ADR 0208 §4.4 (F-D): for a platform-scoped catalogue the key is
+    // (platform_sdd_id, pk). n rows sharing a pk are distinct iff every one
+    // carries a stamp and the stamps are all different — an EMPTY stamp is
+    // unresolved, never a key, so it collides with everything. Mirrors
+    // aggregate.ts findDuplicatePrimaryKeys.
+    const scoped = isPlatformScopedFk(cat, cat, options);
+    const having = scoped
+        ? `HAVING COUNT(*) > COUNT(DISTINCT NULLIF(${quote(PLATFORM_STAMP_COLUMN)}, ''))`
+        : `HAVING COUNT(*) > 1`;
+    return {
+        catalogue: cat.name,
+        kind: "pk",
+        column: cat.primaryKey,
+        sql: `SELECT ${pk} AS row_pk, COUNT(*) AS n FROM ${t} ` +
+            `WHERE ${pk} IS NOT NULL AND ${pk} <> '' ` +
+            `GROUP BY ${pk} ${having} ORDER BY row_pk;`,
+    };
+}
+//# sourceMappingURL=ddl-generator.js.map

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