code-auditor-mcp 4.1.0 → 5.0.1

package/dist/analyzers/universal/schema/migrations.js

@@ -9,6 +9,8 @@ import fs from 'fs/promises';
 import { readFileSync, statSync } from 'node:fs';
 import path from 'path';
 import { MAX_ORPHAN_SOURCE_BYTES } from '../../../types.js';
+import { isTestOrSpecPath } from '../../../languages/testConventions.js';
+import { parseSqlProgramTolerant, ddlColumnDefinitions, ddlForeignKeys as astDdlForeignKeys, ddlMigrationOps, ddlConstraintColumns, ddlTableNames, isDdlStatement, } from '../../../languages/sql/sqlAst.js';
 /**
  * Strip SQL identifier delimiters: backticks or double-quotes.
  * @param name
@@ -48,177 +50,417 @@ export function applyMigrationOps(ops, tables) {
  * operations to the given table set in migration order.
  * @param source
  * @param tables
+ * @param dialect The corpus's named dialect; null is honest abstention — no
+ *   parse under a guessed {@link DEFAULT_SQL_DIALECT} (unproven, cannot-fire).
  */
-export function processMigrationSource(source, tables) {
-    applyMigrationOps(parseMigrationOps(source), tables);
+export function processMigrationSource(source, tables, dialect) {
+    applyMigrationOps(parseMigrationOps(source, dialect), tables);
 }
 /**
- * The DDL state-machine regex shared by the standalone analyze() path and the
- * pipeline's schema-sql visitor. Single ordered pass — applies CREATE/DROP/
- * RENAME in statement order within each migration file (fixes the rename-replay
- * bug where CREATE after RENAME in the same file was silently dropped).
+ * Replay per-file DDL declarations in migration order to compute, in one pass,
+ * both the net known-table set (a table dropped in a migration and not
+ * recreated is *not* known) and the drop provenance (dropped-table name → which
+ * migration dropped it and what it introduced). A table created and dropped
+ * within the *same* file is a self-contained scratch fixture (its DROP is
+ * teardown, not a migration), so it is kept known and excluded from the
+ * provenance. This is the shared pure function the legacy schema reducer's
+ * inline replay and the phase-model `resolution` / `migration-history`
+ * corpus processors both compute, so the two facts are identical by
+ * construction (parity-by-construction for `unknown-table` and
+ * `stale-table-reference`).
+ *
+ * @param ddlFiles Per-file declarations with parsed ops and (optionally) the
+ *   columns the file declares for each table (order-independent — this sorts by
+ *   the numeric prefix in the basename, then localeCompare).
+ * @returns The net known-table set and the drop provenance.
  */
-const DDL_RE = /(CREATE)\s+(?:VIRTUAL\s+)?TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?(`[^`]+`|"[^"]+"|\w+)|(DROP)\s+TABLE\s+(?:IF\s+EXISTS\s+)?(`[^`]+`|"[^"]+"|\w+)|(ALTER)\s+TABLE\s+(`[^`]+`|"[^"]+"|\w+)\s+RENAME\s+TO\s+(`[^`]+`|"[^"]+"|\w+)/gi;
+export function replayDdlDeclarations(ddlFiles) {
+    const numericPrefix = (p) => {
+        const base = p.split('/').pop() ?? p;
+        const m = base.match(/^(\d+)/);
+        return m ? parseInt(m[1], 10) : 0;
+    };
+    const sorted = [...ddlFiles]
+        // A DROP (or CREATE) inside a test/spec file is test scaffolding, not a
+        // production table lifecycle event. Replaying it would let `DROP TABLE
+        // users` in `codeIndexDB-security.spec.ts` mark a production table dropped,
+        // turning every later reference into a `stale-table-reference` false
+        // positive. Skip test/spec files before replay so only production migrations
+        // move the known-table set and the drop provenance.
+        .filter((d) => !isTestOrSpecPath(d.filePath))
+        .sort((a, b) => {
+        const na = numericPrefix(a.filePath);
+        const nb = numericPrefix(b.filePath);
+        if (na !== nb)
+            return na - nb;
+        return a.filePath.localeCompare(b.filePath);
+    });
+    const knownTables = new Set();
+    // Last-CREATE source file + column list per surviving table, so `resolution`
+    // names the file that most recently (re)declared the table, with its columns.
+    const sourceFile = new Map();
+    const columnsByTable = new Map();
+    const uniqueColumnsByTable = new Map();
+    const primaryKeyColumnsByTable = new Map();
+    const notNullColumnsByTable = new Map();
+    const foreignKeysByTable = new Map();
+    const dropProvenance = new Map();
+    for (const ddlFile of sorted) {
+        const before = new Set(knownTables);
+        // Replay this file's CREATE/DROP/RENAME transitions, tracking last-CREATE
+        // source/columns alongside the net set (the same transitions
+        // `applyMigrationOps` performs, but with provenance bookkeeping).
+        for (const op of ddlFile.ops) {
+            const t = stripIdentifier(op.table);
+            if (op.op === 'CREATE') {
+                knownTables.add(t);
+                sourceFile.set(t, ddlFile.filePath);
+                columnsByTable.set(t, [...(ddlFile.tableColumns?.[t] ?? [])]);
+                uniqueColumnsByTable.set(t, [...(ddlFile.uniqueColumns?.[t] ?? [])]);
+                primaryKeyColumnsByTable.set(t, [...(ddlFile.primaryKeyColumns?.[t] ?? [])]);
+                notNullColumnsByTable.set(t, [...(ddlFile.notNullColumns?.[t] ?? [])]);
+                foreignKeysByTable.set(t, [...(ddlFile.foreignKeys?.[t] ?? [])]);
+            }
+            else if (op.op === 'DROP') {
+                knownTables.delete(t);
+            }
+            else {
+                const nt = stripIdentifier(op.newTable);
+                knownTables.delete(t);
+                knownTables.add(nt);
+                sourceFile.delete(t);
+                columnsByTable.delete(t);
+                uniqueColumnsByTable.delete(t);
+                primaryKeyColumnsByTable.delete(t);
+                notNullColumnsByTable.delete(t);
+                foreignKeysByTable.delete(t);
+                sourceFile.set(nt, ddlFile.filePath);
+                columnsByTable.set(nt, [...(ddlFile.tableColumns?.[nt] ?? [])]);
+                uniqueColumnsByTable.set(nt, [...(ddlFile.uniqueColumns?.[nt] ?? [])]);
+                primaryKeyColumnsByTable.set(nt, [...(ddlFile.primaryKeyColumns?.[nt] ?? [])]);
+                notNullColumnsByTable.set(nt, [...(ddlFile.notNullColumns?.[nt] ?? [])]);
+                foreignKeysByTable.set(nt, [...(ddlFile.foreignKeys?.[nt] ?? [])]);
+            }
+        }
+        // Genuinely-new tables introduced by this migration (excludes rename/rebuild
+        // churn like `ALTER … RENAME TO x_old` + re-CREATE of the same name).
+        const createdHere = [];
+        const createdTables = new Set();
+        const droppedTables = new Set();
+        for (const op of ddlFile.ops) {
+            const t = stripIdentifier(op.table);
+            if (op.op === 'CREATE') {
+                createdTables.add(t);
+                if (!before.has(t))
+                    createdHere.push(t);
+            }
+            else if (op.op === 'DROP') {
+                droppedTables.add(t);
+            }
+        }
+        for (const op of ddlFile.ops) {
+            const t = stripIdentifier(op.table);
+            if (op.op === 'DROP') {
+                dropProvenance.set(t, { migrationFile: ddlFile.filePath, createdInSameMigration: createdHere });
+            }
+            else if (op.op === 'CREATE') {
+                dropProvenance.delete(t);
+            }
+        }
+        // A table created and dropped within this same file is a self-contained
+        // fixture — a scratch table a test or script creates, uses, then tears
+        // down. Its DROP is teardown, not a migration: keep it known and clear the
+        // drop provenance this file recorded for it.
+        for (const t of createdTables) {
+            if (droppedTables.has(t)) {
+                knownTables.add(t);
+                if (dropProvenance.get(t)?.migrationFile === ddlFile.filePath) {
+                    dropProvenance.delete(t);
+                }
+            }
+        }
+    }
+    const netTables = [];
+    for (const name of knownTables) {
+        netTables.push({
+            name,
+            source: sourceFile.get(name) ?? '',
+            columns: columnsByTable.get(name) ?? [],
+            uniqueColumns: uniqueColumnsByTable.get(name) ?? [],
+            primaryKeyColumns: primaryKeyColumnsByTable.get(name) ?? [],
+            notNullColumns: notNullColumnsByTable.get(name) ?? [],
+            foreignKeys: foreignKeysByTable.get(name) ?? [],
+        });
+    }
+    return { netTables, dropProvenance };
+}
 /**
- * Extract ordered DDL operations from migration SQL text. Emitted by the
- * schema-sql visitor instead of raw source so the reducer only retains the
- * extracted state transitions, not the full file text.
+ * Extract ordered DDL operations from migration SQL text — the AST replacement
+ * for site #7's `DDL_RE`, which had to regex the whole create/drop/alter-rename
+ * vocabulary as one alternation. Each statement is parsed tolerantly (a `PRAGMA`
+ * or `CREATE TRIGGER` beside a `CREATE TABLE` is a failure the caller accounts
+ * for, not a discard of the whole file) and walked by {@link ddlMigrationOps}.
+ * Emitted by the schema-sql visitor instead of raw source so the reducer only
+ * retains the extracted state transitions, not the full file text.
  * @param source
+ * @param dialect The corpus's named dialect; null is honest abstention — the SQL
+ *   is NOT parsed under a guessed {@link DEFAULT_SQL_DIALECT}. An undetermined
+ *   (or ambiguous) dialect yields `unproven`: the caller surfaces the
+ *   `dialect undetermined` cannot-fire reason, never a sqlite-guessed op set.
  * @returns
  */
