@modusensus/dsh-mneme 0.8.3 → 0.8.4

package/lib/index.js

@@ -1,515 +1,515 @@
-import { createStore } from "./store.js";
-import { createMirror, TYPE_FILE } from "./mirror.js";
-import { createService } from "./service.js";
-import { createTools } from "./tools.js";
-import { createInjector } from "./inject.js";
-import { createSummarizer } from "./summarize.js";
-import { createDreamScheduler } from "./dream.js";
-import { createSleepScheduler, runSleep } from "./dream/sleep.js";
-import { createApi } from "./api.js";
-import { createStandaloneApi } from "./api-standalone.js";
-import { createSettings } from "./settings.js";
-import { createCommandManager } from "./commands.js";
-import { createEmbedder } from "./embedding.js";
-import { createEmbedderByProvider } from "./local-embedder.js";
-import { LocalReranker } from "./reranker.js";
-import { createVectorIndex } from "./vector-index.js";
-import { Config, applyLightModePreset } from "./config.js";
-import { langOf } from "./lang.js";
-import { extractEntities } from "./entities/extractor.js";
-import { mkdirSync } from "node:fs";
-import { join } from "node:path";
-import { homedir } from "node:os";
-
-export const name = "dsh-mneme";
-// webServer 在 inject 声明中：cordis 会等宿主 webServer 服务激活后才 apply 本
-// 插件，保证 apply 时路由注册不落时序（v0.7.23 曾移出 inject 想支持 headless，
-// 结果 cordis 不再等待，apply 时宿主 webServer 未就绪 → 桌面端 "cannot get
-// property without inject" 崩溃）。守卫用 ctx.reflect.get（免 inject 读取，
-// 未提供返回 undefined）而非 if (ctx.webServer)：直接访问未注入属性在 cordis
-// Proxy 下会抛错而非返回 undefined。
-export const inject = ["tools", "systemPrompt", "llm", "agentDefaultModel", "commands", "webServer"];
-export { Config };
-
-// Arrow (not function declaration): cordis 4 treats any apply with a
-// prototype as a class constructor (`new apply(...)`) and discards its return
-// value, so a `function apply` disposer would never run on unload. An arrow
-// has no prototype, is called normally, and its returned disposer is collected
-// and run by the fiber on unload.
-// Entity-extraction LLM adapter (issue #108/#109): maps the extractor's
-// options (provider/model override + reasoningEffort) onto a real dsh-llm
-// stream route and retries once without the effort when the first attempt is
-// rejected. Extracted from apply() so the effort-fallback branch is
-// unit-testable; the extractor only ever sees a callLLM(messages, options)
-// => Promise<string>. The route always carries a real provider/model (dsh-llm
-// GenerateOptions requires both) — never a bare stream.
-export function createEntityStreamAdapter({ llm, agentDefaultModel, logger }) {
-  return async function streamEntityText(messages, options = {}) {
-    let route = {};
-    if (options.provider) route.provider = options.provider;
-    if (options.model) route.model = options.model;
-    if (!route.provider || !route.model) {
-      try {
-        const sel = agentDefaultModel?.currentSelection?.();
-        if (sel?.provider && sel?.model) {
-          route.provider ??= sel.provider;
-          route.model ??= sel.model;
-        }
-      } catch { /* fall through to whatever route we already have */ }
-    }
-    const effort = options.reasoningEffort;
-    const tryStream = (withEffort) => {
-      let text = "";
-      return (async () => {
-        for await (const chunk of llm.stream({
-          ...route,
-          maxTokens: 4096,
-          ...(withEffort && effort ? { reasoningEffort: effort } : {}),
-          messages
-        })) {
-          if (chunk.type === "text-delta" && typeof chunk.text === "string") text += chunk.text;
-          if (chunk.type === "finish" && (chunk.reason?.kind === "error" || chunk.reason?.kind === "aborted")) return undefined;
-        }
-        return text;
-      })().catch((err) => {
-        logger?.warn?.(`[dsh-mneme] entity extraction llm stream failed: ${String(err)}`);
-        return undefined;
-      });
-    };
-    let text = await tryStream(true);
-    if (text === undefined && effort) {
-      // Mirror dream's effort fallback: a provider rejecting the reasoning
-      // effort must not sink the whole extraction — retry once without it.
-      logger?.warn?.(`[dsh-mneme] entity extraction: reasoningEffort "${effort}" rejected, retrying without it`);
-      text = await tryStream(false);
-    }
-    return text;
-  };
-}
-
-/**
- * Issue #128: bounded backfill of rows still missing an embedding (active rows
- * only — needsEmbedding filters archived/forgotten). Exported for tests.
- *
- * Runs regardless of the model fingerprint: the old call-site gate returned
- * early when vector_meta already held the embedder's hash, permanently
- * orphaning rows whose embed failed at write time (embedder not ready /
- * provider rate limit) — one successful embed was enough to never backfill
- * again. markModel is idempotent when the fingerprint already matches, so
- * re-running costs nothing beyond the actually-missing rows.
- */
-export async function backfillMissingEmbeddings({
-  store, embedder, vectorIndex, logger,
-  maxTotal = 500, batchSize = 10, rateLimitMs = 200
-}) {
-  let indexed = 0;
-  for (let done = 0; done < maxTotal;) {
-    const rows = store.needsEmbedding(batchSize);
-    if (!rows.length) break;
-    for (const row of rows) {
-      try {
-        const text = [row.title, row.content].filter(Boolean).join("\n");
-        const vector = await embedder.embedSingle(text);
-        if (vector?.length) {
-          store.setEmbedding(row.id, vector);
-          indexed++;
-        }
-      } catch { /* skip the bad row */ }
-    }
-    done += rows.length;
-    // Rate limit: space out batches so the provider is not hammered.
-    if (store.needsEmbedding(1).length) await new Promise((r) => setTimeout(r, rateLimitMs));
-  }
-  if (indexed > 0 && embedder.modelHash) vectorIndex.markModel?.(embedder.modelHash, embedder.dimension);
-  logger?.info?.(`[dsh-mneme] auto-reindex backfilled ${indexed} embeddings on boot`);
-  return indexed;
-}
-
-export const apply = (ctx, config) => {
-  const rawCfg = Config(config);
-
-  // Resolve memoryDir: expand leading "~"
-  const memoryDir = rawCfg.memoryDir.startsWith("~")
-    ? join(homedir(), rawCfg.memoryDir.slice(1))
-    : rawCfg.memoryDir;
-  mkdirSync(memoryDir, { recursive: true });
-
-  const store = createStore(join(memoryDir, "memory.db"));
-  // Prune reflection failure rows older than 90 days on boot (best-effort, so
-  // the failure table never grows unbounded).
-  try {
-    store.deleteOldFailures(new Date(Date.now() - 90 * 86400000).toISOString());
-  } catch { /* non-fatal */ }
-  // Bug8: enforce llm_audit_logs retention on boot (config.llmAudit.retentionDays,
-  // default 90). Best-effort like the failure prune — the audit trail is
-  // bookkeeping and a failed purge must never block plugin boot.
-  try {
-    if (rawCfg.llmAudit?.enabled !== false) {
-      const retentionMs = Number.isInteger(rawCfg.llmAudit?.retentionDays) ? rawCfg.llmAudit.retentionDays : 90;
-      store.deleteOldLlmAudits(new Date(Date.now() - retentionMs * 86400000).toISOString());
-    }
-  } catch { /* non-fatal */ }
-
-  // User-configurable settings (profile, rules, panel mode, standalone API
-  // token) share the same SQLite file in dedicated tables, isolated from
-  // memories. Created before the config is finalized: the persisted
-  // panel_mode participates in light-mode resolution below.
-  const settings = createSettings(store.db);
-
-  // Light mode (v0.7.12): the bundle config flag OR a persisted panel_mode of
-  // "light" (the panel switch wins over the bundle config so it survives
-  // config redeploys). applyLightModePreset turns every heavy background /
-  // semantic feature off and keeps the core loop (autoInject, autoSummarize,
-  // hot memory, quality filter).
-  const lightMode = rawCfg.lightMode === true || settings.getPanelMode() === "light";
-  // 功能开关合并顺序即优先级：用户显式开关（feature_flags kv，面板写入）>
-  // 轻量预设（applyLightModePreset 批量置关的重型能力）> bundle 配置。预设必须
-  // 先应用、用户开关后展开，否则 LIGHT_MODE_OFF 会把用户显式打开的开关再次
-  // 压掉。合并结果只作用于本次启动：面板改开关后与 panel_mode 一样在下次
-  // 启动生效。
-  // 嵌套对象开关按首个点号拆开（kv 里平铺存的 "memoryQualityFilter.enabled" →
-  // cfg.memoryQualityFilter.enabled），点号键不原样留在 cfg 顶层属性里。
-  const flags = settings.getFeatureFlags();
-  const flatFlags = {};
-  const nestedFlags = {};
-  for (const [key, value] of Object.entries(flags)) {
-    const dot = key.indexOf(".");
-    if (dot > 0) {
-      const objKey = key.slice(0, dot);
-      const subKey = key.slice(dot + 1);
-      nestedFlags[objKey] = { ...(nestedFlags[objKey] ?? {}), [subKey]: value };
-    } else {
-      flatFlags[key] = value;
-    }
-  }
-  const cfg = { ...applyLightModePreset({ ...rawCfg, lightMode }), ...flatFlags };
-  for (const [objKey, sub] of Object.entries(nestedFlags)) {
-    cfg[objKey] = { ...(cfg[objKey] ?? {}), ...sub };
-  }
-
-  // 记忆语言（memory.language）：本实例逐层传入 inject / summarize / dream /
-  // sleep / mirror，多实例（如 agent preset 内挂载）互不影响。
-  const mirror = createMirror(memoryDir, langOf(cfg));
-  const service = createService({ store, mirror, config: cfg, logger: ctx.logger });
-
-  // F-NEW-03: if the mirror sync failed last run (persisted dirty state), retry
-  // a safe re-render at boot so a stale mirror converges without needing a
-  // business write. Bounded: single attempt; on failure dirty stays for the
-  // next boot. Never throws.
-  service.recoverMirror();
-
-  // Recall-layer receipt: when searchMemories runs with recordRecall=true, the
-  // retrieval scene (query/mode/topK/threshold + candidates) is persisted to
-  // recall_runs for audit/replay — the sibling of the dream_runs judgment trail.
-  // Best-effort: a failed recall write must never break the search.
-  service.setRecallRecorder((recall) => {
-    try {
-      store.saveRecallRun({
-        query: recall.query,
-        mode: recall.mode,
-        topK: recall.topK,
-        threshold: recall.threshold ?? null,
-        candidates: recall.candidates ?? [],
-        created_at: recall.createdAt
-      });
-    } catch { /* non-fatal: recall recording is bookkeeping */ }
-  });
-
-  // Semantic pipeline: a local/ollama embedder when configured, otherwise the
-  // legacy OpenAI-compatible embedder (settings-driven). The vector index wraps
-  // the store's embedding column and tracks the active model fingerprint. A
-  // slow embedder init (model download) never blocks plugin boot — failures
-  // degrade to keyword search.
-  const vectorIndex = createVectorIndex({ store, logger: ctx.logger });
-  service.setVectorIndex(vectorIndex);
-
-  // Human edits in mirror files win on every sync; merge them back first.
-  // TYPE_FILE maps each memory type to its mirror filename. Read every type's
-  // edits up front: mergeHumanEdits re-renders ALL mirror files on success, so
-  // a per-type read-then-merge loop would overwrite edits in files not yet read
-  // (e.g. preferences.md merging would clobber unsynced projects.md edits).
-  const humanEdits = new Map();
-  for (const type of Object.keys(TYPE_FILE)) {
-    humanEdits.set(type, mirror.readHumanEdits(type));
-  }
-  const applyHumanEdits = () => {
-    for (const [type, edits] of humanEdits) {
-      if (edits.length) service.mergeHumanEdits(type, edits);
-    }
-  };
-
-  let embedder = null;
-  let reranker = null;
-  // #118: pending embedder-init retry timer, cleared on unload.
-  let embedRetryTimer = null;
-  if (lightMode) {
-    // Light mode: the whole vector pipeline stays off — no embedder (nothing
-    // pulls in ONNX/transformers), no reranker, no boot backfill (the preset
-    // also cleared autoReindexOnBoot). Recall degrades to keyword search and
-    // human mirror edits still merge on boot.
-    applyHumanEdits();
-  } else if (cfg.embedProvider === "openai") {
-    // vectorIndex is passed so the legacy OpenAI embedder records the producing
-    // model fingerprint after each successful embed (Bug3).
-    embedder = createEmbedder({ store, settings, logger: ctx.logger, vectorIndex });
-    service.setEmbedder(embedder);
-    // issue #135: 未配置时明确告警一次。此前 legacy OpenAI embedder 恒报
-    // ready=true，向量层「绿的但全哑」可以静默存在很久（本机持续了数周）。
-    // 只记日志、不阻断启动：轻量模式与「先跑起来再补配置」都是正当用法。
-    if (embedder.configured === false) {
-      ctx.logger?.warn?.(
-        "[dsh-mneme] 向量层未配置（vector-config 的 enabled/baseUrl/apiKey/model 有缺）："
-        + "语义召回、语义去重、rerank、sleep 冲突检测将静默失效，"
-        + "dream 的语义聚类会退化为全量窗口兜底。"
-        + "请在设置面板补全 embedding 端点与模型，或把 embedProvider 改为 local/ollama。"
-      );
-    }
-    // legacy OpenAI embedder needs no async init → human edits apply right away
-    applyHumanEdits();
-  } else {
-    try {
-      embedder = createEmbedderByProvider(cfg.embedProvider, {
-        model: cfg.embedProvider === "ollama" ? cfg.ollamaModel : cfg.localEmbedModel,
-        dimension: cfg.localEmbedDimension,
-        device: cfg.localEmbedDevice,
-        batchSize: cfg.localEmbedBatchSize,
-        cacheDir: cfg.embedModelCacheDir,
-        runtimeDir: cfg.runtimeDir,
-        // #188：embedModelMirror 接成 transformers 的下载镜像（此前死配置）。
-        remoteHost: cfg.embedModelMirror,
-        resilientModelDownload: cfg.resilientModelDownload,
-        baseUrl: cfg.ollamaBaseUrl,
-        logger: ctx.logger
-      });
-      service.setEmbedder(embedder);
-      // issue #6: wait for extractor init before applying human edits, so
-      // scheduled embeddings see a ready embedder.
-      const bootEmbedder = () => embedder.init()
-        .then(() => { applyHumanEdits(); return true; })
-        .catch(() => false);
-      // #118: the old one-shot probe permanently degraded search to keyword
-      // when Ollama was briefly unreachable at boot (recoverable only by
-      // restart). Retry briefly (5 attempts total: 1 initial + 4 × 15s);
-      // search degrades to keyword meanwhile because per-query embed failures
-      // are swallowed.
-      bootEmbedder().then((ok) => {
-        if (ok) return;
-        let tries = 4;
-        const retry = () => {
-          if (tries-- <= 0) {
-            ctx.logger?.warn?.("[dsh-mneme] embedder init retries exhausted, search degrades to keyword");
-            service.setEmbedder(null);
-            applyHumanEdits();
-            return;
-          }
-          embedRetryTimer = setTimeout(async () => {
-            if (await bootEmbedder()) return;
-            retry();
-          }, 15_000);
-        };
-        ctx.logger?.warn?.("[dsh-mneme] embedder init failed, retrying");
-        retry();
-      });
-    } catch (error) {
-      ctx.logger?.warn?.(`[dsh-mneme] embedder unavailable, search degrades to keyword: ${String(error)}`);
-      applyHumanEdits();
-    }
-  }
-
-  // Cross-encoder rerank over recall candidates. Best-effort: a failed model
-  // load only disables reranking, never search itself. Explicit opt-in only
-  // (rerankEnabled defaults to false): constructing LocalReranker is what pulls
-  // in onnxruntime, so the default config never loads it (item ⑥).
-  if (cfg.rerankEnabled && cfg.rerankProvider === "local") {
-    try {
-      reranker = new LocalReranker({
-        model: cfg.rerankModel,
-        batchSize: cfg.rerankBatchSize,
-        maxCandidates: cfg.rerankMaxCandidates,
-        scoreThreshold: cfg.rerankScoreThreshold,
-        device: cfg.localEmbedDevice,
-        cacheDir: cfg.embedModelCacheDir,
-        runtimeDir: cfg.runtimeDir,
-        // #188：量化档默认 q8（此前不传 dtype 会去要 1GB 级 fp32 模型）；
-        // embedModelMirror 此前是死配置，现接成 transformers 的下载镜像。
-        useDtype: cfg.rerankDtype,
-        remoteHost: cfg.embedModelMirror,
-        resilientModelDownload: cfg.resilientModelDownload,
-        logger: ctx.logger
-      });
-      service.setReranker(reranker);
-      reranker.init().catch((error) => {
-        ctx.logger?.warn?.(`[dsh-mneme] reranker init failed, rerank disabled: ${String(error)}`);
-        service.setReranker(null);
-      });
-    } catch (error) {
-      ctx.logger?.warn?.(`[dsh-mneme] reranker unavailable, rerank disabled: ${String(error)}`);
-    }
-  }
-
-  // Bug2: lazy auto-backfill of missing embeddings on boot. When the vector API
-  // is configured and rows still lack an embedding (e.g. written before vector
-  // search was enabled), the backfill runs in the background after a short
-  // delay. Gated on cfg.autoReindexOnBoot; rate-limited in small batches so a
-  // large backlog never floods the provider. Failures degrade silently —
-  // search stays keyword.
-  function scheduleAutoReindex() {
-    if (cfg.autoReindexOnBoot === false) return;
-    const attempt = (tries) => {
-      try {
-        if (!embedder || typeof embedder.embedSingle !== "function") return;
-        if ("ready" in embedder && embedder.ready !== true) {
-          // Local/ollama embedders init asynchronously; give them a moment
-          // before giving up on this boot (next boot retries).
-          if (tries > 0) setTimeout(() => attempt(tries - 1), 2000);
-          return;
-        }
-        if (!store.needsEmbedding(1).length) return; // nothing to backfill
-        // Issue #128: no fingerprint gate here anymore — a matching fingerprint
-        // used to return early and permanently orphan rows whose embed failed
-        // at write time. See backfillMissingEmbeddings().
-        backfillMissingEmbeddings({ store, embedder, vectorIndex, logger: ctx.logger })
-          .catch((error) => {
-            ctx.logger?.warn?.(`[dsh-mneme] auto-reindex failed: ${String(error)}`);
-          });
-      } catch (error) {
-        ctx.logger?.warn?.(`[dsh-mneme] auto-reindex failed: ${String(error)}`);
-      }
-    };
-    setTimeout(() => attempt(5), 5000);
-  }
-  scheduleAutoReindex();
-
-  // Custom commands: register persisted commands into the DSH command registry
-  // on boot; add/remove re-register live through the API.
-  let commands = null;
-  if (ctx.commands) {
-    commands = createCommandManager({ ctx, settings, logger: ctx.logger, language: langOf(cfg) });
-    commands.sync();
-  }
-
-  // Dream scheduler: automatic consolidation + summary runs, triggered by
-  // store growth. Writes through the service fire the dream hook, which asks
-  // the scheduler to (re)schedule a run once absolute and since-last-run
-  // thresholds are both exceeded. onRun is deferred through `dream` so the
-  // closure sees the assigned scheduler; the null guard keeps a run safe even
-  // if the hook fires before assignment or after dispose.
-  let dream = null;
-  if (cfg.autoDream) {
-    dream = createDreamScheduler({
-      thresholdCount: cfg.dreamThresholdCount,
-      thresholdChars: cfg.dreamThresholdChars,
-      delayMs: cfg.dreamDelayMs,
-      minIntervalMs: (cfg.dreamMinIntervalMinutes ?? 0) * 60000,
-      logger: ctx.logger,
-      semantic: { embedder, vectorIndex },
-      onRun: () => (dream ? dream.runDream(ctx, service, cfg) : Promise.resolve({ ok: true, skipped: true }))
-    });
-    service.setDreamHook(() => dream.maybeSchedule(service));
-  }
-
-  // Sleep scheduler (v0.4.0): idle-triggered deep maintenance. Fires when the
-  // store has been quiet for sleepIdleMinutes and re-arms on every write via
-  // noteWrite (hooked to the service's write path). Runs go through
-  // service.enqueue so they serialize with autoDream — the two never overlap.
-  // Abortable on user activity; audited into dream_runs with run_type='sleep'.
-  let sleep = null;
-  if (cfg.sleepModeEnabled) {
-    sleep = createSleepScheduler({
-      service,
-      config: cfg,
-      logger: ctx.logger,
-      onRun: (signal) => (sleep ? runSleep(ctx, service, cfg, ctx.logger, { embedder, vectorIndex }, signal) : Promise.resolve({ ok: true, skipped: true }))
-    });
-    service.setSleepHook(() => sleep.noteWrite());
-  }
-
-  // Entity gene extraction (v0.3.0): wire the extractor into the service as a
-  // hook so saveWithDedupe can fire-and-forget an extraction pass on fresh
-  // writes. The service never sees ctx.llm — index.js adapts it here into the
-  // callLLM(messages, options) => Promise<string> contract the extractor
-  // expects, reusing the same ctx.llm.stream consumption pattern as dream.js.
-  // Explicit opt-in only (entityExtractionEnabled defaults to false); any LLM
-  // failure degrades inside the extractor to { ok:false }, never a write error.
-  if (cfg.entityExtractionEnabled) {
-    if (!ctx.llm) {
-      // Issue #108: an enabled-but-unwired extractor failed silently before —
-      // zero entities, zero llm_audit_logs, no log line anywhere. Make the
-      // missing dependency visible so a user can tell "extractor not installed"
-      // from "extraction failed".
-      ctx.logger?.warn?.("[dsh-mneme] entityExtractionEnabled=true but ctx.llm unavailable — entity extractor NOT installed");
-    } else {
-      const streamEntityText = createEntityStreamAdapter({
-        llm: ctx.llm,
-        agentDefaultModel: ctx.agentDefaultModel,
-        logger: ctx.logger
-      });
-      service.setEntityExtractor((memory) =>
-        extractEntities(memory, { store, config: cfg, callLLM: streamEntityText, logger: ctx.logger })
-          .catch((err) => {
-            ctx.logger?.warn?.(`[dsh-mneme] entity extraction failed: ${String(err)}`);
-            return { ok: false, error: String(err) };
-          })
-      );
-    }
-  }
-
-  const disposers = [];
-
-  // #118: never let a pending embedder init retry fire after unload and touch
-  // a torn-down context.
-  disposers.push(() => { if (embedRetryTimer !== null) clearTimeout(embedRetryTimer); });
-
-  ctx.inject(["systemPrompt"], (promptCtx) => {
-    if (cfg.autoInject) disposers.push(createInjector(promptCtx, service, settings, cfg));
-  });
-
-  ctx.inject(["tools"], (toolsCtx) => {
-    disposers.push(createTools(toolsCtx, service, cfg, embedder));
-  });
-
-  const summarizer = createSummarizer(ctx, service, cfg);
-  disposers.push(summarizer.dispose);
-
-  // webServer 可选依赖：cordis 4 的 ctx 是 Proxy，直接访问未在 inject 声明的
-  // 属性会抛 "cannot get property without inject"（不会返回 undefined），所以
-  // 不能用 if (ctx.webServer) 守卫。ctx.reflect.get 是 cordis 提供的免 inject
-  // 读取（未提供时返回 undefined）；对象字面量 mock ctx（测试）没有 reflect，
-  // 退回直接属性访问。headless/无 UI 宿主无 webServer 时跳过 API 注册，其余
-  // 功能（工具/注入/dream）照常。
-  const webServer = typeof ctx.reflect?.get === "function" ? ctx.reflect.get("webServer") : ctx.webServer;
-  if (webServer) {
-    const api = createApi(ctx, service, settings, commands ?? {
-      add: () => { throw new Error("commands unavailable"); },
-      remove: () => false,
-      list: () => []
-    }, embedder, { vectorIndex, reranker }, cfg.apiToken, cfg);
-    disposers.push(api.dispose);
-  }
-
-  // Standalone external API (v0.7.12): plain node:http server for ecosystem
-  // integrations outside the DSH host. Persisted external_api settings win
-  // over the bundle config (enabled/port); the Bearer token lives in the same
-  // kv and is auto-generated on first boot by createStandaloneApi. Binding a
-  // non-loopback host is the operator's documented responsibility.
-  if ((settings.getExternalApi?.()?.enabled ?? cfg.externalApiEnabled) === true) {
-    const standalone = createStandaloneApi({ service, store, config: cfg, logger: ctx.logger, settings });
-    disposers.push(() => standalone.server.close());
-    standalone.ready.catch((error) => {
-      ctx.logger?.warn?.(`[dsh-mneme] standalone API failed to start: ${String(error)}`);
-    });
-  }
-
-  // Async disposer: cordis awaits the returned promise on unload (runDisposable),
-  // so an in-flight dream run is allowed to finish before the SQLite store is
-  // closed — dream.dispose() resolves only after its current run settles.
-  return async () => {
-    for (const dispose of disposers) {
-      if (typeof dispose === "function") dispose();
-    }
-    commands?.dispose();
-    if (dream) await dream.dispose();
-    if (sleep) sleep.dispose();
-    store.close();
-  };
-};
+import { createStore } from "./store.js";
+import { createMirror, TYPE_FILE } from "./mirror.js";
+import { createService } from "./service.js";
+import { createTools } from "./tools.js";
+import { createInjector } from "./inject.js";
+import { createSummarizer } from "./summarize.js";
+import { createDreamScheduler } from "./dream.js";
+import { createSleepScheduler, runSleep } from "./dream/sleep.js";
+import { createApi } from "./api.js";
+import { createStandaloneApi } from "./api-standalone.js";
+import { createSettings } from "./settings.js";
+import { createCommandManager } from "./commands.js";
+import { createEmbedder } from "./embedding.js";
+import { createEmbedderByProvider } from "./local-embedder.js";
+import { LocalReranker } from "./reranker.js";
+import { createVectorIndex } from "./vector-index.js";
+import { Config, applyLightModePreset } from "./config.js";
+import { langOf } from "./lang.js";
+import { extractEntities } from "./entities/extractor.js";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+export const name = "dsh-mneme";
+// webServer 在 inject 声明中：cordis 会等宿主 webServer 服务激活后才 apply 本
+// 插件，保证 apply 时路由注册不落时序（v0.7.23 曾移出 inject 想支持 headless，
+// 结果 cordis 不再等待，apply 时宿主 webServer 未就绪 → 桌面端 "cannot get
+// property without inject" 崩溃）。守卫用 ctx.reflect.get（免 inject 读取，
+// 未提供返回 undefined）而非 if (ctx.webServer)：直接访问未注入属性在 cordis
+// Proxy 下会抛错而非返回 undefined。
+export const inject = ["tools", "systemPrompt", "llm", "agentDefaultModel", "commands", "webServer"];
+export { Config };
+
+// Arrow (not function declaration): cordis 4 treats any apply with a
+// prototype as a class constructor (`new apply(...)`) and discards its return
+// value, so a `function apply` disposer would never run on unload. An arrow
+// has no prototype, is called normally, and its returned disposer is collected
+// and run by the fiber on unload.
+// Entity-extraction LLM adapter (issue #108/#109): maps the extractor's
+// options (provider/model override + reasoningEffort) onto a real dsh-llm
+// stream route and retries once without the effort when the first attempt is
+// rejected. Extracted from apply() so the effort-fallback branch is
+// unit-testable; the extractor only ever sees a callLLM(messages, options)
+// => Promise<string>. The route always carries a real provider/model (dsh-llm
+// GenerateOptions requires both) — never a bare stream.
+export function createEntityStreamAdapter({ llm, agentDefaultModel, logger }) {
+  return async function streamEntityText(messages, options = {}) {
+    let route = {};
+    if (options.provider) route.provider = options.provider;
+    if (options.model) route.model = options.model;
+    if (!route.provider || !route.model) {
+      try {
+        const sel = agentDefaultModel?.currentSelection?.();
+        if (sel?.provider && sel?.model) {
+          route.provider ??= sel.provider;
+          route.model ??= sel.model;
+        }
+      } catch { /* fall through to whatever route we already have */ }
+    }
+    const effort = options.reasoningEffort;
+    const tryStream = (withEffort) => {
+      let text = "";
+      return (async () => {
+        for await (const chunk of llm.stream({
+          ...route,
+          maxTokens: 4096,
+          ...(withEffort && effort ? { reasoningEffort: effort } : {}),
+          messages
+        })) {
+          if (chunk.type === "text-delta" && typeof chunk.text === "string") text += chunk.text;
+          if (chunk.type === "finish" && (chunk.reason?.kind === "error" || chunk.reason?.kind === "aborted")) return undefined;
+        }
+        return text;
+      })().catch((err) => {
+        logger?.warn?.(`[dsh-mneme] entity extraction llm stream failed: ${String(err)}`);
+        return undefined;
+      });
+    };
+    let text = await tryStream(true);
+    if (text === undefined && effort) {
+      // Mirror dream's effort fallback: a provider rejecting the reasoning
+      // effort must not sink the whole extraction — retry once without it.
+      logger?.warn?.(`[dsh-mneme] entity extraction: reasoningEffort "${effort}" rejected, retrying without it`);
+      text = await tryStream(false);
+    }
+    return text;
+  };
+}
+
+/**
+ * Issue #128: bounded backfill of rows still missing an embedding (active rows
+ * only — needsEmbedding filters archived/forgotten). Exported for tests.
+ *
+ * Runs regardless of the model fingerprint: the old call-site gate returned
+ * early when vector_meta already held the embedder's hash, permanently
+ * orphaning rows whose embed failed at write time (embedder not ready /
+ * provider rate limit) — one successful embed was enough to never backfill
+ * again. markModel is idempotent when the fingerprint already matches, so
+ * re-running costs nothing beyond the actually-missing rows.
+ */
+export async function backfillMissingEmbeddings({
+  store, embedder, vectorIndex, logger,
+  maxTotal = 500, batchSize = 10, rateLimitMs = 200
+}) {
+  let indexed = 0;
+  for (let done = 0; done < maxTotal;) {
+    const rows = store.needsEmbedding(batchSize);
+    if (!rows.length) break;
+    for (const row of rows) {
+      try {
+        const text = [row.title, row.content].filter(Boolean).join("\n");
+        const vector = await embedder.embedSingle(text);
+        if (vector?.length) {
+          store.setEmbedding(row.id, vector);
+          indexed++;
+        }
+      } catch { /* skip the bad row */ }
+    }
+    done += rows.length;
+    // Rate limit: space out batches so the provider is not hammered.
+    if (store.needsEmbedding(1).length) await new Promise((r) => setTimeout(r, rateLimitMs));
+  }
+  if (indexed > 0 && embedder.modelHash) vectorIndex.markModel?.(embedder.modelHash, embedder.dimension);
+  logger?.info?.(`[dsh-mneme] auto-reindex backfilled ${indexed} embeddings on boot`);
+  return indexed;
+}
+
+export const apply = (ctx, config) => {
+  const rawCfg = Config(config);
+
+  // Resolve memoryDir: expand leading "~"
+  const memoryDir = rawCfg.memoryDir.startsWith("~")
+    ? join(homedir(), rawCfg.memoryDir.slice(1))
+    : rawCfg.memoryDir;
+  mkdirSync(memoryDir, { recursive: true });
+
+  const store = createStore(join(memoryDir, "memory.db"));
+  // Prune reflection failure rows older than 90 days on boot (best-effort, so
+  // the failure table never grows unbounded).
+  try {
+    store.deleteOldFailures(new Date(Date.now() - 90 * 86400000).toISOString());
+  } catch { /* non-fatal */ }
+  // Bug8: enforce llm_audit_logs retention on boot (config.llmAudit.retentionDays,
+  // default 90). Best-effort like the failure prune — the audit trail is
+  // bookkeeping and a failed purge must never block plugin boot.
+  try {
+    if (rawCfg.llmAudit?.enabled !== false) {
+      const retentionMs = Number.isInteger(rawCfg.llmAudit?.retentionDays) ? rawCfg.llmAudit.retentionDays : 90;
+      store.deleteOldLlmAudits(new Date(Date.now() - retentionMs * 86400000).toISOString());
+    }
+  } catch { /* non-fatal */ }
+
+  // User-configurable settings (profile, rules, panel mode, standalone API
+  // token) share the same SQLite file in dedicated tables, isolated from
+  // memories. Created before the config is finalized: the persisted
+  // panel_mode participates in light-mode resolution below.
+  const settings = createSettings(store.db);
+
+  // Light mode (v0.7.12): the bundle config flag OR a persisted panel_mode of
+  // "light" (the panel switch wins over the bundle config so it survives
+  // config redeploys). applyLightModePreset turns every heavy background /
+  // semantic feature off and keeps the core loop (autoInject, autoSummarize,
+  // hot memory, quality filter).
+  const lightMode = rawCfg.lightMode === true || settings.getPanelMode() === "light";
+  // 功能开关合并顺序即优先级：用户显式开关（feature_flags kv，面板写入）>
+  // 轻量预设（applyLightModePreset 批量置关的重型能力）> bundle 配置。预设必须
+  // 先应用、用户开关后展开，否则 LIGHT_MODE_OFF 会把用户显式打开的开关再次
+  // 压掉。合并结果只作用于本次启动：面板改开关后与 panel_mode 一样在下次
+  // 启动生效。
+  // 嵌套对象开关按首个点号拆开（kv 里平铺存的 "memoryQualityFilter.enabled" →
+  // cfg.memoryQualityFilter.enabled），点号键不原样留在 cfg 顶层属性里。
+  const flags = settings.getFeatureFlags();
+  const flatFlags = {};
+  const nestedFlags = {};
+  for (const [key, value] of Object.entries(flags)) {
+    const dot = key.indexOf(".");
+    if (dot > 0) {
+      const objKey = key.slice(0, dot);
+      const subKey = key.slice(dot + 1);
+      nestedFlags[objKey] = { ...(nestedFlags[objKey] ?? {}), [subKey]: value };
+    } else {
+      flatFlags[key] = value;
+    }
+  }
+  const cfg = { ...applyLightModePreset({ ...rawCfg, lightMode }), ...flatFlags };
+  for (const [objKey, sub] of Object.entries(nestedFlags)) {
+    cfg[objKey] = { ...(cfg[objKey] ?? {}), ...sub };
+  }
+
+  // 记忆语言（memory.language）：本实例逐层传入 inject / summarize / dream /
+  // sleep / mirror，多实例（如 agent preset 内挂载）互不影响。
+  const mirror = createMirror(memoryDir, langOf(cfg));
+  const service = createService({ store, mirror, config: cfg, logger: ctx.logger });
+
+  // F-NEW-03: if the mirror sync failed last run (persisted dirty state), retry
+  // a safe re-render at boot so a stale mirror converges without needing a
+  // business write. Bounded: single attempt; on failure dirty stays for the
+  // next boot. Never throws.
+  service.recoverMirror();
+
+  // Recall-layer receipt: when searchMemories runs with recordRecall=true, the
+  // retrieval scene (query/mode/topK/threshold + candidates) is persisted to
+  // recall_runs for audit/replay — the sibling of the dream_runs judgment trail.
+  // Best-effort: a failed recall write must never break the search.
+  service.setRecallRecorder((recall) => {
+    try {
+      store.saveRecallRun({
+        query: recall.query,
+        mode: recall.mode,
+        topK: recall.topK,
+        threshold: recall.threshold ?? null,
+        candidates: recall.candidates ?? [],
+        created_at: recall.createdAt
+      });
+    } catch { /* non-fatal: recall recording is bookkeeping */ }
+  });
+
+  // Semantic pipeline: a local/ollama embedder when configured, otherwise the
+  // legacy OpenAI-compatible embedder (settings-driven). The vector index wraps
+  // the store's embedding column and tracks the active model fingerprint. A
+  // slow embedder init (model download) never blocks plugin boot — failures
+  // degrade to keyword search.
+  const vectorIndex = createVectorIndex({ store, logger: ctx.logger });
+  service.setVectorIndex(vectorIndex);
+
+  // Human edits in mirror files win on every sync; merge them back first.
+  // TYPE_FILE maps each memory type to its mirror filename. Read every type's
+  // edits up front: mergeHumanEdits re-renders ALL mirror files on success, so
+  // a per-type read-then-merge loop would overwrite edits in files not yet read
+  // (e.g. preferences.md merging would clobber unsynced projects.md edits).
+  const humanEdits = new Map();
+  for (const type of Object.keys(TYPE_FILE)) {
+    humanEdits.set(type, mirror.readHumanEdits(type));
+  }
+  const applyHumanEdits = () => {
+    for (const [type, edits] of humanEdits) {
+      if (edits.length) service.mergeHumanEdits(type, edits);
+    }
+  };
+
+  let embedder = null;
+  let reranker = null;
+  // #118: pending embedder-init retry timer, cleared on unload.
+  let embedRetryTimer = null;
+  if (lightMode) {
+    // Light mode: the whole vector pipeline stays off — no embedder (nothing
+    // pulls in ONNX/transformers), no reranker, no boot backfill (the preset
+    // also cleared autoReindexOnBoot). Recall degrades to keyword search and
+    // human mirror edits still merge on boot.
+    applyHumanEdits();
+  } else if (cfg.embedProvider === "openai") {
+    // vectorIndex is passed so the legacy OpenAI embedder records the producing
+    // model fingerprint after each successful embed (Bug3).
+    embedder = createEmbedder({ store, settings, logger: ctx.logger, vectorIndex });
+    service.setEmbedder(embedder);
+    // issue #135: 未配置时明确告警一次。此前 legacy OpenAI embedder 恒报
+    // ready=true，向量层「绿的但全哑」可以静默存在很久（本机持续了数周）。
+    // 只记日志、不阻断启动：轻量模式与「先跑起来再补配置」都是正当用法。
+    if (embedder.configured === false) {
+      ctx.logger?.warn?.(
+        "[dsh-mneme] 向量层未配置（vector-config 的 enabled/baseUrl/apiKey/model 有缺）："
+        + "语义召回、语义去重、rerank、sleep 冲突检测将静默失效，"
+        + "dream 的语义聚类会退化为全量窗口兜底。"
+        + "请在设置面板补全 embedding 端点与模型，或把 embedProvider 改为 local/ollama。"
+      );
+    }
+    // legacy OpenAI embedder needs no async init → human edits apply right away
+    applyHumanEdits();
+  } else {
+    try {
+      embedder = createEmbedderByProvider(cfg.embedProvider, {
+        model: cfg.embedProvider === "ollama" ? cfg.ollamaModel : cfg.localEmbedModel,
+        dimension: cfg.localEmbedDimension,
+        device: cfg.localEmbedDevice,
+        batchSize: cfg.localEmbedBatchSize,
+        cacheDir: cfg.embedModelCacheDir,
+        runtimeDir: cfg.runtimeDir,
+        // #188：embedModelMirror 接成 transformers 的下载镜像（此前死配置）。
+        remoteHost: cfg.embedModelMirror,
+        resilientModelDownload: cfg.resilientModelDownload,
+        baseUrl: cfg.ollamaBaseUrl,
+        logger: ctx.logger
+      });
+      service.setEmbedder(embedder);
+      // issue #6: wait for extractor init before applying human edits, so
+      // scheduled embeddings see a ready embedder.
+      const bootEmbedder = () => embedder.init()
+        .then(() => { applyHumanEdits(); return true; })
+        .catch(() => false);
+      // #118: the old one-shot probe permanently degraded search to keyword
+      // when Ollama was briefly unreachable at boot (recoverable only by
+      // restart). Retry briefly (5 attempts total: 1 initial + 4 × 15s);
+      // search degrades to keyword meanwhile because per-query embed failures
+      // are swallowed.
+      bootEmbedder().then((ok) => {
+        if (ok) return;
+        let tries = 4;
+        const retry = () => {
+          if (tries-- <= 0) {
+            ctx.logger?.warn?.("[dsh-mneme] embedder init retries exhausted, search degrades to keyword");
+            service.setEmbedder(null);
+            applyHumanEdits();
+            return;
+          }
+          embedRetryTimer = setTimeout(async () => {
+            if (await bootEmbedder()) return;
+            retry();
+          }, 15_000);
+        };
+        ctx.logger?.warn?.("[dsh-mneme] embedder init failed, retrying");
+        retry();
+      });
+    } catch (error) {
+      ctx.logger?.warn?.(`[dsh-mneme] embedder unavailable, search degrades to keyword: ${String(error)}`);
+      applyHumanEdits();
+    }
+  }
+
+  // Cross-encoder rerank over recall candidates. Best-effort: a failed model
+  // load only disables reranking, never search itself. Explicit opt-in only
+  // (rerankEnabled defaults to false): constructing LocalReranker is what pulls
+  // in onnxruntime, so the default config never loads it (item ⑥).
+  if (cfg.rerankEnabled && cfg.rerankProvider === "local") {
+    try {
+      reranker = new LocalReranker({
+        model: cfg.rerankModel,
+        batchSize: cfg.rerankBatchSize,
+        maxCandidates: cfg.rerankMaxCandidates,
+        scoreThreshold: cfg.rerankScoreThreshold,
+        device: cfg.localEmbedDevice,
+        cacheDir: cfg.embedModelCacheDir,
+        runtimeDir: cfg.runtimeDir,
+        // #188：量化档默认 q8（此前不传 dtype 会去要 1GB 级 fp32 模型）；
+        // embedModelMirror 此前是死配置，现接成 transformers 的下载镜像。
+        useDtype: cfg.rerankDtype,
+        remoteHost: cfg.embedModelMirror,
+        resilientModelDownload: cfg.resilientModelDownload,
+        logger: ctx.logger
+      });
+      service.setReranker(reranker);
+      reranker.init().catch((error) => {
+        ctx.logger?.warn?.(`[dsh-mneme] reranker init failed, rerank disabled: ${String(error)}`);
+        service.setReranker(null);
+      });
+    } catch (error) {
+      ctx.logger?.warn?.(`[dsh-mneme] reranker unavailable, rerank disabled: ${String(error)}`);
+    }
+  }
+
+  // Bug2: lazy auto-backfill of missing embeddings on boot. When the vector API
+  // is configured and rows still lack an embedding (e.g. written before vector
+  // search was enabled), the backfill runs in the background after a short
+  // delay. Gated on cfg.autoReindexOnBoot; rate-limited in small batches so a
+  // large backlog never floods the provider. Failures degrade silently —
+  // search stays keyword.
+  function scheduleAutoReindex() {
+    if (cfg.autoReindexOnBoot === false) return;
+    const attempt = (tries) => {
+      try {
+        if (!embedder || typeof embedder.embedSingle !== "function") return;
+        if ("ready" in embedder && embedder.ready !== true) {
+          // Local/ollama embedders init asynchronously; give them a moment
+          // before giving up on this boot (next boot retries).
+          if (tries > 0) setTimeout(() => attempt(tries - 1), 2000);
+          return;
+        }
+        if (!store.needsEmbedding(1).length) return; // nothing to backfill
+        // Issue #128: no fingerprint gate here anymore — a matching fingerprint
+        // used to return early and permanently orphan rows whose embed failed
+        // at write time. See backfillMissingEmbeddings().
+        backfillMissingEmbeddings({ store, embedder, vectorIndex, logger: ctx.logger })
+          .catch((error) => {
+            ctx.logger?.warn?.(`[dsh-mneme] auto-reindex failed: ${String(error)}`);
+          });
+      } catch (error) {
+        ctx.logger?.warn?.(`[dsh-mneme] auto-reindex failed: ${String(error)}`);
+      }
+    };
+    setTimeout(() => attempt(5), 5000);
+  }
+  scheduleAutoReindex();
+
+  // Custom commands: register persisted commands into the DSH command registry
+  // on boot; add/remove re-register live through the API.
+  let commands = null;
+  if (ctx.commands) {
+    commands = createCommandManager({ ctx, settings, logger: ctx.logger, language: langOf(cfg) });
+    commands.sync();
+  }
+
+  // Dream scheduler: automatic consolidation + summary runs, triggered by
+  // store growth. Writes through the service fire the dream hook, which asks
+  // the scheduler to (re)schedule a run once absolute and since-last-run
+  // thresholds are both exceeded. onRun is deferred through `dream` so the
+  // closure sees the assigned scheduler; the null guard keeps a run safe even
+  // if the hook fires before assignment or after dispose.
+  let dream = null;
+  if (cfg.autoDream) {
+    dream = createDreamScheduler({
+      thresholdCount: cfg.dreamThresholdCount,
+      thresholdChars: cfg.dreamThresholdChars,
+      delayMs: cfg.dreamDelayMs,
+      minIntervalMs: (cfg.dreamMinIntervalMinutes ?? 0) * 60000,
+      logger: ctx.logger,
+      semantic: { embedder, vectorIndex },
+      onRun: () => (dream ? dream.runDream(ctx, service, cfg) : Promise.resolve({ ok: true, skipped: true }))
+    });
+    service.setDreamHook(() => dream.maybeSchedule(service));
+  }
+
+  // Sleep scheduler (v0.4.0): idle-triggered deep maintenance. Fires when the
+  // store has been quiet for sleepIdleMinutes and re-arms on every write via
+  // noteWrite (hooked to the service's write path). Runs go through
+  // service.enqueue so they serialize with autoDream — the two never overlap.
+  // Abortable on user activity; audited into dream_runs with run_type='sleep'.
+  let sleep = null;
+  if (cfg.sleepModeEnabled) {
+    sleep = createSleepScheduler({
+      service,
+      config: cfg,
+      logger: ctx.logger,
+      onRun: (signal) => (sleep ? runSleep(ctx, service, cfg, ctx.logger, { embedder, vectorIndex }, signal) : Promise.resolve({ ok: true, skipped: true }))
+    });
+    service.setSleepHook(() => sleep.noteWrite());
+  }
+
+  // Entity gene extraction (v0.3.0): wire the extractor into the service as a
+  // hook so saveWithDedupe can fire-and-forget an extraction pass on fresh
+  // writes. The service never sees ctx.llm — index.js adapts it here into the
+  // callLLM(messages, options) => Promise<string> contract the extractor
+  // expects, reusing the same ctx.llm.stream consumption pattern as dream.js.
+  // Explicit opt-in only (entityExtractionEnabled defaults to false); any LLM
+  // failure degrades inside the extractor to { ok:false }, never a write error.
+  if (cfg.entityExtractionEnabled) {
+    if (!ctx.llm) {
+      // Issue #108: an enabled-but-unwired extractor failed silently before —
+      // zero entities, zero llm_audit_logs, no log line anywhere. Make the
+      // missing dependency visible so a user can tell "extractor not installed"
+      // from "extraction failed".
+      ctx.logger?.warn?.("[dsh-mneme] entityExtractionEnabled=true but ctx.llm unavailable — entity extractor NOT installed");
+    } else {
+      const streamEntityText = createEntityStreamAdapter({
+        llm: ctx.llm,
+        agentDefaultModel: ctx.agentDefaultModel,
+        logger: ctx.logger
+      });
+      service.setEntityExtractor((memory) =>
+        extractEntities(memory, { store, config: cfg, callLLM: streamEntityText, logger: ctx.logger })
+          .catch((err) => {
+            ctx.logger?.warn?.(`[dsh-mneme] entity extraction failed: ${String(err)}`);
+            return { ok: false, error: String(err) };
+          })
+      );
+    }
+  }
+
+  const disposers = [];
+
+  // #118: never let a pending embedder init retry fire after unload and touch
+  // a torn-down context.
+  disposers.push(() => { if (embedRetryTimer !== null) clearTimeout(embedRetryTimer); });
+
+  ctx.inject(["systemPrompt"], (promptCtx) => {
+    if (cfg.autoInject) disposers.push(createInjector(promptCtx, service, settings, cfg));
+  });
+
+  ctx.inject(["tools"], (toolsCtx) => {
+    disposers.push(createTools(toolsCtx, service, cfg, embedder));
+  });
+
+  const summarizer = createSummarizer(ctx, service, cfg);
+  disposers.push(summarizer.dispose);
+
+  // webServer 可选依赖：cordis 4 的 ctx 是 Proxy，直接访问未在 inject 声明的
+  // 属性会抛 "cannot get property without inject"（不会返回 undefined），所以
+  // 不能用 if (ctx.webServer) 守卫。ctx.reflect.get 是 cordis 提供的免 inject
+  // 读取（未提供时返回 undefined）；对象字面量 mock ctx（测试）没有 reflect，
+  // 退回直接属性访问。headless/无 UI 宿主无 webServer 时跳过 API 注册，其余
+  // 功能（工具/注入/dream）照常。
+  const webServer = typeof ctx.reflect?.get === "function" ? ctx.reflect.get("webServer") : ctx.webServer;
+  if (webServer) {
+    const api = createApi(ctx, service, settings, commands ?? {
+      add: () => { throw new Error("commands unavailable"); },
+      remove: () => false,
+      list: () => []
+    }, embedder, { vectorIndex, reranker }, cfg.apiToken, cfg);
+    disposers.push(api.dispose);
+  }
+
+  // Standalone external API (v0.7.12): plain node:http server for ecosystem
+  // integrations outside the DSH host. Persisted external_api settings win
+  // over the bundle config (enabled/port); the Bearer token lives in the same
+  // kv and is auto-generated on first boot by createStandaloneApi. Binding a
+  // non-loopback host is the operator's documented responsibility.
+  if ((settings.getExternalApi?.()?.enabled ?? cfg.externalApiEnabled) === true) {
+    const standalone = createStandaloneApi({ service, store, config: cfg, logger: ctx.logger, settings });
+    disposers.push(() => standalone.server.close());
+    standalone.ready.catch((error) => {
+      ctx.logger?.warn?.(`[dsh-mneme] standalone API failed to start: ${String(error)}`);
+    });
+  }
+
+  // Async disposer: cordis awaits the returned promise on unload (runDisposable),
+  // so an in-flight dream run is allowed to finish before the SQLite store is
+  // closed — dream.dispose() resolves only after its current run settles.
+  return async () => {
+    for (const dispose of disposers) {
+      if (typeof dispose === "function") dispose();
+    }
+    commands?.dispose();
+    if (dream) await dream.dispose();
+    if (sleep) sleep.dispose();
+    store.close();
+  };
+};