akm-cli 0.9.1 → 0.9.2-alpha.1

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

@@ -29,7 +29,8 @@
  *   NEVER deleted — the user keeps what was already produced.
  *
  * Locked v1 contract:
- *   - LLM access is exclusively via `resolveIndexPassLLM("memory", config)`.
+ *   - LLM access is exclusively via the frozen runner returned by
+ *     `resolveIndexPassExecution("memory", config)`.
  *   - All child memory writes go through `writeAssetToSource` in
  *     `src/core/write-source.ts`. The parent's frontmatter rewrite is an
  *     explicit narrow exception — see {@link markParentProcessed}.
@@ -40,14 +41,19 @@ import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
 import { assembleAsset } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter, parseFrontmatterBlock } from "../../core/asset/frontmatter.js";
 import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-ref.js";
+import { bestEffort } from "../../core/best-effort.js";
 import { todayIso } from "../../core/common.js";
 import { concurrentMap } from "../../core/concurrent.js";
+import { ConfigError } from "../../core/errors.js";
 import { warn } from "../../core/warn.js";
 import { recordWrittenPath } from "../../core/write-provenance.js";
 import { writeAssetToSource } from "../../core/write-source.js";
+import { disposeLoweredExecutionDispatchLease, } from "../../integrations/agent/execution-lowering.js";
 import { isProcessEnabled } from "../../llm/feature-gate.js";
-import { resolveIndexPassLLM } from "../../llm/index-passes.js";
+import { resolveIndexPassExecution } from "../../llm/index-passes.js";
 import * as memoryInfer from "../../llm/memory-infer.js";
