code-auditor-mcp 4.1.1 → 5.0.2

package/dist/analyzers/provenance.js

@@ -18,28 +18,19 @@
  *   provenance            — strict provenance only, never consults name lists
  *   names                 — legacy English-only name matching (opt-in escape hatch)
  */
+import { dialectForPackage } from '../languages/sql/dialectDetection.js';
+import { DB_PACKAGES, handleTypesForPackage } from './tsEcosystem.js';
+import { buildBindingEnv, classifyRootIdentifier, extractInterfaceFields, resolveReceiverRoot, findEnclosingClassHeritage, } from './receiverRoot.js';
+import { identifyHandle } from './handleIdentification.js';
+import { stripSqlQuotes } from './sqlLiteral.js';
 // ═══════════════════════════════════════════════════════════════════════════
-// Constants — the universal vocabulary (package names are language-invariant)
+// Constants — validator packages
+//
+// The DB ecosystem (DB_PACKAGES / ORM_METHODS) was TypeScript/npm-only and
+// moved behind the resolution interface to `tsEcosystem.ts`
+// (correction-seams-not-placement §4). What remains here is the
+// validator-package vocabulary, a distinct concern.
 // ═══════════════════════════════════════════════════════════════════════════
-/** Database packages — spec R1.1 */
-export const DB_PACKAGES = new Set([
-    'better-sqlite3',
-    'drizzle-orm',
-    '@prisma/client',
-    'pg',
-    'mysql2',
-    'postgres',
-    'kysely',
-    'knex',
-    'mongodb',
-    'mongoose',
-    '@libsql/client',
-    '@planetscale/database',
-    '@neondatabase/serverless',
-    '@vercel/postgres',
-    'bun:sqlite',
-    'node:sqlite',
-]);
 /** Validator packages — spec R4.1 */
 export const VALIDATOR_PACKAGES = new Set([
     'zod',
@@ -52,79 +43,6 @@ export const VALIDATOR_PACKAGES = new Set([
     '@sinclair/typebox',
     'class-validator',
 ]);
-/** Known DB type names — spec R1.1 (propagation rule 8) */
-export const DB_TYPES = new Set([
-    'D1Database',
-    'D1PreparedStatement',
-    'D1Result',
-    'Database',
-    'Pool',
-    'PrismaClient',
-    'Kysely',
-    'Connection',
-    'SqliteDatabase',
-    'BetterSQLite3Database',
-]);
-/**
- * DB call methods — the fixed API surface (language-invariant).
- *
- * Spec 33 Item 11 FP category 5: the bare-identifier hybrid fallback in
- * `isDBProvenanced` treated any `get(...)` / `each(...)` / `values(...)` call
- * as a DB query, flagging lodash-style object accessors (e.g.
- * `@directus/utils`'s `get(item, ...)`) as sql-injection. Those three names
- * are also common non-DB methods (lodash `get`, jQuery/iterator
- * `each`, Map/WebSocket `.values()`), so they are removed from the fallback —
- * mirroring the `get`/`each` trim in CHANGELOG 3.4.9 (DB_CALL_METHOD_NAMES).
- *
- * `query` is deliberately RETAINED: it is a genuine query-execution method on
- * mysql2, pg, node-postgres, D1 and Planetscale (`.query(...)`), and the
- * spec-19 data-access fixtures exercise it as a canonical DB entry point.
- * Removing it would turn real SQL-injection positives into false negatives.
- *
- * `raw` is deliberately retained: it is a genuine raw-execution method on
- * D1 prepared statements, Knex, and Kysely, and the Item-6 taint-tracking
- * fixtures exercise it as the canonical raw-SQL entry point.
- */
-export const DB_CALL_METHODS = new Set([
-    'exec',
-    'prepare',
-    'batch',
-    'run',
-    'all',
-    'first',
-    'query',
-    'raw',
-]);
-/** ORM method patterns — fixed API surface for ORM recognition (Spec 21 R1) */
-export const ORM_METHODS = new Set([
-    'find',
-    'findOne',
-    'findMany',
-    'findFirst',
-    'findUnique',
-    'select',
-    'insert',
-    'insertMany',
-    'update',
-    'updateOne',
-    'updateMany',
-    'delete',
-    'deleteOne',
-    'deleteMany',
-    'from',
-    'where',
-    'join',
-    'leftJoin',
-    'rightJoin',
-    'innerJoin',
-    'create',
-    'createMany',
-    'aggregate',
-    'count',
-    'distinct',
-    'execute',
-    'query',
-]);
 // ═══════════════════════════════════════════════════════════════════════════
 // Package matching
 // ═══════════════════════════════════════════════════════════════════════════
@@ -132,6 +50,20 @@ export const ORM_METHODS = new Set([
 function matchesDBPackage(specifier) {
     return [...DB_PACKAGES].some((pkg) => specifier === pkg || specifier.startsWith(pkg + '/'));
 }
+/**
+ * The base npm package name of a module specifier — `pg` for `pg`/`pg/lib`,
+ * `@neondatabase/serverless` for `@neondatabase/serverless` and its subpaths,
+ * `mysql2` for `mysql2/promise`. Used to stamp {@link ProvenanceEvidence.packageName}
+ * with the exact key `dialectForPackage` maps, so a subpath import still resolves
+ * to its driver's dialect.
+ */
+function basePackageName(specifier) {
+    if (specifier.startsWith('@')) {
+        const parts = specifier.split('/');
+        return parts.slice(0, 2).join('/');
+    }
+    return specifier.split('/')[0];
+}
 /** Check if a module specifier matches a validator package. */
 function matchesValidatorPackage(specifier) {
     return [...VALIDATOR_PACKAGES].some((pkg) => specifier === pkg || specifier.startsWith(pkg + '/'));
@@ -144,19 +76,38 @@ function matchesValidatorPackage(specifier) {
  * An import like `import Database from 'better-sqlite3'` produces `Database` as
  * provenanced with reason "package". Shared by the DB and validator variants,
  * which differ only in the package predicate.
+ *
+ * `handleTypesFor` is the Decision A type filter. It maps a matched specifier to
+ * the package's handle-name set, or `undefined` when the caller wants no type
+ * filter (the validator variant — a validator package's every export is a
+ * validator). When the set is present, a *named* import seeds only if its
+ * original export name (`spec.name`, not the local alias) is in the set; a
+ * default or namespace import seeds unconditionally, because a DB package's
+ * default/namespace *is* its handle and tree-sitter records no original export
+ * name for a default import to match. This is what stops
+ * `import { KVNamespace } from '@cloudflare/workers-types'` from seeding while
+ * `import { D1Database }` still does.
+ *
  * @param ast
  * @param adapter
  * @param matchesPackage
+ * @param handleTypesFor
  * @returns
  */
-function extractProvenancedImports(ast, adapter, matchesPackage) {
+function extractProvenancedImports(ast, adapter, matchesPackage, handleTypesFor = () => undefined) {
     const seedMap = new Map();
     const imports = adapter.extractImports(ast);
     for (const imp of imports) {
         const specifier = imp.source;
         if (!matchesPackage(specifier))
             continue;
+        const handleTypes = handleTypesFor(specifier);
         for (const spec of imp.specifiers) {
+            // Decision A: a named import seeds only when the package's manifest lists
+            // the original export name as a handle. Default/namespace imports seed
+            // unconditionally (see the doc above).
+            if (handleTypes && !spec.isDefault && !spec.isNamespace && !handleTypes.has(spec.name))
+                continue;
             const localName = spec.alias ?? spec.name;
             const label = spec.isDefault
                 ? `default import from ${specifier}`
@@ -170,6 +121,7 @@ function extractProvenancedImports(ast, adapter, matchesPackage) {
                     reason: 'package',
                     source: label,
                     chain: [],
+                    packageName: basePackageName(specifier),
                 });
             }
         }
@@ -184,7 +136,7 @@ function extractProvenancedImports(ast, adapter, matchesPackage) {
  * @returns a map of local identifier → DB-provenance evidence
  */
 export function extractDBProvenancedImports(ast, adapter) {
-    return extractProvenancedImports(ast, adapter, matchesDBPackage);
+    return extractProvenancedImports(ast, adapter, matchesDBPackage, handleTypesForPackage);
 }
 /**
  * Extract all validator-provenanced identifiers from a file's imports.
@@ -204,40 +156,17 @@ export function extractValidatorProvenancedImports(ast, adapter) {
  * Returns true if any new identifier was added.
  */
 function propagateVariableDeclaration(node, ctx) {
-    const { nameNode, valueNode, typeAnnotationNode } = splitVariableDeclarator(node, ctx.adapter);
+    const { nameNode, valueNode } = splitVariableDeclarator(node, ctx.adapter);
     if (!nameNode)
         return false;
-    let mutated = false;
-    // Rule 8: type annotation — let x: D1Database
-    if (typeAnnotationNode) {
-        mutated = propagateFromTypeAnnotation(nameNode, typeAnnotationNode, ctx);
-    }
     if (valueNode) {
-        mutated = propagateFromValue(nameNode, valueNode, ctx) || mutated;
+        return propagateFromValue(nameNode, valueNode, ctx);
     }
-    return mutated;
-}
-/** Rule 8: type annotation — `let x: D1Database`. */
-function propagateFromTypeAnnotation(nameNode, typeAnnotationNode, ctx) {
-    if (nameNode.type !== 'identifier')
-        return false;
-    const typeText = ctx.adapter.getNodeText(typeAnnotationNode, ctx.sourceCode).trim();
-    if (!DB_TYPES.has(typeText))
-        return false;
-    const name = ctx.adapter.getNodeText(nameNode, ctx.sourceCode);
-    if (ctx.provenanceMap.has(name))
-        return false;
-    ctx.provenanceMap.set(name, {
-        identifier: name,
-        reason: 'type',
-        source: `type annotation ${typeText}`,
-        chain: [],
-    });
-    return true;
+    return false;
 }
 /** Propagate provenance from a declarator's value expression into its names. */
 function propagateFromValue(nameNode, valueNode, ctx) {
-    const propagated = tryPropagateFromExpression(valueNode, ctx.adapter, ctx.sourceCode, ctx.provenanceMap);
+    const propagated = tryPropagateFromExpression(valueNode, ctx.adapter, ctx.sourceCode, ctx.provenanceMap, ctx.localFunctions);
     if (!propagated)
         return false;
     let mutated = false;
@@ -248,6 +177,7 @@ function propagateFromValue(nameNode, valueNode, ctx) {
                 reason: 'propagation',
                 source: propagated.source,
                 chain: [...propagated.chain, propagated.identifier],
+                packageName: propagated.packageName,
             });
             mutated = true;
         }
@@ -258,7 +188,7 @@ function propagateFromValue(nameNode, valueNode, ctx) {
  * Propagate provenance through a default parameter (rule 6).
  * Returns true if a new identifier was added.
  */
-function propagateDefaultParameter(node, adapter, sourceCode, provenanceMap) {
+function propagateDefaultParameter(node, adapter, sourceCode, provenanceMap, localFunctions) {
     const children = adapter.getChildren(node);
     // assignment_pattern has [left, right]
     if (children.length < 2)
@@ -268,13 +198,14 @@ function propagateDefaultParameter(node, adapter, sourceCode, provenanceMap) {
     if (leftNode.type !== 'identifier')
         return false;
     const paramName = adapter.getNodeText(leftNode, sourceCode);
-    const propagated = tryPropagateFromExpression(rightNode, adapter, sourceCode, provenanceMap);
+    const propagated = tryPropagateFromExpression(rightNode, adapter, sourceCode, provenanceMap, localFunctions);
     if (propagated && !provenanceMap.has(paramName)) {
         provenanceMap.set(paramName, {
             identifier: paramName,
             reason: 'propagation',
             source: `default parameter = ${propagated.source}`,
             chain: [...propagated.chain, propagated.identifier],
+            packageName: propagated.packageName,
         });
         return true;
     }
@@ -284,33 +215,81 @@ function propagateDefaultParameter(node, adapter, sourceCode, provenanceMap) {
  * Propagate provenance through a class field initialization (rule 7).
  * Returns true if a new identifier was added.
  */
-function propagateClassField(node, adapter, sourceCode, provenanceMap) {
+function propagateClassField(node, adapter, sourceCode, provenanceMap, localFunctions) {
     const children = adapter.getChildren(node);
-    // Typically [name, value] or [decorators..., name, value]
+    // Typically [name, value], [modifier, name, type], or [decorators..., name, value].
     const nameChild = children.find((c) => c.type === 'property_identifier');
+    if (!nameChild)
+        return false;
+    const fieldName = adapter.getNodeText(nameChild, sourceCode);
+    // Rule 7 — class field initialized with a DB value (`private db = new Database()`).
+    // `accessibility_modifier` and `type_annotation` are excluded so the value is
+    // found even on a modified or annotated field.
     const valueChild = children.find((c) => c.type !== 'property_identifier' &&
         c.type !== 'decorator' &&
+        c.type !== 'accessibility_modifier' &&
         c.type !== 'private' &&
         c.type !== 'public' &&
         c.type !== 'protected' &&
         c.type !== 'static' &&
         c.type !== 'readonly' &&
-        c.type !== 'abstract');
-    if (nameChild && valueChild) {
-        const fieldName = adapter.getNodeText(nameChild, sourceCode);
-        const propagated = tryPropagateFromExpression(valueChild, adapter, sourceCode, provenanceMap);
+        c.type !== 'abstract' &&
+        c.type !== 'type_annotation');
+    if (valueChild) {
+        const propagated = tryPropagateFromExpression(valueChild, adapter, sourceCode, provenanceMap, localFunctions);
         if (propagated && !provenanceMap.has(fieldName)) {
             provenanceMap.set(fieldName, {
                 identifier: fieldName,
                 reason: 'propagation',
                 source: `class field initialized from ${propagated.source}`,
                 chain: [...propagated.chain, propagated.identifier],
+                packageName: propagated.packageName,
             });
             return true;
         }
     }
     return false;
 }
+/**
+ * S5b (form 4) — propagate provenance through a member assignment
+ * (`this.db = new Database()`). The RHS is a DB-provenanced expression (a
+ * `new X()` where X is an in-repo class that resolves, or a provenanced
+ * identifier), so the assigned field is a DB handle. This is the `new X()`
+ * binding form for the `this.<field> = …` assignment shape that no
+ * `variable_declarator`/`field_definition` rule covers.
+ */
+function propagateMemberAssignment(node, ctx) {
+    const { adapter, sourceCode, provenanceMap } = ctx;
+    const children = adapter.getChildren(node);
+    // children: [member_expression (this.db), <RHS expression>].
+    const lhs = children.find((c) => c.type === 'member_expression' || c.type === 'selector_expression');
+    if (!lhs)
+        return false;
+    const lhsChildren = adapter.getChildren(lhs);
+    const obj = lhsChildren.find((c) => c.type === 'this' || c.type === 'super');
+    if (!obj)
+        return false;
+    const prop = lhsChildren.find((c) => c.type === 'property_identifier' || c.type === 'field_identifier');
+    if (!prop)
+        return false;
+    const fieldName = adapter.getNodeText(prop, sourceCode);
+    if (!fieldName || provenanceMap.has(fieldName))
+        return false;
+    const rhs = children[children.length - 1];
+    if (!rhs || rhs.type === 'member_expression' || rhs.type === 'selector_expression')
+        return false;
+    const propagated = tryPropagateFromExpression(rhs, adapter, sourceCode, provenanceMap, ctx.localFunctions);
+    if (!propagated)
+        return false;
+    provenanceMap.set(fieldName, {
+        identifier: fieldName,
+        reason: 'propagation',
+        source: `this.${fieldName} assigned from ${propagated.source}`,
+        chain: [...propagated.chain, propagated.identifier],
+        packageName: propagated.packageName,
+    });
+    return true;
+}
 function applyPropagationRule(node, parent, ctx) {
     const { adapter, sourceCode, provenanceMap } = ctx;
     if (node.type === 'variable_declarator') {
@@ -318,19 +297,22 @@ function applyPropagationRule(node, parent, ctx) {
     }
     if (node.type === 'assignment_pattern' &&
         parent?.type === 'formal_parameters') {
-        return propagateDefaultParameter(node, adapter, sourceCode, provenanceMap);
+        return propagateDefaultParameter(node, adapter, sourceCode, provenanceMap, ctx.localFunctions);
+    }
+    if (node.type === 'public_field_definition') {
+        return propagateClassField(node, adapter, sourceCode, provenanceMap, ctx.localFunctions);
     }
-    if (node.type === 'public_field_definition' ||
-        node.type === 'field_definition') {
-        return propagateClassField(node, adapter, sourceCode, provenanceMap);
+    // S5b (form 4) — `this.db = new Database()` / `this.db = <provenanced>`.
+    if (node.type === 'assignment_expression') {
+        return propagateMemberAssignment(node, ctx);
     }
     return false;
 }
 /**
- * Propagate provenance through assignments, destructuring, parameters,
- * class fields, and type annotations within a single file.
+ * Propagate provenance through assignments, destructuring, default
+ * parameters, and class-field initializers within a single file.
  *
- * The 8 single-file propagation rules (spec R1):
+ * The 7 single-file propagation rules (spec R1):
  *   1. new Expression → variable
  *   2. DB-provenanced call return → variable
  *   3. member expression on DB receiver → variable
@@ -338,7 +320,6 @@ function applyPropagationRule(node, parent, ctx) {
  *   5. array destructuring from DB source
  *   6. default parameter with DB value
  *   7. class field initialized with DB value
- *   8. type annotation with known DB type
  * @param adapter
  * @param ast
  * @param seedMap
@@ -348,7 +329,12 @@ function applyPropagationRule(node, parent, ctx) {
 export function propagateProvenance(ast, adapter, sourceCode, seedMap) {
     // Work on a copy so we can add newly-provenanced identifiers during the walk
     const provenanceMap = new Map(seedMap);
-    const ctx = { adapter, sourceCode, provenanceMap };
+    const ctx = {
+        adapter,
+        sourceCode,
+        provenanceMap,
+        localFunctions: collectLocalFunctionNames(ast, adapter, sourceCode),
+    };
     // Keep iterating until no new identifiers are discovered (handles chains)
     let changed = true;
     let iterations = 0;
@@ -364,6 +350,37 @@ export function propagateProvenance(ast, adapter, sourceCode, seedMap) {
     }
     return provenanceMap;
 }
+/**
+ * Names of functions *declared in this file* — named function declarations,
+ * method definitions, and arrow/function expressions bound to a variable.
+ * S5f consults this to refuse to forward a provenanced argument through a local
+ * function: the local function's own return is resolved by
+ * `detectDbReturningFunctions` (returned construction), not by
+ * the "it takes a handle, so it must return one" heuristic that is only sound
+ * for *external* factories like `enhancePrisma(PrismaClient)`.
+ */
+function collectLocalFunctionNames(ast, adapter, sourceCode) {
+    const names = new Set();
+    walkAST(ast.root, (node) => {
+        if (FUNCTION_NODE_TYPES.has(node.type)) {
+            const name = adapter.getNodeName(node);
+            if (name)
+                names.add(name);
+            return;
+        }
+        if (node.type === 'variable_declarator') {
+            const { nameNode, valueNode } = splitVariableDeclarator(node, adapter);
+            if (!nameNode || !valueNode)
+                return;
+            const vt = valueNode.type;
+            if (vt === 'arrow_function' || vt === 'function_expression' || vt === 'generator_function') {
+                for (const n of extractPatternNames(nameNode, adapter, sourceCode))
+                    names.add(n);
+            }
+        }
+    });
+    return names;
+}
 // ═══════════════════════════════════════════════════════════════════════════
 // Propagation helpers
 // ═══════════════════════════════════════════════════════════════════════════
@@ -371,7 +388,22 @@ export function propagateProvenance(ast, adapter, sourceCode, seedMap) {
  * Given a value expression node, check if it indicates DB provenance
  * and return the evidence of the provenanced source if so.
  */
-function tryPropagateFromExpression(node, adapter, sourceCode, provenanceMap) {
+function tryPropagateFromExpression(node, adapter, sourceCode, provenanceMap, localFunctions) {
+    // ── Rule 0: await x — unwrap the await and propagate from its operand ──
+    // Mirrors getCallExpressionCallee, which already recurses through
+    // await_expression. `await` is a significant anonymous child (converter.ts
+    // SIGNIFICANT_ANONYMOUS_TYPES) and is skipped; the operand carries the
+    // provenance (e.g. `const x = await factory()`).
+    if (node.type === 'await_expression') {
+        for (const child of adapter.getChildren(node)) {
+            if (child.type === 'await')
+                continue;
+            const result = tryPropagateFromExpression(child, adapter, sourceCode, provenanceMap, localFunctions);
+            if (result)
+                return result;
+        }
+        return null;
+    }
     // ── Rule 1: new Database(...) ──
     if (node.type === 'new_expression') {
         const constructorNode = findChildOfType(node, [
@@ -388,7 +420,7 @@ function tryPropagateFromExpression(node, adapter, sourceCode, provenanceMap) {
     // ── Rule 2: drizzle(env.DB) — call where callee is DB-provenanced ──
     // ── Rule 3: db.prepare(sql) — member expression call on DB receiver ──
     if (node.type === 'call_expression') {
-        const viaCall = tryCallProvenance(node, adapter, sourceCode, provenanceMap);
+        const viaCall = tryCallProvenance(node, adapter, sourceCode, provenanceMap, localFunctions);
         if (viaCall)
             return viaCall;
     }
@@ -423,7 +455,7 @@ function lookupEvidence(provenanceMap, name) {
  * identifier (e.g. `drizzle(...)`) or a member expression on a DB receiver
  * (e.g. `db.prepare(sql)`).
  */
-function tryCallProvenance(node, adapter, sourceCode, provenanceMap) {
+function tryCallProvenance(node, adapter, sourceCode, provenanceMap, localFunctions) {
     const calleeNode = getCallExpressionCallee(node, adapter);
     if (!calleeNode)
         return null;
@@ -433,6 +465,12 @@ function tryCallProvenance(node, adapter, sourceCode, provenanceMap) {
         const evidence = lookupEvidence(provenanceMap, name);
         if (evidence)
             return evidence;
+        // S5f — higher-order wrapper: a plain-identifier call whose callee is NOT
+        // provenanced but forwards a provenanced DB-handle argument
+        // (`enhancePrisma(PrismaClient)`). The call result is treated as a DB handle.
+        const argEvidence = tryProvenancedArgument(node, adapter, sourceCode, provenanceMap, localFunctions);
+        if (argEvidence)
+            return argEvidence;
     }
     // Case: member expression — db.prepare(...)
     if (calleeNode.type === 'member_expression') {
@@ -444,14 +482,55 @@ function tryCallProvenance(node, adapter, sourceCode, provenanceMap) {
     return null;
 }
 /**
- * Split a variable_declarator into its name, value, and type annotation
- * child nodes.
+ * S5f — a call whose callee is unprovenanced but whose *argument* is a
+ * DB-provenanced expression (`enhancePrisma(PrismaClient)`) forwards the handle,
+ * so the call result is a DB handle (a wrapper constructor / factory). Restricted
+ * to a plain-identifier callee so member-expression calls like `JSON.stringify(db)`
+ * or `console.log(db)` — whose result is a string / undefined, not a handle — are
+ * not swept in.
+ */
+function tryProvenancedArgument(node, adapter, sourceCode, provenanceMap, localFunctions) {
+    // S5f is only sound for *external* factories (`enhancePrisma(PrismaClient)`).
+    // A local function that merely takes a handle does not therefore return one —
+    // e.g. `loadCallGraphData(indexHandle)` returns an in-memory graph, not a
+    // handle — and its return is resolved by `detectDbReturningFunctions`. Refusing
+    // to forward through a locally-declared function breaks the cascade that labels
+    // plain Maps/Sets as DB handles (the source of the index-code N+1 false
+    // positives). `localFunctions` is undefined in the `detectDbReturningFunctions`
+    // return-check, where S5f's canonical imported-factory case must still fire.
+    if (localFunctions) {
+        const calleeNode = getCallExpressionCallee(node, adapter);
+        if (calleeNode?.type === 'identifier') {
+            const calleeName = adapter.getNodeText(calleeNode, sourceCode);
+            if (calleeName && localFunctions.has(calleeName))
+                return null;
+        }
+    }
+    const argsNode = adapter.getChildren(node).find((c) => c.type === 'arguments');
+    if (!argsNode)
+        return null;
+    for (const arg of adapter.getChildren(argsNode)) {
+        if (arg.type === '(' || arg.type === ')' || arg.type === ',')
+            continue;
+        const evidence = tryPropagateFromExpression(arg, adapter, sourceCode, provenanceMap, localFunctions);
+        if (evidence) {
+            return {
+                identifier: evidence.identifier,
+                reason: 'wrapper',
+                source: `higher-order wrapper forwards DB handle \`${evidence.identifier}\``,
+                chain: evidence.chain,
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Split a variable_declarator into its name and value child nodes.
  */
 function splitVariableDeclarator(node, adapter) {
     const children = adapter.getChildren(node);
     let nameNode = null;
     let valueNode = null;
-    let typeAnnotationNode = null;
     let pastEquals = false;
     for (const child of children) {
         if (child.type === '=' || child.type === 'equals') {
@@ -460,10 +539,8 @@ function splitVariableDeclarator(node, adapter) {
         }
         if (child.type === ':')
             continue;
-        if (child.type === 'type_annotation') {
-            typeAnnotationNode = child;
+        if (child.type === 'type_annotation')
             continue;
-        }
         if (!pastEquals && !nameNode) {
             // First non-syntax child is the name/pattern
             if (child.type === 'identifier' ||
@@ -482,7 +559,7 @@ function splitVariableDeclarator(node, adapter) {
             }
         }
     }
-    return { nameNode, valueNode, typeAnnotationNode };
+    return { nameNode, valueNode };
 }
 /**
  * Extract all variable names from a destructuring or identifier pattern.
@@ -562,8 +639,21 @@ function collectChildren(node, adapter, sourceCode, names) {
  * `env.DB.prepare` yields "env.DB", not "env"); a `this`/`super` child returns
  * `thisSuperResult` (null for the receiver walker, 'this' for the root walker);
  * any other child returns null.
+ *
+ * A `call_expression` child is the fluent/builder-chain case (`db.selectFrom(…)
+ * .selectAll().execute()` — the object of `.execute` is a call): descend into
+ * the call's *callee* and resolve that, so the root receiver is reached through
+ * the chain rather than dropped. Without this, every ORM whose queries are
+ * builder chains (kysely, drizzle, knex, prisma fluent API) resolves to `null`
+ * at the first call boundary.
  */
 function resolveReceiverText(firstChild, adapter, sourceCode, thisSuperResult) {
+    if (firstChild.type === 'call_expression') {
+        const callee = getCallExpressionCallee(firstChild, adapter);
+        if (!callee)
+            return null;
+        return resolveReceiverText(callee, adapter, sourceCode, thisSuperResult);
+    }
     if (firstChild.type === 'identifier' ||
         firstChild.type === 'member_expression' ||
         firstChild.type === 'selector_expression') {
@@ -578,8 +668,13 @@ function resolveReceiverText(firstChild, adapter, sourceCode, thisSuperResult) {
  * Extract the "receiver" identifier from a member expression chain.
  * For `db.prepare` → "db"
  * For `this.db.prepare` → "db" (walk to the deepest non-member identifier)
+ *
+ * @param node the member/selector expression node
+ * @param adapter the language adapter used to walk child nodes
+ * @param sourceCode the file source text for reading node text
+ * @returns the receiver identifier text, or `null`
  */
-function getMemberExpressionReceiver(node, adapter, sourceCode) {
+export function getMemberExpressionReceiver(node, adapter, sourceCode) {
     // Walk down the member expression chain to find the root object
     let current = node;
     while (current.type === 'member_expression' ||
@@ -604,6 +699,9 @@ function getMemberExpressionReceiver(node, adapter, sourceCode) {
  * guards must agree on: a bare `identifier`, a `member_expression`/`selector`,
  * and — for `await fn<T>(...)` — an `await_expression` wrapping the callee plus
  * a `type_arguments` child (skipped, not mistaken for the callee).
+ * @param node The call-expression node whose callee to extract.
+ * @param adapter The language adapter for child traversal.
+ * @returns The callee node, or null when none is found.
  */
 export function getCallExpressionCallee(node, adapter) {
     for (const child of adapter.getChildren(node)) {
@@ -675,104 +773,297 @@ export function buildProvenanceContext(ast, adapter, sourceCode, options) {
     const mode = options.mode;
     // 1. Extract seed identifiers from imports
     const dbSeeds = extractDBProvenancedImports(ast, adapter);
-    const validatorSeeds = options.mode !== 'names'
-        ? extractValidatorProvenancedImports(ast, adapter)
-        : new Map();
+    const validatorSeeds = extractValidatorProvenancedImports(ast, adapter);
+    // 1a. Merge cross-file resolution seeds (declaration-based, not name-based).
+    //     These replace the deleted name-list fallback (Spec 69 §10): the
+    //     `seedProvenance` map is the per-file DB-provenanced identifier set
+    //     produced by `computeReceiverProvenance` for this file.
+    if (options.seedProvenance) {
+        for (const [name, evidence] of options.seedProvenance) {
+            if (!dbSeeds.has(name))
+                dbSeeds.set(name, evidence);
+        }
+    }
     // 2. Propagate provenance through assignments
     let dbProvenanced = propagateProvenance(ast, adapter, sourceCode, dbSeeds);
-    let validatorProvenanced = mode !== 'names'
-        ? propagateProvenance(ast, adapter, sourceCode, validatorSeeds)
-        : new Map();
-    // 3. Fallback: in hybrid mode, add identifiers that match name lists
-    //    but weren't caught by provenance (R3)
-    if (mode === 'hybrid') {
-        dbProvenanced = addNameListFallbacks(dbProvenanced, sourceCode, {
-            dbReceiverNames: options.dbReceiverNames ?? [],
-            dbBindingNames: options.dbBindingNames ?? [],
-            dbWrapperNames: options.dbWrapperNames ?? [],
-        });
-        // 3a. Wrapper detection: learn DB-wrapper function names from function
-        //     bodies (a D1 REST fetch, or delegation to an already-provenanced
-        //     receiver). A bare call like `d1(sql)` then resolves as DB-provenanced
-        //     and its SQL reaches the table rules instead of bypassing them.
-        dbProvenanced = detectDbWrapperFunctions(ast, adapter, sourceCode, dbProvenanced);
-    }
-    // 4. In names mode, use ONLY name lists
-    if (mode === 'names') {
-        dbProvenanced = buildNamesOnlyProvenance(sourceCode, options.dbReceiverNames ?? [], options.dbBindingNames ?? [], options.dbWrapperNames ?? []);
-    }
+    const validatorProvenanced = propagateProvenance(ast, adapter, sourceCode, validatorSeeds);
+    // 2a. DB-shaped activity — receiver roots of DB/ORM call sites, proven or
+    //     unproven. This is the file-gate signal, not a handle decision: it must
+    //     run before the R3 dialect gate so a type-annotated handle with a dynamic
+    //     SQL argument (unproven under criterion 9, no dialect to parse) still
+    //     passes the gate and reaches the analyzers instead of being dropped.
+    const dbActivity = collectDbActivity(ast, adapter, sourceCode, dbProvenanced);
+    // 3. R3 — a call whose argument parses as SQL proves its receiver a handle
+    //    (criterion 8). This is the replacement for the type-name handle tests
+    //    criterion 9 deleted: `const db: D1Database = getDb()` no longer proves `db`
+    //    by its annotation, but `db.query('SELECT …')` still does — by the parsed
+    //    argument, not the name. Runs before wrapper detection so a wrapper body's
+    //    `db.prepare('SELECT …')` is already visible as a DB call to
+    //    `detectDbWrappers`. Runs even without a named dialect: `identifyHandle`
+    //    parses the literal under DEFAULT_SQL_DIALECT when the dialect is null
+    //    (Spec 70 R2), so a sibling's parseable literal still proves the receiver.
+    dbProvenanced = applySqlArgumentInference(ast, adapter, sourceCode, dbProvenanced, options.sqlDialect ?? null);
+    // 4. Wrapper detection (structural, not name-based): learn DB-wrapper function
+    //    names from function bodies — a body that constructs/calls a DB driver.
+    //    A bare call like `d1(sql)` then resolves as DB-provenanced and its SQL
+    //    reaches the table rules instead of bypassing them.
+    dbProvenanced = detectDbWrappers(ast, adapter, sourceCode, dbProvenanced);
     return {
         dbProvenanced,
         validatorProvenanced,
         mode,
+        dbActivity,
     };
 }
-function addNameListFallbacks(provenanceMap, sourceCode, nameLists) {
-    const { dbReceiverNames, dbBindingNames, dbWrapperNames } = nameLists;
-    const result = new Map(provenanceMap);
-    addIdentifierFallbacks(result, sourceCode, dbReceiverNames, 'dbReceiverNames');
-    addBindingFallbacks(result, sourceCode, dbBindingNames);
-    addIdentifierFallbacks(result, sourceCode, dbWrapperNames, 'dbWrapperNames');
-    return result;
+// ═══════════════════════════════════════════════════════════════════════════
+// R3 — sql-argument handle inference (criterion 8)
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Build the TS receiver-classification env each local fold constructs. The three
+ * receiver folds (`collectDbActivity`, `applySqlArgumentInference`,
+ * `delegatesToProvenanced`) once each hand-built a near-identical `env` literal;
+ * this constructor keeps the classifier's inputs in one place. `interfaceFields`
+ * is omitted by the bare-root callers that classify a receiver with no member
+ * chain (the B3 arm reads it only for `env.DB`-shaped chains); `delegatesToProvenanced`
+ * passes an empty provenance map so the receiver's own declaration — not its
+ * propagated provenance — decides its disposition.
+ */
+function buildRootEnv(adapter, sourceCode, provenance, bindings, interfaceFields) {
+    return { provenance, bindings, interfaceFields, adapter, sourceCode };
 }
-/** Add fallback entries for identifiers that appear in source but lack provenance. */
-function addIdentifierFallbacks(result, sourceCode, names, label) {
-    for (const name of names) {
-        if (result.has(name))
-            continue; // already provenanced — provenance wins
-        if (identifierAppearsInSource(sourceCode, name)) {
-            result.set(name, {
-                identifier: name,
-                reason: 'fallback',
-                source: `name list match: ${label} contains "${name}"`,
-                chain: [],
-            });
+/**
+ * Collect the receiver roots of DB-shaped call sites (a member/selector call
+ * whose first argument is a static SQL string literal, or whose receiver root
+ * resolves handle/unproven), *proven or unproven*. This is the file-gate signal
+ * — see `ProvenanceContext.dbActivity` — not a handle decision (that is
+ * `identifyHandle`'s job alone, criterion 2).
+ *
+ * The discriminator is the package discriminant — the receiver root's
+ * disposition — not the method name: `join` is `Array.prototype.join` and also
+ * `SQL JOIN`. A static SQL literal proves DB shape outright; a dynamic SQL
+ * argument (`db.exec('DROP ' + x)`, `db.prepare(sql)`) is admitted by the
+ * receiver's resolution (`db` → handle/unproven) while `array.join(',')` is
+ * dropped because `array` resolves to a JS global (not-handle). Unlike R3
+ * (`applySqlArgumentInference`) it needs no dialect. Runs unconditionally,
+ * before R3's dialect gate.
+ * @param ast - The file's parsed AST.
+ * @param adapter - The language adapter (used for the callee walk and Go skip).
+ * @param sourceCode - The file's source text (for node-text reads).
+ * @param dbProvenanced - the propagated DB-provenanced map the receiver
+ *   discriminant reads as its provenance seed.
+ * @returns The set of DB-shaped receiver roots, or an empty set for Go.
+ */
+export function collectDbActivity(ast, adapter, sourceCode, dbProvenanced = new Map()) {
+    const activity = new Set();
+    // Go resolves cross-file; a member-receiver root has no local binding to key
+    // the gate on, and Go files are gated by their own import resolution instead.
+    if (adapter.name === 'go')
+        return activity;
+    const env = buildRootEnv(adapter, sourceCode, dbProvenanced, buildBindingEnv(ast, adapter, sourceCode), extractInterfaceFields(ast, adapter, sourceCode));
+    walkAST(ast.root, (node) => {
+        if (node.type !== 'call_expression')
+            return;
+        const callee = getCallExpressionCallee(node, adapter);
+        if (!callee)
+            return;
+        if (callee.type !== 'member_expression' && callee.type !== 'selector_expression')
+            return;
+        const root = resolveReceiverRoot(callee, adapter, sourceCode);
+        if (root === null)
+            return;
+        // A static SQL literal proves DB shape regardless of the receiver's package
+        // (`db.query('SELECT …')`). A dynamic SQL argument is admitted by the
+        // package discriminant: the receiver's disposition — not the method name —
+        // distinguishes `db.prepare(sql)` (handle/unproven) from `array.join(',')`
+        // (root `Array` → not-handle).
+        if (extractStaticSqlArgument(node, adapter, sourceCode) !== null) {
+            activity.add(root);
+            return;
         }
-    }
+        if (classifyRootIdentifier(root, env) !== 'not-handle')
+            activity.add(root);
+    });
+    return activity;
 }
-/** Add fallback entries for binding names like `env.DB` (plus their short forms). */
-function addBindingFallbacks(result, sourceCode, bindings) {
-    for (const binding of bindings) {
-        if (!sourceCode.includes(binding))
-            continue;
-        const dotIdx = binding.lastIndexOf('.');
-        const shortName = dotIdx >= 0 ? binding.substring(dotIdx + 1) : binding;
-        if (!result.has(binding)) {
-            result.set(binding, {
-                identifier: binding,
-                reason: 'fallback',
-                source: `name list match: dbBindingNames contains "${binding}"`,
-                chain: [],
-            });
-        }
-        if (shortName !== binding && !result.has(shortName)) {
-            result.set(shortName, {
-                identifier: shortName,
-                reason: 'fallback',
-                source: `from binding ${binding}`,
+/**
+ * R3: a call whose argument parses as SQL proves its receiver a DB handle.
+ * Folds the one entry point `identifyHandle` (criterion 2: no second decision
+ * path) over DB-shaped call sites and adds every receiver it proves a handle to
+ * `dbProvenanced`. This is the replacement for the type-name handle tests
+ * criterion 9 deleted: a receiver typed `D1Database` / `MockDB` is no longer
+ * proven by its annotation, but `db.query('SELECT …')` still is — by the parsed
+ * argument, not the name.
+ *
+ * The declaration-resolution arm of `identifyHandle` re-runs here, but it is
+ * harmless and already the same evidence `propagateProvenance` produced: for a
+ * type-annotated receiver it now returns `unproven` (criterion 9), and
+ * `combineVerdicts`' `handle > not-handle > unproven` precedence lets the
+ * sql-argument proof win. A receiver already in the map is left untouched.
+ *
+ * @param ast - the parsed file AST whose call sites R3 folds over.
+ * @param adapter - the language adapter (name, extraction helpers) for the file.
+ * @param sourceCode - the raw file source, for callee/method text extraction.
+ * @param dbProvenanced - the running receiver→evidence map to extend in place.
+ * @param sqlDialect - the corpus's named SQL dialect (or null), threaded to the SQL parser.
+ * @returns the same `dbProvenanced` map, now also carrying every receiver R3 proved.
+ */
+export function applySqlArgumentInference(ast, adapter, sourceCode, dbProvenanced, sqlDialect) {
+    if (adapter.name === 'go')
+        return dbProvenanced; // Go resolves cross-file; no TS env here.
+    const env = buildRootEnv(adapter, sourceCode, dbProvenanced, buildBindingEnv(ast, adapter, sourceCode), extractInterfaceFields(ast, adapter, sourceCode));
+    walkAST(ast.root, (node) => {
+        if (node.type !== 'call_expression')
+            return;
+        const callee = getCallExpressionCallee(node, adapter);
+        if (!callee)
+            return;
+        // Only member-expression calls carry the receiver whose handle-ness R3
+        // proves. A bare-identifier call (`query('…')`) has no receiver to add.
+        if (callee.type !== 'member_expression' && callee.type !== 'selector_expression')
+            return;
+        const method = extractMemberExpressionProperty(callee, adapter, sourceCode);
+        if (!method)
+            return;
+        // The SQL argument — not the method name — is the admission proof. R3 folds
+        // `identifyHandle` over every member call; a null static literal simply can't
+        // prove a handle, so it falls through. No method-name set is consulted.
+        const root = resolveReceiverRoot(callee, adapter, sourceCode);
+        if (root === null)
+            return;
+        const receiver = getMemberExpressionReceiver(callee, adapter, sourceCode) ?? root;
+        const sqlArgument = extractStaticSqlArgument(node, adapter, sourceCode);
+        if (sqlArgument === null)
+            return;
+        const thisField = receiverRootIsThis(callee, adapter);
+        const thisHeritage = thisField
+            ? findEnclosingClassHeritage(ast, adapter, node, sourceCode)
+            : null;
+        const verdict = identifyHandle({
+            format: 'typescript',
+            root,
+            receiver,
+            method,
+            sqlArgument,
+            thisField,
+            thisHeritage,
+        }, {
+            imports: new Map(),
+            typeAnnotations: new Map(),
+            bindings: new Map(),
+            withinFileProvenance: new Map(),
+            sqlDialect,
+            resolution: { dialect: 'ts', env },
+        });
+        if (verdict.kind === 'handle' && !dbProvenanced.has(root)) {
+            dbProvenanced.set(root, {
+                identifier: root,
+                reason: 'sql-argument',
+                source: 'SQL argument parses as a statement (Spec 70 R3)',
                 chain: [],
             });
         }
-    }
+    });
+    return dbProvenanced;
 }
 /**
- * Build a provenance map using ONLY name lists (for names mode).
+ * Extract the R3 sites of a TS-family file — the member calls whose static SQL
+ * argument proves their receiver a handle (Spec 70 criterion 8). This is the
+ * provenance-free extraction half of {@link applySqlArgumentInference}: the same
+ * candidate filter (DB/ORM shape) and the same static-argument test, but it
+ * records the site instead of folding `identifyHandle`. The corpus-side
+ * `applyR3FromSites` mirror re-runs the verdict once the seeded provenance and
+ * bindings are known.
+ * @param ast - The file's parsed AST.
+ * @param adapter - The language adapter (used for the callee walk and Go skip).
+ * @param sourceCode - The file's source text (for static-argument reads).
+ * @returns The recorded R3 sites, or `[]` for Go.
  */
-function buildNamesOnlyProvenance(sourceCode, dbReceiverNames, dbBindingNames, dbWrapperNames) {
-    return addNameListFallbacks(new Map(), sourceCode, {
-        dbReceiverNames,
-        dbBindingNames,
-        dbWrapperNames,
+export function extractR3Sites(ast, adapter, sourceCode) {
+    if (adapter.name === 'go')
+        return []; // Go resolves cross-file; no TS env here.
+    const sites = [];
+    walkAST(ast.root, (node) => {
+        if (node.type !== 'call_expression')
+            return;
+        const callee = getCallExpressionCallee(node, adapter);
+        if (!callee)
+            return;
+        // Only member-expression calls carry the receiver whose handle-ness R3
+        // proves. A bare-identifier call (`query('…')`) has no receiver to add.
+        if (callee.type !== 'member_expression' && callee.type !== 'selector_expression')
+            return;
+        const method = extractMemberExpressionProperty(callee, adapter, sourceCode);
+        if (!method)
+            return;
+        // The SQL argument — not the method name — is the admission proof. R3 folds
+        // `identifyHandle` over every member call; a null static literal simply can't
+        // prove a handle, so it falls through. No method-name set is consulted.
+        const root = resolveReceiverRoot(callee, adapter, sourceCode);
+        if (root === null)
+            return;
+        const receiver = getMemberExpressionReceiver(callee, adapter, sourceCode) ?? root;
+        const sqlArgument = extractStaticSqlArgument(node, adapter, sourceCode);
+        if (sqlArgument === null)
+            return;
+        const thisField = receiverRootIsThis(callee, adapter);
+        const thisHeritage = thisField
+            ? findEnclosingClassHeritage(ast, adapter, node, sourceCode)
+            : null;
+        sites.push({
+            root,
+            receiver,
+            method,
+            sqlArgument,
+            thisField,
+            thisHeritage,
+        });
     });
+    return sites;
 }
-/** Check if an identifier name appears as a standalone identifier in source. */
-function identifierAppearsInSource(sourceCode, name) {
-    // Use word boundary matching to avoid partial matches
-    const pattern = new RegExp(`\\b${escapeRegex(name)}\\b`);
-    return pattern.test(sourceCode);
+/** True when a member/selector chain bottoms out at `this`/`super`. */
+function receiverRootIsThis(callee, adapter) {
+    let current = callee;
+    while (current.type === 'member_expression' || current.type === 'selector_expression') {
+        const children = adapter.getChildren(current);
+        const object = children.find((c) => c.type !== '.' && c.type !== 'property_identifier' && c.type !== 'field_identifier');
+        if (!object)
+            return false;
+        current = object;
+    }
+    return current.type === 'this' || current.type === 'super';
 }
-function escapeRegex(s) {
-    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * The statically-present SQL text of a call's first argument (string/template
+ * literal), unquoted — or null when the first argument is not a literal or the
+ * template carries a `${…}` substitution (dynamic). Mirrors the literal-argument
+ * slice of the data-access analyzer's `extractStaticSql`; the tagged-template
+ * and variable-assignment cases are not R3's concern here because a member
+ * receiver already names the handle.
+ */
+function extractStaticSqlArgument(node, adapter, sourceCode) {
+    const children = adapter.getChildren(node);
+    const args = children.find((c) => {
+        const t = adapter.getNodeType(c);
+        return t === 'arguments' || t === 'argument_list';
+    });
+    if (!args)
+        return null;
+    for (const arg of adapter.getChildren(args)) {
+        const t = adapter.getNodeType(arg);
+        if (t === '(' || t === ')' || t === ',')
+            continue;
+        if (t === 'string' || t === 'template_string') {
+            if (t === 'template_string') {
+                const kids = adapter.getChildren(arg) ?? [];
+                if (kids.some((c) => adapter.getNodeType(c) === 'template_substitution'))
+                    return null;
+            }
+            const raw = adapter.getNodeText(arg, sourceCode) ?? '';
+            return stripSqlQuotes(raw);
+        }
+        return null; // first non-trivia argument is not a literal → cannot parse.
+    }
+    return null;
 }
 // ═══════════════════════════════════════════════════════════════════════════
 // Wrapper detection — learn DB-wrapper function names from function bodies
@@ -784,62 +1075,211 @@ const FUNCTION_NODE_TYPES = new Set([
     'arrow_function',
     'method_definition',
     'generator_function_declaration',
-    'generator_function_expression',
+    'generator_function',
+]);
+/** Learn DB-wrapper names from nodes of `spec.nodeTypes` whose bodies wrap a DB
+ *  operation, merging each learned name into `dbProvenanced`. */
+function learnWrapperNames(ast, adapter, sourceCode, dbProvenanced, spec, bindings) {
+    const nodes = adapter.findNodes(ast, {
+        custom: (node) => spec.nodeTypes.has(node.type),
+    });
+    for (const node of nodes) {
+        const name = adapter.getNodeName(node);
+        if (!name)
+            continue;
+        if (dbProvenanced.has(name))
+            continue;
+        if (!spec.isWrapper(node, adapter, sourceCode, dbProvenanced, bindings))
+            continue;
+        dbProvenanced.set(name, {
+            identifier: name,
+            reason: 'wrapper',
+            source: spec.source,
+            chain: [],
+        });
+    }
+    return dbProvenanced;
+}
+/** Class-node types that may wrap a DB handle (Spec 69 §10 — cross-file anchor). */
+const WRAPPER_CLASS_TYPES = new Set([
+    'class_declaration',
+    'abstract_class_declaration',
+    'class',
 ]);
 /**
- * Learn DB-wrapper function names from function bodies and merge them into the
- * provenance map.
+ * Learn DB-wrapper names and merge them into the provenance map.
  *
- * A wrapper is a named function whose own body performs a DB operation — either
- * a `fetch` to the Cloudflare D1 HTTP query API, or a call that delegates to an
- * already DB-provenanced identifier/receiver. Adding the wrapper's name to
+ * A wrapper is a named function/class whose own body performs a DB operation —
+ * either a `fetch` to the Cloudflare D1 HTTP query API, or a call that delegates
+ * to an already DB-provenanced identifier/receiver. Adding the wrapper's name to
  * `dbProvenanced` lets `isDBProvenanced` treat a bare call like `d1(sql)` as a
  * DB call, so its SQL argument reaches the table rules (unknown-table /
  * stale-table-reference) and the data-access rules instead of bypassing them.
  *
- * This is structural evidence, not name matching — the function's body literally
- * talks to a database — so it is only run in hybrid mode (alongside the name
- * fallbacks), never strict `provenance`/`names` modes.
+ * The class form (`options.classes`) is the object-form of the function form: its
+ * body (fields + methods + constructor) constructs or calls a DB driver, so the
+ * class *is* a DB handle — e.g. `export class Database { constructor() {
+ * this.sql = neon(url) } query(t) { return this.sql(t) } }`. Class bodies are
+ * scanned *through* method bodies (the driver call lives in the constructor) but
+ * never into nested classes or nested function declarations — an inner named
+ * function's DB op is not mis-attributed to the outer class.
+ *
+ * This is structural evidence, not name matching, so it is only run in hybrid
+ * mode (alongside the name fallbacks), never strict `provenance`/`names` modes.
  *
- * @param ast The parsed file AST.
- * @param adapter The language adapter for the file's syntax.
- * @param sourceCode The raw source text.
- * @param dbProvenanced The current provenance map (mutated in place and returned).
- * @returns The provenance map with any learned wrapper names added.
+ * @param ast the parsed file AST
+ * @param adapter the language adapter used to walk nodes
+ * @param sourceCode the file source text for reading node text
+ * @param dbProvenanced the provenance map to merge learned wrapper names into
+ * @param options when `classes` is true, also scan wrapper classes
+ * @returns the provenance map with wrapper names added
  */
-function detectDbWrapperFunctions(ast, adapter, sourceCode, dbProvenanced) {
+export function detectDbWrappers(ast, adapter, sourceCode, dbProvenanced, options) {
+    const bindings = buildBindingEnv(ast, adapter, sourceCode);
+    learnWrapperNames(ast, adapter, sourceCode, dbProvenanced, {
+        nodeTypes: FUNCTION_NODE_TYPES,
+        isWrapper: isDbWrapperBody,
+        source: 'function body performs a DB operation',
+    }, bindings);
+    if (options?.classes) {
+        learnWrapperNames(ast, adapter, sourceCode, dbProvenanced, {
+            nodeTypes: WRAPPER_CLASS_TYPES,
+            isWrapper: isDbWrapperClass,
+            source: 'class body constructs or calls a DB driver',
+        }, bindings);
+    }
+    return dbProvenanced;
+}
+/**
+ * Form-5 (Spec 69 §10 S5f) — function return resolution.
+ *
+ * A call to an in-repo function resolves to its *returned construction*,
+ * transitively: `export function getDB() { return new Database() }` proves
+ * `getDB` is a DB handle because the returned expression is already provenanced —
+ * the identifier's name is irrelevant. It is the binding form the two
+ * `cli-integration` fixtures need: `const db = getDB()` in an importing file
+ * resolves through the export fixed point (a provenanced `getDB` export is seeded
+ * in importers) and then propagates via the existing rule 2 (call to a provenanced
+ * identifier).
+ *
+ * This deliberately does NOT learn to accept mocks: a `getDB(): MockDB` with no
+ * provenanced client anywhere in its chain is honestly not a handle, and stays
+ * unprovenanced.
+ *
+ * @param ast the parsed file AST
+ * @param adapter the language adapter used to find function nodes
+ * @param sourceCode the file source text for reading return expressions
+ * @param dbProvenanced the provenance map to merge learned names into
+ * @returns the provenance map with DB-returning function names added
+ */
+export function detectDbReturningFunctions(ast, adapter, sourceCode, dbProvenanced) {
     const functionNodes = adapter.findNodes(ast, {
         custom: (node) => FUNCTION_NODE_TYPES.has(node.type),
     });
     for (const fn of functionNodes) {
         const name = adapter.getNodeName(fn);
-        if (!name)
-            continue;
-        if (dbProvenanced.has(name))
-            continue;
-        if (!isDbWrapperBody(fn, adapter, sourceCode, dbProvenanced))
+        if (!name || dbProvenanced.has(name))
             continue;
-        dbProvenanced.set(name, {
-            identifier: name,
-            reason: 'wrapper',
-            source: 'function body performs a DB operation',
-            chain: [],
-        });
+        // A `return` whose expression is an already-provenanced construction
+        // (`return new Database(...)`, `return db`, `return drizzle(...)`).
+        if (functionReturnsProvenanced(fn, adapter, sourceCode, dbProvenanced)) {
+            dbProvenanced.set(name, {
+                identifier: name,
+                reason: 'propagation',
+                source: 'returns a DB-provenanced construction',
+                chain: [],
+            });
+        }
     }
     return dbProvenanced;
 }
+/**
+ * True when any `return` statement in a function body returns an expression that
+ * is itself a DB-provenanced construction — a provenanced identifier, a
+ * `new`/call whose constructor/callee is provenanced, or a member expression on a
+ * provenanced receiver.
+ */
+function functionReturnsProvenanced(fn, adapter, sourceCode, dbProvenanced) {
+    let found = false;
+    walkAST(fn, (node) => {
+        if (found || node.type !== 'return_statement')
+            return;
+        const arg = adapter.getChildren(node).find((c) => c.type !== 'return');
+        if (!arg)
+            return;
+        if (tryPropagateFromExpression(arg, adapter, sourceCode, dbProvenanced)) {
+            found = true;
+        }
+    });
+    return found;
+}
+/**
+ * Decide whether a class's own body performs a DB operation: a D1 REST fetch, a
+ * call delegating to an already DB-provenanced identifier/receiver, or a
+ * `new`/call to a DB-provenanced constructor/function (the driver a wrapper
+ * class *owns*). Method bodies are included (the constructor is where the driver
+ * call lives); nested classes and nested function declarations are excluded.
+ */
+function isDbWrapperClass(cls, adapter, sourceCode, dbProvenanced, bindings) {
+    for (const expr of collectClassCallExpressions(cls, adapter)) {
+        if (expr.type === 'new_expression') {
+            const ctor = findChildOfType(expr, ['identifier', 'member_expression']);
+            if (ctor) {
+                const ctorName = extractIdentifierName(ctor, adapter, sourceCode);
+                if (ctorName && dbProvenanced.has(ctorName))
+                    return true;
+            }
+            continue;
+        }
+        if (isD1RestCall(expr, adapter, sourceCode))
+            return true;
+        if (delegatesToProvenanced(expr, adapter, sourceCode, dbProvenanced, bindings))
+            return true;
+    }
+    return false;
+}
+/**
+ * Collect `call_expression`/`new_expression` nodes within a class body, descending
+ * through method bodies but never into nested classes or nested function
+ * declarations (so an inner function's DB op doesn't make the class a wrapper).
+ */
+function collectClassCallExpressions(cls, adapter) {
+    const expressions = [];
+    const NESTED_SKIP = new Set([
+        'class_declaration',
+        'abstract_class_declaration',
+        'class',
+        'function_declaration',
+        'function_expression',
+        'arrow_function',
+        'generator_function_declaration',
+        'generator_function',
+    ]);
+    const walk = (node) => {
+        for (const child of adapter.getChildren(node)) {
+            if (NESTED_SKIP.has(child.type))
+                continue;
+            if (child.type === 'call_expression' || child.type === 'new_expression') {
+                expressions.push(child);
+            }
+            walk(child);
+        }
+    };
+    walk(cls);
+    return expressions;
+}
 /**
  * Decide whether a function's own body performs a DB operation: a D1 REST fetch,
  * or a call delegating to an already DB-provenanced receiver/identifier.
  * Nested function bodies are excluded so an inner function's DB op is not
  * mis-attributed to an outer wrapper.
  */
-function isDbWrapperBody(fn, adapter, sourceCode, dbProvenanced) {
+function isDbWrapperBody(fn, adapter, sourceCode, dbProvenanced, bindings) {
     const calls = collectOwnCallExpressions(fn, adapter);
     for (const call of calls) {
         if (isD1RestCall(call, adapter, sourceCode))
             return true;
-        if (delegatesToProvenanced(call, adapter, sourceCode, dbProvenanced))
+        if (delegatesToProvenanced(call, adapter, sourceCode, dbProvenanced, bindings))
             return true;
     }
     return false;
@@ -867,22 +1307,56 @@ function collectOwnCallExpressions(fn, adapter) {
  * True when `call` is a `fetch(...)` to the Cloudflare D1 HTTP query API
  * (`…/d1/database/<id>/query`). That endpoint is specific enough that a match
  * is conclusive evidence the surrounding function is a D1 wrapper.
+ *
+ * @param call the candidate call-expression node
+ * @param adapter the language adapter used to read the callee and arguments
+ * @param sourceCode the file source text for reading node text
+ * @returns true when the call names `fetch` with a literal `/d1/database/` URL
  */
-function isD1RestCall(call, adapter, sourceCode) {
+export function isD1RestCall(call, adapter, sourceCode) {
+    if (adapter.getNodeType(call) !== 'call_expression')
+        return false;
     const callee = getCallExpressionCallee(call, adapter);
     if (!callee)
         return false;
-    const calleeText = adapter.getNodeText(callee, sourceCode) ?? '';
-    if (calleeText !== 'fetch' && !calleeText.endsWith('.fetch'))
+    // The callee must *name* fetch: a bare `fetch(…)` identifier, or a member
+    // `….fetch(…)` whose property node is `fetch`. Reading the property node (not
+    // the callee's whole text) keeps a string inside a subscript/argument from
+    // being read as the method name.
+    const calleeType = adapter.getNodeType(callee);
+    if (calleeType === 'identifier') {
+        if (adapter.getNodeText(callee, sourceCode) !== 'fetch')
+            return false;
+    }
+    else if (calleeType === 'member_expression' || calleeType === 'selector_expression') {
+        if (extractMemberExpressionProperty(callee, adapter, sourceCode) !== 'fetch')
+            return false;
+    }
+    else {
         return false;
-    const callText = adapter.getNodeText(call, sourceCode) ?? '';
-    return callText.includes('/d1/database/');
+    }
+    // The URL is the first string/template-literal argument. A non-literal first
+    // argument (`fetch(makeUrl(…))`) abstains — the value fetch receives is the
+    // *result* of that call, not a literal, so there is no URL to read.
+    const args = adapter.getChildren(call).find((c) => adapter.getNodeType(c) === 'arguments');
+    if (!args)
+        return false;
+    for (const arg of adapter.getChildren(args)) {
+        const t = adapter.getNodeType(arg);
+        if (t === '(' || t === ')' || t === ',')
+            continue;
+        if (t === 'string' || t === 'template_string') {
+            return (adapter.getNodeText(arg, sourceCode) ?? '').includes('/d1/database/');
+        }
+        break; // first argument is not a literal — abstain
+    }
+    return false;
 }
 /**
  * True when `call` delegates to an identifier or member-receiver that is already
  * DB-provenanced (e.g. `db.prepare(...)` inside a `d1Query(sql)` wrapper).
  */
-function delegatesToProvenanced(call, adapter, sourceCode, dbProvenanced) {
+function delegatesToProvenanced(call, adapter, sourceCode, dbProvenanced, bindings) {
     const callee = getCallExpressionCallee(call, adapter);
     if (!callee)
         return false;
@@ -894,159 +1368,84 @@ function delegatesToProvenanced(call, adapter, sourceCode, dbProvenanced) {
         const receiver = getMemberExpressionReceiver(callee, adapter, sourceCode);
         if (!receiver)
             return false;
-        if (dbProvenanced.has(receiver))
-            return true;
-        // Compound receivers ("env.DB", "db.users") — match any dotted segment.
-        return receiver.split('.').some((part) => dbProvenanced.has(part));
+        const receiverProvenanced = dbProvenanced.has(receiver) ||
+            // Compound receivers ("env.DB", "db.users") — match any dotted segment.
+            receiver.split('.').some((part) => dbProvenanced.has(part));
+        if (!receiverProvenanced)
+            return false;
+        // The receiver root's declaration — not the method name — decides whether
+        // this is a DB operation (`db.prepare(…)`) or an in-memory mutation on a
+        // provenanced *result* (`provenancedMap.set(k, v)`, `rows.map(…)`):
+        // `join` is both `Array.prototype.join` and `SQL JOIN`, so a method name
+        // cannot discriminate. Provenance is deliberately left out of the env so the
+        // receiver's own declaration (an array/Map/Set/JS-global/primitive →
+        // not-handle) is consulted rather than its propagated provenance.
+        const root = resolveReceiverRoot(callee, adapter, sourceCode);
+        if (root === null)
+            return false;
+        const env = buildRootEnv(adapter, sourceCode, new Map(), bindings);
+        return classifyRootIdentifier(root, env) !== 'not-handle';
     }
     return false;
 }
+// ═══════════════════════════════════════════════════════════════════════════
+// Per-call-site dialect (Spec 70)
+// ═══════════════════════════════════════════════════════════════════════════
+/** The SQL dialect a DB-driver package's evidence names, or null when the
+ *  evidence carries no package or the package names no single dialect. */
+function dialectForEvidence(evidence) {
+    if (!evidence?.packageName)
+        return null;
+    return dialectForPackage(evidence.packageName);
+}
 /**
- * Determine if a call-expression node's callee is DB-provenanced.
+ * Resolve the SQL dialect a call site should parse its SQL argument under, from
+ * the package its receiver traces to (Spec 70 — per-site dialect). The dialect
+ * is a property of the *located fact*, not the repo: `pool.query(…)` where
+ * `pool` resolves to `pg` is postgres, `conn.query(…)` where `conn` resolves to
+ * `mysql2` is mysql. A repo with two drivers is therefore not "ambiguous" for a
+ * site whose receiver resolves to one of them — that site names its dialect and
+ * parses honestly.
  *
- * This replaces the old `isDBCallee()` / `isDbCallNode()` name-based
- * pattern matching in UniversalDataAccessAnalyzer.
+ * Returns null when the receiver carries no package (a wrapper, a type
+ * annotation, an in-repo module, a cross-dialect ORM like `knex`) or when that
+ * package names no single dialect — the caller then falls back to repo-level
+ * detection (`detectDialect`), and abstains only when that is also null.
  *
- * Checks:
- *   1. Simple identifier call → is the identifier DB-provenanced?
- *   2. Member expression call → is the receiver DB-provenanced AND is the
- *      method in the DB call method set?
- *   3. ORM patterns → receiver is DB-provenanced and method matches ORM API
- *
- * @param node  the call-expression node whose callee is under test
- * @param query  bundled adapter, source, provenance context, and DB methods
- * @returns  true if the call's callee resolves to a DB-provenanced target
+ * @param node The call-expression node whose callee is under test.
+ * @param adapter The language adapter for child traversal.
+ * @param sourceCode The file source text (for reading node text).
+ * @param provenanceContext The resolved provenance context for this file.
+ * @returns The receiver's dialect, or null when the receiver doesn't resolve to one.
  */
-export function isDBProvenanced(node, query) {
-    if (node.type !== 'call_expression')
-        return false;
-    const { adapter, sourceCode, context, methods } = query;
+export function resolveSiteDialect(node, adapter, sourceCode, provenanceContext) {
+    if (!provenanceContext)
+        return null;
     const calleeNode = getCallExpressionCallee(node, adapter);
     if (!calleeNode)
-        return false;
-    // Case 1: Simple identifier call — e.g. query(...)
+        return null;
+    // Bare-identifier call (a wrapper like `d1(sql)`) → the identifier's package.
     if (calleeNode.type === 'identifier') {
         const name = adapter.getNodeText(calleeNode, sourceCode);
-        if (name !== null && context.dbProvenanced.has(name)) {
-            return true;
-        }
-        // Hybrid fallback: standalone calls to dbCallMethods (query, execute, etc.)
-        // qualify as likely DB calls when provenance couldn't resolve the import.
-        // This catches patterns like `import { query } from './db'` where './db' is
-        // a local re-export of a known package — provenance can't see through it,
-        // but the method name is strong evidence.
-        if (context.mode === 'hybrid' && name !== null && methods.has(name)) {
-            return true;
-        }
-        return false;
+        if (!name)
+            return null;
+        return dialectForEvidence(provenanceContext.dbProvenanced.get(name));
     }
-    // Case 2: Member expression — e.g. db.prepare(...)
+    // Member-expression call (`pool.query(...)`) → the receiver's package. Match the
+    // full receiver text and each dotted segment, mirroring
+    // `isMemberExpressionDBProvenanced` (`env.DB` / `db.users` / `this.db`).
     if (calleeNode.type === 'member_expression' || calleeNode.type === 'selector_expression') {
-        return isMemberExpressionDBProvenanced(calleeNode, query);
-    }
-    return false;
-}
-/**
- * Check if a member_expression call is DB-provenanced.
- *
- * Traverses the member chain to find the root receiver,
- * checks if it's in the provenance context, and verifies
- * the method matches the DB call/ORM API.
- */
-function isMemberExpressionDBProvenanced(node, query) {
-    const { adapter, sourceCode, context } = query;
-    const rootReceiver = findRootReceiver(node, adapter, sourceCode);
-    if (!rootReceiver)
-        return false;
-    // In names mode, check the method name directly
-    if (context.mode === 'names') {
-        return isDBMethodCall(node, query);
-    }
-    // Check if the root receiver is DB-provenanced.
-    // Compound receivers (e.g. "db.users" or "env.DB") need to match both
-    // the full text (for bindings like "env.DB") and each sub-identifier
-    // (for receivers like "db.users" where "db" is in dbReceiverNames).
-    const matchesProvenance = (r) => {
-        if (context.dbProvenanced.has(r))
-            return true;
-        for (const part of r.split('.')) {
-            if (context.dbProvenanced.has(part))
-                return true;
+        const receiver = getMemberExpressionReceiver(calleeNode, adapter, sourceCode);
+        if (!receiver)
+            return null;
+        for (const candidate of [receiver, ...receiver.split('.')]) {
+            const dialect = dialectForEvidence(provenanceContext.dbProvenanced.get(candidate));
+            if (dialect)
+                return dialect;
         }
-        return false;
-    };
-    if (!matchesProvenance(rootReceiver)) {
-        if (rootReceiver !== 'this')
-            return false;
-        // For `this.xxx`, check if the method chain itself suggests DB usage
-        return isDBMethodOnThis(node, query);
-    }
-    // Check that the method is in the DB call/ORM API
-    return isDBMethodCall(node, query);
-}
-/**
- * Walk a member/selector expression chain to its root receiver text.
- * Returns `'this'` for `this.xxx` chains and `null` when no root is found.
- */
-function findRootReceiver(node, adapter, sourceCode) {
-    let current = node;
-    while (current.type === 'member_expression' || current.type === 'selector_expression') {
-        const children = adapter.getChildren(current);
-        const firstChild = children[0];
-        if (!firstChild)
-            break;
-        return resolveReceiverText(firstChild, adapter, sourceCode, 'this');
     }
     return null;
 }
-/**
- * Walk a member/selector-expression chain, returning true when any property in
- * the chain is a DB or ORM method. Shared by isDBMethodCall and
- * isDBMethodOnThis, which differ only in how they read a node's children.
- */
-function dbMethodInMemberChain(node, query, getChildren) {
-    const { adapter, sourceCode, methods } = query;
-    let current = node;
-    while (current.type === 'member_expression' ||
-        current.type === 'selector_expression') {
-        const children = getChildren(current);
-        // The property is typically the second or third child
-        for (const child of children) {
-            if (child.type === 'property_identifier' ||
-                child.type === 'field_identifier') {
-                const propName = adapter.getNodeText(child, sourceCode);
-                const lower = propName.toLowerCase();
-                if (methods.has(lower) || ORM_METHODS.has(lower)) {
-                    return true;
-                }
-            }
-        }
-        // Go deeper if there's a nested member/selector expression
-        const firstChild = children[0];
-        if (firstChild?.type === 'member_expression' ||
-            firstChild?.type === 'selector_expression') {
-            current = firstChild;
-        }
-        else {
-            break;
-        }
-    }
-    return false;
-}
-/**
- * Check if a call through a member expression uses a DB method
- * (exec, prepare, all, etc.) or an ORM method (find, insert, etc.).
- */
-function isDBMethodCall(node, query) {
-    return dbMethodInMemberChain(node, query, (n) => n.children ?? []);
-}
-/**
- * For `this.xxx.method()` calls — check if the method chain suggests DB access.
- * Used when the receiver is `this` (not directly DB-provenanced).
- */
-function isDBMethodOnThis(node, query) {
-    return dbMethodInMemberChain(node, query, (n) => query.adapter.getChildren(n));
-}
 /**
  * Check if an identifier is validator-provenanced (R4 infrastructure).
  *
@@ -1097,7 +1496,7 @@ function inferReceiverFromCall(node, ctx) {
     if (!callee || (callee.type !== 'member_expression' && callee.type !== 'selector_expression'))
         return;
     const methodName = extractMemberExpressionProperty(callee, adapter, sourceCode);
-    if (!methodName || !DB_CALL_METHODS.has(methodName.toLowerCase()))
+    if (!methodName || extractStaticSqlArgument(node, adapter, sourceCode) === null)
         return;
     const receiver = getMemberExpressionReceiver(callee, adapter, sourceCode);
     if (!receiver)
@@ -1106,7 +1505,7 @@ function inferReceiverFromCall(node, ctx) {
     if (provenancedSet.has(receiver) || seen.has(receiver))
         return;
     // Step 3: Trace receiver through assignment chain to a provenanced source
-    const traced = traceAssignmentChain(receiver, assignmentGraph, provenancedSet);
+    const traced = traceAssignmentChain(receiver, assignmentGraph, provenancedSet, adapter, sourceCode);
     if (traced.found) {
         seen.add(receiver);
         inferred.identifiers.push(receiver);
@@ -1118,7 +1517,8 @@ function inferReceiverFromCall(node, ctx) {
 }
 /**
  * Build a reverse assignment graph from the AST.
- * Maps variable name → the text of its initializer expression.
+ * Maps variable name → the *node* of its initializer expression (not its text,
+ * so the trace can walk it structurally rather than regex over a string).
  * Handles: const/let/var declarations, parameter defaults, class fields.
  */
 function buildAssignmentGraph(ast, adapter, sourceCode) {
@@ -1142,10 +1542,9 @@ function recordVariableDeclarator(node, ctx) {
     if (!nameNode || !valueNode)
         return;
     const names = extractPatternNames(nameNode, ctx.adapter, ctx.sourceCode);
-    const valueText = ctx.adapter.getNodeText(valueNode, ctx.sourceCode);
     for (const name of names) {
         if (!ctx.graph.has(name))
-            ctx.graph.set(name, valueText);
+            ctx.graph.set(name, valueNode);
     }
 }
 /** Record parameter defaults (`function foo(x = <expr>)`) into the graph. */
@@ -1161,14 +1560,12 @@ function recordParameterDefault(node, parent, ctx) {
     if (leftNode.type !== 'identifier')
         return;
     const paramName = ctx.adapter.getNodeText(leftNode, ctx.sourceCode);
-    const valueText = ctx.adapter.getNodeText(rightNode, ctx.sourceCode);
     if (!ctx.graph.has(paramName))
-        ctx.graph.set(paramName, valueText);
+        ctx.graph.set(paramName, rightNode);
 }
 /** Record class-field initializers (`fieldName = <expr>`) into the graph. */
 function recordClassField(node, ctx) {
-    if (node.type !== 'public_field_definition' &&
-        node.type !== 'field_definition') {
+    if (node.type !== 'public_field_definition') {
         return;
     }
     const children = ctx.adapter.getChildren(node);
@@ -1185,15 +1582,14 @@ function recordClassField(node, ctx) {
     if (!nameChild || !valueChild)
         return;
     const fieldName = ctx.adapter.getNodeText(nameChild, ctx.sourceCode);
-    const valueText = ctx.adapter.getNodeText(valueChild, ctx.sourceCode);
     if (!ctx.graph.has(fieldName))
-        ctx.graph.set(fieldName, valueText);
+        ctx.graph.set(fieldName, valueChild);
 }
 /**
  * Trace a receiver identifier through the assignment graph to see if it
  * ultimately resolves to a provenanced source.
  */
-function traceAssignmentChain(receiver, assignmentGraph, provenancedSet) {
+function traceAssignmentChain(receiver, assignmentGraph, provenancedSet, adapter, sourceCode) {
     const visited = new Set();
     const chain = [receiver];
     let current = receiver;
@@ -1208,9 +1604,9 @@ function traceAssignmentChain(receiver, assignmentGraph, provenancedSet) {
                 reason: provenancedSet.get(current).source,
             };
         }
-        const initText = assignmentGraph.get(current);
-        if (initText) {
-            const idents = extractTopLevelIdentifiers(initText);
+        const initNode = assignmentGraph.get(current);
+        if (initNode) {
+            const idents = extractTopLevelIdentifiers(initNode, adapter, sourceCode);
             for (const ident of idents) {
                 if (provenancedSet.has(ident)) {
                     chain.push(current);
@@ -1222,10 +1618,10 @@ function traceAssignmentChain(receiver, assignmentGraph, provenancedSet) {
                 }
             }
         }
-        if (!initText || visited.has(initText))
+        if (!initNode || visited.has(initNode))
             break;
-        visited.add(initText);
-        const next = findNextTraceIdentifier(initText, assignmentGraph, visited);
+        visited.add(initNode);
+        const next = findNextTraceIdentifier(initNode, assignmentGraph, visited, adapter, sourceCode);
         if (!next)
             break;
         chain.push(next);
@@ -1235,33 +1631,93 @@ function traceAssignmentChain(receiver, assignmentGraph, provenancedSet) {
     return { found: false, chains: [], reason: '' };
 }
 /** Find the next assignment-graph identifier to trace, if any. */
-function findNextTraceIdentifier(initText, assignmentGraph, visited) {
-    const idents = extractTopLevelIdentifiers(initText);
+function findNextTraceIdentifier(initNode, assignmentGraph, visited, adapter, sourceCode) {
+    const idents = extractTopLevelIdentifiers(initNode, adapter, sourceCode);
     for (const ident of idents) {
-        if (assignmentGraph.has(ident) && !visited.has(ident)) {
+        const nextNode = assignmentGraph.get(ident);
+        if (nextNode && !visited.has(nextNode)) {
             return ident;
         }
     }
     return null;
 }
 /**
- * Extract top-level identifier names from an expression text.
- * E.g., "db.prepare(sql)" → ["db"], "getConnection()" → ["getConnection"]
+ * Extract the top-level identifier name from an initializer-expression node.
+ * Walks the node structurally to its root identifier — through `await`,
+ * parentheses, calls, member access, and subscripts — so `await db.connect()`
+ * yields `db` rather than `await`, and `(db.prepare(sql))` yields `db`.
+ * E.g., `db.prepare(sql)` → ["db"], `getConnection()` → ["getConnection"].
+ *
+ * @param node the initializer-expression node to walk from
+ * @param adapter the language adapter used to walk child nodes
+ * @param sourceCode the file source text for reading node text
+ * @returns the root identifier name, or an empty array when there is none
+ */
+export function extractTopLevelIdentifiers(node, adapter, sourceCode) {
+    const root = rootIdentifierNode(node, adapter);
+    if (!root)
+        return [];
+    const name = adapter.getNodeText(root, sourceCode);
+    return name ? [name] : [];
+}
+/**
+ * The root identifier a value node resolves to, or null when the value is not a
+ * bare identifier chain (e.g. a binary expression or literal). Descends through
+ * `await_expression`, `parenthesized_expression`, `call_expression`/
+ * `new_expression` (via their callee), `member_expression`/`selector_expression`
+ * (via their receiver), and `subscript_expression` (via their object).
  */
-function extractTopLevelIdentifiers(text) {
-    // Strip member access and arguments to get the root identifier
-    // Match the first identifier before any '.' or '('
-    const match = text.match(/^[\p{L}_$][\p{L}\p{N}_$]*/u);
-    if (match && match[0]) {
-        return [match[0]];
+function rootIdentifierNode(node, adapter) {
+    let current = node;
+    for (let depth = 0; depth < 64; depth++) {
+        const t = adapter.getNodeType(current);
+        if (t === 'identifier')
+            return current;
+        const children = adapter.getChildren(current) ?? [];
+        let next = null;
+        if (t === 'await_expression') {
+            next = children.find((c) => adapter.getNodeType(c) !== 'await') ?? null;
+        }
+        else if (t === 'parenthesized_expression') {
+            next = children.find((c) => {
+                const ct = adapter.getNodeType(c);
+                return ct !== '(' && ct !== ')';
+            }) ?? null;
+        }
+        else if (t === 'call_expression' || t === 'new_expression') {
+            next = getCallExpressionCallee(current, adapter);
+        }
+        else if (t === 'member_expression' || t === 'selector_expression') {
+            next = children.find((c) => {
+                const ct = adapter.getNodeType(c);
+                return ct !== '.' && ct !== 'property_identifier' && ct !== 'field_identifier';
+            }) ?? null;
+        }
+        else if (t === 'subscript_expression') {
+            next = children.find((c) => {
+                const ct = adapter.getNodeType(c);
+                return ct !== '[' && ct !== ']';
+            }) ?? null;
+        }
+        else {
+            break;
+        }
+        if (!next)
+            break;
+        current = next;
     }
-    return [];
+    return adapter.getNodeType(current) === 'identifier' ? current : null;
 }
 /**
  * Extract the property name from a member expression node.
  * For `db.prepare` → "prepare", for `db.sql.prepare` → "prepare"
+ *
+ * @param node the member/selector expression node
+ * @param adapter the language adapter used to read children
+ * @param sourceCode the file source text for reading node text
+ * @returns the property identifier text, or `null`
  */
-function extractMemberExpressionProperty(node, adapter, sourceCode) {
+export function extractMemberExpressionProperty(node, adapter, sourceCode) {
     const children = adapter.getChildren(node);
     // The property is the last non-dot child
     for (let i = children.length - 1; i >= 0; i--) {
@@ -1272,4 +1728,228 @@ function extractMemberExpressionProperty(node, adapter, sourceCode) {
     }
     return null;
 }
+// ═══════════════════════════════════════════════════════════════════════════
+// TS within-file-provenance split — the extract arm (Spec 70 Item 4 / Item 3)
+// ═══════════════════════════════════════════════════════════════════════════
+//
+// `extractTsWithinFileProvenance` projects everything `computeTsWithinFileProvenance`
+// reads from a single file's AST into a serializable `TsWithinFileProvenanceExtract`
+// (see tsExpressionDescriptor.ts). The classify arm re-runs the fixed point over the
+// projection with no AST. The two are pinned byte-identical by the parity spec.
+//
+// Every helper below is the *structural* half — provenance-free — so it may run at
+// extract time. The semantic half (which name resolves to which evidence) is
+// deferred to classify, where the provenance map is known.
+/** Project an `await` expression: the first non-`await` child carries the value. */
+function describeAwaitExpression(node, adapter, sourceCode) {
+    for (const child of adapter.getChildren(node)) {
+        if (child.type === 'await')
+            continue;
+        return { kind: 'await', operand: describeTsExpression(child, adapter, sourceCode) };
+    }
+    return { kind: 'await', operand: null };
+}
+/** Project a `new` expression: the leftmost identifier of its constructor. */
+function describeNewExpression(node, adapter, sourceCode) {
+    const ctor = findChildOfType(node, ['identifier', 'member_expression']);
+    return { kind: 'new', ctorName: ctor ? extractIdentifierName(ctor, adapter, sourceCode) : null };
+}
+/** Project a call expression: the callee (via `getCallExpressionCallee`) + its args. */
+function describeCallExpression(node, adapter, sourceCode) {
+    const calleeNode = getCallExpressionCallee(node, adapter);
+    const callee = calleeNode ? describeTsExpression(calleeNode, adapter, sourceCode) : null;
+    const argsNode = adapter.getChildren(node).find((c) => c.type === 'arguments');
+    const args = [];
+    if (argsNode) {
+        for (const arg of adapter.getChildren(argsNode)) {
+            if (arg.type === '(' || arg.type === ')' || arg.type === ',')
+                continue;
+            args.push(describeTsExpression(arg, adapter, sourceCode));
+        }
+    }
+    return { kind: 'call', callee, args };
+}
+/** Project a member expression: receiver (object) + property + full source text. */
+function describeMemberExpression(node, adapter, sourceCode) {
+    const children = adapter.getChildren(node);
+    const receiver = children[0] ? describeTsExpression(children[0], adapter, sourceCode) : null;
+    let property = null;
+    for (const child of children) {
+        if (child.type === 'property_identifier' || child.type === 'field_identifier') {
+            property = adapter.getNodeText(child, sourceCode);
+            break;
+        }
+    }
+    return { kind: 'member', receiver, property, text: adapter.getNodeText(node, sourceCode) };
+}
+/**
+ * Project a value-expression node into a {@link TsExpressionDescriptor}. Mirrors
+ * the *structural* dispatch of `tryPropagateFromExpression`: `await` → `new` →
+ * `call` → `identifier` → `member`, and anything else collapses to `unproven`.
+ */
+function describeTsExpression(node, adapter, sourceCode) {
+    switch (node.type) {
+        case 'await_expression':
+            return describeAwaitExpression(node, adapter, sourceCode);
+        case 'new_expression':
+            return describeNewExpression(node, adapter, sourceCode);
+        case 'call_expression':
+            return describeCallExpression(node, adapter, sourceCode);
+        case 'identifier':
+            return { kind: 'identifier', name: adapter.getNodeText(node, sourceCode) };
+        case 'member_expression':
+            return describeMemberExpression(node, adapter, sourceCode);
+        default:
+            return { kind: 'unproven' };
+    }
+}
+/** Child types excluded when locating a class-field initializer (mirrors `propagateClassField`). */
+const CLASS_FIELD_EXCLUDED = new Set([
+    'property_identifier',
+    'decorator',
+    'accessibility_modifier',
+    'private',
+    'public',
+    'protected',
+    'static',
+    'readonly',
+    'abstract',
+    'type_annotation',
+]);
+/**
+ * Project a single file's AST into the serializable {@link TsWithinFileProvenanceExtract}
+ * that `classifyTsWithinFileProvenance` re-runs the provenance fixed point over.
+ *
+ * Everything here is provenance-free (structural reads of the AST + source text),
+ * so it can run once at parse time and be carried as a file fact. The semantic
+ * resolution — which name a value resolves to under the current provenance map —
+ * is deferred to the classify arm.
+ * @param ast - The file's parsed AST.
+ * @param adapter - The language adapter (drives the walk + node-text reads).
+ * @param sourceCode - The file's source text (for structural reads).
+ * @returns The provenance-free `TsWithinFileProvenanceExtract` projection.
+ */
+export function extractTsWithinFileProvenance(ast, adapter, sourceCode) {
+    const seeds = extractDBProvenancedImports(ast, adapter);
+    const localFunctions = collectLocalFunctionNames(ast, adapter, sourceCode);
+    const bindings = buildBindingEnv(ast, adapter, sourceCode);
+    const interfaceFields = extractInterfaceFields(ast, adapter, sourceCode);
+    // ── Propagation rules, in `walkAST` pre-order ─────────────────────────────
+    const propagationRules = [];
+    walkAST(ast.root, (node, parent) => {
+        if (node.type === 'variable_declarator') {
+            const { nameNode, valueNode } = splitVariableDeclarator(node, adapter);
+            if (!nameNode)
+                return;
+            const names = extractPatternNames(nameNode, adapter, sourceCode);
+            const value = valueNode ? describeTsExpression(valueNode, adapter, sourceCode) : null;
+            propagationRules.push({ kind: 'variable-declarator', names, value });
+            return;
+        }
+        if (node.type === 'assignment_pattern' && parent?.type === 'formal_parameters') {
+            const children = adapter.getChildren(node);
+            if (children.length < 2 || children[0].type !== 'identifier')
+                return;
+            propagationRules.push({
+                kind: 'default-parameter',
+                name: adapter.getNodeText(children[0], sourceCode),
+                value: describeTsExpression(children[1], adapter, sourceCode),
+            });
+            return;
+        }
+        if (node.type === 'public_field_definition') {
+            const children = adapter.getChildren(node);
+            const nameChild = children.find((c) => c.type === 'property_identifier');
+            if (!nameChild)
+                return;
+            const valueChild = children.find((c) => !CLASS_FIELD_EXCLUDED.has(c.type));
+            if (!valueChild)
+                return;
+            propagationRules.push({
+                kind: 'class-field',
+                field: adapter.getNodeText(nameChild, sourceCode),
+                value: describeTsExpression(valueChild, adapter, sourceCode),
+            });
+            return;
+        }
+        if (node.type === 'assignment_expression') {
+            const children = adapter.getChildren(node);
+            const lhs = children.find((c) => c.type === 'member_expression' || c.type === 'selector_expression');
+            if (!lhs)
+                return;
+            const lhsChildren = adapter.getChildren(lhs);
+            const obj = lhsChildren.find((c) => c.type === 'this' || c.type === 'super');
+            if (!obj)
+                return;
+            const prop = lhsChildren.find((c) => c.type === 'property_identifier' || c.type === 'field_identifier');
+            if (!prop)
+                return;
+            const fieldName = adapter.getNodeText(prop, sourceCode);
+            if (!fieldName)
+                return;
+            const rhs = children[children.length - 1];
+            if (!rhs || rhs.type === 'member_expression' || rhs.type === 'selector_expression')
+                return;
+            propagationRules.push({
+                kind: 'member-assignment',
+                field: fieldName,
+                value: describeTsExpression(rhs, adapter, sourceCode),
+            });
+            return;
+        }
+    });
+    // ── Wrapper functions, wrapper classes, returning functions ────────────────
+    // One `findNodes` pass for functions (wrappers + returning) and one for classes,
+    // matching the order `detectDbWrappers` / `detectDbReturningFunctions` consume.
+    const wrapperFunctions = [];
+    const returningFunctions = [];
+    const functionNodes = adapter.findNodes(ast, {
+        custom: (n) => FUNCTION_NODE_TYPES.has(n.type),
+    });
+    for (const fn of functionNodes) {
+        const name = adapter.getNodeName(fn);
+        if (!name)
+            continue;
+        const ownCalls = collectOwnCallExpressions(fn, adapter).map((call) => ({
+            callee: getCallExpressionCallee(call, adapter)
+                ? describeTsExpression(getCallExpressionCallee(call, adapter), adapter, sourceCode)
+                : null,
+            isD1Rest: isD1RestCall(call, adapter, sourceCode),
+        }));
+        wrapperFunctions.push({ name, ownCalls });
+        const returnExprs = [];
+        walkAST(fn, (n) => {
+            if (n.type !== 'return_statement')
+                return;
+            const arg = adapter.getChildren(n).find((c) => c.type !== 'return');
+            if (!arg)
+                return;
+            returnExprs.push(describeTsExpression(arg, adapter, sourceCode));
+        });
+        returningFunctions.push({ name, returnExprs });
+    }
+    const wrapperClasses = [];
+    const classNodes = adapter.findNodes(ast, {
+        custom: (n) => WRAPPER_CLASS_TYPES.has(n.type),
+    });
+    for (const cls of classNodes) {
+        const name = adapter.getNodeName(cls);
+        if (!name)
+            continue;
+        const classCalls = collectClassCallExpressions(cls, adapter).map((expr) => {
+            if (expr.type === 'new_expression') {
+                const ctor = findChildOfType(expr, ['identifier', 'member_expression']);
+                return { kind: 'new', ctorName: ctor ? extractIdentifierName(ctor, adapter, sourceCode) : null };
+            }
+            const calleeNode = getCallExpressionCallee(expr, adapter);
+            return {
+                kind: 'call',
+                callee: calleeNode ? describeTsExpression(calleeNode, adapter, sourceCode) : null,
+                isD1Rest: isD1RestCall(expr, adapter, sourceCode),
+            };
+        });
+        wrapperClasses.push({ name, classCalls });
+    }
+    return { seeds, bindings, localFunctions, propagationRules, wrapperFunctions, wrapperClasses, returningFunctions, interfaceFields };
+}
 //# sourceMappingURL=provenance.js.map