akm-cli 0.9.17-alpha.2 → 0.9.17-alpha.4

package/dist/indexer/graph/graph-extraction.js

@@ -7,10 +7,8 @@
  * Walks the primary stash for `memory:` and `knowledge:` assets, asks the
  * configured LLM to extract entities and relations from each one, and
  * persists the result to stash-local SQLite graph tables keyed by stash root.
- * The artifact is consumed by the search
- * pipeline (see `src/indexer/graph/graph-boost.ts`) as a single boost component
- * inside the existing FTS5+boosts loop — there is NO second SearchHit
- * scorer and no parallel ranking track.
+ * The artifact backs `akm show`'s `related` list and curate's support refs
+ * (`src/indexer/graph/graph-related.ts`); it plays no part in search ranking.
  *
  * Disabling — three preconditions must ALL hold for the pass to run:
  *   1. An LLM profile must be configured (no provider = no extraction). When
@@ -24,7 +22,7 @@
  *      Set to `false` to skip just this pass while leaving other passes
  *      that share the same LLM profile enabled.
  *   Toggling any one off does NOT delete the existing persisted graph — the
- *   user keeps the boost component they already have, it just stops
+ *   user keeps the related links they already have, they just stop
  *   refreshing.
  *
  * Locked v1 contract:
@@ -47,39 +45,46 @@ import { concurrentMap } from "../../core/concurrent.js";
 import { getIndexPassConfig, loadConfig, resolveBatchSize } from "../../core/config/config.js";
 import { ConfigError, rethrowIfTestIsolationError } from "../../core/errors.js";
 import { warn, warnVerbose } from "../../core/warn.js";
-import { disposeLoweredExecutionDispatchLease, } from "../../integrations/agent/execution-lowering.js";
+import { assertRunnerCredentials } from "../../integrations/agent/runner-dispatch.js";
 import { isProcessEnabled } from "../../llm/feature-gate.js";
 import * as graphExtract from "../../llm/graph-extract.js";
 import { resolveIndexPassExecution } from "../../llm/index-passes.js";
-import { preflightStructuredLlmRunner } from "../../llm/structured-call.js";
 import { computeBodyHash, getLlmCacheEntriesByRefs, upsertLlmCacheEntry, } from "../../storage/repositories/index-llm-cache-repository.js";
 import { GRAPH_SCHEMA_VERSION } from "../../storage/repositories/index-schema.js";
-import { acknowledgeExtractionQueueEntry, enqueueGraphExtraction, loadStoredGraphSnapshot, peekExtractionQueue, replaceStoredGraph, } from "../db/graph-db.js";
+import { acknowledgeExtractionQueueEntry, enqueueGraphExtraction, loadStoredGraphMeta, loadStoredGraphSnapshot, peekExtractionQueue, replaceStoredGraph, } from "../db/graph-db.js";
 import { walkMarkdownFiles } from "../walk/walker.js";
-import { deduplicateGraph } from "./graph-dedup.js";
 /** Schema version for the persisted artifact — bumps trigger a full rebuild. */
 export const GRAPH_FILE_SCHEMA_VERSION = GRAPH_SCHEMA_VERSION;
