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

package/dist/lib/catalogue/coverage-run.js

@@ -0,0 +1,115 @@
+/**
+ * Coverage mode — `sdd-cli catalogue validate --coverage` (A4 CS-2).
+ *
+ * Runs the thirteen engine coverage predicates against a catalogues
+ * directory and prints EXACTLY the lines the reference shell scripts
+ * printed (coverage-render.ts holds the text contract), in a fixed block
+ * order: the four catalogue-classics (repo-capability, service-capability,
+ * event, contract), then the nine Phase-0 gate checks in the
+ * catalogue-integrity-gate's step order. Nothing else is written to
+ * stdout — the gate swaps N script invocations for one CLI call and the
+ * stream stays parseable by the same baseline machinery.
+ *
+ * Exit code is 0 in normal operation, exactly as the reference scripts:
+ * gating is the findings baseline's job, never this mode's. A classifier
+ * probe failure throws (the references exit 2).
+ *
+ * The one deliberately-unported check is check-repo-config-coverage.sh:
+ * it reads the AUTHORING surface, is text-shaped by design (A0's
+ * classification), and stays shell.
+ */
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { readCatalogueCsv } from "./csv-reader.js";
+import { createEngineSession } from "./engine-validator.js";
+import { loadCanonicalSchema } from "./schema-loader.js";
+import { runContractCoverage, runEventCoverage, runRepoCapabilityCoverage, runServiceCapabilityCoverage, } from "./coverage-predicates.js";
+import { runCapabilityEventCheck, runDataModelEntitiesCheck, runEventCatalogueCheck, runFeatureEventCheck, runFeatureSpecPromotionCheck, runFeatureSurfaceDuplicationCheck, runGlossaryXrefCheck, runPlatformDependenciesCheck, runRelationshipCoherenceCheck, runRepoEdgesCheck, } from "./gate-checks.js";
+import { runScoresCoverage } from "./scores-coverage.js";
+import { renderScaffoldDelta, runScaffoldDelta } from "./scaffold-delta.js";
+import { renderStalenessVerdicts, runStalenessVerdicts } from "./staleness-verdicts.js";
+import { renderCapabilityEventCheck, renderContractCoverage, renderDataModelEntitiesCheck, renderEventCatalogueCheck, renderEventCoverage, renderFeatureEventCheck, renderFeatureSpecPromotionCheck, renderFeatureSurfaceDuplicationCheck, renderGlossaryXrefCheck, renderPlatformDependenciesCheck, renderRelationshipCoherenceCheck, renderRepoCapability, renderRepoEdgesCheck, renderScoresCoverage, renderServiceCapability, } from "./coverage-render.js";
+export async function runCatalogueCoverage(inputs, write) {
+    const sddRoot = resolve(inputs.sddPath ?? process.cwd());
+    const dir = resolve(sddRoot, inputs.cataloguesDir ?? "catalogues");
+    const tier = inputs.tier ?? "member";
+    const schema = await loadCanonicalSchema();
+    const present = (name) => existsSync(join(dir, `${name}.csv`));
+    const rowsByCatalogue = new Map();
+    for (const cat of schema.catalogues) {
+        if (!present(cat.name))
+            continue;
+        const parsed = await readCatalogueCsv(join(dir, `${cat.name}.csv`));
+        rowsByCatalogue.set(cat.name, parsed.rows);
+    }
+    const session = await createEngineSession(schema, rowsByCatalogue);
+    const lines = [];
+    try {
+        // The four catalogue-classics, each anchored on its population file
+        // exactly as the reference scripts anchor (absent file → silent).
+        if (present("repositories")) {
+            const r = await runRepoCapabilityCoverage(session);
+            lines.push(...renderRepoCapability(r.findings, r.metrics));
+        }
+        if (present("services")) {
+            const r = await runServiceCapabilityCoverage(session, {
+                tier,
+                repoCapabilityAvailable: present("repo_capability"),
+            });
+            lines.push(...renderServiceCapability(r.findings, r.metrics, tier));
+        }
+        if (present("events")) {
+            const r = await runEventCoverage(session, { tier });
+            lines.push(...renderEventCoverage(r, tier));
+        }
+        if (present("contracts")) {
+            const r = await runContractCoverage(session, { tier, sddRoot });
+            lines.push(...renderContractCoverage(r, tier));
+        }
+        // The nine Phase-0 gate checks, in the gate's step order.
+        const eventCatalogue = await runEventCatalogueCheck(session, {
+            sddRoot,
+            eventsPresent: present("events"),
+        });
+        lines.push(...renderEventCatalogueCheck(eventCatalogue.gaps));
+        lines.push(...renderRepoEdgesCheck(await runRepoEdgesCheck(session, { sddRoot })));
+        lines.push(...renderGlossaryXrefCheck((await runGlossaryXrefCheck(session, {
+            sddRoot,
+            xrefPresent: present("glossary_xref"),
+        })).finding));
+        lines.push(...renderDataModelEntitiesCheck(await runDataModelEntitiesCheck(session)));
+        lines.push(...renderCapabilityEventCheck(await runCapabilityEventCheck(session)));
+        lines.push(...renderFeatureEventCheck(await runFeatureEventCheck(session)));
+        lines.push(...renderPlatformDependenciesCheck((await runPlatformDependenciesCheck(session, { sddRoot })).finding));
+        lines.push(...renderFeatureSpecPromotionCheck(await runFeatureSpecPromotionCheck(session)));
+        lines.push(...renderFeatureSurfaceDuplicationCheck(await runFeatureSurfaceDuplicationCheck(session)));
+        // The fourteenth check (M-ADR 0205 §4.5, Phase B): every eligible artefact
+        // carries a current score. Last in the block order because it is the newest
+        // and the baselines hold the stream positionally-agnostic but ordered.
+        const available = new Set(schema.catalogues.map((c) => c.name).filter((n) => present(n)));
+        lines.push(...renderScoresCoverage(await runScoresCoverage(session, { tier, available, sddRoot }), tier));
+        // Staleness VERDICTS — the second half of the fourteenth check's §4.5
+        // scope (ledger §3o), member-tier only with the aggregate skip stated.
+        // Same coverage class, same reporting-only staging as the rest of the
+        // scores family.
+        lines.push(...renderStalenessVerdicts(await runStalenessVerdicts(session, { tier, available, sddRoot }), tier));
+        // The fifteenth check (M-ADR 0206 §4.5): relationship coherence for the
+        // three families where drift or gaps mean something — owned-but-untraced
+        // features, publisher-projection drift, supersession drift. Reporting-only
+        // at both tiers; newest last in the block order, same as scores was.
+        lines.push(...renderRelationshipCoherenceCheck(await runRelationshipCoherenceCheck(session)));
+        // The sixteenth check (M-ADR 0207 §4.8): the scaffold declared-vs-derived
+        // delta, its resolution self-check, and the §4.6 staleness verdict.
+        // Reporting-only at both tiers per §4.9 — nothing here gates until the
+        // pilot's stated-in-advance figures land. Newest last in the block order,
+        // same as scores and coherence were.
+        lines.push(...renderScaffoldDelta(await runScaffoldDelta(session, { tier, available, schema, sddRoot }), tier));
+    }
+    finally {
+        session.dispose();
+    }
+    for (const line of lines)
+        write(`${line}\n`);
+    return { exitCode: 0 };
+}
+//# sourceMappingURL=coverage-run.js.map

