@sdd-method/sdd-cli 1.1.0 → 1.3.0

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

@@ -0,0 +1,97 @@
+/**
+ * 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, runRepoEdgesCheck, } from "./gate-checks.js";
+import { runScoresCoverage } from "./scores-coverage.js";
+import { renderCapabilityEventCheck, renderContractCoverage, renderDataModelEntitiesCheck, renderEventCatalogueCheck, renderEventCoverage, renderFeatureEventCheck, renderFeatureSpecPromotionCheck, renderFeatureSurfaceDuplicationCheck, renderGlossaryXrefCheck, renderPlatformDependenciesCheck, 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));
+    }
+    finally {
+        session.dispose();
+    }
+    for (const line of lines)
+        write(`${line}\n`);
+    return { exitCode: 0 };
+}
+//# sourceMappingURL=coverage-run.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-run.js","sourceRoot":"","sources":["../../../src/lib/catalogue/coverage-run.ts"],"names":[],"mappings":"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"}

package/dist/lib/catalogue/ddl-generator.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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 type { CanonicalSchema, ForeignKeyDef } from "./schema-loader.js";
+import type { FkValidationOptions } from "./fk-validator.js";
+/** Engine type for a schema column type; throws on an unmapped type. */
+export declare function sqlType(catalogue: string, column: string, type: string): string;
+/**
+ * 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 declare function isEffectiveExternal(fk: ForeignKeyDef, options: FkValidationOptions): boolean;
+/**
+ * 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 declare function generateTableDdl(schema: CanonicalSchema): readonly string[];
+export type ConstraintKind = "fk" | "pk" | "enum";
+export interface ConstraintQuery {
+    readonly catalogue: string;
+    readonly kind: ConstraintKind;
+    /** The constrained column (fk/enum) or the primary-key column (pk). */
+    readonly column: string;
+    /** For fk: the "{catalogue}.{column}" target. For enum: the enum name. */
+    readonly target?: string;
+    /**
+     * SELECT returning one row per violation with a total ORDER BY.
+     * fk/enum rows: (row_pk, value). pk rows: (row_pk, n).
+     */
+    readonly sql: string;
+}
+/**
+ * The violation-query set for a schema, mirroring the in-memory
+ * validators' semantics under the same options they take.
+ */
+export declare function generateConstraintQueries(schema: CanonicalSchema, options?: FkValidationOptions): readonly ConstraintQuery[];
+/**
+ * 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 declare function generateExternalFindingQueries(schema: CanonicalSchema, options?: FkValidationOptions): readonly ConstraintQuery[];
+//# sourceMappingURL=ddl-generator.d.ts.map

package/dist/lib/catalogue/ddl-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ddl-generator.d.ts","sourceRoot":"","sources":["../../../src/lib/catalogue/ddl-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EACV,eAAe,EAEf,aAAa,EACd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAY7D,wEAAwE;AACxE,wBAAgB,OAAO,CACrB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,MAAM,CAQR;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,aAAa,EACjB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAMT;AAeD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,MAAM,EAAE,CAO3E;AAED,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,IAAI,GAAG,MAAM,CAAC;AAElD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE,mBAAwB,GAChC,SAAS,eAAe,EAAE,CA8F5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE,mBAAwB,GAChC,SAAS,eAAe,EAAE,CA6B5B"}

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

@@ -0,0 +1,215 @@
+/**
+ * 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).
+ */
+/** 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 = [];
+    for (const cat of schema.catalogues) {
+        queries.push(pkQuery(cat));
+        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) {
+                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}))`);
+            }
+            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) {
+    const t = quote(cat.name);
+    const pk = quote(cat.primaryKey);
+    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 COUNT(*) > 1 ORDER BY row_pk;`,
+    };
+}
+//# sourceMappingURL=ddl-generator.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ddl-generator.js","sourceRoot":"","sources":["../../../src/lib/catalogue/ddl-generator.ts"],"names":[],"mappings":"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"}

package/dist/lib/catalogue/engine-validator.d.ts

@@ -0,0 +1,103 @@
+/**
+ * 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 type { CanonicalSchema } from "./schema-loader.js";
+import type { CatalogueRow } from "./csv-writer.js";
+import type { FindingsLog } from "./findings.js";
+import type { FkValidationOptions, FkValidationResult } from "./fk-validator.js";
+import type { EnumValidationResult } from "./enum-validator.js";
+export interface PkDuplicate {
+    readonly catalogue: string;
+    readonly rowPk: string;
+    readonly count: number;
+}
+export interface TypeNonconformance {
+    readonly catalogue: string;
+    readonly column: string;
+    readonly declaredType: string;
+    readonly value: string;
+    readonly rows: number;
+}
+export interface ExternalFindingDetail {
+    readonly catalogue: string;
+    readonly column: string;
+    readonly target: string;
+    /** Display-ready: "?" when the referencing row has a NULL primary key. */
+    readonly rowPk: string;
+    readonly value: string;
+}
+export interface EngineValidationResult {
+    readonly fk: FkValidationResult;
+    readonly enums: EnumValidationResult;
+    /** One entry per unresolved value on an effective-external FK — the rows behind fk.externalFindings. */
+    readonly externalFindingDetails: readonly ExternalFindingDetail[];
+    /** Engine-only: no in-memory counterpart exists at validate time. */
+    readonly pkDuplicates: readonly PkDuplicate[];
+    /**
+     * Engine-only: non-empty values in typed (non-string) columns the engine
+     * cannot read as the declared type. The load uses TRY_CAST so one such
+     * cell cannot abort a whole run, but the miss is REPORTED, never
+     * smoothed — the in-memory path types nothing, so this class was
+     * invisible before the engine existed. Outside the parity claim: the
+     * compared validators only read string columns.
+     */
+    readonly typeNonconformances: readonly TypeNonconformance[];
+}
+export interface EngineConnection {
+    run(sql: string): Promise<unknown>;
+    runAndReadAll(sql: string): Promise<{
+        getRows(): unknown[][];
+    }>;
+}
+export interface EngineSession {
+    readonly conn: EngineConnection;
+    dispose(): void;
+}
+/**
+ * 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 declare function createEngineSession(schema: CanonicalSchema, rowsByCatalogue: ReadonlyMap<string, readonly CatalogueRow[]>): Promise<EngineSession>;
+export declare function validateWithEngine(schema: CanonicalSchema, rowsByCatalogue: ReadonlyMap<string, readonly CatalogueRow[]>, options?: FkValidationOptions): Promise<EngineValidationResult>;
+/**
+ * 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 declare function validateWithEngineToLog(schema: CanonicalSchema, rowsByCatalogue: ReadonlyMap<string, readonly CatalogueRow[]>, findings: FindingsLog, options?: FkValidationOptions, extras?: {
+    /**
+     * False at the aggregation tier, which has never emitted enum
+     * findings — the cutover changes no tier's finding surface.
+     */
+    readonly logEnumFindings?: boolean;
+}): Promise<{
+    fk: FkValidationResult;
+    enums: EnumValidationResult;
+}>;
+//# sourceMappingURL=engine-validator.d.ts.map

package/dist/lib/catalogue/engine-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-validator.d.ts","sourceRoot":"","sources":["../../../src/lib/catalogue/engine-validator.ts"],"names":[],"mappings":"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"}