@quolu/lattice 0.43.0 → 0.45.0

package/sensor/dist/resolution/index.js

@@ -262,6 +262,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
@@ -390,14 +416,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 per-context memos assume the same stable window
-        // as the caches above — drop them together.
-        if (this.context)
+        // 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) {
@@ -446,15 +477,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;
@@ -546,20 +623,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;
@@ -645,7 +736,7 @@ class ReferenceResolver {
         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;
@@ -807,10 +898,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:
@@ -827,7 +922,13 @@ class ReferenceResolver {
             const viaImport = this.gateLanguage((0, import_resolver_1.resolveViaImport)(ref, this.context), ref);
             if (viaImport) {
                 const target = this.queries.getNodeById(viaImport.targetNodeId);
-                if (target && (target.kind === 'function' || target.kind === 'method')) {
+                if (target &&
+                    (target.kind === 'function' ||
+                        target.kind === 'method' ||
+                        // Python (#1478): an imported class used as a value (`return
+                        // OrgSerializerFull`) resolves through its import like any
+                        // callback — mirrors matchFunctionRef's bareClassOk.
+                        (ref.language === 'python' && target.kind === 'class'))) {
                     return viaImport;
                 }
             }
@@ -846,7 +947,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
@@ -865,16 +969,27 @@ 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 tImp = this.profileStages ? process.hrtime.bigint() : 0n;
         const importResult = this.gateLanguage((0, import_resolver_1.resolveViaImport)(ref, this.context), ref);
+        if (this.profileStages)
+            this.stageAdd('viaImport', ref, !!importResult, tImp);
         if (importResult) {
             if (importResult.confidence >= 0.9)
                 return importResult;
@@ -896,7 +1011,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
@@ -1221,6 +1339,7 @@ class ReferenceResolver {
      */
     async resolveBatchYielding(batch, maybeYield) {
         this.warmCaches();
+        this.advanceSupertypeGeneration();
         const resolved = [];
         const unresolved = [];
         const byMethod = {};
@@ -1237,7 +1356,7 @@ class ReferenceResolver {
                 bindingForm: raw.bindingForm,
                 importedName: raw.importedName,
             };
-            const result = this.resolveOne(ref);
+            const result = this.resolveOneTimed(ref);
             if (result) {
                 resolved.push(result);
                 byMethod[result.resolvedBy] = (byMethod[result.resolvedBy] || 0) + 1;
@@ -1270,8 +1389,70 @@ class ReferenceResolver {
      * of resolveBatchYielding, minus the main-thread yields (worker threads have
      * no watchdog heartbeat to starve). Results are in input order.
      */
+    /**
+     * LATTICE_SENSOR_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.LATTICE_SENSOR_RESOLVE_PROFILE ? new Map() : null;
+    /**
+     * LATTICE_SENSOR_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.LATTICE_SENSOR_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 LATTICE_SENSOR_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 = {};
@@ -1288,7 +1469,7 @@ class ReferenceResolver {
                 bindingForm: raw.bindingForm,
                 importedName: raw.importedName,
             };
-            const result = this.resolveOne(ref);
+            const result = this.resolveOneTimed(ref);
             if (result) {
                 resolved.push(result);
                 byMethod[result.resolvedBy] = (byMethod[result.resolvedBy] || 0) + 1;
@@ -1333,7 +1514,12 @@ class ReferenceResolver {
     // Sequential fallback on any pool failure. LATTICE_SENSOR_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.
+    // 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
@@ -1342,6 +1528,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.LATTICE_SENSOR_SYNTH_TIMINGS) {
+            console.error(`[pool-timing] backpressure hook: ${parallel?.backpressure ? 'present' : 'absent'}`);
+        }
+        // LATTICE_SENSOR_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.LATTICE_SENSOR_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;
@@ -1358,21 +1557,51 @@ class ReferenceResolver {
         // costs zero wall-clock. Any failure downgrades to sequential permanently.
         let pool = null;
         let poolReady = false;
-        const tPoolStart = Date.now();
-        if (parallel && total >= (0, resolver_pool_1.minRefsForPool)()) {
-            pool = resolver_pool_1.ResolverPool.tryCreate(parallel.dbPath, this.projectRoot);
-            pool?.ready().then(() => {
+        // 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.LATTICE_SENSOR_SYNTH_TIMINGS)
-                    console.error(`[pool-timing] pool ready after ${Date.now() - tPoolStart}ms`);
-            }, () => { void pool?.destroy().catch(() => undefined); pool = null; });
+                    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;
+        // 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
@@ -1433,20 +1662,94 @@ class ReferenceResolver {
             }
             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;
+            }
+            catch { /* keep the indexes; deletes just pay the per-row maintenance */ }
+        }
         try {
             try {
-                let batch = this.queries.getUnresolvedReferencesBatch(0, batchSize);
+                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 skipping exactly batch.length rows in the same rowid
-                    // enumeration yields the following batch.
-                    const nextBatch = this.queries.getUnresolvedReferencesBatch(batch.length, batchSize);
+                    // 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.LATTICE_SENSOR_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.LATTICE_SENSOR_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
@@ -1463,11 +1766,15 @@ class ReferenceResolver {
                     // 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
@@ -1477,28 +1784,33 @@ class ReferenceResolver {
                     // 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) {
-                        this.queries.deleteReferencesByRowIds(resolvedCleanup.rowIds.slice(i, 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) {
-                        this.queries.deleteSpecificResolvedReferences(resolvedCleanup.legacyKeys.slice(i, 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) {
-                        this.queries.markReferencesFailedByRowIds(failedCleanup.byRowId.slice(i, 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) {
-                        this.queries.markReferencesFailed(failedCleanup.legacyKeys.slice(i, i + PERSIST_CHUNK));
+                        removedThisBatch += this.queries.markReferencesFailed(failedCleanup.legacyKeys.slice(i, i + PERSIST_CHUNK));
                         await maybeYield();
                     }
+                    lp('marks', tLp);
                     if (process.env.LATTICE_SENSOR_SYNTH_TIMINGS)
                         console.error(`[pool-timing] batch persist: ${Date.now() - tPersist}ms`);
                     // Aggregate stats
@@ -1530,10 +1842,23 @@ class ReferenceResolver {
                     // 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.)
-                    const remaining = this.queries.getUnresolvedReferencesCount();
-                    if (remaining >= prevRemaining)
-                        break;
-                    prevRemaining = remaining;
+                    // 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;
@@ -1544,11 +1869,23 @@ class ReferenceResolver {
                 // 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.LATTICE_SENSOR_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.LATTICE_SENSOR_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,
@@ -1560,7 +1897,7 @@ class ReferenceResolver {
             // 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);
+                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
@@ -1572,6 +1909,11 @@ class ReferenceResolver {
             if (pool)
                 await pool.destroy().catch(() => undefined);
         }
+        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: [],