-function graphExecutionForContext(ctx, config) {
-    if (Object.hasOwn(ctx, "llmRunner")) {
-        return Object.freeze({ runner: ctx.llmRunner ?? undefined, notices: Object.freeze([]) });
+/**
+ * The frozen execution a graph call runs under: the invocation's own runner
+ * when the caller passed one (it already passed its own gates), otherwise the
+ * configured `graph` pass's. Undefined when the feature gate closes the pass.
+ */
+function selectGraphExecution(holder, config) {
+    if (Object.hasOwn(holder, "llmRunner")) {
+        return {
+            execution: Object.freeze({ runner: holder.llmRunner ?? undefined, notices: Object.freeze([]) }),
+            featureConfig: { ...config, index: { ...config.index, graph: { ...config.index?.graph, enabled: true } } },
+        };
     }
-    return resolveIndexPassExecution("graph", config);
+    if (!isProcessEnabled("index", "graph_extraction", config))
+        return undefined;
+    return { execution: resolveIndexPassExecution("graph", config), featureConfig: config };
 }
-const EMPTY_QUALITY = {
-    consideredFiles: 0,
-    extractedFiles: 0,
-    entityCount: 0,
-    relationCount: 0,
-    extractionCoverage: 0,
-    density: 0,
-};
 const EMPTY_RESULT = {
     considered: 0,
     extracted: 0,
     totalEntities: 0,
     totalRelations: 0,
     written: false,
-    quality: { ...EMPTY_QUALITY },
+    quality: {
+        consideredFiles: 0,
+        extractedFiles: 0,
+        entityCount: 0,
+        relationCount: 0,
+        extractionCoverage: 0,
+        density: 0,
+    },
     telemetry: {
         cacheHits: 0,
         cacheMisses: 0,
@@ -89,22 +94,6 @@ const EMPTY_RESULT = {
     },
     warnings: [],
 };
-function roundMetric(value) {
-    return Number(value.toFixed(4));
-}
-function computeGraphQualityTelemetry(consideredFiles, extractedFiles, entityCount, relationCount) {
-    const extractionCoverage = consideredFiles > 0 ? extractedFiles / consideredFiles : 0;
-    const maxEdges = entityCount > 1 ? (entityCount * (entityCount - 1)) / 2 : 0;
-    const density = maxEdges > 0 ? relationCount / maxEdges : 0;
-    return {
-        consideredFiles,
-        extractedFiles,
-        entityCount,
-        relationCount,
-        extractionCoverage: roundMetric(extractionCoverage),
-        density: roundMetric(density),
-    };
-}
 export const DEFAULT_GRAPH_EXTRACTION_INCLUDE_TYPES = ["memory", "knowledge"];
 /**
  * Max number of lazy-extraction queue rows drained per pass (#624-P3). Bounds
@@ -245,8 +234,6 @@ function isFailedExtractionStatus(status) {
     return status === "failed";
 }
 function loadGraphFile(stashRoot, db) {
-    if (!db)
-        return { files: [] };
     const graph = loadStoredGraphSnapshot(stashRoot, db);
     if (!graph)
         return { files: [] };
@@ -272,87 +259,93 @@ function loadGraphFile(stashRoot, db) {
         ...(graph.telemetry ? { telemetry: graph.telemetry } : {}),
     };
 }
-function mergeGraphNodes(previousNodes, refreshedNodes, candidatePaths) {
-    if (!candidatePaths)
-        return refreshedNodes;
+/**
+ * The stored graph after a run: each refreshed node replaces the stored node
+ * for its path, and every other stored node is kept as it was — files a
+ * scoped run (`candidatePaths`, `topN`) did not select, and files an aborted
+ * run never reached. With `keptPaths`, stored nodes outside it are dropped
+ * (the file left the eligible set); without it, nothing is dropped.
+ */
+function mergeGraphNodes(previousNodes, refreshedNodes, keptPaths) {
     const refreshedByPath = new Map(refreshedNodes.map((node) => [node.path, node]));
     const merged = [];
     for (const node of previousNodes) {
-        if (candidatePaths.has(node.path))
-            continue;
-        merged.push(node);
+        const refreshed = refreshedByPath.get(node.path);
+        if (refreshed) {
+            merged.push(refreshed);
+            refreshedByPath.delete(node.path);
+        }
+        else if (!keptPaths || keptPaths.has(node.path)) {
+            merged.push(node);
+        }
     }
-    for (const node of refreshedNodes)
-        merged.push(refreshedByPath.get(node.path) ?? node);
+    merged.push(...refreshedByPath.values());
     return merged;
 }
+/** A previous node (validated by {@link loadGraphFile}) for this exact body, unless it failed. */
 function reuseGraphNode(previousNodes, candidate, bodyHash) {
     const node = previousNodes.get(candidate.absPath);
-    if (!node)
-        return undefined;
-    if (node.type !== candidate.type)
-        return undefined;
-    if (typeof node.bodyHash !== "string" || node.bodyHash.length === 0)
-        return undefined;
-    if (node.bodyHash !== bodyHash)
+    if (!node || node.type !== candidate.type || node.bodyHash !== bodyHash)
         return undefined;
     if (isFailedExtractionStatus(node.status))
         return undefined;
-    const validated = validateGraphCacheShape({ entities: node.entities, relations: node.relations });
-    if (!validated)
-        return undefined;
     return {
-        entities: validated.entities,
-        relations: validated.relations,
-        confidence: normalizeConfidence(node.confidence),
+        entities: node.entities,
+        relations: node.relations,
+        confidence: node.confidence,
         ...(node.status ? { status: node.status } : {}),
         ...(node.reason ? { reason: node.reason } : {}),
     };
 }
+/**
+ * A file is a cache hit only through `llm_enrichment_cache`, whose variant is
+ * the extractor id. A stored graph node is never reused here: the graph keeps
+ * nodes that older extractors wrote (files a run did not reach), and reusing
+ * one would record another extractor's output as this one's.
+ */
 function planEligibleGraphExtractions(args) {
-    const { eligible, db, reEnrich, cacheVariant, previousNodes, canReusePreviousGraph } = args;
-    const bodyHashes = eligible.map((candidate) => computeBodyHash(candidate.body));
-    const cacheEntries = db && !reEnrich
-        ? getLlmCacheEntriesByRefs(db, eligible.map((candidate) => candidate.absPath), cacheVariant)
-        : new Map();
-    return eligible.map((candidate, index) => {
-        const bodyHash = bodyHashes[index] ?? "";
-        if (!reEnrich && db) {
-            const entry = cacheEntries.get(candidate.absPath);
-            if (entry?.bodyHash === bodyHash) {
-                try {
-                    const cached = validateGraphCacheShape(JSON.parse(entry.resultJson));
-                    if (cached && !isFailedExtractionStatus(cached.status)) {
-                        return { kind: "cache-hit", candidate, bodyHash, cached, persistCache: false };
-                    }
-                }
-                catch {
-                    // Corrupt cache rows are immutable model plans for this pass.
+    const { eligible, db, reEnrich, cacheVariant } = args;
+    const cacheEntries = reEnrich
+        ? new Map()
+        : getLlmCacheEntriesByRefs(db, eligible.map((candidate) => candidate.absPath), cacheVariant);
+    return eligible.map((candidate) => {
+        const bodyHash = computeBodyHash(candidate.body);
+        if (reEnrich)
+            return { kind: "model", candidate, bodyHash };
+        const entry = cacheEntries.get(candidate.absPath);
+        if (entry?.bodyHash === bodyHash) {
+            try {
+                const cached = validateGraphCacheShape(JSON.parse(entry.resultJson));
+                if (cached && !isFailedExtractionStatus(cached.status)) {
+                    return { kind: "cache-hit", candidate, bodyHash, cached };
                 }
             }
-        }
-        if (!reEnrich && (!db || canReusePreviousGraph)) {
-            const cached = reuseGraphNode(previousNodes, candidate, bodyHash);
-            if (cached)
-                return { kind: "cache-hit", candidate, bodyHash, cached, persistCache: Boolean(db) };
+            catch {
+                // A corrupt cache row is a miss.
+            }
         }
         return { kind: "model", candidate, bodyHash };
     });
 }
-function graphRecordFromCachePlan(plan) {
+function extractionRecord(candidate, bodyHash, shape) {
     return {
-        absPath: plan.candidate.absPath,
-        type: plan.candidate.type,
-        bodyHash: plan.bodyHash,
-        entities: plan.cached.entities,
-        relations: plan.cached.relations,
-        ...(plan.cached.confidence !== undefined ? { confidence: plan.cached.confidence } : {}),
-        ...(plan.cached.status ? { status: plan.cached.status } : {}),
-        ...(plan.cached.reason ? { reason: plan.cached.reason } : {}),
+        absPath: candidate.absPath,
+        type: candidate.type,
+        bodyHash,
+        entities: shape.entities,
+        relations: shape.relations,
+        ...(shape.confidence !== undefined ? { confidence: shape.confidence } : {}),
+        ...(shape.status ? { status: shape.status } : {}),
+        ...(shape.reason ? { reason: shape.reason } : {}),
     };
 }
+/**
+ * Run the planned extractions in chunks of `batchSize`: cache hits are taken
+ * as-is, and each chunk's model plans go to the provider in one
+ * `extractGraphFromBodies` call (a one-body call is the per-asset path).
+ */
 async function extractGraphBatches(args) {
-    const { plans, batchSize, signal, db, cacheVariant, telemetry, llmRunner, lease, featureConfig, onFallback, abortState, batchState, runtimeTelemetry, onNotices, reportProgress, maxChunksPerAsset, } = args;
+    const { plans, batchSize, signal, db, cacheVariant, telemetry, llmRunner, featureConfig, onFallback, abortState, batchState, runtimeTelemetry, onNotices, reportProgress, maxChunksPerAsset, } = args;
     const results = new Array(plans.length).fill(undefined);
     const chunkStarts = [];
     for (let start = 0; start < plans.length; start += batchSize)
@@ -363,23 +356,18 @@ async function extractGraphBatches(args) {
             return;
         const chunk = plans.slice(start, start + batchSize);
         const reportChunkProgress = () => {
-            for (let j = 0; j < chunk.length; j++) {
-                const plan = chunk[j];
-                if (plan)
-                    reportProgress(plan.candidate.absPath, results[start + j]);
-            }
+            for (const [j, plan] of chunk.entries())
+                reportProgress(plan.candidate.absPath, results[start + j]);
         };
-        for (let index = 0; index < chunk.length; index++) {
-            const plan = chunk[index];
-            if (!plan || plan.kind !== "cache-hit")
+        const modelPlans = [];
+        for (const [offset, plan] of chunk.entries()) {
+            if (plan.kind === "model") {
+                modelPlans.push({ plan, offset });
                 continue;
-            telemetry.cacheHits += 1;
-            results[start + index] = graphRecordFromCachePlan(plan);
-            if (db && plan.persistCache && !isFailedExtractionStatus(plan.cached.status)) {
-                upsertLlmCacheEntry(db, plan.candidate.absPath, plan.bodyHash, JSON.stringify(plan.cached), cacheVariant);
             }
+            telemetry.cacheHits += 1;
+            results[start + offset] = extractionRecord(plan.candidate, plan.bodyHash, plan.cached);
         }
-        const modelPlans = chunk.filter((plan) => plan.kind === "model");
         if (modelPlans.length === 0 || abortState.aborted) {
             reportChunkProgress();
             return;
@@ -387,11 +375,10 @@ async function extractGraphBatches(args) {
         telemetry.cacheMisses += modelPlans.length;
         let batchExtractions;
         try {
-            batchExtractions = await graphExtract.extractGraphFromBodies(llmRunner, modelPlans.map((plan) => plan.candidate.body), signal, featureConfig, onFallback, {
+            batchExtractions = await graphExtract.extractGraphFromBodies(llmRunner, modelPlans.map(({ plan }) => plan.candidate.body), signal, featureConfig, onFallback, {
                 batchState,
                 telemetry: runtimeTelemetry,
                 onNotices,
-                ...(lease ? { lease } : {}),
                 ...(maxChunksPerAsset != null ? { maxChunksPerAsset } : {}),
             });
         }
@@ -402,14 +389,10 @@ async function extractGraphBatches(args) {
             }
             throw error;
         }
-        let llmIndex = 0;
         let dispatchHadResult = false;
         let dispatchAllFailed = true;
-        for (let index = 0; index < chunk.length; index++) {
-            const plan = chunk[index];
-            if (!plan || plan.kind !== "model")
-                continue;
-            const extraction = batchExtractions[llmIndex++];
+        for (const [i, { plan, offset }] of modelPlans.entries()) {
+            const extraction = batchExtractions[i];
             if (!extraction)
                 continue;
             const cacheShape = {
@@ -420,17 +403,11 @@ async function extractGraphBatches(args) {
                 ...(extraction.reason ? { reason: extraction.reason } : {}),
             };
             dispatchHadResult = true;
-            if (!isFailedExtractionStatus(cacheShape.status))
+            if (!isFailedExtractionStatus(cacheShape.status)) {
                 dispatchAllFailed = false;
-            if (db && !isFailedExtractionStatus(cacheShape.status)) {
                 upsertLlmCacheEntry(db, plan.candidate.absPath, plan.bodyHash, JSON.stringify(cacheShape), cacheVariant);
             }
-            results[start + index] = {
-                absPath: plan.candidate.absPath,
-                type: plan.candidate.type,
-                bodyHash: plan.bodyHash,
-                ...cacheShape,
-            };
+            results[start + offset] = extractionRecord(plan.candidate, plan.bodyHash, cacheShape);
         }
         // One attempt per `extractGraphFromBodies` dispatch (this chunk's batch
         // call), not one per file it covers — mirrors consolidate.ts's
@@ -455,101 +432,54 @@ function readCurrentGraphBodyHash(filePath) {
 }
 function planQueuedGraphExtractions(args) {
     const { db, stashRoot, previousNodes, signal, reEnrich } = args;
-    if (!db)
-        return [];
     return peekExtractionQueue(db, stashRoot, GRAPH_EXTRACTION_QUEUE_DRAIN_LIMIT).map((queued) => {
-        if (signal?.aborted) {
-            return {
-                kind: "deferred",
-                filePath: queued.filePath,
-                queuedBodyHash: queued.bodyHash,
-                priority: queued.priority,
-            };
-        }
-        let raw;
-        try {
-            raw = fs.readFileSync(queued.filePath, "utf8");
-        }
-        catch {
-            return { kind: "discard", filePath: queued.filePath, queuedBodyHash: queued.bodyHash, priority: queued.priority };
-        }
-        const body = parseFrontmatter(raw).content.trim();
-        if (!body) {
-            return { kind: "discard", filePath: queued.filePath, queuedBodyHash: queued.bodyHash, priority: queued.priority };
-        }
-        const currentBodyHash = computeBodyHash(body);
+        const base = { filePath: queued.filePath, queuedBodyHash: queued.bodyHash, priority: queued.priority };
+        if (signal?.aborted)
+            return { kind: "deferred", ...base };
+        const currentBodyHash = readCurrentGraphBodyHash(queued.filePath);
+        if (!currentBodyHash)
+            return { kind: "discard", ...base };
         const type = inferGraphTypeForPath(stashRoot, queued.filePath) ?? "memory";
-        if (!reEnrich && reuseGraphNode(previousNodes, { absPath: queued.filePath, type }, currentBodyHash)) {
-            return {
-                kind: "hit",
-                filePath: queued.filePath,
-                queuedBodyHash: queued.bodyHash,
-                currentBodyHash,
-                priority: queued.priority,
-            };
-        }
-        return {
-            kind: "model",
-            filePath: queued.filePath,
-            queuedBodyHash: queued.bodyHash,
-            currentBodyHash,
-            priority: queued.priority,
-        };
+        const hit = !reEnrich && reuseGraphNode(previousNodes, { absPath: queued.filePath, type }, currentBodyHash);
+        return { kind: hit ? "hit" : "model", ...base, currentBodyHash };
     });
 }
 async function executeQueuedGraphPlans(args) {
-    const { plans, db, stashRoot, featureConfig, signal, llmRunner, lease, onNotices } = args;
-    if (!db)
-        return { graphChanged: false, acknowledgements: [] };
+    const { plans, db, stashRoot, featureConfig, signal, llmRunner, onNotices } = args;
     let graphChanged = false;
     const acknowledgements = [];
     for (const plan of plans) {
         if (signal?.aborted || plan.kind === "deferred")
             break;
-        if (plan.kind === "discard") {
-            const currentBodyHash = readCurrentGraphBodyHash(plan.filePath);
-            if (currentBodyHash) {
-                enqueueGraphExtraction(db, stashRoot, plan.filePath, currentBodyHash, plan.priority);
-                continue;
-            }
-            acknowledgements.push({ filePath: plan.filePath, queuedBodyHash: plan.queuedBodyHash });
-            continue;
-        }
-        if (plan.kind === "hit") {
-            const currentBodyHash = readCurrentGraphBodyHash(plan.filePath);
-            if (currentBodyHash !== plan.currentBodyHash) {
-                if (currentBodyHash)
-                    enqueueGraphExtraction(db, stashRoot, plan.filePath, currentBodyHash, plan.priority);
-                continue;
-            }
-            acknowledgements.push({ filePath: plan.filePath, queuedBodyHash: plan.queuedBodyHash });
-            continue;
-        }
+        // The body this plan settled: none for a discard (the file was gone or empty).
+        let settledBodyHash;
         if (plan.kind === "model") {
             const outcome = await extractGraphForSingleFileRevision(db, stashRoot, plan.filePath, {
                 config: featureConfig,
                 signal,
                 llmRunner,
-                lease,
                 onNotices,
             });
             if (!outcome.written)
                 continue;
             graphChanged = true;
-            const currentBodyHash = readCurrentGraphBodyHash(plan.filePath);
-            if (currentBodyHash !== outcome.bodyHash) {
-                if (currentBodyHash)
-                    enqueueGraphExtraction(db, stashRoot, plan.filePath, currentBodyHash, plan.priority);
-                continue;
-            }
+            settledBodyHash = outcome.bodyHash;
+        }
+        else if (plan.kind === "hit") {
+            settledBodyHash = plan.currentBodyHash;
+        }
+        // A body that changed since it was planned goes back on the queue.
+        const currentBodyHash = readCurrentGraphBodyHash(plan.filePath);
+        if (currentBodyHash !== settledBodyHash) {
+            if (currentBodyHash)
+                enqueueGraphExtraction(db, stashRoot, plan.filePath, currentBodyHash, plan.priority);
+            continue;
         }
         acknowledgements.push({ filePath: plan.filePath, queuedBodyHash: plan.queuedBodyHash });
     }
     return { graphChanged, acknowledgements };
 }
 function acknowledgeQueuedGraphPlans(db, stashRoot, execution) {
-    if (!db)
-        return;
     for (const intent of execution.acknowledgements) {
         acknowledgeExtractionQueueEntry(db, stashRoot, intent.filePath, intent.queuedBodyHash);
     }
@@ -571,18 +501,16 @@ function acknowledgeQueuedGraphPlans(db, stashRoot, execution) {
  * If any of the three is missing or `false`, this function short-circuits
  * to an empty no-op result, leaving any existing persisted graph untouched.
  *
- * When `config.index.graph.graphExtractionBatchSize > 1`, eligible files are
- * chunked into batches and each chunk is processed with a single LLM call via
- * `extractGraphFromBodies`. Default batch size is 1 (one call per asset —
- * preserves existing behaviour, fully opt-in).
+ * Eligible files are chunked by the resolved batch size
+ * (`graphExtractionBatchSize`) and each chunk is one `extractGraphFromBodies`
+ * call; a batch size of 1 is one call per asset.
  */
 export async function runGraphExtractionPass(ctx) {
     const { config, sources, signal, db, reEnrich, onProgress, options = {} } = ctx;
-    const invocationOwnsRunner = Object.hasOwn(ctx, "llmRunner");
-    // Gate 1 — feature gate via isProcessEnabled, which reads the 0.8.0 path
-    // (selected strategy's processes.graphExtraction.enabled). Defaults to
-    // enabled when the key is absent.
-    if (!invocationOwnsRunner && !isProcessEnabled("index", "graph_extraction", config))
+    // Gate 1 — the feature gate (selected strategy's
+    // processes.graphExtraction.enabled, default enabled).
+    const selection = selectGraphExecution(ctx, config);
+    if (!selection)
         return { ...EMPTY_RESULT };
     const noticesByKey = new Map();
     const onNotices = (notices) => {
@@ -595,9 +523,8 @@ export async function runGraphExtractionPass(ctx) {
     });
     // Gate 2 — per-pass opt-out (#208). Retain the whole frozen resolution so
     // selection-time lowering notices cannot be separated from the runner.
-    const execution = graphExecutionForContext(ctx, config);
-    onNotices(execution.notices);
-    const llmRunner = execution.runner;
+    onNotices(selection.execution.notices);
+    const llmRunner = selection.execution.runner;
     if (!llmRunner) {
         const reason = getIndexPassConfig(config.index, "graph")?.enabled === false
             ? "index.graph.enabled is false"
@@ -605,9 +532,7 @@ export async function runGraphExtractionPass(ctx) {
         warnVerbose(`graph extraction: skipped because ${reason}.`);
         return emptyResult();
     }
-    const featureConfig = invocationOwnsRunner
-        ? { ...config, index: { ...config.index, graph: { ...config.index?.graph, enabled: true } } }
-        : config;
+    const { featureConfig } = selection;
     // The pass only writes to the primary (working) stash. Read-only caches
     // (git, npm, website) are deliberately untouched — the graph artifact for
     // those sources would be clobbered by the next sync().
@@ -616,13 +541,15 @@ export async function runGraphExtractionPass(ctx) {
         warnVerbose("graph extraction: skipped because no primary stash source is available.");
         return emptyResult();
     }
+    if (!db) {
+        warn("graph extraction: no database handle available; skipping graph persistence.");
+        return emptyResult();
+    }
     const includeTypes = options.includeTypes ?? getGraphExtractionIncludeTypes(config);
     let previousGraph = loadGraphFile(primary.path, db);
     const previousNodes = new Map(previousGraph.files.map((node) => [node.path, node]));
     const batchSize = resolveBatchSize(options.batchSize ?? getIndexPassConfig(config.index, "graph")?.graphExtractionBatchSize, llmRunner.connection.contextLength);
     const extractorId = getGraphExtractorId({ model: llmRunner.connection.model, batchSize, includeTypes });
-    const cacheVariant = extractorId;
-    const canReusePreviousGraph = previousGraph.telemetry?.extractorId === extractorId;
     const queuePlans = planQueuedGraphExtractions({
         db,
         stashRoot: primary.path,
@@ -631,286 +558,193 @@ export async function runGraphExtractionPass(ctx) {
         reEnrich,
     });
     const queuedPaths = new Set(queuePlans.map((plan) => plan.filePath));
-    let eligible = collectEligibleFiles(primary.path, includeTypes).filter((candidate) => (!options.candidatePaths || options.candidatePaths.has(candidate.absPath)) && !queuedPaths.has(candidate.absPath));
-    // P2 (#624): when topN is set and a DB is available, rank the (already
-    // candidate-filtered) eligible set by utility_scores DESC and keep only the
-    // top-N. Default (topN unset) is byte-identical to today — no ranking query
-    // is issued and the eligible set is untouched. Ranking composes WITH the
-    // candidatePaths filter: scoped-then-ranked-then-sliced.
-    if (db && options.topN != null && options.topN >= 0) {
-        eligible = rankCandidatesByUtility(db, eligible, primary.path).slice(0, options.topN);
+    const scan = collectEligibleFiles(primary.path, includeTypes);
+    // The stored nodes this run keeps without touching them: every eligible file
+    // (outside candidatePaths or topN, or never reached before an abort) and every
+    // file the queue handled. Only a node whose file left the eligible set — gone,
+    // emptied, inferred, or of a type no longer included — is dropped, and an
+    // incomplete scan drops nothing.
+    const keptPaths = scan.complete
+        ? new Set([
+            ...scan.files.map((file) => file.absPath),
+            ...queuePlans.filter((plan) => plan.kind !== "discard").map((plan) => plan.filePath),
+        ])
+        : undefined;
+    let eligible = scan.files.filter((candidate) => (!options.candidatePaths || options.candidatePaths.has(candidate.absPath)) && !queuedPaths.has(candidate.absPath));
+    // P2 (#624): when topN is set, rank the (already candidate-filtered)
+    // eligible set by utility_scores DESC and keep only the top-N. Unset issues
+    // no ranking query. Ranking composes WITH the candidatePaths filter:
+    // scoped-then-ranked-then-sliced.
+    if (options.topN != null && options.topN >= 0) {
+        eligible = rankCandidatesByUtility(db, eligible).slice(0, options.topN);
     }
     const considered = eligible.length;
-    const eligiblePlans = planEligibleGraphExtractions({
-        eligible,
-        db,
-        reEnrich,
-        cacheVariant,
-        previousNodes,
-        canReusePreviousGraph,
-    });
-    const queueNeedsModel = queuePlans.some((plan) => plan.kind === "model");
-    const eligibleNeedsModel = !signal?.aborted && eligiblePlans.some((plan) => plan.kind === "model");
+    const eligiblePlans = planEligibleGraphExtractions({ eligible, db, reEnrich, cacheVariant: extractorId });
     if (signal?.aborted)
         return emptyResult();
     // Validate exactly once iff classification found real model work. Queue
     // acknowledgements, cache writes, and graph replacement all happen after
     // this boundary, so a missing credential cannot partially mutate a batch.
-    const dispatchLease = queueNeedsModel || eligibleNeedsModel ? await preflightStructuredLlmRunner(llmRunner) : undefined;
-    try {
-        const queueExecution = await executeQueuedGraphPlans({
-            plans: queuePlans,
-            db,
-            stashRoot: primary.path,
-            featureConfig,
-            signal,
-            llmRunner,
-            lease: dispatchLease,
-            onNotices,
-        });
-        if (queueExecution.graphChanged) {
-            previousGraph = loadGraphFile(primary.path, db);
-        }
-        if (considered === 0) {
-            acknowledgeQueuedGraphPlans(db, primary.path, queueExecution);
-            const scoped = options.candidatePaths ? ` matching ${options.candidatePaths.size} candidate path(s)` : "";
-            warnVerbose(`graph extraction: skipped because no eligible files${scoped} were found under ${primary.path}. ` +
-                `includeTypes=${includeTypes.join(",")}`);
-            return emptyResult();
-        }
-        const nodes = [];
-        let totalEntities = 0;
-        let totalRelations = 0;
-        let processed = 0;
-        let extracted = 0;
-        onProgress?.({ processed, total: considered, extracted, totalEntities, totalRelations });
-        const reportProgress = (currentPath, result) => {
-            processed += 1;
-            if (result) {
-                if (result.entities.length > 0)
-                    extracted += 1;
-                totalEntities += result.entities.length;
-                totalRelations += result.relations.length;
-            }
-            onProgress?.({
-                processed,
-                total: considered,
-                extracted,
-                totalEntities,
-                totalRelations,
-                currentPath,
-            });
-        };
-        const extractionRunId = crypto.randomUUID();
-        const telemetry = {
-            extractorId,
-            extractionRunId,
-            model: llmRunner.connection.model,
-            promptVersion: graphExtract.GRAPH_EXTRACT_PROMPT_VERSION,
-            batchSize,
-            cacheHits: 0,
-            cacheMisses: 0,
-            truncationCount: 0,
-            failureCount: 0,
-            htmlErrorCount: 0,
-            retryAttempts: 0,
-            nonArrayBatchFailures: 0,
-        };
-        const runtimeTelemetry = {
-            truncationCount: 0,
-            failureCount: 0,
-            htmlErrorCount: 0,
-            retryAttempts: 0,
-            filteredGenericEntities: 0,
-            filteredInvalidRelations: 0,
-            filteredLowConfidenceRelations: 0,
-            contextBatchRetries: 0,
-            nonArrayBatchFailures: 0,
-        };
-        const batchState = {
-            batchingDisabled: false,
-            nonArrayBatchFailures: 0,
-        };
-        const abortState = { attempts: 0, failures: 0, aborted: false };
-        warnVerbose(`graph extraction: starting for ${considered} eligible file(s) under ${primary.path}; ` +
-            `includeTypes=${includeTypes.join(",")}, batchSize=${batchSize}, concurrency=${llmRunner.connection.concurrency ?? 1}, ` +
-            `reEnrich=${reEnrich === true}, candidateScoped=${options.candidatePaths ? "true" : "false"}.`);
-        const onFallback = (evt) => {
-            warn(`[akm] LLM fallback for ${evt.feature}: ${evt.reason}`);
-        };
-        let extractionResults;
-        let configFailure;
-        if (batchSize <= 1) {
-            // ── Original per-asset path (with incremental cache) ─────────────────
-            extractionResults = await concurrentMap(eligiblePlans, async (plan) => {
-                const { candidate, bodyHash } = plan;
-                if (signal?.aborted) {
-                    reportProgress(candidate.absPath, undefined);
-                    return undefined;
-                }
-                let cached;
-                if (plan.kind === "cache-hit") {
-                    telemetry.cacheHits += 1;
-                    cached = plan.cached;
-                    if (db && plan.persistCache && !isFailedExtractionStatus(cached.status)) {
-                        upsertLlmCacheEntry(db, candidate.absPath, bodyHash, JSON.stringify(cached), cacheVariant);
-                    }
-                }
-                else {
-                    if (abortState.aborted) {
-                        reportProgress(candidate.absPath, undefined);
-                        return undefined;
-                    }
-                    telemetry.cacheMisses += 1;
-                    let extraction;
-                    try {
-                        extraction = await graphExtract.extractGraphFromBody(llmRunner, candidate.body, signal, featureConfig, onFallback, {
-                            batchState,
-                            telemetry: runtimeTelemetry,
-                            onNotices,
-                            ...(dispatchLease ? { lease: dispatchLease } : {}),
-                            ...(options.maxChunksPerAsset != null ? { maxChunksPerAsset: options.maxChunksPerAsset } : {}),
-                        });
-                    }
-                    catch (err) {
-                        if (err instanceof ConfigError) {
-                            configFailure ??= err;
-                            return undefined;
-                        }
-                        throw err;
-                    }
-                    cached = {
-                        entities: extraction.entities,
-                        relations: extraction.relations,
-                        ...(extraction.confidence !== undefined ? { confidence: extraction.confidence } : {}),
-                        ...(extraction.status ? { status: extraction.status } : {}),
-                        ...(extraction.reason ? { reason: extraction.reason } : {}),
-                    };
-                    recordGraphExtractionAttempt(abortState, isFailedExtractionStatus(cached.status));
-                    if (db && !isFailedExtractionStatus(cached.status)) {
-                        upsertLlmCacheEntry(db, candidate.absPath, bodyHash, JSON.stringify(cached), cacheVariant);
-                    }
-                }
-                const result = {
-                    absPath: candidate.absPath,
-                    type: candidate.type,
-                    bodyHash,
-                    entities: cached.entities,
-                    relations: cached.relations,
-                    ...(cached.confidence !== undefined ? { confidence: cached.confidence } : {}),
-                    ...(cached.status ? { status: cached.status } : {}),
-                    ...(cached.reason ? { reason: cached.reason } : {}),
-                };
-                reportProgress(candidate.absPath, result);
-                return result;
-            }, 
-            // Caller-set connection concurrency or 1: `resolveLlmEngineUse` does
-            // not forward `engines.<name>.concurrency`, so config cannot raise this.
-            llmRunner.connection.concurrency ?? 1);
-        }
-        else {
-            const batch = await extractGraphBatches({
-                plans: eligiblePlans,
-                batchSize,
-                signal,
-                db,
-                cacheVariant,
-                telemetry,
-                llmRunner,
-                lease: dispatchLease,
-                featureConfig,
-                onFallback,
-                batchState,
-                runtimeTelemetry,
-                abortState,
-                onNotices,
-                reportProgress,
-                ...(options.maxChunksPerAsset != null ? { maxChunksPerAsset: options.maxChunksPerAsset } : {}),
-            });
-            extractionResults = batch.results;
-            configFailure ??= batch.configFailure;
-        }
-        if (configFailure)
-            throw configFailure;
+    if ([...queuePlans, ...eligiblePlans].some((plan) => plan.kind === "model"))
+        assertRunnerCredentials(llmRunner);
+    const queueExecution = await executeQueuedGraphPlans({
+        plans: queuePlans,
+        db,
+        stashRoot: primary.path,
+        featureConfig,
+        signal,
+        llmRunner,
+        onNotices,
+    });
+    if (queueExecution.graphChanged) {
+        previousGraph = loadGraphFile(primary.path, db);
+    }
+    if (considered === 0) {
         acknowledgeQueuedGraphPlans(db, primary.path, queueExecution);
-        for (const result of extractionResults) {
-            if (!result)
-                continue;
-            nodes.push({
-                path: result.absPath,
-                type: result.type,
-                bodyHash: result.bodyHash,
-                entities: [...new Set(result.entities.map((entity) => entity.trim()).filter(Boolean))],
-                relations: result.relations
-                    .map((r) => ({
-                    from: r.from.trim(),
-                    to: r.to.trim(),
-                    ...(r.type ? { type: r.type.trim() } : {}),
-                    ...(normalizeConfidence(r.confidence) !== undefined
-                        ? { confidence: normalizeConfidence(r.confidence) }
-                        : {}),
-                }))
-                    .filter((relation) => relation.from && relation.to),
-                ...(normalizeConfidence(result.confidence) !== undefined
-                    ? { confidence: normalizeConfidence(result.confidence) }
-                    : {}),
-                status: result.status ?? (result.entities.length > 0 ? "extracted" : "empty"),
-                reason: result.reason ?? (result.entities.length > 0 ? "none" : "no_graph_content"),
-                extractionRunId,
-            });
+        const scoped = options.candidatePaths ? ` matching ${options.candidatePaths.size} candidate path(s)` : "";
+        warnVerbose(`graph extraction: skipped because no eligible files${scoped} were found under ${primary.path}. ` +
+            `includeTypes=${includeTypes.join(",")}`);
+        return emptyResult();
+    }
+    let totalEntities = 0;
+    let totalRelations = 0;
+    let processed = 0;
+    let extracted = 0;
+    onProgress?.({ processed, total: considered, extracted, totalEntities, totalRelations });
+    const reportProgress = (currentPath, result) => {
+        processed += 1;
+        if (result) {
+            if (result.entities.length > 0)
+                extracted += 1;
+            totalEntities += result.entities.length;
+            totalRelations += result.relations.length;
         }
-        const queuedNodes = options.candidatePaths
-            ? []
-            : previousGraph.files.filter((node) => queuePlans.some((plan) => plan.filePath === node.path && plan.kind !== "discard") &&
-                !nodes.some((candidate) => candidate.path === node.path));
-        const mergedNodes = mergeGraphNodes(previousGraph.files, [...queuedNodes, ...nodes], options.candidatePaths);
-        const assetRefs = mergedNodes.map((node) => node.path);
-        const deduped = deduplicateGraph(mergedNodes.map((node) => ({ entities: node.entities, relations: node.relations })), assetRefs);
-        telemetry.truncationCount = runtimeTelemetry.truncationCount ?? 0;
-        telemetry.truncatedChunks = runtimeTelemetry.truncatedChunks ?? 0;
-        telemetry.failureCount = runtimeTelemetry.failureCount ?? 0;
-        telemetry.htmlErrorCount = runtimeTelemetry.htmlErrorCount ?? 0;
-        telemetry.retryAttempts = runtimeTelemetry.retryAttempts ?? 0;
-        telemetry.nonArrayBatchFailures = runtimeTelemetry.nonArrayBatchFailures ?? 0;
-        telemetry.aborted = abortState.aborted;
-        const qualityConsidered = mergedNodes.length;
-        const qualityExtracted = mergedNodes.filter((node) => node.status === "extracted" && node.entities.length > 0).length;
-        const quality = computeGraphQualityTelemetry(qualityConsidered, qualityExtracted, deduped.entities.length, deduped.relations.length);
-        const warnings = buildLowQualityWarnings(quality, telemetry);
-        if (abortState.message)
-            warnings.push(abortState.message);
-        for (const warning of warnings)
-            warnVerbose(`graph extraction quality: ${warning}`);
-        const graph = {
-            schemaVersion: GRAPH_FILE_SCHEMA_VERSION,
-            generatedAt: new Date().toISOString(),
-            stashRoot: primary.path,
-            files: mergedNodes,
-            entities: deduped.entities,
-            relations: deduped.relations,
-            quality,
-            telemetry,
-        };
-        const written = writeGraphFile(primary.path, graph, db);
-        warnVerbose(`graph extraction: ${written ? "persisted" : "did not persist"} graph for ${primary.path}; ` +
-            `considered=${considered}, extractedThisRun=${extracted}, storedFiles=${mergedNodes.length}, ` +
-            `entities=${deduped.entities.length}, relations=${deduped.relations.length}, coverage=${quality.extractionCoverage}.`);
-        return {
-            considered,
+        onProgress?.({
+            processed,
+            total: considered,
             extracted,
             totalEntities,
             totalRelations,
-            written,
-            quality,
-            telemetry,
-            warnings,
-            ...(noticesByKey.size > 0 ? { notices: Object.freeze([...noticesByKey.values()]) } : {}),
-        };
-    }
-    finally {
-        if (dispatchLease)
-            disposeLoweredExecutionDispatchLease(dispatchLease);
-    }
+            currentPath,
+        });
+    };
+    const extractionRunId = crypto.randomUUID();
+    const telemetry = {
+        extractorId,
+        extractionRunId,
+        model: llmRunner.connection.model,
+        promptVersion: graphExtract.GRAPH_EXTRACT_PROMPT_VERSION,
+        batchSize,
+        cacheHits: 0,
+        cacheMisses: 0,
+        truncationCount: 0,
+        failureCount: 0,
+        htmlErrorCount: 0,
+        retryAttempts: 0,
+        nonArrayBatchFailures: 0,
+    };
+    const runtimeTelemetry = {
+        truncationCount: 0,
+        failureCount: 0,
+        htmlErrorCount: 0,
+        retryAttempts: 0,
+        filteredGenericEntities: 0,
+        filteredInvalidRelations: 0,
+        filteredLowConfidenceRelations: 0,
+        contextBatchRetries: 0,
+        nonArrayBatchFailures: 0,
+    };
+    const abortState = { attempts: 0, failures: 0, aborted: false };
+    warnVerbose(`graph extraction: starting for ${considered} eligible file(s) under ${primary.path}; ` +
+        `includeTypes=${includeTypes.join(",")}, batchSize=${batchSize}, concurrency=${llmRunner.connection.concurrency ?? 1}, ` +
+        `reEnrich=${reEnrich === true}, candidateScoped=${options.candidatePaths ? "true" : "false"}.`);
+    const { results, configFailure } = await extractGraphBatches({
+        plans: eligiblePlans,
+        batchSize,
+        signal,
+        db,
+        cacheVariant: extractorId,
+        telemetry,
+        llmRunner,
+        featureConfig,
+        onFallback: (evt) => warn(`[akm] LLM fallback for ${evt.feature}: ${evt.reason}`),
+        batchState: { batchingDisabled: false, nonArrayBatchFailures: 0 },
+        runtimeTelemetry,
+        abortState,
+        onNotices,
+        reportProgress,
+        ...(options.maxChunksPerAsset != null ? { maxChunksPerAsset: options.maxChunksPerAsset } : {}),
+    });
+    if (configFailure)
+        throw configFailure;
+    acknowledgeQueuedGraphPlans(db, primary.path, queueExecution);
+    // A failed attempt says nothing about the file, so a stored node for it stays
+    // as it was; only a file with no stored node records the failure.
+    const storedPaths = new Set(previousGraph.files.map((node) => node.path));
+    const nodes = results.flatMap((result) => !result || (isFailedExtractionStatus(result.status) && storedPaths.has(result.absPath))
+        ? []
+        : [toGraphNode(result, extractionRunId)]);
+    telemetry.truncationCount = runtimeTelemetry.truncationCount ?? 0;
+    telemetry.truncatedChunks = runtimeTelemetry.truncatedChunks ?? 0;
+    telemetry.failureCount = runtimeTelemetry.failureCount ?? 0;
+    telemetry.htmlErrorCount = runtimeTelemetry.htmlErrorCount ?? 0;
+    telemetry.retryAttempts = runtimeTelemetry.retryAttempts ?? 0;
+    telemetry.nonArrayBatchFailures = runtimeTelemetry.nonArrayBatchFailures ?? 0;
+    telemetry.aborted = abortState.aborted;
+    const graph = buildGraphFile(primary.path, mergeGraphNodes(previousGraph.files, nodes, keptPaths), telemetry);
+    const written = writeGraphFile(db, graph);
+    const quality = loadStoredGraphMeta(primary.path, db)?.quality ?? EMPTY_RESULT.quality;
+    const warnings = buildLowQualityWarnings(quality, telemetry);
+    if (abortState.message)
+        warnings.push(abortState.message);
+    for (const warning of warnings)
+        warnVerbose(`graph extraction quality: ${warning}`);
+    warnVerbose(`graph extraction: ${written ? "persisted" : "did not persist"} graph for ${primary.path}; ` +
+        `considered=${considered}, extractedThisRun=${extracted}, storedFiles=${quality.consideredFiles}, ` +
+        `entities=${quality.entityCount}, relations=${quality.relationCount}, coverage=${quality.extractionCoverage}.`);
+    return {
+        considered,
+        extracted,
+        totalEntities,
+        totalRelations,
+        written,
+        quality,
+        telemetry,
+        warnings,
+        ...(noticesByKey.size > 0 ? { notices: Object.freeze([...noticesByKey.values()]) } : {}),
+    };
+}
+/** The persisted node for one extraction outcome (entities and relations trimmed, deduplicated). */
+function toGraphNode(record, extractionRunId) {
+    const confidence = normalizeConfidence(record.confidence);
+    return {
+        path: record.absPath,
+        type: record.type,
+        bodyHash: record.bodyHash,
+        entities: [...new Set(record.entities.map((entity) => entity.trim()).filter(Boolean))],
+        relations: record.relations
+            .map((r) => ({
+            from: r.from.trim(),
+            to: r.to.trim(),
+            ...(r.type ? { type: r.type.trim() } : {}),
+            ...(normalizeConfidence(r.confidence) !== undefined ? { confidence: normalizeConfidence(r.confidence) } : {}),
+        }))
+            .filter((relation) => relation.from && relation.to),
+        ...(confidence !== undefined ? { confidence } : {}),
+        status: record.status ?? (record.entities.length > 0 ? "extracted" : "empty"),
+        reason: record.reason ?? (record.entities.length > 0 ? "none" : "no_graph_content"),
+        extractionRunId,
+    };
+}
+/** The graph snapshot to store for `files`; its counts are derived from the stored rows on write. */
+function buildGraphFile(stashRoot, files, telemetry) {
+    return {
+        schemaVersion: GRAPH_FILE_SCHEMA_VERSION,
+        generatedAt: new Date().toISOString(),
+        stashRoot,
+        files,
+        ...(telemetry ? { telemetry } : {}),
+    };
 }
 /**
  * Infer the asset type (`memory`, `knowledge`, …) for a path from the stash
@@ -944,7 +778,6 @@ function inferGraphTypeForPath(stashRoot, absPath) {
  * skip (missing file, empty body, unknown type, no model, or extraction error).
  */
 async function extractGraphForSingleFileRevision(db, stashRoot, filePath, opts) {
-    let ownedLease;
     try {
         // Re-read from disk — never trust a stale queued body.
         let raw;
@@ -963,83 +796,34 @@ async function extractGraphForSingleFileRevision(db, stashRoot, filePath, opts)
         // Extract — via the injected seam, or the real per-asset path.
         let extraction;
         if (opts?.llmOverride) {
-            const out = await opts.llmOverride(body);
-            extraction = {
-                entities: out.entities,
-                relations: out.relations,
-                ...(out.confidence !== undefined ? { confidence: out.confidence } : {}),
-            };
+            extraction = await opts.llmOverride(body);
         }
         else {
-            const config = opts?.config ?? loadConfig();
-            const invocationOwnsRunner = Object.hasOwn(opts ?? {}, "llmRunner");
-            if (!invocationOwnsRunner && !isProcessEnabled("index", "graph_extraction", config))
+            const selection = selectGraphExecution(opts ?? {}, opts?.config ?? loadConfig());
+            if (!selection)
                 return { written: false };
-            const execution = Object.hasOwn(opts ?? {}, "llmRunner")
-                ? Object.freeze({ runner: opts?.llmRunner ?? undefined, notices: Object.freeze([]) })
-                : resolveIndexPassExecution("graph", config);
-            opts?.onNotices?.(execution.notices);
-            const llmRunner = execution.runner;
+            opts?.onNotices?.(selection.execution.notices);
+            const llmRunner = selection.execution.runner;
             if (!llmRunner)
                 return { written: false }; // model-available guard
-            const featureConfig = invocationOwnsRunner
-                ? { ...config, index: { ...config.index, graph: { ...config.index?.graph, enabled: true } } }
-                : config;
-            const lease = opts?.lease ?? (await preflightStructuredLlmRunner(llmRunner));
-            if (!opts?.lease)
-                ownedLease = lease;
-            const result = await graphExtract.extractGraphFromBody(llmRunner, body, opts?.signal, featureConfig, undefined, {
-                ...(opts?.onNotices ? { onNotices: opts.onNotices } : {}),
-                lease,
-            });
-            extraction = {
-                entities: result.entities,
-                relations: result.relations,
-                ...(result.confidence !== undefined ? { confidence: result.confidence } : {}),
-            };
+            extraction = await graphExtract.extractGraphFromBody(llmRunner, body, opts?.signal, selection.featureConfig, undefined, { ...(opts?.onNotices ? { onNotices: opts.onNotices } : {}) });
         }
+        // A single-file refresh records only entities, relations and confidence;
+        // its status follows from the entities that survive trimming.
         const entities = [...new Set(extraction.entities.map((e) => e.trim()).filter(Boolean))];
-        const relations = extraction.relations
-            .map((r) => ({
-            from: r.from.trim(),
-            to: r.to.trim(),
-            ...(r.type ? { type: r.type.trim() } : {}),
-            ...(normalizeConfidence(r.confidence) !== undefined ? { confidence: normalizeConfidence(r.confidence) } : {}),
-        }))
-            .filter((r) => r.from && r.to);
-        const node = {
-            path: filePath,
+        const node = toGraphNode({
+            absPath: filePath,
             type,
             bodyHash: effectiveHash,
             entities,
-            relations,
-            ...(normalizeConfidence(extraction.confidence) !== undefined
-                ? { confidence: normalizeConfidence(extraction.confidence) }
-                : {}),
-            status: entities.length > 0 ? "extracted" : "empty",
-            reason: entities.length > 0 ? "none" : "no_graph_content",
-            extractionRunId: crypto.randomUUID(),
-        };
-        // Merge with the previously-stored nodes, scoping the refresh to JUST this
-        // path so other files' rows are preserved (and graph_meta counts refresh).
+            relations: extraction.relations,
+            ...(extraction.confidence !== undefined ? { confidence: extraction.confidence } : {}),
+        }, crypto.randomUUID());
+        // Merge with the previously-stored nodes, replacing JUST this path so other
+        // files' rows are preserved (and graph_meta counts refresh).
         const previousGraph = loadGraphFile(stashRoot, db);
-        const candidatePaths = new Set([filePath]);
-        const mergedNodes = mergeGraphNodes(previousGraph.files, [node], candidatePaths);
-        const assetRefs = mergedNodes.map((n) => n.path);
-        const deduped = deduplicateGraph(mergedNodes.map((n) => ({ entities: n.entities, relations: n.relations })), assetRefs);
-        const qualityExtracted = mergedNodes.filter((n) => n.status === "extracted" && n.entities.length > 0).length;
-        const quality = computeGraphQualityTelemetry(mergedNodes.length, qualityExtracted, deduped.entities.length, deduped.relations.length);
-        const graph = {
-            schemaVersion: GRAPH_FILE_SCHEMA_VERSION,
-            generatedAt: new Date().toISOString(),
-            stashRoot,
-            files: mergedNodes,
-            entities: deduped.entities,
-            relations: deduped.relations,
-            quality,
-            ...(previousGraph.telemetry ? { telemetry: previousGraph.telemetry } : {}),
-        };
-        return writeGraphFile(stashRoot, graph, db) ? { written: true, bodyHash: effectiveHash } : { written: false };
+        const graph = buildGraphFile(stashRoot, mergeGraphNodes(previousGraph.files, [node]), previousGraph.telemetry);
+        return writeGraphFile(db, graph) ? { written: true, bodyHash: effectiveHash } : { written: false };
     }
     catch (err) {
         if (err instanceof ConfigError)
@@ -1052,12 +836,8 @@ async function extractGraphForSingleFileRevision(db, stashRoot, filePath, opts)
         warn(`graph extraction: failed to extract graph for ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
         return { written: false };
     }
-    finally {
-        if (ownedLease)
-            disposeLoweredExecutionDispatchLease(ownedLease);
-    }
 }
-export async function extractGraphForSingleFile(db, stashRoot, filePath, _bodyHash, opts) {
+export async function extractGraphForSingleFile(db, stashRoot, filePath, opts) {
     return (await extractGraphForSingleFileRevision(db, stashRoot, filePath, opts)).written;
 }
 // ── Eligible-file detection ─────────────────────────────────────────────────
@@ -1068,9 +848,7 @@ export async function extractGraphForSingleFile(db, stashRoot, filePath, _bodyHa
  * The join is READ-ONLY (`entries.file_path = candidate.absPath`, then
  * `entries.id -> utility_scores.entry_id`) and does NOT re-couple the graph
  * rows to `entries`. It reads the GLOBAL `utility_scores` table (not the
- * per-scope `utility_scores_scoped`), so ranking is corpus-wide; `stashRoot`
- * is accepted for call-site symmetry/future scoping but is not used to filter
- * (the global table has no `stash_root` column).
+ * per-scope `utility_scores_scoped`), so ranking is corpus-wide.
  *
  * Candidates with no matching `entries` row, or an entry with no
  * `utility_scores` row, get an effective utility of 0 (LEFT JOIN + COALESCE)
@@ -1083,9 +861,7 @@ export async function extractGraphForSingleFile(db, stashRoot, filePath, _bodyHa
  *
  * Exported for direct unit testing.
  */
-export function rankCandidatesByUtility(db, candidates, _stashRoot) {
-    // Cannot rank without a DB → return the input unranked rather than throw.
-    // Keeps the DB-less code path (reuse-from-memory) working when topN is set.
+export function rankCandidatesByUtility(db, candidates) {
     if (!db || candidates.length === 0)
         return candidates;
     const utilityByPath = new Map();
@@ -1122,10 +898,14 @@ export function rankCandidatesByUtility(db, candidates, _stashRoot) {
  * are already derived summaries, with no additional internal graph structure worth
  * extracting.
  *
+ * `complete` is false when a directory or a candidate file could not be read,
+ * so the result may be missing eligible files.
+ *
  * Exported for direct unit testing.
  */
 export function collectEligibleFiles(stashRoot, includeTypes = [...DEFAULT_GRAPH_EXTRACTION_INCLUDE_TYPES]) {
     const out = [];
+    let complete = true;
     for (const rawType of includeTypes) {
         const type = rawType.trim().toLowerCase();
         if (!SUPPORTED_GRAPH_EXTRACTION_INCLUDE_TYPES.has(type))
@@ -1138,6 +918,7 @@ export function collectEligibleFiles(stashRoot, includeTypes = [...DEFAULT_GRAPH
             continue;
         const walked = walkMarkdownFiles(dir);
         if (!walked.complete) {
+            complete = false;
             warn(`graph extraction: directory scan under ${dir} is incomplete — some files may be missing`);
         }
         for (const filePath of walked.files) {
@@ -1146,6 +927,7 @@ export function collectEligibleFiles(stashRoot, includeTypes = [...DEFAULT_GRAPH
                 raw = fs.readFileSync(filePath, "utf8");
             }
             catch (err) {
+                complete = false;
                 warn(`graph extraction: failed to read candidate file ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
                 continue;
             }
@@ -1160,23 +942,19 @@ export function collectEligibleFiles(stashRoot, includeTypes = [...DEFAULT_GRAPH
             out.push({ absPath: filePath, type, body });
         }
     }
-    return out;
+    return { files: out, complete };
 }
 // ── Persistence ─────────────────────────────────────────────────────────────
 /**
  * Persist graph rows into the SQLite index DB.
  */
-function writeGraphFile(stashRoot, graph, db) {
-    if (!db) {
-        warn("graph extraction: no database handle available; skipping graph persistence.");
-        return false;
-    }
+function writeGraphFile(db, graph) {
     try {
         replaceStoredGraph(db, graph);
         return true;
     }
     catch (err) {
-        warn(`graph extraction: failed to persist graph for ${stashRoot}: ${err instanceof Error ? err.message : String(err)}`);
+        warn(`graph extraction: failed to persist graph for ${graph.stashRoot}: ${err instanceof Error ? err.message : String(err)}`);
         return false;
     }
 }