package/dist/lib/catalogue/csv-reader.js

@@ -0,0 +1,97 @@
+// CSV reader for catalogue files.
+//
+// RFC-4180-aware: handles `"` quoting (including doubled `""` for literal
+// quotes), commas inside quoted cells, and CR/LF/CRLF line breaks. We
+// don't try to be a general CSV library — the canonical writer's output
+// is the input shape we support, plus tolerance for byte-identical
+// catalogues authored by other conforming aggregator implementations.
+//
+// Headers come from the file's first line; column order is preserved
+// for traceability but row access is by column name.
+import { readFile } from "node:fs/promises";
+export async function readCatalogueCsv(path) {
+    const text = await readFile(path, "utf-8");
+    return parseCatalogueCsv(text);
+}
+export function parseCatalogueCsv(text) {
+    const records = parseRecords(text);
+    if (records.length === 0)
+        return { columns: [], rows: [] };
+    const columns = records[0] ?? [];
+    const rows = [];
+    for (let r = 1; r < records.length; r++) {
+        const record = records[r] ?? [];
+        if (record.length === 1 && record[0] === "")
+            continue; // empty trailing line
+        const row = {};
+        for (let c = 0; c < columns.length; c++) {
+            row[columns[c] ?? ""] = record[c] ?? "";
+        }
+        rows.push(row);
+    }
+    return { columns, rows };
+}
+function parseRecords(text) {
+    const records = [];
+    let current = [];
+    let cell = "";
+    let i = 0;
+    let inQuotes = false;
+    while (i < text.length) {
+        const ch = text[i] ?? "";
+        if (inQuotes) {
+            if (ch === '"') {
+                if (text[i + 1] === '"') {
+                    // Escaped double-quote inside a quoted cell.
+                    cell += '"';
+                    i += 2;
+                    continue;
+                }
+                inQuotes = false;
+                i++;
+                continue;
+            }
+            cell += ch;
+            i++;
+            continue;
+        }
+        if (ch === '"') {
+            inQuotes = true;
+            i++;
+            continue;
+        }
+        if (ch === ",") {
+            current.push(cell);
+            cell = "";
+            i++;
+            continue;
+        }
+        if (ch === "\r") {
+            if (text[i + 1] === "\n")
+                i++;
+            current.push(cell);
+            records.push(current);
+            current = [];
+            cell = "";
+            i++;
+            continue;
+        }
+        if (ch === "\n") {
+            current.push(cell);
+            records.push(current);
+            current = [];
+            cell = "";
+            i++;
+            continue;
+        }
+        cell += ch;
+        i++;
+    }
+    // Trailing cell + record.
+    if (cell !== "" || current.length > 0) {
+        current.push(cell);
+        records.push(current);
+    }
+    return records;
+}
+//# sourceMappingURL=csv-reader.js.map

