homegraph 1.2.0 → 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");
@@ -68,6 +69,8 @@ const CHAIN_LANGUAGES = new Set(['java', 'kotlin', 'csharp', 'swift', 'rust', 'g
 const SCOPED_CHAIN_LANGUAGES = new Set(['rust']);
 /** The extractor's chained-receiver encoding: `<inner>().<method>`. */
 const CHAIN_SHAPE = /^(.+)\(\)\.(\w+)$/;
+/** PHP `$this->prop->method()` encoded as `this->prop.method` — no `()`, so CHAIN_SHAPE misses it. */
+const PHP_PROP_SHAPE = /^this->\w+\.\w+$/;
 /**
  * Cache size limits. Each per-resolver cache is bounded so memory
  * stays flat on large codebases (20k+ files). Sizes were chosen to
@@ -240,6 +243,43 @@ class ReferenceResolver {
     nameCache; // name → nodes cache
     lowerNameCache; // lower(name) → nodes cache
     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
+    // for every dotted call ref by the Spring resolver (constants) and every
+    // `hook_` ref by the Drupal resolver (functions), that scan dominated
+    // resolution on large repos (#1180). The node set is stable within a
+    // resolution pass (same lifetime assumption as nameCache); clearCaches() resets
+    // it between passes. Callers must treat the returned array as read-only.
+    nodesByKindCache = new Map();
     knownNames = null; // all known symbol names for fast pre-filtering
     knownFiles = null;
     cachesWarmed = false;
@@ -265,6 +305,10 @@ class ReferenceResolver {
         this.nameCache = new lru_cache_1.LRUCache(limit);
         this.lowerNameCache = new lru_cache_1.LRUCache(limit);
         this.qualifiedNameCache = new lru_cache_1.LRUCache(limit);
+        // Split-lines arrays are heavier than content strings; refs arrive
+        // file-ordered, so a small cache still hits nearly always.
+        this.fileLinesCache = new lru_cache_1.LRUCache(contentLimit);
+        this.methodMatchCache = new lru_cache_1.LRUCache(limit);
         this.context = this.createContext();
     }
     /**
@@ -320,6 +364,28 @@ class ReferenceResolver {
         this.knownNames = new Set(this.queries.getAllNodeNames());
         this.cachesWarmed = true;
     }
+    /**
+     * warmCaches for the async resolution entry points: streams the distinct
+     * name set with periodic yields instead of one synchronous `.all()`. On a
+     * multi-million-node index the DISTINCT scan is a solid multi-second block
+     * (measured up to 28s inside `homegraph sync` on the Linux kernel index),
+     * long enough to matter to the #850 watchdog on slower hardware. Same
+     * result, same memory — only the event loop keeps turning.
+     */
+    async warmCachesYielding(onYield) {
+        if (this.cachesWarmed)
+            return;
+        this.knownFiles = new Set(this.queries.getAllFilePaths());
+        const names = new Set();
+        let scanned = 0;
+        for (const name of this.queries.iterateNodeNames()) {
+            names.add(name);
+            if ((++scanned & 8191) === 0)
+                await onYield();
+        }
+        this.knownNames = names;
+        this.cachesWarmed = true;
+    }
     /**
      * Clear internal caches
      */
@@ -331,9 +397,38 @@ class ReferenceResolver {
         this.nameCache.clear();
         this.lowerNameCache.clear();
         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) {
+        if (this.fileCache.has(filePath)) {
+            return this.fileCache.get(filePath);
+        }
+        const fullPath = path.join(this.projectRoot, filePath);
+        try {
+            const content = fs.readFileSync(fullPath, 'utf-8');
+            this.fileCache.set(filePath, content);
+            return content;
+        }
+        catch (error) {
+            (0, errors_1.logDebug)('Failed to read file for resolution', { filePath, error: String(error) });
+            this.fileCache.set(filePath, null);
+            return null;
+        }
     }
     /**
      * Create the resolution context
@@ -354,6 +449,76 @@ class ReferenceResolver {
                 this.nameCache.set(name, result);
                 return result;
             },
+            getMethodMatches: (typeName, methodName, language) => {
+                const key = `${language} ${typeName}::${methodName}`;
+                const cached = this.methodMatchCache.get(key);
+                if (cached !== undefined)
+                    return cached;
+                let candidates = this.nameCache.get(methodName);
+                if (candidates === undefined) {
+                    candidates = this.queries.getNodesByName(methodName);
+                    this.nameCache.set(methodName, candidates);
+                }
+                const want = `${typeName}::${methodName}`;
+                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;
+            },
             getNodesByQualifiedName: (qualifiedName) => {
                 const cached = this.qualifiedNameCache.get(qualifiedName);
                 if (cached !== undefined)
@@ -363,8 +528,18 @@ class ReferenceResolver {
                 return result;
             },
             getNodesByKind: (kind) => {
-                return this.queries.getNodesByKind(kind);
+                const cached = this.nodesByKindCache.get(kind);
+                if (cached !== undefined)
+                    return cached;
+                const result = this.queries.getNodesByKind(kind);
+                this.nodesByKindCache.set(kind, result);
+                return result;
             },
+            // Streamed, uncached — synthesizers scan-and-filter whole kinds, and
+            // both the materialized array AND the per-kind cache retention are
+            // O(nodes) memory (#1212). Per-ref resolvers keep the cached array
+            // variant above.
+            iterateNodesByKind: (kind) => this.queries.iterateNodesByKind(kind),
             fileExists: (filePath) => {
                 // Check pre-built known files set first (O(1))
                 if (this.knownFiles) {
@@ -383,21 +558,15 @@ class ReferenceResolver {
                     return false;
                 }
             },
-            readFile: (filePath) => {
-                if (this.fileCache.has(filePath)) {
-                    return this.fileCache.get(filePath);
-                }
-                const fullPath = path.join(this.projectRoot, filePath);
-                try {
-                    const content = fs.readFileSync(fullPath, 'utf-8');
-                    this.fileCache.set(filePath, content);
-                    return content;
-                }
-                catch (error) {
-                    (0, errors_1.logDebug)('Failed to read file for resolution', { filePath, error: String(error) });
-                    this.fileCache.set(filePath, null);
-                    return null;
-                }
+            readFile: (filePath) => this.readFileCached(filePath),
+            getFileLines: (filePath) => {
+                const cached = this.fileLinesCache.get(filePath);
+                if (cached !== undefined)
+                    return cached;
+                const source = this.readFileCached(filePath);
+                const lines = source === null ? null : source.split(/\r?\n/);
+                this.fileLinesCache.set(filePath, lines);
+                return lines;
             },
             getProjectRoot: () => this.projectRoot,
             getAllFiles: () => {
@@ -437,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;
@@ -500,7 +683,7 @@ class ReferenceResolver {
                 // `.ts` index barrel and silently break the chain (#629). Re-key
                 // the parse on the barrel's extension so the chase works no matter
                 // what kind of file imports through it.
-                const isJsFamily = /\.(?:d\.ts|[cm]?tsx?|[cm]?jsx?)$/i.test(filePath);
+                const isJsFamily = /\.(?:d\.ts|[cm]?tsx?|[cm]?jsx?|ets)$/i.test(filePath);
                 const reExports = (0, import_resolver_1.extractReExports)(content, isJsFamily ? 'typescript' : language);
                 this.reExportCache.set(filePath, reExports);
                 return reExports;
@@ -528,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;
@@ -667,15 +851,42 @@ class ReferenceResolver {
         if (this.isBuiltInOrExternal(ref)) {
             return null;
         }
+        // CFML component paths in inheritance (#1152): `extends="coldbox.system.web.
+        // Controller"` names the supertype by its dot-separated path (or `extends=
+        // "../base"` by relative file path) — the graph indexes the class under its
+        // final segment only, so these die at the fast pre-filter below and never
+        // resolved. Handled by a dedicated path-corroborated matcher, gated to
+        // inheritance refs only (a dotted `calls` ref is a member-access chain, not
+        // a component path). No fallthrough on miss: the full path string can only
+        // ever mis-match downstream, and an unresolvable supertype usually lives in
+        // an out-of-repo library (mxunit, testbox) — silent beats wrong.
+        if ((ref.language === 'cfml' || ref.language === 'cfscript') &&
+            (ref.referenceKind === 'extends' || ref.referenceKind === 'implements') &&
+            (ref.referenceName.includes('.') || ref.referenceName.includes('/'))) {
+            return this.resolveCfmlComponentPath(ref);
+        }
         // Fast pre-filter: skip if no symbol with this name exists anywhere
         // AND the name doesn't match a local import. The import escape is
         // necessary because re-export rename chains (`import { login }
         // from './barrel'` where the barrel has `export { signIn as login }
         // from './auth'`) intentionally call a name that has no
         // declaration anywhere — only the renamed upstream symbol does.
-        if (!this.hasAnyPossibleMatch(ref.referenceName) &&
-            !this.matchesAnyImport(ref) &&
-            !this.frameworks.some((f) => f.claimsReference?.(ref.referenceName))) {
+        // ArkTS chained-attribute refs carry a leading dot (`.titleStyle`) that
+        // routes them to the decorator-gated matcher; the symbol itself is
+        // indexed under the bare name, so the existence check strips the dot.
+        // Nix static path imports (`import ./x.nix`) name a FILE, not a symbol —
+        // they bypass the symbol-existence check and resolve via resolveViaImport.
+        const existenceName = ref.language === 'arkts' && ref.referenceName.startsWith('.')
+            ? ref.referenceName.slice(1)
+            : 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:
@@ -701,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
@@ -720,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;
@@ -739,13 +986,43 @@ class ReferenceResolver {
         // If that didn't find the file, do NOT fall back to the symbol
         // name-matcher — it would mis-connect e.g. "inc/db.php" to an unrelated
         // db.php elsewhere in the tree (a wrong edge is worse than none, #660).
-        if ((0, import_resolver_1.isPhpIncludePathRef)(ref)) {
+        // Terraform refs are directory-scoped by language semantics — the
+        // framework resolver IS the whole rulebook (`var.X` can never legally
+        // bind outside its module directory), so the name-matcher's
+        // qualified-name fallback would only ever add wrong cross-module edges.
+        // Nix static path imports are file references for the same reason —
+        // falling through would let "./x.nix" name-match an unrelated node.
+        if ((0, import_resolver_1.isPhpIncludePathRef)(ref) || (0, import_resolver_1.isCobolCopybookRef)(ref) || (0, import_resolver_1.isNixPathImportRef)(ref) || ref.language === 'terraform') {
             return candidates.length > 0
                 ? candidates.reduce((best, curr) => curr.confidence > best.confidence ? curr : best)
                 : null;
         }
         // Strategy 3: Try name matching
-        const nameResult = this.gateLanguage((0, name_matcher_1.matchReference)(ref, this.context), ref);
+        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
+        // module `inherit (lib) mkOption`s the same nixpkgs helpers, so the
+        // matcher would link each `mkOption` call to whichever file's inherit
+        // binding it happened to pick. Same-file matches only.
+        if (nameResult) {
+            const target = this.queries.getNodeById(nameResult.targetNodeId);
+            if (ref.language === 'nix') {
+                if (!target || target.filePath !== ref.filePath) {
+                    nameResult = null;
+                }
+            }
+            else if (target && target.language === 'nix') {
+                // The reverse direction is just as impossible: no other language can
+                // symbolically call into a .nix binding (interop is eval/CLI, never a
+                // linkable symbol) — without this, a Python script's `split()` lands
+                // on some module's `split = ...` binding as a low-confidence match.
+                nameResult = null;
+            }
+        }
         if (nameResult) {
             candidates.push(nameResult);
         }
@@ -758,6 +1035,15 @@ class ReferenceResolver {
                 CHAIN_SHAPE.test(ref.referenceName)) {
                 this.deferredChainRefs.push(ref);
             }
+            else if (
+            // PHP `$this->prop->method()` (encoded `this->prop.method`): its method
+            // may live on the property's declared supertype, resolvable only once
+            // implements/extends edges exist — defer to the same conformance pass.
+            ref.referenceKind === 'calls' &&
+                ref.language === 'php' &&
+                PHP_PROP_SHAPE.test(ref.referenceName)) {
+                this.deferredChainRefs.push(ref);
+            }
             return null;
         }
         // Return highest confidence candidate
@@ -804,6 +1090,18 @@ class ReferenceResolver {
                 metadata: {
                     confidence: ref.confidence,
                     resolvedBy: ref.resolvedBy,
+                    // The ORIGINAL reference text (and kind, when edge-kind promotion
+                    // rewrote it — calls→instantiates, extends→implements,
+                    // function_ref→references). If this edge's target is later removed
+                    // by a re-index, the edge is resurrected as exactly this ref and
+                    // re-resolved (#1240 removal case) — a faithful resurrection, so
+                    // re-resolution can never bind anywhere a full re-index wouldn't.
+                    // Reconstruction from the target node's name instead would strip
+                    // receiver/qualifier context (`h.greet` → `greet`) and risk a
+                    // wrong rebind; edges without refName (pre-#1240, synthesized) are
+                    // deliberately NOT resurrected for the same reason.
+                    refName: ref.original.referenceName,
+                    ...(ref.original.referenceKind !== kind ? { refKind: ref.original.referenceKind } : {}),
                     // Uniform marker for function-as-value edges (#756), regardless of
                     // which strategy resolved them (import vs matchFunctionRef) — lets
                     // tooling label "callback registration" and lets validation diff
@@ -813,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
      */
@@ -826,11 +1170,61 @@ 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
+        // own file never changes is otherwise gone forever, so when a DIFFERENT
+        // file later gains the export/symbol that would satisfy it, no sync can
+        // recreate the edge — only a full re-index. Failed rows are excluded from
+        // the pending readers, which preserves the #1187 orphan sweep's
+        // invariant in status form: after a COMPLETED pass nothing it processed
+        // 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) {
+            const { byRowId, legacyKeys } = ReferenceResolver.partitionFailedCleanup(result.unresolved);
+            this.queries.markReferencesFailedByRowIds(byRowId);
+            this.queries.markReferencesFailed(legacyKeys);
+        }
+        return result;
+    }
+    /**
+     * Yielding counterpart of {@link resolveAndPersist} for a caller-supplied
+     * ref list — used by sync's failed-ref retry pass (#1240). Same persistence
+     * semantics: resolved refs become edges and their rows are deleted;
+     * still-unresolvable refs are (re-)marked failed (a no-op for rows already
+     * in that status). Yields per-ref because sync can run on the daemon's
+     * liveness-watchdog thread (#850/#1091) and a retry set is unbounded when
+     * a large edit lands many popular symbol names at once.
+     */
+    async resolveAndPersistListYielding(refs) {
+        const maybeYield = (0, cooperative_yield_1.createYielder)();
+        const result = await this.resolveBatchYielding(refs, maybeYield);
+        const PERSIST_CHUNK = 1000;
+        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();
+        }
+        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();
+        }
+        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;
     }
