knodin 0.12.2 → 0.13.0

package/dist/src/engine/index.js

@@ -10,6 +10,7 @@
  *
  * This file implements the Phase 1: SQLite + Tree-Sitter Core engine.
  */
+import { AsyncLocalStorage } from "node:async_hooks";
 import child_process from "node:child_process";
 import crypto from "node:crypto";
 import fs from "node:fs";
@@ -18,21 +19,31 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import chokidar from "chokidar";
 import Parser from "web-tree-sitter";
+import { ClassConsumerQueryError, } from "../class-consumer-contract.js";
+import { readClassConsumerCursor } from "../class-consumer-cursor.js";
+import { finalizeClassConsumerPage } from "../class-consumer-page.js";
 import { compareBytes } from "../compare.js";
+import { isFileRelationship } from "../file-dependency.js";
 import { collectFileMetrics } from "../file-metrics.js";
 import { readIndexActivity } from "../index-activity.js";
 import { runReadOnlyLspQuery } from "../lsp-readonly.js";
+import { evidenceHandleSecret } from "../progressive-evidence.js";
 import { acquireRepairLease } from "../repair-lease.js";
 import { analyzeResourceReachability, resourceFingerprint, } from "../resource-reachability.js";
 import { contentFingerprint, writeStructuralSnapshot, } from "../structural-snapshot.js";
 import { acquireLifecycleCoordination } from "../update-coordination.js";
 import { KNODIN_VERSION } from "../version.js";
 import * as ann from "./ann-hnsw.js";
+import { createApexConsumerCatalog, extractApexClassUses, resolveApexClassUses, } from "./apex-class-uses.js";
+import { apexOrgEntryPoints } from "./apex-entry-points.js";
+import { apexCall, apexDeclaration, apexReceiverCapability, apexReferenceReadGuard, parseApexDeclaration, persistApexReferenceEndpoints, } from "./apex-receiver.js";
 import { allocateCandidate, assertCandidate, discardCandidateFiles, listCandidates, promoteCandidateFile, recoverInterruptedPromotion, sweepAbandonedCandidates, } from "./candidate-database.js";
-import { computeSimilarity, generateEmbedding, generateEmbeddings, } from "./embeddings.js";
+import { EmbeddingReuseCache, embeddingReuseKey } from "./embedding-reuse.js";
+import { computeSimilarity, generateEmbedding, generateEmbeddings, getEmbeddingCacheIdentity, } from "./embeddings.js";
 import { walkRepoFiles } from "./file-walker.js";
 import { clearGitHistorySignalCache, collectGitHistorySignals, } from "./git-history.js";
 import { isLinkedWorktree } from "./git-layout.js";
+import { canonicalCoveragePath, coverageContains, coverageGitPathspecBatches, coverageMayContain, INDEX_COVERAGE_COMPLETE_KEY, INDEX_COVERAGE_KEY, INDEX_COVERAGE_PENDING_KEY, indexCoverageSummary, mergeIndexCoverage, readIndexCoverage, requireIndexCoverage, } from "./index-coverage.js";
 // Runtime import, but not a cycle: parse-pool imports only TYPES from here,
 // which erase at compile time. parse-worker's runtime import of this module
 // resolves inside the worker thread, never in this one.
@@ -40,6 +51,7 @@ import { createParsePool, parseWorkersEnabled } from "./parse-pool.js";
 import { beginPerfPhase, measurePerfPhase, measurePerfPhaseSync } from "./perf.js";
 import { isIndexablePath, makeWatchIgnorePredicate } from "./prune.js";
 import { reflinkCopyFile } from "./reflink-copy.js";
+import { componentBindings, componentCatalog, visualforceInlineScripts, } from "./salesforce-components.js";
 import { readSarifLog, SARIF_DEFAULT_LIMITS, } from "./sarif-import.js";
 import { readScipIndex, SCIP_DEFAULT_LIMITS, } from "./scip-import.js";
 import { isSealedDatabase, listSealedFiles, readSealedSource } from "./seal.js";
@@ -511,7 +523,7 @@ function referencesForFiles(db, filePaths) {
     }
     return [...rows.values()];
 }