-export function parseMigrationOps(source) {
+export function parseMigrationOps(source, dialect) {
+    // A null dialect is not a licence to guess sqlite. Parsing DDL under a dialect
+    // nothing in the manifest suggested is a wrong answer wearing a fact — the
+    // same inversion as the dialect gate, one layer over. Abstain: no AST parse and
+    // no FTS5 regex recovery, so an ambiguous corpus (pg+mysql) emits zero ops and
+    // the cannot-fire reason carries the ambiguity instead.
+    if (dialect === null)
+        return [];
+    const { statements } = parseSqlProgramTolerant(source, dialect);
     const ops = [];
-    let match;
-    DDL_RE.lastIndex = 0;
-    while ((match = DDL_RE.exec(source)) !== null) {
-        const op = match[1] || match[3] || match[5];
-        if (op === 'CREATE') {
-            ops.push({ op: 'CREATE', table: match[2] });
-        }
-        else if (op === 'DROP') {
-            ops.push({ op: 'DROP', table: match[4] });
-        }
-        else if (op === 'ALTER') {
-            ops.push({ op: 'RENAME', table: match[6], newTable: match[7] });
-        }
+    for (const stmt of statements) {
+        ops.push(...ddlMigrationOps(stmt));
+    }
+    // FTS5 `CREATE VIRTUAL TABLE … USING fts5(…)` is rejected by node-sql-parser
+    // (it is not `CREATE TABLE`), so the tolerant parse drops it and the DDL replay
+    // never learns the table exists. That makes a dropped-and-recreated FTS table
+    // read as "dropped, never recreated" — the `stale-table-reference` false
+    // positive on `functions_fts` (whose v17 migration drops the FTS5 surface, then
+    // rebuilds it). Recover those creates here so the replay tracks the virtual
+    // table's lifecycle like any other table. The recovered CREATE ops are appended
+    // after the AST-derived ops; the replay's net result is unaffected by
+    // intra-file ordering because the *last* op per table decides its state — a
+    // virtual table's DROP is already captured, so a re-CREATE appended after it
+    // correctly restores it to known.
+    for (const op of virtualTableCreateOps(source)) {
+        ops.push(op);
+    }
+    return ops;
+}
+/** Regex-scan `source` for `CREATE VIRTUAL TABLE [IF NOT EXISTS] <name>` headers
+ *  and emit a CREATE op per name. This is the recovery path for FTS5 virtual
+ *  tables, which node-sql-parser cannot parse; a bare identifier (optionally
+ *  backtick/double-quoted) is the only supported name shape, matching the
+ *  `DDL_HEADER_RE` the ddl-declarations oracle counts. */
+const VIRTUAL_TABLE_CREATE_RE = /CREATE\s+VIRTUAL\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?([`"']?[A-Za-z_][A-Za-z0-9_$]*[`"']?)/gi;
+function virtualTableCreateOps(source) {
+    const ops = [];
+    let m;
+    while ((m = VIRTUAL_TABLE_CREATE_RE.exec(source)) !== null) {
+        const name = stripIdentifier(m[1]);
+        if (name)
+            ops.push({ op: 'CREATE', table: name });
     }
     return ops;
 }
 // ── DDL column extraction (Spec 39 — derived applicability) ──────────────────
+//
+// Sites #9 and #10 are the AST replacements for the regex scanners that used to
+// hand-roll paren-depth tracking and quote handling (a SQL parser written one
+// bug at a time). The statement is parsed once by the grammar and the column /
+// constraint / foreign-key facts are read off the definition nodes.
 /**
- * Split a CREATE TABLE column-definition body on top-level commas. Commas
- * inside nested parens (type arguments, CHECK clauses) and inside string
- * literals are preserved so a column definition is never split mid-expression.
- * @param body The text between the CREATE TABLE parens.
- * @returns The individual column/constraint definitions.
+ * The shared DDL-column extraction body behind `extractDdlTableColumns`,
+ * `extractDdlUniqueColumns`, `extractDdlPrimaryKeyColumns`, and
+ * `extractDdlNotNullColumns`. Each is the same skeleton — null-dialect → empty,
+ * parse the program tolerantly, walk the statements adding lowercased columns to
+ * a per-table set via the `columnsFor` helper, fold the map to
+ * `Record<table, cols>`. Only the per-statement column selection differs, so it
+ * is the `collect` callback here; the null-guard, parse, map lifecycle, and fold
+ * are shared. The column-set helper is passed in so a caller that groups by a
+ * table derived from the statement (a `UNIQUE (…)` / `PRIMARY KEY (…)`
+ * constraint, whose table is the statement's own table rather than a column's)
+ * can still route to the right bucket.
  */
-function splitColumnDefs(body) {
-    const defs = [];
-    let depth = 0;
-    let current = '';
-    let inString = null;
-    for (let i = 0; i < body.length; i++) {
-        const ch = body[i];
-        if (inString) {
-            current += ch;
-            if (ch === inString)
-                inString = null;
-            continue;
+function extractDdlColumns(source, dialect, collect) {
+    if (dialect === null)
+        return {}; // honest abstention — no parse under a guessed dialect
+    const { statements } = parseSqlProgramTolerant(source, dialect);
+    const tableColumns = new Map();
+    const columnsFor = (table) => {
+        let cols = tableColumns.get(table);
+        if (!cols) {
+            cols = new Set();
+            tableColumns.set(table, cols);
         }
-        if (ch === '"' || ch === "'" || ch === '`') {
-            inString = ch;
-            current += ch;
-            continue;
+        return cols;
+    };
+    for (const stmt of statements)
+        collect(stmt, columnsFor);
+    const result = {};
+    for (const [table, cols] of tableColumns)
+        result[table] = [...cols];
+    return result;
+}
+/**
+ * Extract per-table column names from migration SQL — CREATE TABLE column
+ * definitions, ALTER TABLE … ADD COLUMN, and the columns of a foreign-key
+ * constraint (Drizzle's `ALTER TABLE … ADD CONSTRAINT … FOREIGN KEY
+ * ("organization_id") …` declares the tenant column through the constraint, not
+ * a column definition). Returns a `Record<table, columns>` with lowercased,
+ * deduplicated column names, so the schema reducer can answer "does THIS table
+ * carry a tenant-scoping column?" — the per-query question the flat set cannot.
+ * @param source Migration/DDL SQL text.
+ * @param dialect The corpus's named dialect; null is honest abstention — no
+   *   parse under a guessed {@link DEFAULT_SQL_DIALECT} (unproven, cannot-fire).
+ * @returns Per-table lowercased column-name lists.
+ */
+export function extractDdlTableColumns(source, dialect) {
+    return extractDdlColumns(source, dialect, (stmt, columnsFor) => {
+        for (const col of ddlColumnDefinitions(stmt)) {
+            if (col.table)
+                columnsFor(col.table).add(col.column.toLowerCase());
+        }
+        // FK-constraint columns are the tenant-column pass: a table whose only
+        // tenant column is declared through `ADD CONSTRAINT … FOREIGN KEY` still
+        // surfaces its columns here (Spec 68 — declared inputs).
+        for (const fk of astDdlForeignKeys(stmt)) {
+            const cols = columnsFor(fk.table);
+            for (const column of fk.columns)
+                cols.add(column.toLowerCase());
+        }
+    });
+}
+/**
+ * Extract per-table *natural* UNIQUE column names from migration SQL — the
+ * bootstrap-lookup signal `missing-org-filter` reads: a query whose predicate
+ * carries one of these is a structurally-scoped lookup by a natural key. Covers
+ * the three DDL spellings of `UNIQUE`:
+ *
+ *   - column-level:  `slug TEXT UNIQUE`
+ *   - table-level:   `UNIQUE (slug)`, `UNIQUE (a, b)`
+ *   - ALTER:         `ALTER TABLE t ADD CONSTRAINT … UNIQUE (col)`
+ *
+ * PRIMARY KEY is deliberately *excluded*. A surrogate primary key is not a
+ * bootstrap lookup: `WHERE id = $1` on a tenant table returns exactly one row
+ * selected by a caller-supplied id — that is the IDOR surface the rule exists
+ * to catch, not a signal that tenant scoping is unnecessary (see
+ * `specs/rule-authenticity-ledger.md:46`, and the Thing 1 correction that
+ * narrowed this signal to natural keys).
+ *
+ * Returns lowercased SQL column names keyed by table. A column that is unique
+ * only through a composite constraint still appears — the predicate test is
+ * "does the filter name this column", not "is the column alone unique".
+ * @param source Migration/DDL SQL text.
+ * @param dialect The corpus's named dialect; null is honest abstention — no
+   *   parse under a guessed {@link DEFAULT_SQL_DIALECT} (unproven, cannot-fire).
+ * @returns Per-table lowercased natural-UNIQUE column-name lists.
+ */
+export function extractDdlUniqueColumns(source, dialect) {
+    return extractDdlColumns(source, dialect, (stmt, columnsFor) => {
+        const table = ddlTableNames(stmt)[0] ?? '';
+        // Column-level `col … UNIQUE`. PRIMARY KEY is excluded (surrogate PK is the
+        // IDOR surface, not a bootstrap-lookup signal) — `ddlColumnDefinitions`
+        // carries `unique` and `primaryKey` separately.
+        for (const col of ddlColumnDefinitions(stmt)) {
+            if (col.unique)
+                columnsFor(col.table).add(col.column.toLowerCase());
         }
-        if (ch === '(') {
-            depth++;
-            current += ch;
-            continue;
+        // Table-level / ALTER `UNIQUE (…)` / `CONSTRAINT x UNIQUE (…)`.
+        for (const name of ddlConstraintColumns(stmt, 'unique')) {
+            columnsFor(table).add(name.toLowerCase());
         }
-        if (ch === ')') {
-            depth--;
-            current += ch;
-            continue;
+    });
+}
+/**
+ * Extract per-table PRIMARY KEY columns from migration SQL — the surrogate-vs-
+ * natural distinction `missing-org-filter` needs to keep PK *separate* from
+ * UNIQUE (Spec 69 R3, criterion 8). Covers the DDL spellings of a primary key:
+ *
+ *   - column-level:  `id SERIAL PRIMARY KEY`, `id INTEGER PRIMARY KEY`
+ *   - table-level:   `PRIMARY KEY (id)`, `CONSTRAINT pk PRIMARY KEY (id)`
+ *   - ALTER:         `ALTER TABLE t ADD CONSTRAINT pk PRIMARY KEY (col)`
+ *
+ * Returns lowercased SQL column names keyed by table. A composite PK lists every
+ * member column. PRIMARY KEY and UNIQUE are *never* merged here — the caller
+ * records them as separate flags so the quiet set can stay natural-UNIQUE-only.
+ * @param source Migration/DDL SQL text.
+ * @param dialect The corpus's named dialect; null is honest abstention — no
+   *   parse under a guessed {@link DEFAULT_SQL_DIALECT} (unproven, cannot-fire).
+ * @returns Per-table lowercased PRIMARY-KEY column-name lists.
+ */
+export function extractDdlPrimaryKeyColumns(source, dialect) {
+    return extractDdlColumns(source, dialect, (stmt, columnsFor) => {
+        const table = ddlTableNames(stmt)[0] ?? '';
+        // Column-level `id … PRIMARY KEY`.
+        for (const col of ddlColumnDefinitions(stmt)) {
+            if (col.primaryKey)
+                columnsFor(col.table).add(col.column.toLowerCase());
         }
-        if (ch === ',' && depth === 0) {
-            defs.push(current);
-            current = '';
-            continue;
+        // Table-level `PRIMARY KEY (…)` / `CONSTRAINT pk PRIMARY KEY (…)`.
+        for (const name of ddlConstraintColumns(stmt, 'primary key')) {
+            columnsFor(table).add(name.toLowerCase());
         }
-        current += ch;
-    }
-    if (current.trim())
-        defs.push(current);
-    return defs;
+    });
 }
 /**
- * Extract the leading column name from a single column definition. Table-level
- * constraint clauses (PRIMARY KEY, UNIQUE, FOREIGN KEY, CHECK, CONSTRAINT …)
- * have no leading column identifier and are skipped.
- * @param def A single column or constraint definition.
- * @returns The column name, or null when the definition is a table constraint.
+ * Extract per-table NOT NULL columns from migration SQL. Column-level only —
+ * SQL has no table-level NOT NULL constraint. Returns lowercased SQL column
+ * names keyed by table; the resolution fact records the flag separately so a
+ * rule can distinguish a required column from a nullable one.
+ * @param source Migration/DDL SQL text.
+ * @param dialect The corpus's named dialect; null is honest abstention — no
+   *   parse under a guessed {@link DEFAULT_SQL_DIALECT} (unproven, cannot-fire).
+ * @returns Per-table lowercased NOT-NULL column-name lists.
  */
-function leadingColumnName(def) {
-    const m = /^\s*(?:CONSTRAINT\s+(?:`[^`]+`|"[^"]+"|\w+))?\s*(`[^`]+`|"[^"]+"|\w+)/.exec(def);
-    if (!m)
-        return null;
-    const name = stripIdentifier(m[1]);
-    const upper = name.toUpperCase();
-    if (upper === 'PRIMARY' || upper === 'UNIQUE' || upper === 'CONSTRAINT' ||
-        upper === 'FOREIGN' || upper === 'CHECK' || upper === 'KEY' || upper === 'INDEX') {
-        return null;
-    }
-    return name;
+export function extractDdlNotNullColumns(source, dialect) {
+    return extractDdlColumns(source, dialect, (stmt, columnsFor) => {
+        for (const col of ddlColumnDefinitions(stmt)) {
+            if (col.notNull)
+                columnsFor(col.table).add(col.column.toLowerCase());
+        }
+    });
 }
 /**
- * Extract per-table column names from migration SQL — CREATE TABLE bodies (via
- * a depth-tracking paren scan that finds each matching close paren) and
- * ALTER TABLE … ADD COLUMN statements. Returns a `Record<table, columns>` with
- * lowercased, deduplicated column names, so the schema reducer can answer
- * "does THIS table carry a tenant-scoping column?" — the per-query question the
- * flat set cannot.
+ * Extract per-table foreign-key references from migration SQL. Covers the DDL
+ * spellings of a reference:
+ *
+ *   - column-level:  `org_id INTEGER REFERENCES organizations(id)`
+ *   - table-level:   `FOREIGN KEY (org_id) REFERENCES organizations(id)`
+ *   - ALTER:         `ALTER TABLE t ADD CONSTRAINT fk FOREIGN KEY (col) REFERENCES other(col)`
+ *
+ * Returns lowercased SQL names keyed by the declaring table. The reference is a
+ * separate fact from PK/UNIQUE/NOT NULL (Spec 69 R3 — each constraint recorded
+ * separately), so a rule can trace which column links to which other table.
  * @param source Migration/DDL SQL text.
- * @returns Per-table lowercased column-name lists.
+ * @param dialect The corpus's named dialect; null is honest abstention — no
+   *   parse under a guessed {@link DEFAULT_SQL_DIALECT} (unproven, cannot-fire).
+ * @returns Per-table foreign-key references.
  */
-export function extractDdlTableColumns(source) {
-    const tableColumns = new Map();
-    const columnsFor = (table) => {
-        let cols = tableColumns.get(table);
-        if (!cols) {
-            cols = new Set();
-            tableColumns.set(table, cols);
+export function extractDdlForeignKeys(source, dialect) {
+    if (dialect === null)
+        return {}; // honest abstention — no parse under a guessed dialect
+    const { statements } = parseSqlProgramTolerant(source, dialect);
+    const fks = new Map();
+    const fksFor = (table) => {
+        let list = fks.get(table);
+        if (!list) {
+            list = [];
+            fks.set(table, list);
         }
-        return cols;
+        return list;
     };
-    const createRe = /\bCREATE\s+(?:VIRTUAL\s+)?TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?(`[^`]+`|"[^"]+"|\w+)\s*\(/gi;
-    let match;
-    while ((match = createRe.exec(source)) !== null) {
-        const table = stripIdentifier(match[1]);
-        const openParen = createRe.lastIndex - 1;
-        let depth = 0;
-        let closeParen = -1;
-        let inString = null;
-        for (let i = openParen; i < source.length; i++) {
-            const ch = source[i];
-            if (inString) {
-                if (ch === inString)
-                    inString = null;
-                continue;
-            }
-            if (ch === '"' || ch === "'" || ch === '`') {
-                inString = ch;
-                continue;
-            }
-            if (ch === '(')
-                depth++;
-            else if (ch === ')') {
-                depth--;
-                if (depth === 0) {
-                    closeParen = i;
-                    break;
+    // Dedupe by (column, refTable, refColumn) — the same FK is often re-declared
+    // in a later migration (DROP + re-ADD), and the replay keeps the last CREATE.
+    const seen = new Set();
+    for (const stmt of statements) {
+        for (const fk of astDdlForeignKeys(stmt)) {
+            const refTable = stripIdentifier(fk.referencesTable).toLowerCase();
+            const refCols = fk.referencesColumns.map((c) => stripIdentifier(c).toLowerCase());
+            const cols = fk.columns.map((c) => stripIdentifier(c).toLowerCase());
+            for (let i = 0; i < cols.length; i++) {
+                const key = `${cols[i]}|${refTable}|${refCols[i] ?? ''}`;
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    fksFor(fk.table).push({ column: cols[i], refTable, refColumn: refCols[i] ?? '' });
                 }
             }
         }
-        if (closeParen === -1) {
-            createRe.lastIndex = openParen + 1;
-            continue;
-        }
-        const cols = columnsFor(table);
-        const body = source.slice(openParen + 1, closeParen);
-        for (const def of splitColumnDefs(body)) {
-            const name = leadingColumnName(def);
-            if (name)
-                cols.add(name.toLowerCase());
-        }
-        createRe.lastIndex = closeParen + 1;
-    }
-    const alterRe = /\bALTER\s+TABLE\s+(?:IF\s+EXISTS\s+)?(`[^`]+`|"[^"]+"|\w+)\s+ADD\s+(?:COLUMN\s+)?(?:IF\s+NOT\s+EXISTS\s+)?(`[^`]+`|"[^"]+"|\w+)/gi;
-    while ((match = alterRe.exec(source)) !== null) {
-        columnsFor(stripIdentifier(match[1])).add(stripIdentifier(match[2]).toLowerCase());
     }
     const result = {};
-    for (const [table, cols] of tableColumns)
-        result[table] = [...cols];
+    for (const [table, list] of fks)
+        result[table] = list;
     return result;
 }
 /**
@@ -229,16 +471,54 @@ export function extractDdlTableColumns(source) {
  * column?" without materializing per-table column lists. The flat union of
  * {@link extractDdlTableColumns}.
  * @param source Migration/DDL SQL text.
+ * @param dialect The corpus's named dialect; null is honest abstention — no
+   *   parse under a guessed {@link DEFAULT_SQL_DIALECT} (unproven, cannot-fire).
  * @returns The set of column names declared across the source.
  */
-export function extractDdlColumnNames(source) {
+export function extractDdlColumnNames(source, dialect) {
     const columns = new Set();
-    for (const cols of Object.values(extractDdlTableColumns(source))) {
+    for (const cols of Object.values(extractDdlTableColumns(source, dialect))) {
         for (const c of cols)
             columns.add(c);
     }
     return [...columns];
 }
+/**
+ * Extract the DDL SQL fragments embedded in host-language source — the TS/JS
+ * migration files whose `CREATE/DROP/ALTER TABLE` statements live inside string
+ * or template literals (Durable-Object-local DDL and raw `sql.exec(...)` bodies
+ * that migration discovery never sees). This is the literal-*extraction* half of
+ * that path: the raw TS/JS text carries the SQL verbatim inside the literals, so
+ * this names the strings to hand to the AST extractors — it is NOT itself a SQL
+ * parse, and it is deliberately NOT a general "find SQL anywhere" sweep. It only
+ * matches a literal that contains a CREATE/DROP/ALTER TABLE (or VIRTUAL TABLE)
+ * header, the same boundary the legacy schema-code visitor drew; every matched
+ * fragment is then parsed by {@link parseMigrationOps} /
+ * {@link extractDdlTableColumns} downstream.
+ *
+ * Returns the fragments joined as a `;`-separated program (so a template literal
+ * holding several statements parses as one), or `null` when the source carries no
+ * DDL-bearing literal.
+ * @param source The raw TS/JS (or other host-language) source text.
+ * @returns Pure SQL for the DDL extractors, or null when none is present.
+ */
+export function extractDdlSqlFromSource(source) {
+    const templateRe = /`([^`]*(?:CREATE|DROP|ALTER)\s+(?:TABLE|VIRTUAL\s+TABLE)\s+[^`]+)`/gis;
+    const stringRe = /(["'])((?:\s*(?:CREATE|DROP|ALTER)\s+(?:TABLE|VIRTUAL\s+TABLE)\s+[^"']+))\1/gis;
+    const fragments = [];
+    let m;
+    while ((m = templateRe.exec(source)) !== null) {
+        const sql = m[1].trim();
+        if (sql)
+            fragments.push(sql);
+    }
+    while ((m = stringRe.exec(source)) !== null) {
+        const sql = m[2].trim();
+        if (sql)
+            fragments.push(sql);
+    }
+    return fragments.length > 0 ? fragments.join(';\n') : null;
+}
 // ── One-hop barrel re-export resolution (Spec 33 item 9) ─────────────────────
 /**
  * Extract `export * from 'x'` and `export { a, b as c } from 'x'` statements
@@ -325,56 +605,26 @@ export function readModuleFromDisk(fromFile, specifier) {
         return null;
     }
 }
-/** Lightweight DDL presence marker — detection only, no capture groups. */
-const DDL_PRESENCE_RE = /(?:CREATE|DROP|ALTER)\s+(?:VIRTUAL\s+)?TABLE/i;
-/**
- * Detect whether an SQL file contains any DDL statement without materializing
- * the whole file. Streams in 1 MB chunks, carrying a small tail across chunk
- * boundaries so a marker split at "CREATE TA/BLE" is still caught. Used by the
- * schema-sql visitor for oversized orphans yielded with empty source by stage 1.
- * @param filePath
- * @returns
- */
-export async function sqlFileHasDdl(filePath) {
-    const CHUNK = 1024 * 1024; // 1 MB
-    const CARRY = 32; // "ALTER VIRTUAL TABLE IF NOT EXISTS" — enough to bridge a boundary
-    const handle = await fs.open(filePath, 'r');
-    try {
-        const buffer = Buffer.alloc(CHUNK);
-        let carry = '';
-        let pos = 0;
-        for (;;) {
-            const { bytesRead } = await handle.read(buffer, 0, CHUNK, pos);
-            if (bytesRead === 0)
-                break;
-            const text = carry + buffer.toString('utf8', 0, bytesRead);
-            if (DDL_PRESENCE_RE.test(text))
-                return true;
-            carry = text.slice(-CARRY);
-            pos += bytesRead;
-        }
-        return false;
-    }
-    finally {
-        await handle.close();
-    }
-}
 /**
  * Extract migration ops from an SQL file, honoring stage-1 streaming: when
- * `sourceCode` is empty the file was too large to materialize, so DDL presence
- * is detected by streaming; only a real oversized migration is read in full
- * (rare). Returns a `skipped` flag so the pipeline can surface the skip in
- * coverage without emitting a violation.
+ * `sourceCode` is empty the file was too large to materialize, so it is read in
+ * full only to answer "is this a migration or a data dump?" — the AST successor
+ * to site #8's streaming `CREATE|DROP|ALTER TABLE` regex. The parsed statements
+ * decide: a file with no table DDL is a data dump and is skipped (surfaced in
+ * coverage, no violation); one with table DDL has its ops/columns extracted.
+ * Only a real oversized migration is read in full (rare).
  * @param filePath
  * @param sourceCode
+ * @param dialect The corpus's named dialect; null is honest abstention — no
+ *   parse under a guessed {@link DEFAULT_SQL_DIALECT} (unproven, cannot-fire).
  * @returns
  */
-export async function extractMigrationOpsFromFile(filePath, sourceCode) {
+export async function extractMigrationOpsFromFile(filePath, sourceCode, dialect) {
     if (sourceCode !== '') {
         return {
-            ops: parseMigrationOps(sourceCode),
-            columns: extractDdlColumnNames(sourceCode),
-            tableColumns: extractDdlTableColumns(sourceCode),
+            ops: parseMigrationOps(sourceCode, dialect),
+            columns: extractDdlColumnNames(sourceCode, dialect),
+            tableColumns: extractDdlTableColumns(sourceCode, dialect),
             skipped: false,
             bytes: Buffer.byteLength(sourceCode),
         };
@@ -390,14 +640,21 @@ export async function extractMigrationOpsFromFile(filePath, sourceCode) {
         // Empty or small file whose read produced an empty string — nothing to do.
         return { ops: [], columns: [], tableColumns: {}, skipped: false, bytes: size };
     }
-    if (!(await sqlFileHasDdl(filePath))) {
+    const full = await fs.readFile(filePath, 'utf-8');
+    if (dialect === null) {
+        // Honest abstention — a null dialect must not guess sqlite just to answer
+        // "migration or data dump". Report no ops/columns and let the caller's
+        // dialect-undetermined cannot-fire reason carry the abstention.
+        return { ops: [], columns: [], tableColumns: {}, skipped: false, bytes: size };
+    }
+    const { statements } = parseSqlProgramTolerant(full, dialect);
+    if (!statements.some((stmt) => isDdlStatement(stmt))) {
         return { ops: [], columns: [], tableColumns: {}, skipped: true, bytes: size };
     }
-    const full = await fs.readFile(filePath, 'utf-8');
     return {
-        ops: parseMigrationOps(full),
-        columns: extractDdlColumnNames(full),
-        tableColumns: extractDdlTableColumns(full),
+        ops: statements.flatMap((stmt) => ddlMigrationOps(stmt)),
+        columns: extractDdlColumnNames(full, dialect),
+        tableColumns: extractDdlTableColumns(full, dialect),
         skipped: false,
         bytes: size,
     };