akm-cli 0.9.1 → 0.9.2-alpha.2

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

@@ -14,8 +14,8 @@
  *
  * Disabling — three preconditions must ALL hold for the pass to run:
  *   1. An LLM profile must be configured (no provider = no extraction). When
- *      absent, `resolveIndexPassLLM("graph", config)` returns `undefined`
- *      and the pass short-circuits.
+ *      absent, `resolveIndexPassExecution("graph", config).runner` is
+ *      `undefined` and the pass short-circuits.
  *   2. The selected strategy's `processes.graphExtraction.enabled !== false`
  *      — the feature-gate layer (historically v1 spec §14, since superseded by
  *      the 0.8.0 profile shape). Set to `false` to block the pass at the
@@ -28,7 +28,8 @@
  *   refreshing.
  *
  * Locked v1 contract:
- *   - LLM access is exclusively via `resolveIndexPassLLM("graph", config)`.
+ *   - LLM access is exclusively via the frozen runner returned by
+ *     `resolveIndexPassExecution("graph", config)`.
  *   - The graph rows are an indexer artifact, NOT a user-visible
  *     asset. It does not have an asset ref, does not appear in search
  *     hits, and is not addressable via `akm show`. The persisted artifact
@@ -44,18 +45,26 @@ import { stashDirFor } from "../../core/asset/asset-placement.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { concurrentMap } from "../../core/concurrent.js";
 import { getIndexPassConfig, loadConfig, resolveBatchSize } from "../../core/config/config.js";
-import { rethrowIfTestIsolationError } from "../../core/errors.js";
+import { ConfigError, rethrowIfTestIsolationError } from "../../core/errors.js";
 import { warn, warnVerbose } from "../../core/warn.js";
+import { disposeLoweredExecutionDispatchLease, } from "../../integrations/agent/execution-lowering.js";
 import { isProcessEnabled } from "../../llm/feature-gate.js";
 import * as graphExtract from "../../llm/graph-extract.js";
-import { resolveIndexPassLLM } from "../../llm/index-passes.js";
-import { computeBodyHash, getLlmCacheEntriesByRefs, getLlmCacheEntry, upsertLlmCacheEntry, } from "../../storage/repositories/index-llm-cache-repository.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 { drainExtractionQueue, loadStoredGraphSnapshot, replaceStoredGraph } from "../db/graph-db.js";
+import { acknowledgeExtractionQueueEntry, enqueueGraphExtraction, 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([]) });
+    }
+    return resolveIndexPassExecution("graph", config);
+}
 const EMPTY_QUALITY = {
     consideredFiles: 0,
     extractedFiles: 0,
@@ -254,14 +263,244 @@ function reuseGraphNode(previousNodes, candidate, bodyHash) {
         ...(node.reason ? { reason: node.reason } : {}),
     };
 }