-function persistSymbolIdentities(db, repoPath, filePaths) {
+function persistSymbolIdentities(db, repoPath, filePaths, deferApex = false) {
     const scope = scopedFilePaths(filePaths);
     const rows = symbolsForFiles(db, scope);
     const update = db.query("UPDATE symbols SET identity = ? WHERE id = ?");
@@ -579,7 +591,7 @@ function persistSymbolIdentities(db, repoPath, filePaths) {
                 update.run(identity, row.id);
         }
         update.finalize();
-        persistReferenceEndpoints(db, scope);
+        persistReferenceEndpoints(db, scope, deferApex);
         db.run("RELEASE persist_symbol_identities;");
     }
     catch (error) {
@@ -599,15 +611,26 @@ async function persistSymbolIdentitiesCancellable(db, repoPath, filePaths, signa
         : (scopedFilePaths(filePaths) ?? []);
     for (const file of scope) {
         throwIfAborted(signal);
-        persistSymbolIdentities(db, repoPath, [file]);
+        persistSymbolIdentities(db, repoPath, [file], true);
         await yieldToIndexEventLoop();
     }
+    if (scope.some((file) => /\.(?:cls|trigger)$/i.test(file))) {
+        persistApexReferenceEndpoints(db);
+        persistApexClassConsumerEndpoints(db);
+    }
 }
 /** Bind name/file reference rows to exact definitions after identities exist. */
-function persistReferenceEndpoints(db, filePaths) {
+function persistReferenceEndpoints(db, filePaths, deferApex = false) {
+    const resolveApex = !deferApex &&
+        (filePaths === undefined || filePaths.some((file) => /\.(?:cls|trigger)$/i.test(file)));
     const refs = referencesForFiles(db, filePaths);
-    if (refs.length === 0)
+    if (refs.length === 0) {
+        if (resolveApex) {
+            persistApexReferenceEndpoints(db);
+            persistApexClassConsumerEndpoints(db);
+        }
         return;
+    }
     const definitionFiles = filePaths === undefined
         ? undefined
         : [
@@ -670,7 +693,7 @@ function persistReferenceEndpoints(db, filePaths) {
         const caller = choose(ref.callerSymbol, ref.callerFile, ref.line);
         // Never invent an endpoint for an ambiguous name/file pair. Parsers can
         // later provide a qualified identity; until then ambiguity remains explicit.
-        const callee = ref.calleeFile
+        const callee = ref.calleeFile && !ref.apexCall
             ? chooseScopedCallee(ref.calleeSymbol, ref.calleeFile, ref.line)
             : undefined;
         const callerIdentity = caller?.identity ?? null;
@@ -680,6 +703,835 @@ function persistReferenceEndpoints(db, filePaths) {
         }
     }
     update.finalize();
+    if (resolveApex) {
+        persistApexReferenceEndpoints(db);
+        persistApexClassConsumerEndpoints(db);
+    }
+}
+const APEX_CONSUMER_BINDING_VERSION = "2-interface-types";
+/** Classes retain receiver provenance; interfaces use their independent parser span proof. */
+function apexConsumerSymbolOwner(db, symbol, cache) {
+    if (symbol.kind === "class" &&
+        !cache
+            .get(symbol.filePath)
+            ?.declarations.some((declaration) => declaration.kind === "class" &&
+            declaration.name === symbol.name &&
+            declaration.declarationRange?.start.line === symbol.startLine &&
+            declaration.declarationRange.start.column - 1 === symbol.startCol))
+        return parseApexDeclaration(symbol.apexDeclaration)?.owner ?? null;
+    if (symbol.kind !== "interface" && symbol.kind !== "class")
+        return null;
+    if (!cache.has(symbol.filePath)) {
+        const row = db
+            .query("SELECT f.* FROM apex_consumer_files f JOIN index_state i ON i.filePath=f.filePath WHERE f.filePath=?")
+            .get(symbol.filePath);
+        cache.set(symbol.filePath, row ? readApexConsumerFacts(row) : null);
+    }
+    const facts = cache.get(symbol.filePath);
+    if (facts?.parseState !== "complete")
+        return null;
+    const matches = facts.declarations.filter((declaration) => {
+        const range = declaration.declarationRange;
+        return (declaration.kind === symbol.kind &&
+            declaration.name === symbol.name &&
+            range &&
+            range.start.line === symbol.startLine &&
+            range.start.column - 1 === symbol.startCol &&
+            range.end.line === symbol.endLine &&
+            range.end.column - 1 === symbol.endCol);
+    });
+    return matches.length === 1 ? matches[0].ownerPath : null;
+}
+const apexConsumerKinds = new Set([
+    "static_field_read",
+    "constructor",
+    "variable_type",
+    "cast",
+    "class_literal",
+    "parameter_type",
+    "generic_parameter_type",
+    "loop_variable_type",
+    "generic_type_argument",
+]);
+function validConsumerPosition(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const p = value;
+    return ["line", "column", "utf16Offset", "byte"].every((key) => Number.isSafeInteger(p[key]) &&
+        p[key] >= (key === "line" || key === "column" ? 1 : 0));
+}
+function validConsumerSite(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const site = value;
+    return (site.version === 1 &&
+        apexConsumerKinds.has(site.kind) &&
+        typeof site.qualifiedSpelling === "string" &&
+        typeof site.typePath === "string" &&
+        /^[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*$/.test(site.typePath) &&
+        (site.memberName === null || typeof site.memberName === "string") &&
+        (site.lexicalOwner === null || typeof site.lexicalOwner === "string") &&
+        [null, "value-shadow", "malformed-source"].includes(site.blockedReason) &&
+        validConsumerPosition(site.start) &&
+        validConsumerPosition(site.end) &&
+        site.end.byte > site.start.byte &&
+        site.end.utf16Offset > site.start.utf16Offset);
+}
+function readApexConsumerFacts(row) {
+    if (row.version !== 1 ||
+        row.facts.length > 32 * 1024 * 1024 ||
+        crypto.createHash("sha256").update(row.facts).digest("hex") !== row.factsHash)
+        return null;
+    try {
+        const facts = JSON.parse(row.facts);
+        if (facts.heritageComplete !== undefined && typeof facts.heritageComplete !== "boolean")
+            return null;
+        if (facts.heritage !== undefined &&
+            (!Array.isArray(facts.heritage) ||
+                !facts.heritage.every((entry) => ["extends", "implements"].includes(entry.kind) &&
+                    typeof entry.ownerPath === "string" &&
+                    typeof entry.typePath === "string" &&
+                    /^[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*$/.test(entry.typePath) &&
+                    validConsumerPosition(entry.start) &&
+                    validConsumerPosition(entry.end) &&
+                    entry.start.byte < entry.end.byte)))
+            return null;
+        if ("omissionReason" in facts &&
+            (!["source-size-limit", "parser-unavailable", "parser-failure"].includes(String(facts.omissionReason)) ||
+                facts.parseState !== "partial" ||
+                facts.isTest !== null ||
+                !Array.isArray(facts.sites) ||
+                facts.sites.length !== 0 ||
+                !Array.isArray(facts.declarations) ||
+                facts.declarations.length !== 0 ||
+                !Array.isArray(facts.unsupportedUses) ||
+                facts.unsupportedUses.length !== 0))
+            return null;
+        if (facts.version !== 1 ||
+            facts.file !== row.filePath ||
+            facts.sourceHash !== row.sourceHash ||
+            !/^[a-f0-9]{64}$/.test(facts.sourceHash) ||
+            facts.parseState !== row.parseState ||
+            !["complete", "partial"].includes(facts.parseState) ||
+            facts.coverage !== "supported-syntax-only" ||
+            !(facts.isTest === null || typeof facts.isTest === "boolean") ||
+            (facts.isTest === null ? null : facts.isTest ? 1 : 0) !== row.isTest ||
+            !Array.isArray(facts.sites) ||
+            !facts.sites.every(validConsumerSite) ||
+            !Array.isArray(facts.declarations) ||
+            !Array.isArray(facts.unsupportedUses))
+            return null;
+        if (!facts.declarations.every((decl) => decl.version === 1 &&
+            ["class", "interface", "enum", "field", "property"].includes(decl.kind) &&
+            typeof decl.ownerPath === "string" &&
+            typeof decl.name === "string" &&
+            typeof decl.static === "boolean" &&
+            (decl.superclass === null || typeof decl.superclass === "string") &&
+            Array.isArray(decl.annotations) &&
+            decl.annotations.every((a) => typeof a === "string") &&
+            validConsumerPosition(decl.start) &&
+            validConsumerPosition(decl.end) &&
+            (decl.declarationRange === undefined ||
+                (validConsumerPosition(decl.declarationRange.start) &&
+                    validConsumerPosition(decl.declarationRange.end) &&
+                    decl.declarationRange.start.byte <= decl.start.byte &&
+                    decl.declarationRange.end.byte >= decl.end.byte))))
+            return null;
+        return facts;
+    }
+    catch {
+        return null;
+    }
+}
+/** Rebind retained typed facts after identities exist, without reading repository source. */
+function apexConsumerMaterializationDigest(db) {
+    const hash = crypto.createHash("sha256");
+    let after;
+    for (;;) {
+        const rows = db
+            .query(`SELECT filePath,startByte,endByte,kind,raw,status,targetFile,targetOwner,targetIdentity,ownerIdentity,isTest FROM apex_class_uses ${after ? "WHERE (filePath COLLATE BINARY,startByte,endByte,kind COLLATE BINARY)>(? COLLATE BINARY,?,?,? COLLATE BINARY)" : ""} ORDER BY filePath COLLATE BINARY,startByte,endByte,kind COLLATE BINARY LIMIT 500`)
+            .all(...(after ? [after.filePath, after.startByte, after.endByte, after.kind] : []));
+        for (const row of rows)
+            hash.update(JSON.stringify(row)).update("\n");
+        if (rows.length < 500)
+            break;
+        after = rows[rows.length - 1];
+    }
+    return hash.digest("hex");
+}
+function apexConsumerMaterializationValid(db) {
+    if (db
+        .query("SELECT COUNT(*) count FROM sqlite_master WHERE type='table' AND name IN ('apex_class_uses','apex_consumer_files')")
+        .get()?.count !== 2)
+        return false;
+    const stored = db
+        .query("SELECT f.* FROM apex_consumer_files f JOIN index_state i ON i.filePath=f.filePath")
+        .all();
+    const facts = stored.map(readApexConsumerFacts);
+    if (facts.includes(null))
+        return false;
+    const expected = facts.reduce((sum, fact) => sum + (fact?.sites.length ?? 0), 0);
+    if ((db.query("SELECT COUNT(*) count FROM apex_class_uses").get()?.count ??
+        0) !== expected)
+        return false;
+    return Boolean(getMeta(db, "apexConsumerBindingVersion") === APEX_CONSUMER_BINDING_VERSION &&
+        getMeta(db, "apexConsumerFactsRevision") &&
+        getMeta(db, "apexConsumerFactsRevision") === getMeta(db, "apexConsumerBoundRevision") &&
+        getMeta(db, "apexConsumerMaterializationDigest") === apexConsumerMaterializationDigest(db));
+}
+function persistApexClassConsumerEndpoints(db) {
+    const stored = db
+        .query("SELECT f.* FROM apex_consumer_files f JOIN index_state i ON i.filePath=f.filePath")
+        .all();
+    const facts = stored
+        .map(readApexConsumerFacts)
+        .filter((fact) => fact !== null);
+    const catalog = createApexConsumerCatalog(facts);
+    const symbols = db
+        .query("SELECT * FROM symbols WHERE kind IN ('class','interface')")
+        .all();
+    const factsByFile = new Map(facts.map((file) => [file.file, file]));
+    const identities = new Map();
+    for (const symbol of symbols) {
+        const owner = apexConsumerSymbolOwner(db, symbol, factsByFile);
+        if (!owner || !symbol.identity)
+            continue;
+        const key = `${symbol.filePath}\0${owner.toLowerCase()}`;
+        const entries = identities.get(key) ?? [];
+        entries.push(symbol.identity);
+        identities.set(key, entries);
+    }
+    const identity = (file, owner) => {
+        const candidates = owner ? identities.get(`${file}\0${owner.toLowerCase()}`) : undefined;
+        return candidates?.length === 1 ? candidates[0] : null;
+    };
+    db.run("SAVEPOINT apex_consumer_rebind");
+    try {
+        db.run("DELETE FROM apex_class_uses");
+        const insert = db.prepare("INSERT INTO apex_class_uses(filePath,startByte,endByte,kind,raw,status,targetFile,targetOwner,targetIdentity,ownerIdentity,isTest) VALUES (?,?,?,?,?,?,?,?,?,?,?)");
+        try {
+            for (const file of facts) {
+                for (const resolved of resolveApexClassUses(catalog, file)) {
+                    const targetIdentity = resolved.target
+                        ? identity(resolved.target.file, resolved.target.declaration.ownerPath)
+                        : null;
+                    const status = stored.length !== facts.length || (resolved.status === "resolved" && !targetIdentity)
+                        ? "blocked"
+                        : resolved.status;
+                    insert.run(file.file, resolved.site.start.byte, resolved.site.end.byte, resolved.site.kind, JSON.stringify(resolved.site), status, resolved.target?.file ?? null, resolved.target?.declaration.ownerPath ?? null, status === "resolved" ? targetIdentity : null, identity(file.file, resolved.site.lexicalOwner), file.isTest === null ? null : file.isTest ? 1 : 0);
+                }
+            }
+        }
+        finally {
+            insert.finalize();
+        }
+        setMeta(db, "apexConsumerBoundRevision", getMeta(db, "apexConsumerFactsRevision") ?? "");
+        setMeta(db, "apexConsumerBindingVersion", APEX_CONSUMER_BINDING_VERSION);
+        setMeta(db, "apexConsumerMaterializationDigest", apexConsumerMaterializationDigest(db));
+        db.run("RELEASE apex_consumer_rebind");
+    }
+    catch (error) {
+        db.run("ROLLBACK TO apex_consumer_rebind");
+        db.run("RELEASE apex_consumer_rebind");
+        throw error;
+    }
+}
+function missingApexConsumerDescriptorFiles(db) {
+    const files = db
+        .query("SELECT filePath FROM index_state WHERE lower(filePath) LIKE '%.cls' OR lower(filePath) LIKE '%.trigger'")
+        .all()
+        .map((row) => row.filePath);
+    if (!files.length)
+        return [];
+    const hasTable = db
+        .query("SELECT COUNT(*) count FROM sqlite_master WHERE type='table' AND name='apex_consumer_files'")
+        .get()?.count === 1;
+    if (!hasTable)
+        return files;
+    const valid = new Set(db
+        .query("SELECT * FROM apex_consumer_files")
+        .all()
+        .filter((row) => {
+        const facts = readApexConsumerFacts(row);
+        if (!facts)
+            return false;
+        if (facts.parseState !== "complete")
+            return true;
+        if (facts.heritage === undefined &&
+            facts.unsupportedUses.some((use) => use.kind === "inheritance"))
+            return false;
+        const interfaces = facts.declarations.filter((d) => d.kind === "interface");
+        if (!interfaces.length)
+            return true;
+        const symbols = db
+            .query("SELECT * FROM symbols WHERE filePath=? AND kind='interface' AND identity IS NOT NULL")
+            .all(row.filePath);
+        const cache = new Map([[row.filePath, facts]]);
+        return interfaces.every((declaration) => declaration.declarationRange &&
+            symbols.some((symbol) => apexConsumerSymbolOwner(db, symbol, cache) === declaration.ownerPath));
+    })
+        .map((row) => row.filePath));
+    return files.filter((file) => !valid.has(file));
+}
+const apexConsumerValidationMemo = new Map();
+const apexConsumerFastHits = new WeakMap();
+const apexConsumerValidationMemoStats = new WeakMap();
+const APEX_CONSUMER_MEMO_MAX_ENTRIES = 4;
+const APEX_CONSUMER_MEMO_MAX_BYTES = 8 * 1024 * 1024;
+/** Diagnostic counters only; never expose retained source or descriptors. */
+export function getApexConsumerValidationMemoStats(db) {
+    return {
+        ...(apexConsumerValidationMemoStats.get(db) ?? { hits: 0, misses: 0 }),
+        retainedBytes: apexConsumerValidationMemo.get(db)?.retainedBytes ?? 0,
+        fastHits: apexConsumerFastHits.get(db) ?? 0,
+    };
+}
+/** Normal SQLite commit/snapshot semantics, not protection against malicious counter or file manipulation. */
+function apexConsumerSnapshotStamp(db, transaction) {
+    const identity = db.readSnapshotIdentity();
+    if (identity.replaced) {
+        apexConsumerValidationMemo.delete(db);
+        throw new Error("Graph database file was replaced; reopen the engine before querying.");
+    }
+    if (identity.transaction !== transaction || identity.fileStamp === null)
+        return null;
+    try {
+        // This read lazily opens TEMP on a fresh connection. Normalize it before
+        // sampling attachments so our own inspection does not invalidate the proof.
+        const tempSchemaVersion = db
+            .query("PRAGMA temp.schema_version")
+            .get()?.schema_version;
+        const attachments = db.query("PRAGMA database_list").all();
+        if (attachments.some((row) => row.name !== "main" && row.name !== "temp"))
+            return null;
+        if (db.query("PRAGMA read_uncommitted").get()
+            ?.read_uncommitted !== 0)
+            return null;
+        const values = [
+            db.query("PRAGMA main.data_version").get()?.data_version,
+            db.query("SELECT total_changes() value").get()?.value,
+            db.query("PRAGMA main.schema_version").get()?.schema_version,
+            tempSchemaVersion,
+        ];
+        if (!values.every((value) => Number.isSafeInteger(value) && value >= 0))
+            return null;
+        const schema = db
+            .query("SELECT 'main' origin,name,sql FROM main.sqlite_master UNION ALL SELECT 'temp' origin,name,sql FROM sqlite_temp_master ORDER BY origin COLLATE BINARY,name COLLATE BINARY")
+            .all();
+        return crypto
+            .createHash("sha256")
+            .update(JSON.stringify([identity.fileStamp, attachments, values, schema]))
+            .digest("hex");
+    }
+    catch {
+        return null;
+    }
+}
+function releaseApexConsumerRead(db, eligible, completed, proof) {
+    try {
+        db.run("RELEASE class_consumer_read");
+        const afterStamp = eligible ? apexConsumerSnapshotStamp(db, false) : null;
+        const cached = apexConsumerValidationMemo.get(db);
+        if (cached) {
+            if (completed && proof && afterStamp === proof.stamp && cached.key === proof.validationDigest)
+                cached.fastProof = proof;
+            else
+                delete cached.fastProof;
+        }
+    }
+    catch (error) {
+        const cached = apexConsumerValidationMemo.get(db);
+        if (cached)
+            delete cached.fastProof;
+        throw error;
+    }
+}
+function validatedApexConsumerSummary(db, stored, key) {
+    const stats = apexConsumerValidationMemoStats.get(db) ?? { hits: 0, misses: 0 };
+    apexConsumerValidationMemoStats.set(db, stats);
+    const cached = apexConsumerValidationMemo.get(db);
+    if (cached?.key === key) {
+        stats.hits++;
+        apexConsumerValidationMemo.delete(db);
+        apexConsumerValidationMemo.set(db, cached);
+        return cached.summary;
+    }
+    stats.misses++;
+    apexConsumerValidationMemo.delete(db);
+    const valid = stored
+        .map(readApexConsumerFacts)
+        .filter((facts) => facts !== null);
+    const summary = {
+        validFiles: valid.length,
+        invalidDescriptorFiles: stored.length - valid.length,
+        partialFiles: valid.filter((facts) => facts.parseState !== "complete").length,
+        expectedSites: valid.reduce((count, facts) => count + facts.sites.length, 0),
+        unsupportedUses: valid.reduce((count, facts) => count + facts.unsupportedUses.length, 0),
+        catalog: createApexConsumerCatalog(valid),
+    };
+    // Account for retained declaration strings/structure, not the much larger raw sites.
+    // Byte and entry caps bound retention; this is not a precise V8 heap measurement.
+    const retainedBytes = Buffer.byteLength(JSON.stringify([Array.from(summary.catalog.classes), Array.from(summary.catalog.members)])) + 256;
+    if (summary.invalidDescriptorFiles === 0 && retainedBytes <= APEX_CONSUMER_MEMO_MAX_BYTES) {
+        while (apexConsumerValidationMemo.size >= APEX_CONSUMER_MEMO_MAX_ENTRIES) {
+            const oldest = apexConsumerValidationMemo.keys().next().value;
+            if (!oldest)
+                break;
+            apexConsumerValidationMemo.delete(oldest);
+        }
+        apexConsumerValidationMemo.set(db, { key, summary, retainedBytes });
+    }
+    return summary;
+}
+/** @internal Snapshot reader; callers must establish repository freshness before entry. */
+export function readClassConsumerPage(db, repoPath, request) {
+    if (!request.symbol ||
+        !Number.isSafeInteger(request.limit) ||
+        request.limit < 1 ||
+        request.limit > 1000 ||
+        !["all", "test", "production"].includes(request.testScope))
+        throw new Error("Invalid class-consumer query bounds");
+    const filterPath = request.path?.replace(/\/$/, "");
+    if (filterPath &&
+        (path.posix.normalize(filterPath) !== filterPath ||
+            filterPath.startsWith("/") ||
+            filterPath.split("/").includes("..") ||
+            filterPath.includes("\\")))
+        throw new Error("Class-consumer path must be canonical and repository-relative");
+    const after = request.after;
+    if (after &&
+        (!Number.isSafeInteger(after.startByte) ||
+            !Number.isSafeInteger(after.endByte) ||
+            after.startByte < 0 ||
+            after.endByte <= after.startByte ||
+            !apexConsumerKinds.has(after.kind) ||
+            path.posix.normalize(after.file) !== after.file ||
+            after.file.startsWith("/") ||
+            after.file.split("/").includes("..")))
+        throw new Error("Invalid class-consumer page key");
+    const beforeStamp = apexConsumerSnapshotStamp(db, false);
+    if (!beforeStamp) {
+        const cached = apexConsumerValidationMemo.get(db);
+        if (cached)
+            delete cached.fastProof;
+    }
+    let publishProof;
+    let pinnedStamp = null;
+    let completed = false;
+    db.run("SAVEPOINT class_consumer_read");
+    try {
+        // SAVEPOINT alone is deferred: touch main to establish the read snapshot first.
+        db.query("SELECT name FROM main.sqlite_master LIMIT 1").get();
+        pinnedStamp = beforeStamp ? apexConsumerSnapshotStamp(db, true) : null;
+        const memo = apexConsumerValidationMemo.get(db);
+        const fastProof = pinnedStamp && pinnedStamp === beforeStamp && memo?.fastProof?.stamp === pinnedStamp
+            ? memo.fastProof
+            : undefined;
+        if (fastProof) {
+            apexConsumerFastHits.set(db, (apexConsumerFastHits.get(db) ?? 0) + 1);
+            const stats = apexConsumerValidationMemoStats.get(db);
+            if (stats)
+                stats.hits++;
+        }
+        const indexCoverage = indexCoverageSummary(coverageForDatabase(db));
+        const freshness = buildFreshnessEnvelope(repoPath, db, new Date().toISOString());
+        const tablesPresent = (db
+            .query("SELECT COUNT(*) count FROM sqlite_master WHERE type='table' AND name IN ('apex_consumer_files','apex_class_uses')")
+            .get()?.count ?? 0) === 2;
+        const stored = tablesPresent && !fastProof
+            ? db
+                .query("SELECT f.* FROM apex_consumer_files f JOIN index_state i ON i.filePath=f.filePath")
+                .all()
+            : [];
+        const missingDescriptorFiles = db
+            .query(tablesPresent
+            ? "SELECT COUNT(*) count FROM index_state i LEFT JOIN apex_consumer_files f ON f.filePath=i.filePath WHERE (lower(i.filePath) LIKE '%.cls' OR lower(i.filePath) LIKE '%.trigger') AND f.filePath IS NULL"
+            : "SELECT COUNT(*) count FROM index_state WHERE lower(filePath) LIKE '%.cls' OR lower(filePath) LIKE '%.trigger'")
+            .get()?.count ?? 0;
+        const allClassRows = db
+            .query("SELECT * FROM symbols WHERE kind IN ('class','interface') AND identity IS NOT NULL")
+            .all()
+            .filter((row) => /\.(?:cls|trigger)$/i.test(row.filePath));
+        const typeFacts = new Map();
+        if (tablesPresent)
+            for (const row of allClassRows)
+                if (row.kind === "interface")
+                    apexConsumerSymbolOwner(db, row, typeFacts);
+        const typeOwner = (row) => tablesPresent
+            ? apexConsumerSymbolOwner(db, row, typeFacts)
+            : row.kind === "class"
+                ? (parseApexDeclaration(row.apexDeclaration)?.owner ?? null)
+                : null;
+        const classRows = allClassRows.filter((row) => {
+            if (row.name.toLowerCase() !== request.symbol.split(".").at(-1)?.toLowerCase())
+                return false;
+            if (tablesPresent && !typeFacts.has(row.filePath)) {
+                const descriptor = db
+                    .query("SELECT f.* FROM apex_consumer_files f JOIN index_state i ON i.filePath=f.filePath WHERE f.filePath=?")
+                    .get(row.filePath);
+                typeFacts.set(row.filePath, descriptor ? readApexConsumerFacts(descriptor) : null);
+            }
+            return (typeOwner(row)?.toLowerCase() === request.symbol.toLowerCase() ||
+                row.name.toLowerCase() === request.symbol.toLowerCase());
+        });
+        const selector = request.selector ?? {};
+        const candidates = classRows.filter((row) => (!selector.file || row.filePath === selector.file) &&
+            (!selector.kind || row.kind === selector.kind) &&
+            (!selector.identity || symbolIdentityMatches(row.identity ?? "", selector.identity)));
+        if (candidates.length === 0 &&
+            tablesPresent &&
+            !selector.identity &&
+            (!selector.kind || selector.kind === "interface")) {
+            const descriptorRows = stored.length
+                ? stored
+                : db
+                    .query("SELECT f.* FROM apex_consumer_files f JOIN index_state i ON i.filePath=f.filePath")
+                    .all();
+            const retained = descriptorRows
+                .map(readApexConsumerFacts)
+                .filter((f) => f !== null);
+            const competitors = retained.flatMap((f) => f.declarations
+                .filter((d) => ["class", "interface", "enum"].includes(d.kind) &&
+                (d.name.toLowerCase() === request.symbol.toLowerCase() ||
+                    d.ownerPath.toLowerCase() === request.symbol.toLowerCase()))
+                .map((d) => ({ file: f.file, state: f.parseState, declaration: d })));
+            if (competitors.length === 1 &&
+                competitors[0].state === "complete" &&
+                competitors[0].declaration.kind === "interface" &&
+                (!selector.file || selector.file === competitors[0].file))
+                throw new ClassConsumerQueryError("CLASS_CONSUMER_TARGET_CAPABILITY_MISSING", "An indexed interface declaration exists but its typed symbol capability is missing; repair the indexed scope.");
+        }
+        if (candidates.length !== 1) {
+            if (candidates.length === 0)
+                throw new ClassConsumerQueryError("CLASS_CONSUMER_TARGET_NOT_FOUND", "No indexed Apex class matches the requested target and selectors.");
+            throw new ClassConsumerQueryError("CLASS_CONSUMER_TARGET_AMBIGUOUS", "Several indexed Apex classes match; select an exact identity or file.", candidates.slice(0, 100).map((row, index) => ({
+                identity: row.identity,
+                symbol: row.name,
+                file: row.filePath,
+                kind: row.kind,
+                line: row.startLine,
+                rank: index + 1,
+            })));
+        }
+        const selected = candidates[0];
+        const targetIdentity = selected.identity;
+        const targetOwner = typeOwner(selected);
+        if (!targetOwner && selected.kind === "interface")
+            throw new ClassConsumerQueryError("CLASS_CONSUMER_TARGET_CAPABILITY_MISSING", "The indexed interface lacks validated declaration-to-symbol provenance; repair the indexed scope.");
+        if (!targetOwner)
+            throw new ClassConsumerQueryError("CLASS_CONSUMER_TARGET_NOT_FOUND", "No validated Apex type declaration matches the target.");
+        const targetKind = selected.kind;
+        const digest = (value) => crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex");
+        const queryDigest = digest({
+            version: 1,
+            repository: path.resolve(repoPath),
+            targetIdentity,
+            targetKind,
+            bindingVersion: APEX_CONSUMER_BINDING_VERSION,
+            testScope: request.testScope,
+            path: filterPath ?? null,
+        });
+        const factsRevision = getMeta(db, "apexConsumerFactsRevision");
+        const boundRevision = getMeta(db, "apexConsumerBoundRevision");
+        const bindingVersion = getMeta(db, "apexConsumerBindingVersion");
+        const descriptorDigest = fastProof?.descriptorDigest ??
+            digest(stored
+                .map((row) => [
+                row.filePath,
+                row.version,
+                row.sourceHash,
+                row.factsHash,
+                digest(row.facts),
+                row.parseState,
+                row.isTest,
+            ])
+                .sort((a, b) => compareBytes(String(a[0]), String(b[0]))));
+        const materializedSites = tablesPresent
+            ? (db.query("SELECT COUNT(*) count FROM apex_class_uses").get()
+                ?.count ?? 0)
+            : 0;
+        const materializedDigest = fastProof
+            ? fastProof.materializedDigest
+            : tablesPresent
+                ? apexConsumerMaterializationDigest(db)
+                : null;
+        // Unknown/changed native snapshots retain the full actual-byte scan, never revision-only trust.
+        const inventory = fastProof
+            ? []
+            : db
+                .query("SELECT filePath FROM index_state WHERE lower(filePath) LIKE '%.cls' OR lower(filePath) LIKE '%.trigger' ORDER BY filePath COLLATE BINARY")
+                .all();
+        const schema = fastProof
+            ? []
+            : db
+                .query("SELECT 'main' origin,name,sql FROM sqlite_master UNION ALL SELECT 'temp' origin,name,sql FROM sqlite_temp_master ORDER BY origin COLLATE BINARY,name COLLATE BINARY")
+                .all();
+        const validationDigest = fastProof?.validationDigest ??
+            digest({
+                version: 1,
+                descriptorDigest,
+                inventory,
+                schema,
+                tablesPresent,
+                missingDescriptorFiles,
+                materializedSites,
+                materializedDigest,
+                factsRevision,
+                boundRevision,
+                bindingVersion,
+                expectedMaterialization: getMeta(db, "apexConsumerMaterializationDigest"),
+            });
+        const validation = fastProof && memo ? memo.summary : validatedApexConsumerSummary(db, stored, validationDigest);
+        const { expectedSites, invalidDescriptorFiles, partialFiles, unsupportedUses, catalog } = validation;
+        // Fresh symbol proof is intentionally outside both validation caches. A removed outer
+        // interface must not turn retained nested-class rows into a certified zero result.
+        const missingInterfaceBindings = new Set();
+        const interfaceSymbolSpans = new Set(allClassRows
+            .filter((row) => row.kind === "interface")
+            .map((row) => JSON.stringify([
+            row.filePath,
+            row.name,
+            row.startLine,
+            row.startCol,
+            row.endLine,
+            row.endCol,
+        ])));
+        for (const entries of catalog.classes.values())
+            for (const entry of entries) {
+                if (entry.declaration.kind !== "interface" || entry.parseState !== "complete")
+                    continue;
+                const range = entry.declaration.declarationRange;
+                if (!range ||
+                    !interfaceSymbolSpans.has(JSON.stringify([
+                        entry.file,
+                        entry.declaration.name,
+                        range.start.line,
+                        range.start.column - 1,
+                        range.end.line,
+                        range.end.column - 1,
+                    ])))
+                    missingInterfaceBindings.add(entry.file);
+            }
+        const snapshotDigest = digest({
+            version: 1,
+            queryDigest,
+            validationDigest,
+            classBindings: allClassRows
+                .map((row) => [
+                row.filePath,
+                row.name,
+                row.kind,
+                row.identity,
+                row.apexDeclaration,
+                row.startLine,
+                row.startCol,
+                row.endLine,
+                row.endCol,
+            ])
+                .sort((a, b) => compareBytes(JSON.stringify(a), JSON.stringify(b))),
+            factsRevision,
+            boundRevision,
+            bindingVersion,
+            descriptorDigest,
+            materializedSites,
+            materializedDigest,
+            indexCoverage,
+            head: freshness.currentHead,
+            indexedHead: freshness.indexedHead,
+            workingTree: freshness.workingTree,
+        });
+        if (request.expectedQueryDigest && request.expectedQueryDigest !== queryDigest)
+            throw new ClassConsumerQueryError("CLASS_CONSUMER_QUERY_MISMATCH", "The continuation does not describe this class-consumer query.");
+        if (request.expectedSnapshotDigest && request.expectedSnapshotDigest !== snapshotDigest)
+            throw new ClassConsumerQueryError("CLASS_CONSUMER_STALE_CURSOR", "The indexed graph or coverage changed; restart class-consumer paging.");
+        const unresolvedSites = tablesPresent
+            ? (db
+                .query("SELECT COUNT(*) count FROM apex_class_uses WHERE status<>'resolved'")
+                .get()?.count ?? 0)
+            : 0;
+        const bound = Boolean(tablesPresent &&
+            bindingVersion === APEX_CONSUMER_BINDING_VERSION &&
+            factsRevision &&
+            boundRevision === factsRevision &&
+            materializedDigest === getMeta(db, "apexConsumerMaterializationDigest") &&
+            materializedSites === expectedSites &&
+            invalidDescriptorFiles === 0 &&
+            missingDescriptorFiles === 0 &&
+            missingInterfaceBindings.size === 0);
+        const where = [
+            "u.status='resolved'",
+            "u.targetIdentity IS NOT NULL",
+            "u.targetFile=?",
+            "(lower(u.targetOwner)=lower(?) OR substr(lower(u.targetOwner),1,length(?)+1)=lower(?)||'.')",
+            "u.filePath<>?",
+            "u.isTest IS NOT NULL",
+        ];
+        const params = [
+            selected.filePath,
+            targetOwner,
+            targetOwner,
+            targetOwner,
+            selected.filePath,
+        ];
+        if (!bound)
+            where.push("0");
+        if (request.testScope !== "all") {
+            where.push("u.isTest=?");
+            params.push(request.testScope === "test" ? 1 : 0);
+        }
+        if (filterPath) {
+            where.push("(u.filePath=? OR substr(u.filePath,1,length(?)+1)=?||'/')");
+            params.push(filterPath, filterPath, filterPath);
+        }
+        const from = "FROM apex_class_uses u JOIN index_state i ON i.filePath=u.filePath JOIN apex_consumer_files f ON f.filePath=u.filePath";
+        const predicate = where.join(" AND ");
+        const totals = tablesPresent
+            ? db
+                .query(`SELECT COUNT(*) count,COUNT(DISTINCT u.filePath) files ${from} WHERE ${predicate}`)
+                .get(...params)
+            : undefined;
+        const targetInternalSites = tablesPresent
+            ? (db
+                .query("SELECT COUNT(*) count FROM apex_class_uses WHERE status='resolved' AND filePath=? AND targetFile=? AND (lower(targetOwner)=lower(?) OR substr(lower(targetOwner),1,length(?)+1)=lower(?)||'.')")
+                .get(selected.filePath, selected.filePath, targetOwner, targetOwner, targetOwner)
+                ?.count ?? 0)
+            : 0;
+        const pageParams = [...params];
+        let afterSql = "";
+        if (after) {
+            afterSql =
+                " AND (u.filePath COLLATE BINARY,u.startByte,u.endByte,u.kind COLLATE BINARY)>(? COLLATE BINARY,?,?,? COLLATE BINARY)";
+            pageParams.push(after.file, after.startByte, after.endByte, after.kind);
+        }
+        pageParams.push(request.limit + 1);
+        const rows = tablesPresent
+            ? db
+                .query(`SELECT u.* ${from} WHERE ${predicate}${afterSql} ORDER BY u.filePath COLLATE BINARY,u.startByte,u.endByte,u.kind COLLATE BINARY LIMIT ?`)
+                .all(...pageParams)
+            : [];
+        const storedByFile = new Map(stored.map((row) => [row.filePath, row]));
+        const pageFacts = new Map();
+        const proofByFile = new Map();
+        let invalidRows = false;
+        const results = [];
+        for (const row of rows.slice(0, request.limit)) {
+            let site;
+            try {
+                site = JSON.parse(row.raw);
+            }
+            catch {
+                invalidRows = true;
+                continue;
+            }
+            if (!validConsumerSite(site) ||
+                site.blockedReason ||
+                site.start.byte !== row.startByte ||
+                site.end.byte !== row.endByte ||
+                site.kind !== row.kind) {
+                invalidRows = true;
+                continue;
+            }
+            if (!pageFacts.has(row.filePath)) {
+                const descriptor = storedByFile.get(row.filePath) ??
+                    (fastProof
+                        ? db
+                            .query("SELECT f.* FROM apex_consumer_files f JOIN index_state i ON i.filePath=f.filePath WHERE f.filePath=?")
+                            .get(row.filePath)
+                        : null);
+                pageFacts.set(row.filePath, descriptor ? readApexConsumerFacts(descriptor) : null);
+            }
+            const facts = pageFacts.get(row.filePath);
+            if (!facts || facts.isTest !== (row.isTest === 1)) {
+                invalidRows = true;
+                continue;
+            }
+            let proofs = proofByFile.get(row.filePath);
+            if (!proofs) {
+                proofs = resolveApexClassUses(catalog, facts);
+                proofByFile.set(row.filePath, proofs);
+            }
+            const proof = proofs.find((entry) => entry.status === "resolved" && JSON.stringify(entry.site) === row.raw);
+            if (!proof?.target ||
+                proof.target.file !== selected.filePath ||
+                !(proof.target.declaration.ownerPath.toLowerCase() === targetOwner.toLowerCase() ||
+                    proof.target.declaration.ownerPath
+                        .toLowerCase()
+                        .startsWith(`${targetOwner.toLowerCase()}.`))) {
+                invalidRows = true;
+                continue;
+            }
+            const owners = allClassRows.filter((candidate) => candidate.filePath === row.filePath &&
+                typeOwner(candidate)?.toLowerCase() === site.lexicalOwner?.toLowerCase());
+            const ownerIdentity = owners.length === 1 ? (owners[0].identity ?? null) : null;
+            results.push({
+                key: { file: row.filePath, startByte: row.startByte, endByte: row.endByte, kind: row.kind },
+                file: row.filePath,
+                start: { line: site.start.line, column: site.start.column, byte: site.start.byte },
+                end: { line: site.end.line, column: site.end.column, byte: site.end.byte },
+                kind: site.kind,
+                qualifiedSpelling: site.qualifiedSpelling,
+                ownerIdentity,
+                isTest: row.isTest === 1,
+                grounding: "syntax-resolved",
+            });
+        }
+        if (invalidRows)
+            results.length = 0;
+        const files = [...new Set(results.map((site) => site.file))].map((file) => ({
+            file,
+            isTest: results.find((site) => site.file === file)?.isTest ?? false,
+            siteCount: db
+                .query(`SELECT COUNT(*) count ${from} WHERE ${predicate} AND u.filePath=?`)
+                .get(...params, file)?.count ?? 0,
+            returnedSiteCount: results.filter((site) => site.file === file).length,
+        }));
+        const endStamp = pinnedStamp ? apexConsumerSnapshotStamp(db, true) : null;
+        if (pinnedStamp && endStamp !== pinnedStamp) {
+            throw new ClassConsumerQueryError("CLASS_CONSUMER_STALE_CURSOR", "The graph changed while reading its snapshot; retry the query.");
+        }
+        if (bound && !invalidRows && pinnedStamp && beforeStamp === pinnedStamp)
+            publishProof = { stamp: pinnedStamp, descriptorDigest, materializedDigest, validationDigest };
+        completed = true;
+        return {
+            targetIdentity,
+            targetKind,
+            queryDigest,
+            snapshotDigest,
+            count: invalidRows ? 0 : (totals?.count ?? 0),
+            consumerFileCount: invalidRows ? 0 : (totals?.files ?? 0),
+            returnedCount: results.length,
+            results,
+            files,
+            hasMore: !invalidRows && rows.length > request.limit,
+            analysis: {
+                version: 1,
+                grounding: "syntax-resolved",
+                partial: !bound ||
+                    missingDescriptorFiles > 0 ||
+                    partialFiles > 0 ||
+                    invalidRows ||
+                    unresolvedSites > 0 ||
+                    unsupportedUses > 0,
+                inspectedFiles: validation.validFiles,
+                missingDescriptorFiles: missingDescriptorFiles + missingInterfaceBindings.size,
+                invalidDescriptorFiles: invalidDescriptorFiles + (invalidRows ? 1 : 0),
+                unresolvedSites,
+                unsupportedUses,
+                exclusions: { targetInternalSites },
+                limitations: [
+                    "Only the nine supported explicit Apex syntax roles are resolved; this is not runtime reachability or complete class-use coverage.",
+                    "Descriptor, unresolved-site and unsupported-use counters cover the inspected indexed Apex inventory, not just this target.",
+                    "Inherited or ambiguous value/type scopes can remain unresolved; target self-file sites are excluded.",
+                    "Query results cover this repository's indexed graph scope only, not federated repositories or metadata.",
+                ],
+            },
+            indexCoverage,
+            freshness,
+        };
+    }
+    finally {
+        releaseApexConsumerRead(db, beforeStamp !== null, completed, publishProof);
+    }
 }
 function resolveSymbolRows(db, repoPath, name, selector = {}) {
     let rows = db.query("SELECT * FROM symbols WHERE name = ?").all(name);
@@ -1278,7 +2130,8 @@ export function resetSearchCacheStats() {
     }
 }
 /**
- * Decode a repository's embedded symbol metadata once per index generation.
+ * Decode a repository's symbol metadata once per index generation, including
+ * structural-only symbols. Semantic coverage must not gate lexical retrieval.
  * Corrupt vectors remain represented so totals and FTS behavior stay truthful,
  * but exact vector scoring can skip them without reparsing every warm query.
  */
@@ -1294,12 +2147,14 @@ function getSearchMetadataSnapshot(repoPath, db) {
         const stmt = db.query(`
 			SELECT s.id, s.identity, s.name, s.kind, s.filePath, s.startLine, s.endLine, se.embedding
 			FROM symbols s
-			JOIN symbol_embeddings se ON s.id = se.symbolId
+			LEFT JOIN symbol_embeddings se ON s.id = se.symbolId
 		`);
         const raw = stmt.all();
         stmt.finalize();
         return raw.map((row) => {
             const { embedding, ...metadata } = row;
+            if (embedding === null)
+                return { ...metadata, vector: null };
             try {
                 return { ...metadata, vector: bufferToFloat32(embedding) };
             }
@@ -2526,14 +3381,17 @@ function extractSymbolsAndReferences(rootNode, isPython, isApex = false, filePat
             }
         }
         else if (isApex) {
-            if (node.type === "class_declaration") {
+            if (node.type === "class_declaration" || node.type === "interface_declaration") {
                 const nameNode = node.childForFieldName("name") || node.children.find((c) => c.type === "identifier");
                 if (nameNode) {
                     const name = nameNode.text;
                     symName = name;
                     definitions.push({
+                        ...(node.type === "class_declaration"
+                            ? { apexDeclaration: JSON.stringify(apexDeclaration(node)) }
+                            : {}),
                         name,
-                        kind: "class",
+                        kind: node.type === "class_declaration" ? "class" : "interface",
                         startLine: node.startPosition.row + 1,
                         endLine: node.endPosition.row + 1,
                         startCol: node.startPosition.column,
@@ -2598,6 +3456,7 @@ function extractSymbolsAndReferences(rootNode, isPython, isApex = false, filePat
                     symName = name;
                     isNewSymbol = true;
                     definitions.push({
+                        apexDeclaration: JSON.stringify(apexDeclaration(node)),
                         name,
                         kind: "method",
                         startLine: node.startPosition.row + 1,
@@ -2768,6 +3627,15 @@ function extractSymbolsAndReferences(rootNode, isPython, isApex = false, filePat
         }
         // --- Identify Dependencies (Imports) ---
         if (!isPython && !isApex) {
+            // A source-bearing re-export is a real module dependency even though it
+            // introduces no local binding. The AST source field covers named,
+            // aliased, namespace and star exports without mistaking strings or
+            // comments for wiring. Local `export { value }` has no source field.
+            if (node.type === "export_statement") {
+                const sourceNode = node.childForFieldName("source");
+                if (sourceNode?.type === "string")
+                    fileDependencies.push(sourceNode.text.replace(/^['"`]|['"`]$/g, ""));
+            }
             if (node.type === "import_statement" || node.type === "import_declaration") {
                 const sourceNode = node.childForFieldName("source");
                 if (sourceNode?.type === "string") {
@@ -2847,6 +3715,7 @@ function extractSymbolsAndReferences(rootNode, isPython, isApex = false, filePat
                 if (nameNode) {
                     const calleeName = nameNode.text;
                     references.push({
+                        apexCall: node.childForFieldName("object") ? JSON.stringify(apexCall(node)) : undefined,
                         callerSymbol: getEnclosingSymbol(),
                         calleeSymbol: calleeName,
                         line: node.startPosition.row + 1,
@@ -2860,6 +3729,7 @@ function extractSymbolsAndReferences(rootNode, isPython, isApex = false, filePat
                 if (typeNode) {
                     const calleeName = typeNode.text;
                     references.push({
+                        apexCall: JSON.stringify(apexCall(node)),
                         callerSymbol: getEnclosingSymbol(),
                         calleeSymbol: calleeName,
                         line: node.startPosition.row + 1,
@@ -3453,19 +4323,25 @@ const packageMapCache = new Map();
 function invalidateResolutionCaches(repoPath) {
     const resolved = path.resolve(repoPath);
     packageMapCache.delete(resolved);
+    salesforceBindingTargetCache.delete(resolved);
     const prefix = `${resolved}\0`;
     for (const key of reExportCache.keys())
         if (key.startsWith(prefix))
             reExportCache.delete(key);
 }
+const explicitPackageInputs = new AsyncLocalStorage();
 function getPackageMap(repoPath) {
     const resolvedRepoPath = path.resolve(repoPath);
     const cached = packageMapCache.get(resolvedRepoPath);
-    if (cached?.generation === indexGeneration)
+    const explicitInputs = explicitPackageInputs.getStore() ?? [];
+    if (!explicitInputs.length && cached?.generation === indexGeneration)
         return cached.value;
     const map = new Map();
     let cacheable = true;
-    for (const rel of listSourceFiles(repoPath, (file) => path.posix.basename(file) === "package.json")) {
+    for (const rel of new Set([
+        ...explicitInputs,
+        ...listSourceFiles(repoPath, (file) => path.posix.basename(file) === "package.json"),
+    ])) {
         try {
             const manifest = readWholeSource(repoPath, rel);
             if (manifest.availability.state !== "available")
@@ -3485,7 +4361,7 @@ function getPackageMap(repoPath) {
             cacheable = false;
         }
     }
-    if (cacheable)
+    if (cacheable && !explicitInputs.length)
         packageMapCache.set(resolvedRepoPath, {
             generation: indexGeneration,
             value: map,
@@ -3637,10 +4513,7 @@ function getLineAndColumnForIndex(content, index) {
     return { line, column };
 }
 function findClassFilePath(className, repoPath) {
-    return (walkRepoFiles(repoPath, {
-        accept: (file) => path.posix.basename(file) === `${className}.cls`,
-        limit: 1,
-    })[0] ?? null);
+    return (listSourceFiles(repoPath, (file) => path.posix.basename(file) === `${className}.cls`)[0] ?? null);
 }
 /**
  * C19 only reports an Apex bridge when its class path is unambiguous. The
@@ -3773,6 +4646,9 @@ function salesforceMetadataFile(relativePath) {
     const root = "force-app/main/default/";
     if (!normalized.startsWith(root))
         return null;
+    const webLink = /^force-app\/main\/default\/objects\/([A-Za-z]\w*)\/webLinks\/([A-Za-z]\w*)\.webLink-meta\.xml$/.exec(normalized);
+    if (webLink)
+        return { type: "weblink", object: webLink[1], name: webLink[2] };
     let match = /^force-app\/main\/default\/objects\/([A-Za-z]\w*)\/\1\.object-meta\.xml$/.exec(normalized);
     if (match)
         return { type: "object", object: match[1] };
@@ -3787,6 +4663,13 @@ function salesforceMetadataFile(relativePath) {
     match = /^force-app\/main\/default\/permissionSets\/([A-Za-z]\w*)\.permissionSet-meta\.xml$/.exec(normalized);
     if (match)
         return { type: "permissionSet", name: match[1] };
+    match =
+        /^force-app\/main\/default\/quickActions\/([A-Za-z]\w*(?:\.[A-Za-z]\w*)?)\.quickAction-meta\.xml$/.exec(normalized);
+    if (match)
+        return { type: "quickAction", name: match[1] };
+    match = /^force-app\/main\/default\/flexipages\/([A-Za-z]\w*)\.flexipage-meta\.xml$/.exec(normalized);
+    if (match)
+        return { type: "flexipage", name: match[1] };
     match = /^force-app\/main\/default\/flows\/([A-Za-z]\w*)\.flow-meta\.xml$/.exec(normalized);
     if (match)
         return { type: "flow", name: match[1] };
@@ -3810,11 +4693,12 @@ function findUniqueInvocableApexMethod(className, methodName, repoPath) {
     const source = read.text;
     const matches = [];
     for (const match of source.matchAll(/@InvocableMethod\b[\s\S]{0,300}?\b(?:global|public)\s+static\s(?:\s|[^({;]*?(?<!\s))\s+([a-z]\w*)\s*\(/gi)) {
-        if (!isExecutablePosition(source, match.index ?? 0) || match[1] !== methodName)
+        if (!isExecutablePosition(source, match.index ?? 0) ||
+            (methodName !== undefined && match[1] !== methodName))
             continue;
         matches.push({
             file,
-            method: methodName,
+            method: match[1],
             line: source.slice(0, match.index ?? 0).split("\n").length,
             evidence: match[0].trim(),
         });
@@ -4009,7 +4893,9 @@ export const SALESFORCE_METADATA_KINDS = [
     "salesforce_field",
     "salesforce_record_type",
     "salesforce_permission_set",
+    "salesforce_quick_action",
     "salesforce_flow",
+    "salesforce_weblink",
     "salesforce_workflow",
     "salesforce_approval",
 ];
@@ -4018,7 +4904,10 @@ const SALESFORCE_KIND_BY_TYPE = {
     field: "salesforce_field",
     recordType: "salesforce_record_type",
     permissionSet: "salesforce_permission_set",
+    quickAction: "salesforce_quick_action",
+    flexipage: "salesforce_flexipage",
     flow: "salesforce_flow",
+    weblink: "salesforce_weblink",
     workflow: "salesforce_workflow",
     approval: "salesforce_approval",
 };
@@ -4058,7 +4947,9 @@ function describeSalesforceMetadata(metadata, content) {
     const label = first("label") ?? first("masterLabel");
     const name = metadata.type === "flow"
         ? metadata.name
-        : metadata.type === "permissionSet"
+        : metadata.type === "permissionSet" ||
+            metadata.type === "quickAction" ||
+            metadata.type === "flexipage"
             ? metadata.name
             : metadata.type === "recordType"
                 ? `${metadata.object}.${metadata.recordType}`
@@ -4085,6 +4976,20 @@ async function indexSalesforceMetadataFile(content, relativePath, repoPath, db,
             add(qualified, kind, evidence);
     };
     switch (metadata.type) {
+        case "flexipage": {
+            for (const entry of await resolvedSalesforceComponentBindings(content, "flexipage", repoPath))
+                add(entry.to, entry.kind, entry.sourceEvidence);
+            break;
+        }
+        case "quickAction": {
+            const component = quickActionComponent(content);
+            if (component) {
+                const target = findUniqueSalesforceBindingTarget(component.name, repoPath, "aura");
+                if (target)
+                    add(target, "quickaction_lightning_component", component.evidence);
+            }
+            break;
+        }
         case "object":
             add(metadata.object, "salesforce_metadata_object", "Salesforce DX CustomObject file path");
             break;
@@ -4142,7 +5047,7 @@ async function indexSalesforceMetadataFile(content, relativePath, repoPath, db,
                 if (!/<actionType>apex<\/actionType>/.test(action[1]))
                     continue;
                 for (const entry of staticXmlTagValues(action[1], "actionName")) {
-                    const target = /^([A-Za-z]\w*)\.([A-Za-z]\w*)$/.exec(entry.value);
+                    const target = /^([A-Za-z]\w*)(?:\.([A-Za-z]\w*))?$/.exec(entry.value);
                     if (!target)
                         continue;
                     const invocable = findUniqueInvocableApexMethod(target[1], target[2], repoPath);
@@ -4159,16 +5064,14 @@ async function indexSalesforceMetadataFile(content, relativePath, repoPath, db,
                     });
                 }
             }
-            for (const entry of staticXmlTagValues(content, "extensionName")) {
-                const component = /^c:([A-Za-z]\w*)$/.exec(entry.value);
-                if (!component)
-                    continue;
-                const target = findSalesforceLwcComponentFile(component[1], repoPath);
-                if (target)
-                    add(target, "flow_screen_component", entry.evidence);
-            }
+            for (const binding of await resolvedSalesforceComponentBindings(content, "flow", repoPath))
+                add(binding.to, binding.kind, binding.sourceEvidence);
             break;
         }
+        case "weblink":
+            for (const binding of await resolvedSalesforceComponentBindings(content, "weblink", repoPath))
+                add(binding.to, binding.kind, binding.sourceEvidence);
+            break;
         case "workflow":
             add(metadata.object, "workflow_object", "Salesforce DX workflow object file path");
             for (const entry of staticXmlTagValues(content, "field"))
@@ -4224,21 +5127,255 @@ async function indexSalesforceMetadataFile(content, relativePath, repoPath, db,
         throw error;
     }
 }
+/** Mask non-markup content without interpreting entities or loading external resources. */
+function salesforceBindingMarkup(content) {
+    return content.replace(/<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>/g, (value) => value.replace(/[^\n]/g, " "));
+}
+function quickActionComponent(content) {
+    const markup = salesforceBindingMarkup(content);
+    if (!/^\s*(?:<\?xml[^?]*\?>\s*)?<QuickAction(?:\s[^<>]*)?>/.test(markup))
+        return null;
+    const types = staticXmlTagValues(markup, "type");
+    const components = staticXmlTagValues(markup, "lightningComponent");
+    if (types.length !== 1 || types[0].value !== "LightningComponent" || components.length !== 1)
+        return null;
+    const name = /^(?:c:)?([A-Za-z]\w*)$/.exec(components[0].value)?.[1];
+    return name && !name.includes("__") ? { name, evidence: components[0].evidence } : null;
+}
+const salesforceBindingTargetCache = new Map();
+/** One source-path catalog per graph generation, never a walk for each binding. */
+function salesforceBindingTargets(repoPath) {
+    const key = path.resolve(repoPath);
+    const coverageDigest = indexCoverageSummary(coverageForDatabase(extractionCoverage.getStore() ?? dbInstances.get(key))).digest;
+    let cached = salesforceBindingTargetCache.get(key);
+    if (!cached ||
+        cached.generation !== indexGeneration ||
+        cached.coverageDigest !== coverageDigest) {
+        const targets = new Map();
+        const files = listSourceFiles(repoPath, (file) => file.endsWith(".cls") ||
+            file.endsWith(".cmp") ||
+            file.endsWith(".js") ||
+            file.endsWith(".app") ||
+            file.endsWith(".page"));
+        for (const file of files) {
+            const name = file.endsWith(".cls")
+                ? path.posix.basename(file, ".cls")
+                : /(?:^|\/)aura\/([A-Za-z]\w*)\/\1\.cmp$/.exec(file)?.[1];
+            if (!name)
+                continue;
+            const targetKey = `${file.endsWith(".cls") ? "apex" : "aura"}:${name}`;
+            const files = targets.get(targetKey) ?? [];
+            if (files.length < 2)
+                files.push(file);
+            targets.set(targetKey, files);
+        }
+        cached = {
+            generation: indexGeneration,
+            coverageDigest,
+            targets,
+            components: componentCatalog(files),
+        };
+        if (salesforceBindingTargetCache.size >= 8)
+            salesforceBindingTargetCache.clear();
+        salesforceBindingTargetCache.set(key, cached);
+    }
+    return cached;
+}
+function findUniqueSalesforceBindingTarget(name, repoPath, kind) {
+    const matches = salesforceBindingTargets(repoPath).targets.get(`${kind}:${name}`) ?? [];
+    return matches.length === 1 ? matches[0] : null;
+}
+/** Reuse the shipped XML grammar; HTML deliberately retains its own literal subset. */
+async function salesforceComponentBindings(content, format) {
+    if (format === "lwc")
+        return componentBindings(content, format);
+    const language = await getLanguageForFile("component.xml");
+    if (!language)
+        return [];
+    const parser = new Parser();
+    try {
+        parser.setLanguage(language);
+        return componentBindings(content, format, (source) => {
+            const tree = parser.parse(source);
+            try {
+                return !tree.rootNode.hasError();
+            }
+            finally {
+                tree.delete();
+            }
+        });
+    }
+    finally {
+        parser.delete();
+    }
+}
+async function resolvedSalesforceComponentBindings(content, format, repoPath) {
+    const bindings = await salesforceComponentBindings(content, format);
+    if (!bindings.length)
+        return [];
+    const catalog = salesforceBindingTargets(repoPath).components;
+    const seen = new Set();
+    return bindings.flatMap((binding) => {
+        const target = catalog.resolve(binding);
+        if (!target)
+            return [];
+        const key = `${target.file}\0${binding.kind}\0${binding.evidence}`;
+        if (seen.has(key))
+            return [];
+        seen.add(key);
+        return [
+            {
+                to: target.file,
+                kind: binding.kind === "aura_component" && target.kind === "lwc"
+                    ? "aura_lwc_component"
+                    : binding.kind,
+                sourceEvidence: binding.evidence,
+            },
+        ];
+    });
+}
+/** Literal design-time Apex data sources, not method execution or runtime dispatch. */
+function appBuilderApexDataSources(content, aura) {
+    const markup = salesforceBindingMarkup(content);
+    const root = aura ? "design:component" : "LightningComponentBundle";
+    if (!new RegExp(String.raw `^\s*(?:<\?xml[^?]*\?>\s*)?<${root}(?:\s[^<>]*)?>`).test(markup))
+        return [];
+    const regions = aura
+        ? [markup]
+        : [...markup.matchAll(/<targetConfig\b[^<>]*>([\s\S]*?)<\/targetConfig>/g)].map((match) => match[1]);
+    const results = [];
+    const tag = aura ? "design:attribute" : "property";
+    for (const region of regions) {
+        for (const match of region.matchAll(new RegExp(String.raw `<${tag}\b(?:[^"'<>]|"[^"]*"|'[^']*')*\/?>`, "g"))) {
+            const attributes = [
+                ...match[0].matchAll(/([A-Za-z_:][\w:.-]*)\s*=\s*(?:"([^"]*)"|'([^']*)')/g),
+            ];
+            const sources = attributes.filter((attribute) => attribute[1] === "datasource");
+            if (sources.length !== 1)
+                continue;
+            const name = /^apex:\/\/([A-Za-z]\w*)$/.exec(sources[0][2] ?? sources[0][3])?.[1];
+            if (name && !name.includes("__"))
+                results.push({ name, evidence: sources[0][0] });
+        }
+    }
+    return results;
+}
+/** Re-evaluate indexed bindings, including previously missing/ambiguous targets. */
+async function refreshSalesforceMetadataBindings(db, repoPath, changedFiles) {
+    const classes = new Set(changedFiles.filter((file) => file.endsWith(".cls")).map((file) => path.basename(file, ".cls")));
+    const components = new Set(changedFiles.filter((file) => file.endsWith(".cmp")).map((file) => path.basename(file, ".cmp")));
+    const componentNames = new Set(changedFiles.flatMap((file) => {
+        const name = /^force-app\/main\/default\/(?:aura|lwc)\/([A-Za-z]\w*)\/\1\.(?:cmp|js)$/.exec(file)?.[1];
+        return name ? [name] : [];
+    }));
+    const componentTags = new Set([...componentNames].map((name) => name.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`)));
+    const applicationNames = new Set(changedFiles.flatMap((file) => /^force-app\/main\/default\/aura\/([A-Za-z]\w*)\/\1\.app$/.exec(file)?.slice(1) ?? []));
+    const pageNames = new Set(changedFiles.flatMap((file) => /^force-app\/main\/default\/pages\/([A-Za-z]\w*)\.page$/.exec(file)?.slice(1) ?? []));
+    if (!classes.size &&
+        !components.size &&
+        !componentNames.size &&
+        !applicationNames.size &&
+        !pageNames.size)
+        return [];
+    // Target additions/deletions can precede the generation increment. Refresh
+    // the catalog before reconsidering formerly missing or ambiguous bindings.
+    salesforceBindingTargetCache.delete(path.resolve(repoPath));
+    const candidates = db
+        .query("SELECT filePath FROM index_state WHERE filePath LIKE 'force-app/main/default/quickActions/%.quickAction-meta.xml' OR filePath LIKE 'force-app/main/default/lwc/%.js-meta.xml' OR filePath LIKE 'force-app/main/default/aura/%.design' OR filePath LIKE 'force-app/main/default/aura/%.cmp' OR filePath LIKE 'force-app/main/default/aura/%.app' OR filePath LIKE 'force-app/main/default/lwc/%.html' OR filePath LIKE 'force-app/main/default/flexipages/%.flexipage-meta.xml' OR filePath LIKE 'force-app/main/default/flows/%.flow-meta.xml' OR filePath LIKE 'force-app/main/default/pages/%.page' OR filePath LIKE 'force-app/main/default/objects/%/webLinks/%.webLink-meta.xml' ORDER BY filePath")
+        .all();
+    const refreshed = [];
+    for (const { filePath } of candidates) {
+        if (/^force-app\/main\/default\/pages\/[A-Za-z]\w*\.page$/.test(filePath)) {
+            if (!applicationNames.size)
+                continue;
+            const read = readWholeSource(repoPath, filePath);
+            if (read.availability.state !== "available" ||
+                !(await visualforceLightningBindings(read.text)).some((binding) => applicationNames.has(binding.name)))
+                continue;
+            await indexFile(path.join(repoPath, filePath), filePath, repoPath, db);
+            recordIndexState(db, repoPath, filePath);
+            refreshed.push(filePath);
+            continue;
+        }
+        const metadata = salesforceMetadataFile(filePath);
+        const auraSource = auraBundleFile(filePath);
+        const lwcSource = lwcBundleFile(filePath);
+        const format = metadata?.type === "flexipage" || metadata?.type === "flow" || metadata?.type === "weblink"
+            ? metadata.type
+            : auraSource && (auraSource.extension === "cmp" || auraSource.extension === "app")
+                ? "aura"
+                : lwcSource?.extension === "html"
+                    ? "lwc"
+                    : undefined;
+        // Filter by changed target category before opening source. An Apex-only
+        // edit must not read every component template in a large repository.
+        if (format
+            ? !(format === "weblink" ? pageNames : componentNames).size
+            : metadata?.type === "quickAction"
+                ? !components.size
+                : !classes.size)
+            continue;
+        const read = readWholeSource(repoPath, filePath);
+        if (read.availability.state !== "available")
+            continue;
+        if (format) {
+            const bindings = await salesforceComponentBindings(read.text, format);
+            if (!bindings.some((binding) => (binding.target === "page"
+                ? pageNames
+                : binding.target === "lwc-tag"
+                    ? componentTags
+                    : componentNames).has(binding.name)))
+                continue;
+            if (metadata?.type === "flexipage" ||
+                metadata?.type === "flow" ||
+                metadata?.type === "weblink")
+                await indexSalesforceMetadataFile(read.text, filePath, repoPath, db, metadata);
+            else if (auraSource)
+                await indexAuraBundleFile(read.text, filePath, repoPath, db, auraSource);
+            else if (lwcSource)
+                await indexLwcBundleFile(read.text, filePath, repoPath, db, lwcSource);
+        }
+        else if (metadata?.type === "quickAction") {
+            const target = quickActionComponent(read.text);
+            if (!target || !components.has(target.name))
+                continue;
+            await indexSalesforceMetadataFile(read.text, filePath, repoPath, db, metadata);
+        }
+        else {
+            const aura = auraBundleFile(filePath);
+            const lwc = lwcBundleFile(filePath);
+            if (!aura && !lwc)
+                continue;
+            if (!appBuilderApexDataSources(read.text, !!aura).some((entry) => classes.has(entry.name)))
+                continue;
+            if (aura)
+                await indexAuraBundleFile(read.text, filePath, repoPath, db, aura);
+            else if (lwc)
+                await indexLwcBundleFile(read.text, filePath, repoPath, db, lwc);
+        }
+        recordIndexState(db, repoPath, filePath);
+        refreshed.push(filePath);
+    }
+    return refreshed;
+}
 /**
  * Revisit only indexed Flow files that literally name an incrementally changed
  * Apex class. This keeps persisted method edges coherent when an annotation,
  * overload, or declaration changes without requiring a repository-wide scan.
  */
-async function refreshFlowsForApexFiles(db, repoPath, apexFiles) {
+async function refreshFlowsForApexFiles(...args) {
+    return extractionCoverage.run(args[0], () => refreshFlowsWithinCoverage(...args));
+}
+async function refreshFlowsWithinCoverage(db, repoPath, apexFiles) {
+    const refreshed = await refreshSalesforceMetadataBindings(db, repoPath, apexFiles);
     const classNames = new Set(apexFiles
         .filter((file) => /^force-app\/main\/default\/classes\/[A-Za-z]\w*\.cls$/.test(file))
         .map((file) => path.basename(file, ".cls")));
     if (classNames.size === 0)
-        return [];
+        return refreshed;
     const flowFiles = db
         .query("SELECT DISTINCT filePath FROM symbols WHERE kind = 'salesforce_flow' AND filePath LIKE 'force-app/main/default/flows/%.flow-meta.xml' ORDER BY filePath")
         .all();
-    const refreshed = [];
     for (const { filePath } of flowFiles) {
         const absolute = path.join(repoPath, filePath);
         let content;
@@ -4251,7 +5388,7 @@ async function refreshFlowsForApexFiles(db, repoPath, apexFiles) {
         const mentionsChangedClass = [...content.matchAll(/<actionCalls>([\s\S]*?)<\/actionCalls>/g)]
             .filter((match) => /<actionType>apex<\/actionType>/.test(match[1]))
             .some((match) => staticXmlTagValues(match[1], "actionName").some((entry) => {
-            const target = /^([A-Za-z]\w*)\.([A-Za-z]\w*)$/.exec(entry.value);
+            const target = /^([A-Za-z]\w*)(?:\.([A-Za-z]\w*))?$/.exec(entry.value);
             return target ? classNames.has(target[1]) : false;
         }));
         if (!mentionsChangedClass)
@@ -4271,6 +5408,17 @@ async function indexLwcBundleFile(content, relativePath, repoPath, db, bundle) {
         { to: bundle.bundlePath, kind: "lwc_bundle_member" },
     ];
     const references = [];
+    if (bundle.extension === "js-meta.xml") {
+        for (const entry of appBuilderApexDataSources(content, false)) {
+            const target = findUniqueSalesforceBindingTarget(entry.name, repoPath, "apex");
+            if (target)
+                dependencies.push({
+                    to: target,
+                    kind: "appbuilder_apex_datasource",
+                    sourceEvidence: entry.evidence,
+                });
+        }
+    }
     if (bundle.extension === "js") {
         const importedNames = new Map();
         for (const match of content.matchAll(/import\s+([\s\S]*?)\s+from\s+["']([^"']+)["']/g)) {
@@ -4338,6 +5486,7 @@ async function indexLwcBundleFile(content, relativePath, repoPath, db, bundle) {
         }
     }
     if (bundle.extension === "html") {
+        dependencies.push(...(await resolvedSalesforceComponentBindings(content, "lwc", repoPath)));
         const markup = content.replace(/<!--[\s\S]*?-->/g, (comment) => comment.replace(/[^\n]/g, " "));
         for (const match of markup.matchAll(/<(lightning-record-(?:form|view-form|edit-form|picker))\b/gi)) {
             dependencies.push({
@@ -4372,13 +5521,13 @@ async function indexLwcBundleFile(content, relativePath, repoPath, db, bundle) {
         }
         insertRef.finalize();
         const seen = new Set();
-        const insertDep = db.prepare("INSERT INTO dependencies (fromFile, toFile, kind, confidence) VALUES (?, ?, ?, ?)");
+        const insertDep = db.prepare("INSERT INTO dependencies (fromFile, toFile, kind, confidence, sourceEvidence) VALUES (?, ?, ?, ?, ?)");
         for (const dependency of dependencies) {
             const key = `${dependency.to}\0${dependency.kind}`;
             if (seen.has(key))
                 continue;
             seen.add(key);
-            insertDep.run(relativePath, dependency.to, dependency.kind, 1);
+            insertDep.run(relativePath, dependency.to, dependency.kind, 1, dependency.sourceEvidence ?? null);
         }
         insertDep.finalize();
         db.run("COMMIT;");
@@ -5476,6 +6625,17 @@ async function indexAuraBundleFile(content, relativePath, repoPath, db, bundle)
             sourceEvidence: "Aura bundle file path",
         },
     ];
+    if (bundle.extension === "design") {
+        for (const entry of appBuilderApexDataSources(content, true)) {
+            const target = findUniqueSalesforceBindingTarget(entry.name, repoPath, "apex");
+            if (target)
+                dependencies.push({
+                    to: target,
+                    kind: "appbuilder_apex_datasource",
+                    sourceEvidence: entry.evidence,
+                });
+        }
+    }
     // Only component controller attributes name an Apex controller. `$A` lookups,
     // computed strings, and client-side action names deliberately produce no edge.
     if (bundle.extension === "cmp") {
@@ -5491,17 +6651,9 @@ async function indexAuraBundleFile(content, relativePath, repoPath, db, bundle)
                     sourceEvidence: `controller="${controller}"`,
                 });
         }
-        // An Aura markup tag in the local `c` namespace is a declared, static LWC
-        // target only when the matching Salesforce DX LWC entry point exists.
-        for (const match of markup.matchAll(/<c:([A-Za-z]\w*)\b/g)) {
-            const target = findSalesforceLwcComponentFile(match[1], repoPath);
-            if (target)
-                dependencies.push({
-                    to: target,
-                    kind: "aura_lwc_component",
-                    sourceEvidence: match[0],
-                });
-        }
+    }
+    if (bundle.extension === "cmp" || bundle.extension === "app") {
+        dependencies.push(...(await resolvedSalesforceComponentBindings(content, "aura", repoPath)));
     }
     db.run("BEGIN TRANSACTION;");
     try {
@@ -5616,10 +6768,87 @@ async function indexSalesforceExperienceFile(content, relativePath, repoPath, db
         throw error;
     }
 }
+/** Static Lightning Out declarations, never evidence that the call executed. */
+async function visualforceLightningBindings(content) {
+    const scripts = visualforceInlineScripts(content);
+    if (!scripts?.length)
+        return [];
+    const language = await getLanguageForFile("lightning-out.js");
+    if (!language)
+        return [];
+    const parser = new Parser();
+    parser.setLanguage(language);
+    const bindings = [];
+    try {
+        for (const source of scripts) {
+            const tree = parser.parse(source);
+            try {
+                if (tree.rootNode.hasError())
+                    return [];
+                const queue = [tree.rootNode];
+                for (let i = 0; i < queue.length; i++) {
+                    const node = queue[i];
+                    // References as well as direct calls can hide indirect eval or a
+                    // Function constructor; computed browser-global access can hide
+                    // a fragmented "$" + "Lightning" assignment. Fail closed.
+                    if ((["identifier", "property_identifier"].includes(node.type) &&
+                        ["eval", "Function"].includes(node.text)) ||
+                        (node.type === "subscript_expression" &&
+                            ["window", "globalThis", "self", "this"].includes(node.childForFieldName("object")?.text ?? "")))
+                        return [];
+                    if ((node.type === "identifier" || node.type === "shorthand_property_identifier_pattern") &&
+                        node.text === "$Lightning") {
+                        const parent = node.parent;
+                        if (parent?.type !== "member_expression" ||
+                            parent.childForFieldName("object")?.id !== node.id)
+                            return [];
+                    }
+                    if ((node.type === "property_identifier" && node.text === "$Lightning") ||
+                        (node.type === "subscript_expression" && /\$Lightning/.test(node.text)))
+                        return [];
+                    if ([
+                        "assignment_expression",
+                        "augmented_assignment_expression",
+                        "update_expression",
+                        "unary_expression",
+                    ].includes(node.type) &&
+                        /\$Lightning/.test((node.childForFieldName("left") ?? node.childForFieldName("argument") ?? node).text))
+                        return [];
+                    if (node.type === "with_statement" ||
+                        (node.type === "call_expression" &&
+                            ["eval", "Function"].includes(node.childForFieldName("function")?.text ?? "")))
+                        return [];
+                    if (node.type === "call_expression") {
+                        const call = node.childForFieldName("function");
+                        const argument = node.childForFieldName("arguments")?.namedChild(0);
+                        if (call?.type === "member_expression" &&
+                            call.text === "$Lightning.use" &&
+                            argument?.type === "string") {
+                            const name = /^["']c:([A-Za-z]\w*)["']$/.exec(argument.text)?.[1];
+                            if (name && !name.includes("__"))
+                                bindings.push({ name, evidence: `${call.text}(${argument.text}` });
+                        }
+                    }
+                    queue.push(...node.namedChildren);
+                }
+            }
+            finally {
+                tree.delete();
+            }
+        }
+        return [...new Map(bindings.map((binding) => [binding.name, binding])).values()];
+    }
+    finally {
+        parser.delete();
+    }
+}
 async function indexVisualforceFile(content, tree, relativePath, repoPath, db) {
     const controllerNames = new Set();
     const extensionNames = [];
     const references = [];
+    const lightning = /^force-app\/main\/default\/pages\/[A-Za-z]\w*\.page$/.test(relativePath)
+        ? await visualforceLightningBindings(content)
+        : [];
     function traverseXML(node) {
         if (node.type === "element" || node.type === "start_tag") {
             const tagNameNode = node.childForFieldName("name") || node.children.find((c) => c.type === "tag_name");
@@ -5747,6 +6976,14 @@ async function indexVisualforceFile(content, tree, relativePath, repoPath, db) {
             const target = resolvedPath || className;
             insertDep.run(relativePath, target, "controller", 1, `${attribute}="${className}"`);
         }
+        for (const binding of lightning) {
+            const target = salesforceBindingTargets(repoPath).components.resolve({
+                target: "application",
+                name: binding.name,
+            });
+            if (target)
+                insertDep.run(relativePath, target.file, "visualforce_lightning_out", 1, binding.evidence);
+        }
         insertDep.finalize();
         db.run("COMMIT;");
     }
@@ -6260,9 +7497,10 @@ function buildFileIndexResult(tree, content, isPython, isApex, absolutePath, rel
         return null;
     };
     const resolvedReferences = references.map((ref) => ({
+        apexCall: ref.apexCall,
         callerSymbol: ref.callerSymbol,
         calleeSymbol: ref.calleeSymbol,
-        calleeFile: resolveCalleeFile(ref.calleeSymbol, ref.calleeModule),
+        calleeFile: ref.apexCall ? null : resolveCalleeFile(ref.calleeSymbol, ref.calleeModule),
         line: ref.line,
         column: ref.column,
         kind: ref.kind ?? "call",
@@ -6293,6 +7531,10 @@ function buildFileIndexResult(tree, content, isPython, isApex, absolutePath, rel
     return {
         relativePath,
         mcpRegistrations,
+        ...(isApex
+            ? { apexClassUses: extractApexClassUses(tree.rootNode, content, relativePath) }
+            : {}),
+        ...(isApex ? { apexReceiverVersion: 1 } : {}),
         definitions,
         references: resolvedReferences,
         apiContracts,
@@ -6323,6 +7565,26 @@ function writeFileIndexResult(db, result) {
 /** The actual delete+insert statements, run inside a transaction/savepoint the caller owns. */
 function writeFileIndexResultUnwrapped(db, result) {
     const { relativePath, mcpRegistrations, definitions, references, apiContracts, dependencies } = result;
+    db.run("DELETE FROM apex_consumer_files WHERE filePath = ?", [relativePath]);
+    db.run("DELETE FROM apex_class_uses WHERE filePath = ?", [relativePath]);
+    if (result.apexClassUses) {
+        const facts = result.apexClassUses;
+        const serialized = JSON.stringify(facts);
+        db.run("INSERT INTO apex_consumer_files(filePath,version,sourceHash,parseState,isTest,facts,factsHash) VALUES (?,1,?,?,?,?,?)", [
+            relativePath,
+            facts.sourceHash,
+            facts.parseState,
+            facts.isTest === null ? null : facts.isTest ? 1 : 0,
+            serialized,
+            crypto.createHash("sha256").update(serialized).digest("hex"),
+        ]);
+        setMeta(db, "apexConsumerFactsRevision", crypto.randomUUID());
+    }
+    db.run("DELETE FROM apex_file_capabilities WHERE filePath = ?", [relativePath]);
+    if (result.apexReceiverVersion === 1)
+        db.run("INSERT OR REPLACE INTO apex_file_capabilities(filePath,version) VALUES (?,1)", [
+            relativePath,
+        ]);
     db.run('DELETE FROM "references" WHERE callerFile = ?', [relativePath]);
     deleteSymbolsForFile(db, relativePath);
     db.run("DELETE FROM dependencies WHERE fromFile = ?", [relativePath]);
@@ -6337,19 +7599,19 @@ function writeFileIndexResultUnwrapped(db, result) {
     }
     insertMcp.finalize();
     const insertSym = db.prepare(`
-		INSERT INTO symbols (name, kind, filePath, startLine, endLine, startCol, endCol, summary)
-		VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+		INSERT INTO symbols (name, kind, filePath, startLine, endLine, startCol, endCol, summary, apexDeclaration)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
 	`);
     for (const def of definitions) {
-        insertSym.run(def.name, def.kind, relativePath, def.startLine, def.endLine, def.startCol, def.endCol, def.summary);
+        insertSym.run(def.name, def.kind, relativePath, def.startLine, def.endLine, def.startCol, def.endCol, def.summary, def.apexDeclaration ?? null);
     }
     insertSym.finalize();
     const insertRef = db.prepare(`
-		INSERT INTO "references" (callerSymbol, callerFile, calleeSymbol, calleeFile, line, column, kind)
-		VALUES (?, ?, ?, ?, ?, ?, ?)
+		INSERT INTO "references" (callerSymbol, callerFile, calleeSymbol, calleeFile, line, column, kind, apexCall)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?)
 	`);
     for (const ref of references) {
-        insertRef.run(ref.callerSymbol, relativePath, ref.calleeSymbol, ref.calleeFile, ref.line, ref.column, ref.kind);
+        insertRef.run(ref.callerSymbol, relativePath, ref.calleeSymbol, ref.calleeFile, ref.line, ref.column, ref.kind, ref.apexCall ?? null);
     }
     insertRef.finalize();
     const insertApiContract = db.prepare(`
@@ -6470,6 +7732,34 @@ function freeQuietly(target) {
         // Intentionally ignored; see above.
     }
 }
+function incompleteApexExtraction(content, relativePath, reason) {
+    const facts = {
+        version: 1,
+        file: relativePath,
+        sourceHash: crypto.createHash("sha256").update(content).digest("hex"),
+        parseState: "partial",
+        isTest: null,
+        sites: [],
+        declarations: [],
+        unsupportedUses: [],
+        coverage: "supported-syntax-only",
+        omissionReason: reason,
+    };
+    return {
+        kind: "result",
+        result: {
+            relativePath,
+            apexClassUses: facts,
+            apexClassUseIncompleteReason: reason,
+            mcpRegistrations: [],
+            definitions: [],
+            references: [],
+            apiContracts: [],
+            dependencies: [],
+            apexPlatformDependencies: [],
+        },
+    };
+}
 /**
  * Read, parse, and extract one file through the generic tree-sitter path.
  *
@@ -6479,15 +7769,23 @@ function freeQuietly(target) {
  * through here so routing can never drift between them.
  */
 export async function extractGenericFileForIndex(absolutePath, relativePath, repoPath) {
+    const isApex = absolutePath.endsWith(".cls") || absolutePath.endsWith(".trigger");
     const lang = await measurePerfPhase("parser_wasm_init", () => getLanguageForFile(absolutePath));
     if (!lang)
-        return { kind: "unparsed" };
+        return isApex
+            ? incompleteApexExtraction(fs.readFileSync(absolutePath, "utf8"), relativePath, "parser-unavailable")
+            : { kind: "unparsed" };
     const content = measurePerfPhaseSync("read", () => fs.readFileSync(absolutePath, "utf-8"));
     // Skip minified / generated bundles (e.g. a `*.bundle.js`): they're not
     // readable source and would inject thousands of junk "symbols" that pollute
     // the graph, communities, and hubs. Heuristic: a very high average line
     // length (minified code packs everything onto a few enormous lines).
-    if (isMinifiedSource(content))
+    // Apex response fixtures legitimately contain huge single-line string literals. Line
+    // density is not a sound minification signal for that language; preserve the existing
+    // absolute source-length bound and record its omission rather than inventing empty coverage.
+    if (isApex && content.length > 1_000_000)
+        return incompleteApexExtraction(content, relativePath, "source-size-limit");
+    if (!isApex && isMinifiedSource(content))
         return { kind: "unparsed" };
     const isSql = absolutePath.endsWith(".sql") || absolutePath.endsWith(".pkb") || absolutePath.endsWith(".pks");
     // SQL: neutralize dollar-quoted bodies that crash the grammar's scanner.
@@ -6514,10 +7812,14 @@ export async function extractGenericFileForIndex(absolutePath, relativePath, rep
         // to an abort through the recovery path itself.
         freeQuietly(parser);
         console.warn(`knodin: skipped ${relativePath} (parser error: ${e.message})`);
+        if (isApex)
+            return incompleteApexExtraction(content, relativePath, "parser-failure");
         return { kind: "skipped", reason: e.message };
     }
     if (!tree) {
         freeQuietly(parser);
+        if (isApex)
+            return incompleteApexExtraction(content, relativePath, "parser-failure");
         return { kind: "skipped", reason: "parser returned no tree" };
     }
     // Everything from here on can throw — `extractMcpToolRegistrations` and the
@@ -6531,7 +7833,6 @@ export async function extractGenericFileForIndex(absolutePath, relativePath, rep
             ? extractMcpToolRegistrations(content, relativePath, tree.rootNode)
             : [];
         const isPython = absolutePath.endsWith(".py");
-        const isApex = absolutePath.endsWith(".cls") || absolutePath.endsWith(".trigger");
         const isVisualforce = absolutePath.endsWith(".page") || absolutePath.endsWith(".component");
         const isPrisma = absolutePath.endsWith(".prisma");
         const isWorkday = absolutePath.endsWith(".clp") ||
@@ -6670,7 +7971,14 @@ const SPECIAL_ROUTE_EXTENSIONS = [
     ".pks",
     ".prisma",
 ];
-async function indexFile(absolutePath, relativePath, repoPath, db, unparsed, collectResult) {
+const extractionCoverage = new AsyncLocalStorage();
+async function indexFile(...args) {
+    const [, , , db] = args;
+    if (!coverageContains(requireIndexCoverage(coverageForDatabase(db)), args[1]))
+        throw new Error(`knodin: refusing to index outside declared coverage: ${args[1]}`);
+    return extractionCoverage.run(db, () => indexFileInCoverage(...args));
+}
+async function indexFileInCoverage(absolutePath, relativePath, repoPath, db, unparsed, collectResult) {
     try {
         invalidateScipFacts(db);
         const read = () => measurePerfPhaseSync("read", () => fs.readFileSync(absolutePath, "utf-8"));
@@ -6765,6 +8073,8 @@ async function indexFile(absolutePath, relativePath, repoPath, db, unparsed, col
             }
             return;
         }
+        if (extraction.result.apexClassUseIncompleteReason && unparsed)
+            tallyOne(unparsed, extensionBucket(relativePath));
         if (collectResult) {
             collectResult(extraction.result);
         }
@@ -6792,7 +8102,7 @@ async function indexFile(absolutePath, relativePath, repoPath, db, unparsed, col
  * stale wiring atomically without a second schema or cache.
  */
 function reconcileTypeScriptDi(db, repoPath) {
-    const files = collectRepoFiles(repoPath).filter((file) => (file.endsWith(".ts") || file.endsWith(".tsx")) && !file.endsWith(".d.ts"));
+    const files = collectRepoFiles(repoPath, db).filter((file) => (file.endsWith(".ts") || file.endsWith(".tsx")) && !file.endsWith(".d.ts"));
     const frameworkFiles = files.filter((file) => {
         try {
             const source = fs.readFileSync(path.join(repoPath, file), "utf8");
@@ -7381,10 +8691,10 @@ async function indexEmbeddings(db, repoPath, progress, signal) {
             progress?.("embedding-symbols", 0, `Embedding ${missing.length.toLocaleString()} symbols`, {
                 phaseTotal: missing.length,
             });
-            progress?.("embedding-model", 0, "Preparing local embedding model");
             let completedEmbeddings = 0;
+            let modelProgressComplete = false;
             const onModelProgress = (event) => {
-                if (completedEmbeddings > 0)
+                if (modelProgressComplete)
                     return;
                 const completed = event.loaded ?? 0;
                 const total = event.total;
@@ -7404,6 +8714,8 @@ async function indexEmbeddings(db, repoPath, progress, signal) {
 			`);
             const batchSize = embeddingBatchSize();
             const sourceForEmbedding = createEmbeddingSourceReader(repoPath);
+            const reuse = new EmbeddingReuseCache(db);
+            const modelIdentity = getEmbeddingCacheIdentity();
             let lastYieldAt = Date.now();
             for (let offset = 0; offset < missing.length; offset += batchSize) {
                 throwIfAborted(signal);
@@ -7411,14 +8723,33 @@ async function indexEmbeddings(db, repoPath, progress, signal) {
                     const source = sourceForEmbedding(sym.filePath, sym.startLine, sym.endLine);
                     return { symbol: sym, text: embeddingInputFor(sym, source) };
                 });
-                const generated = await embedPreparedBatch(prepared, onModelProgress);
+                const cached = [];
+                const uncached = [];
+                const keys = new Map();
+                for (const item of prepared) {
+                    const key = embeddingReuseKey(modelIdentity, item.text);
+                    keys.set(item.symbol.id, key);
+                    const embedding = reuse.get(key);
+                    if (embedding)
+                        cached.push({ symbol: item.symbol, embedding });
+                    else
+                        uncached.push(item);
+                }
+                const generated = [
+                    ...cached,
+                    ...(uncached.length ? await embedPreparedBatch(uncached, onModelProgress) : []),
+                ];
+                if (uncached.length > 0)
+                    modelProgressComplete = true;
                 throwIfAborted(signal);
                 db.run("BEGIN TRANSACTION;");
                 try {
                     for (const { symbol, embedding: embeddingVec } of generated) {
                         const u8 = new Uint8Array(embeddingVec.buffer, embeddingVec.byteOffset, embeddingVec.byteLength);
                         insertEmbedding.run(symbol.id, u8);
+                        reuse.put(keys.get(symbol.id), embeddingVec);
                     }
+                    reuse.prune();
                     db.run("COMMIT;");
                 }
                 catch (error) {
@@ -7460,8 +8791,8 @@ function extensionBucket(relativePath) {
 function tallyOne(tally, bucket) {
     tally.set(bucket, (tally.get(bucket) ?? 0) + 1);
 }
-function collectRepoFiles(repoPath) {
-    return collectRepoFilesWithCoverage(repoPath).files;
+function collectRepoFiles(repoPath, db) {
+    return collectRepoFilesWithCoverage(repoPath, db).files;
 }
 /** Descending-count record, so the largest coverage gap reads first. */
 function sortedTally(tally) {
@@ -7664,7 +8995,8 @@ function isIndexableJsonCandidate(file, repoPath) {
         return false;
     }
 }
-function gitTrackedCandidates(repoPath) {
+function gitTrackedCandidates(repoPath, intent) {
+    let gitConfirmed = false;
     try {
         const gitRoot = child_process
             .execFileSync("git", ["rev-parse", "--show-toplevel"], {
@@ -7675,21 +9007,31 @@ function gitTrackedCandidates(repoPath) {
             .trim();
         if (!gitRoot || !isSameDir(gitRoot, repoPath))
             return null;
-        return splitNulPaths(child_process.execFileSync("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], {
-            cwd: repoPath,
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"],
-            maxBuffer: 64 * 1024 * 1024,
-        })).filter((file) => {
+        gitConfirmed = true;
+        let candidates = [];
+        for (const pathspecs of coverageGitPathspecBatches(intent))
+            candidates = candidates.concat(splitNulPaths(child_process.execFileSync("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard", ...pathspecs], {
+                cwd: repoPath,
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+                maxBuffer: 64 * 1024 * 1024,
+            })));
+        return (intent?.mode === "scoped" ? [...new Set(candidates)] : candidates).filter((file) => {
+            if (intent && !coverageContains(intent, file))
+                return false;
             try {
-                return fs.statSync(path.join(repoPath, file)).isFile();
+                return intent?.mode === "scoped"
+                    ? (safeCoveragePath(repoPath, file)?.isFile() ?? false)
+                    : fs.statSync(path.join(repoPath, file)).isFile();
             }
             catch {
                 return false;
             }
         });
     }
-    catch {
+    catch (error) {
+        if (intent?.mode === "scoped" && (gitConfirmed || fs.existsSync(path.join(repoPath, ".git"))))
+            throw new Error("knodin: scoped Git file enumeration failed; refusing an unfiltered filesystem fallback", { cause: error });
         return null;
     }
 }
@@ -7708,29 +9050,41 @@ async function execGitAbortable(repoPath, args, signal) {
             : resolve(stdout));
     });
 }
-async function collectRepoFilesWithCoverageAbortable(repoPath, signal) {
+async function collectRepoFilesWithCoverageAbortable(repoPath, signal, db) {
+    const intent = requireIndexCoverage(coverageForDatabase(db ?? dbInstances.get(path.resolve(repoPath))));
     let candidates = null;
+    let gitConfirmed = false;
     try {
         const gitRoot = (await execGitAbortable(repoPath, ["rev-parse", "--show-toplevel"], signal)).trim();
         if (gitRoot && isSameDir(gitRoot, repoPath)) {
-            candidates = splitNulPaths(await execGitAbortable(repoPath, ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], signal));
+            gitConfirmed = true;
+            let selected = [];
+            for (const pathspecs of coverageGitPathspecBatches(intent))
+                selected = selected.concat(splitNulPaths(await execGitAbortable(repoPath, ["ls-files", "-z", "--cached", "--others", "--exclude-standard", ...pathspecs], signal)));
+            candidates = intent.mode === "scoped" ? [...new Set(selected)] : selected;
         }
     }
-    catch {
+    catch (error) {
         throwIfAborted(signal);
+        if (intent.mode === "scoped" && (gitConfirmed || fs.existsSync(path.join(repoPath, ".git"))))
+            throw new Error("knodin: scoped Git file enumeration failed; refusing an unfiltered filesystem fallback", { cause: error });
     }
     const files = [];
     const skippedByExtension = new Map();
-    const source = candidates ?? walkRepoFiles(repoPath);
+    const source = candidates ?? walkCoverageFiles(repoPath, intent);
     for (let index = 0; index < source.length; index++) {
         if (index % 256 === 0) {
             throwIfAborted(signal);
             await yieldToIndexEventLoop();
         }
         const file = source[index];
+        if (!coverageContains(intent, file))
+            continue;
         if (candidates) {
             try {
-                if (!fs.statSync(path.join(repoPath, file)).isFile())
+                if (!(intent.mode === "scoped"
+                    ? safeCoveragePath(repoPath, file)?.isFile()
+                    : fs.statSync(path.join(repoPath, file)).isFile()))
                     continue;
             }
             catch {
@@ -7755,17 +9109,21 @@ async function collectRepoFilesWithCoverageAbortable(repoPath, signal) {
  * `manifest.json` files and Dockerfiles. Shared by the full index and the
  * cold-start reconcile so both see the identical candidate set.
  */
-function collectRepoFilesWithCoverage(repoPath) {
+function collectRepoFilesWithCoverage(repoPath, db, requestedIntent) {
+    const intent = requestedIntent ??
+        requireIndexCoverage(coverageForDatabase(db ?? dbInstances.get(path.resolve(repoPath))));
     const files = [];
     const skippedByExtension = new Map();
-    const candidates = gitTrackedCandidates(repoPath);
+    const candidates = gitTrackedCandidates(repoPath, intent);
     // The walk deliberately does NOT pre-filter with `accept`: both branches must
     // see the same candidate superset so the skip tally below counts identically
     // whether or not the repository is a Git work tree. (main passed
     // `{ accept: isIndexableSourcePath }` here; filtering during the walk would
     // make the excluded files invisible to the tally, which is the whole point of
     // this function.)
-    for (const file of candidates ?? walkRepoFiles(repoPath)) {
+    for (const file of candidates ?? walkCoverageFiles(repoPath, intent)) {
+        if (!coverageContains(intent, file))
+            continue;
         // Pruned infrastructure (node_modules, dist, .git, state dirs) is not a
         // coverage gap and is never counted as one.
         if (!isIndexablePath(file))
@@ -7792,7 +9150,7 @@ function collectRepoFilesWithCoverage(repoPath) {
 function gitHead(repoPath) {
     try {
         const out = child_process
-            .execSync("git rev-parse HEAD", {
+            .execFileSync("git", ["rev-parse", "HEAD"], {
             cwd: repoPath,
             encoding: "utf-8",
             stdio: ["pipe", "pipe", "ignore"],
@@ -7800,28 +9158,119 @@ function gitHead(repoPath) {
             .trim();
         return out || null;
     }
-    catch {
-        return null;
+    catch {
+        return null;
+    }
+}
+/** Read a value from the `meta` key/value table (null if absent). */
+function getMeta(db, key) {
+    try {
+        const row = db
+            .query("SELECT value FROM meta WHERE key = ?")
+            .get(key);
+        return row?.value ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Upsert a value into the `meta` key/value table. */
+function setMeta(db, key, value) {
+    try {
+        db.run("INSERT INTO meta(key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value", [key, value]);
+    }
+    catch (_) { }
+}
+const coverageStates = new WeakMap();
+function coverageForDatabase(db) {
+    if (!db)
+        return readIndexCoverage(null, null, null);
+    const values = [
+        getMeta(db, INDEX_COVERAGE_KEY),
+        getMeta(db, INDEX_COVERAGE_PENDING_KEY),
+        getMeta(db, INDEX_COVERAGE_COMPLETE_KEY),
+    ];
+    const key = JSON.stringify(values);
+    const cached = coverageStates.get(db);
+    if (cached?.key === key)
+        return cached.state;
+    const state = readIndexCoverage(...values);
+    coverageStates.set(db, { key, state });
+    return state;
+}
+function writeCoverageIntent(db, repoPath, intent) {
+    // Unlike best-effort informational meta, scope intent must commit or fail BEFORE work.
+    db.run("BEGIN TRANSACTION;");
+    try {
+        for (const [key, value] of [
+            [INDEX_COVERAGE_KEY, JSON.stringify(intent)],
+            [INDEX_COVERAGE_PENDING_KEY, String(intent.revision)],
+        ])
+            db.run("INSERT INTO meta(key,value) VALUES (?,?) ON CONFLICT(key) DO UPDATE SET value=excluded.value", [key, value]);
+        db.run("COMMIT;");
+    }
+    catch (error) {
+        db.run("ROLLBACK;");
+        throw error;
+    }
+    freshnessProbes.delete(path.resolve(repoPath));
+    statusCache.delete(path.resolve(repoPath));
+    invalidateResolutionCaches(repoPath);
+    indexGeneration++;
+}
+function markCoverageIntentComplete(db) {
+    const state = coverageForDatabase(db);
+    if (state.origin !== "explicit" || !state.intent)
+        return;
+    db.run("INSERT INTO meta(key,value) VALUES (?,?) ON CONFLICT(key) DO UPDATE SET value=excluded.value", [INDEX_COVERAGE_COMPLETE_KEY, String(state.intent.revision)]);
+    db.run("DELETE FROM meta WHERE key = ?", [INDEX_COVERAGE_PENDING_KEY]);
+}
+function completeCoverageIntent(db) {
+    db.run("BEGIN TRANSACTION;");
+    try {
+        markCoverageIntentComplete(db);
+        db.run("COMMIT;");
+    }
+    catch (error) {
+        db.run("ROLLBACK;");
+        throw error;
     }
 }
-/** Read a value from the `meta` key/value table (null if absent). */
-function getMeta(db, key) {
+/** No selector can follow a symlink, including a symlink in a parent directory. */
+function safeCoveragePath(repoPath, file) {
+    if (!canonicalCoveragePath(file) || !isIndexablePath(file))
+        return null;
+    let absolute = repoPath;
+    let stat = null;
     try {
-        const row = db
-            .query("SELECT value FROM meta WHERE key = ?")
-            .get(key);
-        return row?.value ?? null;
+        for (const part of file.split("/")) {
+            absolute = path.join(absolute, part);
+            stat = fs.lstatSync(absolute);
+            if (stat.isSymbolicLink())
+                return null;
+        }
+        return stat;
     }
     catch {
         return null;
     }
 }
-/** Upsert a value into the `meta` key/value table. */
-function setMeta(db, key, value) {
-    try {
-        db.run("INSERT INTO meta(key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value", [key, value]);
+function walkCoverageFiles(repoPath, intent) {
+    if (intent.mode === "full")
+        return walkRepoFiles(repoPath);
+    const files = new Set();
+    for (const file of intent.files)
+        if (safeCoveragePath(repoPath, file)?.isFile())
+            files.add(file);
+    for (const prefix of intent.prefixes) {
+        const stat = safeCoveragePath(repoPath, prefix);
+        if (stat?.isFile())
+            files.add(prefix);
+        else if (stat?.isDirectory())
+            for (const file of walkRepoFiles(path.join(repoPath, prefix)))
+                files.add(`${prefix}/${file}`);
     }
-    catch (_) { }
+    return [...files].sort(compareBytes);
 }
 function commitRelation(repoPath, indexedHead, currentHead) {
     if (!indexedHead || !currentHead)
@@ -7856,16 +9305,21 @@ function freshnessFingerprint(value) {
     return crypto.createHash("sha256").update(value).digest("hex");
 }
 function buildFreshnessEnvelope(repoPath, db, verifiedAt, stateOverride, gitProbe) {
-    const git = gitProbe === undefined ? gitWorkTreeProbe(repoPath) : gitProbe;
+    const coverage = coverageForDatabase(db);
+    const git = gitProbe === undefined ? gitWorkTreeProbe(repoPath, coverage.intent ?? undefined) : gitProbe;
+    const intent = coverage.intent;
+    const scopedDirty = intent
+        ? git?.dirty.filter((file) => coverageContains(intent, file))
+        : undefined;
     const currentHead = git && isSameDir(git.root, repoPath) ? git.head || null : gitHead(repoPath);
     const indexedHead = db ? getMeta(db, "lastIndexedHead") || null : null;
     const relation = commitRelation(repoPath, indexedHead, currentHead);
     const baseline = db ? getMeta(db, "lastProbeDirty") : null;
-    const pendingPaths = git && isSameDir(git.root, repoPath) ? git.dirty.length : null;
+    const pendingPaths = git && isSameDir(git.root, repoPath) ? (scopedDirty?.length ?? null) : null;
     const workingTreeChanged = git !== null &&
         isSameDir(git.root, repoPath) &&
         baseline !== null &&
-        baseline !== git.dirty.join("\n");
+        baseline !== (scopedDirty ? coverageDirtyFingerprint(coverage.intent, scopedDirty) : undefined);
     const state = stateOverride ??
         (currentHead === null && indexedHead === null && baseline !== null
             ? workingTreeChanged
@@ -7880,6 +9334,7 @@ function buildFreshnessEnvelope(repoPath, db, verifiedAt, stateOverride, gitProb
                         : "fresh");
     return {
         currentHead,
+        indexCoverage: indexCoverageSummary(coverage),
         indexedHead,
         ...relation,
         workingTree: {
@@ -7963,6 +9418,10 @@ function removeIndexState(db, relPath) {
     if (!shouldPurgeMissingFile(db))
         return;
     try {
+        db.run("DELETE FROM apex_consumer_files WHERE filePath = ?", [relPath]);
+        db.run("DELETE FROM apex_class_uses WHERE filePath = ?", [relPath]);
+        if (/\.(?:cls|trigger)$/i.test(relPath))
+            setMeta(db, "apexConsumerFactsRevision", crypto.randomUUID());
         db.run("DELETE FROM index_state WHERE filePath = ?", [relPath]);
     }
     catch (_) { }
@@ -8035,8 +9494,9 @@ function detectDriftByStat(repoPath, db, canonicalFiles) {
     }
     return changed;
 }
-async function reconcileIndex(repoPath, db, progress, skipEmbeddings = false) {
+async function reconcileIndex(repoPath, db, progress, skipEmbeddings = getMeta(db, "semanticDeferred") === "1") {
     try {
+        const coverage = requireIndexCoverage(coverageForDatabase(db));
         progress?.("collecting-files", 0, "Checking existing local graph for changes");
         const changed = new Set();
         const head = gitHead(repoPath);
@@ -8045,26 +9505,37 @@ async function reconcileIndex(repoPath, db, progress, skipEmbeddings = false) {
             // --- git fast path ---
             const lastHead = getMeta(db, "lastIndexedHead");
             try {
-                const status = child_process.execFileSync("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all"], {
-                    cwd: repoPath,
-                    encoding: "utf-8",
-                    stdio: ["ignore", "pipe", "ignore"],
-                });
-                for (const file of parseGitStatusPaths(status))
-                    changed.add(file);
-            }
-            catch (_) { }
-            let baselineUnresolved = false;
-            if (lastHead && lastHead !== head) {
-                try {
-                    const diff = child_process.execFileSync("git", ["diff", "--name-only", "-z", lastHead, head, "--"], {
+                for (const pathspecs of coverageGitPathspecBatches(coverage)) {
+                    const status = child_process.execFileSync("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all", ...pathspecs], {
                         cwd: repoPath,
                         encoding: "utf-8",
                         stdio: ["ignore", "pipe", "ignore"],
                     });
-                    for (const file of splitNulPaths(diff))
+                    for (const file of parseGitStatusPaths(status))
                         changed.add(file);
                 }
+            }
+            catch (_) { }
+            let baselineUnresolved = false;
+            if (lastHead && lastHead !== head) {
+                try {
+                    for (const pathspecs of coverageGitPathspecBatches(coverage)) {
+                        const diff = child_process.execFileSync("git", [
+                            "diff",
+                            "--name-only",
+                            "-z",
+                            lastHead,
+                            head,
+                            ...(pathspecs.length ? pathspecs : ["--"]),
+                        ], {
+                            cwd: repoPath,
+                            encoding: "utf-8",
+                            stdio: ["ignore", "pipe", "ignore"],
+                        });
+                        for (const file of splitNulPaths(diff))
+                            changed.add(file);
+                    }
+                }
                 catch (_) {
                     // `lastHead` is not resolvable in this checkout's object database
                     // (a shallow clone missing that commit, or a database seeded from
@@ -8077,7 +9548,7 @@ async function reconcileIndex(repoPath, db, progress, skipEmbeddings = false) {
             }
             if (baselineUnresolved) {
                 console.warn(`knodin: cached baseline commit ${lastHead} is not resolvable in this checkout (shallow clone or foreign database) — falling back to a full file-drift comparison`);
-                canonicalFiles = collectRepoFiles(repoPath);
+                canonicalFiles = collectRepoFiles(repoPath, db);
                 if (canonicalFiles.length > 50000) {
                     console.warn(`knodin: skipping full-drift fallback reconcile (${canonicalFiles.length} files exceeds 50k bound)`);
                 }
@@ -8089,7 +9560,7 @@ async function reconcileIndex(repoPath, db, progress, skipEmbeddings = false) {
         }
         else {
             // --- non-git fallback: mtime/size vs index_state ---
-            canonicalFiles = collectRepoFiles(repoPath);
+            canonicalFiles = collectRepoFiles(repoPath, db);
             if (canonicalFiles.length > 50000) {
                 console.warn(`knodin: skipping freshness reconcile (${canonicalFiles.length} files exceeds 50k bound)`);
                 return 0;
@@ -8100,7 +9571,7 @@ async function reconcileIndex(repoPath, db, progress, skipEmbeddings = false) {
         // A row in index_state whose file is gone or no longer satisfies the
         // canonical source policy must be purged. Keep those legacy rows in the
         // candidate set without admitting newly changed non-source files.
-        canonicalFiles ??= collectRepoFiles(repoPath);
+        canonicalFiles ??= collectRepoFiles(repoPath, db);
         const canonicalPaths = new Set(canonicalFiles);
         const indexedPaths = new Set();
         for (const row of db
@@ -8114,7 +9585,8 @@ async function reconcileIndex(repoPath, db, progress, skipEmbeddings = false) {
             if (!indexedPaths.has(file))
                 changed.add(file);
         const candidates = [...changed]
-            .filter((file) => isIndexableSourcePath(file) || indexedPaths.has(file))
+            .filter((file) => (coverageContains(coverage, file) && isIndexableSourcePath(file)) ||
+            indexedPaths.has(file))
             .sort(compareBytes);
         progress?.("indexing-files", 0, `Reconciling ${candidates.length.toLocaleString()} changed files`, {
             phaseTotal: candidates.length,
@@ -8154,6 +9626,10 @@ async function reconcileIndex(repoPath, db, progress, skipEmbeddings = false) {
         // Re-embed ONLY what changed (indexEmbeddings embeds symbols lacking an
         // embedding), so a no-op reconcile triggers no embedding work at all.
         if (reindexed > 0) {
+            const refreshed = await refreshFlowsForApexFiles(db, repoPath, reindexedPaths);
+            for (const file of refreshed)
+                if (!reindexedPaths.includes(file))
+                    reindexedPaths.push(file);
             progress?.("finalizing", 0, skipEmbeddings
                 ? "Refreshing identities (semantic embeddings deferred)"
                 : "Refreshing identities and semantic embeddings");
@@ -8186,6 +9662,7 @@ async function reconcileIndex(repoPath, db, progress, skipEmbeddings = false) {
         setMeta(db, "knodinVersion", KNODIN_VERSION);
         setMeta(db, "lastSuccessfulReconciliation", new Date().toISOString());
         recordFreshnessBaseline(repoPath, db);
+        completeCoverageIntent(db);
         return reindexed;
     }
     catch (e) {
@@ -8309,7 +9786,35 @@ export function resetFreshnessStats() {
  * Returns null when `repoPath` is not a git work tree (or git failed), which
  * sends the caller to the mtime fallback.
  */
-function gitWorkTreeProbe(repoPath) {
+function gitWorkTreeProbe(repoPath, intent) {
+    if (intent?.mode === "scoped") {
+        try {
+            const options = {
+                cwd: repoPath,
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+                maxBuffer: 64 * 1024 * 1024,
+            };
+            const root = child_process
+                .execFileSync("git", ["rev-parse", "--show-toplevel"], options)
+                .trim();
+            if (!isSameDir(root, repoPath))
+                return null;
+            const dirty = new Set();
+            for (const pathspecs of coverageGitPathspecBatches(intent)) {
+                const output = child_process.execFileSync("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all", ...pathspecs], options);
+                for (const file of parseGitStatusPaths(output))
+                    if (coverageContains(intent, file) && isIndexablePath(file))
+                        dirty.add(file);
+            }
+            return { root, head: gitHead(repoPath) ?? "", dirty: [...dirty].sort(compareBytes) };
+        }
+        catch (error) {
+            if (error.code === "ENOBUFS")
+                freshnessStats.probeOverflows++;
+            return null;
+        }
+    }
     let lines;
     try {
         lines = child_process
@@ -8385,10 +9890,17 @@ function fileDriftedFromIndexState(db, repoPath, relPath) {
  * compare the dirty set against. Uses the existing R8 `meta` table — no schema
  * bump — and self-heals on indexes written before this key existed.
  */
+function coverageDirtyFingerprint(intent, dirty) {
+    return intent?.mode === "scoped" ? JSON.stringify(dirty) : dirty.join("\n");
+}
 function recordFreshnessBaseline(repoPath, db) {
-    const git = gitWorkTreeProbe(repoPath);
-    const dirty = git && isSameDir(git.root, repoPath) ? git.dirty : null;
-    setMeta(db, "lastProbeDirty", dirty === null ? "" : dirty.join("\n"));
+    const intent = requireIndexCoverage(coverageForDatabase(db));
+    const git = gitWorkTreeProbe(repoPath, intent);
+    const dirty = git && isSameDir(git.root, repoPath)
+        ? git.dirty.filter((file) => coverageContains(intent, file))
+        : null;
+    setMeta(db, "lastProbeDirty", dirty === null ? "" : coverageDirtyFingerprint(intent, dirty));
+    setMeta(db, "lastProbeCoverage", indexCoverageSummary(coverageForDatabase(db)).digest ?? "");
 }
 /**
  * Decide — WITHOUT indexing anything — whether the index still matches the
@@ -8411,15 +9923,24 @@ function recordFreshnessBaseline(repoPath, db) {
  * the watcher or a cold start, not by this probe.
  */
 function probeDrift(repoPath, db, gitProbe) {
-    const git = gitProbe === undefined ? gitWorkTreeProbe(repoPath) : gitProbe;
+    const coverage = coverageForDatabase(db);
+    const intent = requireIndexCoverage(coverage);
+    if (coverage.intentState === "pending" ||
+        (coverage.origin === "explicit" &&
+            getMeta(db, "lastProbeCoverage") !== indexCoverageSummary(coverage).digest))
+        return { drifted: true, verifiable: true };
+    const git = gitProbe === undefined ? gitWorkTreeProbe(repoPath, intent) : gitProbe;
+    if (!git && intent.mode === "scoped" && fs.existsSync(path.join(repoPath, ".git")))
+        return { drifted: false, verifiable: false };
     if (git && isSameDir(git.root, repoPath)) {
         if ((getMeta(db, "lastIndexedHead") ?? "") !== git.head) {
             return { drifted: true, verifiable: true };
         }
-        if (getMeta(db, "lastProbeDirty") !== git.dirty.join("\n")) {
+        const dirty = git.dirty.filter((file) => coverageContains(intent, file));
+        if (getMeta(db, "lastProbeDirty") !== coverageDirtyFingerprint(intent, dirty)) {
             return { drifted: true, verifiable: true };
         }
-        for (const rel of git.dirty) {
+        for (const rel of dirty) {
             if (!isIndexablePath(rel))
                 continue;
             if (fileDriftedFromIndexState(db, repoPath, rel))
@@ -8456,6 +9977,8 @@ function noteFreshness(repoPath, staleness) {
  * after the fact is therefore worthless here.
  */
 async function ensureIndexFresh(repoPath, db) {
+    const coverage = coverageForDatabase(db);
+    requireIndexCoverage(coverage);
     const key = path.resolve(repoPath);
     const cached = freshnessProbes.get(key);
     // A watcher cannot prove that an edit made immediately before this call has
@@ -8475,7 +9998,11 @@ async function ensureIndexFresh(repoPath, db) {
         : watchQueues.get(key)?.ready
             ? WATCHED_FRESHNESS_LEASE_MS
             : FRESHNESS_PROBE_TTL_MS;
-    if (cached && Date.now() - cached.at < lease) {
+    if (cached &&
+        Date.now() - cached.at < lease &&
+        coverage.intentState !== "pending" &&
+        (coverage.origin !== "explicit" ||
+            getMeta(db, "lastProbeCoverage") === indexCoverageSummary(coverage).digest)) {
         freshnessStats.cacheHits++;
         return cached.staleness;
     }
@@ -8522,7 +10049,7 @@ function stalenessFor(repoPath) {
     return freshnessProbes.get(path.resolve(repoPath))?.staleness ?? "unknown";
 }
 /** Recursively indexes all matching files within the repository. */
-async function indexRepo(repoPath, db, progress, skipEmbeddings = false, publishProcessState = true, 
+async function indexRepo(repoPath, db, progress, skipEmbeddings = getMeta(db, "semanticDeferred") === "1", publishProcessState = true, 
 /**
  * Continue a build already in this database instead of starting over.
  *
@@ -8533,8 +10060,9 @@ async function indexRepo(repoPath, db, progress, skipEmbeddings = false, publish
  * observable in that condition.
  */
 resume = false) {
+    setMeta(db, "semanticDeferred", skipEmbeddings ? "1" : "0");
     progress?.("collecting-files", 0, "Discovering indexable files");
-    const collected = measurePerfPhaseSync("file_collection", () => collectRepoFilesWithCoverage(repoPath));
+    const collected = measurePerfPhaseSync("file_collection", () => collectRepoFilesWithCoverage(repoPath, db));
     const files = collected.files;
     // Files that reach the indexer but yield nothing can only be observed here,
     // during the parse. Persisted below so `status` can report the gap without
@@ -8582,6 +10110,9 @@ resume = false) {
         db.run("DELETE FROM dependencies;");
         db.run("DELETE FROM mcp_tools;");
         db.run("DELETE FROM index_state;");
+        db.run("DELETE FROM apex_consumer_files;");
+        db.run("DELETE FROM apex_class_uses;");
+        setMeta(db, "apexConsumerFactsRevision", crypto.randomUUID());
     }
     // On a resume, everything already recorded and still matching disk is done.
     // Counted toward progress rather than dropped from it, so the totals stay
@@ -8684,6 +10215,8 @@ resume = false) {
             await pool.run(eligible, async (task, outcome) => {
                 switch (outcome.kind) {
                     case "result":
+                        if (outcome.result.apexClassUseIncompleteReason)
+                            tallyOne(unparsedByExtension, extensionBucket(task.relativePath));
                         pendingWrites.push(outcome.result);
                         break;
                     case "unparsed":
@@ -8717,6 +10250,7 @@ resume = false) {
     }
     flushPendingWrites();
     progress?.("finalizing", 0, "Persisting symbol identities and semantic index");
+    await refreshFlowsForApexFiles(db, repoPath, files);
     persistSymbolIdentities(db, repoPath);
     reconcileTypeScriptDi(db, repoPath);
     // Structure is complete at this point; embeddings are the expensive tail. When
@@ -8816,11 +10350,14 @@ function startFileWatcher(repoPath, db, watcherFileLimit = MAX_RECURSIVE_WATCH_F
                         }
                         throw new Error("injected watcher flush failure");
                     }
+                    const intent = requireIndexCoverage(coverageForDatabase(db));
+                    const canonicalScopedFiles = intent.mode === "scoped" ? new Set(collectRepoFiles(resolvedRepoPath, db)) : null;
                     for (const relativePath of paths) {
                         const absolutePath = path.join(resolvedRepoPath, relativePath);
                         // Event order is intentionally ignored: disk truth at flush time handles
                         // atomic-save unlink/add sequences and duplicate change notifications.
-                        if (fs.existsSync(absolutePath)) {
+                        if (fs.existsSync(absolutePath) &&
+                            (!canonicalScopedFiles || canonicalScopedFiles.has(relativePath))) {
                             await indexFile(absolutePath, relativePath, resolvedRepoPath, db);
                             recordIndexState(db, resolvedRepoPath, relativePath);
                         }
@@ -8828,10 +10365,13 @@ function startFileWatcher(repoPath, db, watcherFileLimit = MAX_RECURSIVE_WATCH_F
                             purgeFile(relativePath);
                         }
                     }
-                    persistSymbolIdentities(db, resolvedRepoPath, paths);
+                    const refreshed = await refreshFlowsForApexFiles(db, resolvedRepoPath, paths);
+                    persistSymbolIdentities(db, resolvedRepoPath, [...new Set([...paths, ...refreshed])]);
                     reconcileTypeScriptDi(db, resolvedRepoPath);
-                    await indexEmbeddings(db, resolvedRepoPath);
-                    queue.embeddingReconciliations++;
+                    if (getMeta(db, "semanticDeferred") !== "1") {
+                        await indexEmbeddings(db, resolvedRepoPath);
+                        queue.embeddingReconciliations++;
+                    }
                     indexGeneration++;
                     queue.generationAdvances++;
                     recordFreshnessBaseline(resolvedRepoPath, db);
@@ -8871,7 +10411,10 @@ function startFileWatcher(repoPath, db, watcherFileLimit = MAX_RECURSIVE_WATCH_F
         if (queue.closed)
             return;
         const relativePath = path.relative(resolvedRepoPath, filePath);
-        if (!isIndexableSourcePath(relativePath))
+        const coverage = coverageForDatabase(db);
+        if (!coverage.intent ||
+            !coverageContains(coverage.intent, relativePath) ||
+            !isIndexableSourcePath(relativePath))
             return;
         freshnessProbes.delete(resolvedRepoPath);
         queue.pending.add(relativePath);
@@ -8884,7 +10427,13 @@ function startFileWatcher(repoPath, db, watcherFileLimit = MAX_RECURSIVE_WATCH_F
     };
     queue.drain = flush;
     const watcher = chokidar.watch(repoPath, {
-        ignored: makeWatchIgnorePredicate(repoPath),
+        ignored: (targetPath) => {
+            const coverage = coverageForDatabase(db);
+            const relative = path.relative(repoPath, targetPath).split(path.sep).join("/");
+            return (!coverage.intent ||
+                !coverageMayContain(coverage.intent, relative) ||
+                makeWatchIgnorePredicate(repoPath)(targetPath));
+        },
         persistent: true,
         ignoreInitial: true,
     });
@@ -9103,6 +10652,10 @@ export async function getOrInitDb(repoPath, options = {}) {
                 db.run("ALTER TABLE symbols ADD COLUMN identity TEXT;");
             }
             catch (_) { }
+            try {
+                db.run("ALTER TABLE symbols ADD COLUMN apexDeclaration TEXT;");
+            }
+            catch (_) { }
             db.run("CREATE INDEX IF NOT EXISTS idx_symbols_identity ON symbols(identity);");
             db.run(`
 				CREATE TABLE IF NOT EXISTS "references" (
@@ -9153,6 +10706,20 @@ export async function getOrInitDb(repoPath, options = {}) {
                 db.run('ALTER TABLE "references" ADD COLUMN calleeIdentity TEXT;');
             }
             catch (_) { }
+            try {
+                db.run('ALTER TABLE "references" ADD COLUMN apexCall TEXT;');
+            }
+            catch (_) { }
+            db.run("CREATE TABLE IF NOT EXISTS apex_file_capabilities(filePath TEXT PRIMARY KEY, version INTEGER NOT NULL)");
+            db.run("CREATE TABLE IF NOT EXISTS apex_consumer_files(filePath TEXT PRIMARY KEY, version INTEGER NOT NULL, sourceHash TEXT NOT NULL, parseState TEXT NOT NULL, isTest INTEGER, facts TEXT NOT NULL, factsHash TEXT)");
+            try {
+                db.run("ALTER TABLE apex_consumer_files ADD COLUMN factsHash TEXT");
+            }
+            catch (_) { }
+            db.run("CREATE TABLE IF NOT EXISTS apex_class_uses(filePath TEXT NOT NULL,startByte INTEGER NOT NULL,endByte INTEGER NOT NULL,kind TEXT NOT NULL,raw TEXT NOT NULL,status TEXT NOT NULL,targetFile TEXT,targetOwner TEXT,targetIdentity TEXT,ownerIdentity TEXT,isTest INTEGER,PRIMARY KEY(filePath,startByte,endByte,kind))");
+            db.run("CREATE INDEX IF NOT EXISTS idx_apex_class_uses_target ON apex_class_uses(targetFile,targetOwner,filePath,startByte,endByte,kind)");
+            db.run("CREATE INDEX IF NOT EXISTS idx_symbols_apex_provenance ON symbols(id) WHERE apexDeclaration IS NOT NULL");
+            db.run('CREATE INDEX IF NOT EXISTS idx_references_apex_provenance ON "references"(id) WHERE apexCall IS NOT NULL');
             db.run(`
 				CREATE TABLE IF NOT EXISTS dependencies (
 					id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -9314,12 +10881,16 @@ export async function getOrInitDb(repoPath, options = {}) {
             catch {
                 needsIndex = true;
             }
-            if (needsIndex && !options.skipContentReconciliation) {
+            if (!options.skipContentReconciliation)
+                requireIndexCoverage(coverageForDatabase(db));
+            if (needsIndex &&
+                coverageForDatabase(db).intent?.mode !== "scoped" &&
+                !options.skipContentReconciliation) {
                 await indexRepo(normalizedPath, db, options.onProgress);
                 // Just built from the working tree — nothing can be stale yet.
                 noteFreshness(normalizedPath, "fresh");
             }
-            else if (!needsIndex && !options.skipContentReconciliation) {
+            else if (!options.skipContentReconciliation) {
                 // Existing on-disk index: reconcile any offline drift (git pull /
                 // branch switch / rebase / external edit) before serving queries.
                 const reindexed = await reconcileIndex(normalizedPath, db, options.onProgress);
@@ -9584,7 +11155,11 @@ function listSourceFiles(repoPath, accept) {
     const sealed = sealedRepositories.get(path.resolve(repoPath));
     if (sealed)
         return listSealedFiles(sealed).filter(accept);
-    return walkRepoFiles(repoPath, { accept });
+    const db = extractionCoverage.getStore() ?? dbInstances.get(path.resolve(repoPath));
+    const intent = requireIndexCoverage(coverageForDatabase(db));
+    return intent.mode === "full"
+        ? walkRepoFiles(repoPath, { accept })
+        : (gitTrackedCandidates(repoPath, intent) ?? walkCoverageFiles(repoPath, intent)).filter((file) => isIndexablePath(file) && accept(file));
 }
 /** Get verbatim source with line numbers, and say so when it is unavailable. */
 function readSourceRange(repoPath, relativePath, startLine, endLine, maxLines) {
@@ -10040,7 +11615,7 @@ const BUILTIN_CALLEE_NAMES = new Set([
  * unrelated same-named symbol. A caller's own definition lives in its
  * `callerFile`, so recursion stays file-qualified by passing that down.
  */
-function findCallersFederated(allRepos, currentRepoPath, targetSymbol, depth, visited = new Set(), targetFile = null, targetIdentity = null) {
+function findCallersFederated(allRepos, currentRepoPath, targetSymbol, depth, visited = new Set(), targetFile = null, targetIdentity = null, includeAnonymousOrigins = false) {
     if (depth <= 0)
         return [];
     const visitedKey = `${currentRepoPath}:${targetSymbol}:${targetFile ?? ""}`;
@@ -10062,28 +11637,32 @@ function findCallersFederated(allRepos, currentRepoPath, targetSymbol, depth, vi
 			FROM "references"
 			WHERE calleeSymbol = ? AND calleeFile = ?
 			  AND (? IS NULL OR calleeIdentity = ?)
-			  AND kind IN ('call', 'di_binding', 'di_resolution', 'flow_apex_action')
+			  AND kind IN ('call', 'di_binding', 'di_resolution', 'flow_apex_action', 'apex_method')
 		`);
         rows = stmt.all(targetSymbol, targetFile, targetIdentity, targetIdentity);
         stmt.finalize();
     }
     else {
         const stmt = db.query(`
-			SELECT id, callerSymbol, callerFile, calleeSymbol, calleeFile, line, column, kind
+			SELECT *
 			FROM "references"
-			WHERE calleeSymbol = ? AND kind IN ('call', 'di_binding', 'di_resolution', 'flow_apex_action')
+			WHERE calleeSymbol = ? AND kind IN ('call', 'di_binding', 'di_resolution', 'flow_apex_action', 'apex_method')
 		`);
         rows = stmt.all(targetSymbol);
         stmt.finalize();
     }
+    const validApexReference = apexReferenceReadGuard(db);
     for (const row of rows) {
-        // A null callerSymbol means the reference couldn't be attributed to a
-        // calling symbol (e.g. a call inside an anonymous callback). Skip it rather
-        // than presenting the file path as if it were the caller.
-        if (!row.callerSymbol)
+        if (!validApexReference(row))
+            continue;
+        // Preserve exact callee-resolved sites even when no named caller was
+        // extracted. The label is not a symbol identity or a claim about nesting.
+        const anonymous = row.callerSymbol === null;
+        if (anonymous && !includeAnonymousOrigins)
             continue;
         results.push({
-            symbol: row.callerSymbol,
+            symbol: row.callerSymbol ?? "(anonymous or top-level)",
+            ...(anonymous ? { callerOrigin: "anonymous-or-top-level" } : {}),
             filePath: row.callerFile,
             lineNumber: row.line,
             repoPath: currentRepoPath,
@@ -10092,6 +11671,8 @@ function findCallersFederated(allRepos, currentRepoPath, targetSymbol, depth, vi
             evidenceFile: row.callerFile,
             evidenceLine: row.line,
         });
+        if (!row.callerSymbol)
+            continue;
         const parentCallers = findCallersFederated(allRepos, currentRepoPath, row.callerSymbol, depth - 1, visited, row.callerFile, row.callerIdentity ?? null);
         results.push(...parentCallers);
     }
@@ -10172,14 +11753,17 @@ function findCalleesFederated(allRepos, currentRepoPath, targetSymbol, depth, vi
     }
     else {
         const stmt = db.query(`
-			SELECT id, callerSymbol, callerFile, calleeSymbol, calleeFile, line, column, kind
+			SELECT *
 			FROM "references"
 			WHERE callerSymbol = ? AND kind IN ('call', 'di_binding', 'di_resolution', 'flow_apex_action')
 		`);
         rows = stmt.all(targetSymbol);
         stmt.finalize();
     }
+    const validApexReference = apexReferenceReadGuard(db);
     for (const row of rows) {
+        if (!validApexReference(row))
+            continue;
         // An unresolved callee (no calleeFile) with a built-in / global name is
         // almost certainly a stdlib member call (Math.min -> "min") — skip it even
         // if some unrelated project symbol happens to share the name, so it doesn't
@@ -11837,6 +13421,7 @@ function withStaleness(engine, claimRepository, openDb, openPolicy) {
         async status(repoPath, options) {
             claimRepository(repoPath);
             const result = await engine.status(repoPath, options);
+            result.indexCoverage ??= result.freshness.indexCoverage;
             result.freshnessMechanism = freshnessMechanismFor(repoPath, openPolicy);
             return result;
         },
@@ -11864,10 +13449,15 @@ function withStaleness(engine, claimRepository, openDb, openPolicy) {
             // stamping them with the index's freshness would misreport them.
             return engine.searchText(term, repoPath, options);
         },
+        queryClassConsumers(repoPath, request) {
+            claimRepository(repoPath);
+            return engine.queryClassConsumers(repoPath, request);
+        },
         async query(pattern, target, repoPath, to, limit, depth, detailLevel, selector, impactOptions, options) {
             claimRepository(repoPath);
             const result = await engine.query(pattern, target, repoPath, to, limit, depth, detailLevel, selector, impactOptions, options);
-            result.staleness = stalenessFor(repoPath);
+            if (pattern !== "class_consumers")
+                result.staleness = stalenessFor(repoPath);
             return result;
         },
         async rename(oldName, newName, repoPath, apply, verify, selector) {
@@ -12178,6 +13768,14 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
             if (!db)
                 throw new Error("candidate database did not open");
             if (!changes) {
+                const oldCoverage = coverageForDatabase(db);
+                writeCoverageIntent(db, resolved, {
+                    version: 1,
+                    mode: "full",
+                    revision: (oldCoverage.intent?.revision ?? 0) + 1,
+                    prefixes: [],
+                    files: [],
+                });
                 // Claim the build before touching anything, and record which tree it
                 // is for. A candidate carrying this marker is one a previous run left
                 // mid-build; without the commit, a resume could silently continue a
@@ -12190,11 +13788,12 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                 // killed above leaves it set, which is exactly what makes the
                 // candidate recognisable as resumable rather than abandoned.
                 setMeta(db, CLEAN_INDEX_IN_PROGRESS_META_KEY, "");
-                return { reconciled: collectRepoFiles(resolved) };
+                completeCoverageIntent(db);
+                return { reconciled: collectRepoFiles(resolved, db) };
             }
             const reconciled = [...new Set(changes)]
                 .map((file) => path.relative(resolved, path.resolve(resolved, file)))
-                .filter((file) => file !== "" && !file.startsWith("..") && !path.isAbsolute(file))
+                .filter((file) => coverageContains(requireIndexCoverage(coverageForDatabase(db)), file))
                 .sort(compareBytes);
             for (const file of reconciled) {
                 const absolute = path.join(resolved, file);
@@ -12233,10 +13832,16 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                 .filter((file) => !reconciledSet.has(file));
             for (const file of knownPaths)
                 recordIndexState(db, resolved, file);
-            await refreshFlowsForApexFiles(db, resolved, reconciled);
+            const refreshed = await refreshFlowsForApexFiles(db, resolved, reconciled);
+            for (const file of refreshed) {
+                if (!reconciledSet.has(file))
+                    reconciled.push(file);
+                reconciledSet.add(file);
+            }
             persistSymbolIdentities(db, resolved, reconciled);
             reconcileTypeScriptDi(db, resolved);
-            await indexEmbeddings(db, resolved);
+            if (getMeta(db, "semanticDeferred") !== "1")
+                await indexEmbeddings(db, resolved);
             setMeta(db, "lastIndexedHead", gitHead(resolved) ?? "");
             setMeta(db, "knodinVersion", KNODIN_VERSION);
             setMeta(db, "lastSuccessfulReconciliation", new Date().toISOString());
@@ -12251,6 +13856,11 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
             const issues = [];
             const db = new Database(candidate.databasePath, { readonly: true });
             try {
+                const coverage = coverageForDatabase(db);
+                if (coverage.origin === "invalid")
+                    issues.push("invalid-index-coverage");
+                if (coverage.intentState === "pending")
+                    issues.push("pending-index-coverage");
                 const quick = db.query("PRAGMA quick_check").all();
                 if (quick.length !== 1 || Object.values(quick[0] ?? {})[0] !== "ok")
                     issues.push("sqlite-integrity");
@@ -12278,11 +13888,22 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     const symbols = db.query("SELECT COUNT(*) count FROM symbols").get()?.count ?? 0;
                     const embeddings = db.query("SELECT COUNT(*) count FROM symbol_embeddings").get()
                         ?.count ?? 0;
-                    if (symbols !== embeddings)
+                    if (symbols !== embeddings && getMeta(db, "semanticDeferred") !== "1")
                         issues.push("semantic-index-incomplete");
+                    if (db
+                        .query(`SELECT COUNT(*) count FROM symbol_embeddings WHERE ${ORPHANED_EMBEDDING_PREDICATE}`)
+                        .get()?.count)
+                        issues.push("orphaned-embeddings");
                 }
                 if (tables.has("index_state")) {
-                    const sourceFiles = collectRepoFiles(candidate.repo);
+                    if (missingApexConsumerDescriptorFiles(db).length)
+                        issues.push("apex-consumer-descriptors");
+                    if ((db
+                        .query("SELECT COUNT(*) count FROM index_state WHERE lower(filePath) LIKE '%.cls' OR lower(filePath) LIKE '%.trigger'")
+                        .get()?.count ?? 0) > 0 &&
+                        !apexConsumerMaterializationValid(db))
+                        issues.push("apex-consumer-materialization");
+                    const sourceFiles = collectRepoFiles(candidate.repo, db);
                     const sourceSet = new Set(sourceFiles);
                     const indexed = db
                         .query("SELECT filePath, mtimeMs, size FROM index_state")
@@ -12351,6 +13972,9 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
         async explain(symbol, repoPath, detailLevel = "standard", selector = {}) {
             const repos = await getFederatedRepos(repoPath);
             const allRepos = await Promise.all(repos.map(async (r) => ({ path: r, db: await openDb(r) })));
+            const indexCoverage = allRepos.length === 1
+                ? indexCoverageSummary(coverageForDatabase(allRepos[0].db))
+                : undefined;
             let targetRepoPath = repoPath;
             let primaryDef = null;
             const matches = [];
@@ -12384,6 +14008,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     })),
                 };
                 return {
+                    ...(indexCoverage ? { indexCoverage } : {}),
                     symbol,
                     summary: ambiguity.message,
                     source: "",
@@ -12402,6 +14027,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
             }
             if (!primaryDef) {
                 return {
+                    ...(indexCoverage ? { indexCoverage } : {}),
                     symbol,
                     summary: `Symbol "${symbol}" not found in codebase.`,
                     source: "",
@@ -12508,6 +14134,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                 allBlastFiles.length > cap ||
                 omissions.length > cap;
             return {
+                ...(indexCoverage ? { indexCoverage } : {}),
                 identity: symbolIdentity(targetRepoPath, primaryDef),
                 symbol,
                 summary,
@@ -13192,9 +14819,41 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
             const db = activeDb ??
                 (fs.existsSync(diskDbPath) ? new Database(diskDbPath, { readonly: true }) : null);
             const verifiedAt = new Date().toISOString();
+            if (db && coverageForDatabase(db).origin === "invalid") {
+                const result = {
+                    status: "repair-needed",
+                    repo: resolved,
+                    version: KNODIN_VERSION,
+                    schemaVersion: 0,
+                    model: { id: "Xenova/all-MiniLM-L6-v2", dimensions: 384, locality: "local" },
+                    indexCoverage: indexCoverageSummary(coverageForDatabase(db)),
+                    coverage: {
+                        sourceFiles: 0,
+                        indexedFiles: 0,
+                        filesWithSymbols: 0,
+                        percent: 0,
+                        countsUnknown: true,
+                    },
+                    orphaned: { embeddings: 0, references: 0, dependencies: 0 },
+                    missing: {
+                        files: [],
+                        records: ["malformed index coverage intent; inventory was not enumerated"],
+                    },
+                    lastSuccessfulReconciliation: null,
+                    freshness: buildFreshnessEnvelope(resolved, db, verifiedAt, "repair-needed", null),
+                    verification: { mode: "deep-audit", verifiedAt },
+                    freshnessMechanism: freshnessMechanismFor(resolved, openPolicy),
+                    repairSteps: [
+                        "Restore valid coverage metadata, or explicitly rebuild a full candidate with knodin index --clean. Automatic repair cannot guess the intended scope.",
+                    ],
+                };
+                if (!activeDb)
+                    db.close();
+                return result;
+            }
             const activity = options.ignoreActiveOperation ? null : readIndexActivity(resolved);
             if (activity) {
-                const collected = measurePerfPhaseSync("status_audit", () => collectRepoFilesWithCoverage(resolved));
+                const collected = measurePerfPhaseSync("status_audit", () => collectRepoFilesWithCoverage(resolved, db));
                 const sourceFiles = collected.files;
                 const skipped = buildCoverageSkips(collected.skippedByExtension, db);
                 let schemaVersion = 0;
@@ -13322,7 +14981,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     const persisted = readPersistedStatusAudit(resolved, diskDbPath, databaseFingerprint, schemaVersion);
                     if (persisted) {
                         throwIfAborted(options.signal);
-                        const gitProbe = measurePerfPhaseSync("freshness_probe", () => gitWorkTreeProbe(resolved));
+                        const gitProbe = measurePerfPhaseSync("freshness_probe", () => gitWorkTreeProbe(resolved, requireIndexCoverage(coverageForDatabase(db))));
                         const drift = probeDrift(resolved, db, gitProbe);
                         const probeVerifiedAt = new Date().toISOString();
                         const freshness = buildFreshnessEnvelope(resolved, db, probeVerifiedAt, drift.verifiable ? (drift.drifted ? "stale-working-tree" : undefined) : "unknown", gitProbe);
@@ -13400,8 +15059,8 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
             }
             throwIfAborted(options.signal);
             const collected = options.signal
-                ? await measurePerfPhase("status_audit", () => collectRepoFilesWithCoverageAbortable(resolved, options.signal))
-                : measurePerfPhaseSync("status_audit", () => collectRepoFilesWithCoverage(resolved));
+                ? await measurePerfPhase("status_audit", () => collectRepoFilesWithCoverageAbortable(resolved, options.signal, db))
+                : measurePerfPhaseSync("status_audit", () => collectRepoFilesWithCoverage(resolved, db));
             throwIfAborted(options.signal);
             const sourceFiles = collected.files;
             const coverageSkips = buildCoverageSkips(collected.skippedByExtension, db);
@@ -13498,8 +15157,8 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     await yieldToIndexEventLoop();
                 }
                 const row = indexedRows[index];
-                const exists = fs.existsSync(path.join(resolved, row.filePath));
                 if (!sourceFileSet.has(row.filePath)) {
+                    const exists = fs.existsSync(path.join(resolved, row.filePath));
                     (exists ? ineligibleFiles : staleFiles).push(row.filePath);
                     continue;
                 }
@@ -13523,6 +15182,11 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
 					   AND NOT (d.fromFile LIKE '.knodin/dbt/%' AND EXISTS (SELECT 1 FROM symbols s WHERE s.filePath=d.fromFile))`),
             };
             const records = staleFiles.map((file) => `indexed file no longer exists: ${file}`);
+            for (const file of missingApexConsumerDescriptorFiles(db))
+                records.push(`Apex class-consumer descriptor missing or invalid: ${file}`);
+            if (indexedRows.some((row) => /\.(cls|trigger)$/i.test(row.filePath)) &&
+                !apexConsumerMaterializationValid(db))
+                records.push("Apex class-consumer binding materialization is incomplete");
             for (const file of ineligibleFiles)
                 records.push(`indexed file is no longer eligible: ${file}`);
             for (const file of damagedFiles)
@@ -13535,10 +15199,13 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                 records.push(`${orphaned.dependencies} dependency row(s) lack an indexed source file`);
             if (getMeta(db, "repairPostprocessingPending") === "1")
                 records.push("repair post-processing is incomplete");
+            if (coverageForDatabase(db).intentState === "pending")
+                records.push("index coverage operation is pending");
             const needsRepair = missingFiles.length > 0 || records.length > 0;
             const freshness = buildFreshnessEnvelope(resolved, db, verifiedAt, needsRepair ? "repair-needed" : undefined);
             const stale = !needsRepair && freshness.state !== "fresh";
             const result = {
+                indexCoverage: indexCoverageSummary(coverageForDatabase(db)),
                 status: needsRepair ? "repair-needed" : stale ? "stale" : "healthy",
                 repo: resolved,
                 version: KNODIN_VERSION,
@@ -13585,7 +15252,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
             };
             if (!needsRepair && !stale)
                 noteFreshness(resolved, "fresh");
-            if (activeDb) {
+            if (activeDb && options.checkpoint !== "defer") {
                 try {
                     db.run("PRAGMA wal_checkpoint(PASSIVE);");
                 }
@@ -13726,12 +15393,19 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                 }
                 emitProgress("planning", 0, "Building the repair plan");
                 const repairKinds = new Map();
+                const descriptorRepairPaths = new Set();
                 for (const file of before.missing.files)
                     repairKinds.set(file, "indexed");
                 for (const record of before.missing.records) {
                     const damagedPrefix = "indexed snapshot differs from disk: ";
                     const stalePrefix = "indexed file no longer exists: ";
                     const ineligiblePrefix = "indexed file is no longer eligible: ";
+                    const descriptorPrefix = "Apex class-consumer descriptor missing or invalid: ";
+                    if (record.startsWith(descriptorPrefix)) {
+                        const file = record.slice(descriptorPrefix.length);
+                        descriptorRepairPaths.add(file);
+                        repairKinds.set(file, "damaged");
+                    }
                     if (record.startsWith(damagedPrefix))
                         repairKinds.set(record.slice(damagedPrefix.length), "damaged");
                     else if (record.startsWith(stalePrefix))
@@ -13779,9 +15453,11 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                 if (schemaPrepared)
                     committedWork = true;
                 const inheritedPostprocessing = getMeta(db, "repairPostprocessingPending") === "1";
-                const eligibleRepairPaths = new Set(collectRepoFiles(resolved));
+                const eligibleRepairPaths = new Set(collectRepoFiles(resolved, db));
                 repairPaths = [...repairKinds.keys()]
-                    .filter((file) => repairKinds.get(file) === "stale" || fileDriftedFromIndexState(db, resolved, file))
+                    .filter((file) => repairKinds.get(file) === "stale" ||
+                    descriptorRepairPaths.has(file) ||
+                    fileDriftedFromIndexState(db, resolved, file))
                     .sort(compareBytes);
                 const repairAffectsTypeScriptDi = inheritedPostprocessing || repairPathsAffectTypeScriptDi(db, resolved, repairPaths);
                 counts.skipped = Math.max(0, repairKinds.size - repairPaths.length);
@@ -13853,17 +15529,31 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     });
                     cancelBoundary();
                 }
-                const needsPostprocessing = repairPaths.length > 0 || getMeta(db, "repairPostprocessingPending") === "1";
+                const needsPostprocessing = repairPaths.length > 0 ||
+                    before.missing.records.includes("Apex class-consumer binding materialization is incomplete") ||
+                    getMeta(db, "repairPostprocessingPending") === "1" ||
+                    coverageForDatabase(db).intentState === "pending";
                 if (needsPostprocessing) {
                     emitProgress("symbol-identities", 0, "Persisting stable symbol identities", {
                         phaseTotal: 1,
                     });
                     cancelBoundary();
-                    const identityScope = inheritedPostprocessing ? undefined : repairPaths;
+                    const bindingPaths = inheritedPostprocessing
+                        ? db
+                            .query("SELECT filePath FROM index_state WHERE filePath LIKE '%.cls' OR filePath LIKE '%.cmp' OR filePath LIKE 'force-app/main/default/lwc/%.js' OR filePath LIKE 'force-app/main/default/aura/%.app' OR filePath LIKE 'force-app/main/default/pages/%.page' UNION SELECT toFile AS filePath FROM dependencies WHERE toFile LIKE '%.cls' OR toFile LIKE '%.cmp' OR toFile LIKE 'force-app/main/default/lwc/%.js' OR toFile LIKE 'force-app/main/default/aura/%.app' OR toFile LIKE 'force-app/main/default/pages/%.page'")
+                            .all()
+                            .map((row) => row.filePath)
+                        : repairPaths;
+                    const refreshed = await refreshFlowsForApexFiles(db, resolved, bindingPaths);
+                    const identityScope = inheritedPostprocessing
+                        ? undefined
+                        : [...new Set([...repairPaths, ...refreshed])];
                     if (options?.signal)
                         await persistSymbolIdentitiesCancellable(db, resolved, identityScope, activeOperation.controller.signal);
                     else
                         persistSymbolIdentities(db, resolved, identityScope);
+                    if (before.missing.records.includes("Apex class-consumer binding materialization is incomplete"))
+                        persistApexClassConsumerEndpoints(db);
                     if (repairAffectsTypeScriptDi)
                         reconcileTypeScriptDi(db, resolved);
                     committedWork = true;
@@ -13958,11 +15648,12 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     // revision; a second deep audit proves the complete envelope.
                     const contentVerified = after.coverage.sourceFiles === after.coverage.indexedFiles &&
                         after.missing.files.length === 0 &&
-                        after.missing.records.length === 0 &&
+                        after.missing.records.every((record) => record === "index coverage operation is pending") &&
                         Object.values(after.orphaned).every((count) => count === 0);
                     if (contentVerified) {
                         db.run("BEGIN TRANSACTION;");
                         try {
+                            markCoverageIntentComplete(db);
                             if (after.freshness.state === "stale-head" || after.freshness.state === "unknown") {
                                 setMeta(db, "lastIndexedHead", gitHead(resolved) ?? "");
                             }
@@ -14067,26 +15758,60 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
         },
         async index(repoPath, files, clean = false, options) {
             const resolved = path.resolve(repoPath);
-            // Expand `--under` before anything else, so everything downstream sees an
-            // ordinary explicit-file index and no path can route a scoped rebuild
-            // into the destructive full-index branch.
             const scopedUnder = options?.under;
-            if (scopedUnder !== undefined && (!files || files.length === 0)) {
-                const prefix = path
-                    .relative(resolved, path.resolve(resolved, scopedUnder))
+            const normalizeSelector = (file, allowRoot = false) => {
+                const relative = path
+                    .relative(resolved, path.resolve(resolved, file))
                     .split(path.sep)
                     .join("/");
-                if (prefix.startsWith("..") || path.isAbsolute(prefix))
-                    throw new Error(`knodin index --under: ${scopedUnder} is outside the repository`);
-                const collected = collectRepoFilesWithCoverage(resolved);
-                files =
-                    prefix === ""
-                        ? collected.files
-                        : collected.files.filter((file) => file === prefix || file.startsWith(`${prefix}/`));
-                // Failing loudly rather than indexing nothing and reporting success:
-                // a silent no-op here would look identical to a completed rebuild.
-                if (files.length === 0)
-                    throw new Error(`knodin index --under: no indexable files under ${scopedUnder || "the repository root"}`);
+                if (!(allowRoot && relative === "") &&
+                    (!canonicalCoveragePath(relative) || !isIndexablePath(relative)))
+                    throw new Error(`knodin index: selector is invalid or outside the repository: ${file}`);
+                if (relative &&
+                    fs.existsSync(path.join(resolved, relative)) &&
+                    !safeCoveragePath(resolved, relative))
+                    throw new Error(`knodin index: selector follows a symbolic link: ${file}`);
+                return relative;
+            };
+            const prefix = scopedUnder === undefined ? undefined : normalizeSelector(scopedUnder, true);
+            files = files?.length
+                ? [...new Set(files.map((file) => normalizeSelector(file)))]
+                : undefined;
+            // Manifests are resolution inputs, not source coverage selectors. A
+            // config-only request must never fall through to a full repository index.
+            const packageInputs = (files ?? []).filter((file) => path.posix.basename(file) === "package.json" &&
+                !safeCoveragePath(resolved, file)?.isDirectory());
+            if (packageInputs.length) {
+                const packageInputSet = new Set(packageInputs);
+                files = files?.filter((file) => !packageInputSet.has(file));
+                if (!files?.length && prefix === undefined)
+                    throw new Error("knodin index: configuration inputs require source files or --under; no source work requested");
+            }
+            for (const file of files ?? [])
+                if (!isIndexableSourcePath(file) || safeCoveragePath(resolved, file)?.isDirectory())
+                    throw new Error(`knodin index: explicit file selector must name an indexable file: ${file}`);
+            const requestedCoverage = prefix === ""
+                ? null
+                : prefix !== undefined
+                    ? { prefixes: [prefix], files: files ?? [] }
+                    : files
+                        ? { prefixes: [], files }
+                        : null;
+            let promoteScope = false;
+            if (requestedCoverage === null && !openPolicy.databasePath) {
+                const active = dbInstances.get(resolved);
+                const disk = resolveDbPath(resolved);
+                const prior = active ?? (fs.existsSync(disk) ? new Database(disk, { readonly: true }) : null);
+                try {
+                    if (prior) {
+                        const state = coverageForDatabase(prior);
+                        promoteScope = state.intent?.mode === "scoped" || state.origin === "invalid";
+                    }
+                }
+                finally {
+                    if (prior && prior !== active)
+                        prior.close();
+                }
             }
             const indexCoordination = acquireLifecycleCoordination({
                 command: "index",
@@ -14094,8 +15819,8 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                 verificationToken: process.env.KNODIN_UPDATE_VERIFICATION_TOKEN,
             });
             try {
-                if (clean &&
-                    (!files || files.length === 0) &&
+                if (requestedCoverage === null &&
+                    (clean || promoteScope) &&
                     !openPolicy.databasePath &&
                     !process.env.VITEST &&
                     process.env.NODE_ENV !== "test") {
@@ -14153,6 +15878,8 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                         return {
                             indexed: reconciliation.reconciled,
                             unchanged: [],
+                            semanticReadiness: health.semanticReadiness,
+                            indexCoverage: health.indexCoverage,
                             verification: {
                                 status: health.status,
                                 issueCount,
@@ -14192,6 +15919,28 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                         skipContentReconciliation: true,
                         skipFreshnessGuard: true,
                     });
+                    const existingCoverage = coverageForDatabase(db);
+                    const freshCoverage = existingCoverage.origin === "legacy" &&
+                        !getMeta(db, "lastSuccessfulReconciliation") &&
+                        (db.query("SELECT COUNT(*) count FROM index_state").get()
+                            ?.count ?? 0) === 0;
+                    const intent = mergeIndexCoverage(existingCoverage, requestedCoverage, freshCoverage);
+                    writeCoverageIntent(db, resolved, intent);
+                    // Persist the requested semantic policy even if collection fails or
+                    // the prefix is currently empty; recovery must not start inference.
+                    setMeta(db, "semanticDeferred", options?.skipEmbeddings === true ? "1" : "0");
+                    if (prefix !== undefined && prefix !== "") {
+                        const selection = {
+                            version: 1,
+                            mode: "scoped",
+                            revision: intent.revision,
+                            prefixes: [prefix],
+                            files: files ?? [],
+                        };
+                        files = collectRepoFilesWithCoverage(resolved, db, selection).files;
+                        if (files.length === 0)
+                            throw new Error(`knodin index --under: no indexable files under ${scopedUnder}`);
+                    }
                     let completionMessage = "Local graph is current";
                     if (files && files.length > 0) {
                         progress("indexing-files", 0, `Checking ${files.length.toLocaleString()} requested files`, {
@@ -14205,7 +15954,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                                 unchanged.push(relativePath);
                             }
                             else if (fs.existsSync(absPath)) {
-                                await indexFile(absPath, relativePath, repoPath, db);
+                                await explicitPackageInputs.run(packageInputs, () => indexFile(absPath, relativePath, repoPath, db));
                                 recordIndexState(db, repoPath, relativePath);
                             }
                             else if (shouldPurgeMissingFile(db)) {
@@ -14236,9 +15985,10 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                             progress("finalizing", 0, "Refreshing identities and semantic embeddings");
                             persistSymbolIdentities(db, repoPath, indexed);
                             reconcileTypeScriptDi(db, repoPath);
-                            await indexEmbeddings(db, repoPath, progress);
                             indexGeneration++;
                         }
+                        if (!options?.skipEmbeddings)
+                            await indexEmbeddings(db, repoPath, progress);
                         const alreadyCurrent = unchanged.length === 1
                             ? "1 requested file already current"
                             : `${unchanged.length.toLocaleString()} requested files already current`;
@@ -14336,10 +16086,13 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     });
                     const contentVerified = health.coverage.sourceFiles === health.coverage.indexedFiles &&
                         health.missing.files.length === 0 &&
-                        health.missing.records.length === 0 &&
+                        health.missing.records.every((record) => record === "index coverage operation is pending") &&
                         Object.values(health.orphaned).every((count) => count === 0);
                     if (contentVerified &&
-                        (health.freshness.state === "stale-head" || health.freshness.state === "unknown")) {
+                        (coverageForDatabase(db).intentState === "pending" ||
+                            health.freshness.state === "stale-head" ||
+                            health.freshness.state === "unknown")) {
+                        completeCoverageIntent(db);
                         setMeta(db, "lastIndexedHead", gitHead(repoPath) ?? "");
                         setMeta(db, "knodinVersion", KNODIN_VERSION);
                         setMeta(db, "lastSuccessfulReconciliation", new Date().toISOString());
@@ -14394,6 +16147,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     return {
                         indexed,
                         unchanged,
+                        indexCoverage: indexCoverageSummary(coverageForDatabase(db)),
                         // Measured from the graph rather than inferred from the flag: a
                         // run that deferred embeddings and a run that never had any are
                         // the same state to a consumer, and a partially embedded graph is
@@ -14488,6 +16242,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
             };
             const formatPath = makePathFormatter(resolvedRepoPath);
             const retrievalMode = options.retrievalMode ?? "complete";
+            const hasSearchVectors = [...searchSnapshots.values()].some((snapshot) => snapshot.rows.some((row) => row.vector !== null && accepts(row)));
             const normalize = (value) => value.toLocaleLowerCase().replace(/[^a-z0-9]/g, "");
             const hydrateStructural = (matches) => {
                 const fileToCommunityMap = matches.length > 0
@@ -14733,7 +16488,8 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     [...lexicalRanks.values()].some((ranks) => ranks.and.length > 0);
                 if (retrievalMode === "lexical-only" ||
                     retrievalMode === "bounded-graph" ||
-                    structurallySufficient) {
+                    structurallySufficient ||
+                    !hasSearchVectors) {
                     const matches = allRepos.flatMap((repo) => {
                         const snapshot = searchSnapshots.get(repo.path);
                         const ranks = lexicalRanks.get(repo.path);
@@ -14764,6 +16520,19 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     };
                 }
             }
+            // No query vector can retrieve candidates from an empty vector corpus.
+            // Explicit vector-only requests must not trigger model loading either.
+            if (!hasSearchVectors) {
+                return {
+                    results: [],
+                    total: 0,
+                    offset,
+                    limit: maxResults,
+                    hasMore: false,
+                    retrieval: { route: [], embeddingsUsed: false },
+                    semanticReadiness,
+                };
+            }
             // 1. Generate query embedding once
             const queryVec = await generateMeasuredEmbedding(query, true);
             const rankedCandidates = [];
@@ -14988,7 +16757,59 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                 semanticReadiness,
             };
         },
+        async queryClassConsumers(repoPath, request) {
+            const resolved = path.resolve(repoPath);
+            const db = await openDb(resolved);
+            return readClassConsumerPage(db, resolved, request);
+        },
         async query(pattern, target, repoPath, to, limit, depth, detailLevel, selector = {}, impactOptions = {}, options = {}) {
+            if (pattern === "class_consumers") {
+                if (to !== undefined ||
+                    depth !== undefined ||
+                    options.kinds ||
+                    options.direction ||
+                    options.relationKinds ||
+                    options.sort ||
+                    options.topN ||
+                    options.base ||
+                    options.minLines !== undefined ||
+                    options.minComplexity !== undefined)
+                    throw new Error("class_consumers supports only target selectors, testScope/path, limit and typed continuation budgets");
+                const secret = evidenceHandleSecret(path.resolve(repoPath)).secret;
+                const cursor = options.classConsumerContinuation
+                    ? readClassConsumerCursor(options.classConsumerContinuation, secret)
+                    : undefined;
+                const request = {
+                    symbol: target,
+                    selector,
+                    testScope: options.testScope ?? "all",
+                    path: options.path,
+                    limit: limit ?? 100,
+                    ...(cursor
+                        ? {
+                            after: cursor.after,
+                            expectedQueryDigest: cursor.queryDigest,
+                            expectedSnapshotDigest: cursor.snapshotDigest,
+                        }
+                        : {}),
+                };
+                const page = await this.queryClassConsumers(repoPath, request);
+                const envelope = finalizeClassConsumerPage(page, {
+                    secret,
+                    budget: {
+                        bytes: options.classConsumerMaxBytes,
+                        tokens: options.classConsumerMaxTokens,
+                        items: options.classConsumerMaxItems,
+                    },
+                    decorate: (candidate) => ({
+                        ...candidate,
+                        target,
+                        targetResolution: "resolved",
+                        staleness: stalenessFor(repoPath),
+                    }),
+                });
+                return { ...envelope, pattern: "class_consumers", target, targetResolution: "resolved" };
+            }
             if (pattern === "lsp_diagnostics" ||
                 pattern === "lsp_definitions" ||
                 pattern === "lsp_declarations" ||
@@ -15091,6 +16912,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                 const resolved = resolveSymbolRows(db, primary.path, target, selector);
                 if (resolved.ambiguity)
                     return {
+                        indexCoverage: indexCoverageSummary(coverageForDatabase(db)),
                         pattern,
                         target,
                         ...(to ? { to } : {}),
@@ -15139,7 +16961,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
             }
             const finish = (rows, extra = {}) => {
                 for (const row of rows) {
-                    if (row.identity || !row.symbol || !row.file)
+                    if (row.identity || row.callerOrigin || !row.symbol || !row.file)
                         continue;
                     const definition = db
                         .query("SELECT * FROM symbols WHERE name = ? AND filePath = ? LIMIT 1")
@@ -15148,6 +16970,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                         row.identity = symbolIdentity(primary.path, definition);
                 }
                 return {
+                    indexCoverage: indexCoverageSummary(coverageForDatabase(db)),
                     pattern,
                     target,
                     ...(to ? { to } : {}),
@@ -15155,6 +16978,11 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     results: rows.slice(0, cap),
                     ...(rows.length > cap ? { hasMore: true } : {}),
                     ...(targetResolution ? { targetResolution } : {}),
+                    ...((pattern === "callers_of" || pattern === "callees_of") &&
+                        selectedTarget &&
+                        /\.(?:cls|trigger)$/i.test(selectedTarget.filePath)
+                        ? { apexReceiverCapability: apexReceiverCapability(db) }
+                        : {}),
                     ...extra,
                 };
             };
@@ -15335,7 +17163,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                         }
                     }
                     const refs = pattern === "callers_of"
-                        ? findCallersFederated(allRepos, defRepo, targetName, 1, new Set(), defFile, selectedTarget?.identity ?? null)
+                        ? findCallersFederated(allRepos, defRepo, targetName, 1, new Set(), defFile, selectedTarget?.identity ?? null, true)
                         : findCalleesFederated(allRepos, defRepo, targetName, 1, new Set(), defFile, selectedTarget?.identity ?? null);
                     // One row per caller symbol, but carrying every call site it has.
                     // Collapsing to the first line lost the rest and made `count`
@@ -15343,25 +17171,44 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     const byCaller = new Map();
                     const rows = [];
                     let callSiteCount = 0;
+                    let bindingSiteCount = 0;
                     for (const r of refs) {
                         const file = formatPath(r.repoPath || defRepo, r.filePath);
-                        const key = `${r.symbol}|${file}`;
-                        callSiteCount++;
+                        const binding = r.kind === "apex_method";
+                        const key = `${r.symbol}|${file}|${binding ? "binding" : "call"}`;
+                        if (binding)
+                            bindingSiteCount++;
+                        else
+                            callSiteCount++;
                         const existing = byCaller.get(key);
                         if (existing) {
-                            if (r.lineNumber !== undefined && !existing.callSiteLines?.includes(r.lineNumber))
-                                existing.callSiteLines?.push(r.lineNumber);
+                            const lines = binding ? existing.bindingSiteLines : existing.callSiteLines;
+                            if (r.lineNumber !== undefined && !lines?.includes(r.lineNumber))
+                                lines?.push(r.lineNumber);
                             continue;
                         }
-                        const rr = (r.repoPath ? allRepos.find((x) => x.path === r.repoPath) : primary)?.db
-                            .query("SELECT * FROM symbols WHERE name = ? AND filePath = ? LIMIT 1")
-                            .get(r.symbol, r.filePath);
+                        const rr = r.callerOrigin
+                            ? undefined
+                            : (r.repoPath ? allRepos.find((x) => x.path === r.repoPath) : primary)?.db
+                                .query("SELECT * FROM symbols WHERE name = ? AND filePath = ? LIMIT 1")
+                                .get(r.symbol, r.filePath);
                         const row = {
                             symbol: r.symbol,
+                            ...(r.callerOrigin
+                                ? {
+                                    callerOrigin: r.callerOrigin,
+                                    sourceEvidence: "Resolved call site; no named enclosing caller was extracted. Anonymous nesting is not established.",
+                                }
+                                : {}),
                             file,
                             line: r.lineNumber,
                             kind: r.kind ?? "call",
-                            callSiteLines: r.lineNumber !== undefined ? [r.lineNumber] : [],
+                            ...(binding
+                                ? {
+                                    bindingSiteLines: r.lineNumber !== undefined ? [r.lineNumber] : [],
+                                    sourceEvidence: "Static Apex import binding; not evidence that the method executes.",
+                                }
+                                : { callSiteLines: r.lineNumber !== undefined ? [r.lineNumber] : [] }),
                             ...(rr ? { identity: symbolIdentity(r.repoPath || defRepo, rr) } : {}),
                         };
                         byCaller.set(key, row);
@@ -15369,9 +17216,10 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     }
                     for (const row of rows) {
                         row.callSiteLines?.sort((a, b) => a - b);
-                        row.line = row.callSiteLines?.[0] ?? row.line;
+                        row.bindingSiteLines?.sort((a, b) => a - b);
+                        row.line = row.callSiteLines?.[0] ?? row.bindingSiteLines?.[0] ?? row.line;
                     }
-                    return finish(rows, { callSiteCount });
+                    return finish(rows, { callSiteCount, ...(bindingSiteCount ? { bindingSiteCount } : {}) });
                 }
                 case "imports_of": {
                     const stmt = db.query("SELECT DISTINCT toFile, kind FROM dependencies WHERE fromFile = ?");
@@ -15456,16 +17304,188 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     });
                 }
                 case "inheritors_of": {
-                    // Classes that extend or implement the target (kind-tagged references).
-                    const stmt = db.query("SELECT DISTINCT callerSymbol, callerFile, kind, line FROM \"references\" WHERE calleeSymbol = ? AND kind IN ('extends', 'implements') AND callerSymbol IS NOT NULL");
-                    const rows = stmt.all(selectedTarget?.name ?? target).map((r) => ({
-                        symbol: r.callerSymbol,
-                        file: r.callerFile,
-                        kind: r.kind,
-                        line: r.line,
-                    }));
-                    stmt.finalize();
-                    return finish(rows);
+                    db.run("SAVEPOINT apex_heritage_read");
+                    try {
+                        // Unselected heritage queries historically aggregate names across languages.
+                        // An Apex spelling match must not suppress those independent legacy rows.
+                        const aggregate = !selector.file && !selector.identity;
+                        const nonApexRows = db
+                            .query(`SELECT DISTINCT callerSymbol, callerFile, kind, line FROM "references"
+						 WHERE calleeSymbol = ? AND kind IN ('extends', 'implements')
+						 AND callerSymbol IS NOT NULL AND lower(callerFile) NOT LIKE '%.cls'
+						 AND lower(callerFile) NOT LIKE '%.trigger'
+						 ORDER BY callerFile COLLATE BINARY, line, kind COLLATE BINARY, callerSymbol COLLATE BINARY LIMIT ?`)
+                            .all(selectedTarget?.name ?? target, cap + 1)
+                            .map((row) => ({
+                            symbol: row.callerSymbol,
+                            file: row.callerFile,
+                            kind: row.kind,
+                            line: row.line,
+                        }));
+                        const finishHeritage = (apexRows, apex, partial, extra = {}) => {
+                            const includeNonApex = aggregate || apex === "not-selected";
+                            const merged = [...(includeNonApex ? nonApexRows : []), ...apexRows];
+                            const unique = [
+                                ...new Map(merged.map((row) => [
+                                    JSON.stringify([row.file, row.line, row.column ?? null, row.kind, row.symbol]),
+                                    row,
+                                ])).values(),
+                            ];
+                            unique.sort((a, b) => Buffer.compare(Buffer.from(a.file ?? ""), Buffer.from(b.file ?? "")) ||
+                                (a.line ?? 0) - (b.line ?? 0) ||
+                                (a.column ?? 0) - (b.column ?? 0) ||
+                                Buffer.compare(Buffer.from(a.kind ?? ""), Buffer.from(b.kind ?? "")) ||
+                                Buffer.compare(Buffer.from(a.symbol ?? ""), Buffer.from(b.symbol ?? "")));
+                            const truncated = unique.length > cap || extra.truncated === true;
+                            return finish(unique, {
+                                ...extra,
+                                inheritanceQuery: {
+                                    version: 1,
+                                    mode: aggregate || apex === "not-selected" ? "name-aggregate" : "selected-target",
+                                    partial: partial || truncated,
+                                    truncated,
+                                    apex,
+                                },
+                                ...(truncated ? { truncated: true, hasMore: true } : {}),
+                            });
+                        };
+                        const apexCandidates = db
+                            .query("SELECT * FROM symbols WHERE kind IN ('class','interface')")
+                            .all()
+                            .filter((row) => /\.(?:cls|trigger)$/i.test(row.filePath) &&
+                            (!selector.file || selector.file === row.filePath) &&
+                            (!selector.identity ||
+                                symbolIdentityMatches(row.identity ?? "", selector.identity)) &&
+                            (!selector.kind || selector.kind === row.kind) &&
+                            row.name.toLowerCase() === target.split(".").at(-1)?.toLowerCase());
+                        const hasApexInventory = aggregate &&
+                            db
+                                .query("SELECT 1 AS present FROM index_state WHERE lower(filePath) LIKE '%.cls' OR lower(filePath) LIKE '%.trigger' LIMIT 1")
+                                .get() != null;
+                        if (apexCandidates.length ||
+                            selector.file?.match(/\.(?:cls|trigger)$/i) ||
+                            hasApexInventory) {
+                            try {
+                                const targetPage = readClassConsumerPage(db, repoPath, {
+                                    symbol: target,
+                                    selector,
+                                    testScope: "all",
+                                    limit: 1,
+                                });
+                                const symbols = db
+                                    .query("SELECT * FROM symbols WHERE kind IN ('class','interface') AND identity IS NOT NULL")
+                                    .all();
+                                const selected = symbols.find((row) => row.identity === targetPage.targetIdentity);
+                                if (!selected)
+                                    throw new Error("Apex heritage target changed within the read lease");
+                                const stored = db
+                                    .query("SELECT f.* FROM apex_consumer_files f JOIN index_state i ON i.filePath=f.filePath ORDER BY f.filePath COLLATE BINARY")
+                                    .all();
+                                const facts = stored
+                                    .map(readApexConsumerFacts)
+                                    .filter((file) => file !== null);
+                                const catalog = createApexConsumerCatalog(facts);
+                                const cache = new Map(facts.map((file) => [file.file, file]));
+                                const targetOwner = apexConsumerSymbolOwner(db, selected, cache);
+                                const rows = [];
+                                let work = 0;
+                                let partial = facts.length !== stored.length || targetPage.analysis.missingDescriptorFiles > 0;
+                                for (const file of facts) {
+                                    if (file.heritageComplete !== true)
+                                        partial = true;
+                                    if (file.parseState !== "complete" || file.heritage === undefined) {
+                                        partial = true;
+                                        continue;
+                                    }
+                                    for (const edge of file.heritage) {
+                                        if (++work > 50000 || rows.length >= cap + 1) {
+                                            partial = true;
+                                            break;
+                                        }
+                                        const site = {
+                                            version: 1,
+                                            kind: "variable_type",
+                                            qualifiedSpelling: edge.typePath,
+                                            typePath: edge.typePath,
+                                            memberName: null,
+                                            lexicalOwner: edge.ownerPath,
+                                            start: edge.start,
+                                            end: edge.end,
+                                            blockedReason: null,
+                                        };
+                                        const proof = resolveApexClassUses(catalog, { ...file, sites: [site] })[0];
+                                        if (proof.status !== "resolved") {
+                                            partial = true;
+                                            continue;
+                                        }
+                                        if (proof.target?.file !== selected.filePath ||
+                                            proof.target.declaration.ownerPath !== targetOwner)
+                                            continue;
+                                        const owners = symbols.filter((row) => row.filePath === file.file &&
+                                            apexConsumerSymbolOwner(db, row, cache) === edge.ownerPath);
+                                        if (owners.length !== 1) {
+                                            partial = true;
+                                            continue;
+                                        }
+                                        const sourceKind = owners[0].kind;
+                                        const targetKind = proof.target.declaration.kind;
+                                        if (!(edge.kind === "implements"
+                                            ? sourceKind === "class" && targetKind === "interface"
+                                            : (sourceKind === "class" && targetKind === "class") ||
+                                                (sourceKind === "interface" && targetKind === "interface"))) {
+                                            partial = true;
+                                            continue;
+                                        }
+                                        rows.push({
+                                            symbol: owners[0].name,
+                                            identity: owners[0].identity ?? undefined,
+                                            file: file.file,
+                                            kind: edge.kind,
+                                            line: edge.start.line,
+                                            column: edge.start.column,
+                                            heritageEvidence: {
+                                                spelling: edge.typePath,
+                                                targetIdentity: targetPage.targetIdentity,
+                                                grounding: "syntax-resolved",
+                                            },
+                                        });
+                                    }
+                                    if (work > 50000 || rows.length >= cap + 1)
+                                        break;
+                                }
+                                return finishHeritage(rows, "resolved", partial, {
+                                    ...(work > 50000 ? { truncated: true } : {}),
+                                    ...(!aggregate ? { targetResolution: "resolved" } : {}),
+                                    apexHeritageCapability: {
+                                        version: 1,
+                                        partial,
+                                        limitations: [
+                                            "Explicit source heritage resolved to unique indexed Apex type identities; not calls or runtime dispatch.",
+                                            "Malformed, legacy, ambiguous or unsupported heritage is withheld; scope is the local indexed inventory.",
+                                        ],
+                                    },
+                                });
+                            }
+                            catch (error) {
+                                if (!aggregate || !(error instanceof ClassConsumerQueryError))
+                                    throw error;
+                                const state = error.code === "CLASS_CONSUMER_TARGET_AMBIGUOUS"
+                                    ? "ambiguous"
+                                    : error.code === "CLASS_CONSUMER_TARGET_CAPABILITY_MISSING"
+                                        ? "capability-missing"
+                                        : error.code === "CLASS_CONSUMER_TARGET_NOT_FOUND"
+                                            ? "not-found"
+                                            : null;
+                                if (!state)
+                                    throw error;
+                                return finishHeritage([], state, true);
+                            }
+                        }
+                        return finishHeritage([], "not-selected", false);
+                    }
+                    finally {
+                        db.run("RELEASE apex_heritage_read");
+                    }
                 }
                 case "structural_implementations_of": {
                     const stmt = db.query("SELECT DISTINCT callerSymbol, callerFile, kind, line FROM \"references\" WHERE calleeSymbol = ? AND calleeFile = ? AND kind = 'structural_implements' AND callerSymbol IS NOT NULL");
@@ -15710,49 +17730,229 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     // Explicit compatibility mode for PR/change-set impact. It is intentionally
                     // labeled file-level and remains an upstream blast-radius query.
                     if (mode === "file") {
-                        const files = target
-                            .split(",")
-                            .map((f) => f.trim())
-                            .filter(Boolean);
-                        const defined = [];
-                        for (const f of files) {
-                            const stmt = db.query("SELECT name FROM symbols WHERE filePath = ?");
-                            for (const r of stmt.all(f))
-                                defined.push({ name: r.name, file: f });
-                            stmt.finalize();
-                        }
+                        const maxFiles = 256;
+                        const maxEdges = 4096;
+                        const maxSeeds = 32;
+                        const reasons = new Set();
+                        const omissions = new Set();
+                        const requested = [
+                            ...new Set(target
+                                .split(",")
+                                .map((file) => file.trim())
+                                .filter(Boolean)),
+                        ];
+                        if (requested.length > maxSeeds)
+                            reasons.add("seed-limit");
+                        const validFiles = new Map();
+                        const indexedFile = db.query("SELECT 1 AS present FROM index_state WHERE filePath = ?");
+                        const sealed = sealedRepositories.get(resolvedRepoPath);
+                        const canonicalFile = (file) => {
+                            const cached = validFiles.get(file);
+                            if (cached !== undefined)
+                                return cached;
+                            let valid = false;
+                            try {
+                                if (file &&
+                                    file.length <= 1024 &&
+                                    !file.includes("\\") &&
+                                    !file.includes("\0") &&
+                                    !path.posix.isAbsolute(file) &&
+                                    !/^[A-Za-z]:/.test(file) &&
+                                    path.posix.normalize(file) === file &&
+                                    !file.split("/").includes("..") &&
+                                    !file.startsWith(".knodin/") &&
+                                    isIndexableSourcePath(file) &&
+                                    indexedFile.get(file)) {
+                                    if (sealed) {
+                                        valid = !!sealed
+                                            .query("SELECT 1 AS present FROM sealed_file WHERE filePath = ?")
+                                            .get(file);
+                                    }
+                                    else {
+                                        let current = resolvedRepoPath;
+                                        valid = true;
+                                        for (const part of file.split("/")) {
+                                            current = path.join(current, part);
+                                            if (fs.lstatSync(current).isSymbolicLink()) {
+                                                valid = false;
+                                                break;
+                                            }
+                                        }
+                                        if (valid)
+                                            valid = fs.lstatSync(current).isFile();
+                                    }
+                                }
+                            }
+                            catch {
+                                valid = false;
+                            }
+                            validFiles.set(file, valid);
+                            return valid;
+                        };
+                        const files = requested.slice(0, maxSeeds).filter((file) => {
+                            if (canonicalFile(file))
+                                return true;
+                            omissions.add("A requested path is not an exact indexed regular source file; no basename or symbol-name fallback was used.");
+                            return false;
+                        });
+                        const seeds = new Set(files);
                         const seen = new Set();
                         const rows = [];
-                        const stmt = db.query('SELECT DISTINCT callerSymbol, callerFile, line, kind, confidence FROM "references" WHERE calleeSymbol = ? AND calleeFile = ? AND callerSymbol IS NOT NULL');
-                        for (const definition of defined) {
-                            for (const r of stmt.all(definition.name, definition.file)) {
-                                if (files.includes(r.callerFile))
-                                    continue;
-                                const key = `${r.callerSymbol}|${r.callerFile}`;
-                                if (seen.has(key))
-                                    continue;
-                                seen.add(key);
-                                if (!allowed(r.kind, r.confidence, r.callerFile))
-                                    continue;
-                                rows.push({
-                                    symbol: r.callerSymbol,
-                                    file: r.callerFile,
-                                    line: r.line,
-                                    depth: 1,
-                                    impactEdge: {
-                                        from: r.callerSymbol,
-                                        fromFile: r.callerFile,
-                                        to: definition.name,
-                                        toFile: definition.file,
-                                        kind: r.kind,
-                                        confidence: r.confidence,
-                                        line: r.line,
-                                    },
-                                });
+                        let examinedEdges = 0;
+                        const resultFull = () => rows.length >= cap;
+                        const refs = db.query('SELECT r.* FROM "references" r WHERE r.calleeFile = ? AND r.callerSymbol IS NOT NULL AND EXISTS (SELECT 1 FROM symbols s WHERE s.filePath = r.calleeFile AND s.name = r.calleeSymbol) ORDER BY r.id LIMIT ?');
+                        const referenceSafe = apexReferenceReadGuard(db);
+                        try {
+                            // Preserve direct named callers; file dependency rows do not invent symbol identities.
+                            for (const file of files) {
+                                if (examinedEdges >= maxEdges) {
+                                    reasons.add("work-limit");
+                                    break;
+                                }
+                                const candidates = refs.all(file, maxEdges - examinedEdges + 1);
+                                for (const ref of candidates) {
+                                    if (examinedEdges >= maxEdges) {
+                                        reasons.add("work-limit");
+                                        break;
+                                    }
+                                    examinedEdges++;
+                                    if (!ref.callerSymbol ||
+                                        seeds.has(ref.callerFile) ||
+                                        !referenceSafe(ref) ||
+                                        !canonicalFile(ref.callerFile) ||
+                                        !allowed(ref.kind, ref.confidence ?? 1, ref.callerFile))
+                                        continue;
+                                    const key = JSON.stringify([ref.callerSymbol, ref.callerFile]);
+                                    if (seen.has(key))
+                                        continue;
+                                    seen.add(key);
+                                    if (resultFull()) {
+                                        reasons.add("result-limit");
+                                        break;
+                                    }
+                                    rows.push({
+                                        symbol: ref.callerSymbol,
+                                        file: ref.callerFile,
+                                        line: ref.line,
+                                        depth: 1,
+                                        impactEdge: {
+                                            from: ref.callerSymbol,
+                                            fromFile: ref.callerFile,
+                                            to: ref.calleeSymbol,
+                                            toFile: file,
+                                            kind: ref.kind,
+                                            confidence: ref.confidence ?? 1,
+                                            line: ref.line,
+                                        },
+                                    });
+                                }
+                                if (reasons.has("result-limit"))
+                                    break;
                             }
                         }
-                        stmt.finalize();
-                        return decorate(rows, "upstream");
+                        finally {
+                            refs.finalize();
+                        }
+                        const incoming = db.query("SELECT id,fromFile,toFile,kind,confidence,sourceEvidence FROM dependencies WHERE toFile = ? ORDER BY id LIMIT ?");
+                        const visited = new Set(files);
+                        const queue = files.map((file) => ({ file, depth: 0 }));
+                        try {
+                            for (let index = 0; index < queue.length; index++) {
+                                if (reasons.has("result-limit"))
+                                    break;
+                                if (examinedEdges >= maxEdges) {
+                                    reasons.add("work-limit");
+                                    break;
+                                }
+                                const current = queue[index];
+                                for (const edge of incoming.all(current.file, maxEdges - examinedEdges + 1)) {
+                                    if (examinedEdges >= maxEdges) {
+                                        reasons.add("work-limit");
+                                        break;
+                                    }
+                                    examinedEdges++;
+                                    if (!isFileRelationship(edge.kind, edge.fromFile, true) ||
+                                        !isFileRelationship(edge.kind, edge.toFile, false)) {
+                                        omissions.add("Unsupported or non-file dependency kinds were not traversed.");
+                                        continue;
+                                    }
+                                    if (!canonicalFile(edge.fromFile) || !canonicalFile(edge.toFile)) {
+                                        omissions.add("Noncanonical, missing, symlinked, or unindexed dependency endpoints were not traversed.");
+                                        continue;
+                                    }
+                                    const confidence = edge.confidence ?? 1;
+                                    if (!Number.isFinite(confidence) ||
+                                        confidence < 0 ||
+                                        confidence > 1 ||
+                                        !allowed(edge.kind, confidence, edge.fromFile) ||
+                                        visited.has(edge.fromFile))
+                                        continue;
+                                    if (current.depth >= maxDepth) {
+                                        reasons.add("depth-limit");
+                                        continue;
+                                    }
+                                    if (visited.size >= maxFiles) {
+                                        reasons.add("file-limit");
+                                        continue;
+                                    }
+                                    if (resultFull()) {
+                                        reasons.add("result-limit");
+                                        break;
+                                    }
+                                    visited.add(edge.fromFile);
+                                    queue.push({ file: edge.fromFile, depth: current.depth + 1 });
+                                    rows.push({
+                                        file: edge.fromFile,
+                                        kind: edge.kind,
+                                        depth: current.depth + 1,
+                                        ...(edge.sourceEvidence ? { sourceEvidence: edge.sourceEvidence } : {}),
+                                        impactEdge: {
+                                            from: edge.fromFile,
+                                            fromFile: edge.fromFile,
+                                            to: edge.toFile,
+                                            toFile: edge.toFile,
+                                            kind: edge.kind,
+                                            confidence,
+                                            ...(edge.sourceEvidence ? { sourceEvidence: edge.sourceEvidence } : {}),
+                                        },
+                                    });
+                                }
+                            }
+                        }
+                        finally {
+                            incoming.finalize();
+                            indexedFile.finalize();
+                        }
+                        omissions.add("File mode reports direct named callers and bounded upstream file dependencies, not runtime reachability; whole-graph flow/community decoration is omitted.");
+                        return finish(rows, {
+                            ...(reasons.size ? { hasMore: true } : {}),
+                            impact: {
+                                mode,
+                                direction: "upstream",
+                                maxDepth,
+                                heuristic: true,
+                                summary: [
+                                    rows.length,
+                                    "heuristic upstream file-level results; bounded dependency traversal",
+                                    reasons.size ? "(partial)" : "",
+                                ]
+                                    .filter(Boolean)
+                                    .join(" "),
+                                affectedFlows: [],
+                                affectedCommunities: [],
+                                traversal: {
+                                    maxFiles,
+                                    maxEdges,
+                                    maxSeeds,
+                                    visitedFiles: visited.size,
+                                    examinedEdges,
+                                    truncated: reasons.size > 0,
+                                    reasons: [...reasons],
+                                    omissions: [...omissions],
+                                    countIsLowerBound: reasons.size > 0,
+                                },
+                            },
+                        });
                     }
                     if (!selectedTarget)
                         return decorate([], direction);
@@ -16040,10 +18240,31 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                         // not recognized (for example, a dynamic loader). Keep it live.
                         return !matchedTarget;
                     };
-                    const stmt = db.query("SELECT name, kind, filePath, startLine FROM symbols WHERE kind IN ('function', 'class', 'method')");
+                    const hasApexDeclarations = db
+                        .query("PRAGMA table_info(symbols)")
+                        .all()
+                        .some((column) => column.name === "apexDeclaration");
+                    const stmt = db.query(`SELECT id, identity, name, kind, filePath, startLine, ${hasApexDeclarations ? "apexDeclaration" : "NULL AS apexDeclaration"} FROM symbols WHERE kind IN ('function', 'class', 'method')`);
                     let rows = stmt.all();
                     stmt.finalize();
+                    if (target)
+                        rows = rows.filter((row) => row.filePath.includes(target));
+                    const declarations = [];
+                    const unsupportedApexFiles = new Set();
+                    for (const row of rows) {
+                        if (!/\.cls$/i.test(row.filePath))
+                            continue;
+                        const declaration = parseApexDeclaration(row.apexDeclaration);
+                        if (declaration)
+                            declarations.push({ key: String(row.id), file: row.filePath, declaration });
+                        else
+                            unsupportedApexFiles.add(row.filePath);
+                    }
+                    const protectedApexEntries = apexOrgEntryPoints(declarations);
+                    const capability = apexReceiverCapability(db);
                     rows = rows.filter((r) => {
+                        if (protectedApexEntries.has(String(r.id)) || unsupportedApexFiles.has(r.filePath))
+                            return false;
                         if (r.kind === "variable")
                             return false;
                         if (r.name.length <= 3)
@@ -16082,6 +18303,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                         file: r.filePath,
                         line: r.startLine,
                         heuristic: true,
+                        identity: r.identity ?? undefined,
                         sourceEvidence: "No statically resolved references; runtime dispatch, reflection, aliases, and indirect exports remain unresolved.",
                         drillDown: {
                             operation: "query",
@@ -16090,7 +18312,21 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                             file: r.filePath,
                             limit: 25,
                         },
-                    })));
+                    })), {
+                        deadCodeAnalysis: {
+                            protectedApexEntries: protectedApexEntries.size,
+                            unsupportedApexFiles: unsupportedApexFiles.size,
+                            repositoryMissingApexCapabilityFiles: capability.missingFiles,
+                            partial: unsupportedApexFiles.size > 0 || capability.partial,
+                            limitations: [
+                                "Org-facing Apex declarations are excluded; this does not prove runtime use or root reachability. Global visibility alone is not an exemption.",
+                                "Remaining results are static candidates, not safe-to-delete findings; dead chains and dynamic dispatch are not established.",
+                                ...(unsupportedApexFiles.size > 0 || capability.partial
+                                    ? [capability.repair]
+                                    : []),
+                            ],
+                        },
+                    });
                 }
                 case "cross_substrate_path": {
                     const unsupportedCrossings = [
@@ -16147,7 +18383,10 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                             ...flowSource.matchAll(/<actionCalls>([\s\S]*?)<\/actionCalls>/g),
                         ]
                             .filter((match) => /<actionType>apex<\/actionType>/.test(match[1]))
-                            .filter((match) => staticXmlTagValues(match[1], "actionName").some((entry) => entry.value === actionName));
+                            .filter((match) => staticXmlTagValues(match[1], "actionName").some((entry) => entry.value === actionName ||
+                            (entry.value === className &&
+                                findUniqueInvocableApexMethod(className, undefined, primary.path)?.method ===
+                                    destination.selected?.name)));
                         if (matchingActions.length === 1)
                             flowEvidence = matchingActions[0][0].trim();
                     }
@@ -17642,6 +19881,8 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
             }
             for (const repo of releasable) {
                 const db = dbInstances.get(repo);
+                if (db)
+                    apexConsumerValidationMemo.delete(db);
                 if (db)
                     db.close();
                 dbInstances.delete(repo);
@@ -17650,6 +19891,8 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
             }
             for (const key of explicitDatabaseKeys) {
                 const db = dbInstances.get(key);
+                if (db)
+                    apexConsumerValidationMemo.delete(db);
                 if (db)
                     db.close();
                 dbInstances.delete(key);