akm-cli 0.8.0-rc2 → 0.8.0

package/dist/indexer/graph-extraction.js

@@ -1,48 +1,19 @@
-/**
- * Graph-extraction pass for `akm index` (#207).
- *
- * 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-boost.ts`) as a single boost component
- * inside the existing FTS5+boosts loop — there is NO second SearchHit
- * scorer and no parallel ranking track.
- *
- * Disabling — three preconditions must ALL hold for the pass to run:
- *   1. `akm.llm` must be configured (no provider = no extraction). When
- *      absent, `resolveIndexPassLLM("graph", config)` returns `undefined`
- *      and the pass short-circuits.
- *   2. `llm.features.graph_extraction !== false` — the locked v1 spec §14
- *      feature-flag layer. Set to `false` to block the pass at the
- *      feature-gate layer (no network call may ever issue).
- *   3. `index.graph.llm !== false` — the per-pass opt-out layer (#208).
- *      Set to `false` to skip just this pass while leaving other passes
- *      that share the same `llm` block enabled.
- *   Toggling any one off does NOT delete the existing persisted graph — the
- *   user keeps the boost component they already have, it just stops
- *   refreshing.
- *
- * Locked v1 contract:
- *   - LLM access is exclusively via `resolveIndexPassLLM("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`. Direct `fs.writeFile`
- *     is therefore the correct primitive — `writeAssetToSource` is
- *     reserved for asset writes (CLAUDE.md / spec §10 step 5).
- */
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
 import { TYPE_DIRS } from "../core/asset-spec";
 import { concurrentMap } from "../core/concurrent";
+import { getIndexPassConfig, resolveBatchSize } from "../core/config";
 import { parseFrontmatter } from "../core/frontmatter";
-import { warn } from "../core/warn";
+import { warn, warnVerbose } from "../core/warn";
+import { isProcessEnabled } from "../llm/feature-gate";
 import * as graphExtract from "../llm/graph-extract";
 import { resolveIndexPassLLM } from "../llm/index-passes";
-import { computeBodyHash, GRAPH_SCHEMA_VERSION, getLlmCacheEntry, upsertLlmCacheEntry } from "./db";
+import { computeBodyHash, GRAPH_SCHEMA_VERSION, getLlmCacheEntriesByRefs, getLlmCacheEntry, upsertLlmCacheEntry, } from "./db";
 import { loadStoredGraphSnapshot, replaceStoredGraph } from "./graph-db";
 import { deduplicateGraph } from "./graph-dedup";
-import { withLlmCache } from "./llm-cache";
 import { walkMarkdownFiles } from "./walker";
 /** Schema version for the persisted artifact — bumps trigger a full rebuild. */
 export const GRAPH_FILE_SCHEMA_VERSION = GRAPH_SCHEMA_VERSION;