+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)
+                        return { kind: "cache-hit", candidate, bodyHash, cached, persistCache: false };
+                }
+                catch {
+                    // Corrupt cache rows are immutable model plans for this pass.
+                }
+            }
+        }
+        if (!reEnrich && (!db || canReusePreviousGraph)) {
+            const cached = reuseGraphNode(previousNodes, candidate, bodyHash);
+            if (cached)
+                return { kind: "cache-hit", candidate, bodyHash, cached, persistCache: Boolean(db) };
+        }
+        return { kind: "model", candidate, bodyHash };
+    });
+}
+function graphRecordFromCachePlan(plan) {
+    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 } : {}),
+    };
+}
+async function extractGraphBatches(args) {
+    const { plans, batchSize, signal, db, cacheVariant, telemetry, llmRunner, lease, featureConfig, onFallback, batchState, runtimeTelemetry, onNotices, reportProgress, } = args;
+    const results = new Array(plans.length).fill(undefined);
+    const chunkStarts = [];
+    for (let start = 0; start < plans.length; start += batchSize)
+        chunkStarts.push(start);
+    let configFailure;
+    await concurrentMap(chunkStarts, async (start) => {
+        if (signal?.aborted)
+            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 (let index = 0; index < chunk.length; index++) {
+            const plan = chunk[index];
+            if (!plan || plan.kind !== "cache-hit")
+                continue;
+            telemetry.cacheHits += 1;
+            results[start + index] = graphRecordFromCachePlan(plan);
+            if (db && plan.persistCache) {
+                upsertLlmCacheEntry(db, plan.candidate.absPath, plan.bodyHash, JSON.stringify(plan.cached), cacheVariant);
+            }
+        }
+        const modelPlans = chunk.filter((plan) => plan.kind === "model");
+        if (modelPlans.length === 0) {
+            reportChunkProgress();
+            return;
+        }
+        telemetry.cacheMisses += modelPlans.length;
+        let batchExtractions;
+        try {
+            batchExtractions = await graphExtract.extractGraphFromBodies(llmRunner, modelPlans.map((plan) => plan.candidate.body), signal, featureConfig, onFallback, {
+                batchState,
+                telemetry: runtimeTelemetry,
+                onNotices,
+                ...(lease ? { lease } : {}),
+            });
+        }
+        catch (error) {
+            if (error instanceof ConfigError) {
+                configFailure ??= error;
+                return;
+            }
+            throw error;
+        }
+        let llmIndex = 0;
+        for (let index = 0; index < chunk.length; index++) {
+            const plan = chunk[index];
+            if (!plan || plan.kind !== "model")
+                continue;
+            const extraction = batchExtractions[llmIndex++];
+            if (!extraction)
+                continue;
+            const cacheShape = {
+                entities: extraction.entities,
+                relations: extraction.relations,
+                ...(extraction.confidence !== undefined ? { confidence: extraction.confidence } : {}),
+                ...(extraction.status ? { status: extraction.status } : {}),
+                ...(extraction.reason ? { reason: extraction.reason } : {}),
+            };
+            if (db) {
+                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,
+            };
+        }
+        reportChunkProgress();
+    }, llmRunner.connection.concurrency ?? 1);
+    return { results, ...(configFailure ? { configFailure } : {}) };
+}
+function readCurrentGraphBodyHash(filePath) {
+    try {
+        const body = parseFrontmatter(fs.readFileSync(filePath, "utf8")).content.trim();
+        return body ? computeBodyHash(body) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+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 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,
+        };
+    });
+}
+async function executeQueuedGraphPlans(args) {
+    const { plans, db, stashRoot, featureConfig, signal, llmRunner, lease, onNotices } = args;
+    if (!db)
+        return { graphChanged: false, acknowledgements: [] };
+    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;
+        }
+        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;
+            }
+        }
+        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);
+    }
+}
 /**
  * Top-level entry point. Returns a no-op result when the pass is disabled.
  *
  * Three preconditions — ALL must hold for the pass to run:
  *
  *   1. **Provider configured** — an LLM profile must be selectable. Without a
- *      configured provider, `resolveIndexPassLLM("graph", config)` returns
- *      `undefined` (the pass cannot run because there is no model to call).
+ *      configured provider, `resolveIndexPassExecution("graph", config).runner`
+ *      is `undefined` (the pass cannot run because there is no model to call).
  *   2. **Feature gate** — the selected strategy's `processes.graphExtraction.enabled`
  *      (defaults to `true`). When `false`, no network call may issue regardless
  *      of per-pass settings.
@@ -278,23 +517,34 @@ function reuseGraphNode(previousNodes, candidate, bodyHash) {
  */
 export async function runGraphExtractionPass(ctx) {
     const { config, sources, signal, db, reEnrich, onProgress, options = {} } = ctx;
-    const invocationOwnsConnection = Object.hasOwn(ctx, "llmConfig");
+    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 (!invocationOwnsConnection && !isProcessEnabled("index", "graph_extraction", config))
+    if (!invocationOwnsRunner && !isProcessEnabled("index", "graph_extraction", config))
         return { ...EMPTY_RESULT };
-    // Gate 2 — per-pass opt-out (#208). Returns the resolved llm config or
-    // `undefined` when the pass should not run.
-    const llmConfig = Object.hasOwn(ctx, "llmConfig") ? ctx.llmConfig : resolveIndexPassLLM("graph", config);
-    if (!llmConfig) {
+    const noticesByKey = new Map();
+    const onNotices = (notices) => {
+        for (const notice of notices)
+            noticesByKey.set(JSON.stringify(notice), notice);
+    };
+    const emptyResult = () => ({
+        ...EMPTY_RESULT,
+        ...(noticesByKey.size > 0 ? { notices: Object.freeze([...noticesByKey.values()]) } : {}),
+    });
+    // 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;
+    if (!llmRunner) {
         const reason = getIndexPassConfig(config.index, "graph")?.enabled === false
             ? "index.graph.enabled is false"
             : "no LLM engine is configured";
         warnVerbose(`graph extraction: skipped because ${reason}.`);
-        return { ...EMPTY_RESULT };
+        return emptyResult();
     }
-    const featureConfig = invocationOwnsConnection
+    const featureConfig = invocationOwnsRunner
         ? { ...config, index: { ...config.index, graph: { ...config.index?.graph, enabled: true } } }
         : config;
     // The pass only writes to the primary (working) stash. Read-only caches
@@ -303,27 +553,24 @@ export async function runGraphExtractionPass(ctx) {
     const primary = sources[0];
     if (!primary) {
         warnVerbose("graph extraction: skipped because no primary stash source is available.");
-        return { ...EMPTY_RESULT };
-    }
-    // #624-P3: drain the lazy-extraction queue BEFORE the ranked sweep, highest
-    // priority first. Queued paths are extracted individually (per-file merge,
-    // other files untouched) so they are processed even when they fall outside
-    // the normal candidate set. Default (empty queue) is a byte-identical no-op:
-    // drainExtractionQueue returns [] and the loop body never runs.
-    if (db) {
-        const drained = drainExtractionQueue(db, primary.path, GRAPH_EXTRACTION_QUEUE_DRAIN_LIMIT);
-        for (const queued of drained) {
-            if (signal?.aborted)
-                break;
-            await extractGraphForSingleFile(db, primary.path, queued.filePath, queued.bodyHash, {
-                config: featureConfig,
-                signal,
-                llmConfig,
-            });
-        }
+        return emptyResult();
     }
     const includeTypes = options.includeTypes ?? getGraphExtractionIncludeTypes(config);
-    let eligible = collectEligibleFiles(primary.path, includeTypes).filter((candidate) => !options.candidatePaths || options.candidatePaths.has(candidate.absPath));
+    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,
+        previousNodes,
+        signal,
+        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
@@ -333,341 +580,263 @@ export async function runGraphExtractionPass(ctx) {
         eligible = rankCandidatesByUtility(db, eligible, primary.path).slice(0, options.topN);
     }
     const considered = eligible.length;
-    if (considered === 0) {
-        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 { ...EMPTY_RESULT };
-    }
-    const previousGraph = loadGraphFile(primary.path, db);
-    const previousNodes = new Map(previousGraph.files.map((node) => [node.path, node]));
-    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 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");
+    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,
         });
-    };
-    // Resolve the effective batch size. Falls back to
-    // DEFAULT_GRAPH_EXTRACTION_BATCH_SIZE (4) when unset, and clamps against
-    // `llm.contextLength` if the model's context window is configured.
-    const batchSize = resolveBatchSize(options.batchSize ?? getIndexPassConfig(config.index, "graph")?.graphExtractionBatchSize, llmConfig.contextLength);
-    const extractionRunId = crypto.randomUUID();
-    const extractorId = getGraphExtractorId({ model: llmConfig.model, batchSize, includeTypes });
-    const cacheVariant = extractorId;
-    const telemetry = {
-        extractorId,
-        extractionRunId,
-        model: llmConfig.model,
-        promptVersion: graphExtract.GRAPH_EXTRACT_PROMPT_VERSION,
-        batchSize,
-        cacheHits: 0,
-        cacheMisses: 0,
-        truncationCount: 0,
-        failureCount: 0,
-        htmlErrorCount: 0,
-        retryAttempts: 0,
-        nonArrayBatchFailures: 0,
-    };
-    const canReusePreviousGraph = previousGraph.telemetry?.extractorId === extractorId;
-    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,
-    };
-    warnVerbose(`graph extraction: starting for ${considered} eligible file(s) under ${primary.path}; ` +
-        `includeTypes=${includeTypes.join(",")}, batchSize=${batchSize}, concurrency=${llmConfig.concurrency ?? 1}, ` +
-        `reEnrich=${reEnrich === true}, candidateScoped=${options.candidatePaths ? "true" : "false"}.`);
-    const onFallback = (evt) => {
-        warn(`[akm] LLM fallback for ${evt.feature}: ${evt.reason}`);
-    };
-    let extractionResults;
-    if (batchSize <= 1) {
-        // ── Original per-asset path (with incremental cache) ─────────────────
-        extractionResults = await concurrentMap(eligible, async (candidate) => {
-            if (signal?.aborted) {
-                reportProgress(candidate.absPath, undefined);
-                return undefined;
-            }
-            const bodyHash = computeBodyHash(candidate.body);
-            let cached;
-            if (db) {
-                if (!(reEnrich ?? false)) {
-                    const cacheEntry = getLlmCacheEntry(db, candidate.absPath, bodyHash, cacheVariant);
-                    if (cacheEntry) {
-                        try {
-                            cached = validateGraphCacheShape(JSON.parse(cacheEntry.resultJson));
-                            if (cached)
-                                telemetry.cacheHits += 1;
-                        }
-                        catch {
-                            cached = undefined;
-                        }
-                    }
-                }
-            }
-            else if (!(reEnrich ?? false)) {
-                // No DB — best-effort reuse from the previous in-memory graph.
-                cached = reuseGraphNode(previousNodes, candidate, bodyHash);
-            }
-            if (!cached && !(reEnrich ?? false) && canReusePreviousGraph) {
-                const reused = reuseGraphNode(previousNodes, candidate, bodyHash);
-                if (reused) {
-                    cached = reused;
-                    if (db) {
-                        upsertLlmCacheEntry(db, candidate.absPath, bodyHash, JSON.stringify(reused), cacheVariant);
-                    }
-                    telemetry.cacheHits += 1;
-                }
-            }
-            if (!cached) {
-                telemetry.cacheMisses += 1;
-                const extraction = await graphExtract.extractGraphFromBody(llmConfig, candidate.body, signal, featureConfig, onFallback, { batchState, telemetry: runtimeTelemetry });
-                cached = {
-                    entities: extraction.entities,
-                    relations: extraction.relations,
-                    ...(extraction.confidence !== undefined ? { confidence: extraction.confidence } : {}),
-                    ...(extraction.status ? { status: extraction.status } : {}),
-                    ...(extraction.reason ? { reason: extraction.reason } : {}),
-                };
-                if (db) {
-                    upsertLlmCacheEntry(db, candidate.absPath, bodyHash, JSON.stringify(cached), cacheVariant);
-                }
+        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;
             }
-            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.
-        llmConfig.concurrency ?? 1);
-    }
-    else {
-        // ── Batched path (with incremental cache) ────────────────────────────
-        // Chunk eligible files into groups of `batchSize` and call
-        // `extractGraphFromBodies` once per chunk. Cache hits are resolved
-        // before chunking so they don't consume LLM tokens in the batch call.
-        const rawResults = new Array(eligible.length).fill(undefined);
-        const chunkStarts = [];
-        for (let start = 0; start < eligible.length; start += batchSize)
-            chunkStarts.push(start);
-        await concurrentMap(chunkStarts, async (start) => {
-            if (signal?.aborted)
-                return;
-            const chunk = eligible.slice(start, start + batchSize);
-            const reportChunkProgress = () => {
-                for (let j = 0; j < chunk.length; j++) {
-                    const candidate = chunk[j];
-                    if (!candidate)
-                        continue;
-                    reportProgress(candidate.absPath, rawResults[start + j]);
-                }
-            };
-            // Pre-resolve cache hits for this chunk; track which positions need LLM.
-            const bodyHashes = chunk.map((c) => computeBodyHash(c.body));
-            // Batch the cache lookup: one IN(...) query for the whole chunk instead
-            // of N individual SELECTs. The map covers every ref in this chunk that
-            // has any cached row; the per-position hash check happens below.
-            const chunkCache = db && !reEnrich
-                ? getLlmCacheEntriesByRefs(db, chunk.map((c) => c.absPath), cacheVariant)
-                : new Map();
-            const needsLlm = chunk.map((c, j) => {
-                if (!db || reEnrich)
-                    return true;
-                const cached = chunkCache.get(c.absPath);
-                // Hash mismatch → body changed, treat as cache miss.
-                if (!cached || cached.bodyHash !== (bodyHashes[j] ?? ""))
-                    return true;
-                try {
-                    const parsed = validateGraphCacheShape(JSON.parse(cached.resultJson));
-                    if (!parsed)
-                        return true;
-                    telemetry.cacheHits += 1;
-                    rawResults[start + j] = {
-                        absPath: c.absPath,
-                        type: c.type,
-                        bodyHash: bodyHashes[j] ?? "",
-                        entities: parsed.entities,
-                        relations: parsed.relations,
-                        ...(parsed.confidence !== undefined ? { confidence: parsed.confidence } : {}),
-                        ...(parsed.status ? { status: parsed.status } : {}),
-                        ...(parsed.reason ? { reason: parsed.reason } : {}),
-                    };
-                    return false;
-                }
-                catch {
-                    return true;
-                }
+            onProgress?.({
+                processed,
+                total: considered,
+                extracted,
+                totalEntities,
+                totalRelations,
+                currentPath,
             });
-            // Secondary incremental path: reuse previous graph nodes when the body hash
-            // still matches and DB cache is missing/stale/unavailable.
-            if (!(reEnrich ?? false) && canReusePreviousGraph) {
-                for (let j = 0; j < chunk.length; j++) {
-                    if (!needsLlm[j])
-                        continue;
-                    const candidate = chunk[j];
-                    if (!candidate)
-                        continue;
-                    const reused = reuseGraphNode(previousNodes, candidate, bodyHashes[j] ?? "");
-                    if (!reused)
-                        continue;
+        };
+        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,
+        };
+        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;
-                    rawResults[start + j] = {
-                        absPath: candidate.absPath,
-                        type: candidate.type,
-                        bodyHash: bodyHashes[j] ?? "",
-                        entities: reused.entities,
-                        relations: reused.relations,
-                        ...(reused.confidence !== undefined ? { confidence: reused.confidence } : {}),
-                        ...(reused.status ? { status: reused.status } : {}),
-                        ...(reused.reason ? { reason: reused.reason } : {}),
-                    };
-                    if (db) {
-                        upsertLlmCacheEntry(db, candidate.absPath, bodyHashes[j] ?? "", JSON.stringify(reused), cacheVariant);
+                    cached = plan.cached;
+                    if (db && plan.persistCache) {
+                        upsertLlmCacheEntry(db, candidate.absPath, bodyHash, JSON.stringify(cached), cacheVariant);
                     }
-                    needsLlm[j] = false;
                 }
-            }
-            const uncachedChunk = chunk.filter((_, j) => needsLlm[j]);
-            if (uncachedChunk.length === 0) {
-                reportChunkProgress();
-                return;
-            }
-            const bodies = uncachedChunk.map((c) => c.body);
-            telemetry.cacheMisses += uncachedChunk.length;
-            // extractGraphFromBodies always returns an array of the same length
-            // as bodies (it falls back per-asset for any missing indices).
-            const batchExtractions = await graphExtract.extractGraphFromBodies(llmConfig, bodies, signal, featureConfig, onFallback, { batchState, telemetry: runtimeTelemetry });
-            // Map LLM results back to original positions and write cache entries.
-            let llmIdx = 0;
-            for (let j = 0; j < chunk.length; j++) {
-                if (!needsLlm[j])
-                    continue;
-                const candidate = chunk[j];
-                const extraction = batchExtractions[llmIdx++];
-                if (!candidate || !extraction)
-                    continue;
-                if (db) {
-                    upsertLlmCacheEntry(db, candidate.absPath, bodyHashes[j] ?? "", JSON.stringify({
+                else {
+                    telemetry.cacheMisses += 1;
+                    let extraction;
+                    try {
+                        extraction = await graphExtract.extractGraphFromBody(llmRunner, candidate.body, signal, featureConfig, onFallback, {
+                            batchState,
+                            telemetry: runtimeTelemetry,
+                            onNotices,
+                            ...(dispatchLease ? { lease: dispatchLease } : {}),
+                        });
+                    }
+                    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 } : {}),
-                    }), cacheVariant);
+                    };
+                    if (db) {
+                        upsertLlmCacheEntry(db, candidate.absPath, bodyHash, JSON.stringify(cached), cacheVariant);
+                    }
                 }
-                rawResults[start + j] = {
+                const result = {
                     absPath: candidate.absPath,
                     type: candidate.type,
-                    bodyHash: bodyHashes[j] ?? "",
-                    entities: extraction.entities,
-                    relations: extraction.relations,
-                    ...(extraction.confidence !== undefined ? { confidence: extraction.confidence } : {}),
-                    ...(extraction.status ? { status: extraction.status } : {}),
-                    ...(extraction.reason ? { reason: extraction.reason } : {}),
+                    bodyHash,
+                    entities: cached.entities,
+                    relations: cached.relations,
+                    ...(cached.confidence !== undefined ? { confidence: cached.confidence } : {}),
+                    ...(cached.status ? { status: cached.status } : {}),
+                    ...(cached.reason ? { reason: cached.reason } : {}),
                 };
-            }
-            reportChunkProgress();
-        }, llmConfig.concurrency ?? 1);
-        extractionResults = rawResults;
+                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,
+                onNotices,
+                reportProgress,
+            });
+            extractionResults = batch.results;
+            configFailure ??= batch.configFailure;
+        }
+        if (configFailure)
+            throw configFailure;
+        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 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.failureCount = runtimeTelemetry.failureCount ?? 0;
+        telemetry.htmlErrorCount = runtimeTelemetry.htmlErrorCount ?? 0;
+        telemetry.retryAttempts = runtimeTelemetry.retryAttempts ?? 0;
+        telemetry.nonArrayBatchFailures = runtimeTelemetry.nonArrayBatchFailures ?? 0;
+        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);
+        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,
+            extracted,
+            totalEntities,
+            totalRelations,
+            written,
+            quality,
+            telemetry,
+            warnings,
+            ...(noticesByKey.size > 0 ? { notices: Object.freeze([...noticesByKey.values()]) } : {}),
+        };
     }