@@ -862,11 +1256,15 @@ class ReferenceResolver {
         const maybeYield = (0, cooperative_yield_1.createYielder)();
         const resolved = [];
         for (const ref of deferred) {
-            // `::`-receiver languages (Rust) split on `::` (matchScopedCallChain);
+            // PHP `this->prop.method` resolves via matchMethodCall (declared-type
+            // inference + resolveMethodOnType conformance walk); `::`-receiver
+            // languages (Rust) split on `::` (matchScopedCallChain); other
             // dotted-receiver languages on `.` (matchDottedCallChain).
-            const chainMatch = SCOPED_CHAIN_LANGUAGES.has(ref.language)
-                ? (0, name_matcher_1.matchScopedCallChain)(ref, this.context)
-                : (0, name_matcher_1.matchDottedCallChain)(ref, this.context);
+            const chainMatch = (ref.language === 'php' && PHP_PROP_SHAPE.test(ref.referenceName))
+                ? (0, name_matcher_1.matchMethodCall)(ref, this.context)
+                : SCOPED_CHAIN_LANGUAGES.has(ref.language)
+                    ? (0, name_matcher_1.matchScopedCallChain)(ref, this.context)
+                    : (0, name_matcher_1.matchDottedCallChain)(ref, this.context);
             const match = this.gateLanguage(chainMatch, ref);
             if (match)
                 resolved.push(match);
@@ -882,45 +1280,198 @@ class ReferenceResolver {
         return edges.length;
     }
     /**
-     * Resolve one batch in smaller sub-chunks, yielding to the event loop between
-     * them so the #850 liveness heartbeat can fire on a slow/dense batch (#1091).
-     * Behaviourally identical to a single `resolveAll(batch)`: `warmCaches()` is
-     * idempotent (guarded) and `resolveOne` is independent per ref, so splitting
-     * and re-merging changes only timing, never which edges get created. Falls
-     * through to a plain `resolveAll` when the batch is already small.
+     * Resolve one batch with a yield checkpoint between EVERY ref so the #850
+     * liveness heartbeat can fire on a slow/dense batch (#1091). The checkpoint
+     * granularity is per-ref — not per-N-refs — because per-ref cost is unbounded
+     * in the worst case (a collision-heavy method name whose candidate set misses
+     * the LRU re-fetches tens of thousands of rows): any fixed N multiplies that
+     * worst case into the watchdog window, which is how v1.2.0 still got killed
+     * at "Resolving refs" on large Java monorepos (#1122). `maybeYield()` is a
+     * ~ns time check when under budget, so per-ref checkpoints cost nothing.
+     * Behaviourally identical to `resolveAll(batch)`: `warmCaches()` is
+     * idempotent (guarded) and `resolveOne` is independent per ref, so yielding
+     * between refs changes only timing, never which edges get created.
      */
-    async resolveBatchYielding(batch, maybeYield, subChunkSize = 500) {
-        if (batch.length <= subChunkSize)
-            return this.resolveAll(batch);
+    async resolveBatchYielding(batch, maybeYield) {
+        this.warmCaches();
+        this.advanceSupertypeGeneration();
         const resolved = [];
         const unresolved = [];
         const byMethod = {};
-        let total = 0;
-        let resolvedCount = 0;
-        let unresolvedCount = 0;
-        for (let i = 0; i < batch.length; i += subChunkSize) {
-            const chunk = this.resolveAll(batch.slice(i, i + subChunkSize));
-            for (const r of chunk.resolved)
-                resolved.push(r);
-            for (const u of chunk.unresolved)
-                unresolved.push(u);
-            total += chunk.stats.total;
-            resolvedCount += chunk.stats.resolved;
-            unresolvedCount += chunk.stats.unresolved;
-            for (const [m, c] of Object.entries(chunk.stats.byMethod)) {
-                byMethod[m] = (byMethod[m] || 0) + c;
+        for (const raw of batch) {
+            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;
             }
-            await maybeYield();
+            else {
+                unresolved.push(ref);
+            }
+            // 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,
+            unresolved,
+            stats: {
+                total: batch.length,
+                resolved: resolved.length,
+                unresolved: unresolved.length,
+                byMethod,
+            },
+        };
+    }
+    /**
+     * 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 });
         }
-        return { resolved, unresolved, stats: { total, resolved: resolvedCount, unresolved: unresolvedCount, byMethod } };
+    }
+    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) {
-        this.warmCaches();
+    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
@@ -928,6 +1479,20 @@ 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;
         const aggregateStats = {
@@ -936,74 +1501,370 @@ class ReferenceResolver {
             unresolved: 0,
             byMethod: {},
         };
-        // Process in batches. We always read from offset 0 because resolved refs
-        // are deleted after each batch, shifting the remaining rows forward.
+        // 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 edges immediately
-            const edges = this.createEdges(result.resolved);
-            if (edges.length > 0) {
-                this.queries.insertEdges(edges);
+        // 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
-            if (result.resolved.length > 0) {
-                this.queries.deleteSpecificResolvedReferences(result.resolved.map((r) => ({
-                    fromNodeId: r.original.fromNodeId,
-                    referenceName: r.original.referenceName,
-                    referenceKind: r.original.referenceKind,
-                })));
-            }
-            // Delete unresolvable refs from this batch to avoid re-processing them
-            if (result.unresolved.length > 0) {
-                this.queries.deleteSpecificResolvedReferences(result.unresolved.map((r) => ({
-                    fromNodeId: r.fromNodeId,
-                    referenceName: r.referenceName,
-                    referenceKind: r.referenceKind,
-                })));
+            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;
             }
-            // 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;
+            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;
             }
-            processed += batch.length;
-            onProgress?.(processed, total);
-            // Yield so progress UI can render between batches
-            await new Promise(resolve => setImmediate(resolve));
-            // If nothing was resolved or removed in this batch, we'd loop forever
-            // on the same rows. Break to avoid infinite loop.
-            if (result.resolved.length === 0 && result.unresolved.length === batch.length) {
-                break;
+            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;
             }
-            // Non-progress guard (defense-in-depth). Because we re-read from offset 0
-            // each pass, the unresolved_refs table MUST shrink every iteration — both
-            // resolved and unresolved refs are deleted above. If it didn't shrink, a
-            // resolver returned a match whose `original.referenceName` differs from the
-            // stored row, so the keyed delete 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);
+            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: [],
@@ -1022,11 +1883,18 @@ class ReferenceResolver {
     isBuiltInOrExternal(ref) {
         const name = ref.referenceName;
         const isJsTs = ref.language === 'typescript' || ref.language === 'javascript'
-            || ref.language === 'tsx' || ref.language === 'jsx';
+            || ref.language === 'tsx' || ref.language === 'jsx' || ref.language === 'arkts';
         // JavaScript/TypeScript built-ins
         if (isJsTs && JS_BUILT_INS.has(name)) {
             return true;
         }
+        // ArkTS resource-reference intrinsics — `$r('app.string.x')` /
+        // `$rawfile('x.png')` are framework-provided and appear dozens of times
+        // per UI file; without this they can resolve to a stray same-named
+        // symbol (e.g. a checked-in hvigor wrapper's `$r`).
+        if (ref.language === 'arkts' && (name === '$r' || name === '$rawfile')) {
+            return true;
+        }
         // Common JS/TS library calls (console.log, Math.floor, JSON.parse)
         if (isJsTs && (name.startsWith('console.') || name.startsWith('Math.') || name.startsWith('JSON.'))) {
             return true;
@@ -1191,6 +2059,96 @@ class ReferenceResolver {
         const target = found.values().next().value;
         return { original: ref, targetNodeId: target.id, confidence: 0.9, resolvedBy: 'import' };
     }
+    /**
+     * Resolve a CFML inheritance reference written as a component path (#1152).
+     * Two forms exist in real code:
+     *
+     * - Dotted: `extends="coldbox.system.web.Controller"` — dots are directory
+     *   separators from the webroot or a CFML mapping. Mappings live in server
+     *   config / Application.cfc, so the leading segments may not exist in the
+     *   repo at all (in the coldbox repo itself the path is `system/web/
+     *   Controller.cfc` — the `coldbox.` root IS the repo). Matched by final
+     *   segment (the class), corroborated right-to-left against the candidate's
+     *   parent directories.
+     * - Relative: `extends="../base"` / `extends="./base"` (the FW/1 style) —
+     *   resolved against the referencing file's own directory.
+     *
+     * Conservative by design: a candidate needs at least one corroborating
+     * directory segment (a dotted path whose only same-named class sits in an
+     * unrelated directory is almost always an out-of-repo library supertype —
+     * mxunit/testbox/coldbox-as-dependency), and a corroboration tie yields no
+     * edge. Directory comparison is case-insensitive (CFML path resolution is);
+     * the class segment itself is matched exactly, which real code satisfies —
+     * dotted paths are written to match the on-disk file name.
+     */
+    resolveCfmlComponentPath(ref) {
+        const cfmlCandidates = (name) => this.context
+            .getNodesByName(name)
+            .filter((n) => (n.kind === 'class' || n.kind === 'interface') &&
+            (n.language === 'cfml' || n.language === 'cfscript'));
+        const norm = (p) => p.replace(/\\/g, '/').toLowerCase();
+        // Relative-path form: `../base`, `./base`, `sub/thing` — resolve against
+        // the referencing file's directory and require an exact (case-insensitive)
+        // file match.
+        if (ref.referenceName.includes('/')) {
+            const rel = ref.referenceName.replace(/\.cfc$/i, '');
+            const fromDir = ref.filePath.replace(/\\/g, '/').split('/').slice(0, -1);
+            const parts = [...fromDir];
+            for (const seg of rel.split('/')) {
+                if (seg === '' || seg === '.')
+                    continue;
+                if (seg === '..') {
+                    if (parts.length === 0)
+                        return null; // escapes the project root
+                    parts.pop();
+                }
+                else {
+                    parts.push(seg);
+                }
+            }
+            const wantPath = norm(parts.join('/') + '.cfc');
+            const className = parts[parts.length - 1];
+            if (!className)
+                return null;
+            const target = cfmlCandidates(className).find((c) => norm(c.filePath) === wantPath);
+            return target
+                ? { original: ref, targetNodeId: target.id, confidence: 0.95, resolvedBy: 'file-path' }
+                : null;
+        }
+        // Dotted form.
+        const segments = ref.referenceName.split('.').map((s) => s.trim()).filter(Boolean);
+        if (segments.length < 2)
+            return null;
+        const className = segments[segments.length - 1];
+        const dirSegments = segments.slice(0, -1);
+        let best = null;
+        let bestScore = 0;
+        let tie = false;
+        for (const cand of cfmlCandidates(className)) {
+            const dirs = cand.filePath.replace(/\\/g, '/').split('/').slice(0, -1);
+            // Count matching directory segments right-to-left: for
+            // `coldbox.system.web.Controller` vs `system/web/Controller.cfc`,
+            // `web` and `system` match, then the repo root ends the run → score 2.
+            let score = 0;
+            while (score < dirSegments.length &&
+                score < dirs.length &&
+                dirSegments[dirSegments.length - 1 - score].toLowerCase() ===
+                    dirs[dirs.length - 1 - score].toLowerCase()) {
+                score++;
+            }
+            if (score > bestScore) {
+                best = cand;
+                bestScore = score;
+                tie = false;
+            }
+            else if (score === bestScore && score > 0) {
+                tie = true;
+            }
+        }
+        if (!best || bestScore === 0 || tie)
+            return null;
+        return { original: ref, targetNodeId: best.id, confidence: 0.9, resolvedBy: 'qualified-name' };
+    }
     /**
      * Resolve a `this.<member>` function-as-value reference (#756/#808) to the
      * ENCLOSING CLASS's own member — never a same-named symbol elsewhere. The