code-auditor-mcp 4.1.0 → 5.0.1

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

@@ -8,11 +8,14 @@
  * identical to the original class method (minus `this`). Violations are built
  * with `createSchemaViolation` instead of `this.createViolation`.
  */
-import { isDBProvenanced, DB_CALL_METHODS } from '../../provenance.js';
+import { getCallExpressionCallee, getMemberExpressionReceiver, extractMemberExpressionProperty, resolveSiteDialect, } from '../../provenance.js';
+import { identifyHandle } from '../../handleIdentification.js';
+import { resolveReceiverRoot, buildBindingEnv } from '../../receiverRoot.js';
 import { OrmAdapterRegistry } from '../../orm/index.js';
-import { SQL_TAG_NAMES, DB_CALL_METHOD_NAMES, DB_RECEIVER_NAMES, SQL_CARRYING_METHOD_NAMES, DEFAULT_SCHEMA_CONFIG } from './config.js';
+import { SQL_TAG_NAMES, DEFAULT_SCHEMA_CONFIG } from './config.js';
 import { createSchemaViolation } from './violations.js';
 import { isTestOrSpecPath } from '../../../languages/testConventions.js';
+import { parseSqlProgramTolerant, collectTypedRelations, DEFAULT_SQL_DIALECT } from '../../../languages/sql/sqlAst.js';
 /**
  * Extract table references from a TypeScript/JavaScript AST.
  *
@@ -28,30 +31,38 @@ import { isTestOrSpecPath } from '../../../languages/testConventions.js';
 export function findTableReferences(ast, adapter, sourceCode, ctx) {
     const references = [];
     const unresolved = [];
+    const unparseable = [];
     // (1) Tagged template SQL — e.g. sql`SELECT * FROM heroes`
-    references.push(...extractTaggedTemplateRefs(ast, adapter, sourceCode, ctx));
+    const taggedRefs = extractTaggedTemplateRefs(ast, adapter, sourceCode, ctx);
+    references.push(...taggedRefs.references);
+    unparseable.push(...taggedRefs.unparseable);
     // (2) DB-call patterns — e.g. db.exec("SELECT * FROM heroes")
     const dbRefs = extractDbCallRefs(ast, adapter, sourceCode, ctx);
     references.push(...dbRefs.references);
     unresolved.push(...dbRefs.unresolved);
+    unparseable.push(...dbRefs.unparseable);
     // (3) .sql files — scan the entire source (the whole file IS SQL).
     if (ast.filePath.endsWith('.sql')) {
-        const fileRefs = parseSqlTables(sourceCode, { line: 1, column: 1 }, sourceCode, ctx.allTables);
-        references.push(...fileRefs);
+        const fileRefs = parseSqlTables(sourceCode, { line: 1, column: 1 }, sourceCode, ctx.allTables, ctx.config.sqlDialect ?? null, ctx.config.sqlDialectReason ?? null);
+        references.push(...fileRefs.references);
+        unparseable.push(...fileRefs.unparseable);
     }
     // (4) Spec 15 R2 — ORM-aware extraction (Drizzle + Prisma)
     references.push(...extractOrmRefs(ast, adapter, sourceCode));
     // (5) knex-style query-builder reads — db('table').select(...) / .where(...) / .first(...)
     references.push(...extractQueryBuilderRefs(ast, adapter, sourceCode, ctx));
-    return { references, unresolved };
+    // (6) table-backed collection-facade constructors — new SqliteCollectionAdapter(db, 't')
+    references.push(...extractCollectionAdapterRefs(ast, adapter, sourceCode));
+    return { references, unresolved, unparseable };
 }
 /**
  * Strategy (1): tagged-template SQL — e.g. sql`SELECT * FROM heroes`.
  * This is a syntax feature, not a naming convention — keep the sqlTagNames gate.
  */
 function extractTaggedTemplateRefs(ast, adapter, sourceCode, ctx) {
-    const { config, allTables } = ctx;
+    const { config, allTables, provenanceContext } = ctx;
     const references = [];
+    const unparseable = [];
     const sqlTags = config.sqlTagNames ?? [...SQL_TAG_NAMES];
     const taggedTemplates = adapter.findNodes(ast, {
         custom: (node) => {
@@ -70,80 +81,173 @@ function extractTaggedTemplateRefs(ast, adapter, sourceCode, ctx) {
         if (!templateText)
             continue;
         const location = getCallLocation(callNode);
-        references.push(...parseSqlTables(templateText, location, sourceCode, allTables));
+        // Spec 70 (per-site dialect) — a tag imported from `postgres` (the `postgres`
+        // package's `sql\`…\``) is postgres, not whatever the repo-level detection
+        // names. Resolves from the tag identifier's package, else falls back.
+        const siteDialect = resolveSiteDialect(callNode, adapter, sourceCode, provenanceContext);
+        const parsed = parseSqlTables(templateText, location, sourceCode, allTables, siteDialect ?? config.sqlDialect ?? null, siteDialect ? null : (config.sqlDialectReason ?? null));
+        references.push(...parsed.references);
+        unparseable.push(...parsed.unparseable);
     }
-    return references;
+    return { references, unparseable };
+}
+/**
+ * Spec 70 R1.2 — the schema family's DB-call admission funnels through
+ * `identifyHandle` (the one entry point) instead of the boolean
+ * `isDBProvenanced`. A `handle` or `unproven` verdict admits the call — an
+ * `unproven` receiver whose type annotation is no longer a handle test
+ * (criterion 9) stays visible so `unresolved-query` / `unparseable` report its
+ * SQL as unreadable rather than silently clean; `not-handle` drops it. `null`
+ * means "not a query-shaped call" (a non-DB/ORM method, or a name with no DB
+ * signal at all). Admission is tri-state, not boolean.
+ */
+function dbCallVerdict(node, ast, adapter, sourceCode, ctx) {
+    const { provenanceContext, config, handleEnv } = ctx;
+    if (!provenanceContext || provenanceContext.mode === 'names')
+        return null;
+    const callee = getCallExpressionCallee(node, adapter);
+    if (!callee)
+        return null;
+    // The declaration-resolution env `identifyHandle` reads. Production threads it
+    // (`handleEnv`); a direct caller that seeded only `dbProvenanced` (unit tests)
+    // falls back to a freshly-built env over that provenance — the same evidence the
+    // boolean `isDBProvenanced` gate this replaced consumed, so a seeded-provenanced
+    // receiver still admits and its SQL still reaches `parseSqlTables`.
+    const env = handleEnv ?? {
+        provenance: provenanceContext.dbProvenanced,
+        bindings: buildBindingEnv(ast, adapter, sourceCode),
+        adapter,
+        sourceCode,
+    };
+    const dialect = resolveSiteDialect(node, adapter, sourceCode, provenanceContext) ??
+        config.sqlDialect ?? null;
+    const facts = () => ({
+        imports: new Map(),
+        typeAnnotations: new Map(),
+        bindings: new Map(),
+        withinFileProvenance: new Map(),
+        sqlDialect: dialect,
+        resolution: { dialect: 'ts', env },
+    });
+    // Bare-identifier call (`query(…)` / `d1(…)`): a provenanced wrapper or a
+    // type-annotated handle — the seam decides. A truly unbound name carries no DB
+    // signal, so it is rejected before its SQL argument could prove handle-ness.
+    if (callee.type === 'identifier') {
+        const name = adapter.getNodeText(callee, sourceCode);
+        if (!name)
+            return null;
+        const binding = env.bindings.get(name);
+        const isProvenanced = provenanceContext.dbProvenanced.has(name);
+        const isTypeAnnotated = !!binding && !!binding.typeText;
+        if (!isProvenanced && !isTypeAnnotated)
+            return null;
+        return identifyHandle({
+            format: 'typescript',
+            root: name,
+            receiver: name,
+            method: name,
+            sqlArgument: getFirstStringArgument(node, adapter, sourceCode),
+            thisField: false,
+        }, facts());
+    }
+    if (callee.type !== 'member_expression' && callee.type !== 'selector_expression') {
+        return null;
+    }
+    const method = extractMemberExpressionProperty(callee, adapter, sourceCode);
+    if (!method)
+        return null;
+    // The package discriminant — not the method name — decides handle-ness
+    // (`identifyHandle` below). No method-name set gates admission here.
+    const root = resolveReceiverRoot(callee, adapter, sourceCode);
+    if (root === null)
+        return null;
+    const receiver = getMemberExpressionReceiver(callee, adapter, sourceCode) ?? root;
+    return identifyHandle({
+        format: 'typescript',
+        root,
+        receiver,
+        method,
+        sqlArgument: getFirstStringArgument(node, adapter, sourceCode),
+        thisField: receiverIsThisRootedLocal(callee, adapter),
+    }, facts());
+}
+/**
+ * Walk a member chain to see whether it bottoms out at `this`/`super`.
+ * @param callee - The member/selector expression to walk.
+ * @param adapter - The language adapter (drives child access).
+ * @returns True when the chain's root is `this` or `super`.
+ */
+export function receiverIsThisRootedLocal(callee, adapter) {
+    let current = callee;
+    while (current.type === 'member_expression' || current.type === 'selector_expression') {
+        const children = adapter.getChildren(current);
+        const firstChild = children.find((c) => c.type !== '.' && c.type !== 'property_identifier' && c.type !== 'field_identifier');
+        if (!firstChild)
+            return false;
+        current = firstChild;
+    }
+    return current.type === 'this' || current.type === 'super';
 }
 /**
  * Strategy (2): DB-call patterns — e.g. db.exec("SELECT * FROM heroes").
- * Spec 21: provenance-based isDBProvenanced when available, falling back to
- * the name-based isDbMemberCall for `names` mode / no context.
+ * Spec 70 R1.2: admission is decided once by {@link dbCallVerdict} (via
+ * `identifyHandle`); a `handle` or `unproven` receiver is a DB call, a
+ * `not-handle` receiver is not. There is no name-list fallback.
  */
 function extractDbCallRefs(ast, adapter, sourceCode, ctx) {
-    const { config, provenanceContext, allTables } = ctx;
+    const { provenanceContext, allTables, config } = ctx;
     const references = [];
     const unresolved = [];
+    const unparseable = [];
     const dbCalls = adapter.findNodes(ast, {
         custom: (node) => {
             if (node.type !== 'call_expression')
                 return false;
-            // Spec 21: Use provenance when available, fall back to name-based check
-            if (provenanceContext && provenanceContext.mode !== 'names') {
-                return isDBProvenanced(node, { adapter, sourceCode, context: provenanceContext, methods: DB_CALL_METHODS });
-            }
-            // Legacy name-based check for names mode / no context
-            const callee = getCallee(node, adapter, sourceCode);
-            if (!callee)
-                return false;
-            const dbMethods = config.dbCallMethods ?? [...DB_CALL_METHOD_NAMES];
-            const dbReceivers = config.dbReceiverNames ?? [...DB_RECEIVER_NAMES];
-            return isDbMemberCall(callee, dbMethods, dbReceivers);
+            const verdict = dbCallVerdict(node, ast, adapter, sourceCode, ctx);
+            return verdict !== null && verdict.kind !== 'not-handle';
         },
     });
     for (const callNode of dbCalls) {
         // A string/template argument is always SQL text, for *every* DB-call method:
         // node-sqlite3's `db.all(sql, cb)` / `db.run(sql, cb)` pass SQL as a literal
-        // just as D1's `db.prepare(sql)` does. Only the identifier-resolution path
-        // is method-gated — `batch`/`run`/`all`/`first` take a statements array or a
-        // bound-parameter object, so `db.batch(stmts)` (where `stmts` is an array)
-        // must not resolve `stmts` as SQL and emit a spurious `unresolved-query`.
-        const methodName = extractDbCallMethodName(callNode, adapter, sourceCode);
-        const resolveIdentifier = methodName === null ||
-            SQL_CARRYING_METHOD_NAMES.includes(methodName);
+        // just as D1's `db.prepare(sql)` does. "Is this argument SQL" is answered by
+        // the resolved value's shape, not by a method name list (Spec 70): a string
+        // literal is SQL, an array/object literal is a statements array / parameter
+        // object (not SQL), and anything unreadable stays `unresolved`.
         const location = getCallLocation(callNode);
-        const resolved = resolveQuerySql(callNode, ast, adapter, sourceCode, resolveIdentifier);
+        const resolved = resolveQuerySql(callNode, ast, adapter, sourceCode);
         if (resolved.sqlText !== null) {
-            references.push(...parseSqlTables(resolved.sqlText, location, sourceCode, allTables));
+            // §13 — a static SQL argument in a SQL position (provenanced receiver) is
+            // parsed, not regex-scanned. A named dialect that cannot parse it, or no
+            // dialect at all, is `cannot-fire` — surfaced by `parseSqlTables` as an
+            // unreadable statement rather than a silent empty reference set that
+            // `unknown-table` / `stale-table-reference` would read as clean.
+            // Spec 70 (per-site dialect) — the dialect is a property of the call site's
+            // receiver, not the repo: `pool.query(…)` where `pool` → `pg` parses as
+            // postgres even in a repo that also names `mysql2`. Falls back to the
+            // repo-level detection result only when the receiver doesn't resolve to a
+            // package (or resolves to a cross-dialect ORM).
+            const siteDialect = resolveSiteDialect(callNode, adapter, sourceCode, provenanceContext);
+            const parsed = parseSqlTables(resolved.sqlText, location, sourceCode, allTables, siteDialect ?? config.sqlDialect ?? null, siteDialect ? null : (config.sqlDialectReason ?? null));
+            references.push(...parsed.references);
+            unparseable.push(...parsed.unparseable);
         }
         else if (resolved.unresolved !== null) {
             unresolved.push(resolved.unresolved);
         }
     }
-    return { references, unresolved };
-}
-/**
- * Extract the method name from a DB call's callee, returning the final
- * identifier segment stripped of any chained call / type-argument text.
- * Handles bare identifiers (`query(...)`) and member expressions, including
- * chained ones (`db.prepare(sql).run()` → `run`, `env.DB.prepare(...)` →
- * `prepare`). Returns null only when the callee text cannot be read.
- */
-function extractDbCallMethodName(node, adapter, sourceCode) {
-    const callee = getCallee(node, adapter, sourceCode);
-    if (!callee)
-        return null;
-    const dotIdx = callee.lastIndexOf('.');
-    const segment = dotIdx === -1 ? callee : callee.substring(dotIdx + 1);
-    // Strip a chained argument list (`run(...)`) or generic type args (`all<Row>`).
-    const name = segment.replace(/[<(].*$/, '').trim();
-    return name.length > 0 ? name : null;
+    return { references, unresolved, unparseable };
 }
 /**
  * Strategy (4): ORM-aware extraction (Drizzle + Prisma) via the registered
  * adapter. Complements raw-SQL extraction by picking up ORM-specific patterns
  * like db.select().from(users) and prisma.user.findMany().
+ * @param ast - The file's parsed AST.
+ * @param adapter - The language adapter (for ORM adapter dispatch).
+ * @param sourceCode - The file's source text.
+ * @returns The ORM-extracted table references (empty when no ORM adapter applies).
  */
-function extractOrmRefs(ast, adapter, sourceCode) {
+export function extractOrmRefs(ast, adapter, sourceCode) {
     const references = [];
     const ormRegistry = OrmAdapterRegistry.getInstance();
     const ormAdapter = ormRegistry.getAdapterForFile(ast.filePath);
@@ -194,14 +298,22 @@ function extractOrmRefs(ast, adapter, sourceCode) {
  * schema violation, and feeding it into unknown-table floods a test-heavy corpus
  * and flips the fail-open ratio.
  */
-/** Extra knex/transaction receiver names beyond the configured DB receivers. */
+/** Knex/transaction receiver names for the fluent `receiver('table').method(` form.
+ *  Spec 69 §10: this is a structural knex idiom, not a name-list fallback — the
+ *  generic `db`/`database`/`sql`/`stmt` names are provenanced by declaration only. */
 const QUERY_BUILDER_RECEIVER_NAMES = ['trx', 'knex'];
-function extractQueryBuilderRefs(ast, adapter, sourceCode, ctx) {
+/** Strategy (5): fluent query-builder reads — `trx('table').method(` and the
+ *  `knex` receiver. Records the *read* only, tagged `origin: 'query-builder'`,
+ *  so a scratch/test table name carried in a fluent builder call is not a schema
+ *  violation and does not flood the naming/unknown-table/lifecycle checks.
+ * @param ast - The file's parsed AST.
+ * @param adapter - The language adapter (drives node discovery + text reads).
+ * @param sourceCode - The file's source text.
+ * @param ctx - Shared table-reference extraction context.
+ * @returns The query-builder table references (read-only, `origin: 'query-builder'`). */
+export function extractQueryBuilderRefs(ast, adapter, sourceCode, ctx) {
     const references = [];
-    const receivers = new Set([
-        ...(ctx.config.dbReceiverNames ?? [...DB_RECEIVER_NAMES]),
-        ...QUERY_BUILDER_RECEIVER_NAMES,
-    ]);
+    const receivers = new Set([...QUERY_BUILDER_RECEIVER_NAMES]);
     const calls = adapter.findNodes(ast, { type: 'call_expression' });
     for (const call of calls) {
         // Only the outermost call of a query chain carries the complete text and the
@@ -236,6 +348,64 @@ function extractQueryBuilderRefs(ast, adapter, sourceCode, ctx) {
 function normalizeQueryBuilderTable(table) {
     return table.split(/\s+as\s+/i)[0].trim();
 }
+/**
+ * Strategy (6): table-backed collection-facade constructors — e.g.
+ * `new SqliteCollectionAdapter(db, 'project_tasks')`.
+ *
+ * `SqliteCollectionAdapter` (src/codeIndex/sqliteCollection.ts) is a
+ * LokiJS-`Collection`-compatible facade over a SQLite table. Every statement it
+ * issues interpolates the table from an instance field — `SELECT * FROM
+ * "${this.tableName}"`, `INSERT INTO "${this.tableName}" (…)`, `UPDATE
+ * "${this.tableName}" …`, `DELETE FROM "${this.tableName}" …` — so the keyword-
+ * anchored `parseSqlTables` never sees the table name and the facade's reads and
+ * writes are both invisible to the schema-usage fact. The one place the table
+ * name is a string literal is the constructor call. Recognizing it records the
+ * *read* (the `find`/`findOne` SELECT) so a table seeded by a migration and then
+ * read through the facade is not flagged `written-never-read` — the
+ * `project_tasks` case: `new SqliteCollectionAdapter(db, 'project_tasks')` with
+ * reads through `this.tasksAdapter.find(...)`.
+ *
+ * Only the read is recorded, mirroring strategy (5)'s read-only choice: the
+ * facade's write verbs (`insert`/`update`/`remove`/`clear`) back tables that
+ * migrations already `CREATE`/`INSERT` seed, so the write is already in the fact
+ * and recording a second, unsourceable write from the constructor would
+ * double-count. The read is the missing half of the lifecycle pair. References
+ * are tagged `origin: 'collection-adapter'` — a real schema table, so naming/
+ * unknown-table checks still run on it (unlike 'query-builder'), but the
+ * discriminator lets the cross-domain analyzer recognise a table that is *only*
+ * seen through a facade.
+ */
+const COLLECTION_ADAPTER_NAMES = new Set(['SqliteCollectionAdapter']);
+/** Strategy (6): table-backed collection-facade constructors — `new
+ *  SqliteCollectionAdapter(db, 'table')`. Records the *read* the facade issues
+ *  (tagged `origin: 'collection-adapter'`) so a migration-seeded table read
+ *  through a facade is not flagged `written-never-read`; the facade's writes are
+ *  already seeded by migrations and left unrecorded to avoid double-counting.
+ * @param ast - The file's parsed AST.
+ * @param adapter - The language adapter (drives `new_expression` discovery).
+ * @param sourceCode - The file's source text.
+ * @returns The collection-facade table references (`origin: 'collection-adapter'`). */
+export function extractCollectionAdapterRefs(ast, adapter, sourceCode) {
+    const references = [];
+    const constructors = adapter.findNodes(ast, { type: 'new_expression' });
+    for (const node of constructors) {
+        const text = adapter.getNodeText(node, sourceCode).trim();
+        // `new SqliteCollectionAdapter(db, 'project_tasks')` — the first argument is
+        // the shared handle, the second is the literal table name the facade backs.
+        // `[^,]+` for the handle tolerates `this.db` / `db` / any receiver expression.
+        const m = /^new\s+([A-Za-z_$][\w$]*)\s*\(\s*[^,]+,\s*['"]([^'"]+)['"]/.exec(text);
+        if (!m || !COLLECTION_ADAPTER_NAMES.has(m[1]))
+            continue;
+        references.push({
+            table: m[2],
+            type: 'select',
+            location: node.location.start,
+            context: `new ${m[1]}(…, '${m[2]}')`,
+            origin: 'collection-adapter',
+        });
+    }
+    return references;
+}
 /** True when `call` is the object of a parent member_expression (it is chained
  *  into a further `.method(...)`), so it is not the outermost call of its chain. */
 function isChainedFurther(call, adapter) {
@@ -249,193 +419,106 @@ function isChainedFurther(call, adapter) {
     return object === call;
 }
 /**
- * SQL patterns anchored to SQL keywords (not arbitrary substrings).
+ * Parse SQL table names from a SQL text string via the node-sql-parser AST
+ * (Spec 70 §13). This is the schema family's successor to the keyword-regex
+ * scanner: relations come from a typed statement walk (`collectTypedRelations`),
+ * so a `FROM`/`JOIN`/`INSERT INTO`/`UPDATE`/`DELETE`/`CREATE TABLE` is read
+ * exactly where the grammar says it is, and a CTE name or an `ALTER … RENAME`
+ * target is subtracted from the walk instead of regex-guessed.
  *
- * Uses Unicode-aware \p{L} so non-Latin table names (日, 注文, пользователи)
- * are correctly matched — \w is ASCII-only. Spec 21 R5. No trailing \b:
- * greedy [\p{L}\p{N}_]* consumes the full identifier and \b after a closing
- * quote (non-word char) fails, blocking quoted-table extraction.
- */
-function sqlTablePatterns() {
-    return [
-        // `fromKeyword` marks the generic FROM pattern so the match loop can
-        // exclude `DELETE FROM` — a write context whose table is already captured
-        // by the DELETE pattern below. Without the gate, `DELETE FROM users` is
-        // also tagged `select`, misclassifying a delete-only table as read.
-        { regex: /\bFROM\s+([`"']?)([\p{L}_][\p{L}\p{N}_]*)\1/giu, type: 'select', fromKeyword: true },
-        { regex: /\bJOIN\s+([`"']?)([\p{L}_][\p{L}\p{N}_]*)\1/giu, type: 'select' },
-        // Spec 52 R2 — the four D1/SQLite upsert forms are writes. MySQL's
-        // `INSERT IGNORE INTO` (no OR) and `ON DUPLICATE KEY UPDATE` are
-        // deliberately out of scope: the classifier targets the D1/Workers SQLite
-        // dialect, and `ON DUPLICATE KEY UPDATE col = …` (no `SET`) would otherwise
-        // misfire the UPDATE pattern below onto the column name.
-        { regex: /\b(?:INSERT(?:\s+OR\s+(?:IGNORE|REPLACE))?|REPLACE)\s+INTO\s+([`"']?)([\p{L}_][\p{L}\p{N}_]*)\1/giu, type: 'insert' },
-        { regex: /\bUPDATE\s+([`"']?)([\p{L}_][\p{L}\p{N}_]*)\1/giu, type: 'update' },
-        { regex: /\bDELETE\s+FROM\s+([`"']?)([\p{L}_][\p{L}\p{N}_]*)\1/giu, type: 'delete' },
-        { regex: /\bCREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?([`"']?)([\p{L}_][\p{L}\p{N}_]*)\1/giu, type: 'create' },
-    ];
-}
-/**
- * Run the keyword-anchored SQL patterns over `cleaned`, skipping system
- * tables, table-valued functions, module-specifier FROMs, short CTE/alias
- * identifiers, and SQL keywords.
- */
-function matchSqlPatterns(ctx) {
-    const { sqlText, cleaned, baseLocation, sourceCode, allTables } = ctx;
-    const references = [];
-    for (const { regex, type, fromKeyword } of sqlTablePatterns()) {
-        // Create fresh regex since we might consume with exec
-        const re = new RegExp(regex.source, regex.flags);
-        let match;
-        while ((match = re.exec(cleaned)) !== null) {
-            const table = match[2]; // The table name (capture group 2)
-            if (!table || isSystemTable(table) || isTableValuedFunction(table))
-                continue;
-            // Skip JS/TS module specifiers (`import x from 'mod'`) that step (3)'s
-            // full-source scan of migration `.ts` files otherwise captures as tables.
-            if (isModuleImportFrom(cleaned, match.index))
-                continue;
-            // `DELETE FROM` is a write, not a read — the DELETE pattern below already
-            // classifies the table, so the generic FROM pattern must not also tag it
-            // `select` (Spec 56 R4 finding: a delete-only table was misread as
-            // also-read, suppressing written-never-read).
-            if (fromKeyword && isDeleteFrom(cleaned, match.index))
-                continue;
-            // Skip very short identifiers (likely CTE names / bare aliases like 'x',
-            // 't', 'o', 'c') unless they are known table names — the guard catches
-            // false positives from single-char CTE/alias identifiers.
-            if (!isSqlKeyword(table) && table.length < 3 && !allTables?.has(table.toLowerCase()))
-                continue;
-            // Skip common false positives: common variable names, keywords
-            if (isSqlKeyword(table))
-                continue;
-            // Calculate position in original source. Anchor against `sqlText` — the
-            // original SQL, which appears verbatim in the source — NOT `cleaned`, which
-            // carries `__TMPL__` sentinels for `${…}` substitutions that never appear
-            // in the source. `sourceCode.indexOf(cleaned)` returns -1 for any
-            // interpolated template, collapsing every anchor to a plausible-but-wrong
-            // line. An `indexOf` that returns -1 is a bug, not a fallback — throw
-            // rather than mis-place (same guard the severity lookup uses for `undefined`).
-            if (match[0].includes('__TMPL__')) {
-                // The match overlaps a template substitution (a templated table name);
-                // there is no verbatim anchor to point at, and the reference is filtered
-                // out downstream — skip it rather than fabricate a location.
-                continue;
-            }
-            const sqlAbs = sourceCode.indexOf(sqlText);
-            if (sqlAbs < 0) {
-                throw new Error(`parseSqlTables: SQL text not found in source — a table reference that cannot be anchored is a bug, not something to mis-place.`);
-            }
-            const offset = sqlText.indexOf(match[0]);
-            if (offset < 0) {
-                throw new Error(`parseSqlTables: match "${match[0]}" not found in SQL text — a table reference that cannot be anchored is a bug, not something to mis-place.`);
-            }
-            const location = offsetToLocation(sourceCode, sqlAbs + offset, baseLocation);
-            references.push({
-                table,
-                type,
-                location,
-                context: match[0].trim(),
-            });
-        }
-    }
-    return references;
-}
-/**
- * Parse a SQL string (possibly with template expressions) into table references.
+ * Contract (Spec 70): a named dialect that cannot parse the SQL is *unreadable*,
+ * not "no tables". A null dialect does not skip the parse (R2: parsing a literal
+ * does not require proving the site's dialect first) — the SQL is attempted under
+ * {@link DEFAULT_SQL_DIALECT}; when it parses, the tables are derived; when it
+ * fails, the record is `cannot-fire` naming **both** the parse failure and the
+ * undetermined dialect (the failure may be dialect-specific syntax). Either way
+ * a failure is returned as an `unparseable` record, never a silent empty
+ * reference set that `unknown-table` / `stale-table-reference` would read clean.
  *
  * @param sqlText The SQL text to parse.
- * @param baseLocation Location of the SQL text within its source file.
- * @param sourceCode The full source file contents.
- * @param allTables Optional known table set for match filtering.
- * @returns Table references discovered in the SQL text.
+ * @param baseLocation The line/column of the SQL text's start in `sourceCode`.
+ * @param sourceCode The full source text (for offset-to-location mapping).
+ * @param allTables Known-table catalog used to keep short (1–2 char) identifiers.
+ * @param dialect The corpus's named dialect, or null when detection named none.
+ * @param dialectReason Why `dialect` is null (for the cannot-fire message).
+ * @returns Table references parsed from the SQL, plus unparseable statements.
  */
-export function parseSqlTables(sqlText, baseLocation, sourceCode, allTables) {
-    // R2.3: Strip template expressions — `${prefix}_builds` → `_builds`
-    // (the prefix is replaced with empty, the suffix remains for matching)
-    const cleaned = resolveTemplateExpressions(sqlText);
-    const ctx = { sqlText, cleaned, baseLocation, sourceCode, allTables };
-    let references = matchSqlPatterns(ctx);
-    // Template sentinel filter: resolveTemplateExpressions() replaces
-    // ${...} with __TMPL__. Strip these before alias extraction and
-    // before returning — __TMPL__ is never a real table name.
-    references = references.filter(ref => !ref.table.startsWith('__TMPL__'));
-    // Spec 22 R4.3: Filter out alias identifiers.
-    // "FROM x AS t" defines t as an alias; later references like "JOIN t.posts"
-    // would capture t via the JOIN regex. Scan for explicit AS aliases.
-    const aliasIds = extractAliasIdentifiers(cleaned);
-    if (aliasIds.size > 0) {
-        return references.filter(ref => !aliasIds.has(ref.table.toLowerCase()));
+export function parseSqlTables(sqlText, baseLocation, sourceCode, allTables, dialect, dialectReason) {
+    const references = [];
+    const unparseable = [];
+    const trimmed = sqlText.trim();
+    if (trimmed.length === 0)
+        return { references, unparseable };
+    const program = parseSqlProgramTolerant(sqlText, dialect ?? DEFAULT_SQL_DIALECT, false);
+    for (const failure of program.failures) {
+        unparseable.push({
+            sqlText,
+            location: baseLocation,
+            reason: dialect === null
+                ? `${dialectReason ?? 'dialect undetermined (no database driver in package.json or wrangler.toml)'} — and the SQL does not parse under the default ${DEFAULT_SQL_DIALECT} grammar: ${failure.reason}`
+                : failure.reason,
+            kind: dialect === null ? 'dialect-undetermined' : 'parse-failure',
+        });
     }
-    return references;
+    if (program.statements.length === 0)
+        return { references, unparseable };
+    // Anchor the SQL text against the source exactly once. The raw `sqlText`
+    // (still carrying `${…}`) appears verbatim in the source; the normalized
+    // parse input does not. An absent match is a bug, not a fallback — throw
+    // rather than mis-place every reference onto a wrong line.
+    const sqlAbs = sourceCode.indexOf(sqlText);
+    if (sqlAbs < 0) {
+        throw new Error(`parseSqlTables: SQL text not found in source — a table reference that cannot be anchored is a bug, not something to mis-place.`);
+    }
+    references.push(...extractSqlTables(collectTypedRelations(program.statements, new Set(program.truncatedConflictIndices)), sqlText, sqlAbs, baseLocation, sourceCode, allTables));
+    return { references, unparseable };
 }
 /**
- * Spec 22 R4.3: Extract alias identifiers from SQL text.
- *
- * Detects both explicit (`FROM x AS t`) and bare (`FROM x t`) aliases
- * so they can be filtered from table-references in parseSqlTables().
- * Without this, "JOIN t.posts" captures t via the JOIN regex when t is
- * an alias for the real table x.
- *
- * @param sqlText The SQL text to scan for alias identifiers.
- * @returns Lowercased alias identifiers to filter from table references.
+ * Convert typed AST relations into `TableReference`s, applying the same guards
+ * the regex scanner applied (system tables, table-valued functions, SQL
+ * keywords, short 1–2-char identifiers) and anchoring each to its source line.
  */
-export function extractAliasIdentifiers(sqlText) {
-    const aliases = new Set();
-    // CTE: WITH <name> AS ( — the CTE name is an alias, not a real table.
-    // Without this, "WITH fresh AS (SELECT ...)" causes 'fresh' to be
-    // captured by FROM/JOIN/subquery patterns and flagged as unknown-table.
-    const cteRe = /\bWITH\s+([\p{L}_][\p{L}\p{N}_]*)\s+AS\s*\(/giu;
-    let m;
-    while ((m = cteRe.exec(sqlText)) !== null) {
-        aliases.add(m[1].toLowerCase());
-    }
-    // Explicit: FROM/JOIN <table> AS <alias>
-    const explicitRe = /\b(?:FROM|JOIN)\s+[\p{L}_][\p{L}\p{N}_]*\s+AS\s+([\p{L}_][\p{L}\p{N}_]*)\b/giu;
-    while ((m = explicitRe.exec(sqlText)) !== null) {
-        aliases.add(m[1].toLowerCase());
-    }
-    // Subquery bare alias: FROM (SELECT ...) <alias>
-    // The '(' stops the bare FROM/JOIN regex below because \w+ can't match it.
-    // Pattern: FROM/JOIN \s* \( ... \) \s* <alias>
-    const subqueryRe = /\b(?:FROM|JOIN)\s*\([^)]*\)\s+([\p{L}_][\p{L}\p{N}_]*)\b/giu;
-    while ((m = subqueryRe.exec(sqlText)) !== null) {
-        const alias = m[1];
-        if (!isSqlKeyword(alias)) {
-            aliases.add(alias.toLowerCase());
-        }
-    }
-    // Bare: FROM/JOIN <table> <alias> (alias is a bare identifier, not a keyword)
-    // Pattern: keyword + table + word — the third word is the alias if it's
-    // not a SQL keyword and not followed by '.' (table.column reference).
-    const bareRe = /\b(?:FROM|JOIN)\s+([\p{L}_][\p{L}\p{N}_]*)\s+([\p{L}_][\p{L}\p{N}_]*)\b/giu;
-    while ((m = bareRe.exec(sqlText)) !== null) {
-        const alias = m[2];
-        // Don't add if it looks like a keyword or is followed by '.' (table ref)
-        if (!isSqlKeyword(alias)) {
-            const afterMatch = sqlText.substring(m.index + m[0].length);
-            if (!/^\s*\./.test(afterMatch)) {
-                aliases.add(alias.toLowerCase());
-            }
-        }
+function extractSqlTables(relations, sqlText, sqlAbs, baseLocation, sourceCode, allTables) {
+    const references = [];
+    const lowerSql = sqlText.toLowerCase();
+    for (const rel of relations) {
+        const table = rel.table;
+        if (isSystemTable(table))
+            continue;
+        if (rel.db !== null && isSystemTable(`${rel.db}.${table}`))
+            continue;
+        if (isTableValuedFunction(table))
+            continue;
+        if (isSqlKeyword(table))
+            continue;
+        // Short 1–2-char identifiers are almost always CTE names / bare aliases
+        // (`x`, `t`, `o`) rather than real tables; keep one only when the catalog
+        // names it. (CTE names are already subtracted by collectTypedRelations.)
+        if (table.length < 3 && !allTables?.has(table.toLowerCase()))
+            continue;
+        const qualified = rel.db !== null ? `${rel.db}.${table}` : table;
+        references.push({
+            table,
+            type: rel.type,
+            location: anchorTable(table, lowerSql, sqlAbs, baseLocation, sourceCode),
+            context: `${rel.type} ${qualified}`,
+            ...(rel.conflictClauseTruncated ? { conflictClauseTruncated: true } : {}),
+        });
     }
-    return aliases;
+    return references;
 }
 /**
- * R2.3: Resolve template expressions in SQL text.
- *
- * Uses the sentinel `__TMPL__` instead of an empty string. An empty
- * replacement produces whitespace artifacts (e.g. `FROM   t WHERE`
- * when `${tableName}` is stripped), which causes the bare-alias regex
- * in extractAliasIdentifiers() to misalign: `t` lands in the table-name
- * capture group instead of the alias group, and is never denylisted.
- *
- * `__TMPL__` keeps the token boundaries intact so alias extraction
- * correctly identifies `t` as the alias. `__TMPL__` table references
- * are filtered in parseSqlTables().
+ * Anchor a table name to its source location. The node-sql-parser AST is
+ * location-free, so the anchor is the first case-insensitive occurrence of the
+ * bare name within the SQL text — a line-level attribution good enough for the
+ * lifecycle rules' per-function re-homing. When the name is not found (a quoted
+ * identifier the parser normalized, or a name only present via a substitution),
+ * fall back to the SQL text's own start.
  */
-export function resolveTemplateExpressions(text) {
-    return text.replace(/\$\{[^}]+\}/g, '__TMPL__');
+function anchorTable(table, lowerSql, sqlAbs, baseLocation, sourceCode) {
+    const idx = lowerSql.indexOf(table.toLowerCase());
+    const rel = idx >= 0 ? idx : 0;
+    return offsetToLocation(sourceCode, sqlAbs + rel, baseLocation);
 }
 /**
  * Return known table names within edit distance ≤ maxDist.
@@ -561,21 +644,28 @@ const DANGEROUS_SQL_PATTERNS = [
 ];
 /**
  * Evaluate a single dangerous-pattern match: skip parameterized queries and
- * taint-safe dynamic strings, else emit a dynamic-sql-construction violation.
+ * taint-safe dynamic strings, else produce a dynamic-sql-construction candidate.
  */
-function checkInjectionMatch(ctx, match) {
-    const { ast, adapter, sourceCode, symbolOrdinals, violations } = ctx;
-    // Parameterized queries pass a bound-params argument (`query(sql, params)`).
-    // When the matched literal is followed by `, params` the interpolated
-    // `${...}` segments are compile-time clauses whose `?` placeholders are
-    // bound by that argument — not an injection vector. The data-access
-    // analyzer's checkQuerySecurity applies the same signal.
-    const afterMatch = sourceCode.slice(match.index + match[0].length);
-    if (/^\s*,/.test(afterMatch))
-        return;
+function collectInjectionMatch(ctx, match) {
+    const { ast, adapter, sourceCode, symbolOrdinals } = ctx;
     const location = offsetToLocation(sourceCode, match.index, { line: 1, column: 1 });
     // Find enclosing function from the AST at this position
     const node = findClosestNodeAt(ast.root, location, adapter);
+    const callNode = findEnclosingCallExpression(node, adapter);
+    // Parameterized queries pass a bound-params argument (`query(sql, params)`).
+    // When the matched literal's enclosing call carries a second argument, the
+    // interpolated `${...}` segments are compile-time clauses whose `?`
+    // placeholders are bound by that argument — not an injection vector.  This is
+    // checked at the *call* level (two source forms below), not by looking for a
+    // comma immediately after the match: a *nested* template fragment inside the
+    // first argument — `query(\`...\${scope ? \` WHERE \${scope.clause}\` : ''}\`,
+    // scope?.params)` — ends the regex match at the inner template's backtick, so
+    // the `,` lands several characters later and a bare `^\s*,` lookahead misses
+    // it.  The data-access analyzer's checkQuerySecurity applies the same signal.
+    const afterMatch = sourceCode.slice(match.index + match[0].length);
+    if (/^\s*,/.test(afterMatch) || (callNode && callHasBindParams(callNode, adapter))) {
+        return null;
+    }
     // Taint-aware safety check (Spec 33 Item 11a): clear the finding when the
     // query argument's dynamic parts are all provably safe. The naive regex
     // cannot tell trusted-DDL interpolation (`query(\`CREATE TABLE ${name}...\`)`
@@ -583,18 +673,15 @@ function checkInjectionMatch(ctx, match) {
     // distinction is delegated to the adapter's dynamic-string safety analysis
     // (isSafeInterpolation / resolveLocalConstant) — the same signal the
     // data-access analyzer already trusts for sql-injection-risk.
-    const callNode = findEnclosingCallExpression(node, adapter);
     if (callNode && isAllDynamicPartsSafe(callNode, ast, adapter, sourceCode)) {
-        return;
+        return null;
     }
     const enclosingFn = node ? functionIdentityLabel(findEnclosingFunctionIdentity(node, adapter, ast.filePath)) : 'top-level';
     const baseSymbol = `${enclosingFn}:dynamic-sql-construction`;
     const ordinal = (symbolOrdinals.get(baseSymbol) ?? 0) + 1;
     symbolOrdinals.set(baseSymbol, ordinal);
     const symbol = ordinal > 1 ? `${baseSymbol}:${ordinal}` : baseSymbol;
-    violations.push(createSchemaViolation(ast.filePath, location, `SQL query built via string interpolation or concatenation in ${enclosingFn}; use parameterized queries.`, 
-    // User-controlled SQL built by interpolation is injectable now — critical.
-    { severity: 'critical', rule: 'dynamic-sql-construction', symbol }));
+    return { file: ast.filePath, line: location.line, column: location.column, enclosingFn, symbol };
 }
 /**
  * Detect potential SQL injection in query/execute calls.
@@ -604,24 +691,42 @@ function checkInjectionMatch(ctx, match) {
  * @param sourceCode The raw source text.
  * @returns SQL-injection violations.
  */
-export function checkSQLInjection(ast, adapter, sourceCode) {
-    const violations = [];
+export function collectDynamicSqlCandidates(ast, adapter, sourceCode) {
+    const candidates = [];
     const ctx = {
         ast,
         adapter,
         sourceCode,
         symbolOrdinals: new Map(),
-        violations,
     };
     for (const pattern of DANGEROUS_SQL_PATTERNS) {
         // Clone regex to reset state (global regexes track lastIndex)
         const re = new RegExp(pattern.source, pattern.flags);
         let match;
         while ((match = re.exec(sourceCode)) !== null) {
-            checkInjectionMatch(ctx, match);
+            const candidate = collectInjectionMatch(ctx, match);
+            if (candidate)
+                candidates.push(candidate);
         }
     }
-    return violations;
+    return candidates;
+}
+/**
+ * Detect potential SQL injection in query/execute calls (legacy emission form).
+ *
+ * Maps the collected candidates — the exact set `collectDynamicSqlCandidates`
+ * returns — to schema violations, so the legacy path and the phase path cannot
+ * diverge (parity by construction).
+ *
+ * @param ast The parsed file AST.
+ * @param adapter The language adapter for the file's syntax.
+ * @param sourceCode The raw source text.
+ * @returns SQL-injection violations.
+ */
+export function checkSQLInjection(ast, adapter, sourceCode) {
+    return collectDynamicSqlCandidates(ast, adapter, sourceCode).map((c) => createSchemaViolation(c.file, { line: c.line, column: c.column }, `SQL query built via string interpolation or concatenation in ${c.enclosingFn}; use parameterized queries.`, 
+    // User-controlled SQL built by interpolation is injectable now — critical.
+    { severity: 'critical', rule: 'dynamic-sql-construction', symbol: c.symbol }));
 }
 /**
  * Walk up from a node to the enclosing call_expression, if any.  Used by
@@ -637,6 +742,16 @@ function findEnclosingCallExpression(node, adapter) {
     }
     return null;
 }
+/** True when the call expression carries a second argument — the bound-params
+ *  argument of a parameterized `query(sql, params)` / `execute(sql, params)`.
+ *  Mirrors the argument-count signal `isWrapperFunctionWithBindParams` uses. */
+function callHasBindParams(callNode, adapter) {
+    const args = adapter.getChildren(callNode).find(c => adapter.getNodeType(c) === 'arguments');
+    if (!args)
+        return false;
+    const realArgs = adapter.getChildren(args).filter(c => !['(', ')', ','].includes(adapter.getNodeType(c)));
+    return realArgs.length >= 2;
+}
 /**
  * True when a dynamic query/execute string argument is provably safe to embed
  * in SQL — every interpolated sub-part is a compile-time constant, quote-escaped
@@ -747,7 +862,7 @@ export function hasTemplateArgument(node, adapter) {
         return false;
     for (const child of node.children) {
         const type = adapter.getNodeType(child);
-        if (type === 'template_string' || type === 'template_literal') {
+        if (type === 'template_string') {
             return true;
         }
     }
@@ -766,8 +881,16 @@ export function getTemplateText(node, adapter, sourceCode) {
         return null;
     for (const child of node.children) {
         const type = adapter.getNodeType(child);
-        if (type === 'template_string' || type === 'template_literal') {
-            return adapter.getNodeText(child, sourceCode).trim();
+        if (type === 'template_string') {
+            const text = adapter.getNodeText(child, sourceCode).trim();
+            // A template literal's source text includes its surrounding backticks
+            // (`` `SELECT …` ``). node-sql-parser rejects a statement wrapped in
+            // backticks, so strip them before handing the SQL to the AST parser —
+            // the same unwrap `getFirstStringArgument` already does for string args.
+            if (text.startsWith('`') && text.endsWith('`')) {
+                return text.slice(1, -1);
+            }
+            return text;
         }
     }
     return null;
@@ -790,8 +913,7 @@ export function getFirstStringArgument(node, adapter, sourceCode) {
             for (const arg of child.children) {
                 const argType = adapter.getNodeType(arg);
                 if (argType === 'string' ||
-                    argType === 'template_string' ||
-                    argType === 'template_literal') {
+                    argType === 'template_string') {
                     const text = adapter.getNodeText(arg, sourceCode).trim();
                     // Strip surrounding quotes from string literals
                     if ((text.startsWith("'") && text.endsWith("'")) ||
@@ -844,6 +966,16 @@ function unquoteLiteral(text) {
     }
     return null;
 }
+/**
+ * True when an initializer's source text is a structured literal — an array
+ * (`[...]`) or object (`{...}`) — rather than a string, call result, or
+ * identifier. A DB-call first argument that resolves to a structured literal
+ * is a statements array / bound-parameter object, not SQL text.
+ */
+function isStructuredLiteral(text) {
+    const t = text.trim();
+    return t.startsWith('[') || t.startsWith('{');
+}
 /**
  * Resolve the SQL text held by a DB call's first argument.
  *
@@ -851,30 +983,29 @@ function unquoteLiteral(text) {
  * identifier argument is resolved via the adapter's `resolveLocalConstant`
  * capability — a same-module `const` bound to a string/template literal yields
  * its SQL text (template substitutions are left in place; `parseSqlTables`
- * resolves them). Anything else (imported constant, reassigned/concatenated
- * expression, call result, parameter, unsupported language) is reported as
- * `unresolved` so the query is not silently treated as table-free.
+ * resolves them).
+ *
+ * "Is this argument SQL" is answered by the resolved value's shape, not by a
+ * method name list (Spec 70): a string/template literal is SQL; an array/object
+ * literal is a statements array or parameter object (not SQL, so it is skipped
+ * rather than reported as unresolvable); anything unreadable (imported constant,
+ * reassigned/concatenated expression, call result, parameter, unsupported
+ * language) is reported as `unresolved` so the query is not silently treated as
+ * table-free.
  *
  * @param callNode The DB call_expression node.
  * @param ast The full AST (for local-constant scope traversal).
  * @param adapter The language adapter for the file's syntax.
  * @param sourceCode The raw source text.
- * @param resolveIdentifier When false, skip identifier resolution entirely (the
- *   call's first argument is not SQL — e.g. `db.batch(stmts)`).
  * @returns The resolved SQL text, an unresolved-query record, or neither.
  */
-function resolveQuerySql(callNode, ast, adapter, sourceCode, resolveIdentifier = true) {
+export function resolveQuerySql(callNode, ast, adapter, sourceCode) {
     // Direct string/template argument — the common, fully-static path. This runs
     // for every DB-call method (node-sqlite3 `db.all(sql)` / `db.run(sql)` pass
     // SQL as a literal, not just `prepare`/`exec`).
     const direct = getFirstStringArgument(callNode, adapter, sourceCode);
     if (direct !== null)
         return { sqlText: direct, unresolved: null };
-    // Identifier resolution is method-gated by the caller: `batch`/`run`/`all`/
-    // `first` take statements/parameters, not SQL, so a bare identifier argument
-    // there is not SQL and must not be reported as unresolvable.
-    if (!resolveIdentifier)
-        return { sqlText: null, unresolved: null };
     // Bare identifier argument — resolve the local constant.
     const identNode = getFirstIdentifierArgument(callNode, adapter);
     if (!identNode)
@@ -894,8 +1025,13 @@ function resolveQuerySql(callNode, ast, adapter, sourceCode, resolveIdentifier =
     }
     const sqlText = unquoteLiteral(resolved.initText);
     if (sqlText === null) {
-        // initText is not a string literal — a call result, binary expr, or a
-        // chained identifier (`const B = A`). Cannot statically read the SQL.
+        // initText is not a string literal. A structured literal (array/object) is
+        // a statements array / parameter object, not SQL — skip it. Anything else
+        // (call result, binary expr, chained identifier `const B = A`) cannot be
+        // statically read, so the query is genuinely unseen.
+        if (isStructuredLiteral(resolved.initText)) {
+            return { sqlText: null, unresolved: null };
+        }
         return { sqlText: null, unresolved: { identifier, location } };
     }
     return { sqlText, unresolved: null };
@@ -907,6 +1043,9 @@ function resolveQuerySql(callNode, ast, adapter, sourceCode, resolveIdentifier =
  * file whose DB access is only partly visible. These are diagnostics — "the
  * tool could not see this query" — not findings that the code is wrong, so they
  * are non-blocking (see CoverageDiagnostic).
+ * @param unresolved The unresolved-query records to report.
+ * @param filePath The file path the diagnostics belong to.
+ * @returns Coverage diagnostics for each unresolved query.
  */
 export function checkUnresolvedQueries(unresolved, filePath) {
     return unresolved.map((u) => ({
@@ -919,21 +1058,145 @@ export function checkUnresolvedQueries(unresolved, filePath) {
     }));
 }
 /**
- * Check if a callee is a DB member call like db.exec, database.query, etc.
+ * Build `cannot-fire` coverage diagnostics for DB-call SQL whose static string
+ * argument a named dialect cannot parse (`PRAGMA table_info(x)`, `VACUUM`,
+ * `ANALYZE`, and other grammar gaps). These are the SQL-position siblings of the
+ * unresolvable-identifier `unresolved-query` diagnostic: the argument *is* read,
+ * but the parser cannot answer "which tables", so the table-read/write facts are
+ * unreadable rather than "no tables". Reporting (rather than letting
+ * `unknown-table` / `stale-table-reference` read an empty reference set as clean)
+ * is what keeps an unparseable statement visibly unreadable (Spec 70 R2).
  *
- * @param calleeText The callee text (e.g. "db.exec").
- * @param methods The allowed DB call method names.
- * @param receivers The allowed DB receiver names.
- * @returns True when the callee is a permitted receiver.method DB call.
+ * @param unparseable The unparseable-SQL records to report.
+ * @param filePath The file path the diagnostics belong to.
+ * @returns One `cannot-fire` diagnostic per unparseable SQL argument.
  */
-export function isDbMemberCall(calleeText, methods, receivers) {
-    // calleeText might be like "db.exec"
-    const dotIdx = calleeText.indexOf('.');
-    if (dotIdx === -1)
-        return false;
-    const receiver = calleeText.substring(0, dotIdx);
-    const method = calleeText.substring(dotIdx + 1);
-    return receivers.includes(receiver) && methods.includes(method);
+export function checkUnparseableSql(unparseable, filePath) {
+    return unparseable.map((u) => {
+        const why = u.kind === 'parse-failure'
+            ? `cannot be parsed ('${u.reason}')`
+            : `is ${u.reason}`;
+        return {
+            analyzerName: 'schema',
+            kind: 'cannot-fire',
+            message: `SQL statement ${why} — its table read/write status is unreadable, so cross-domain lifecycle rules (unknown-table, stale-table-reference) may be unreliable for this file.`,
+            file: filePath,
+            line: u.location.line,
+            details: { sql: u.sqlText, reason: u.reason, kind: u.kind },
+        };
+    });
+}
+/**
+ * Build `cannot-fire` coverage diagnostics for DB-looking imports whose
+ * specifier could not be resolved to an in-repo file. This is the Spec 69 §10
+ * coverage-parity signal: the deleted `DB_RECEIVER_NAMES` name-list fallback
+ * used to mark a receiver named `db`/`database`/`sql`/`stmt` as DB-provenanced
+ * even without a declaration. With that gone, a receiver imported from a
+ * non-resolvable `./db`-style specifier can no longer be provenanced by
+ * declaration, so any DB access through it is unseen. Reporting that as
+ * `cannot-fire` (rather than letting the affected rules report `clean`) is what
+ * prevents a silent regression — the coverage count must rise by exactly the
+ * amount the finding count falls.
+ *
+ * @param unresolved The unresolved-import records for this file (already
+ *   filtered to the current file by the caller).
+ * @param filePath The file path the diagnostics belong to.
+ * @returns One `cannot-fire` diagnostic per unresolved DB-looking import.
+ */
+export function checkUnresolvedReceiverImports(unresolved, filePath) {
+    return unresolved.map((u) => {
+        const reason = `import of ${u.names.length > 0 ? u.names.map((n) => `'${n}'`).join(', ') : 'a DB receiver'} ` +
+            `from '${u.source}' does not resolve to an in-repo file, so its DB provenance cannot be ` +
+            `established by declaration`;
+        return {
+            analyzerName: 'schema',
+            kind: 'cannot-fire',
+            message: `${reason}. DB access through this receiver is unseen: table-reference ` +
+                `and data-access rules may report clean on access they could not observe.`,
+            file: filePath,
+            line: 0,
+            // `reason` carries the same "why" the call-site shape (`checkUnprovenQueryReceivers`)
+            // carries in `details.reason` — a consumer reading `details.reason` must never
+            // see `undefined` for an unproven receiver, whichever emission path produced it.
+            details: { source: u.source, names: u.names, reason },
+        };
+    });
+}
+/**
+ * Build `cannot-fire` coverage diagnostics for query-shaped call sites whose
+ * receiver is unproven (Spec 69 §10 S5a — disposition replaces step-failure).
+ *
+ * The §10 guard is keyed to *the question being unanswered*, not to a resolution
+ * step failing: an unproven receiver — whether an unresolved import, a runtime
+ * binding (`env.DB`), an unannotated parameter, or a `new <wrapper-class>()` the
+ * resolution does not trace — must report `cannot-fire` with a reason, never
+ * `clean`. This is the per-call-site complement to
+ * {@link checkUnresolvedReceiverImports} (which is keyed to the import alone).
+ *
+ * @param unproven The unproven-query-receiver records for this file.
+ * @param filePath The file path the diagnostics belong to.
+ * @returns One `cannot-fire` diagnostic per unproven query receiver.
+ */
+export function checkUnprovenQueryReceivers(unproven, filePath) {
+    return unproven.map((u) => ({
+        analyzerName: 'schema',
+        kind: 'cannot-fire',
+        message: `Query-shaped call \`.${u.method}()\` on ${u.receiver}: ${u.reason}`,
+        file: filePath,
+        line: u.line,
+        details: { receiver: u.receiver, method: u.method, reason: u.reason },
+    }));
+}
+/**
+ * Deduplicate `cannot-fire` diagnostics so one receiver gets one disposition
+ * (Spec 69 §10 Q3).
+ *
+ * Two emission paths can both report the same unanswered question — "is this
+ * receiver a DB handle?" — for one receiver:
+ *
+ *   - {@link checkUnresolvedReceiverImports} — keyed to the *import* (`line: 0`,
+ *     `details.names`) for a receiver imported from an unresolvable `./db`-style
+ *     specifier.
+ *   - {@link checkUnprovenQueryReceivers} — keyed to the *call site* (real line,
+ *     `details.receiver`) for a query-shaped call through an unproven receiver.
+ *
+ * A receiver imported from an unresolvable specifier *and* called at a query
+ * site therefore produced two diagnostics for one unanswered question, doubling
+ * the coverage count and making the §10 finding↔coverage arithmetic reconcile
+ * when it should not.
+ *
+ * The call-site diagnostic wins: it carries the precise line and method. The
+ * import-level diagnostic is dropped for each name the call-site path already
+ * dispositioned (compared by bare receiver name — `this.db` → `db`), and
+ * survives only for names imported but never called, where it is the sole
+ * signal that a receiver is unseen.
+ *
+ * @param diagnostics The merged `cannot-fire` diagnostics for one file.
+ * @returns The same diagnostics, with redundant import-level signals removed.
+ */
+export function dedupeCannotFireByReceiver(diagnostics) {
+    const callSiteReceivers = new Set();
+    for (const d of diagnostics) {
+        const receiver = d.details?.receiver;
+        if (typeof receiver !== 'string' || receiver.length === 0)
+            continue;
+        const bare = receiver.split('.').pop() ?? receiver;
+        callSiteReceivers.add(`${d.file}${bare}`);
+    }
+    const out = [];
+    for (const d of diagnostics) {
+        const names = d.details?.names;
+        if (Array.isArray(names) && d.line === 0) {
+            const remaining = names.filter((n) => typeof n === 'string' && !callSiteReceivers.has(`${d.file}${n}`));
+            if (remaining.length === 0)
+                continue; // fully dispositioned by the call-site path
+            out.push({ ...d, details: { ...d.details, names: remaining } });
+        }
+        else {
+            out.push(d);
+        }
+    }
+    return out;
 }
 /**
  * Get the line/column location of the call expression.
@@ -981,6 +1244,34 @@ export function isSystemTable(table) {
     ];
     return systemTables.some(st => table.toLowerCase() === st || table.toLowerCase().startsWith(st + '.'));
 }
+const TABLE_VALUED_FUNCTIONS = new Set([
+    // SQLite
+    'json_each', 'json_tree',
+    // PostgreSQL
+    'unnest', 'generate_series', 'generate_subscripts',
+    'json_array_elements', 'jsonb_array_elements',
+    'json_array_elements_text', 'jsonb_array_elements_text',
+    'json_each_text', 'jsonb_each_text', 'jsonb_each',
+    'json_object_keys', 'jsonb_object_keys',
+    'regexp_split_to_table', 'string_to_table',
+    // DuckDB / ClickHouse-ish readers
+    'read_csv', 'read_csv_auto', 'read_parquet', 'read_json', 'read_json_auto',
+    'parquet_scan', 'csv_scan', 'glob', 'range',
+]);
+const SQL_KEYWORDS = new Set([
+    'select', 'from', 'where', 'join', 'inner', 'outer', 'left', 'right',
+    'full', 'cross', 'on', 'and', 'or', 'not', 'in', 'as', 'is', 'null',
+    'like', 'between', 'order', 'group', 'by', 'having', 'limit', 'offset',
+    'union', 'all', 'distinct', 'case', 'when', 'then', 'else', 'end',
+    'insert', 'into', 'values', 'update', 'set', 'delete', 'create',
+    'table', 'alter', 'drop', 'index', 'view', 'if', 'exists', 'primary',
+    'key', 'foreign', 'references', 'constraint', 'default', 'unique',
+    'check', 'asc', 'desc', 'count', 'sum', 'avg', 'min', 'max',
+    'skip', 'locked', 'nowait',
+    'integer', 'text', 'varchar', 'text', 'boolean', 'float', 'blob',
+    'real', 'timestamp', 'date', 'time', 'datetime', 'serial', 'bigint',
+    'the', 'a', 'an',
+]);
 /**
  * True when `name` is a SQL table-valued function rather than a real table.
  * These appear after FROM/JOIN (`FROM json_each(...)`, `FROM generate_series(...)`)
@@ -996,21 +1287,7 @@ export function isSystemTable(table) {
  * @returns True when `name` is a known table-valued function.
  */
 export function isTableValuedFunction(name) {
-    const tvfs = new Set([
-        // SQLite
-        'json_each', 'json_tree',
-        // PostgreSQL
-        'unnest', 'generate_series', 'generate_subscripts',
-        'json_array_elements', 'jsonb_array_elements',
-        'json_array_elements_text', 'jsonb_array_elements_text',
-        'json_each_text', 'jsonb_each_text', 'jsonb_each',
-        'json_object_keys', 'jsonb_object_keys',
-        'regexp_split_to_table', 'string_to_table',
-        // DuckDB / ClickHouse-ish readers
-        'read_csv', 'read_csv_auto', 'read_parquet', 'read_json', 'read_json_auto',
-        'parquet_scan', 'csv_scan', 'glob', 'range',
-    ]);
-    return tvfs.has(name.toLowerCase());
+    return TABLE_VALUED_FUNCTIONS.has(name.toLowerCase());
 }
 /**
  * Common SQL keywords and identifiers that are not real table names.
@@ -1019,77 +1296,7 @@ export function isTableValuedFunction(name) {
  * @returns True when `word` is a SQL keyword/reserved identifier.
  */
 export function isSqlKeyword(word) {
-    const keywords = new Set([
-        'select', 'from', 'where', 'join', 'inner', 'outer', 'left', 'right',
-        'full', 'cross', 'on', 'and', 'or', 'not', 'in', 'as', 'is', 'null',
-        'like', 'between', 'order', 'group', 'by', 'having', 'limit', 'offset',
-        'union', 'all', 'distinct', 'case', 'when', 'then', 'else', 'end',
-        'insert', 'into', 'values', 'update', 'set', 'delete', 'create',
-        'table', 'alter', 'drop', 'index', 'view', 'if', 'exists', 'primary',
-        'key', 'foreign', 'references', 'constraint', 'default', 'unique',
-        'check', 'asc', 'desc', 'count', 'sum', 'avg', 'min', 'max',
-        'skip', 'locked', 'nowait',
-        'integer', 'text', 'varchar', 'text', 'boolean', 'float', 'blob',
-        'real', 'timestamp', 'date', 'time', 'datetime', 'serial', 'bigint',
-        'the', 'a', 'an',
-    ]);
-    return keywords.has(word.toLowerCase());
-}
-/**
- * True when the `from` keyword at `fromIndex` is a JavaScript/TypeScript
- * module specifier (`import x from 'mod'`, `import { a } from 'mod'`,
- * `export { a } from 'mod'`, `export * from 'mod'`) rather than a SQL
- * FROM clause.
- *
- * Step (3) of findTableReferences() full-source scans `.ts` files under
- * `migrations/`, where a case-insensitive `\bFROM\s+([`"']?)...` pattern
- * matches `from 'typeorm'` / `from 'path'` / `from 'dotenv'` and records the
- * module name as an unknown table. SQL never introduces FROM with
- * `import`/`export`, so requiring that introducer at a statement boundary is
- * unambiguous — and only checking the introducer at a line/`;` boundary
- * avoids misreading a SQL comment (`-- import data`) or a table named
- * `import_log` as a module statement.
- *
- * @param sqlText The source text being scanned for a FROM introducer.
- * @param fromIndex The character index of the `from` keyword within `sqlText`.
- * @returns True when the introducer preceding `fromIndex` is an import/export.
- */
-export function isDeleteFrom(sqlText, fromIndex) {
-    // `DELETE FROM` is a write: the table is captured by the DELETE pattern, and
-    // the generic FROM pattern must not re-tag it as a read. Check whether the
-    // word immediately preceding the FROM keyword (across any whitespace) is
-    // `DELETE` — the only SQL keyword that introduces a write-FROM. `SELECT …
-    // FROM`, `JOIN`, and `INSERT INTO … SELECT … FROM` all keep their read FROM.
-    return /\bDELETE\s+$/iu.test(sqlText.slice(0, fromIndex));
-}
-/**
- * Whether the `from` keyword at `fromIndex` is the FROM of a module
- * `import`/`export` statement rather than the read-FROM of a SQL `SELECT`/`JOIN`.
- *
- * Scans back from `fromIndex` to the enclosing statement boundary (a `;` or a
- * blank line — a module introducer never crosses either) and checks that the
- * prefix is introduced by `import`/`export`. This keeps `SELECT … FROM`,
- * `JOIN …`, and `INSERT … SELECT … FROM` out of the module-import count while
- * letting `IMPORT … FROM` and `EXPORT … FROM` through.
- *
- * @param sqlText The source text being scanned.
- * @param fromIndex The character index of the `from` keyword within `sqlText`.
- * @returns True when the introducer preceding `fromIndex` is an import/export.
- */
-export function isModuleImportFrom(sqlText, fromIndex) {
-    let start = fromIndex;
-    while (start > 0) {
-        const prev = sqlText[start - 1];
-        // Stop at a statement terminator or a blank line — a module statement's
-        // `import`/`export` introducer never crosses these.
-        if (prev === ';')
-            break;
-        if (prev === '\n' && start >= 2 && sqlText[start - 2] === '\n')
-            break;
-        start--;
-    }
-    const prefix = sqlText.slice(start, fromIndex);
-    return /(?:^|[\n;])\s*(?:import|export)\b/m.test(prefix);
+    return SQL_KEYWORDS.has(word.toLowerCase());
 }
 /**
  * SQL statement keyword patterns that mark a query. Shared by the standalone
@@ -1100,21 +1307,74 @@ export function isModuleImportFrom(sqlText, fromIndex) {
  * statement, not a second query (Spec 52 R2).
  */
 const SQL_QUERY_PATTERNS = [
-    /SELECT\s+/gi,
-    /INSERT(?:\s+OR\s+(?:IGNORE|REPLACE))?\s+INTO|REPLACE\s+INTO/gi,
-    /(?<!DO\s)(?<!KEY\s)UPDATE\s+/gi,
-    /DELETE\s+FROM/gi,
+    { keyword: 'SELECT', pattern: /SELECT\s+/gi },
+    { keyword: 'INSERT', pattern: /INSERT(?:\s+OR\s+(?:IGNORE|REPLACE))?\s+INTO|REPLACE\s+INTO/gi },
+    { keyword: 'UPDATE', pattern: /(?<!DO\s)(?<!KEY\s)UPDATE\s+/gi },
+    { keyword: 'DELETE', pattern: /DELETE\s+FROM/gi },
 ];
-/** Number of SQL-statement keyword occurrences a text slice contains. */
-function countSqlKeywordOccurrences(text) {
+/** Number of SQL-statement keyword occurrences a text slice contains.
+ *
+ * @param text The text slice to count SQL keywords over.
+ * @returns The number of SQL-statement keyword occurrences.
+ */
+export function countSqlKeywordOccurrences(text) {
     let count = 0;
-    for (const pattern of SQL_QUERY_PATTERNS) {
+    for (const { pattern } of SQL_QUERY_PATTERNS) {
         const matches = text.match(pattern);
         if (matches)
             count += matches.length;
     }
     return count;
 }
+/** Located SQL-keyword occurrences — the offset form of
+ *  {@link countSqlKeywordOccurrences}, returning each keyword's start offset and
+ *  its label. The caller passes call-body-stripped text (same length as the
+ *  original, so offsets map 1:1 onto it). */
+function findSqlKeywordOffsets(text) {
+    const sites = [];
+    for (const { keyword, pattern } of SQL_QUERY_PATTERNS) {
+        pattern.lastIndex = 0;
+        let m;
+        while ((m = pattern.exec(text)) !== null) {
+            sites.push({ offset: m.index, method: keyword });
+        }
+    }
+    return sites;
+}
+/**
+ * Locate every DB-query site in a source slice — the located counterpart of
+ * {@link countQueries}. The three components match `countQueries` exactly (the
+ * eager execution-method call sites, the `.exec`-with-SQL sites, and the
+ * standalone SQL-keyword sites over the call-body-stripped text), so the two can
+ * never drift: `countQueries` is `extractQuerySiteOffsets(...).length`. Each
+ * site's `offset` points at the method name (for a call) or keyword start (for a
+ * standalone keyword), and `method` is the label the fact carries.
+ *
+ * @param text The source slice to scan.
+ * @returns One located site per query the slice issues.
+ */
+export function extractQuerySiteOffsets(text) {
+    const sites = [];
+    // Eager execution-method call sites.
+    const callRe = /\.(query|execute|run|first|raw|batch)\b[^()\n]*\(|(?<!Promise)\.(all)\b[^()\n]*\(/g;
+    let m;
+    while ((m = callRe.exec(text)) !== null) {
+        sites.push({ offset: m.index + 1, method: m[1] ?? m[2] });
+    }
+    // `.exec(...)` sites whose balanced body carries a SQL keyword.
+    const execRe = /\.exec\b[^()\n]*\(/g;
+    while ((m = execRe.exec(text)) !== null) {
+        const openParen = m.index + m[0].length;
+        const i = scanBalancedParens(text, openParen);
+        if (countSqlKeywordOccurrences(text.slice(openParen, i - 1)) > 0) {
+            sites.push({ offset: m.index + 1, method: 'exec' });
+        }
+        execRe.lastIndex = i;
+    }
+    // Standalone SQL keywords outside recognized call bodies.
+    sites.push(...findSqlKeywordOffsets(stripQueryCallBodies(text)));
+    return sites;
+}
 /**
  * Count the number of DB queries a function body issues — by *call site*, not
  * by SQL literal (defect #47: counting literals made parameterizing a query into
@@ -1142,11 +1402,7 @@ function countSqlKeywordOccurrences(text) {
  * @returns The number of DB queries the function issues.
  */
 export function countQueries(text) {
-    const callCount = (text.match(/\.(?:query|execute|run|first|raw|batch)\b[^()\n]*\(|(?<!Promise)\.all\b[^()\n]*\(/g) || []).length;
-    const execCount = countExecCallsWithSql(text);
-    const bodyless = stripQueryCallBodies(text);
-    const sqlCount = countSqlKeywordOccurrences(bodyless);
-    return callCount + execCount + sqlCount;
+    return extractQuerySiteOffsets(text).length;
 }
 /**
  * Scan forward from just after an opening `(` (at `openParen`) to the matching
@@ -1277,7 +1533,7 @@ const FUNCTION_NODE_TYPES = new Set([
     'function_declaration',
     'function_expression',
     'generator_function_declaration',
-    'generator_function_expression',
+    'generator_function',
     'method_definition',
 ]);
 /**
@@ -1290,6 +1546,10 @@ const FUNCTION_NODE_TYPES = new Set([
  * than carrying a divergent copy (the old copies differed only in whether the
  * walk started at `node` or `parent(node)`, which is equivalent for every real
  * call site, all of which hand in a leaf or call node, never a function node).
+ * @param node The AST node to start walking from.
+ * @param adapter The language adapter for parent/type traversal.
+ * @param filePath The file path recorded in the identity.
+ * @returns The enclosing function's identity (or a top-level identity).
  */
 export function findEnclosingFunctionIdentity(node, adapter, filePath) {
     let current = node;
@@ -1324,4 +1584,70 @@ export function functionIdentityLabel(id) {
         return 'top-level';
     return id.name ?? `fn:${id.startLine}:${id.startColumn}`;
 }
+/**
+ * Project every node `findEnclosingFunctionIdentity` would match — the six
+ * `FUNCTION_NODE_TYPES` plus `adapter.isMethod` — into a `FunctionSpan`. The set
+ * and the `adapter.getNodeName` text are byte-identical to the identity walk, so
+ * a corpus-side "innermost span containing the location" reproduces the walk's
+ * result (a nested function's start is inside its parent's span, hence later, so
+ * the containing span with the latest start is the deepest one).
+ *
+ * @param ast The parsed AST whose enclosing functions are projected.
+ * @param adapter The language adapter for type/name traversal.
+ * @returns One `FunctionSpan` per enclosing-function node, in walk pre-order.
+ */
+export function extractEnclosingFunctionSpans(ast, adapter) {
+    const spans = [];
+    const walk = (node) => {
+        const type = adapter.getNodeType(node);
+        if (FUNCTION_NODE_TYPES.has(type) || adapter.isMethod(node)) {
+            spans.push({
+                startLine: node.location.start.line,
+                startColumn: node.location.start.column,
+                endLine: node.location.end.line,
+                endColumn: node.location.end.column,
+                name: adapter.getNodeName(node),
+            });
+        }
+        if (node.children) {
+            for (const child of node.children)
+                walk(child);
+        }
+    };
+    walk(ast.root);
+    return spans;
+}
+/**
+ * Project every `string_fragment` leaf into a `StringFragmentSpan`. The legacy
+ * re-home's `findClosestNodeAt(ref.location)` returns the deepest node containing
+ * the reference; for a table name parsed out of a SQL string that node is a
+ * `string_fragment` (the `alias(…, $.string_fragment)` token, a named leaf). The
+ * set and the start/end coordinates are byte-identical to that node, so a
+ * corpus-side "innermost fragment containing the location" reproduces the
+ * top-level coordinate (a reference is always inside exactly one fragment — the
+ * fragments of one string are disjoint, and distinct strings are disjoint).
+ *
+ * @param ast The parsed AST whose string fragments are projected.
+ * @param adapter The language adapter for type/child traversal.
+ * @returns One `StringFragmentSpan` per `string_fragment` node, in walk pre-order.
+ */
+export function extractStringFragmentSpans(ast, adapter) {
+    const spans = [];
+    const walk = (node) => {
+        if (adapter.getNodeType(node) === 'string_fragment') {
+            spans.push({
+                startLine: node.location.start.line,
+                startColumn: node.location.start.column,
+                endLine: node.location.end.line,
+                endColumn: node.location.end.column,
+            });
+        }
+        if (node.children) {
+            for (const child of node.children)
+                walk(child);
+        }
+    };
+    walk(ast.root);
+    return spans;
+}
 //# sourceMappingURL=codeAnalysis.js.map