akm-cli 0.9.0-beta.45 → 0.9.0-beta.47

package/dist/indexer/passes/dir-staleness.js

@@ -0,0 +1,114 @@
+// 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/.
+/**
+ * Incremental dir-staleness engine.
+ *
+ * Decides, per stash directory, whether the directory's indexed rows are still
+ * fresh relative to what is on disk — so an incremental `akm index` run can
+ * skip unchanged directories instead of regenerating their metadata.
+ *
+ * Two persisted signals back the decision:
+ *   1. The `entries` rows already indexed for the directory (`getEntriesByDir`).
+ *   2. The `index_dir_state` fingerprint row (`getIndexDirState`), which caches
+ *      the file-set hash + max mtime for directories that legitimately produced
+ *      zero rows, so they are not rescanned every run.
+ *
+ * `computeDirFingerprint` derives the fingerprint (basename set + max mtime)
+ * that both the freshness check and the persisted `index_dir_state` row use.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getEntriesByDir, getIndexDirState } from "../db/db.js";
+export function getDirIndexState(db, dirPath, files, builtAtMs) {
+    const prevEntries = getEntriesByDir(db, dirPath);
+    const fingerprint = computeDirFingerprint(dirPath, files);
+    if (prevEntries.length > 0) {
+        const staleReason = getDirStaleReason(dirPath, files, prevEntries, builtAtMs);
+        if (!staleReason) {
+            return { stale: false, reason: { kind: "unchanged" }, persistedRowCount: prevEntries.length };
+        }
+        return { stale: true, reason: staleReason, persistedRowCount: prevEntries.length };
+    }
+    const cachedState = getIndexDirState(db, dirPath);
+    if (cachedState &&
+        cachedState.fileSetHash === fingerprint.fileSetHash &&
+        cachedState.fileMtimeMaxMs === fingerprint.fileMtimeMaxMs) {
+        return {
+            stale: false,
+            reason: { kind: "cached-zero-row-state", detail: cachedState.reason },
+            persistedRowCount: 0,
+        };
+    }
+    return {
+        stale: true,
+        reason: { kind: "no-previous-rows", detail: cachedState ? `cached=${cachedState.reason}` : undefined },
+        persistedRowCount: 0,
+    };
+}
+export function getCachedZeroRowDirState(db, dirPath, files, builtAtMs, priorDirsChanged) {
+    const state = getDirIndexState(db, dirPath, files, builtAtMs);
+    if (state.stale || state.reason.kind !== "cached-zero-row-state")
+        return undefined;
+    if (!canUseIncrementalSkip(state, priorDirsChanged))
+        return undefined;
+    return state;
+}
+export function canUseIncrementalSkip(state, priorDirsChanged) {
+    return !(priorDirsChanged &&
+        state.reason.kind === "cached-zero-row-state" &&
+        state.reason.detail === "deduped-zero-row");
+}
+export function computeDirFingerprint(_dirPath, files) {
+    const normalizedFiles = [...new Set(files.map((file) => path.basename(file)))].sort();
+    let fileMtimeMaxMs = 0;
+    for (const file of files) {
+        try {
+            fileMtimeMaxMs = Math.max(fileMtimeMaxMs, fs.statSync(file).mtimeMs);
+        }
+        catch {
+            fileMtimeMaxMs = Number.POSITIVE_INFINITY;
+            break;
+        }
+    }
+    return {
+        fileSetHash: normalizedFiles.join("\0"),
+        fileMtimeMaxMs,
+    };
+}
+function getDirStaleReason(_dirPath, currentFiles, previousEntries, builtAtMs) {
+    const prevFileNames = new Set(previousEntries
+        .map((ie) => {
+        const fromPath = path.basename(ie.filePath);
+        return fromPath || ie.entry.filename;
+    })
+        .filter((e) => !!e));
+    const currFileNames = new Set(currentFiles.map((f) => path.basename(f)));
+    if (prevFileNames.size !== currFileNames.size) {
+        return { kind: "file-set-changed", detail: `${prevFileNames.size} -> ${currFileNames.size} files` };
+    }
+    for (const name of currFileNames) {
+        if (!prevFileNames.has(name))
+            return { kind: "file-set-changed", detail: name };
+    }
+    for (const file of currentFiles) {
+        try {
+            if (fs.statSync(file).mtimeMs > builtAtMs)
+                return { kind: "mtime-changed", detail: path.basename(file) };
+        }
+        catch {
+            return { kind: "missing-file", detail: path.basename(file) };
+        }
+    }
+    return undefined;
+}
+export function inferZeroRowReason(stash, priorReason, warnings, dirPath, dedupedRows) {
+    if (dedupedRows > 0)
+        return "deduped-zero-row";
+    const workflowNoise = warnings.some((warning) => warning.startsWith("Skipped workflow ") && warning.includes(dirPath));
+    if (workflowNoise)
+        return "workflow-noise";
+    if (!stash || stash.entries.length === 0)
+        return "empty-generated-set";
+    return `zero-row:${priorReason?.kind ?? "unknown"}`;
+}

package/dist/indexer/search/search-source.js

@@ -5,13 +5,11 @@ import fs from "node:fs";
 import path from "node:path";
 import { resolveStashDir } from "../../core/common.js";
 import { getSources, loadConfig } from "../../core/config/config.js";
-import { resolveSourceProviderFactory } from "../../sources/provider-factory.js";
+import { resolveSourceProviderFactory, resolveSourceProviders } from "../../sources/provider-factory.js";
 // Eager side-effect imports so all built-in source providers self-register
 // before resolveEntryContentDir() runs.
 import "../../sources/providers/index.js";
 import { warn } from "../../core/warn.js";
-import { ensureGitMirror, getCachePaths, parseGitRepoUrl } from "../../sources/providers/git.js";
-import { ensureWebsiteMirror } from "../../sources/website-ingest.js";
 // Legacy "context-hub" / "github" type aliases are normalized to "git" at
 // config-load time (see src/config.ts), so this set only contains the canonical
 // type.
@@ -261,31 +259,19 @@ function isValidDirectory(dir) {
 export async function ensureSourceCaches(config, options) {
     const cfg = config ?? loadConfig();
     const force = options?.force === true;
-    const entries = getSources(cfg);
-    for (const entry of entries) {
-        if (!GIT_STASH_TYPES.has(entry.type) || !entry.url || entry.enabled === false)
+    // Polymorphic refresh: walk every enabled source through its registered
+    // provider and call `sync()`. Every cache-backed kind (git, website, npm)
+    // refreshes the same way — a bad source warns and is skipped without
+    // aborting the others. The git content/-subdir layout convention stays in
+    // resolveEntryContentDir.
+    for (const provider of resolveSourceProviders(cfg)) {
+        if (!provider.sync)
             continue;
         try {
-            const repo = parseGitRepoUrl(entry.url);
-            const cachePaths = getCachePaths(repo.canonicalUrl);
-            await ensureGitMirror(repo, cachePaths, {
-                requireRepoDir: true,
-                writable: entry.writable === true,
-                force,
-            });
-        }
-        catch (err) {
-            warn(`Warning: failed to refresh git mirror for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
-        }
-    }
-    for (const entry of entries) {
-        if (entry.type !== "website" || !entry.url || entry.enabled === false)
-            continue;
-        try {
-            await ensureWebsiteMirror(entry, { requireStashDir: true, force });
+            await provider.sync({ force });
         }
         catch (err) {
-            warn(`Warning: failed to refresh website stash for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
+            warn(`Warning: failed to refresh ${provider.kind} source "${provider.name}": ${err instanceof Error ? err.message : String(err)}`);
         }
     }
 }

package/dist/indexer/search/semantic-status.js

@@ -4,8 +4,12 @@
 import fs from "node:fs";
 import { writeFileAtomic } from "../../core/common.js";
 import { getCacheDir, getSemanticStatusPath } from "../../core/paths.js";
+import { DETERMINISTIC_EMBED_MODEL_ID, isDeterministicEmbedEnabled } from "../../llm/embedders/deterministic.js";
 import { DEFAULT_LOCAL_MODEL } from "../../llm/embedders/local.js";
 export function deriveSemanticProviderFingerprint(embedding) {
+    if (isDeterministicEmbedEnabled()) {
+        return `deterministic:${DETERMINISTIC_EMBED_MODEL_ID}`;
+    }
     if (embedding?.endpoint) {
         return `remote:${embedding.endpoint}|${embedding.model}|${embedding.dimension ?? "default"}`;
     }

package/dist/integrations/agent/runner-dispatch.js

@@ -0,0 +1,59 @@
+// 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/.
+/**
+ * X3 — the ONE dispatch seam for the {@link RunnerSpec} tagged union.
+ *
+ * The improve slice dispatches a `RunnerSpec` (`llm | agent | sdk`) in several
+ * places (`reflect.ts`, `proposal/drain.ts`, …). Before this module each site
+ * re-rolled the identical 3-arm switch and re-declared its own per-kind test
+ * seams (`chat`, `runAgentFn`, `runSdkFn`). `executeRunner` collapses that into
+ * one switch + one {@link RunnerSeams} object.
+ *
+ * Scoping (behavior-preserving):
+ *   - The `agent` and `sdk` arms are byte-identical across call sites: invoke
+ *     the profile runner (`runAgent` / `runOpencodeSdk`) with the per-call
+ *     `RunAgentOptions` the caller passes. Those default runners live here so
+ *     callers stop importing `runAgent` / `runOpencodeSdk` for dispatch. The
+ *     `opts` (incl. any `timeoutMs`) is constructed by the caller and passed
+ *     through unchanged, so each site keeps its exact option set.
+ *   - The `llm` arm is irreducibly caller-specific (reflect wraps
+ *     `runReflectViaLlm`, which returns reflect's iteration shape; drain wraps a
+ *     plain `chatCompletion`). It is therefore a REQUIRED seam — there is no
+ *     default `llm` handler — so neither caller's bespoke behavior is changed.
+ *   - The `assertNever` exhaustiveness arm is kept so a 4th `RunnerSpec` kind is
+ *     a compile error here instead of a silent runtime fall-through.
+ *
+ * The return type is {@link AgentRunResult} so a later `callStructured` layer
+ * (X2) can wrap `executeRunner` without changing this contract.
+ */
+import { assertNever } from "../../core/assert.js";
+import { runOpencodeSdk } from "../harnesses/opencode-sdk/index.js";
+import { runAgent } from "./spawn.js";
+/**
+ * Dispatch a {@link RunnerSpec} to its runner and return the raw
+ * {@link AgentRunResult}. `opts` is the {@link RunAgentOptions} for the profile
+ * (`agent` / `sdk`) arms; it is passed through unchanged so each caller keeps
+ * its exact option set (incl. any `timeoutMs` the caller chose to apply).
+ */
+export async function executeRunner(spec, prompt, opts, seams = {}) {
+    switch (spec.kind) {
+        case "llm": {
+            if (!seams.llm) {
+                throw new Error("executeRunner: an `llm` runner requires a `seams.llm` handler (no default LLM dispatch).");
+            }
+            return seams.llm(spec, prompt);
+        }
+        case "agent": {
+            const run = seams.runAgent ?? runAgent;
+            return run(spec.profile, prompt, opts);
+        }
+        case "sdk": {
+            const run = seams.runSdk ?? runOpencodeSdk;
+            return run(spec.profile, prompt, opts);
+        }
+        default:
+            // Exhaustiveness arm: a 4th RunnerSpec kind becomes a compile error here.
+            return assertNever(spec);
+    }
+}