-    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,
-        });
+    finally {
+        if (dispatchLease)
+            disposeLoweredExecutionDispatchLease(dispatchLease);
     }
-    const mergedNodes = mergeGraphNodes(previousGraph.files, 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.failureCount = runtimeTelemetry.failureCount ?? 0;
-    telemetry.htmlErrorCount = runtimeTelemetry.htmlErrorCount ?? 0;
-    telemetry.retryAttempts = runtimeTelemetry.retryAttempts ?? 0;
-    telemetry.nonArrayBatchFailures = runtimeTelemetry.nonArrayBatchFailures ?? 0;
-    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);
-    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,
-        extracted,
-        totalEntities,
-        totalRelations,
-        written,
-        quality,
-        telemetry,
-        warnings,
-    };
 }
 /**
  * Infer the asset type (`memory`, `knowledge`, …) for a path from the stash
@@ -691,16 +860,17 @@ function inferGraphTypeForPath(stashRoot, absPath) {
  *
  * Re-reads the body from disk at call time (the queued body_hash is NOT trusted
  * blindly — the file may have been deleted or changed since enqueue) and skips
- * silently (returns `false`) when the file is gone or empty. Resolves the LLM
- * via {@link resolveIndexPassLLM} (model-available guard: returns `false` when
- * no provider is configured) UNLESS `opts.llmOverride` is supplied, in which
- * case the override is the extractor seam (used by tests and by callers that
- * already hold a resolved model).
+ * silently (returns `false`) when the file is gone or empty. Resolves a frozen
+ * LLM execution via {@link resolveIndexPassExecution} (model-available guard:
+ * returns `false` when no provider is configured) UNLESS a caller supplies
+ * `opts.llmRunner` or `opts.llmOverride`. Those seams let a command reuse an
+ * invocation-owned selection or provide a test extractor without re-resolving.
  *
  * Returns `true` when a graph row was written for the file, `false` on any
  * skip (missing file, empty body, unknown type, no model, or extraction error).
  */