package/dist/lib/catalogue/csv-writer.js

@@ -0,0 +1,96 @@
+/**
+ * Deterministic CSV writer for catalogues.
+ *
+ * Emits headers + sorted rows per ADR 0134 builder contract:
+ *   - column order matches the canonical schema exactly,
+ *   - rows sorted by primary-key value,
+ *   - cells with embedded comma/quote/newline are RFC-4180 quoted,
+ *   - empty trailing newline (POSIX convention).
+ *
+ * Headers-only emission is supported — pass an empty rows array to write
+ * a CSV that downstream consumers can rely on the file existence of.
+ *
+ * ⚠ BUT A HEADERS-ONLY WRITE NEVER TRUNCATES A CATALOGUE THAT HAS ROWS.
+ * `conformance_finding` is written by a DIFFERENT VERB — `sdd-cli conformance
+ * --emit-finding` calls writeFindings() into the same `catalogues/` directory —
+ * and nothing in the `catalogue build` row-collection path ever sets it. So
+ * build emitted a bare header over it, unconditionally, and one verb destroyed
+ * another verb's output. Measured across one estate: every SDD that had
+ * authored a conformance finding lost it, while the gate registries went on
+ * citing those rows as CURRENT evidence for a hard-gated score.
+ *
+ * ⚠ The first cut of this comment said `c4_system_entity` was a second
+ * producerless catalogue. It is not — `build.ts` sets it directly rather than
+ * via `builders/`, and the sweep that "found" it only searched `builders/`.
+ * An adopter disproved it by counterfactual, installing the defective version
+ * and measuring that its rows survived. Stated here because the wrong version
+ * shipped in 1.29.0 and a reader deserves the correction beside the claim.
+ *
+ * The guard is keyed on the CONDITION, not on those two names, so it also
+ * catches the case nobody has hit yet: a builder that regresses to zero rows
+ * silently deleting a populated catalogue.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+/** Data-row count of an existing catalogue file, or 0 when absent/unreadable/header-only. */
+async function existingDataRows(filePath) {
+    let text;
+    try {
+        text = await readFile(filePath, "utf-8");
+    }
+    catch {
+        return 0;
+    }
+    const lines = text.split("\n").filter((l) => l.trim() !== "");
+    return lines.length > 1 ? lines.length - 1 : 0;
+}
+export async function writeCatalogue(opts) {
+    await mkdir(opts.outDir, { recursive: true });
+    const filePath = join(opts.outDir, `${opts.catalogue.name}.csv`);
+    // Refuse to replace rows with a bare header. Emitting one is correct when the
+    // file is absent or already empty — that is the "consumers can rely on the
+    // file existing" case — and is data loss when it is not.
+    if (opts.rows.length === 0) {
+        const onDisk = await existingDataRows(filePath);
+        if (onDisk > 0) {
+            return { rowCount: onDisk, path: filePath, preserved: true, preservedRows: onDisk };
+        }
+    }
+    const text = renderCatalogueCsv(opts.catalogue, opts.rows);
+    await mkdir(dirname(filePath), { recursive: true });
+    await writeFile(filePath, text, "utf-8");
+    return { rowCount: opts.rows.length, path: filePath };
+}
+export function renderCatalogueCsv(catalogue, rows) {
+    const columns = catalogue.columns.map((c) => c.name);
+    const lines = [];
+    lines.push(columns.map(escapeCell).join(","));
+    const sorted = [...rows].sort((a, b) => compareCell(a[catalogue.primaryKey], b[catalogue.primaryKey]));
+    for (const row of sorted) {
+        const cells = columns.map((col) => escapeCell(formatCell(row[col])));
+        lines.push(cells.join(","));
+    }
+    // Trailing newline per POSIX convention.
+    return `${lines.join("\n")}\n`;
+}
+function formatCell(value) {
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    return String(value);
+}
+function escapeCell(value) {
+    if (value === "")
+        return "";
+    if (/[",\n\r]/.test(value)) {
+        return `"${value.replace(/"/g, '""')}"`;
+    }
+    return value;
+}
+function compareCell(a, b) {
+    const sa = a === undefined || a === null ? "" : String(a);
+    const sb = b === undefined || b === null ? "" : String(b);
+    return sa < sb ? -1 : sa > sb ? 1 : 0;
+}
+//# sourceMappingURL=csv-writer.js.map

package/dist/lib/catalogue/data-plane-coherence.js

@@ -0,0 +1,77 @@
+// data_plane ↔ product_platform_dependencies coherence cross-check
+// (M-ADR 0193 §4.2, as amended 2026-07-19).
+//
+// The two surfaces are complementary views, not mutually derived: a data_plane
+// binding carries pattern / fine locality / runtime that platform-dependencies
+// lack, and a platform-dependency carries capability / contract / stability that
+// a binding lacks. The method CROSS-CHECKS them for coherence rather than
+// deriving one from the other.
+//
+// The check is deliberately COARSE, and per-target correspondence is NOT
+// asserted. Under the gateway convention (M-ADR 0189: consumers reach a
+// capability through a BFF/gateway), a `retrieve@internal-domain` binding names
+// the DOMAIN service it logically reads (its finer-grained `target`), while the
+// matching `product_platform_dependencies` row names the GATEWAY through which
+// access physically flows. The two targets legitimately differ — that
+// difference is the locality/granularity signal the axis exists to capture, not
+// drift. Matching binding.target against platform-dep.target_service_id would
+// flag every such binding falsely, and adopters would "fix" the false finding by
+// coarsening `target` to the gateway id — destroying the axis's value. So the
+// coherence check asserts only the coarse invariant: a product that declares
+// platform-targeting data-plane bindings should also declare *some* platform
+// dependency. A product with internal bindings and zero platform-deps has one
+// surface without the other — a genuine coherence gap worth surfacing.
+import { isOutputSidePattern } from "./manifest-loader.js";
+const INTERNAL_LOCALITIES = new Set([
+    "internal-platform",
+    "internal-domain",
+]);
+/**
+ * Coarse coherence check: if a product declares platform-targeting INBOUND
+ * data-plane bindings (internal locality) but no `product_platform_dependencies`
+ * rows at all, the two complementary surfaces are out of step. Returns 1 if
+ * flagged, else 0. Per-target correspondence is intentionally NOT checked, and
+ * output-side bindings are excluded entirely (see header).
+ */
+// @rule data-plane-platform-dep-coherence
+export function checkDataPlanePlatformDepCoherence(inputs) {
+    const { productId, bindings, platformDeps, findings } = inputs;
+    const platformTargeting = bindings.filter((b) => INTERNAL_LOCALITIES.has(String(b["locality"] ?? "")) &&
+        !isOutputSidePattern(String(b["pattern"] ?? "")));
+    if (platformTargeting.length === 0)
+        return 0; // no platform-targeting bindings
+    if (platformDeps.length > 0)
+        return 0; // both surfaces present — coherent
+    findings.add("convention", `data_plane coherence: ${productId} declares ${platformTargeting.length} platform-targeting ` +
+        `inbound data_plane binding(s) (internal locality) but no product_platform_dependencies rows — the two ` +
+        `complementary surfaces are out of step; declare the platform dependencies in ` +
+        `app-platform-dependencies.yaml (M-ADR 0193 §4.2). Per-target correspondence is not asserted ` +
+        `(gateway indirection, M-ADR 0189).`);
+    return 1;
+}
+/**
+ * Coherence cross-check between the `surface: api` trait and a `publish`
+ * data_plane binding. Returns 1 if a drift finding was raised, else 0.
+ *
+ * One-directional: only a headless (`surface: api`) product missing its
+ * `publish` binding is flagged. A `publish` binding on a `ui` surface is
+ * legitimate and never flagged (see header). Runs only over a DECLARED
+ * data-plane (bindings present) — same gating as the platform-dep check; a
+ * product that has not authored a data_plane is not nagged.
+ */
+// @rule publish-surface-coherence
+export function checkPublishSurfaceCoherence(inputs) {
+    const { productId, surface, bindings, findings } = inputs;
+    const effectiveSurface = surface ?? "ui";
+    if (effectiveSurface !== "api")
+        return 0; // publish is orthogonal to a ui surface
+    const hasPublish = bindings.some((b) => String(b["pattern"] ?? "") === "publish");
+    if (hasPublish)
+        return 0; // both views present — coherent
+    findings.add("convention", `data_plane/surface coherence: ${productId} declares surface: api (headless, M-ADR 0167) but its ` +
+        `data_plane has no publish binding — a headless product's entire surface is programmatic, so the ` +
+        `contract that constitutes it is missing from the declared composition. Add a publish binding, or ` +
+        `reconsider the surface classification (M-ADR 0193 §4.7). Complementary views, not a derivation.`);
+    return 1;
+}
+//# sourceMappingURL=data-plane-coherence.js.map

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