akm-cli 0.9.0-beta.9 → 0.9.0-rc.0

package/dist/integrations/harnesses/opencode/session-log.js

@@ -4,6 +4,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { openDatabase } from "../../../storage/database.js";
 import { extractInlineRefMentions } from "../../session-logs/inline-refs.js";
 function getOpenCodeBaseDir() {
     if (process.platform === "darwin") {
@@ -12,20 +13,49 @@ function getOpenCodeBaseDir() {
     return path.join(os.homedir(), ".local", "share", "opencode");
 }
 /**
- * Opencode storage layout (observed 2026-05):
- *   <base>/storage/session/<projectId>/<sessionId>.json    — metadata
- *   <base>/storage/message/<sessionId>/<messageId>.json    — one per message
+ * Opencode storage layouts:
+ *
+ *   SQLite (current, observed 2026-06): `<base>/opencode.db` — a Drizzle-managed
+ *   database with `session` / `message` / `part` tables. Message text lives in
+ *   `part` rows (`data` JSON, `type: "text"`); `message.data` holds role/timing.
+ *   This is the layout current opencode builds write; it is preferred whenever
+ *   `opencode.db` exists.
+ *
+ *   JSON files (legacy, observed 2026-05): `<base>/storage/session/<projectId>/
+ *   <sessionId>.json` (metadata) + `<base>/storage/message/<sessionId>/
+ *   <messageId>.json` (one per message). Read only when `opencode.db` is absent.
  *
  * Older builds wrote logs directly into `<base>/log/` and `<base>/*.log`;
  * those are still scanned by {@link OpenCodeProvider.readEvents} for
  * backward compatibility with the existing failure-pattern aggregator.
  */
+/** Filename of opencode's SQLite session store, relative to its base dir. */
+const OPENCODE_DB_FILENAME = "opencode.db";
 export class OpenCodeProvider {
     name = "opencode";
     #baseDir = getOpenCodeBaseDir();
     isAvailable() {
         return fs.existsSync(this.#baseDir);
     }
+    /** Absolute path to opencode's SQLite store under `base`. */
+    #dbPath(base) {
+        return path.join(base, OPENCODE_DB_FILENAME);
+    }
+    /**
+     * Directories/files opencode writes session data under. Returns the base dir
+     * when the SQLite store (`opencode.db`) exists, the legacy JSON session root
+     * (`<base>/storage/session`) when present, or both during a migration overlap.
+     * Empty when neither exists. See {@link SessionLogHarness.watchRoots}.
+     */
+    watchRoots() {
+        const roots = [];
+        if (fs.existsSync(this.#dbPath(this.#baseDir)))
+            roots.push(this.#baseDir);
+        const sessionRoot = path.join(this.#baseDir, "storage", "session");
+        if (fs.existsSync(sessionRoot))
+            roots.push(sessionRoot);
+        return roots;
+    }
     *readEvents(input) {
         // Legacy behavior: stream raw log lines from the top-level dir and `log/`
         // subdirectory. Kept to keep `getExecutionLogCandidates` working without
@@ -82,6 +112,9 @@ export class OpenCodeProvider {
     listSessions(input = {}) {
         const base = input.location ?? this.#baseDir;
         const sinceMs = input.sinceMs ?? 0;
+        const dbPath = this.#dbPath(base);
+        if (fs.existsSync(dbPath))
+            return this.#listSessionsFromDb(dbPath, sinceMs);
         const sessionRoot = path.join(base, "storage", "session");
         if (!fs.existsSync(sessionRoot))
             return [];
@@ -142,6 +175,8 @@ export class OpenCodeProvider {
         return summaries.sort((a, b) => (b.endedAt ?? 0) - (a.endedAt ?? 0));
     }
     readSession(ref) {
+        if (path.basename(ref.filePath) === OPENCODE_DB_FILENAME)
+            return this.#readSessionFromDb(ref);
         let meta = {};
         try {
             meta = JSON.parse(fs.readFileSync(ref.filePath, "utf8"));
@@ -199,6 +234,141 @@ export class OpenCodeProvider {
             inlineRefs,
         };
     }
+    /**
+     * List sessions from the SQLite store. `filePath` on each summary is the
+     * `opencode.db` path so {@link readSession} can route back to the DB reader.
+     * Returns `[]` (never throws) when the DB is unreadable or lacks the expected
+     * schema — callers treat a missing harness as "no sessions".
+     */
+    #listSessionsFromDb(dbPath, sinceMs) {
+        let db;
+        try {
+            db = openDatabase(dbPath, { readonly: true, create: false });
+        }
+        catch {
+            return [];
+        }
+        try {
+            const rows = db
+                .prepare("SELECT id, title, directory, time_created, time_updated FROM session WHERE time_updated >= ? ORDER BY time_updated DESC")
+                .all(sinceMs);
+            return rows.map((r) => {
+                const startedAt = typeof r.time_created === "number" ? r.time_created : undefined;
+                const endedAt = typeof r.time_updated === "number" ? r.time_updated : undefined;
+                const title = typeof r.title === "string" && r.title.length > 0 ? r.title : undefined;
+                const projectHint = typeof r.directory === "string" && r.directory.length > 0 ? r.directory : undefined;
+                return {
+                    harness: this.name,
+                    sessionId: r.id,
+                    filePath: dbPath,
+                    ...(startedAt !== undefined ? { startedAt } : {}),
+                    ...(endedAt !== undefined ? { endedAt } : {}),
+                    ...(projectHint ? { projectHint } : {}),
+                    ...(title ? { title } : {}),
+                };
+            });
+        }
+        catch {
+            // Missing `session` table / unexpected schema — treat as no sessions.
+            return [];
+        }
+        finally {
+            db.close();
+        }
+    }
+    /**
+     * Read one session from the SQLite store. Message text lives in `part` rows
+     * (`type: "text"`); `message.data` carries role + timing. One event per
+     * message, text-parts concatenated in time order. Returns empty events
+     * (never throws) when the DB is unreadable.
+     */
+    #readSessionFromDb(ref) {
+        const emptyRef = { harness: this.name, sessionId: ref.sessionId, filePath: ref.filePath };
+        let db;
+        try {
+            db = openDatabase(ref.filePath, { readonly: true, create: false });
+        }
+        catch {
+            return { ref: emptyRef, events: [], inlineRefs: [] };
+        }
+        try {
+            const meta = db
+                .prepare("SELECT title, directory, time_created, time_updated FROM session WHERE id = ?")
+                .get(ref.sessionId);
+            const startedAt = typeof meta?.time_created === "number" ? meta.time_created : undefined;
+            const endedAt = typeof meta?.time_updated === "number" ? meta.time_updated : undefined;
+            const title = typeof meta?.title === "string" && meta.title.length > 0 ? meta.title : undefined;
+            const projectHint = typeof meta?.directory === "string" && meta.directory.length > 0 ? meta.directory : undefined;
+            const messages = db
+                .prepare("SELECT id, data, time_created FROM message WHERE session_id = ? ORDER BY time_created ASC, id ASC")
+                .all(ref.sessionId);
+            const parts = db
+                .prepare("SELECT message_id, data FROM part WHERE session_id = ? ORDER BY time_created ASC, id ASC")
+                .all(ref.sessionId);
+            // Group text-part bodies by their parent message.
+            const textByMessage = new Map();
+            for (const part of parts) {
+                let parsed;
+                try {
+                    parsed = JSON.parse(part.data);
+                }
+                catch {
+                    continue;
+                }
+                if (parsed?.type !== "text")
+                    continue;
+                const text = parsed.text;
+                if (typeof text !== "string" || text.length < 1)
+                    continue;
+                const bucket = textByMessage.get(part.message_id) ?? [];
+                bucket.push(text);
+                textByMessage.set(part.message_id, bucket);
+            }
+            const events = [];
+            const inlineRefs = [];
+            for (const message of messages) {
+                let mdata = {};
+                try {
+                    mdata = JSON.parse(message.data);
+                }
+                catch {
+                    // role/timing unavailable — fall through with defaults
+                }
+                const role = typeof mdata.role === "string" ? mdata.role : "unknown";
+                const mtime = mdata.time?.created;
+                const ts = typeof mtime === "number"
+                    ? mtime
+                    : typeof message.time_created === "number"
+                        ? message.time_created
+                        : undefined;
+                const text = (textByMessage.get(message.id) ?? []).join("\n").trim();
+                if (text.length < 1)
+                    continue;
+                events.push({ harness: this.name, text, ts, sessionId: ref.sessionId, role, filePath: ref.filePath });
+                inlineRefs.push(...extractInlineRefMentions(text, ts));
+            }
+            events.sort((a, b) => (a.ts ?? 0) - (b.ts ?? 0));
+            return {
+                ref: {
+                    harness: this.name,
+                    sessionId: ref.sessionId,
+                    filePath: ref.filePath,
+                    ...(startedAt !== undefined ? { startedAt } : {}),
+                    ...(endedAt !== undefined ? { endedAt } : {}),
+                    ...(projectHint ? { projectHint } : {}),
+                    ...(title ? { title } : {}),
+                },
+                events,
+                inlineRefs,
+            };
+        }
+        catch {
+            return { ref: emptyRef, events: [], inlineRefs: [] };
+        }
+        finally {
+            db.close();
+        }
+    }
     /**
      * Derive opencode base dir from a session metadata file path so a caller
      * passing a custom `--location` can still find the message dir.

package/dist/integrations/harnesses/opencode-sdk/index.js

@@ -5,7 +5,7 @@
  * OpenCode SDK harness (#564).
  *
  * Per-harness barrel for the SDK-mode dispatch path:
- *   - agent runner → ./sdk-runner.ts (runOpencodeSdk / runAgentSdk)
+ *   - agent runner → ./sdk-runner.ts (runOpencodeSdk)
  *
  * It also defines {@link OpencodeSdkHarness}, the {@link AkmHarness} descriptor
  * that `HARNESS_REGISTRY` registers.
@@ -17,7 +17,7 @@
  * names. Canonical id is `'opencode-sdk'` with no alias.
  */
 import { BaseHarness } from "../types.js";
-export { closeServer, runAgentSdk, runOpencodeSdk } from "./sdk-runner.js";
+export { closeServer, runOpencodeSdk } from "./sdk-runner.js";
 function caps(c) {
     return {
         sessionLogs: false,

package/dist/integrations/harnesses/opencode-sdk/sdk-runner.js

@@ -14,6 +14,7 @@
  */
 import { resolveSecret } from "../../../core/config/config.js";
 import { DEFAULT_AGENT_TIMEOUT_MS } from "../../agent/config.js";
+import { resolveModel } from "../../agent/model-aliases.js";
 // Singleton server — started once per process, reused across calls
 let _server = null;
 /**
@@ -85,16 +86,23 @@ function toolsToSdkAllowlist(tools) {
         out[n] = true;
     return out;
 }
-async function getOrStartServer(profile, llmConfig) {
-    if (_server)
-        return _server;
-    const { createOpencode } = await import("@opencode-ai/sdk").catch(() => {
-        throw new Error("OpenCode SDK not available. Install @opencode-ai/sdk or configure a CLI agent instead.");
-    });
+/**
+ * Assemble the OpenCode SDK server config from the profile + LLM fallback.
+ * Pure and exported for tests. `profile.model` is resolved through the model
+ * alias tables (platform key `"opencode-sdk"`) so config aliases like
+ * `"model": "fast"` work on the SDK path the same way they do for CLI
+ * builders. Note there is no built-in alias column for `opencode-sdk` —
+ * built-in opus/sonnet/haiku strings are CLI-provider-qualified and would
+ * collide with the `akm-custom/` provider prefixing below, so only profile
+ * and config-root alias tables apply here.
+ */
+export function buildSdkConfig(profile, llmConfig) {
     // Resolve endpoint and model: profile fields take precedence over config.llm
     const endpoint = profile.endpoint ?? llmConfig?.endpoint;
     const apiKey = resolveSecret(profile.apiKey ?? llmConfig?.apiKey);
-    const model = profile.model;
+    const model = profile.model
+        ? resolveModel(profile.model, "opencode-sdk", profile.modelAliases, profile.globalModelAliases)
+        : undefined;
     const sdkConfig = {};
     if (model)
         sdkConfig.model = model;
@@ -114,6 +122,15 @@ async function getOrStartServer(profile, llmConfig) {
             sdkConfig.model = `akm-custom/${model}`;
         }
     }
+    return sdkConfig;
+}
+async function getOrStartServer(profile, llmConfig) {
+    if (_server)
+        return _server;
+    const { createOpencode } = await import("@opencode-ai/sdk").catch(() => {
+        throw new Error("OpenCode SDK not available. Install @opencode-ai/sdk or configure a CLI agent instead.");
+    });
+    const sdkConfig = buildSdkConfig(profile, llmConfig);
     _server = (await createOpencode(Object.keys(sdkConfig).length > 0 ? { config: sdkConfig } : {}));
     process.once("exit", () => {
         closeServer();
@@ -122,8 +139,38 @@ async function getOrStartServer(profile, llmConfig) {
         throw new Error("Failed to initialise OpenCode SDK server.");
     return _server;
 }
+/**
+ * Extract best-effort token usage from a prompt response. Only numeric
+ * fields the server actually reported are copied; returns undefined when
+ * nothing usable is present (older servers, test fakes).
+ */
+function extractUsage(info) {
+    const tokens = info?.tokens;
+    if (!tokens)
+        return undefined;
+    const usage = {};
+    if (typeof tokens.input === "number" && Number.isFinite(tokens.input))
+        usage.inputTokens = tokens.input;
+    if (typeof tokens.output === "number" && Number.isFinite(tokens.output))
+        usage.outputTokens = tokens.output;
+    if (typeof tokens.reasoning === "number" && Number.isFinite(tokens.reasoning)) {
+        usage.reasoningTokens = tokens.reasoning;
+    }
+    return Object.keys(usage).length > 0 ? usage : undefined;
+}
 export async function runOpencodeSdk(profile, prompt, opts = {}, llmConfig) {
     const start = Date.now();
+    if (opts.signal?.aborted) {
+        return {
+            ok: false,
+            stdout: "",
+            stderr: "",
+            durationMs: 0,
+            exitCode: null,
+            reason: "aborted",
+            error: `opencode-sdk agent "${profile.name}" not started: caller signal already aborted`,
+        };
+    }
     let client;
     try {
         ({ client } = await getOrStartServer(profile, llmConfig));
@@ -180,16 +227,42 @@ export async function runOpencodeSdk(profile, prompt, opts = {}, llmConfig) {
     const clearTimeoutImpl = opts.clearTimeoutFn ?? clearTimeout;
     let timer;
     const TIMED_OUT = Symbol("opencode-sdk-timeout");
+    const ABORTED = Symbol("opencode-sdk-aborted");
+    // Cooperative cancel: there is no OS process to signal, so an abort simply
+    // wins the race below; the finally block reaps the in-flight session, same
+    // as the timeout path.
+    let onAbort;
+    const abortSignal = opts.signal;
     try {
         const promptPromise = client.session.prompt({ path: { id: sessionId }, body });
-        const result = timeoutMs === null
-            ? await promptPromise
-            : await Promise.race([
-                promptPromise,
-                new Promise((resolve) => {
-                    timer = setTimeoutImpl(() => resolve(TIMED_OUT), timeoutMs);
-                }),
-            ]);
+        const racers = [promptPromise];
+        if (timeoutMs !== null) {
+            racers.push(new Promise((resolve) => {
+                timer = setTimeoutImpl(() => resolve(TIMED_OUT), timeoutMs);
+            }));
+        }
+        if (abortSignal) {
+            racers.push(new Promise((resolve) => {
+                onAbort = () => resolve(ABORTED);
+                if (abortSignal.aborted)
+                    onAbort();
+                else
+                    abortSignal.addEventListener("abort", onAbort, { once: true });
+            }));
+        }
+        const result = racers.length === 1 ? await promptPromise : await Promise.race(racers);
+        if (result === ABORTED) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: "",
+                durationMs: Date.now() - start,
+                exitCode: null,
+                reason: "aborted",
+                error: `opencode-sdk agent "${profile.name}" aborted by caller signal`,
+                sessionId,
+            };
+        }
         if (result === TIMED_OUT) {
             return {
                 ok: false,
@@ -199,17 +272,24 @@ export async function runOpencodeSdk(profile, prompt, opts = {}, llmConfig) {
                 exitCode: null,
                 reason: "timeout",
                 error: `opencode-sdk agent "${profile.name}" timed out after ${timeoutMs}ms`,
+                sessionId,
             };
         }
         const parts = result.data?.parts ?? [];
         const textPart = parts.find((p) => p.type === "text");
         const stdout = textPart?.text ?? "";
+        // Token accounting from the AssistantMessage (previously discarded) —
+        // the seam that makes workflow budget.maxTokens meterable on the
+        // default sdk runner.
+        const usage = extractUsage(result.data?.info);
         return {
             ok: true,
             stdout,
             stderr: "",
             durationMs: Date.now() - start,
             exitCode: 0,
+            sessionId,
+            ...(usage ? { usage } : {}),
         };
     }
     catch (e) {
@@ -221,14 +301,15 @@ export async function runOpencodeSdk(profile, prompt, opts = {}, llmConfig) {
             exitCode: 1,
             reason: "non_zero_exit",
             error: String(e),
+            sessionId,
         };
     }
     finally {
         if (timer !== undefined)
             clearTimeoutImpl(timer);
+        if (abortSignal && onAbort)
+            abortSignal.removeEventListener("abort", onAbort);
         // Clean up session to prevent disk accumulation in ~/.local/share/opencode/
         await client.session.delete({ path: { id: sessionId } }).catch(() => { });
     }
 }
-/** @deprecated Use {@link runOpencodeSdk} instead. */
-export const runAgentSdk = runOpencodeSdk;

package/dist/integrations/harnesses/types.js

@@ -13,6 +13,7 @@
 export class BaseHarness {
     runtimeId;
     setupDetectionDir;
+    agentBuilder;
     /**
      * Lowercase prefixes that a decorated v1 profile name may start with and
      * still belong to this harness (e.g. `["opencode-sdk"]`). The canonical id

package/dist/integrations/session-logs/index.js

@@ -28,6 +28,22 @@ const ERROR_PATTERNS = /error|failed|exception|cannot|undefined|null pointer|ENO
 export function getAvailableHarnesses() {
     return HARNESSES.filter((harness) => harness.isAvailable());
 }
+/**
+ * Map each available harness to its `{ harnessName, roots }` watch target,
+ * skipping harnesses that expose no roots (absent `watchRoots()` or an empty
+ * result). This is the one stable entry point the watcher uses so it never
+ * reaches into providers directly.
+ */
+export function getWatchTargets() {
+    const targets = [];
+    for (const harness of getAvailableHarnesses()) {
+        const roots = harness.watchRoots?.() ?? [];
+        if (roots.length === 0)
+            continue;
+        targets.push({ harnessName: harness.name, roots });
+    }
+    return targets;
+}
 export function normalizeSessionTopic(text) {
     const normalized = text.replace(/\s+/g, " ").trim().toLowerCase();
     if (normalized.length < 10)

package/dist/llm/call-ai.js

@@ -3,7 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { getDefaultLlmConfig } from "../core/config/config.js";
 import { warn } from "../core/warn.js";
-import { resolveAgentProfile, runAgent } from "../integrations/agent/index.js";
+import { resolveProfileFromConfig, runAgent } from "../integrations/agent/index.js";
 import { chatCompletion } from "./client.js";
 /**
  * Unified AI call: prefers the default agent profile, falls back to the
@@ -14,7 +14,7 @@ export async function callAi(config, prompt, opts = {}) {
     const defaultAgentName = config.defaults?.agent;
     if (defaultAgentName) {
         try {
-            const profile = resolveAgentProfile(defaultAgentName, config.profiles?.agent?.[defaultAgentName]);
+            const profile = resolveProfileFromConfig(defaultAgentName, config);
             if (!profile) {
                 return {
                     ok: false,

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;
@@ -154,7 +165,19 @@ function isRetryable(err) {
     }
     return false;
 }
+// ── Test seam ────────────────────────────────────────────────────────────────
+// Swap-and-restore override. Inert in production; only tests call the setter.
+let chatCompletionOverride;
+/** TEST-ONLY. Swap the implementation of `chatCompletion`; pass undefined to restore. */
+export function _setChatCompletionForTests(fake) {
+    chatCompletionOverride = fake;
+}
 export async function chatCompletion(config, messages, options) {
+    if (chatCompletionOverride)
+        return chatCompletionOverride(config, messages, options);
+    return chatCompletionReal(config, messages, options);
+}
+async function chatCompletionReal(config, messages, options) {
     const effectiveTimeoutMs = options?.timeoutMs ?? config.timeoutMs ?? 120_000;
     const started = Date.now();
     try {

package/dist/llm/embedder.js

@@ -2,11 +2,27 @@
 // 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 { isTransformersAvailable, LocalEmbedder } from "./embedders/local.js";
+import { DETERMINISTIC_EMBED_MODEL_ID, deterministicEmbed, isDeterministicEmbedEnabled, } from "./embedders/deterministic.js";
+import { DEFAULT_LOCAL_MODEL, isTransformersAvailable as isTransformersAvailableReal, LocalEmbedder, } from "./embedders/local.js";
 import { hasRemoteEndpoint, RemoteEmbedder } from "./embedders/remote.js";
 // ── Re-exports (public API) ─────────────────────────────────────────────────
 export { clearEmbeddingCache } from "./embedders/cache.js";
-export { DEFAULT_LOCAL_MODEL, isTransformersAvailable } from "./embedders/local.js";
+export { _setTransformersLoaderForTests, DEFAULT_LOCAL_MODEL } from "./embedders/local.js";
+let embedderOverrides;
+/** TEST-ONLY. Swap embedder implementations; pass undefined to restore. */
+export function _setEmbedderForTests(fakes) {
+    embedderOverrides = fakes;
+}
+/**
+ * Check whether the @huggingface/transformers package is importable.
+ * Delegating wrapper around `./embedders/local`'s probe so tests can swap it
+ * via {@link _setEmbedderForTests}.
+ */
+export function isTransformersAvailable() {
+    if (embedderOverrides?.isTransformersAvailable)
+        return embedderOverrides.isTransformersAvailable();
+    return isTransformersAvailableReal();
+}
 // ── Singleton local embedder ────────────────────────────────────────────────
 // `_localEmbedder` is an intentional module-level singleton but constructed
 // lazily on first use. The underlying @huggingface/transformers pipeline is
@@ -39,6 +55,12 @@ export function resetLocalEmbedder() {
  * and embedding config. Repeated identical queries return the cached vector.
  */
 export async function embed(text, embeddingConfig, signal) {
+    if (embedderOverrides?.embed)
+        return embedderOverrides.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)
@@ -52,16 +74,28 @@ export async function embed(text, embeddingConfig, signal) {
 /**
  * Generate embeddings for multiple texts in batch.
  * Uses the OpenAI-compatible batch API for remote endpoints (batches of 100).
- * Falls back to sequential embedding for the local transformer pipeline.
+ * Uses the LocalEmbedder.embedBatch path for the local transformer pipeline,
+ * which processes texts in chunks of 32 for genuine batched inference.
  */
 export async function embedBatch(texts, embeddingConfig, signal) {
+    if (embedderOverrides?.embedBatch)
+        return embedderOverrides.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);
     }
-    // Local transformer: process sequentially (pipeline handles one at a time)
+    // Local transformer: use the batched path (chunks of 32 via LocalEmbedder).
+    // When a localModel override is set we cannot share the singleton (which uses
+    // the default model), so fall back to per-text embedWithModel in that case.
     const localModel = embeddingConfig?.localModel;
+    if (!localModel) {
+        return getLocalEmbedder().embedBatch(texts, signal);
+    }
     const results = [];
     for (const text of texts) {
         if (signal?.aborted) {
@@ -77,11 +111,40 @@ export async function embedBatch(texts, embeddingConfig, signal) {
 // facade and its `@huggingface/transformers` import chain. Re-export
 // preserves the existing public API.
 export { cosineSimilarity } from "./embedders/types.js";
+// ── Model ID resolution ─────────────────────────────────────────────────────
+/**
+ * Derive a stable string identifier for the embedding model in use.
+ * This is the `model_id` stored in `body_embeddings` (and used for the
+ * drop-all-on-mismatch purge when the model changes).
+ *
+ * Rules:
+ *   - Remote endpoint: use `config.model` (the API-level model name).
+ *   - Local transformers: use `config.localModel ?? DEFAULT_LOCAL_MODEL`.
+ *   - No config: use `DEFAULT_LOCAL_MODEL` (the shared singleton model).
+ */
+export function resolveEmbeddingModelId(embeddingConfig) {
+    if (embedderOverrides?.resolveEmbeddingModelId)
+        return embedderOverrides.resolveEmbeddingModelId(embeddingConfig);
+    if (isDeterministicEmbedEnabled())
+        return DETERMINISTIC_EMBED_MODEL_ID;
+    if (!embeddingConfig)
+        return DEFAULT_LOCAL_MODEL;
+    if (hasRemoteEndpoint(embeddingConfig))
+        return embeddingConfig.model ?? "remote";
+    return embeddingConfig.localModel ?? DEFAULT_LOCAL_MODEL;
+}
 // ── Availability check ──────────────────────────────────────────────────────
 /**
  * Check whether embedding is available with a detailed reason on failure.
  */
 export async function checkEmbeddingAvailability(embeddingConfig) {
+    if (embedderOverrides?.checkEmbeddingAvailability) {
+        return embedderOverrides.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");