@@ -61,6 +32,13 @@ const EMPTY_RESULT = {
     totalRelations: 0,
     written: false,
     quality: { ...EMPTY_QUALITY },
+    telemetry: {
+        cacheHits: 0,
+        cacheMisses: 0,
+        truncationCount: 0,
+        failureCount: 0,
+    },
+    warnings: [],
 };
 function roundMetric(value) {
     return Number(value.toFixed(4));
@@ -90,13 +68,38 @@ const SUPPORTED_GRAPH_EXTRACTION_INCLUDE_TYPES = new Set([
     "task",
     "wiki",
 ]);
+const GRAPH_CACHE_VARIANT_PREFIX = "graph-extraction";
 function normalizeConfidence(raw) {
     if (typeof raw !== "number" || !Number.isFinite(raw))
         return undefined;
     return Math.max(0, Math.min(1, raw));
 }
+function getGraphExtractorId(config) {
+    const fingerprint = computeBodyHash(JSON.stringify({
+        promptVersion: graphExtract.GRAPH_EXTRACT_PROMPT_VERSION,
+        model: config.model,
+        batchSize: config.batchSize,
+        includeTypes: config.includeTypes,
+        maxChunkBodyChars: 1600,
+        maxBatchBodyChars: 1600,
+    })).slice(0, 16);
+    return `${GRAPH_CACHE_VARIANT_PREFIX}:${graphExtract.GRAPH_EXTRACT_PROMPT_VERSION}:${config.model}:${fingerprint}`;
+}
+function buildLowQualityWarnings(quality, telemetry) {
+    const warnings = [];
+    if (quality.consideredFiles >= 5 && quality.extractionCoverage < 0.3) {
+        warnings.push(`Low graph extraction coverage (${quality.extractedFiles}/${quality.consideredFiles}, ${quality.extractionCoverage}).`);
+    }
+    if (quality.entityCount >= 8 && quality.relationCount === 0) {
+        warnings.push("Graph extraction produced many entities but no relations.");
+    }
+    if (telemetry.failureCount > 0) {
+        warnings.push(`Graph extraction encountered ${telemetry.failureCount} failed file extraction(s).`);
+    }
+    return warnings;
+}
 export function getGraphExtractionIncludeTypes(config) {
-    const configured = config.index?.graph?.graphExtractionIncludeTypes;
+    const configured = getIndexPassConfig(config.index, "graph")?.graphExtractionIncludeTypes;
     if (!configured || configured.length === 0)
         return [...DEFAULT_GRAPH_EXTRACTION_INCLUDE_TYPES];
     const out = [];
@@ -139,6 +142,8 @@ function validateGraphCacheShape(raw) {
         entities: obj.entities,
         relations: Array.isArray(obj.relations) ? obj.relations : [],
         confidence: normalizeConfidence(obj.confidence),
+        ...(typeof obj.status === "string" ? { status: obj.status } : {}),
+        ...(typeof obj.reason === "string" ? { reason: obj.reason } : {}),
     };
 }
 function loadGraphFile(stashRoot, db) {
@@ -159,9 +164,15 @@ function loadGraphFile(stashRoot, db) {
             entities: cacheShape.entities,
             relations: cacheShape.relations,
             confidence: normalizeConfidence(node.confidence),
+            ...(node.status ? { status: node.status } : {}),
+            ...(node.reason ? { reason: node.reason } : {}),
+            ...(node.extractionRunId ? { extractionRunId: node.extractionRunId } : {}),
         });
     }