package/dist/llm/client.js

@@ -103,18 +103,29 @@ function retryBackoffMs() {
     return RETRY_BACKOFF_MIN_MS + Math.random() * (RETRY_BACKOFF_MAX_MS - RETRY_BACKOFF_MIN_MS);
 }
 /**
- * Detect whether an error message indicates a context-size-exceeded condition.
- * Mirrors the heuristic in `graph-extract.ts` — retrying a context overflow
- * cannot shrink the input, so it must not be retried.
+ * Detect whether an error message indicates a context size exceeded condition.
+ * Covers common patterns from OpenAI-compatible APIs (LM Studio, Ollama, etc).
+ *
+ * Requires BOTH a context keyword AND token-count/overflow evidence so that
+ * model prose merely mentioning "context size" / "context length" (e.g. gemma
+ * narrating about a document) does not get misclassified as a provider
+ * context-limit error (#496).
+ *
+ * Canonical home: `graph-extract.ts` re-exports this so the index-pass
+ * graph extractor and the retry classifier (`isRetryable`) share one
+ * definition — retrying a context overflow cannot shrink the input, so it
+ * must never be retried.
  */
-function looksLikeContextOverflow(message) {
+export function isContextSizeError(message) {
     const lower = message.toLowerCase();
-    return (lower.includes("context") &&
-        (lower.includes("context size") ||
-            lower.includes("context length") ||
-            lower.includes("context_window") ||
-            lower.includes("prompt too long") ||
-            lower.includes("exceeds")));
+    const contextKw = /context (size|length|window)|prompt too long|exceeds.*context/.test(lower);
+    if (!contextKw) {
+        return false;
+    }
+    const evidence = /\b\d+\s*(token|tokens|tk)\b/.test(lower) ||
+        /max(imum)?\s+(context|token|input)/.test(lower) ||
+        /exceeded|over.*limit|too.*long/.test(lower);
+    return evidence;
 }
 /**
  * Decide whether a first-attempt {@link LlmCallError} is eligible for a single
@@ -138,7 +149,7 @@ function looksLikeContextOverflow(message) {
  * failure in the improve/reflect and capability-probe flows.
  */
 function isRetryable(err) {
-    if (looksLikeContextOverflow(err.message))
+    if (isContextSizeError(err.message))
         return false;
     if (err.code === "provider_error") {
         return typeof err.statusCode === "number" && err.statusCode >= 500;

package/dist/llm/embedder.js

@@ -2,6 +2,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { embedCacheKey, getCachedEmbedding, setCachedEmbedding } from "./embedders/cache.js";
+import { DETERMINISTIC_EMBED_MODEL_ID, deterministicEmbed, isDeterministicEmbedEnabled, } from "./embedders/deterministic.js";
 import { DEFAULT_LOCAL_MODEL, isTransformersAvailable, LocalEmbedder } from "./embedders/local.js";
 import { hasRemoteEndpoint, RemoteEmbedder } from "./embedders/remote.js";
 // ── Re-exports (public API) ─────────────────────────────────────────────────
@@ -39,6 +40,10 @@ export function resetLocalEmbedder() {
  * and embedding config. Repeated identical queries return the cached vector.
  */
 export async function embed(text, embeddingConfig, signal) {
+    // Deterministic mode (env-gated, test/bench only): model-free, stable.
+    if (isDeterministicEmbedEnabled()) {
+        return deterministicEmbed(text);
+    }
     const key = embedCacheKey(text, embeddingConfig);
     const cached = getCachedEmbedding(key);
     if (cached)
@@ -58,6 +63,10 @@ export async function embed(text, embeddingConfig, signal) {
 export async function embedBatch(texts, embeddingConfig, signal) {
     if (texts.length === 0)
         return [];
+    // Deterministic mode (env-gated, test/bench only): model-free, stable.
+    if (isDeterministicEmbedEnabled()) {
+        return texts.map((t) => deterministicEmbed(t));
+    }
     if (embeddingConfig && hasRemoteEndpoint(embeddingConfig)) {
         return new RemoteEmbedder(embeddingConfig).embedBatch(texts, signal);
     }
@@ -95,6 +104,8 @@ export { cosineSimilarity } from "./embedders/types.js";
  *   - No config: use `DEFAULT_LOCAL_MODEL` (the shared singleton model).
  */
 export function resolveEmbeddingModelId(embeddingConfig) {
+    if (isDeterministicEmbedEnabled())
+        return DETERMINISTIC_EMBED_MODEL_ID;
     if (!embeddingConfig)
         return DEFAULT_LOCAL_MODEL;
     if (hasRemoteEndpoint(embeddingConfig))
@@ -106,6 +117,10 @@ export function resolveEmbeddingModelId(embeddingConfig) {
  * Check whether embedding is available with a detailed reason on failure.
  */
 export async function checkEmbeddingAvailability(embeddingConfig) {
+    // Deterministic mode (env-gated): always available — no model, no network.
+    if (isDeterministicEmbedEnabled()) {
+        return { available: true };
+    }
     if (embeddingConfig && hasRemoteEndpoint(embeddingConfig)) {
         try {
             await new RemoteEmbedder(embeddingConfig).embed("test");

package/dist/llm/embedders/deterministic.js

@@ -0,0 +1,66 @@
+// 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/.
+/** Env var that switches the whole embedding facade into deterministic mode. */
+export const DETERMINISTIC_EMBED_ENV = "AKM_EMBED_DETERMINISTIC";
+/**
+ * Vector width. Matches the default local model (`bge-small`, 384 dims) so the
+ * index DB's embedding column and sqlite-vec table dimensions line up without
+ * any extra config.
+ */
+export const DETERMINISTIC_EMBED_DIM = 384;
+/**
+ * Stable model id reported for deterministic mode. Used as the embedding
+ * `model_id` and folded into the provider fingerprint so a deterministic index
+ * is never confused with a real-model index (and vice versa).
+ */
+export const DETERMINISTIC_EMBED_MODEL_ID = "akm-deterministic-hash-v1";
+/** True when deterministic embedding is enabled via env. */
+export function isDeterministicEmbedEnabled() {
+    return process.env[DETERMINISTIC_EMBED_ENV] === "1";
+}
+/** FNV-1a 32-bit hash. Platform- and version-stable. */
+function fnv1a(str) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < str.length; i++) {
+        h ^= str.charCodeAt(i);
+        // 32-bit FNV prime multiply via shifts to stay in uint32.
+        h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+    }
+    return h >>> 0;
+}
+/** Lowercase, split on non-alphanumeric, drop empties. */
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length > 0);
+}
+/**
+ * Deterministically embed `text` into a unit-length vector of width `dim`
+ * using feature hashing. Empty / token-less input returns a fixed unit
+ * vector so cosine similarity never sees a zero vector (NaN guard).
+ */
+export function deterministicEmbed(text, dim = DETERMINISTIC_EMBED_DIM) {
+    const vec = new Array(dim).fill(0);
+    const tokens = tokenize(text);
+    for (const tok of tokens) {
+        const h = fnv1a(tok);
+        const idx = h % dim;
+        // Use a higher bit for the sign so it is independent of the bucket index.
+        const sign = (h >>> 16) & 1 ? 1 : -1;
+        vec[idx] += sign;
+    }
+    let norm = 0;
+    for (const v of vec)
+        norm += v * v;
+    norm = Math.sqrt(norm);
+    if (norm === 0) {
+        // No usable tokens — return a fixed, stable unit vector.
+        vec[0] = 1;
+        return vec;
+    }
+    for (let i = 0; i < dim; i++)
+        vec[i] /= norm;
+    return vec;
+}

package/dist/llm/graph-extract.js

@@ -24,8 +24,9 @@ import systemPromptTemplate from "../assets/prompts/graph-extract-system.md" wit
 import userPromptTemplate from "../assets/prompts/graph-extract-user-prompt.md" with { type: "text" };
 import { toErrorMessage } from "../core/common.js";
 import { warn, warnVerbose } from "../core/warn.js";
-import { chatCompletion, LlmCallError, parseEmbeddedJsonResponse } from "./client.js";
+import { chatCompletion, isContextSizeError, parseEmbeddedJsonResponse } 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.
@@ -46,26 +47,11 @@ 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));
-/**
- * Detect whether an error message indicates a context size exceeded condition.
- * Covers common patterns from OpenAI-compatible APIs (LM Studio, Ollama, etc).
- *
- * Requires BOTH a context keyword AND token-count/overflow evidence so that
- * model prose merely mentioning "context size" / "context length" (e.g. gemma
- * narrating about a document) does not get misclassified as a provider
- * context-limit error (#496).
- */
-export function isContextSizeError(message) {
-    const lower = message.toLowerCase();
-    const contextKw = /context (size|length|window)|prompt too long|exceeds.*context/.test(lower);
-    if (!contextKw) {
-        return false;
-    }
-    const evidence = /\b\d+\s*(token|tokens|tk)\b/.test(lower) ||
-        /max(imum)?\s+(context|token|input)/.test(lower) ||
-        /exceeded|over.*limit|too.*long/.test(lower);
-    return evidence;
-}
+// `isContextSizeError` is defined in `./client` and re-exported here so the
+// graph extractor and the retry classifier (`isRetryable`) share one
+// definition (#496). Re-exported (not just imported) to preserve existing
+// importers of this module — including its unit test.
+export { isContextSizeError } from "./client.js";
 const GENERIC_ENTITIES = new Set([
     "agent",
     "application",
@@ -703,17 +689,21 @@ export async function extractGraphFromBody(llmConfig, body, signal, akmConfig, o
         return merged;
     }
     const userPrompt = `${USER_PROMPT_PREFIX}${trimmedBody}`;
-    return tryLlmFeature("graph_extraction", akmConfig, async () => {
-        try {
-            const raw = await chatCompletion(llmConfig, [
-                { role: "system", content: SYSTEM_PROMPT },
-                { role: "user", content: userPrompt },
-            ], {
-                temperature: 0.1,
-                timeoutMs: llmConfig.timeoutMs,
-                signal,
-                onRetryAttempt: () => bumpTelemetry(options.telemetry, "retryAttempts"),
-            });
+    return callStructured({
+        feature: "graph_extraction",
+        akmConfig,
+        config: llmConfig,
+        messages: [
+            { role: "system", content: SYSTEM_PROMPT },
+            { role: "user", content: userPrompt },
+        ],
+        request: {
+            temperature: 0.1,
+            timeoutMs: llmConfig.timeoutMs,
+            signal,
+            onRetryAttempt: () => bumpTelemetry(options.telemetry, "retryAttempts"),
+        },
+        parse: (raw) => {
             if (!raw)
                 return empty();
             const parsed = parseEmbeddedJsonResponse(raw);
@@ -729,16 +719,16 @@ export async function extractGraphFromBody(llmConfig, body, signal, akmConfig, o
             if (extraction.status === "failed")
                 bumpTelemetry(options.telemetry, "failureCount");
             return extraction;
-        }
-        catch (err) {
+        },
+        onError: (cls, err) => {
             const errMsg = toErrorMessage(err);
-            if (isContextSizeError(errMsg)) {
+            if (cls === "context_limit") {
                 bumpTelemetry(options.telemetry, "failureCount");
                 warn(`graph extraction: context size exceeded for asset; promptChars=${userPrompt.length}${formatContextHint(llmConfig)}. ` +
                     `Consider increasing llm.contextLength in config.json.`);
                 return empty("context_limit", "failed");
             }
-            else if (err instanceof LlmCallError && err.code === "provider_html_error") {
+            else if (cls === "html") {
                 bumpTelemetry(options.telemetry, "htmlErrorCount");
                 warn(`graph extraction: provider returned HTML instead of JSON for asset; promptChars=${userPrompt.length}${formatContextHint(llmConfig)}: ${errMsg}`);
                 return empty("llm_error", "failed");
@@ -748,9 +738,8 @@ export async function extractGraphFromBody(llmConfig, body, signal, akmConfig, o
                 warn(`graph extraction failed for asset; promptChars=${userPrompt.length}${formatContextHint(llmConfig)}: ${errMsg}`);
                 return empty("llm_error", "failed");
             }
-        }
-    }, empty(), {
-        timeoutMs: llmConfig.timeoutMs,
+        },
+        fallback: empty(),
         onFallback,
     });
 }

package/dist/llm/memory-infer.js

@@ -22,8 +22,8 @@ import memoryInferSystemPrompt from "../assets/prompts/memory-infer-system.md" w
 import memoryInferUserPrompt from "../assets/prompts/memory-infer-user.md" with { type: "text" };
 import { toErrorMessage } from "../core/common.js";
 import { warn } from "../core/warn.js";
-import { chatCompletion, LlmCallError, parseEmbeddedJsonResponse } from "./client.js";
-import { tryLlmFeature } from "./feature-gate.js";
+import { parseEmbeddedJsonResponse } from "./client.js";
+import { callStructured } from "./structured-call.js";
 /** Hard cap on body chars sent to the model — pragmatic and matches `runLlmEnrich`. */
 const MAX_BODY_CHARS = 4000;
 const SYSTEM_PROMPT = memoryInferSystemPrompt;
@@ -59,26 +59,39 @@ const DERIVED_MEMORY_JSON_SCHEMA = {
  * Errors are logged via `warn()` but never thrown — a failed split for one memory
  * must not abort the rest of the index pass.
  *
- * Routes through `tryLlmFeature("memory_inference", ...)` so the feature gate
- * and onFallback hook are honoured uniformly (Fix C5).
+ * Routes through `callStructured({ feature: "memory_inference", ... })` so the
+ * feature gate, error classification, and onFallback hook are honoured uniformly
+ * (Fix C5).
  */
 export async function compressMemoryToDerivedMemory(llmConfig, body, signal, akmConfig, onFallback, telemetry, onRetryAttempt) {
     const trimmedBody = body.trim();
     if (!trimmedBody)
         return undefined;
     const userPrompt = `${USER_PROMPT_PREFIX}${trimmedBody.slice(0, MAX_BODY_CHARS)}`;
-    return tryLlmFeature("memory_inference", akmConfig, async () => {
-        try {
-            const raw = await chatCompletion(llmConfig, [
-                { role: "system", content: SYSTEM_PROMPT },
-                { role: "user", content: userPrompt },
-            ], {
-                temperature: 0.1,
-                timeoutMs: llmConfig.timeoutMs,
-                signal,
-                responseSchema: DERIVED_MEMORY_JSON_SCHEMA,
-                onRetryAttempt,
-            });
+    // Memory-inference is ALWAYS gated: no `akmConfig` ⇒ gate closed (no chat,
+    // `disabled` fallback), never the seam's ungated/propagate path (which is for
+    // direct callers like `enhanceMetadata`). This is the gate-closed branch
+    // `tryLlmFeature(_, undefined, _)` took before the migration.
+    if (!akmConfig) {
+        onFallback?.({ feature: "memory_inference", reason: "disabled" });
+        return undefined;
+    }
+    return callStructured({
+        feature: "memory_inference",
+        akmConfig,
+        config: llmConfig,
+        messages: [
+            { role: "system", content: SYSTEM_PROMPT },
+            { role: "user", content: userPrompt },
+        ],
+        request: {
+            temperature: 0.1,
+            timeoutMs: llmConfig.timeoutMs,
+            signal,
+            responseSchema: DERIVED_MEMORY_JSON_SCHEMA,
+            onRetryAttempt,
+        },
+        parse: (raw) => {
             if (!raw)
                 return undefined;
             const parsed = parseEmbeddedJsonResponse(raw);
@@ -108,9 +121,9 @@ export async function compressMemoryToDerivedMemory(llmConfig, body, signal, akm
                 return undefined;
             }
             return { title, description, tags, searchHints, content };
-        }
-        catch (err) {
-            if (err instanceof LlmCallError && err.code === "provider_html_error") {
+        },
+        onError: (cls, err) => {
+            if (cls === "html") {
                 if (telemetry)
                     telemetry.htmlErrorCount = (telemetry.htmlErrorCount ?? 0) + 1;
                 warn(`memory inference: provider returned HTML instead of JSON; skipping memory: ${toErrorMessage(err)}`);
@@ -118,9 +131,8 @@ export async function compressMemoryToDerivedMemory(llmConfig, body, signal, akm
             }
             warn(`memory inference failed: ${toErrorMessage(err)}`);
             return undefined;
-        }
-    }, undefined, {
-        timeoutMs: llmConfig.timeoutMs,
+        },
+        fallback: undefined,
         onFallback,
     });
 }