-export async function extractGraphForSingleFile(db, stashRoot, filePath, bodyHash, opts) {
+async function extractGraphForSingleFileRevision(db, stashRoot, filePath, opts) {
+    let ownedLease;
     try {
         // Re-read from disk — never trust a stale queued body.
         let raw;
@@ -708,14 +878,14 @@ export async function extractGraphForSingleFile(db, stashRoot, filePath, bodyHas
             raw = fs.readFileSync(filePath, "utf8");
         }
         catch {
-            return false; // file gone / unreadable → silent skip
+            return { written: false }; // file gone / unreadable → silent skip
         }
         const parsed = parseFrontmatter(raw);
         const body = parsed.content.trim();
         if (!body)
-            return false;
+            return { written: false };
         const type = inferGraphTypeForPath(stashRoot, filePath) ?? "memory";
-        const effectiveHash = bodyHash ?? computeBodyHash(body);
+        const effectiveHash = computeBodyHash(body);
         // Extract — via the injected seam, or the real per-asset path.
         let extraction;
         if (opts?.llmOverride) {
@@ -728,16 +898,26 @@ export async function extractGraphForSingleFile(db, stashRoot, filePath, bodyHas
         }
         else {
             const config = opts?.config ?? loadConfig();
-            const invocationOwnsConnection = Object.hasOwn(opts ?? {}, "llmConfig");
-            if (!invocationOwnsConnection && !isProcessEnabled("index", "graph_extraction", config))
-                return false;
-            const llmConfig = Object.hasOwn(opts ?? {}, "llmConfig") ? opts?.llmConfig : resolveIndexPassLLM("graph", config);
-            if (!llmConfig)
-                return false; // model-available guard
-            const featureConfig = invocationOwnsConnection
+            const invocationOwnsRunner = Object.hasOwn(opts ?? {}, "llmRunner");
+            if (!invocationOwnsRunner && !isProcessEnabled("index", "graph_extraction", config))
+                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;
+            if (!llmRunner)
+                return { written: false }; // model-available guard
+            const featureConfig = invocationOwnsRunner
                 ? { ...config, index: { ...config.index, graph: { ...config.index?.graph, enabled: true } } }
                 : config;
-            const result = await graphExtract.extractGraphFromBody(llmConfig, body, opts?.signal, featureConfig);
+            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,
@@ -785,13 +965,22 @@ export async function extractGraphForSingleFile(db, stashRoot, filePath, bodyHas
             quality,
             ...(previousGraph.telemetry ? { telemetry: previousGraph.telemetry } : {}),
         };
-        return writeGraphFile(stashRoot, graph, db);
+        return writeGraphFile(stashRoot, graph, db) ? { written: true, bodyHash: effectiveHash } : { written: false };
     }
     catch (err) {
+        if (err instanceof ConfigError)
+            throw err;
         rethrowIfTestIsolationError(err);
-        return false;
+        return { written: false };
+    }
+    finally {
+        if (ownedLease)
+            disposeLoweredExecutionDispatchLease(ownedLease);
     }
 }
+export async function extractGraphForSingleFile(db, stashRoot, filePath, _bodyHash, opts) {
+    return (await extractGraphForSingleFileRevision(db, stashRoot, filePath, opts)).written;
+}
 // ── Eligible-file detection ─────────────────────────────────────────────────
 /**
  * Rank eligible graph-extraction candidates by their entry `utility_scores`,