akm-cli 0.9.17-alpha.7 → 0.9.17-alpha.9

package/dist/llm/graph-extract.js

@@ -1,903 +0,0 @@
-// 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/.
-/**
- * LLM helper for the `akm index` graph-extraction pass (#207).
- *
- * Given a single asset body (typically a `memory:` or `knowledge:` file),
- * asks the configured LLM to surface the entities mentioned in it and the
- * relations between them. The pass itself
- * (`src/indexer/graph/graph-extraction.ts`) is responsible for deciding which
- * files to extract, persisting the resulting nodes/edges to the index DB,
- * and feeding the graph data into the FTS5+boosts
- * search pipeline as a single boost component.
- *
- * This module is intentionally tiny and stateless so tests can stub it via
- * `mock.module("../src/llm/graph-extract", ...)` without hitting a network.
- *
- * The symbolic LLM runner comes from the current index-pass execution
- * resolution and is passed straight through.
- */
-import systemPromptTemplate from "../assets/prompts/graph-extract-system.md" with { type: "text" };
-import userPromptTemplate from "../assets/prompts/graph-extract-user-prompt.md" with { type: "text" };
-import { splitMarkdownFragmentStats } from "../core/asset/markdown-fragments.js";
-import { toErrorMessage } from "../core/common.js";
-import { ConfigError } from "../core/errors.js";
-import { parseEmbeddedJsonResponse } from "../core/parse.js";
-import { warn, warnVerbose } from "../core/warn.js";
-import { isContextSizeError, isTransportFailure, LlmCallError } from "./client.js";
-import { tryLlmFeature } from "./feature-gate.js";
-import { callStructured } from "./structured-call.js";
-/**
- * Separator token used between assets in a batch prompt.
- * Chosen to be visually clear and unlikely to appear verbatim in asset bodies.
- */
-const BATCH_ASSET_SEPARATOR = "=== ASSET";
-/**
- * Part of the extractor id that keys cached extractions; the prompt text is
- * not. Bump it with any change to either prompt, and expect every cached file
- * to be extracted again. Pending for the next bump (GR-D12): the batch prompt
- * still asks for "file/dir names", which the single-asset prompt rules out.
- */
-export const GRAPH_EXTRACT_PROMPT_VERSION = "v3";
-/** Asset bodies longer than this are chunked instead of truncated. */
-const MAX_CHUNK_BODY_CHARS = 1600;
-/** Bodies longer than this are excluded from multi-asset batch prompts. */
-const MAX_BATCH_BODY_CHARS = 1600;
-const MIN_RELATION_CONFIDENCE = 0.5;
-const NON_ARRAY_BATCH_DISABLE_THRESHOLD = 2;
-/** Hard cap on entities returned per asset — guards against runaway LLM output. */
-const MAX_ENTITIES_PER_ASSET = 32;
-/** Hard cap on relations returned per asset. */
-const MAX_RELATIONS_PER_ASSET = 32;
-/**
- * Default cap on chunks processed per asset (R12b + R20) — overridable via
- * `processes.graphExtraction.maxChunksPerAsset`. Without a cap, one long file
- * chunked at MAX_CHUNK_BODY_CHARS could spend dozens of calls on a single
- * asset (one file spent 21 of 27 run calls this way) before its output was
- * sliced to MAX_ENTITIES_PER_ASSET/MAX_RELATIONS_PER_ASSET anyway.
- */
-const DEFAULT_MAX_CHUNKS_PER_ASSET = 8;
-const SYSTEM_PROMPT = systemPromptTemplate;
-const USER_PROMPT_PREFIX = userPromptTemplate
-    .replace("{{MAX_ENTITIES}}", String(MAX_ENTITIES_PER_ASSET))
-    .replace("{{MAX_RELATIONS}}", String(MAX_RELATIONS_PER_ASSET));
-/**
- * Strict JSON Schema for one asset's extraction payload (R12b, compacted for
- * R12). Sent via `responseSchema` to providers that opt into structured
- * output (`runner.connection.supportsJsonSchema` — same lift as
- * memory-infer.ts's `DERIVED_MEMORY_JSON_SCHEMA`); the client silently drops
- * it otherwise. `maxItems` mirrors MAX_ENTITIES_PER_ASSET/MAX_RELATIONS_PER_ASSET
- * so a compliant provider cannot pay for output beyond what
- * parseGraphExtraction keeps. Relations are compact `[from, type, to]`
- * triples (`type` may be `""`) rather than `{"from","to","type"}` objects —
- * the object-keyed form cost 10+ tokens per relation for no signal, and
- * output tokens cost far more than prompt tokens. There is deliberately no
- * relation-level `confidence` in the schema (the prompt never asks for one);
- * `parseGraphExtraction` still reads it from a legacy object-shaped relation
- * for backward compatibility. `confidence` stays at the extraction level —
- * parseGraphExtraction reads it into the merged confidence.
- * `additionalProperties: false` forbids anything else. Reused as the `items`
- * schema of a batch call's array response (see
- * {@link buildBatchResponseSchema}) so a single-asset and a batched call
- * bound entities/relations identically.
- */
-const GRAPH_EXTRACTION_ITEM_SCHEMA = {
-    type: "object",
-    properties: {
-        entities: { type: "array", items: { type: "string" }, maxItems: MAX_ENTITIES_PER_ASSET },
-        relations: {
-            type: "array",
-            maxItems: MAX_RELATIONS_PER_ASSET,
-            items: {
-                type: "array",
-                items: { type: "string" },
-                minItems: 3,
-                maxItems: 3,
-            },
-        },
-        confidence: { type: "number" },
-    },
-    required: ["entities", "relations"],
-    additionalProperties: false,
-};
-/** Schema for {@link extractGraphFromBody}'s single-asset `responseSchema`. */
-const GRAPH_EXTRACTION_JSON_SCHEMA = GRAPH_EXTRACTION_ITEM_SCHEMA;
-/**
- * Schema for {@link extractGraphFromBodies}' batch `responseSchema` — an
- * array of exactly `count` {@link GRAPH_EXTRACTION_ITEM_SCHEMA} elements, one
- * per asset in the batch, matching the batch prompt's contract.
- */
-function buildBatchResponseSchema(count) {
-    return {
-        type: "array",
-        minItems: count,
-        maxItems: count,
-        items: GRAPH_EXTRACTION_ITEM_SCHEMA,
-    };
-}
-const GENERIC_ENTITIES = new Set([
-    "agent",
-    "application",
-    "assistant",
-    "code",
-    "content",
-    "data",
-    "developer",
-    "document",
-    "file",
-    "knowledge",
-    "memory",
-    "note",
-    "notes",
-    "project",
-    "service",
-    "system",
-    "task",
-    "team",
-    "text",
-    "thing",
-    "user",
-]);
-const GENERIC_RELATION_TYPES = new Set(["has", "is", "mentions", "references", "related to"]);
-function parseConfidence(raw) {
-    if (typeof raw !== "number" || !Number.isFinite(raw))
-        return undefined;
-    return Math.max(0, Math.min(1, raw));
-}
-function normalizeEntityName(raw) {
-    return raw
-        .trim()
-        .replace(/^[`"']+|[`"']+$/g, "")
-        .replace(/\s+/g, " ")
-        .replace(/[;,!?]+$/g, "")
-        .trim();
-}
-function normalizeRelationType(raw) {
-    const normalized = raw
-        .trim()
-        .toLowerCase()
-        .replace(/^[`"']+|[`"']+$/g, "")
-        .replace(/\s+/g, " ")
-        .replace(/[.;,!?]+$/g, "")
-        .trim();
-    if (!normalized)
-        return undefined;
-    if (normalized === "use" || normalized === "utilizes")
-        return "uses";
-    if (normalized === "depend on" || normalized === "depends")
-        return "depends on";
-    if (normalized === "integrates" || normalized === "integration with")
-        return "integrates with";
-    return normalized;
-}
-/**
- * The key under which two entity names are the same entity: the display
- * clean-up above, case-folded. The one normalization for graph entities:
- * extraction deduplicates on it, the pass deduplicates on it before writing,
- * and it is the stored `entity_norm` that `related` joins on (GR-D17).
- */
-export function normalizeEntityKey(raw) {
-    return normalizeEntityName(raw).toLowerCase();
-}
-function bumpTelemetry(telemetry, key, amount = 1) {
-    if (!telemetry)
-        return;
-    telemetry[key] = (telemetry[key] ?? 0) + amount;
-}
-/**
- * `Promise.all(items.map(fn))` with at most `limit` calls in flight, so the
- * per-asset calls of one batch never outnumber the chunk pool's concurrency
- * (GR-D14). The first rejection rejects the map and stops further calls.
- */
-async function mapWithConcurrency(items, limit, fn) {
-    const results = new Array(items.length);
-    let next = 0;
-    let failed = false;
-    const worker = async () => {
-        while (!failed && next < items.length) {
-            const index = next++;
-            try {
-                results[index] = await fn(items[index]);
-            }
-            catch (error) {
-                failed = true;
-                throw error;
-            }
-        }
-    };
-    await Promise.all(Array.from({ length: Math.min(Math.max(1, limit), items.length) }, worker));
-    return results;
-}
-/** Count what the parser dropped from one parsed extraction (single-asset or batch item). */
-function bumpFilterTelemetry(telemetry, extraction) {
-    bumpTelemetry(telemetry, "filteredGenericEntities", extraction.filteredGenericEntities ?? 0);
-    bumpTelemetry(telemetry, "filteredInvalidRelations", extraction.filteredInvalidRelations ?? 0);
-    bumpTelemetry(telemetry, "filteredLowConfidenceRelations", extraction.filteredLowConfidenceRelations ?? 0);
-}
-function normalizeBatchState(state) {
-    if (!state)
-        return undefined;
-    state.batchingDisabled = state.batchingDisabled === true;
-    state.nonArrayBatchFailures = Math.max(0, state.nonArrayBatchFailures ?? 0);
-    return state;
-}
-function splitBodyIntoChunks(body, maxChars = MAX_CHUNK_BODY_CHARS) {
-    const split = splitMarkdownFragmentStats(body, maxChars);
-    // Graph extraction keeps its historical cost shape: adjacent safe fragments
-    // share one LLM call whenever they fit. The fragment splitter is still the
-    // sole boundary authority; this is only prompt packing, never a second
-    // parser/chunker. Hard splits stay isolated and telemetry remains the core
-    // split count rather than counting ordinary heading boundaries.
-    const chunks = [];
-    let current = "";
-    for (const fragment of split.fragments) {
-        const candidate = current ? `${current}\n\n${fragment.text}` : fragment.text;
-        if (candidate.length <= maxChars) {
-            current = candidate;
-        }
-        else {
-            if (current)
-                chunks.push(current);
-            current = fragment.text;
-        }
-    }
-    if (current)
-        chunks.push(current);
-    return { chunks, truncationCount: split.hardSplitCount };
-}
-/** Consistency weight for blending chunk-agreement with LLM confidence. */
-const CONSISTENCY_WEIGHT = 0.4;
-function mergeGraphExtractions(extractions) {
-    const totalChunks = extractions.length;
-    const entityCanonical = new Map();
-    const entityChunkCounts = new Map();
-    const relationByKey = new Map();
-    const relationChunkCounts = new Map();
-    let confidence;
-    let truncationCount = 0;
-    let truncatedChunks = 0;
-    let filteredGenericEntities = 0;
-    let filteredInvalidRelations = 0;
-    let filteredLowConfidenceRelations = 0;
-    let firstFailureReason;
-    for (const extraction of extractions) {
-        truncationCount += extraction.truncationCount ?? 0;
-        truncatedChunks += extraction.truncatedChunks ?? 0;
-        filteredGenericEntities += extraction.filteredGenericEntities ?? 0;
-        filteredInvalidRelations += extraction.filteredInvalidRelations ?? 0;
-        filteredLowConfidenceRelations += extraction.filteredLowConfidenceRelations ?? 0;
-        if (extraction.status === "failed" && !firstFailureReason)
-            firstFailureReason = extraction.reason;
-        const nextConfidence = parseConfidence(extraction.confidence);
-        if (nextConfidence !== undefined)
-            confidence = confidence === undefined ? nextConfidence : Math.max(confidence, nextConfidence);
-        for (const entity of extraction.entities) {
-            const key = normalizeEntityKey(entity);
-            if (!key)
-                continue;
-            if (!entityCanonical.has(key))
-                entityCanonical.set(key, entity);
-            entityChunkCounts.set(key, (entityChunkCounts.get(key) ?? 0) + 1);
-        }
-    }
-    for (const extraction of extractions) {
-        for (const relation of extraction.relations) {
-            const fromKey = normalizeEntityKey(relation.from);
-            const toKey = normalizeEntityKey(relation.to);
-            const type = normalizeRelationType(relation.type ?? "");
-            if (!fromKey || !toKey || !type)
-                continue;
-            const from = entityCanonical.get(fromKey);
-            const to = entityCanonical.get(toKey);
-            if (!from || !to)
-                continue;
-            const key = `${fromKey}\u0000${toKey}\u0000${type}`;
-            if (!relationByKey.has(key)) {
-                relationByKey.set(key, {
-                    from,
-                    to,
-                    type,
-                });
-                relationChunkCounts.set(key, 0);
-            }
-            relationChunkCounts.set(key, (relationChunkCounts.get(key) ?? 0) + 1);
-            const nextConfidence = parseConfidence(relation.confidence);
-            const existing = relationByKey.get(key);
-            if (existing && nextConfidence !== undefined) {
-                const current = parseConfidence(existing.confidence) ?? 0;
-                if (nextConfidence > current)
-                    existing.confidence = nextConfidence;
-            }
-        }
-    }
-    function blendConsistency(llmConfidence, chunkCount) {
-        const consistency = totalChunks > 1 ? chunkCount / totalChunks : 1;
-        if (llmConfidence === undefined)
-            return consistency;
-        return (1 - CONSISTENCY_WEIGHT) * llmConfidence + CONSISTENCY_WEIGHT * consistency;
-    }
-    const entities = [...entityCanonical.values()].slice(0, MAX_ENTITIES_PER_ASSET);
-    const relations = [...relationByKey.values()].slice(0, MAX_RELATIONS_PER_ASSET);
-    for (const relation of relations) {
-        const fromKey = normalizeEntityKey(relation.from);
-        const toKey = normalizeEntityKey(relation.to);
-        const type = normalizeRelationType(relation.type ?? "");
-        if (!fromKey || !toKey || !type)
-            continue;
-        const key = `${fromKey}\u0000${toKey}\u0000${type}`;
-        const chunkCount = relationChunkCounts.get(key) ?? 1;
-        relation.confidence = blendConsistency(relation.confidence, chunkCount);
-    }
-    const status = entities.length > 0 ? "extracted" : firstFailureReason ? "failed" : "empty";
-    const reason = status === "extracted" ? "none" : (firstFailureReason ?? "no_graph_content");
-    const mergedConfidence = confidence !== undefined ? blendConsistency(confidence, totalChunks) : totalChunks > 1 ? 1 : undefined;
-    return {
-        entities,
-        relations,
-        ...(mergedConfidence !== undefined ? { confidence: mergedConfidence } : {}),
-        status,
-        reason,
-        chunkCount: extractions.length,
-        truncationCount,
-        truncatedChunks,
-        filteredGenericEntities,
-        filteredInvalidRelations,
-        filteredLowConfidenceRelations,
-    };
-}
-function parseGraphExtraction(raw) {
-    const empty = (reason = "no_graph_content") => ({
-        entities: [],
-        relations: [],
-        status: reason === "llm_error" || reason === "invalid_json" || reason === "context_limit" ? "failed" : "empty",
-        reason,
-    });
-    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
-        return empty();
-    const item = raw;
-    const extractionConfidence = parseConfidence(item.confidence);
-    const entityCanonical = new Map();
-    let filteredGenericEntities = 0;
-    if (Array.isArray(item.entities)) {
-        for (const value of item.entities) {
-            if (typeof value !== "string")
-                continue;
-            const normalized = normalizeEntityName(value);
-            if (!normalized)
-                continue;
-            const normalizedKey = normalized.toLowerCase();
-            // Drop generic/empty entities AND raw file/dir paths (anything with a
-            // path separator) — the prompt no longer asks for them and isJunkEntity
-            // discards them downstream, so emitting them is pure waste/junk (#632).
-            if (!/[a-z0-9]/i.test(normalized) ||
-                GENERIC_ENTITIES.has(normalizedKey) ||
-                normalized.includes("/") ||
-                normalized.includes("\\")) {
-                filteredGenericEntities += 1;
-                continue;
-            }
-            const key = normalized.toLowerCase();
-            if (!entityCanonical.has(key))
-                entityCanonical.set(key, normalized);
-            if (entityCanonical.size >= MAX_ENTITIES_PER_ASSET)
-                break;
-        }
-    }
-    const entities = Array.from(entityCanonical.values());
-    const relations = [];
-    let filteredInvalidRelations = 0;
-    let filteredLowConfidenceRelations = 0;
-    if (Array.isArray(item.relations)) {
-        for (const relation of item.relations) {
-            // Compact triple form `[from, type, to]` (R12) — `type` may be "".
-            // Legacy `{"from","to","type","confidence"}` object form still parses
-            // for backward compatibility (older cached prompts, other callers).
-            let fromRaw;
-            let toRaw;
-            let typeRaw;
-            let confidenceRaw;
-            if (Array.isArray(relation)) {
-                if (relation.length !== 3 ||
-                    typeof relation[0] !== "string" ||
-                    typeof relation[1] !== "string" ||
-                    typeof relation[2] !== "string") {
-                    filteredInvalidRelations += 1;
-                    continue;
-                }
-                fromRaw = normalizeEntityName(relation[0]);
-                typeRaw = relation[1];
-                toRaw = normalizeEntityName(relation[2]);
-            }
-            else if (typeof relation === "object" && relation !== null) {
-                const rel = relation;
-                fromRaw = typeof rel.from === "string" ? normalizeEntityName(rel.from) : "";
-                toRaw = typeof rel.to === "string" ? normalizeEntityName(rel.to) : "";
-                typeRaw = typeof rel.type === "string" ? rel.type : undefined;
-                confidenceRaw = rel.confidence;
-            }
-            else {
-                filteredInvalidRelations += 1;
-                continue;
-            }
-            if (!fromRaw || !toRaw) {
-                filteredInvalidRelations += 1;
-                continue;
-            }
-            const from = entityCanonical.get(fromRaw.toLowerCase());
-            const to = entityCanonical.get(toRaw.toLowerCase());
-            if (!from || !to || from.toLowerCase() === to.toLowerCase()) {
-                filteredInvalidRelations += 1;
-                continue;
-            }
-            const type = typeRaw !== undefined ? normalizeRelationType(typeRaw) : undefined;
-            if (type !== undefined && GENERIC_RELATION_TYPES.has(type)) {
-                filteredInvalidRelations += 1;
-                continue;
-            }
-            const confidence = parseConfidence(confidenceRaw);
-            if (confidence !== undefined && confidence < MIN_RELATION_CONFIDENCE) {
-                filteredLowConfidenceRelations += 1;
-                continue;
-            }
-            relations.push({
-                from,
-                to,
-                ...(type ? { type } : {}),
-                ...(confidence !== undefined ? { confidence } : {}),
-            });
-            if (relations.length >= MAX_RELATIONS_PER_ASSET)
-                break;
-        }
-    }
-    const confidence = extractionConfidence;
-    const status = entities.length > 0 ? "extracted" : "empty";
-    const reason = entities.length > 0 ? "none" : filteredGenericEntities > 0 ? "generic_entities_only" : "no_graph_content";
-    return {
-        entities,
-        relations,
-        status,
-        reason,
-        filteredGenericEntities,
-        filteredInvalidRelations,
-        filteredLowConfidenceRelations,
-        ...(confidence !== undefined ? { confidence } : {}),
-    };
-}
-/**
- * Build the system prompt for a batched graph-extraction call.
- *
- * The prompt instructs the model to return a JSON array of exactly `count`
- * objects, one per asset, in input order. Index alignment is the critical
- * invariant — if the model drops an asset it still must emit an empty
- * placeholder `{"entities":[],"relations":[]}` at that position.
- *
- * Worked example (3 assets, abbreviated):
- *
- *   Input user message:
- *     Extract entities and relations from the N=3 assets below.
- *     ...rules...
- *     === ASSET 1 ===
- *     ServiceA integrates with ServiceB.
- *     === ASSET 2 ===
- *     Terraform provisions the Prod cluster.
- *     === ASSET 3 ===
- *     No extractable graph content here.
- *
- *   Expected model output (valid JSON array, no prose):
- *     [
- *       {"entities":["ServiceA","ServiceB"],"relations":[["ServiceA","integrates with","ServiceB"]]},
- *       {"entities":["Terraform","Prod cluster"],"relations":[["Terraform","provisions","Prod cluster"]]},
- *       {"entities":[],"relations":[]}
- *     ]
- *
- * If the model returns fewer than 3 items (partial failure), the caller
- * (`extractGraphFromBodies`) falls back to individual calls for missing indices.
- */
-function buildBatchSystemPrompt() {
-    return ("You extract knowledge graphs from developer notes. " +
-        "Return ONLY a valid JSON array — no prose, no markdown fences, no preamble. " +
-        "Each element of the array corresponds to one input asset, in order. " +
-        "The array length MUST equal the number of assets provided. " +
-        'Use {"entities":[],"relations":[]} for assets with no extractable graph content.');
-}
-/**
- * Hardened system prompt for the single batch retry (#635). Used only after a
- * first response failed array salvage — leans harder on "raw array only" so a
- * model that wrapped the array in prose/fences corrects itself before we pay
- * the per-asset fallback.
- */
-function buildBatchRetrySystemPrompt() {
-    return (`${buildBatchSystemPrompt()} ` +
-        "Your previous response could NOT be parsed as a JSON array. " +
-        "Respond with ONLY the raw JSON array — start with '[' and end with ']'. " +
-        "No prose, no explanation, no markdown code fences, no preamble.");
-}
-function buildBatchUserPrompt(bodies) {
-    const count = bodies.length;
-    const assetBlocks = bodies.map((body, i) => `${BATCH_ASSET_SEPARATOR} ${i + 1} ===\n${body.trim()}`).join("\n\n");
-    return (`Extract entities and relations from the N=${count} assets below.\n\n` +
-        `Rules:\n` +
-        `- Output ONLY a JSON array of exactly ${count} objects, one per asset, preserving input order.\n` +
-        `- Each object: {"entities": ["Entity One", ...], "relations": [["A", "uses", "B"], ...]}\n` +
-        `- Entities are short, canonical noun phrases (project names, services, tools, people, file/dir names, technical concepts).\n` +
-        `- Each relation is a 3-element array: [from, type, to]. Relations connect two entities that both appear in that asset's entities array.\n` +
-        `- "type" is a short verb phrase (e.g. "uses", "depends on", "owns"). Use "" when unsure.\n` +
-        `- Drop pleasantries, meta-commentary, and timestamps.\n` +
-        `- Limit to at most ${MAX_ENTITIES_PER_ASSET} entities and ${MAX_RELATIONS_PER_ASSET} relations per asset.\n` +
-        `- Use {"entities":[],"relations":[]} for assets with no extractable graph content.\n` +
-        `- The array MUST have exactly ${count} elements — one placeholder per asset even if empty.\n\n` +
-        assetBlocks);
-}
-function formatContextHint(llmRunner) {
-    return llmRunner.connection.contextLength ? `, configured contextLength=${llmRunner.connection.contextLength}` : "";
-}
-/** Dispatch one raw graph prompt through the common resolved-request adapter. */
-async function callGraphLlm(runner, messages, request, onNotices) {
-    return callStructured({
-        feature: "graph_extraction",
-        runner,
-        messages,
-        request,
-        onNotices,
-        parse: (raw) => raw ?? "",
-        onError: (_cls, error) => {
-            throw error;
-        },
-        fallback: "",
-    });
-}
-/**
- * Parse and validate a single item from the batch response array.
- * Mirrors the validation logic in `extractGraphFromBody`.
- */
-function parseBatchItem(raw) {
-    return parseGraphExtraction(raw);
-}
-function applySuccessfulBatchResults(results, batchResult, nonEmptyBodies, nonEmptyIndices, batchState, telemetry) {
-    if (batchState)
-        batchState.nonArrayBatchFailures = 0;
-    if (batchResult.length > nonEmptyBodies.length) {
-        warn(`graph extraction (batch): response had ${batchResult.length} items for ${nonEmptyBodies.length} assets; ` +
-            `ignoring ${batchResult.length - nonEmptyBodies.length} extra item(s).`);
-    }
-    for (let j = 0; j < nonEmptyBodies.length; j++) {
-        const originalIndex = nonEmptyIndices[j];
-        if (originalIndex === undefined)
-            continue;
-        if (j >= batchResult.length)
-            continue;
-        const extraction = parseBatchItem(batchResult[j]);
-        bumpFilterTelemetry(telemetry, extraction);
-        results[originalIndex] = extraction;
-    }
-}
-/**
- * Extract entities and relations from multiple asset bodies in a single LLM
- * call (batched graph extraction).
- *
- * Sends all `bodies` as a single prompt with `=== ASSET N ===` separators
- * and expects a JSON array where element `i` corresponds to `bodies[i]`.
- *
- * **Partial-failure handling**: if the model returns fewer elements than
- * `bodies.length`, missing indices are filled by falling back to individual
- * `extractGraphFromBody` calls — ensuring every input always has a result.
- *
- * Returns an array of the same length as `bodies` (never shorter). A body
- * whose extraction failed gets no entities and `status: "failed"`.
- *
- * Routes through `tryLlmFeature("graph_extraction", ...)` so the feature gate
- * and onFallback hook are honoured uniformly.
- *
- * @param llmRunner - Symbolic LLM runner selected through shared execution lowering.
- * @param bodies    - Asset body strings to process in one batch.
- * @param signal    - Optional AbortSignal for cancellation.
- * @param akmConfig - Full AKM config (for feature-gate checks).
- * @param onFallback - Optional fallback event sink.
- */
-export async function extractGraphFromBodies(llmRunner, bodies, signal, akmConfig, onFallback, options = {}) {
-    const empty = () => ({ entities: [], relations: [] });
-    const batchState = normalizeBatchState(options.batchState);
-    // Degenerate case: no bodies → empty array (not an error).
-    if (bodies.length === 0)
-        return [];
-    // Single body: delegate to the single-asset path for identical behaviour.
-    if (bodies.length === 1) {
-        const result = await extractGraphFromBody(llmRunner, bodies[0] ?? "", signal, akmConfig, onFallback, options);
-        return [result];
-    }
-    const concurrency = llmRunner.connection.concurrency ?? 1;
-    const extractOne = (body) => extractGraphFromBody(llmRunner, body, signal, akmConfig, onFallback, options);
-    // With batching disabled every body takes the single-asset path, once.
-    if (batchState?.batchingDisabled)
-        return mapWithConcurrency(bodies, concurrency, extractOne);
-    // Filter out bodies that are empty so we don't waste tokens, but keep
-    // index correspondence by tracking which indices were non-empty.
-    const results = bodies.map(empty);
-    const nonEmptyIndices = [];
-    const nonEmptyBodies = [];
-    const oversizedIndices = [];
-    for (let i = 0; i < bodies.length; i++) {
-        const trimmed = (bodies[i] ?? "").trim();
-        if (trimmed) {
-            if (trimmed.length > MAX_BATCH_BODY_CHARS) {
-                oversizedIndices.push(i);
-            }
-            else {
-                nonEmptyIndices.push(i);
-                nonEmptyBodies.push(trimmed);
-            }
-        }
-    }
-    await mapWithConcurrency(oversizedIndices, concurrency, async (index) => {
-        results[index] = await extractOne(bodies[index] ?? "");
-    });
-    if (nonEmptyBodies.length === 0)
-        return results;
-    const systemPrompt = buildBatchSystemPrompt();
-    const userPrompt = buildBatchUserPrompt(nonEmptyBodies);
-    // Same responseSchema lift as extractGraphFromBody (R12b), scoped to this
-    // batch's asset count so a compliant provider bounds every element's
-    // entities/relations by the same maxItems as the single-asset path.
-    const batchResponseSchema = buildBatchResponseSchema(nonEmptyBodies.length);
-    let batchContextError = false;
-    // R2: a dead/erroring provider must not be hammered with a per-asset
-    // fallback retry for every body in the batch — that is what turned one
-    // outage into 15,453 additional retry attempts. `isTransportFailure`
-    // (shared with client.ts's `isRetryable` — see its definition) covers
-    // `provider_error`, `network_error`, and `provider_html_error`: the
-    // provider itself is failing (a dead endpoint more often raises
-    // `network_error` or `provider_html_error` than a plain 5xx), not that this
-    // particular response was malformed; skip the fallback and record every
-    // asset as failed instead. A batch that got no answer at all (the gate's
-    // timeout, or a closed gate) is handled the same way.
-    let batchProviderError = false;
-    const batchOutcome = await tryLlmFeature("graph_extraction", akmConfig, async () => {
-        try {
-            const raw = await callGraphLlm(llmRunner, [
-                { role: "system", content: systemPrompt },
-                { role: "user", content: userPrompt },
-            ], {
-                temperature: 0.1,
-                timeoutMs: llmRunner.timeoutMs,
-                signal,
-                responseSchema: batchResponseSchema,
-                onRetryAttempt: () => bumpTelemetry(options.telemetry, "retryAttempts"),
-            }, options.onNotices);
-            if (!raw)
-                return { kind: "value", value: null };
-            // Array-preferring salvage (#635): the batch contract is a top-level
-            // JSON array. A leading/example `{…}` object in the response must not
-            // mask a valid `[…]` array as a false "non-array" failure.
-            let parsed = parseEmbeddedJsonResponse(raw, { expect: "array" });
-            if (!Array.isArray(parsed)) {
-                // One stricter-reprompt retry before paying the per-asset fallback
-                // (#635). Many genuine non-array responses recover when the model is
-                // told explicitly to emit only the raw array.
-                bumpTelemetry(options.telemetry, "retryAttempts");
-                const retryRaw = await callGraphLlm(llmRunner, [
-                    { role: "system", content: buildBatchRetrySystemPrompt() },
-                    { role: "user", content: userPrompt },
-                ], {
-                    temperature: 0,
-                    timeoutMs: llmRunner.timeoutMs,
-                    signal,
-                    responseSchema: batchResponseSchema,
-                }, options.onNotices);
-                parsed = retryRaw ? parseEmbeddedJsonResponse(retryRaw, { expect: "array" }) : undefined;
-            }
-            if (!Array.isArray(parsed)) {
-                bumpTelemetry(options.telemetry, "nonArrayBatchFailures");
-                if (batchState) {
-                    batchState.nonArrayBatchFailures += 1;
-                    if (batchState.nonArrayBatchFailures >= NON_ARRAY_BATCH_DISABLE_THRESHOLD) {
-                        batchState.batchingDisabled = true;
-                    }
-                }
-                warn(`graph extraction (batch): LLM response was not a JSON array for ${nonEmptyBodies.length} asset(s) ` +
-                    `even after a stricter retry; will fall back per-asset. ` +
-                    `promptChars=${userPrompt.length}${formatContextHint(llmRunner)}`);
-                return { kind: "value", value: null };
-            }
-            return { kind: "value", value: parsed };
-        }
-        catch (err) {
-            if (err instanceof ConfigError)
-                return { kind: "config-error", error: err };
-            const errMsg = toErrorMessage(err);
-            if (isContextSizeError(errMsg)) {
-                batchContextError = true;
-                bumpTelemetry(options.telemetry, "contextBatchRetries");
-                warn(`graph extraction (batch): context size exceeded for ${nonEmptyBodies.length} asset(s); ` +
-                    `skipping batch. promptChars=${userPrompt.length}${formatContextHint(llmRunner)}`);
-            }
-            else if (err instanceof LlmCallError && isTransportFailure(err)) {
-                batchProviderError = true;
-                bumpTelemetry(options.telemetry, "failureCount", nonEmptyBodies.length);
-                warn(`graph extraction (batch): provider error (${err.code}) for ${nonEmptyBodies.length} asset(s); ` +
-                    `skipping per-asset fallback retries. promptChars=${userPrompt.length}${formatContextHint(llmRunner)}: ${errMsg}`);
-            }
-            else {
-                warn(`graph extraction (batch) failed for ${nonEmptyBodies.length} asset(s); ` +
-                    `promptChars=${userPrompt.length}${formatContextHint(llmRunner)}: ${errMsg}`);
-            }
-            return { kind: "value", value: null };
-        }
-    }, { kind: "no-answer" }, {
-        timeoutMs: llmRunner.timeoutMs,
-        onFallback,
-    });
-    if (batchOutcome.kind === "config-error")
-        throw batchOutcome.error;
-    if (batchOutcome.kind === "no-answer") {
-        batchProviderError = true;
-        bumpTelemetry(options.telemetry, "failureCount", nonEmptyBodies.length);
-    }
-    const batchResult = batchOutcome.kind === "value" ? batchOutcome.value : null;
-    // Map successful batch results back to their original indices.
-    if (batchResult !== null) {
-        applySuccessfulBatchResults(results, batchResult, nonEmptyBodies, nonEmptyIndices, batchState, options.telemetry);
-    }
-    else if (batchProviderError) {
-        // No per-asset fallback against a failing provider — record every asset
-        // in this batch as a genuine failure so it is neither silently empty nor
-        // retried again below.
-        for (const origIdx of nonEmptyIndices)
-            results[origIdx] = { entities: [], relations: [], status: "failed", reason: "llm_error" };
-    }
-    if (batchContextError && nonEmptyBodies.length > 1) {
-        const splitAt = Math.ceil(nonEmptyBodies.length / 2);
-        const left = await extractGraphFromBodies(llmRunner, nonEmptyBodies.slice(0, splitAt), signal, akmConfig, onFallback, options);
-        const right = await extractGraphFromBodies(llmRunner, nonEmptyBodies.slice(splitAt), signal, akmConfig, onFallback, options);
-        const combined = [...left, ...right];
-        for (let j = 0; j < nonEmptyIndices.length; j++) {
-            const origIdx = nonEmptyIndices[j];
-            if (origIdx === undefined)
-                continue;
-            results[origIdx] = combined[j] ?? empty();
-        }
-        return results;
-    }
-    // Partial-failure fallback: any non-empty body whose result is still the
-    // empty placeholder (either because batchResult was null or the array was
-    // shorter than expected) gets an individual retry — unless the batch failed
-    // due to context size, in which case individual calls would also fail.
-    const fallbackIndices = nonEmptyIndices.filter((_origIdx, j) => {
-        if (batchContextError)
-            return false; // skip individual retries on context error
-        if (batchProviderError)
-            return false; // skip individual retries against a failing provider
-        // Result is still empty → needs a fallback call.
-        if (batchResult === null)
-            return true;
-        // batchResult was shorter than the number of non-empty bodies.
-        return j >= batchResult.length;
-    });
-    if (fallbackIndices.length > 0) {
-        if (batchResult !== null) {
-            // Only warn on partial failure (not when the whole batch failed, which
-            // already emitted a warn above).
-            warn(`graph extraction (batch): response had ${batchResult.length} items for ${nonEmptyBodies.length} assets; ` +
-                `falling back to individual calls for ${fallbackIndices.length} missing asset(s).`);
-        }
-        await mapWithConcurrency(fallbackIndices, concurrency, async (origIdx) => {
-            results[origIdx] = await extractOne(bodies[origIdx] ?? "");
-        });
-    }
-    else if (batchContextError) {
-        warn(`graph extraction (batch): skipped ${nonEmptyBodies.length} asset(s) due to context size error; ` +
-            `consider increasing llm.contextLength or reducing index.graph.graphExtractionBatchSize to 1.`);
-    }
-    return results;
-}
-/**
- * Extract entities and relations from a single asset body via the configured LLM.
- *
- * Any failure (timeout, invalid JSON, empty response, provider error) returns
- * no entities with `status: "failed"`, which is never cached, so the next run
- * retries it. Errors are logged via `warn()` but never thrown — a failed
- * extraction for one asset must not abort the rest of the index pass.
- *
- * Routes through `tryLlmFeature("graph_extraction", ...)` so the feature gate
- * and onFallback hook are honoured uniformly (Fix C5).
- */
-export async function extractGraphFromBody(llmRunner, body, signal, akmConfig, onFallback, options = {}) {
-    const empty = (reason, status) => ({
-        entities: [],
-        relations: [],
-        ...(status ? { status } : {}),
-        ...(reason ? { reason } : {}),
-    });
-    const trimmedBody = body.trim();
-    if (!trimmedBody)
-        return empty();
-    const chunked = splitBodyIntoChunks(trimmedBody, MAX_CHUNK_BODY_CHARS);
-    if (chunked.truncationCount > 0) {
-        bumpTelemetry(options.telemetry, "truncationCount", chunked.truncationCount);
-        warnVerbose(`graph extraction: split a long asset into ${chunked.chunks.length} chunk(s) with ${chunked.truncationCount} hard split(s).`);
-    }
-    // R12b + R20: bound per-asset cost by capping how many chunks of a long
-    // asset are ever sent to the LLM. Excess chunks are dropped, never
-    // processed — the coverage loss is recorded as truncatedChunks rather than
-    // silently absorbed.
-    const maxChunksPerAsset = options.maxChunksPerAsset ?? DEFAULT_MAX_CHUNKS_PER_ASSET;
-    const cappedChunks = chunked.chunks.length > maxChunksPerAsset ? chunked.chunks.slice(0, maxChunksPerAsset) : chunked.chunks;
-    const truncatedChunkCount = chunked.chunks.length - cappedChunks.length;
-    if (truncatedChunkCount > 0) {
-        bumpTelemetry(options.telemetry, "truncatedChunks", truncatedChunkCount);
-        warnVerbose(`graph extraction: capped a long asset to ${cappedChunks.length} of ${chunked.chunks.length} chunk(s) ` +
-            `(maxChunksPerAsset=${maxChunksPerAsset}); ${truncatedChunkCount} chunk(s) not processed.`);
-    }
-    if (cappedChunks.length > 1) {
-        const chunkResults = [];
-        for (const chunk of cappedChunks) {
-            chunkResults.push(await extractGraphFromBody(llmRunner, chunk, signal, akmConfig, onFallback, options));
-        }
-        const merged = mergeGraphExtractions(chunkResults);
-        merged.truncationCount = (merged.truncationCount ?? 0) + chunked.truncationCount;
-        merged.truncatedChunks = (merged.truncatedChunks ?? 0) + truncatedChunkCount;
-        return merged;
-    }
-    // When capped down to exactly one chunk from a body that originally split
-    // into more, that single surviving chunk (not the full trimmedBody) is what
-    // must be sent — otherwise the cap would have no effect on prompt size.
-    const bodyForCall = truncatedChunkCount > 0 ? (cappedChunks[0] ?? trimmedBody) : trimmedBody;
-    const userPrompt = `${USER_PROMPT_PREFIX}${bodyForCall}`;
-    const result = await callStructured({
-        feature: "graph_extraction",
-        akmConfig,
-        runner: llmRunner,
-        messages: [
-            { role: "system", content: SYSTEM_PROMPT },
-            { role: "user", content: userPrompt },
-        ],
-        request: {
-            temperature: 0.1,
-            timeoutMs: llmRunner.timeoutMs,
-            signal,
-            responseSchema: GRAPH_EXTRACTION_JSON_SCHEMA,
-            onRetryAttempt: () => bumpTelemetry(options.telemetry, "retryAttempts"),
-        },
-        onNotices: options.onNotices,
-        parse: (raw) => {
-            // An empty response is not JSON either; "nothing to extract" is `{"entities": []}`.
-            const parsed = raw ? parseEmbeddedJsonResponse(raw) : undefined;
-            if (!parsed) {
-                warn("graph extraction: invalid JSON response from LLM; skipping asset.");
-                bumpTelemetry(options.telemetry, "failureCount");
-                return empty("invalid_json", "failed");
-            }
-            const extraction = parseGraphExtraction(parsed);
-            bumpFilterTelemetry(options.telemetry, extraction);
-            if (extraction.status === "failed")
-                bumpTelemetry(options.telemetry, "failureCount");
-            return extraction;
-        },
-        onError: (cls, err) => {
-            const errMsg = toErrorMessage(err);
-            if (cls === "context_limit") {
-                bumpTelemetry(options.telemetry, "failureCount");
-                warn(`graph extraction: context size exceeded for asset; promptChars=${userPrompt.length}${formatContextHint(llmRunner)}. ` +
-                    `Consider increasing llm.contextLength in config.json.`);
-                return empty("context_limit", "failed");
-            }
-            else if (cls === "html") {
-                bumpTelemetry(options.telemetry, "htmlErrorCount");
-                warn(`graph extraction: provider returned HTML instead of JSON for asset; promptChars=${userPrompt.length}${formatContextHint(llmRunner)}: ${errMsg}`);
-                return empty("llm_error", "failed");
-            }
-            else {
-                bumpTelemetry(options.telemetry, "failureCount");
-                warn(`graph extraction failed for asset; promptChars=${userPrompt.length}${formatContextHint(llmRunner)}: ${errMsg}`);
-                return empty("llm_error", "failed");
-            }
-        },
-        // No answer from the model (the gate's timeout, or a closed gate) is a
-        // failure the next run retries, never a cacheable "no entities".
-        fallback: empty("llm_error", "failed"),
-        onFallback,
-    });
-    if (truncatedChunkCount > 0)
-        result.truncatedChunks = (result.truncatedChunks ?? 0) + truncatedChunkCount;
-    return result;
-}