homegraph 1.4.1 → 1.5.0

package/dist/resolution/index.js

@@ -47,6 +47,7 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const name_matcher_1 = require("./name-matcher");
 const import_resolver_1 = require("./import-resolver");
+const resolver_pool_1 = require("./resolver-pool");
 const frameworks_1 = require("./frameworks");
 const callback_synthesizer_1 = require("./callback-synthesizer");
 const cooperative_yield_1 = require("./cooperative-yield");
@@ -244,6 +245,32 @@ class ReferenceResolver {
     qualifiedNameCache; // qualified_name → nodes cache
     fileLinesCache; // file → split lines cache
     methodMatchCache; // lang\0Type::method → matching method nodes
+    // Per-(language, methodName) owner index for getMethodMatches: buckets a
+    // method name's candidates by their qualifiedName's last two segments so a
+    // (type, method) query is a lookup instead of an O(candidates) filter per
+    // methodMatchCache miss. Derived purely from node rows (stable through the
+    // resolution loop, same window nameCache relies on); dropped in clearCaches.
+    methodOwnerIndexCache = new Map();
+    // Generation-tagged memo for getSupertypes. Supertype edges GROW during the
+    // resolution loop (batch k persists its implements/extends edges BEFORE
+    // batch k+1 fans out — the #1320 ordering), so a plain cache would freeze an
+    // early batch's emptier answer and change later batches' outcomes. Within
+    // one batch the edge state is fixed by that same ordering, so entries are
+    // tagged with a generation that advances at every batch entry point
+    // (resolveBatchYielding / resolveListForAdmission) — a stale-gen entry is
+    // recomputed, making the memo behavior-identical to no memo at every point
+    // in time. On the Swift compiler the unmemoized walk ran 971k times for
+    // 565s of combined worker time (~581µs each, recursion-multiplied).
+    supertypeGen = 0;
+    supertypeMemo = new Map();
+    /** Invalidate the getSupertypes memo — call when resolved edges may have advanced. */
+    advanceSupertypeGeneration() {
+        this.supertypeGen++;
+        // Lazy invalidation via the gen tag; bound the map so a long run over many
+        // batches doesn't accrete dead entries.
+        if (this.supertypeMemo.size > 50_000)
+            this.supertypeMemo.clear();
+    }
     // Node kinds are a small fixed set (~24), so this is a plain Map, not an LRU.
     // getNodesByKind returns the FULL node list for a kind; it was previously
     // uncached — a per-ref `SELECT * FROM nodes WHERE kind=?` + row-mapping. Called
@@ -372,10 +399,19 @@ class ReferenceResolver {
         this.qualifiedNameCache.clear();
         this.fileLinesCache.clear();
         this.methodMatchCache.clear();
+        this.methodOwnerIndexCache.clear();
+        this.supertypeMemo.clear();
+        this.supertypeGen++;
         this.nodesByKindCache.clear();
         this.knownNames = null;
         this.knownFiles = null;
         this.cachesWarmed = false;
+        // The import-resolver's and name-matcher's per-context memos assume the
+        // same stable window as the caches above — drop them together.
+        if (this.context) {
+            (0, import_resolver_1.clearImportResolverMemos)(this.context);
+            (0, name_matcher_1.clearNameMatcherMemos)(this.context);
+        }
     }
     /** `readFile` through the LRU content cache (null = read failed, also cached). */
     readFileCached(filePath) {
@@ -424,15 +460,61 @@ class ReferenceResolver {
                     this.nameCache.set(methodName, candidates);
                 }
                 const want = `${typeName}::${methodName}`;
-                const matches = [];
-                for (const m of candidates) {
-                    if (m.kind !== 'method')
-                        continue;
-                    if (m.language !== language)
-                        continue;
-                    const qn = m.qualifiedName;
-                    if (qn === want || qn.endsWith(`::${want}`))
-                        matches.push(m);
+                let matches;
+                if (typeName.includes('::') || methodName.includes(':')) {
+                    // Legacy linear filter for the shapes the owner index below can't
+                    // key exactly: a multi-segment typeName (the endsWith test then
+                    // spans more than two `::` segments) and ObjC selectors (whose
+                    // single/empty-keyword colons defeat the segment split). Tiny
+                    // populations; the per-key memo above still amortizes them.
+                    matches = [];
+                    for (const m of candidates) {
+                        if (m.kind !== 'method')
+                            continue;
+                        if (m.language !== language)
+                            continue;
+                        const qn = m.qualifiedName;
+                        if (qn === want || qn.endsWith(`::${want}`))
+                            matches.push(m);
+                    }
+                }
+                else {
+                    // Owner index: the linear filter above is O(all same-named methods)
+                    // per CACHE MISS, and on overload-heavy landscapes the distinct
+                    // (type, method) key space is so large the per-key memo never
+                    // amortizes — Swift's `init` has tens of thousands of candidates
+                    // and the compiler repo measured 732µs per failing call, most of it
+                    // this scan (re-entered once per supertype recursion level, too).
+                    // Bucket each (language, methodName)'s candidates ONCE by the
+                    // qualifiedName's last two `::` segments — exactly the span the
+                    // `qn === want || qn.endsWith('::' + want)` predicate tests for a
+                    // segment-clean typeName — then every query is a map lookup.
+                    // Bucket insertion follows candidate order, so each bucket is
+                    // byte-identical to what the linear filter produced.
+                    const idxKey = `${language} ${methodName}`;
+                    let ownerIndex = this.methodOwnerIndexCache.get(idxKey);
+                    if (!ownerIndex) {
+                        ownerIndex = new Map();
+                        for (const m of candidates) {
+                            if (m.kind !== 'method')
+                                continue;
+                            if (m.language !== language)
+                                continue;
+                            const qn = m.qualifiedName;
+                            const i2 = qn.lastIndexOf('::');
+                            if (i2 < 0)
+                                continue; // single-segment qn can never match `T::m`
+                            const i1 = qn.lastIndexOf('::', i2 - 1);
+                            const bucketKey = i1 < 0 ? qn : qn.slice(i1 + 2);
+                            const bucket = ownerIndex.get(bucketKey);
+                            if (bucket)
+                                bucket.push(m);
+                            else
+                                ownerIndex.set(bucketKey, [m]);
+                        }
+                        this.methodOwnerIndexCache.set(idxKey, ownerIndex);
+                    }
+                    matches = ownerIndex.get(want) ?? [];
                 }
                 this.methodMatchCache.set(key, matches);
                 return matches;
@@ -524,20 +606,34 @@ class ReferenceResolver {
                 // Matching by simple name (not id) reconciles a type declared in one node
                 // (`KF::Builder`) with conformance declared in a separate extension node
                 // (`KF.Builder: KFOptionSetter`) — both have name `Builder`.
+                // Memoized per batch generation (see supertypeMemo): within a batch the
+                // edge state is fixed, and the conformance walk re-queries the same
+                // popular supertypes (Swift stdlib protocols especially) thousands of
+                // times per batch.
+                const memoKey = `${language} ${typeName}`;
+                const hit = this.supertypeMemo.get(memoKey);
+                if (hit && hit.gen === this.supertypeGen)
+                    return hit.supers;
                 const typeNodes = this.context
                     .getNodesByName(typeName)
                     .filter((n) => SUPERTYPE_BEARING_KINDS.has(n.kind) && n.language === language);
-                if (typeNodes.length === 0)
-                    return [];
-                const supertypes = new Set();
-                for (const tn of typeNodes) {
-                    for (const edge of this.queries.getOutgoingEdges(tn.id, ['implements', 'extends'])) {
-                        const target = this.queries.getNodeById(edge.target);
-                        if (target?.name && target.name !== typeName)
-                            supertypes.add(target.name);
+                let supers;
+                if (typeNodes.length === 0) {
+                    supers = [];
+                }
+                else {
+                    const supertypes = new Set();
+                    for (const tn of typeNodes) {
+                        for (const edge of this.queries.getOutgoingEdges(tn.id, ['implements', 'extends'])) {
+                            const target = this.queries.getNodeById(edge.target);
+                            if (target?.name && target.name !== typeName)
+                                supertypes.add(target.name);
+                        }
                     }
+                    supers = [...supertypes];
                 }
-                return [...supertypes];
+                this.supertypeMemo.set(memoKey, { gen: this.supertypeGen, supers });
+                return supers;
             },
             getImportMappings: (filePath, language) => {
                 const cacheKey = filePath;
@@ -615,12 +711,13 @@ class ReferenceResolver {
             column: ref.column,
             filePath: ref.filePath || this.getFilePathFromNodeId(ref.fromNodeId),
             language: ref.language || this.getLanguageFromNodeId(ref.fromNodeId),
+            rowId: ref.rowId,
         }));
         const total = refs.length;
         let lastReportedPercent = -1;
         for (let i = 0; i < refs.length; i++) {
             const ref = refs[i]; // Array index is guaranteed to be in bounds
-            const result = this.resolveOne(ref);
+            const result = this.resolveOneTimed(ref);
             if (result) {
                 resolved.push(result);
                 byMethod[result.resolvedBy] = (byMethod[result.resolvedBy] || 0) + 1;
@@ -782,10 +879,14 @@ class ReferenceResolver {
         const existenceName = ref.language === 'arkts' && ref.referenceName.startsWith('.')
             ? ref.referenceName.slice(1)
             : ref.referenceName;
-        if (!(0, import_resolver_1.isNixPathImportRef)(ref) &&
-            !this.hasAnyPossibleMatch(existenceName) &&
-            !this.matchesAnyImport(ref) &&
-            !this.frameworks.some((f) => f.claimsReference?.(ref.referenceName))) {
+        const tPre = this.profileStages ? process.hrtime.bigint() : 0n;
+        const preFilterPass = (0, import_resolver_1.isNixPathImportRef)(ref) ||
+            this.hasAnyPossibleMatch(existenceName) ||
+            this.matchesAnyImport(ref) ||
+            this.frameworks.some((f) => f.claimsReference?.(ref.referenceName));
+        if (this.profileStages)
+            this.stageAdd('preFilter', ref, preFilterPass, tPre);
+        if (!preFilterPass) {
             return null;
         }
         // Function-as-value refs (#756) get a dedicated, strictly-gated path:
@@ -811,7 +912,10 @@ class ReferenceResolver {
         // JVM FQN imports skip framework/name-matcher: `import com.example.Bar`
         // resolves directly through the qualifiedName index, which is unambiguous
         // even when several `Bar` classes exist in different packages.
+        const tJvm = this.profileStages ? process.hrtime.bigint() : 0n;
         const jvmImport = (0, import_resolver_1.resolveJvmImport)(ref, this.context);
+        if (this.profileStages)
+            this.stageAdd('jvmImport', ref, !!jvmImport, tJvm);
         if (jvmImport)
             return jvmImport;
         // Razor/Blazor: a markup or `@code` type ref resolves through the file's
@@ -830,16 +934,49 @@ class ReferenceResolver {
         // JS → native `calls`) — `gateFrameworkLanguage` only drops a type/import
         // edge between two KNOWN families (see its doc), never a `calls` bridge or
         // a config↔code edge.
+        const tFw = this.profileStages ? process.hrtime.bigint() : 0n;
+        let fwEarly = null;
         for (const framework of this.frameworks) {
             const result = this.gateFrameworkLanguage(framework.resolve(ref, this.context), ref);
             if (result) {
-                if (result.confidence >= 0.9)
-                    return result; // High confidence, return immediately
+                if (result.confidence >= 0.9) {
+                    fwEarly = result; // High confidence, return immediately (below)
+                    break;
+                }
                 candidates.push(result);
             }
         }
+        if (this.profileStages)
+            this.stageAdd('frameworks', ref, fwEarly !== null, tFw);
+        if (fwEarly)
+            return fwEarly;
         // Strategy 2: Try import-based resolution
-        const importResult = this.gateLanguage((0, import_resolver_1.resolveViaImport)(ref, this.context), ref);
+        const tImp = this.profileStages ? process.hrtime.bigint() : 0n;
+        let importResult = this.gateLanguage((0, import_resolver_1.resolveViaImport)(ref, this.context), ref);
+        // ArkTS:
+        //  - `instantiates`: never via import — `import { Foo }` + a constructor
+        //    seed would mint a `new Foo` edge for every false CFG constructor in
+        //    that file (99k instantiates on scene_board). Same-file / unique-class
+        //    exact-match in matchReference only.
+        //  - dotted `Class.method`: import → static member (cross-module path;
+        //    Strategy 1 is same-file only).
+        //  - bare calls: only when the import local maps to a function/method.
+        if (importResult &&
+            ref.language === 'arkts' &&
+            (ref.referenceKind === 'calls' || ref.referenceKind === 'instantiates')) {
+            if (ref.referenceKind === 'instantiates') {
+                importResult = null;
+            }
+            else {
+                const target = this.queries.getNodeById(importResult.targetNodeId);
+                const ok = target &&
+                    (target.kind === 'function' || target.kind === 'method');
+                if (!ok)
+                    importResult = null;
+            }
+        }
+        if (this.profileStages)
+            this.stageAdd('viaImport', ref, !!importResult, tImp);
         if (importResult) {
             if (importResult.confidence >= 0.9)
                 return importResult;
@@ -861,7 +998,10 @@ class ReferenceResolver {
                 : null;
         }
         // Strategy 3: Try name matching
+        const tName = this.profileStages ? process.hrtime.bigint() : 0n;
         let nameResult = this.gateLanguage((0, name_matcher_1.matchReference)(ref, this.context), ref);
+        if (this.profileStages)
+            this.stageAdd('nameMatch', ref, !!nameResult, tName);
         // Nix has no ambient cross-file namespace — a callee binds lexically
         // (same file) or through explicit import/callPackage wiring (the import
         // path above). A cross-file name match is wrong by construction: every
@@ -971,6 +1111,52 @@ class ReferenceResolver {
             };
         });
     }
+    /**
+     * Split resolved refs into rows deletable by id and hand-built refs that
+     * must fall back to the key-tuple delete. Rows loaded from the database
+     * carry their row id and are deleted by exactly that id; the key tuple
+     * omits line/col, so it also removes SIBLING rows — the same caller calling
+     * the same callee at other lines — that a later batch hadn't attempted yet:
+     * when a batch boundary split a caller's same-named call sites, the later
+     * sites' edges were silently never created (#1269).
+     */
+    static partitionResolvedCleanup(resolved) {
+        const rowIds = [];
+        const legacyKeys = [];
+        for (const r of resolved) {
+            if (r.original.rowId != null)
+                rowIds.push(r.original.rowId);
+            else
+                legacyKeys.push({
+                    fromNodeId: r.original.fromNodeId,
+                    referenceName: r.original.referenceName,
+                    referenceKind: r.original.referenceKind,
+                });
+        }
+        return { rowIds, legacyKeys };
+    }
+    /**
+     * Same row-id precision for parking unresolvable refs as status='failed'
+     * (#1240): the key-tuple fallback would flip same-key sibling rows in later
+     * batches to 'failed' before they were ever attempted, and resolution
+     * outcome can differ per call site (receiver-type inference reads the
+     * ref's line), so a sibling must not inherit this row's failure (#1269).
+     */
+    static partitionFailedCleanup(unresolved) {
+        const byRowId = [];
+        const legacyKeys = [];
+        for (const r of unresolved) {
+            if (r.rowId != null)
+                byRowId.push({ rowId: r.rowId, referenceName: r.referenceName });
+            else
+                legacyKeys.push({
+                    fromNodeId: r.fromNodeId,
+                    referenceName: r.referenceName,
+                    referenceKind: r.referenceKind,
+                });
+        }
+        return { byRowId, legacyKeys };
+    }
     /**
      * Resolve and persist edges to database
      */
@@ -984,11 +1170,9 @@ class ReferenceResolver {
         }
         // Clean up resolved refs from unresolved_refs table so metrics are accurate
         if (result.resolved.length > 0) {
-            this.queries.deleteSpecificResolvedReferences(result.resolved.map((r) => ({
-                fromNodeId: r.original.fromNodeId,
-                referenceName: r.original.referenceName,
-                referenceKind: r.original.referenceKind,
-            })));
+            const { rowIds, legacyKeys } = ReferenceResolver.partitionResolvedCleanup(result.resolved);
+            this.queries.deleteReferencesByRowIds(rowIds);
+            this.queries.deleteSpecificResolvedReferences(legacyKeys);
         }
         // Park unresolvable refs as status='failed' — parity with
         // resolveAndPersistBatched. Deleting them was wrong (#1240): a ref whose
@@ -1000,11 +1184,9 @@ class ReferenceResolver {
         // is still 'pending', so any pending row at rest belongs to an
         // interrupted run and the sweep can key off the pending count.
         if (result.unresolved.length > 0) {
-            this.queries.markReferencesFailed(result.unresolved.map((r) => ({
-                fromNodeId: r.fromNodeId,
-                referenceName: r.referenceName,
-                referenceKind: r.referenceKind,
-            })));
+            const { byRowId, legacyKeys } = ReferenceResolver.partitionFailedCleanup(result.unresolved);
+            this.queries.markReferencesFailedByRowIds(byRowId);
+            this.queries.markReferencesFailed(legacyKeys);
         }
         return result;
     }
@@ -1026,22 +1208,22 @@ class ReferenceResolver {
             this.queries.insertEdges(edges.slice(i, i + PERSIST_CHUNK));
             await maybeYield();
         }
-        const resolvedKeys = result.resolved.map((r) => ({
-            fromNodeId: r.original.fromNodeId,
-            referenceName: r.original.referenceName,
-            referenceKind: r.original.referenceKind,
-        }));
-        for (let i = 0; i < resolvedKeys.length; i += PERSIST_CHUNK) {
-            this.queries.deleteSpecificResolvedReferences(resolvedKeys.slice(i, i + PERSIST_CHUNK));
+        const resolvedCleanup = ReferenceResolver.partitionResolvedCleanup(result.resolved);
+        for (let i = 0; i < resolvedCleanup.rowIds.length; i += PERSIST_CHUNK) {
+            this.queries.deleteReferencesByRowIds(resolvedCleanup.rowIds.slice(i, i + PERSIST_CHUNK));
             await maybeYield();
         }
-        const unresolvedKeys = result.unresolved.map((r) => ({
-            fromNodeId: r.fromNodeId,
-            referenceName: r.referenceName,
-            referenceKind: r.referenceKind,
-        }));
-        for (let i = 0; i < unresolvedKeys.length; i += PERSIST_CHUNK) {
-            this.queries.markReferencesFailed(unresolvedKeys.slice(i, i + PERSIST_CHUNK));
+        for (let i = 0; i < resolvedCleanup.legacyKeys.length; i += PERSIST_CHUNK) {
+            this.queries.deleteSpecificResolvedReferences(resolvedCleanup.legacyKeys.slice(i, i + PERSIST_CHUNK));
+            await maybeYield();
+        }
+        const failedCleanup = ReferenceResolver.partitionFailedCleanup(result.unresolved);
+        for (let i = 0; i < failedCleanup.byRowId.length; i += PERSIST_CHUNK) {
+            this.queries.markReferencesFailedByRowIds(failedCleanup.byRowId.slice(i, i + PERSIST_CHUNK));
+            await maybeYield();
+        }
+        for (let i = 0; i < failedCleanup.legacyKeys.length; i += PERSIST_CHUNK) {
+            this.queries.markReferencesFailed(failedCleanup.legacyKeys.slice(i, i + PERSIST_CHUNK));
             await maybeYield();
         }
         return result;
@@ -1112,6 +1294,7 @@ class ReferenceResolver {
      */
     async resolveBatchYielding(batch, maybeYield) {
         this.warmCaches();
+        this.advanceSupertypeGeneration();
         const resolved = [];
         const unresolved = [];
         const byMethod = {};
@@ -1124,8 +1307,9 @@ class ReferenceResolver {
                 column: raw.column,
                 filePath: raw.filePath || this.getFilePathFromNodeId(raw.fromNodeId),
                 language: raw.language || this.getLanguageFromNodeId(raw.fromNodeId),
+                rowId: raw.rowId,
             };
-            const result = this.resolveOne(ref);
+            const result = this.resolveOneTimed(ref);
             if (result) {
                 resolved.push(result);
                 byMethod[result.resolvedBy] = (byMethod[result.resolvedBy] || 0) + 1;
@@ -1133,7 +1317,11 @@ class ReferenceResolver {
             else {
                 unresolved.push(ref);
             }
-            await maybeYield();
+            // Fast-path the per-ref yield check: awaiting the async no-op costs a
+            // microtask hop per ref, which dominates at ~10⁵ refs (see MaybeYield).
+            const y = maybeYield();
+            if (y)
+                await y;
         }
         return {
             resolved,
@@ -1146,12 +1334,144 @@ class ReferenceResolver {
             },
         };
     }
+    /**
+     * Resolve a list of refs and return everything the ADMISSION side needs to
+     * persist the outcome: resolutions, failures, the deferred post-pass refs
+     * this run produced (drained, so the caller owns routing them), and stats.
+     * This is the resolver-worker entry point — it runs the exact per-ref loop
+     * of resolveBatchYielding, minus the main-thread yields (worker threads have
+     * no watchdog heartbeat to starve). Results are in input order.
+     */
+    /**
+     * HOMEGRAPH_RESOLVE_PROFILE=1: per-outcome wall-clock histogram of
+     * resolveOne, keyed by the winning strategy (`resolvedBy`) or
+     * `fail:<referenceKind>` — the §7a.2 "profile the per-ref path" probe. The
+     * kernel-scale batch loop is ~430s and CORE-INVARIANT (835.9s pooled-4-on-8
+     * ≈ 812.5s sequential-on-2 for the whole superphase), so the next lever is
+     * which CLASS of ref the time belongs to, not more parallelism. Off by
+     * default: the hrtime pair costs ~100ns/ref only when the env is set.
+     */
+    resolveProfile = process.env.HOMEGRAPH_RESOLVE_PROFILE ? new Map() : null;
+    /**
+     * HOMEGRAPH_RESOLVE_PROFILE=2 additionally attributes time to the
+     * STRATEGIES inside resolveOne (`stage:<name>|<refKind>|hit/miss` rows in
+     * the same histogram) — i.e. WHICH machinery a failing class of refs pays
+     * for, not just that it fails. =1 keeps the per-outcome rows only.
+     */
+    profileStages = process.env.HOMEGRAPH_RESOLVE_PROFILE === '2';
+    stageAdd(stage, ref, hit, t0) {
+        if (!this.resolveProfile)
+            return;
+        const dt = process.hrtime.bigint() - t0;
+        const key = `stage:${stage}|${ref.referenceKind}|${hit ? 'hit' : 'miss'}`;
+        const slot = this.resolveProfile.get(key);
+        if (slot) {
+            slot.n++;
+            slot.ns += dt;
+        }
+        else {
+            this.resolveProfile.set(key, { n: 1, ns: dt });
+        }
+    }
+    resolveOneTimed(ref) {
+        if (!this.resolveProfile)
+            return this.resolveOne(ref);
+        const t0 = process.hrtime.bigint();
+        const result = this.resolveOne(ref);
+        const dt = process.hrtime.bigint() - t0;
+        const key = result ? result.resolvedBy : `fail:${ref.referenceKind}`;
+        const slot = this.resolveProfile.get(key);
+        if (slot) {
+            slot.n++;
+            slot.ns += dt;
+        }
+        else {
+            this.resolveProfile.set(key, { n: 1, ns: dt });
+        }
+        return result;
+    }
+    /** Dump the HOMEGRAPH_RESOLVE_PROFILE histogram to stderr (no-op when off). */
+    dumpResolveProfile(label) {
+        if (!this.resolveProfile || this.resolveProfile.size === 0)
+            return;
+        const rows = [...this.resolveProfile.entries()]
+            .map(([k, v]) => ({ k, n: v.n, ms: Number(v.ns / 1000000n) }))
+            .sort((a, b) => b.ms - a.ms);
+        for (const r of rows) {
+            console.error(`[resolve-profile] ${label} ${r.k}: n=${r.n} total=${(r.ms / 1000).toFixed(1)}s avg=${((r.ms * 1000) / Math.max(1, r.n)).toFixed(0)}µs`);
+        }
+        // =2 only: this thread's matchReference sub-stage table rides along.
+        (0, name_matcher_1.dumpNameMatcherProfile)(label);
+    }
+    resolveListForAdmission(refs) {
+        this.warmCaches();
+        this.advanceSupertypeGeneration();
+        const resolved = [];
+        const unresolved = [];
+        const byMethod = {};
+        for (const raw of refs) {
+            const ref = {
+                fromNodeId: raw.fromNodeId,
+                referenceName: raw.referenceName,
+                referenceKind: raw.referenceKind,
+                line: raw.line,
+                column: raw.column,
+                filePath: raw.filePath || this.getFilePathFromNodeId(raw.fromNodeId),
+                language: raw.language || this.getLanguageFromNodeId(raw.fromNodeId),
+                rowId: raw.rowId,
+            };
+            const result = this.resolveOneTimed(ref);
+            if (result) {
+                resolved.push(result);
+                byMethod[result.resolvedBy] = (byMethod[result.resolvedBy] || 0) + 1;
+            }
+            else {
+                unresolved.push(ref);
+            }
+        }
+        return {
+            resolved,
+            unresolved,
+            deferredChain: this.deferredChainRefs.splice(0),
+            deferredThisMember: this.deferredThisMemberRefs.splice(0),
+            byMethod,
+        };
+    }
+    /**
+     * The resolver's live ResolutionContext — resolver-pool workers use it to
+     * run synthesis passes against their own read-only connection.
+     */
+    getResolutionContext() {
+        return this.context;
+    }
+    /**
+     * Re-queue deferred post-pass refs produced by resolver workers, preserving
+     * their admission order so resolveChainedCallsViaConformance /
+     * resolveDeferredThisMemberRefs process them exactly as the sequential path
+     * would have.
+     */
+    appendDeferredFromWorkers(deferredChain, deferredThisMember) {
+        this.deferredChainRefs.push(...deferredChain);
+        this.deferredThisMemberRefs.push(...deferredThisMember);
+    }
     /**
      * Resolve and persist in batches to keep memory bounded.
      * Processes unresolved references in chunks, persisting edges and cleaning
      * up resolved refs after each batch to avoid accumulating large arrays.
      */
-    async resolveAndPersistBatched(onProgress, batchSize = 5000, onSynthesisProgress) {
+    async resolveAndPersistBatched(onProgress, batchSize = 5000, onSynthesisProgress, 
+    // When provided, big batches fan out across a read-only resolver-worker
+    // pool with results admitted in canonical order (see resolver-pool.ts).
+    // Sequential fallback on any pool failure. HOMEGRAPH_NO_PARALLEL_RESOLVE=1
+    // disables entirely. bulkEdgeLoad hooks (when provided) bracket the batch
+    // loop with drop/recreate of the non-unique edge indexes on big runs —
+    // see DatabaseConnection.beginBulkEdgeLoad. backpressure (when provided)
+    // is the WAL valve's writer-side backstop (WalCheckpointValve.backpressure):
+    // called at pool-idle boundaries so a full backfill can actually complete —
+    // the valve's timer-driven passive passes stay perpetually partial against
+    // the pool's continuous reads, which is how a kernel-scale resolution grew
+    // a 22GB WAL on a 4.6GB DB (migration plan §7a.1).
+    parallel) {
         // Resolution runs on the indexer's MAIN thread, and the #850 liveness
         // watchdog SIGKILLs a process whose event loop stalls past its window (60s
         // by default). A single dense batch's resolveAll — or the synthesis pass
@@ -1159,6 +1479,19 @@ class ReferenceResolver {
         // (#1091). A shared yielder lets both give the watchdog heartbeat a regular
         // window to fire; see ./cooperative-yield.
         const maybeYield = (0, cooperative_yield_1.createYielder)();
+        if (process.env.HOMEGRAPH_SYNTH_TIMINGS) {
+            console.error(`[pool-timing] backpressure hook: ${parallel?.backpressure ? 'present' : 'absent'}`);
+        }
+        // HOMEGRAPH_RESOLVE_PROFILE loop-stage attribution: the §7a.2 kernel-scale
+        // histogram showed resolveOne owns only ~93s of the ~436s batch loop —
+        // these counters name where the other ~340s goes (reads, edge build+insert,
+        // deletes/marks, the per-batch count guard).
+        const loopProf = process.env.HOMEGRAPH_RESOLVE_PROFILE
+            ? { read: 0, settle: 0, backpressure: 0, recycle: 0, createEdges: 0, insertEdges: 0, deletes: 0, marks: 0, countGuard: 0 }
+            : null;
+        const lp = (k, t0) => { if (loopProf)
+            loopProf[k] = (loopProf[k] ?? 0) + (Date.now() - t0); };
+        let tLp = 0;
         await this.warmCachesYielding(maybeYield);
         const total = this.queries.getUnresolvedReferencesCount();
         let processed = 0;
@@ -1168,95 +1501,370 @@ class ReferenceResolver {
             unresolved: 0,
             byMethod: {},
         };
-        // Process in batches. We always read from offset 0 because every ref the
-        // batch processed leaves the pending set (resolved rows are deleted,
+        // Parallel pool, started immediately but never awaited up front: early
+        // batches run sequentially while the workers boot (module load + readonly
+        // DB open + framework detect + cache warm ≈ hundreds of ms), and the loop
+        // switches to fan-out the moment the pool reports ready — so pool boot
+        // costs zero wall-clock. Any failure downgrades to sequential permanently.
+        let pool = null;
+        let poolReady = false;
+        // True once pool creation has been attempted by EITHER engage site (the
+        // up-front ref-count gate or the adaptive projection below) — a pool that
+        // failed or was destroyed must stay down (downgrade is permanent), and
+        // tryCreate's sizing probes shouldn't re-run every batch on hosts that
+        // declined.
+        let poolEngageTried = false;
+        const createPool = (t0, why) => {
+            poolEngageTried = true;
+            if (!parallel)
+                return null;
+            const p = resolver_pool_1.ResolverPool.tryCreate(parallel.dbPath, this.projectRoot);
+            p?.ready().then(() => {
+                poolReady = true;
+                if (process.env.HOMEGRAPH_SYNTH_TIMINGS)
+                    console.error(`[pool-timing] pool ready after ${Date.now() - t0}ms (${why})`);
+            }, () => {
+                void p.destroy().catch(() => undefined);
+                if (pool === p)
+                    pool = null;
+            });
+            return p;
+        };
+        if (parallel && total >= (0, resolver_pool_1.minRefsForPool)()) {
+            pool = createPool(Date.now(), 'ref-count');
+        }
+        // Adaptive engagement bar (see the batch-loop hook): projected remaining
+        // sequential settle above this boots the pool mid-loop. Boot is async and
+        // fan-out waits for ready, so a marginal engage costs background boot
+        // only; the bar just needs to clear the fan-out's own overhead class.
+        const ADAPTIVE_ENGAGE_SETTLE_MS = 400;
+        let adaptiveSeqMs = 0;
+        let adaptiveSeqRefs = 0;
+        // Process in PIPELINED batches (double-buffer). The enumeration is the
+        // head of the pending set in rowid order; every ref a persisted batch
+        // processed leaves the pending set (resolved rows are deleted,
         // unresolvable ones flip to status='failed'), shifting the remaining
         // pending rows forward.
         let prevRemaining = Number.POSITIVE_INFINITY;
-        while (true) {
-            const batch = this.queries.getUnresolvedReferencesBatch(0, batchSize);
-            if (batch.length === 0)
-                break;
-            const result = await this.resolveBatchYielding(batch, maybeYield);
-            // Persist in bounded sub-transactions with yields between: a whole
-            // batch's edge insert / keyed deletes are otherwise one solid
-            // synchronous span each on a multi-GB index, sitting BETWEEN the
-            // per-ref yields — the last unyielded stretch of the resolution loop.
-            // Crash semantics are unchanged (already several transactions): edges
-            // land before their refs are deleted, so a kill mid-way re-resolves
-            // the remainder idempotently on the next run/sweep (#1187).
-            const PERSIST_CHUNK = 1000;
-            // Persist edges immediately
-            const edges = this.createEdges(result.resolved);
-            for (let i = 0; i < edges.length; i += PERSIST_CHUNK) {
-                this.queries.insertEdges(edges.slice(i, i + PERSIST_CHUNK));
-                await maybeYield();
+        // Cadence for the worker connection recycling below — ~8 batches
+        // ≈ 40k refs between recycles keeps the WAL shallow at kernel scale
+        // while a small sync never recycles at all. (25 recovered only half
+        // the write tax — the WAL re-deepened between recycles; reopens are
+        // sub-millisecond so the shorter cadence is ~free.)
+        const RECYCLE_EVERY_BATCHES = 8;
+        let batchesSinceRecycle = 0;
+        // Begin one batch: fan out to the pool when it's ready and the batch is
+        // big enough — workers then resolve batch k+1 WHILE the main thread
+        // persists batch k (persist measured at ~58% of resolution wall on a
+        // 255k-ref repo, all of it previously spent with the pool idle).
+        // Sequential batches stay lazy: they run on the main thread at settle
+        // time, where an early start would only contend with the persist.
+        const beginBatch = (batch) => {
+            if (pool && poolReady && resolver_pool_1.ResolverPool.worthParallel(batch.length)) {
+                return {
+                    mode: 'pool',
+                    settled: pool.resolveBatch(batch).then((out) => ({ ok: true, out }), (err) => ({ ok: false, err })),
+                };
             }
-            // Clean up resolved refs so they don't appear in the next batch
-            const resolvedKeys = result.resolved.map((r) => ({
-                fromNodeId: r.original.fromNodeId,
-                referenceName: r.original.referenceName,
-                referenceKind: r.original.referenceKind,
-            }));
-            for (let i = 0; i < resolvedKeys.length; i += PERSIST_CHUNK) {
-                this.queries.deleteSpecificResolvedReferences(resolvedKeys.slice(i, i + PERSIST_CHUNK));
-                await maybeYield();
+            return { mode: 'seq' };
+        };
+        // Settle an in-flight batch to a ResolutionResult. Deferred post-pass refs
+        // are appended HERE, in loop order — never inside the fan-out promise — so
+        // admission order stays exactly the sequential order even while a later
+        // batch resolves concurrently. A pool failure downgrades to sequential
+        // permanently and re-resolves this batch on the main thread.
+        const settleBatch = async (inFlight, batch) => {
+            if (inFlight.mode === 'pool') {
+                const settled = await inFlight.settled;
+                if (settled.ok) {
+                    this.appendDeferredFromWorkers(settled.out.deferredChain, settled.out.deferredThisMember);
+                    return {
+                        resolved: settled.out.resolved,
+                        unresolved: settled.out.unresolved,
+                        stats: {
+                            total: batch.length,
+                            resolved: settled.out.resolved.length,
+                            unresolved: settled.out.unresolved.length,
+                            byMethod: settled.out.byMethod,
+                        },
+                    };
+                }
+                (0, errors_1.logDebug)('Parallel resolution failed; falling back to sequential', {
+                    error: settled.err instanceof Error ? settled.err.message : String(settled.err),
+                });
+                if (pool)
+                    await pool.destroy().catch(() => undefined);
+                pool = null;
             }
-            // Park unresolvable refs from this batch as status='failed' so they
-            // leave the pending set (the batch reader and non-progress guard below
-            // only see pending rows) but stay retryable when a later sync adds a
-            // symbol that could satisfy them (#1240).
-            const unresolvedKeys = result.unresolved.map((r) => ({
-                fromNodeId: r.fromNodeId,
-                referenceName: r.referenceName,
-                referenceKind: r.referenceKind,
-            }));
-            for (let i = 0; i < unresolvedKeys.length; i += PERSIST_CHUNK) {
-                this.queries.markReferencesFailed(unresolvedKeys.slice(i, i + PERSIST_CHUNK));
-                await maybeYield();
+            return this.resolveBatchYielding(batch, maybeYield);
+        };
+        // Bulk edge load: on big runs, drop the non-unique edge indexes for the
+        // duration of the batch loop (the identity index stays — OR IGNORE dedup
+        // and the source-keyed supertype-walk reads both live on it). Recreated in
+        // the inner finally BEFORE synthesis, whose passes read kind-keyed.
+        // Measured on a 224k-edge resolution set: insert 2.8s → 1.1s + 0.3s
+        // recreate. Same ref-count gate as the pool so small syncs never pay the
+        // recreate cost.
+        let bulkEdgesActive = false;
+        if (parallel?.bulkEdgeLoad && total >= (0, resolver_pool_1.minRefsForPool)()) {
+            try {
+                parallel.bulkEdgeLoad.begin();
+                bulkEdgesActive = true;
             }
-            // Aggregate stats
-            aggregateStats.total += result.stats.total;
-            aggregateStats.resolved += result.stats.resolved;
-            aggregateStats.unresolved += result.stats.unresolved;
-            for (const [method, count] of Object.entries(result.stats.byMethod)) {
-                aggregateStats.byMethod[method] = (aggregateStats.byMethod[method] || 0) + count;
+            catch { /* keep the indexes; inserts just pay the per-row maintenance */ }
+        }
+        // Same gate for the ref-index window: the loop's deletes stop maintaining
+        // the five sync-path unresolved_refs indexes, and the end-of-loop rebuild
+        // is near-free (only failed refs survive the loop).
+        let bulkRefsActive = false;
+        if (parallel?.refIndexLoad && total >= (0, resolver_pool_1.minRefsForPool)()) {
+            try {
+                parallel.refIndexLoad.begin();
+                bulkRefsActive = true;
             }
-            processed += batch.length;
-            onProgress?.(processed, total);
-            // Yield so progress UI can render between batches
-            await new Promise(resolve => setImmediate(resolve));
-            // NOTE: there used to be an extra early break here when a batch resolved
-            // nothing (`result.unresolved.length === batch.length`). That was wrong:
-            // an all-unresolvable batch still DELETES its rows (progress), yet the
-            // break abandoned every batch after it in the same run — on a repo whose
-            // first 5000 refs are all external/stdlib calls, resolution stopped at
-            // batch one and left the rest of the table as permanent orphans (#1187).
-            // The count-based guard below catches the true no-progress case.
-            // Non-progress guard (defense-in-depth). Because we re-read from offset 0
-            // each pass, the PENDING population MUST shrink every iteration — resolved
-            // refs are deleted and unresolvable ones are marked failed above, and both
-            // leave the pending set the batch reader sees. If it didn't shrink, a
-            // resolver returned a match whose `original.referenceName` differs from the
-            // stored row, so the keyed delete/update no-ops, and we'd re-read +
-            // re-resolve + re-insert the same rows forever (the runaway that grew a
-            // 99-file repo to 5M edges / 1.4 GB before the Go-fallback fix). Stop
-            // rather than grow the graph without bound.
-            const remaining = this.queries.getUnresolvedReferencesCount();
-            if (remaining >= prevRemaining)
-                break;
-            prevRemaining = remaining;
+            catch { /* keep the indexes; deletes just pay the per-row maintenance */ }
         }
-        // Dynamic-edge synthesis: now that all base `calls` edges are persisted,
-        // synthesize observer/callback dispatch edges (dispatcher → registered
-        // callbacks) that static parsing leaves out. Best-effort — never fail the
-        // index on it. See docs/design/callback-edge-synthesis.md.
         try {
-            aggregateStats.byMethod['callback-synthesis'] = await (0, callback_synthesizer_1.synthesizeCallbackEdges)(this.queries, this.context, onSynthesisProgress);
+            try {
+                tLp = Date.now();
+                let batch = this.queries.getUnresolvedReferencesBatchAfter(0, batchSize);
+                lp('read', tLp);
+                let inFlight = batch.length > 0 ? beginBatch(batch) : null;
+                while (batch.length > 0 && inFlight) {
+                    // Prefetch the NEXT batch before this one persists: this batch's rows
+                    // are still pending (nothing has mutated the table since they were
+                    // read), so seeking past this batch's last row id in the same rowid
+                    // enumeration yields the following batch (keyset — OFFSET re-walked the
+                    // accumulated failed prefix every read, 54.6s at kernel scale, §7a.2).
+                    tLp = Date.now();
+                    const nextBatch = this.queries.getUnresolvedReferencesBatchAfter(batch[batch.length - 1].rowId, batchSize);
+                    lp('read', tLp);
+                    const tBatch = Date.now();
+                    const result = await settleBatch(inFlight, batch);
+                    if (process.env.HOMEGRAPH_SYNTH_TIMINGS)
+                        console.error(`[pool-timing] batch ${inFlight.mode}: ${batch.length} refs in ${Date.now() - tBatch}ms`);
+                    lp('settle', tBatch);
+                    // Adaptive pool engagement: the fixed ref-count gate can't see PER-REF
+                    // cost, and settle rates differ ~9× by language (56k Rust refs cost
+                    // more sequential settle than 154k Go refs — 36µs vs 4µs measured on
+                    // tokio/prometheus). After each sequential batch, project the remaining
+                    // settle from the observed rate and boot the pool mid-loop when it
+                    // clears the bar. The loop already switches to fan-out only when the
+                    // async boot reports ready, admission order is mode-independent, and
+                    // 2-core/low-memory hosts still decline inside tryCreate's sizing —
+                    // so the switch changes wall-clock, never the graph.
+                    if (inFlight.mode === 'seq' && parallel && pool === null && !poolEngageTried) {
+                        adaptiveSeqMs += Date.now() - tBatch;
+                        adaptiveSeqRefs += batch.length;
+                        const remaining = total - processed - batch.length;
+                        const projectedMs = (adaptiveSeqMs / Math.max(1, adaptiveSeqRefs)) * Math.max(0, remaining);
+                        if (projectedMs >= ADAPTIVE_ENGAGE_SETTLE_MS) {
+                            if (process.env.HOMEGRAPH_SYNTH_TIMINGS) {
+                                console.error(`[pool-timing] adaptive engage: projected ${Math.round(projectedMs)}ms sequential settle over ${remaining} remaining refs`);
+                            }
+                            pool = createPool(Date.now(), 'adaptive');
+                        }
+                    }
+                    // WAL-valve backstop at the ONE pool-idle boundary of the double-buffer
+                    // (this batch settled, the next not yet fanned out): past the hard cap
+                    // the writer parks for a full backfill here, where the pool's readers
+                    // are all between statements — so the backfill completes, readers
+                    // re-enter at SQLite's backfilled mark, and the next persist commit
+                    // WRAPS the WAL instead of growing it. No-op (one fstat) under the cap.
+                    tLp = Date.now();
+                    const bp = parallel?.backpressure?.();
+                    if (bp)
+                        await bp;
+                    lp('backpressure', tLp);
+                    // Recycle the workers' read connections periodically at this same
+                    // worker-idle boundary (batch k settled, batch k+1 not yet fanned
+                    // out): a long-lived reader pins WAL checkpoint progress, and the
+                    // deep WAL that accumulates behind it taxes the writer's OWN page
+                    // operations — the §7a.6 writes-under-readers finding (deletes
+                    // 42.6s → 118.8s from 0 to 4 attached readers; an aggressive valve
+                    // recovered the writes but paid +129s in full-park folds). Releasing
+                    // the read marks every ~25 batches lets the existing checkpoints
+                    // advance instead, at ~milliseconds of reopen cost. A failed recycle
+                    // downgrades to sequential permanently, same as a failed fan-out.
+                    if (pool && poolReady && ++batchesSinceRecycle >= RECYCLE_EVERY_BATCHES) {
+                        batchesSinceRecycle = 0;
+                        tLp = Date.now();
+                        try {
+                            await pool.recycleWorkers();
+                        }
+                        catch (err) {
+                            (0, errors_1.logDebug)('Worker connection recycle failed; falling back to sequential', {
+                                error: err instanceof Error ? err.message : String(err),
+                            });
+                            await pool.destroy().catch(() => undefined);
+                            pool = null;
+                        }
+                        lp('recycle', tLp);
+                    }
+                    // Persist in bounded sub-transactions with yields between: a whole
+                    // batch's edge insert / keyed deletes are otherwise one solid
+                    // synchronous span each on a multi-GB index, sitting BETWEEN the
+                    // per-ref yields — the last unyielded stretch of the resolution loop.
+                    // Crash semantics are unchanged (already several transactions): edges
+                    // land before their refs are deleted, so a kill mid-way re-resolves
+                    // the remainder idempotently on the next run/sweep (#1187).
+                    const PERSIST_CHUNK = 1000;
+                    const tPersist = Date.now();
+                    // Persist edges BEFORE fanning out the next batch: later batches read
+                    // this batch's edges — resolveMethodOnType walks supertype chains over
+                    // `extends`/`implements` edges that earlier batches resolved, so a
+                    // receiver typed as a subclass only reaches a method declared on its
+                    // base class if those edges are visible. (Validated on dubbo: fanning
+                    // out first downgraded exactly those supertype-method resolutions from
+                    // the 0.9 typed-receiver path to the 0.65 word-overlap fallback.)
+                    tLp = Date.now();
+                    const edges = this.createEdges(result.resolved);
+                    lp('createEdges', tLp);
+                    tLp = Date.now();
+                    for (let i = 0; i < edges.length; i += PERSIST_CHUNK) {
+                        this.queries.insertEdges(edges.slice(i, i + PERSIST_CHUNK));
+                        await maybeYield();
+                    }
+                    lp('insertEdges', tLp);
+                    // NOW fan the next batch out — workers see exactly the edge state the
+                    // sequential baseline would (every batch ≤ this one committed), while
+                    // the main thread spends the REST of the persist (ref deletes + failed
+                    // parking below) overlapped with their resolution — the double-buffer.
+                    const nextInFlight = nextBatch.length > 0 ? beginBatch(nextBatch) : null;
+                    // Clean up resolved refs so they don't appear in the next batch —
+                    // by row id, so a same-key sibling ref in a LATER batch (same caller
+                    // calling the same callee at another line) is left pending for its own
+                    // attempt instead of being swept out with this batch's rows (#1269).
+                    tLp = Date.now();
+                    let removedThisBatch = 0;
+                    const resolvedCleanup = ReferenceResolver.partitionResolvedCleanup(result.resolved);
+                    for (let i = 0; i < resolvedCleanup.rowIds.length; i += PERSIST_CHUNK) {
+                        removedThisBatch += this.queries.deleteReferencesByRowIds(resolvedCleanup.rowIds.slice(i, i + PERSIST_CHUNK));
+                        await maybeYield();
+                    }
+                    for (let i = 0; i < resolvedCleanup.legacyKeys.length; i += PERSIST_CHUNK) {
+                        removedThisBatch += this.queries.deleteSpecificResolvedReferences(resolvedCleanup.legacyKeys.slice(i, i + PERSIST_CHUNK));
+                        await maybeYield();
+                    }
+                    lp('deletes', tLp);
+                    // Park unresolvable refs from this batch as status='failed' so they
+                    // leave the pending set (the batch reader and non-progress guard below
+                    // only see pending rows) but stay retryable when a later sync adds a
+                    // symbol that could satisfy them (#1240).
+                    tLp = Date.now();
+                    const failedCleanup = ReferenceResolver.partitionFailedCleanup(result.unresolved);
+                    for (let i = 0; i < failedCleanup.byRowId.length; i += PERSIST_CHUNK) {
+                        removedThisBatch += this.queries.markReferencesFailedByRowIds(failedCleanup.byRowId.slice(i, i + PERSIST_CHUNK));
+                        await maybeYield();
+                    }
+                    for (let i = 0; i < failedCleanup.legacyKeys.length; i += PERSIST_CHUNK) {
+                        removedThisBatch += this.queries.markReferencesFailed(failedCleanup.legacyKeys.slice(i, i + PERSIST_CHUNK));
+                        await maybeYield();
+                    }
+                    lp('marks', tLp);
+                    if (process.env.HOMEGRAPH_SYNTH_TIMINGS)
+                        console.error(`[pool-timing] batch persist: ${Date.now() - tPersist}ms`);
+                    // Aggregate stats
+                    aggregateStats.total += result.stats.total;
+                    aggregateStats.resolved += result.stats.resolved;
+                    aggregateStats.unresolved += result.stats.unresolved;
+                    for (const [method, count] of Object.entries(result.stats.byMethod)) {
+                        aggregateStats.byMethod[method] = (aggregateStats.byMethod[method] || 0) + count;
+                    }
+                    processed += batch.length;
+                    onProgress?.(processed, total);
+                    // Yield so progress UI can render between batches
+                    await new Promise(resolve => setImmediate(resolve));
+                    // NOTE: there used to be an extra early break here when a batch resolved
+                    // nothing (`result.unresolved.length === batch.length`). That was wrong:
+                    // an all-unresolvable batch still DELETES its rows (progress), yet the
+                    // break abandoned every batch after it in the same run — on a repo whose
+                    // first 5000 refs are all external/stdlib calls, resolution stopped at
+                    // batch one and left the rest of the table as permanent orphans (#1187).
+                    // The count-based guard below catches the true no-progress case.
+                    // Non-progress guard (defense-in-depth). Each iteration enumerates from
+                    // the head of the pending set, so the PENDING population MUST shrink
+                    // every iteration — resolved refs are deleted and unresolvable ones are
+                    // marked failed above, and both leave the pending set the batch reader
+                    // sees. If it didn't shrink, a resolver returned a match whose
+                    // `original.referenceName` differs from the stored row, so the keyed
+                    // delete/update no-ops, and we'd re-read + re-resolve + re-insert the
+                    // same rows forever (the runaway that grew a 99-file repo to 5M edges /
+                    // 1.4 GB before the Go-fallback fix). Stop rather than grow the graph
+                    // without bound. (An in-flight prefetched batch is abandoned unsettled —
+                    // fan-out has no side effects until settleBatch appends its results.)
+                    // Non-progress signal, now O(1): `changes` summed across this batch's
+                    // deletes + failed-parks is the DIRECT evidence the guard's old count
+                    // diff inferred — a resolver returning a mismatched name makes the keyed
+                    // cleanup no-op, which shows up here as zero removals. The per-batch
+                    // COUNT(*) it replaces walked every remaining pending row — O(N²/batch)
+                    // over a run, 93.9s of the kernel-scale batch loop (§7a.2). A REAL count
+                    // runs only on the suspicious path (claimed-work batch removed nothing —
+                    // e.g. every row was a sibling a legacy-key sweep already consumed),
+                    // where it arbitrates stop-vs-continue exactly as before.
+                    if (removedThisBatch <= 0 && batch.length > 0) {
+                        tLp = Date.now();
+                        const remaining = this.queries.getUnresolvedReferencesCount();
+                        lp('countGuard', tLp);
+                        if (remaining >= prevRemaining)
+                            break;
+                        prevRemaining = remaining;
+                    }
+                    // Advance the pipeline: the prefetched batch (already fanned out when
+                    // the pool is on) becomes the current one.
+                    batch = nextBatch;
+                    inFlight = nextInFlight;
+                }
+            }
+            finally {
+                // Recreate the edge indexes BEFORE synthesis (kind-keyed reads) and on
+                // any error path. A crash before this line is healed by the next
+                // DatabaseConnection open (schema.sql re-applies IF NOT EXISTS).
+                if (bulkRefsActive) {
+                    const tRef = Date.now();
+                    await parallel.refIndexLoad.end();
+                    if (process.env.HOMEGRAPH_SYNTH_TIMINGS)
+                        console.error(`[phase-timing] ref-index-recreate: ${Date.now() - tRef}ms`);
+                }
+                if (bulkEdgesActive) {
+                    const tIdx = Date.now();
+                    await parallel.bulkEdgeLoad.end();
+                    if (process.env.HOMEGRAPH_SYNTH_TIMINGS)
+                        console.error(`[phase-timing] edge-index-recreate: ${Date.now() - tIdx}ms`);
+                    // The recreate just wrote every non-unique edge index into the WAL
+                    // (multi-GB at kernel scale) with the pool idle — fold before the
+                    // synthesis passes pin readers against it for minutes.
+                    const bp = parallel?.backpressure?.();
+                    if (bp)
+                        await bp;
+                }
+            }
+            // Dynamic-edge synthesis: now that all base `calls` edges are persisted,
+            // synthesize observer/callback dispatch edges (dispatcher → registered
+            // callbacks) that static parsing leaves out. Best-effort — never fail the
+            // index on it. The pool (when it survived resolution) is REUSED to fan the
+            // independent passes across its read-only workers — that's why its destroy
+            // lives in the finally below, after synthesis, not at the end of the batch
+            // loop. See docs/design/callback-edge-synthesis.md.
+            const tSynth = Date.now();
+            try {
+                aggregateStats.byMethod['callback-synthesis'] = await (0, callback_synthesizer_1.synthesizeCallbackEdges)(this.queries, this.context, onSynthesisProgress, pool, parallel?.backpressure);
+            }
+            catch {
+                // synthesis is additive and optional; ignore failures
+            }
+            if (process.env.HOMEGRAPH_SYNTH_TIMINGS)
+                console.error(`[phase-timing] callback-synthesis: ${Date.now() - tSynth}ms`);
+        }
+        finally {
+            if (pool)
+                await pool.destroy().catch(() => undefined);
         }
-        catch {
-            // synthesis is additive and optional; ignore failures
+        if (loopProf) {
+            const parts = Object.entries(loopProf).map(([k, v]) => `${k}=${(v / 1000).toFixed(1)}s`).join(' ');
+            console.error(`[resolve-profile] loop-stages ${parts}`);
         }
+        this.dumpResolveProfile('main');
         return {
             resolved: [],
             unresolved: [],