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

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

@@ -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).
@@ -260,7 +260,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 +276,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 +313,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 +365,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 +446,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,
@@ -562,7 +570,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++) {
@@ -718,12 +726,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,

package/dist/indexer/index-writer-lock.js

@@ -3,15 +3,15 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { probeLock, releaseLock, releaseLockIfOwned, tryAcquireLockSync } from "../core/file-lock.js";
+import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync, } from "../core/file-lock.js";
+import { tryAcquireMaintenanceBarrier } from "../core/maintenance-barrier.js";
 import { getDbPath, getIndexWriterLockPath } from "../core/paths.js";
 const INDEX_WRITER_LOCK_STALE_AFTER_MS = 12 * 60 * 60 * 1000;
 const INDEX_WRITER_WAIT_MS = 100;
 const DEFAULT_INDEX_WRITER_MAX_WAIT_MS = 10 * 60 * 1000;
 const heldLocks = new Map();
-function buildPayload(purpose, pid = process.pid) {
-    return JSON.stringify({
-        pid,
+function buildPayload(purpose) {
+    return createLockPayload({
         purpose,
         dbPath: getDbPath(),
         startedAt: new Date().toISOString(),
@@ -34,17 +34,19 @@ function releaseHeldLock(lockPath) {
         return;
     heldLocks.delete(lockPath);
     process.off("exit", held.exitHandler);
-    releaseLockIfOwned(lockPath, process.pid);
+    releaseLock(held.ownership);
 }
-function retainHeldLock(lockPath) {
+function retainHeldLock(lockPath, ownership) {
     const existing = heldLocks.get(lockPath);
     if (existing) {
         existing.depth += 1;
         return { lockPath, release: () => releaseHeldLock(lockPath) };
     }
-    const exitHandler = () => releaseLockIfOwned(lockPath, process.pid);
+    if (!ownership)
+        throw new Error(`Missing ownership for index writer lock at ${lockPath}.`);
+    const exitHandler = () => releaseLock(ownership);
     process.on("exit", exitHandler);
-    heldLocks.set(lockPath, { depth: 1, exitHandler });
+    heldLocks.set(lockPath, { depth: 1, exitHandler, ownership });
     return { lockPath, release: () => releaseHeldLock(lockPath) };
 }
 export async function acquireIndexWriterLease(options) {
@@ -53,25 +55,30 @@ export async function acquireIndexWriterLease(options) {
     const startedAt = Date.now();
     const maxWaitMs = options.maxWaitMs ?? DEFAULT_INDEX_WRITER_MAX_WAIT_MS;
     fs.mkdirSync(path.dirname(lockPath), { recursive: true });
-    if (heldLocks.has(lockPath)) {
-        options.onAcquired?.({ waitedMs: 0 });
-        return retainHeldLock(lockPath);
-    }
     let lastWaitNoticeMs = 0;
     while (true) {
         throwIfAborted(options.signal);
-        if (tryAcquireLockSync(lockPath, buildPayload(options.purpose))) {
-            options.onAcquired?.({ waitedMs: Date.now() - startedAt });
-            return retainHeldLock(lockPath);
-        }
-        const probe = probeLock(lockPath, { staleAfterMs: INDEX_WRITER_LOCK_STALE_AFTER_MS });
-        if (probe.state === "held" && probe.holderPid === process.pid) {
-            options.onAcquired?.({ waitedMs: Date.now() - startedAt });
-            return retainHeldLock(lockPath);
-        }
-        if (probe.state === "stale") {
-            releaseLock(lockPath);
-            continue;
+        const releaseBarrier = tryAcquireMaintenanceBarrier();
+        if (releaseBarrier) {
+            try {
+                if (heldLocks.has(lockPath)) {
+                    options.onAcquired?.({ waitedMs: Date.now() - startedAt });
+                    return retainHeldLock(lockPath);
+                }
+                const ownership = tryAcquireLockSync(lockPath, buildPayload(options.purpose));
+                if (ownership) {
+                    options.onAcquired?.({ waitedMs: Date.now() - startedAt });
+                    return retainHeldLock(lockPath, ownership);
+                }
+                const probe = probeLock(lockPath, { staleAfterMs: INDEX_WRITER_LOCK_STALE_AFTER_MS });
+                if (probe.state === "stale") {
+                    if (reclaimStaleLock(lockPath, probe))
+                        continue;
+                }
+            }
+            finally {
+                releaseBarrier();
+            }
         }
         if (mode === "try")
             return undefined;

package/dist/indexer/index-written-assets.js

@@ -23,7 +23,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { getDbPath } from "../core/paths.js";
 import { warnVerbose } from "../core/warn.js";
-import { closeDatabase, getEntryCount, openExistingDatabase, rebuildFts, upsertEntry } from "./db/db.js";
+import { takeWorkflowDocument } from "../workflows/runtime/document-cache.js";
+import { closeDatabase, getEntryCount, openExistingDatabase, rebuildFts, upsertEntry, upsertWorkflowDocument, } from "./db/db.js";
 import { generateMetadataFlat } from "./passes/metadata.js";
 import { buildSearchText } from "./search/search-fields.js";
 /**
@@ -69,10 +70,10 @@ export async function indexWrittenAssets(stashDir, filePaths) {
         for (const file of files) {
             const generated = await generateMetadataFlat(stashDir, [file]);
             const entry = generated.entries[0];
-            // Workflows carry a side-table document upsert this fast path doesn't
-            // do; no current caller writes them, but guard so one never lands
-            // half-indexed.
-            if (entry && entry.type !== "workflow")
+            // Workflows also carry a workflow_documents side-table upsert — handled
+            // below, mirroring the full walk — since `akm mv` rewrites citer files
+            // that can be workflows.
+            if (entry)
                 pairs.push({ file, entry });
         }
         if (pairs.length === 0)
@@ -91,7 +92,15 @@ export async function indexWrittenAssets(stashDir, filePaths) {
                 catch {
                     // stat raced a delete — index without the size, like the full walk does.
                 }
-                upsertEntry(db, entryKey, path.dirname(file), file, stashDir, entryWithSize, buildSearchText(entry));
+                const entryId = upsertEntry(db, entryKey, path.dirname(file), file, stashDir, entryWithSize, buildSearchText(entry));
+                if (entry.type === "workflow") {
+                    // Same contract as the full walk (indexer.ts): the renderer cached
+                    // the parsed document during metadata generation; persist it so the
+                    // workflow runtime never sees an entry without its document.
+                    const doc = takeWorkflowDocument(entry);
+                    if (doc)
+                        upsertWorkflowDocument(db, entryId, doc, fs.readFileSync(file));
+                }
             }
             rebuildFts(db, { incremental: true });
         }

package/dist/indexer/indexer.js

@@ -182,6 +182,11 @@ async function runFinalizePhase(ctx) {
     setMeta(db, "stashDir", stashDir);
     setMeta(db, "stashDirs", JSON.stringify(sourceDirs));
     setMeta(db, "hasEmbeddings", embeddingResult.success ? "1" : "0");
+    // Stash-organization conventions (SPEC-8): track which `index.indexBodyOpening`
+    // state the index was built with, and warn while the flag diverges from it.
+    const bodyOpeningWarning = reconcileBodyOpeningIndexState(db, config.index?.indexBodyOpening === true, ctx.full || !isIncremental);
+    if (bodyOpeningWarning)
+        warn(bodyOpeningWarning);
     warnIfVecMissing(db);
     const totalEntries = getEntryCount(db);
     const semanticEntryCount = getEmbeddableEntryCount(db);
@@ -209,6 +214,41 @@ async function runFinalizePhase(ctx) {
     // suppress unused warning — sources was previously used inline
     void sources;
 }
+/**
+ * Stash-organization conventions (SPEC-8): reconcile the `index.indexBodyOpening`
+ * flag with the state the index was last FULLY built with (index_meta key
+ * `indexBodyOpening`), returning a warning message while they diverge.
+ *
+ * Incremental runs re-extract only changed files (and embeddings are only
+ * generated for rows lacking one), so a flag toggle leaves the index MIXED
+ * until a full rebuild — `akm index --full` re-extracts every entry and wipes
+ * embeddings so they regenerate from the new text. The warning therefore
+ * repeats on every incremental run until a full walk records the flag state
+ * as applied.
+ *
+ * A missing meta key on an incremental run means the index predates this
+ * feature, i.e. it was necessarily built with the flag OFF — so the absent
+ * key reads (and is seeded) as "0", never as the current flag value. This
+ * keeps the most likely real toggle scenario — upgrade, enable the flag, run
+ * a plain `akm index` — warning until `--full` runs (review finding).
+ *
+ * Exported for tests; production's only caller is the finalize phase above.
+ */
+export function reconcileBodyOpeningIndexState(db, flagEnabled, isFullWalk) {
+    const bodyOpeningFlag = flagEnabled ? "1" : "0";
+    const prevBodyOpeningFlag = getMeta(db, "indexBodyOpening") ?? "0";
+    // Only a full walk (which includes the first build ever) may record the
+    // current flag as the applied state; incremental runs preserve — or, for a
+    // pre-feature index, seed — the state of the last full build.
+    setMeta(db, "indexBodyOpening", isFullWalk ? bodyOpeningFlag : prevBodyOpeningFlag);
+    if (isFullWalk || prevBodyOpeningFlag === bodyOpeningFlag)
+        return undefined;
+    return (`index.indexBodyOpening is ${flagEnabled ? "enabled" : "disabled"} but the index was built with it ` +
+        `${flagEnabled ? "disabled" : "enabled"}. Incremental runs only re-extract changed files, so ` +
+        "indexed text and embeddings are stale for unchanged entries. Run `akm index --full` to apply the new " +
+        "setting everywhere (embeddings regenerate), and re-mint collapse-detector canary baselines via " +
+        "`akm improve canary --refresh` if you use them.");
+}
 // ── Clean pass ───────────────────────────────────────────────────────────────
 /**
  * Post-index clean pass: scan the `entries` table for rows whose source file
@@ -733,10 +773,11 @@ async function enhanceDirsWithLlm(db, config, dirsNeedingLlm, onProgress, signal
     // P3 — wall-clock budget for the enrichment pass. Defaults to llm.timeoutMs
     // (or 10 minutes if not set). Users can extend this via llm.timeoutMs in
     // config — no separate knob needed.
-    const budgetMs = (llmConfig.timeoutMs ?? 10 * 60 * 1000) * Math.max(totalEntries, 1);
-    const enrichDeadline = AbortSignal.timeout(budgetMs);
+    const enrichDeadline = createEnrichmentDeadline(llmConfig.timeoutMs, totalEntries);
     let deadlineHit = false;
     const enrichSignal = (() => {
+        if (!enrichDeadline)
+            return signal ?? new AbortController().signal;
         if (!signal)
             return enrichDeadline;
         // Combine: abort when either fires.
@@ -865,6 +906,10 @@ async function enhanceDirsWithLlm(db, config, dirsNeedingLlm, onProgress, signal
         warn(`LLM enhancement failed for ${failed}/${summary.attempted} entries — they were left un-enhanced.${sample}`);
     }
 }
+export function createEnrichmentDeadline(timeoutMs, totalEntries) {
+    const perEntryTimeoutMs = timeoutMs === undefined ? 10 * 60 * 1000 : timeoutMs;
+    return perEntryTimeoutMs === null ? undefined : AbortSignal.timeout(perEntryTimeoutMs * Math.max(totalEntries, 1));
+}
 async function generateEmbeddingsForDb(db, config, onProgress, signal) {
     throwIfAborted(signal);
     if (config.semanticSearchMode === "off") {

package/dist/indexer/passes/memory-inference.js

@@ -19,7 +19,7 @@
  * the parent without re-running the LLM.
  *
  * Disabling — two orthogonal gates:
- *   1. `profiles.improve.default.processes.memoryInference.enabled = false`
+ *   1. The selected strategy sets `processes.memoryInference.enabled = false`
  *      blocks the pass at the feature-flag layer (no network call may ever
  *      issue). Historically the v1 spec §14 gate, superseded by the 0.8.0
  *      profile shape.
@@ -60,7 +60,7 @@ const FM_CAPTURE_MODE = "captureMode";
  *
  * Two orthogonal gates:
  *
- *   1. **Feature gate** — `profiles.improve.default.processes.memoryInference.enabled`
+ *   1. **Feature gate** — the selected strategy's `processes.memoryInference.enabled`
  *      (defaults to `true`). When `false`, no network call may issue regardless
  *      of per-pass settings.
  *   2. **Per-pass gate** — `resolveIndexPassLLM("memory", config)` (which
@@ -72,6 +72,7 @@ const FM_CAPTURE_MODE = "captureMode";
  */
 export async function runMemoryInferencePass(ctx) {
     const { config, sources, signal, db, reEnrich, onProgress, options = {} } = ctx;
+    const invocationOwnsConnection = Object.hasOwn(ctx, "llmConfig");
     const compressMemoryToDerivedMemory = options.compressMemoryToDerivedMemory ?? memoryInfer.compressMemoryToDerivedMemory;
     const result = {
         considered: 0,
@@ -90,15 +91,18 @@ export async function runMemoryInferencePass(ctx) {
     // gate) bubbles up into the pass result.
     const inferTelemetry = {};
     // Gate 1 — feature gate via isProcessEnabled, which reads the 0.8.0 path
-    // (profiles.improve.default.processes.memoryInference.enabled). Defaults to
+    // (selected strategy's processes.memoryInference.enabled). Defaults to
     // enabled when the key is absent.
-    if (!isProcessEnabled("index", "memory_inference", config))
+    if (!invocationOwnsConnection && !isProcessEnabled("index", "memory_inference", config))
         return result;
     // Gate 2 — per-pass opt-out (#208). Returns the resolved llm config or
     // `undefined` when the pass should not run.
-    const llmConfig = resolveIndexPassLLM("memory", config);
+    const llmConfig = Object.hasOwn(ctx, "llmConfig") ? ctx.llmConfig : resolveIndexPassLLM("memory", config);
     if (!llmConfig)
         return result;
+    const featureConfig = invocationOwnsConnection
+        ? { ...config, index: { ...config.index, memory: { ...config.index?.memory, enabled: true } } }
+        : config;
     // The pass only writes to the primary (working) stash. Read-only caches
     // (git, npm, website) are deliberately untouched — writing inferred
     // children there would be clobbered by the next sync().
@@ -173,7 +177,7 @@ export async function runMemoryInferencePass(ctx) {
             retryAttempts += 1;
         };
         const derived = db
-            ? await withLlmCache(db, record.filePath, record.body, reEnrich ?? false, () => compressMemoryToDerivedMemory(llmConfig, record.body, signal, config, (evt) => {
+            ? await withLlmCache(db, record.filePath, record.body, reEnrich ?? false, () => compressMemoryToDerivedMemory(llmConfig, record.body, signal, featureConfig, (evt) => {
                 warn(`[akm] LLM fallback for ${evt.feature}: ${evt.reason}`);
             }, inferTelemetry, onRetryAttempt), validate, undefined, "", {
                 onCacheHit: () => {