+import { preflightStructuredLlmRunner } from "../../llm/structured-call.js";
+import { computeBodyHash, getLlmCacheEntry } from "../../storage/repositories/index-llm-cache-repository.js";
 import { withLlmCache } from "../db/llm-cache.js";
 import { walkMarkdownFiles } from "../walk/walker.js";
 /**
@@ -58,6 +64,114 @@ const FM_INFERRED = "inferred";
 const FM_INFERENCE_PROCESSED = "inferenceProcessed";
 const FM_SOURCE = "source";
 const FM_CAPTURE_MODE = "captureMode";
+function validateDerivedMemoryDraft(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const parsed = raw;
+    const title = typeof parsed.title === "string" ? parsed.title : "";
+    const description = typeof parsed.description === "string" ? parsed.description : "";
+    const content = typeof parsed.content === "string" ? parsed.content : "";
+    const tags = Array.isArray(parsed.tags) ? parsed.tags.filter((tag) => typeof tag === "string") : [];
+    const searchHints = Array.isArray(parsed.searchHints)
+        ? parsed.searchHints.filter((hint) => typeof hint === "string")
+        : [];
+    return title && description && content && tags.length > 0 && searchHints.length > 0
+        ? { title, description, tags, searchHints, content }
+        : undefined;
+}
+function planPendingMemoryRecord(record, ctx) {
+    if (ctx.signal?.aborted)
+        return { kind: "aborted", record };
+    if (fs.existsSync(derivedChildPath(record)))
+        return { kind: "existing-child", record };
+    if (ctx.db && !ctx.reEnrich) {
+        const cached = bestEffort(() => {
+            const entry = getLlmCacheEntry(ctx.db, record.filePath, computeBodyHash(record.body), "memory-inference-v2");
+            return entry ? validateDerivedMemoryDraft(JSON.parse(entry.resultJson)) : undefined;
+        }, "memory inference cache read corrupt — fall through to recompute");
+        if (cached)
+            return { kind: "cache-hit", record, derived: cached };
+    }
+    return { kind: "model", record };
+}
+function memoryExecutionForContext(ctx, config) {
+    if (Object.hasOwn(ctx, "llmRunner")) {
+        return Object.freeze({ runner: ctx.llmRunner ?? undefined, notices: Object.freeze([]) });
+    }
+    return resolveIndexPassExecution("memory", config);
+}
+async function inferPendingMemoryRecord(plan, ctx) {
+    const { record } = plan;
+    const { config, featureConfig, signal, db, reEnrich, llmRunner, lease, inferTelemetry, compressMemoryToDerivedMemory, onNotices, onConfigFailure, } = ctx;
+    if (signal?.aborted || plan.kind === "aborted")
+        return { aborted: true };
+    // Existing children are complete, but the parent may be unmarked after a
+    // crash between the child write and parent update (or an external write).
+    if (fs.existsSync(derivedChildPath(record))) {
+        markParentProcessed(record);
+        return {
+            skipped: false,
+            splitParent: false,
+            written: 0,
+            fromCache: false,
+            retryAttempts: 0,
+            childExists: true,
+            precheck: true,
+        };
+    }
+    // The child can disappear after the read-only classification pass (for
+    // example, an external cleanup racing this index run). The plan is not proof
+    // that the child still exists at the mutation boundary: leave the parent
+    // pending so a later run can classify and preflight the now-real model work.
+    if (plan.kind === "existing-child") {
+        return { skipped: true, fromCache: false, retryAttempts: 0 };
+    }
+    let fromCache = plan.kind === "cache-hit";
+    let retryAttempts = 0;
+    const onRetryAttempt = () => {
+        retryAttempts += 1;
+    };
+    const infer = () => compressMemoryToDerivedMemory(llmRunner, record.body, signal, featureConfig, (event) => warn(`[akm] LLM fallback for ${event.feature}: ${event.reason}`), inferTelemetry, onRetryAttempt, onNotices, lease);
+    let derived = plan.kind === "cache-hit" ? plan.derived : undefined;
+    try {
+        if (plan.kind === "model") {
+            derived = db
+                ? await withLlmCache(db, record.filePath, record.body, reEnrich ?? false, infer, validateDerivedMemoryDraft, undefined, "memory-inference-v2", {
+                    onCacheHit: () => {
+                        fromCache = true;
+                    },
+                })
+                : await compressMemoryToDerivedMemory(llmRunner, record.body, signal, config, (event) => warn(`[akm] LLM fallback for ${event.feature}: ${event.reason}`), inferTelemetry, onRetryAttempt, onNotices, lease);
+        }
+    }
+    catch (error) {
+        if (error instanceof ConfigError) {
+            onConfigFailure(error);
+            return undefined;
+        }
+        throw error;
+    }
+    if (!derived)
+        return { skipped: true, fromCache, retryAttempts };
+    const writeOutcome = await writeDerivedMemory(record, derived);
+    if (writeOutcome.written > 0) {
+        markParentProcessed(record);
+        return { skipped: false, splitParent: true, written: writeOutcome.written, fromCache, retryAttempts };
+    }
+    // A child that appeared mid-flight is complete and can safely mark its
+    // parent. A genuine write failure remains unmarked for a later retry.
+    if (writeOutcome.childExists)
+        markParentProcessed(record);
+    return {
+        skipped: false,
+        splitParent: false,
+        written: 0,
+        fromCache,
+        retryAttempts,
+        childExists: true,
+        precheck: false,
+    };
+}
 /**
  * Top-level entry point. Returns a no-op result when the pass is disabled.
  *
@@ -66,8 +180,8 @@ const FM_CAPTURE_MODE = "captureMode";
  *   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
- *      reads `index.memory.llm`). When `false`, the indexer simply skips
+ *   2. **Per-pass gate** — `resolveIndexPassExecution("memory", config)` reads
+ *      the index pass selection. Without a runner, the indexer simply skips
  *      this pass for the current run.
  *
  * Both must allow the call for the pass to run. Either set to `false`
@@ -75,7 +189,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 invocationOwnsRunner = Object.hasOwn(ctx, "llmRunner");
     const compressMemoryToDerivedMemory = options.compressMemoryToDerivedMemory ?? memoryInfer.compressMemoryToDerivedMemory;
     const result = {
         considered: 0,
@@ -93,17 +207,29 @@ export async function runMemoryInferencePass(ctx) {
     // HTML-error categorization (which is otherwise swallowed inside the feature
     // gate) bubbles up into the pass result.
     const inferTelemetry = {};
+    const noticesByKey = new Map();
+    const onNotices = (notices) => {
+        for (const notice of notices)
+            noticesByKey.set(JSON.stringify(notice), notice);
+    };
+    const completeResult = () => {
+        if (noticesByKey.size > 0)
+            result.notices = Object.freeze([...noticesByKey.values()]);
+        return result;
+    };
     // Gate 1 — feature gate via isProcessEnabled, which reads the 0.8.0 path
     // (selected strategy's processes.memoryInference.enabled). Defaults to
     // enabled when the key is absent.
-    if (!invocationOwnsConnection && !isProcessEnabled("index", "memory_inference", config))
-        return result;
+    if (!invocationOwnsRunner && !isProcessEnabled("index", "memory_inference", config))
+        return completeResult();
     // Gate 2 — per-pass opt-out (#208). Returns the resolved llm config or
     // `undefined` when the pass should not run.
-    const llmConfig = Object.hasOwn(ctx, "llmConfig") ? ctx.llmConfig : resolveIndexPassLLM("memory", config);
-    if (!llmConfig)
-        return result;
-    const featureConfig = invocationOwnsConnection
+    const execution = memoryExecutionForContext(ctx, config);
+    onNotices(execution.notices);
+    const llmRunner = execution.runner;
+    if (!llmRunner)
+        return completeResult();
+    const featureConfig = invocationOwnsRunner
         ? { ...config, index: { ...config.index, memory: { ...config.index?.memory, enabled: true } } }
         : config;
     // The pass only writes to the primary (working) stash. Read-only caches
@@ -111,128 +237,94 @@ export async function runMemoryInferencePass(ctx) {
     // children there would be clobbered by the next sync().
     const primary = sources[0];
     if (!primary || (primary.adapterId ?? detectAdapterId(primary.path)) !== "akm")
-        return result;
+        return completeResult();
     const pending = collectPendingMemories(primary.path).filter((record) => !options.candidateRefs || options.candidateRefs.has(record.ref));
     result.considered = pending.length;
     if (pending.length === 0)
-        return result;
-    let processed = 0;
-    const total = pending.length;
-    onProgress?.({ processed, total, writtenFacts: 0, skippedNoFacts: 0 });
-    const perRecordResults = await concurrentMap(pending, async (record) => {
-        // Aborted BEFORE a fresh LLM call. Returned as a typed outcome so the
-        // for-loop below increments `skippedAborted` instead of silently
-        // dropping the record (which historically inflated freshAttempts and
-        // dragged the health-reported yield rate down — see investigation
-        // 2026-05-26).
-        if (signal?.aborted)
-            return { aborted: true };
-        // Pre-check (#588): when `<parent>.derived.md` is already on disk the
-        // inference is by definition complete — the parent only looks pending
-        // because `markParentProcessed` never ran (process killed between the
-        // child write and the mark) or the child was created externally (e.g.
-        // consolidation). Skip the LLM/cache call entirely and mark the parent
-        // so it never re-pends. Before this check, production measurements
-        // showed ~55% of the pass's LLM budget re-deriving such parents only to
-        // discover the existing child after the fact.
-        if (fs.existsSync(derivedChildPath(record))) {
-            markParentProcessed(record);
-            return {
-                skipped: false,
-                splitParent: false,
-                written: 0,
-                fromCache: false,
-                retryAttempts: 0,
-                childExists: true,
-                precheck: true,
-            };
-        }
-        // Incremental cache: skip LLM call when body hash is unchanged and
-        // --re-enrich was not requested. The cache ref is the absolute file path.
-        const validate = (raw) => {
-            if (!raw || typeof raw !== "object")
-                return undefined;
-            const parsed = raw;
-            const title = typeof parsed.title === "string" ? parsed.title : "";
-            const description = typeof parsed.description === "string" ? parsed.description : "";
-            const content = typeof parsed.content === "string" ? parsed.content : "";
-            const tags = Array.isArray(parsed.tags) ? parsed.tags.filter((t) => typeof t === "string") : [];
-            const searchHints = Array.isArray(parsed.searchHints)
-                ? parsed.searchHints.filter((h) => typeof h === "string")
-                : [];
-            if (title && description && content && tags.length > 0 && searchHints.length > 0) {
-                return { title, description, tags, searchHints, content };
+        return completeResult();
+    // Classify the whole batch without mutation. Required credentials are
+    // materialized only when at least one record will actually dispatch; this
+    // keeps aborted, existing-child, and validated-cache-only batches available
+    // offline while preserving all-or-nothing preflight for mixed batches.
+    const plans = pending.map((record) => planPendingMemoryRecord(record, { signal, db, reEnrich }));
+    const dispatchLease = plans.some((plan) => plan.kind === "model")
+        ? await preflightStructuredLlmRunner(llmRunner)
+        : undefined;
+    try {
+        let processed = 0;
+        const total = pending.length;
+        onProgress?.({ processed, total, writtenFacts: 0, skippedNoFacts: 0 });
+        let configFailure;
+        const perRecordResults = await concurrentMap(plans, (plan) => inferPendingMemoryRecord(plan, {
+            config,
+            featureConfig,
+            signal,
+            db,
+            reEnrich,
+            llmRunner,
+            lease: dispatchLease,
+            inferTelemetry,
+            compressMemoryToDerivedMemory,
+            onNotices,
+            onConfigFailure: (error) => {
+                configFailure ??= error;
+            },
+        }), 
+        // Caller-set connection concurrency or 1: `resolveLlmEngineUse` does
+        // not forward `engines.<name>.concurrency`, so config cannot raise this.
+        llmRunner.connection.concurrency ?? 1);
+        if (configFailure)
+            throw configFailure;
+        for (let i = 0; i < perRecordResults.length; i++) {
+            const res = perRecordResults[i];
+            if (!res)
+                continue;
+            if ("aborted" in res && res.aborted) {
+                result.skippedAborted += 1;
+                processed++;
+                onProgress?.({
+                    processed,
+                    total,
+                    writtenFacts: result.writtenFacts,
+                    skippedNoFacts: result.skippedNoFacts,
+                    currentRef: pending[i]?.ref,
+                });
+                continue;
+            }
+            if (res.fromCache) {
+                result.cacheHits += 1;
+            }
+            if ("retryAttempts" in res) {
+                result.retryAttempts += res.retryAttempts;
+            }
+            if (res.skipped) {
+                result.skippedNoFacts += 1;
+                // Intentionally NOT marked processed — a transient LLM failure should
+                // be retried on the next index run.
+            }
+            else if (res.splitParent) {
+                result.splitParents += 1;
+                result.writtenFacts += res.written;
+            }
+            else if ("childExists" in res && res.childExists) {
+                // Derived child already on disk. Track separately so this category is
+                // observable in health output and stops bleeding into the
+                // freshAttempts denominator. Pre-check skips (#588) are the routine
+                // self-healing path — no LLM attempt was consumed and the parent has
+                // been marked processed — so only the rare post-LLM case (mid-flight
+                // race or write failure) warrants a per-ref warning.
+                result.skippedChildExists += 1;
+                if (!res.precheck) {
+                    warn(`memory inference: derived child for ${pending[i]?.ref ?? "<unknown>"} already existed or write failed; counted as skippedChildExists`);
+                }
+            }
+            else {
+                // The per-record state machine should cover every outcome. A hit here
+                // means a new code path slipped past the categorisation — surface it
+                // loudly so health metrics stay honest and we get a signal to fix.
+                result.unaccounted += 1;
+                warn(`memory inference: unaccounted per-record outcome for ${pending[i]?.ref ?? "<unknown>"}`);
             }
-            return undefined;
-        };
-        // Track whether THIS candidate's result came from the body-hash
-        // cache vs. a fresh LLM call. The cache short-circuits when the
-        // parent body has not changed since a prior derived write — surfacing
-        // the hit count separately so the operational yield rate
-        // (writtenFacts / freshAttempts) is interpretable as the cache warms.
-        let fromCache = false;
-        // Count single bounded retries for transient LLM failures on this
-        // candidate. Bumped via the `onRetryAttempt` callback threaded into
-        // `chatCompletion`; surfaced as `retryAttempts` telemetry, never as a
-        // failure for the same call.
-        let retryAttempts = 0;
-        const onRetryAttempt = () => {
-            retryAttempts += 1;
-        };
-        const derived = db
-            ? 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, "memory-inference-v2", {
-                onCacheHit: () => {
-                    fromCache = true;
-                },
-            })
-            : await compressMemoryToDerivedMemory(llmConfig, record.body, signal, config, (evt) => {
-                warn(`[akm] LLM fallback for ${evt.feature}: ${evt.reason}`);
-            }, inferTelemetry, onRetryAttempt);
-        if (!derived) {
-            return { skipped: true, fromCache, retryAttempts };
-        }
-        const writeOutcome = await writeDerivedMemory(record, derived);
-        if (writeOutcome.written > 0) {
-            markParentProcessed(record);
-            return { skipped: false, splitParent: true, written: writeOutcome.written, fromCache, retryAttempts };
-        }
-        // LLM produced a valid derived draft but no file was written — either
-        // because `<parent>.derived.md` appeared on disk after the pre-check
-        // above (a rare mid-flight race) or `writeAssetToSource` threw.
-        // Categorise as `childExists` so the consumed attempt is accounted for
-        // in health metrics rather than vanishing into the freshAttempts
-        // denominator.
-        //
-        // When the child exists the inference is, by definition, complete — so
-        // mark the parent processed here too (#550), otherwise
-        // `isPendingMemory()` re-queues the same parent every run. A genuine
-        // write *failure* (`writeAssetToSource` threw) must NOT mark the parent
-        // — it should be retried next run — so we key off the explicit
-        // `childExists` outcome rather than the conflated `written === 0`.
-        if (writeOutcome.childExists) {
-            markParentProcessed(record);
-        }
-        return {
-            skipped: false,
-            splitParent: false,
-            written: 0,
-            fromCache,
-            retryAttempts,
-            childExists: true,
-            precheck: false,
-        };
-    }, 
-    // Caller-set connection concurrency or 1: `resolveLlmEngineUse` does
-    // not forward `engines.<name>.concurrency`, so config cannot raise this.
-    llmConfig.concurrency ?? 1);
-    for (let i = 0; i < perRecordResults.length; i++) {
-        const res = perRecordResults[i];
-        if (!res)
-            continue;
-        if ("aborted" in res && res.aborted) {
-            result.skippedAborted += 1;
             processed++;
             onProgress?.({
                 processed,
@@ -241,53 +333,14 @@ export async function runMemoryInferencePass(ctx) {
                 skippedNoFacts: result.skippedNoFacts,
                 currentRef: pending[i]?.ref,
             });
-            continue;
-        }
-        if (res.fromCache) {
-            result.cacheHits += 1;
-        }
-        if ("retryAttempts" in res) {
-            result.retryAttempts += res.retryAttempts;
         }
-        if (res.skipped) {
-            result.skippedNoFacts += 1;
-            // Intentionally NOT marked processed — a transient LLM failure should
-            // be retried on the next index run.
-        }
-        else if (res.splitParent) {
-            result.splitParents += 1;
-            result.writtenFacts += res.written;
-        }
-        else if ("childExists" in res && res.childExists) {
-            // Derived child already on disk. Track separately so this category is
-            // observable in health output and stops bleeding into the
-            // freshAttempts denominator. Pre-check skips (#588) are the routine
-            // self-healing path — no LLM attempt was consumed and the parent has
-            // been marked processed — so only the rare post-LLM case (mid-flight
-            // race or write failure) warrants a per-ref warning.
-            result.skippedChildExists += 1;
-            if (!res.precheck) {
-                warn(`memory inference: derived child for ${pending[i]?.ref ?? "<unknown>"} already existed or write failed; counted as skippedChildExists`);
-            }
-        }
-        else {
-            // The per-record state machine should cover every outcome. A hit here
-            // means a new code path slipped past the categorisation — surface it
-            // loudly so health metrics stay honest and we get a signal to fix.
-            result.unaccounted += 1;
-            warn(`memory inference: unaccounted per-record outcome for ${pending[i]?.ref ?? "<unknown>"}`);
-        }
-        processed++;
-        onProgress?.({
-            processed,
-            total,
-            writtenFacts: result.writtenFacts,
-            skippedNoFacts: result.skippedNoFacts,
-            currentRef: pending[i]?.ref,
-        });
+        result.htmlErrorCount = inferTelemetry.htmlErrorCount ?? 0;
+        return completeResult();
+    }
+    finally {
+        if (dispatchLease)
+            disposeLoweredExecutionDispatchLease(dispatchLease);
     }
-    result.htmlErrorCount = inferTelemetry.htmlErrorCount ?? 0;
-    return result;
 }
 // ── Pending detection ───────────────────────────────────────────────────────
 /**

package/dist/indexer/scan/doc-to-entry.js

@@ -6,13 +6,11 @@
  * `indexDocumentFromEntry` (`adapters/akm-adapter.ts`). akm 0.9.0 Chunk 5,
  * milestone F4a (M2 groundwork).
  *
- * The engine swap drains an `IndexDocument` stream (`drainDirDocuments` × the
- * dispatched adapter's `recognize`) in place of the per-dir flat-walk matcher-pass
- * `IndexDocument` stream, then persists it. But the durable `entries.entry_json`
- * column stays a faithful `IndexDocument` — every reader (`rowToIndexedEntry` →
- * `DbIndexedEntry.entry`) consumes it as one, and the byte-for-byte goldens pin
- * it. So the persist path must reconstruct the exact `IndexDocument` the old
- * pipeline stored FROM the `IndexDocument` the new pipeline produces.
+ * The indexer drains a single `IndexDocument` stream (`drainDirDocuments` × the
+ * dispatched adapter's `recognize`) and persists its canonical projection in
+ * `entries.document_json`. Every reader (`rowToIndexedEntry` →
+ * `DbIndexedEntry.entry`) consumes that same projection, and parity tests pin
+ * the boundary.
  *
  * That reconstruction is lossless by construction: the akm adapter's `recognize`
  * assembles a full `IndexDocument` (P1/P2 → fold → P4) and then maps it onto the
@@ -20,8 +18,8 @@
  * onto named members, every other search-surface/provenance field onto
  * `documentJson` (the `DOCUMENT_JSON_CARRIED_FIELDS` set). This function reverses
  * that mapping exactly, so `indexDocumentToStashEntry(recognize(file))` deep-
- * equals the entry the legacy flat-walk pass stored for the same file (the
- * `tests/integration/shadow-scan-parity.test.ts` gate pins the persisted index).
+ * equals the current persisted document for the same file (the
+ * `tests/integration/shadow-scan-parity.test.ts` gate pins this boundary).
  *
  * Two deliberate non-round-trip fields:
  *   - `filename` — dropped by `indexDocumentFromEntry` (no IndexDocument home),

package/dist/indexer/scan/drain-dir.js

@@ -14,26 +14,23 @@
  *  - **Broken-workflow drop (item 3).** The live path dropped a broken workflow
  *    via the renderer contributor's throw → metadata-pass skip-with-warning; the
  *    `akm` adapter's synchronous `foldRecognizedMetadata` SWALLOWS the parse
- *    error, so a broken workflow would otherwise silently index. We re-run
- *    `parseWorkflow` on drained workflow docs and DROP
+ *    error, so a broken workflow would otherwise silently index. We run the
+ *    shared source-IR compiler on drained workflow docs and DROP
  *    the entry with the same `Skipped workflow …` warning
  *    ({@link buildMetadataSkipWarning}), so the workflow-skip summary counts it.
- *  - **Workflow-document side-table (workflow-md only).** The valid parsed
- *    `WorkflowDocument` is handed to the persist layer through the same
- *    `document-cache` side channel the live renderer contributor used, keyed by
- *    the reconstructed entry — so `takeWorkflowDocument(entry)` in the persist
- *    loop writes the `workflow_documents` row exactly as before.
  *
  * `doc.hash` (= sha256 of the file content) is surfaced per recognized file so
  * the persist layer can populate the `content_hash` column (item 2). It is keyed
  * by the file's absolute path rather than by the entry object.
  *
- * Pure of DB/global state beyond the workflow-document side channel; a new leaf
- * (nothing imports it back), so it joins no import cycle.
+ * Pure of DB/global state; a new leaf (nothing imports it back), so it joins no
+ * import cycle.
  */
