akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/indexer/bundle-identity-guard.js

@@ -0,0 +1,92 @@
+// 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/.
+/**
+ * §11.5 bundle-rename startup guard.
+ *
+ * Renaming a workspace bundle id is a mass identity migration (every ref in the
+ * bundle changes without any file moving) and MUST go through the future
+ * explicit `akm bundle rename <old> <new>` command, which rekeys the index +
+ * every ref-keyed state table atomically. If a user instead hand-edits the
+ * `bundles` KEY in config.json, the durable index/state rows still carry the OLD
+ * bundle prefix while the config names the NEW id. Silently re-minting fresh
+ * state under the new id would strand the old rows; §11.5 requires we detect this
+ * and refuse-or-warn.
+ *
+ * This guard implements the cheap heuristic form (WARN, never silently re-mint):
+ * it compares the configured bundle ids against the DISTINCT `bundle_id`
+ * (item_ref bundle prefix) values already persisted in the index — and, by
+ * cutover construction, the same prefixes key the state.db usage/salience rows.
+ * The hand-rename signature is: a configured bundle id with NO indexed rows
+ * co-existing with indexed rows under a bundle id that is no longer configured.
+ *
+ * SEAM CHOICE: invoked from `ensureIndex` — the single funnel every read/index
+ * path passes through before consuming or (re)building the index, so the guard
+ * fires BEFORE a stale-index rebuild could re-mint fresh rows under the new id.
+ * It has a handful of call sites (vs. `loadConfig`'s hundreds), reads a cached
+ * config plus one indexed `DISTINCT` query, and settles after the first
+ * comparison over a non-empty index so the steady-state cost is a boolean check.
+ */
+import fs from "node:fs";
+import { loadConfig } from "../core/config/config.js";
+import { getDbPath } from "../core/paths.js";
+import { warn } from "../core/warn.js";
+import { openDatabase } from "../storage/database.js";
+let guardSettled = false;
+/** TEST-ONLY: re-arm the once-per-process guard between cases. */
+export function resetBundleIdentityGuardForTests() {
+    guardSettled = false;
+}
+/** Distinct non-empty `bundle_id` prefixes persisted in the index, or `undefined` when unreadable. */
+function indexBundlePrefixes(dbPath) {
+    if (!fs.existsSync(dbPath))
+        return undefined;
+    let db;
+    try {
+        db = openDatabase(dbPath, { readonly: true });
+        if (!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='entries'").get())
+            return undefined;
+        return db
+            .prepare("SELECT DISTINCT bundle_id AS b FROM entries WHERE bundle_id IS NOT NULL AND bundle_id != ''")
+            .all().map((row) => row.b);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        db?.close();
+    }
+}
+/**
+ * Warn (once per process) when the config's bundle ids and the index's bundle
+ * prefixes show the hand-rename signature (§11.5). No-op for an old-shape config
+ * (no `bundles`), an absent/empty index, or when the guard already settled.
+ */
+export function warnOnBundleRenameDrift(config = loadConfig()) {
+    if (guardSettled)
+        return;
+    const bundles = config.bundles;
+    if (!bundles)
+        return; // old-shape config — no bundle identity to guard (do not settle)
+    const configIds = new Set(Object.keys(bundles));
+    if (configIds.size === 0)
+        return;
+    const indexIds = indexBundlePrefixes(getDbPath());
+    if (indexIds === undefined || indexIds.length === 0)
+        return; // nothing indexed yet — re-check later
+    // A real comparison happened over a populated index: settle so the steady
+    // state is one boolean check.
+    guardSettled = true;
+    const indexIdSet = new Set(indexIds);
+    const configuredMissingFromIndex = [...configIds].filter((id) => !indexIdSet.has(id));
+    const indexedNotConfigured = indexIds.filter((id) => !configIds.has(id));
+    if (configuredMissingFromIndex.length === 0 || indexedNotConfigured.length === 0)
+        return;
+    warn("WARNING: bundle identity drift detected. " +
+        `Configured bundle(s) with no indexed content: ${configuredMissingFromIndex.map((id) => `"${id}"`).join(", ")}; ` +
+        `indexed content under unconfigured bundle id(s): ${indexedNotConfigured.map((id) => `"${id}"`).join(", ")}. ` +
+        "This is the signature of a hand-renamed bundle id (spec §11.5). AKM will NOT silently re-mint fresh state " +
+        "under the new id. There is no rekey command in 0.9.0: either restore the previous bundle id in config.json " +
+        "to reattach the existing rows, or keep the new id and run `akm index --full` to re-mint under it, accepting " +
+        "that learned state (utility, salience, outcomes, usage history) keyed to the old id is left behind.");
+}

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

@@ -4,7 +4,7 @@
 import fs from "node:fs";
 import { rethrowIfTestIsolationError } from "../../core/errors.js";
 import { getDbPath } from "../../core/paths.js";
-import { closeDatabase, openExistingDatabase } from "./db.js";
+import { closeDatabase, openExistingDatabase } from "../../storage/repositories/index-connection.js";
 function withReadableGraphDb(db, fn) {
     if (db)
         return fn(db);
@@ -215,13 +215,6 @@ export function drainExtractionQueue(db, stashRoot, limit) {
         return [];
     }
 }
-/**
- * Scoped loader — only the graph_meta row for a stash. Used by callers that
- * only need summary numbers (e.g. `akm graph summary`).
- */
-export function loadGraphMetaOnly(stashPath, db) {
-    return loadStoredGraphMeta(stashPath, db);
-}
 /**
  * Scoped loader — graph_files rows without entities/relations. Used for
  * orphan detection and entity overview commands.
@@ -256,23 +249,6 @@ export function loadGraphFilesOnly(stashPath, db) {
         return [];
     }
 }
-/**
- * Scoped loader — entities for a single file, keyed on the #624-P1 composite
- * (stash_root, file_path, body_hash). Used by per-asset show/curate lookups.
- */
-export function loadGraphEntitiesByPath(db, stashRoot, filePath, bodyHash) {
-    try {
-        const rows = db
-            .prepare(`SELECT entity FROM graph_file_entities
-          WHERE stash_root = ? AND file_path = ? AND body_hash = ?
-          ORDER BY entity_order`)
-            .all(stashRoot, filePath, bodyHash);
-        return rows.map((r) => r.entity);
-    }
-    catch {
-        return [];
-    }
-}
 export function loadStoredGraphMeta(stashPath, db) {
     try {
         return withReadableGraphDb(db, (readDb) => {

package/dist/indexer/db/llm-cache.js

@@ -9,7 +9,7 @@
  * duplicating the hash-compute → lookup → write pattern inline.
  */
 import { bestEffort } from "../../core/best-effort.js";
-import { computeBodyHash, getLlmCacheEntry, upsertLlmCacheEntry } from "./db.js";
+import { computeBodyHash, getLlmCacheEntry, upsertLlmCacheEntry, } from "../../storage/repositories/index-llm-cache-repository.js";
 /**
  * Generic LLM cache wrapper. Returns cached result if body unchanged,
  * otherwise calls llmFn(), caches the result, and returns it.

package/dist/indexer/ensure-index.js

@@ -14,17 +14,20 @@
  * populated index exists. The previous design — a staleness walk plus a
  * detached background reindex per read — made every read on an actively
  * written stash spawn a writer that the read's own telemetry then queued
- * behind (see docs/design/read-path-reindex-contention-findings.md).
+ * behind (the 2026-07 read-path reindex-contention findings).
  *
  * `mode: "blocking"` (improve) still checks staleness and rebuilds inline,
  * because its planning logic needs a current `entries` table in-process.
  */
 import fs from "node:fs";
 import path from "node:path";
-import { ASSET_SPECS, TYPE_DIRS } from "../core/asset/asset-spec.js";
+import { placementSpecList } from "../core/asset/asset-placement.js";
 import { getDbPath } from "../core/paths.js";
 import { warn } from "../core/warn.js";
-import { closeDatabase, getEntryCount, getIndexedFilePaths, getMeta, openExistingDatabase } from "./db/db.js";
+import { closeDatabase, openExistingDatabase } from "../storage/repositories/index-connection.js";
+import { getEntryCount, getIndexedFilePaths } from "../storage/repositories/index-entries-repository.js";
+import { getMeta } from "../storage/repositories/index-meta-repository.js";
+import { warnOnBundleRenameDrift } from "./bundle-identity-guard.js";
 function getIndexableFiles(root, spec) {
     if (!fs.existsSync(root))
         return [];
@@ -80,8 +83,8 @@ function getIndexableFiles(root, spec) {
 function hasNewerIndexableFiles(stashDir, builtAt, indexedPaths) {
     const builtAtMs = builtAt ? new Date(builtAt).getTime() : Number.NaN;
     const builtAtUsable = Number.isFinite(builtAtMs);
-    for (const [type, spec] of Object.entries(ASSET_SPECS)) {
-        const typeRoot = path.join(stashDir, TYPE_DIRS[type] ?? spec.stashDir);
+    for (const spec of placementSpecList()) {
+        const typeRoot = path.join(stashDir, spec.stashDir);
         const files = getIndexableFiles(typeRoot, spec);
         for (const file of files) {
             if (!indexedPaths.has(file))
@@ -177,13 +180,20 @@ function indexCanServeStash(stashDir) {
             closeDatabase(db);
     }
 }
-async function runInlineReindex(stashDir) {
+async function runInlineReindex(stashDir, options = {}) {
     try {
         const { akmIndex } = await import("./indexer.js");
-        await akmIndex({ stashDir });
+        await akmIndex({
+            stashDir,
+            implicit: true,
+            ...(options.signal ? { signal: options.signal } : {}),
+            ...(options.hydrateSources === false ? { hydrateSources: false } : {}),
+        });
         return true;
     }
     catch (error) {
+        if (options.signal?.aborted)
+            throw error;
         warn("Auto-index failed, proceeding with existing index:", error instanceof Error ? error.message : String(error));
         return false;
     }
@@ -204,12 +214,23 @@ async function runInlineReindex(stashDir) {
  * A rebuild attempt that fails (throws) resolves to `false`.
  */
 export async function ensureIndex(stashDir, options = {}) {
+    // §11.5: warn (once) if the configured bundle ids drifted from the persisted
+    // index prefixes (hand-renamed bundle key) BEFORE any rebuild could re-mint.
+    warnOnBundleRenameDrift();
     if (options.mode === "blocking") {
+        // Blocking callers (improve's planning preflight) are a sanctioned
+        // materialization point — hydrate cache-backed sources as usual.
         if (!isIndexStale(stashDir))
             return false;
-        return runInlineReindex(stashDir);
+        return runInlineReindex(stashDir, { ...(options.signal ? { signal: options.signal } : {}) });
     }
+    // Background = the READ path (`show` auto-index): query time must never clone/
+    // pull/fetch (spec §14.3 / D11). Build from already-materialized content only;
+    // absent source caches are skipped with a warning, not fetched.
     if (indexCanServeStash(stashDir))
         return false;
-    return runInlineReindex(stashDir);
+    return runInlineReindex(stashDir, {
+        ...(options.signal ? { signal: options.signal } : {}),
+        hydrateSources: false,
+    });
 }

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

@@ -249,10 +249,9 @@ export function collectGraphRelatedHit(context, filePath) {
  * NOT entries.id — so candidates are identified by file_path (the unique index
  * idx_graph_files_path guarantees one graph_files row per path).
  *
- * The returned `ref` field carries the canonical asset ref (`type:name`)
- * resolved from entries.entry_key when the file is indexed. Callers should
- * fall back to formatting `path` when `ref` is undefined (graph row with no
- * matching entries row).
+ * The returned `ref` field carries the canonical indexed `concept_id`, never a
+ * value re-derived from presentation fields or `entry_key`. It is undefined
+ * when the graph row has no matching entry with current indexed provenance.
  */
 export function listRelatedPathsForFile(stashRoot, filePath, limit = 5, db) {
     if (!db) {
@@ -343,20 +342,17 @@ export function listRelatedPathsForFile(stashRoot, filePath, limit = 5, db) {
             relationCountByPath.set(row.file_path, (relationCountByPath.get(row.file_path) ?? 0) + 1);
         }
     }
-    // Optional: ref lookup via entries.entry_key. entry_key is stored as
-    // `${stash_dir}:${type}:${name}` — strip the stash-dir prefix to get the
-    // user-facing `type:name`. Resolve by (stash_dir, file_path) now that the
-    // graph rows are no longer keyed on entries.id.
+    // This related list is scoped to one source root, so the user-facing ref is
+    // the indexed bundle-less conceptId.
     const refByPath = new Map();
     try {
         const entryRows = db
-            .prepare(`SELECT entry_key, stash_dir, file_path FROM entries
-          WHERE file_path IN (${placeholders}) AND stash_dir = ?`)
+            .prepare(`SELECT file_path, concept_id FROM entries
+          WHERE file_path IN (${placeholders}) AND stash_dir = ?
+            AND item_ref IS NOT NULL AND concept_id IS NOT NULL`)
             .all(...candidatePaths, stashRoot);
         for (const row of entryRows) {
-            const ref = stripStashPrefix(row.entry_key, row.stash_dir);
-            if (ref)
-                refByPath.set(row.file_path, ref);
+            refByPath.set(row.file_path, row.concept_id);
         }
     }
     catch {
@@ -375,23 +371,6 @@ export function listRelatedPathsForFile(stashRoot, filePath, limit = 5, db) {
         };
     });
 }
-/**
- * Convert an entries.entry_key to a user-facing asset ref. Entry keys are
- * stored as `${stash_dir}:${type}:${name}`; strip the stash-dir prefix.
- */
-function stripStashPrefix(entryKey, stashDir) {
-    const prefix = `${stashDir}:`;
-    if (entryKey.startsWith(prefix))
-        return entryKey.slice(prefix.length);
-    // Fall back to last two colon-separated segments.
-    const lastColon = entryKey.lastIndexOf(":");
-    if (lastColon < 0)
-        return entryKey;
-    const prevColon = entryKey.lastIndexOf(":", lastColon - 1);
-    if (prevColon < 0)
-        return entryKey;
-    return entryKey.slice(prevColon + 1);
-}
 /**
  * Load and normalize graph data from SQLite once, then reuse it across all
  * per-entry boost lookups in the current query.

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

@@ -8,7 +8,7 @@
  * 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
+ * pipeline (see `src/indexer/graph/graph-boost.ts`) as a single boost component
  * inside the existing FTS5+boosts loop — there is NO second SearchHit
  * scorer and no parallel ranking track.
  *
@@ -16,7 +16,7 @@
  *   1. An LLM profile must be configured (no provider = no extraction). When
  *      absent, `resolveIndexPassLLM("graph", config)` returns `undefined`
  *      and the pass short-circuits.
- *   2. `profiles.improve.default.processes.graphExtraction.enabled !== false`
+ *   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
  *      feature-gate layer (no network call may ever issue).
@@ -31,13 +31,16 @@
  *   - 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
+ *     hits, and is not addressable via `akm show`. The persisted artifact
+ *     lives in indexer-owned SQLite tables (`replaceStoredGraph` /
+ *     `loadStoredGraphSnapshot` in `../db/graph-db.ts`), NOT as a file on
+ *     disk (R-065 #3 — this comment previously described a retired
+ *     `fs.writeFile`-based storage layout) — `writeAssetToSource` is
  *     reserved for asset writes (CLAUDE.md / spec §10 step 5).
  */
 import fs from "node:fs";
 import path from "node:path";
-import { TYPE_DIRS } from "../../core/asset/asset-spec.js";
+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";
@@ -46,9 +49,9 @@ import { warn, warnVerbose } from "../../core/warn.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 "../db/db.js";
+import { computeBodyHash, getLlmCacheEntriesByRefs, getLlmCacheEntry, 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 { GRAPH_SCHEMA_VERSION } from "../db/schema.js";
 import { walkMarkdownFiles } from "../walk/walker.js";
 import { deduplicateGraph } from "./graph-dedup.js";
 /** Schema version for the persisted artifact — bumps trigger a full rebuild. */
@@ -109,7 +112,6 @@ const SUPPORTED_GRAPH_EXTRACTION_INCLUDE_TYPES = new Set([
     "workflow",
     "lesson",
     "task",
-    "wiki",
 ]);
 const GRAPH_CACHE_VARIANT_PREFIX = "graph-extraction";
 function normalizeConfidence(raw) {
@@ -260,7 +262,7 @@ function reuseGraphNode(previousNodes, candidate, bodyHash) {
  *   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** — `profiles.improve.default.processes.graphExtraction.enabled`
+ *   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.
  *   3. **Per-pass gate** — `index.graph.llm` (defaults to `true`). When
@@ -276,21 +278,25 @@ 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");
     // Gate 1 — feature gate via isProcessEnabled, which reads the 0.8.0 path
-    // (profiles.improve.default.processes.graphExtraction.enabled). Defaults to
+    // (selected strategy's processes.graphExtraction.enabled). Defaults to
     // enabled when the key is absent.
-    if (!isProcessEnabled("index", "graph_extraction", config))
+    if (!invocationOwnsConnection && !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);
+    const llmConfig = Object.hasOwn(ctx, "llmConfig") ? ctx.llmConfig : resolveIndexPassLLM("graph", config);
     if (!llmConfig) {
-        const reason = getIndexPassConfig(config.index, "graph")?.llm === false
-            ? "index.graph.llm is false"
-            : "no default LLM profile is configured";
+        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 };
     }
+    const featureConfig = invocationOwnsConnection
+        ? { ...config, index: { ...config.index, graph: { ...config.index?.graph, enabled: true } } }
+        : config;
     // 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().
@@ -309,10 +315,14 @@ export async function runGraphExtractionPass(ctx) {
         for (const queued of drained) {
             if (signal?.aborted)
                 break;
-            await extractGraphForSingleFile(db, primary.path, queued.filePath, queued.bodyHash, { config, signal });
+            await extractGraphForSingleFile(db, primary.path, queued.filePath, queued.bodyHash, {
+                config: featureConfig,
+                signal,
+                llmConfig,
+            });
         }
     }
-    const includeTypes = getGraphExtractionIncludeTypes(config);
+    const includeTypes = options.includeTypes ?? getGraphExtractionIncludeTypes(config);
     let eligible = collectEligibleFiles(primary.path, includeTypes).filter((candidate) => !options.candidatePaths || options.candidatePaths.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
@@ -357,7 +367,7 @@ export async function runGraphExtractionPass(ctx) {
     // 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 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;
@@ -438,7 +448,7 @@ export async function runGraphExtractionPass(ctx) {
             }
             if (!cached) {
                 telemetry.cacheMisses += 1;
-                const extraction = await graphExtract.extractGraphFromBody(llmConfig, candidate.body, signal, config, onFallback, { batchState, telemetry: runtimeTelemetry });
+                const extraction = await graphExtract.extractGraphFromBody(llmConfig, candidate.body, signal, featureConfig, onFallback, { batchState, telemetry: runtimeTelemetry });
                 cached = {
                     entities: extraction.entities,
                     relations: extraction.relations,
@@ -463,8 +473,8 @@ export async function runGraphExtractionPass(ctx) {
             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).
+        // Caller-set connection concurrency or 1: `resolveLlmEngineUse` does
+        // not forward `engines.<name>.concurrency`, so config cannot raise this.
         llmConfig.concurrency ?? 1);
     }
     else {
@@ -562,7 +572,7 @@ export async function runGraphExtractionPass(ctx) {
             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, { batchState, telemetry: runtimeTelemetry });
+            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++) {
@@ -670,7 +680,7 @@ function inferGraphTypeForPath(stashRoot, absPath) {
     if (!firstSeg)
         return undefined;
     for (const type of SUPPORTED_GRAPH_EXTRACTION_INCLUDE_TYPES) {
-        if (TYPE_DIRS[type] === firstSeg)
+        if (stashDirFor(type) === firstSeg)
             return type;
     }
     return undefined;
@@ -718,12 +728,16 @@ export async function extractGraphForSingleFile(db, stashRoot, filePath, bodyHas
         }
         else {
             const config = opts?.config ?? loadConfig();
-            if (!isProcessEnabled("index", "graph_extraction", config))
+            const invocationOwnsConnection = Object.hasOwn(opts ?? {}, "llmConfig");
+            if (!invocationOwnsConnection && !isProcessEnabled("index", "graph_extraction", config))
                 return false;
-            const llmConfig = resolveIndexPassLLM("graph", config);
+            const llmConfig = Object.hasOwn(opts ?? {}, "llmConfig") ? opts?.llmConfig : resolveIndexPassLLM("graph", config);
             if (!llmConfig)
                 return false; // model-available guard
-            const result = await graphExtract.extractGraphFromBody(llmConfig, body, opts?.signal, config);
+            const featureConfig = invocationOwnsConnection
+                ? { ...config, index: { ...config.index, graph: { ...config.index?.graph, enabled: true } } }
+                : config;
+            const result = await graphExtract.extractGraphFromBody(llmConfig, body, opts?.signal, featureConfig);
             extraction = {
                 entities: result.entities,
                 relations: result.relations,
@@ -848,7 +862,7 @@ export function collectEligibleFiles(stashRoot, includeTypes = [...DEFAULT_GRAPH
         const type = rawType.trim().toLowerCase();
         if (!SUPPORTED_GRAPH_EXTRACTION_INCLUDE_TYPES.has(type))
             continue;
-        const stashDir = TYPE_DIRS[type];
+        const stashDir = stashDirFor(type);
         if (!stashDir)
             continue;
         const dir = path.join(stashRoot, stashDir);

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

@@ -0,0 +1,4 @@
+// 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 {};