-    return { files: out };
+    return {
+        files: out,
+        ...(graph.telemetry ? { telemetry: graph.telemetry } : {}),
+    };
 }
 function mergeGraphNodes(previousNodes, refreshedNodes, candidatePaths) {
     if (!candidatePaths)
@@ -194,6 +205,8 @@ function reuseGraphNode(previousNodes, candidate, bodyHash) {
         entities: validated.entities,
         relations: validated.relations,
         confidence: normalizeConfidence(node.confidence),
+        ...(node.status ? { status: node.status } : {}),
+        ...(node.reason ? { reason: node.reason } : {}),
     };
 }
 /**
@@ -201,12 +214,12 @@ function reuseGraphNode(previousNodes, candidate, bodyHash) {
  *
  * Three preconditions — ALL must hold for the pass to run:
  *
- *   1. **Provider configured** — `akm.llm` must be present. Without a
+ *   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).
- *   2. **Feature gate** — `llm.features.graph_extraction` (defaults to
- *      `true`). When `false`, no network call may issue regardless of
- *      per-pass settings. This is the locked spec-§14 gate.
+ *   2. **Feature gate** — `profiles.improve.default.processes.graphExtraction.enabled`
+ *      (defaults to `true`). When `false`, no network call may issue regardless
+ *      of per-pass settings.
  *   3. **Per-pass gate** — `index.graph.llm` (defaults to `true`). When
  *      `false`, the indexer simply skips this pass for the current run.
  *
@@ -219,25 +232,38 @@ function reuseGraphNode(previousNodes, candidate, bodyHash) {
  * preserves existing behaviour, fully opt-in).
  */
 export async function runGraphExtractionPass(config, sources, signal, db, reEnrich, onProgress, options = {}) {
-    // Gate 1 — locked feature flag (§14). Defaults to enabled; only an
-    // explicit `false` disables the pass entirely.
-    if (config.llm?.features?.graph_extraction === false)
+    // Gate 1 — feature gate via isProcessEnabled, which reads the 0.8.0 path
+    // (profiles.improve.default.processes.graphExtraction.enabled). Defaults to
+    // enabled when the key is absent.
+    if (!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 = resolveIndexPassLLM("graph", config);
-    if (!llmConfig)
+    if (!llmConfig) {
+        const reason = getIndexPassConfig(config.index, "graph")?.llm === false
+            ? "index.graph.llm is false"
+            : "no default LLM profile is configured";
+        warnVerbose(`graph extraction: skipped because ${reason}.`);
         return { ...EMPTY_RESULT };
+    }
     // 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().
     const primary = sources[0];
-    if (!primary)
+    if (!primary) {
+        warnVerbose("graph extraction: skipped because no primary stash source is available.");
         return { ...EMPTY_RESULT };
-    const eligible = collectEligibleFiles(primary.path, getGraphExtractionIncludeTypes(config)).filter((candidate) => !options.candidatePaths || options.candidatePaths.has(candidate.absPath));
+    }
+    const includeTypes = getGraphExtractionIncludeTypes(config);
+    const eligible = collectEligibleFiles(primary.path, includeTypes).filter((candidate) => !options.candidatePaths || options.candidatePaths.has(candidate.absPath));
     const considered = eligible.length;
-    if (considered === 0)
+    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 = [];
@@ -246,9 +272,58 @@ export async function runGraphExtractionPass(config, sources, signal, db, reEnri
     let processed = 0;
     let extracted = 0;
     onProgress?.({ processed, total: considered, extracted, totalEntities, totalRelations });
-    // Read the configured batch size. Default of 1 preserves the existing
-    // per-asset behaviour and is fully opt-in.
-    const batchSize = config.index?.graph?.graphExtractionBatchSize ?? 1;
+    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,
+        });
+    };
+    // 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(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,
+    };
+    const canReusePreviousGraph = previousGraph.telemetry?.extractorId === extractorId;
+    const runtimeTelemetry = {
+        truncationCount: 0,
+        failureCount: 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}`);
     };
@@ -256,49 +331,67 @@ export async function runGraphExtractionPass(config, sources, signal, db, reEnri
     if (batchSize <= 1) {
         // ── Original per-asset path (with incremental cache) ─────────────────
         extractionResults = await concurrentMap(eligible, async (candidate) => {
-            if (signal?.aborted)
+            if (signal?.aborted) {
+                reportProgress(candidate.absPath, undefined);
                 return undefined;
+            }
             const bodyHash = computeBodyHash(candidate.body);
             let cached;
             if (db) {
-                // withLlmCache handles hash computation, cache lookup, LLM call, and cache write.
-                // When cache misses and this run is not forced, attempt graph-node reuse before LLM.
-                cached = await withLlmCache(db, candidate.absPath, candidate.body, reEnrich ?? false, async () => {
-                    if (!(reEnrich ?? false)) {
-                        const reused = reuseGraphNode(previousNodes, candidate, bodyHash);
-                        if (reused)
-                            return reused;
+                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;
+                        }
                     }
-                    const extraction = await graphExtract.extractGraphFromBody(llmConfig, candidate.body, signal, config, onFallback);
-                    // Cache empty results too so we skip on next run.
-                    return {
-                        entities: extraction.entities,
-                        relations: extraction.relations,
-                        ...(extraction.confidence !== undefined ? { confidence: extraction.confidence } : {}),
-                    };
-                }, validateGraphCacheShape);
+                }
             }
             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) {
-                const extraction = await graphExtract.extractGraphFromBody(llmConfig, candidate.body, signal, config, onFallback);
+                telemetry.cacheMisses += 1;
+                const extraction = await graphExtract.extractGraphFromBody(llmConfig, candidate.body, signal, config, 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 (!cached || cached.entities.length === 0)
-                return undefined;
-            return {
+            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;
         }, 
         // Default concurrency of 4 for cloud APIs. Set `llm.concurrency: 1`
         // in config.json for local model servers (LM Studio, Ollama).
@@ -317,30 +410,44 @@ export async function runGraphExtractionPass(config, sources, signal, db, reEnri
             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 = getLlmCacheEntry(db, c.absPath, bodyHashes[j] ?? "");
-                if (!cached)
+                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;
-                    const entities = parsed.entities;
-                    rawResults[start + j] =
-                        entities.length > 0
-                            ? {
-                                absPath: c.absPath,
-                                type: c.type,
-                                bodyHash: bodyHashes[j] ?? "",
-                                entities,
-                                relations: parsed.relations,
-                                ...(parsed.confidence !== undefined ? { confidence: parsed.confidence } : {}),
-                            }
-                            : undefined;
+                    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 {
@@ -349,7 +456,7 @@ export async function runGraphExtractionPass(config, sources, signal, db, reEnri
             });
             // Secondary incremental path: reuse previous graph nodes when the body hash
             // still matches and DB cache is missing/stale/unavailable.
-            if (!(reEnrich ?? false)) {
+            if (!(reEnrich ?? false) && canReusePreviousGraph) {
                 for (let j = 0; j < chunk.length; j++) {
                     if (!needsLlm[j])
                         continue;
@@ -359,30 +466,33 @@ export async function runGraphExtractionPass(config, sources, signal, db, reEnri
                     const reused = reuseGraphNode(previousNodes, candidate, bodyHashes[j] ?? "");
                     if (!reused)
                         continue;
-                    rawResults[start + j] =
-                        reused.entities.length > 0
-                            ? {
-                                absPath: candidate.absPath,
-                                type: candidate.type,
-                                bodyHash: bodyHashes[j] ?? "",
-                                entities: reused.entities,
-                                relations: reused.relations,
-                                ...(reused.confidence !== undefined ? { confidence: reused.confidence } : {}),
-                            }
-                            : undefined;
+                    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));
+                        upsertLlmCacheEntry(db, candidate.absPath, bodyHashes[j] ?? "", JSON.stringify(reused), cacheVariant);
                     }
                     needsLlm[j] = false;
                 }
             }
             const uncachedChunk = chunk.filter((_, j) => needsLlm[j]);
-            if (uncachedChunk.length === 0)
+            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, config, onFallback);
+            const batchExtractions = await graphExtract.extractGraphFromBodies(llmConfig, bodies, signal, config, 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++) {
@@ -397,22 +507,22 @@ export async function runGraphExtractionPass(config, sources, signal, db, reEnri
                         entities: extraction.entities,
                         relations: extraction.relations,
                         ...(extraction.confidence !== undefined ? { confidence: extraction.confidence } : {}),
-                    }));
-                }
-                if (extraction.entities.length === 0) {
-                    rawResults[start + j] = undefined;
-                }
-                else {
-                    rawResults[start + j] = {
-                        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 } : {}),
+                    }), cacheVariant);
                 }
+                rawResults[start + j] = {
+                    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 } : {}),
+                };
             }
+            reportChunkProgress();
         }, llmConfig.concurrency ?? 1);
         extractionResults = rawResults;
     }
@@ -435,45 +545,22 @@ export async function runGraphExtractionPass(config, sources, signal, db, reEnri
             ...(normalizeConfidence(result.confidence) !== undefined
                 ? { confidence: normalizeConfidence(result.confidence) }
                 : {}),
-        });
-    }
-    processed = 0;
-    extracted = 0;
-    totalEntities = 0;
-    totalRelations = 0;
-    for (let i = 0; i < extractionResults.length; i++) {
-        const result = extractionResults[i];
-        processed += 1;
-        if (result) {
-            extracted += 1;
-            totalEntities += result.entities.length;
-            totalRelations += result.relations.length;
-        }
-        onProgress?.({
-            processed,
-            total: considered,
-            extracted,
-            totalEntities,
-            totalRelations,
-            currentPath: eligible[i]?.absPath,
+            status: result.status ?? (result.entities.length > 0 ? "extracted" : "empty"),
+            reason: result.reason ?? (result.entities.length > 0 ? "none" : "no_graph_content"),
+            extractionRunId,
         });
     }
     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);
-    if (mergedNodes.length === 0) {
-        warn("graph extraction: all extractions failed or returned no entities; leaving existing graph rows untouched.");
-        return {
-            considered,
-            extracted: 0,
-            totalEntities: 0,
-            totalRelations: 0,
-            written: false,
-            quality: computeGraphQualityTelemetry(considered, 0, 0, 0),
-        };
-    }
-    const qualityConsidered = options.candidatePaths ? mergedNodes.length : considered;
-    const quality = computeGraphQualityTelemetry(qualityConsidered, mergedNodes.length, deduped.entities.length, deduped.relations.length);
+    telemetry.truncationCount = runtimeTelemetry.truncationCount ?? 0;
+    telemetry.failureCount = runtimeTelemetry.failureCount ?? 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(),
@@ -482,8 +569,12 @@ export async function runGraphExtractionPass(config, sources, signal, db, reEnri
         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,
@@ -491,6 +582,8 @@ export async function runGraphExtractionPass(config, sources, signal, db, reEnri
         totalRelations,
         written,
         quality,
+        telemetry,
+        warnings,
     };
 }
 /**

package/dist/indexer/index-context.js

@@ -1,10 +1,4 @@
-/**
- * IndexRunContext — shared state threaded through every phase of `akmIndex()`.
- *
- * Extracted from `src/indexer/indexer.ts` so each named phase function
- * (`runSourceCachePhase`, `runMemoryInferencePhase`, …) can receive a single
- * typed argument rather than a long positional parameter list. The context is
- * assembled once at the top of `akmIndex()` and passed to each phase in
- * sequence.
- */
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 export {};