+import path from "node:path";
 import { akmAdapter } from "../../core/adapter/adapters/akm-adapter.js";
-import { parseWorkflow } from "../../workflows/parser.js";
-import { cacheWorkflowDocument } from "../../workflows/runtime/document-cache.js";
+import { canonicalizeWorkflowName } from "../../core/recognition-util.js";
+import { resolveUniqueWorkflowSource, WorkflowSourceRejectionError, workflowNameForSourcePath, } from "../../workflows/source-files.js";
+import { compileWorkflowSource } from "../../workflows/source-ir/compile.js";
 import { buildMetadataSkipWarning } from "../passes/metadata.js";
 import { buildFileContext } from "../walk/file-context.js";
 import { indexDocumentToStashEntry } from "./doc-to-entry.js";
@@ -53,7 +50,34 @@ export function drainDirDocuments(adapter, component, fileContexts) {
     const warnings = [];
     const hashByFile = new Map();
     const conceptIdByFile = new Map();
+    const rejectedPaths = new Set();
+    const rejectedConceptIds = new Set();
+    const workflowLookups = new Map();
     for (const file of fileContexts) {
+        const workflowName = workflowNameForSourcePath(component.root, adapter.id, file.absPath);
+        if (workflowName !== undefined) {
+            const canonicalName = canonicalizeWorkflowName(workflowName);
+            if (!workflowLookups.has(canonicalName))
+                workflowLookups.set(canonicalName, workflowName);
+        }
+    }
+    for (const [canonicalName, workflowName] of [...workflowLookups].sort(([left], [right]) => comparePaths(left, right))) {
+        try {
+            resolveUniqueWorkflowSource(component.root, adapter.id, workflowName);
+        }
+        catch (error) {
+            if (!(error instanceof WorkflowSourceRejectionError))
+                throw error;
+            rejectedConceptIds.add(adapter.id === "akm" ? `workflows/${canonicalName}` : canonicalName);
+            for (const relativePath of error.sourcePaths) {
+                rejectedPaths.add(path.join(component.root, relativePath));
+            }
+            warnings.push(error.message);
+        }
+    }
+    for (const file of fileContexts) {
+        if (rejectedPaths.has(file.absPath))
+            continue;
         const doc = adapter.recognize(component, file);
         if (doc === null)
             continue;
@@ -62,9 +86,9 @@ export function drainDirDocuments(adapter, component, fileContexts) {
             continue;
         }
         const entry = indexDocumentToStashEntry(doc);
-        // Workflow docs: drop-with-warning if broken; otherwise cache the parsed
-        // markdown document for the persist-time `workflow_documents` write.
-        const dropWarning = handleWorkflowDoc(doc, entry, file);
+        // Workflow docs: drop-with-warning if broken; otherwise cache a lossless
+        // runtime projection when the current executor can represent the source.
+        const dropWarning = handleWorkflowDoc(doc, file, component.root);
         if (dropWarning !== null) {
             warnings.push(dropWarning);
             continue;
@@ -74,7 +98,10 @@ export function drainDirDocuments(adapter, component, fileContexts) {
         conceptIdByFile.set(file.absPath, doc.conceptId);
         entries.push(entry);
     }
-    return { entries, warnings, hashByFile, conceptIdByFile };
+    return { entries, warnings, hashByFile, conceptIdByFile, rejectedPaths, rejectedConceptIds };
+}
+function comparePaths(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
 }
 /**
  * `(stashRoot, files) → StashFile` drop-in for the deleted flat-walk matcher
@@ -98,18 +125,19 @@ export function recognizeStashEntries(stashRoot, files) {
         : { entries: drained.entries };
 }
 /**
- * If `doc` is a workflow, re-parse it: return a `Skipped workflow …` drop
- * warning when it is broken, or cache the parsed markdown `WorkflowDocument`
- * (workflow-md only) and return `null` when valid. Non-workflow docs return
- * `null` immediately.
+ * If `doc` is a workflow, compile it through source IR: return a
+ * `Skipped workflow …` drop warning when it is broken, or return `null` when
+ * it compiles. Non-workflow docs return `null` immediately.
  */
-function handleWorkflowDoc(doc, entry, file) {
-    if (docRenderer(doc) !== WORKFLOW_MD_RENDERER)
+function handleWorkflowDoc(doc, file, workspaceRoot) {
+    if (doc.type !== "workflow" ||
+        (doc.adapterId !== "akm" && doc.adapterId !== "akm-workflow") ||
+        (docRenderer(doc) !== WORKFLOW_MD_RENDERER && doc.adapterId !== "akm-workflow")) {
         return null;
-    const result = parseWorkflow(file.content(), { path: file.relPath });
+    }
+    const result = compileWorkflowSource(file.content(), { path: file.relPath, workspaceRoot });
     if (!result.ok)
         return workflowDropWarning(file, result.errors);
-    cacheWorkflowDocument(entry, result.document);
     return null;
 }
 /** The winning renderer name the `akm` adapter carries on `documentJson.renderer`, or `undefined`. */