dsh-engram 0.3.4 → 0.3.6

package/lib/store.js

@@ -1,7 +1,7 @@
 /**
  * dsh-engram: storage layer over DSH's own `ctx.storageDomain`.
  *
- * One domain `dsh_engram` (JSON unit `~/.dsh/storages/dsh_engram.json`) with three
+ * One domain `dsh_engram` (JSON unit `~/.dsh/storages/dsh_engram.json`) with four
  * tables:
  *   - `memories` — the memory pool (kinds: decision/error/procedure/fact/
  *     insight/handoff/task), with provenance, signal strength, hit counts,
@@ -22,6 +22,7 @@ import path from "node:path";
 import { defineDomain, domainTable } from "@deepseek-ai/dsh-storage-domain";
 import { hashText, byRecency, uuid, now, truncate as truncateText, bm25Rank, tokenize as tokenizeLocal, dedupeBySession } from "./util.js";
 import { deriveObservations } from "./obs.js";
+import { redactText } from "./redact.js";
 
 export const DOMAIN_VERSION = 1;
 
@@ -64,6 +65,14 @@ const MemorySchema = z.object({
   status: z.enum(["active", "archived"]).default("active"),
   /** Absolute TTL expiry (epoch ms), null = no expiry. */
   expiresAt: z.number().int().nullable().default(null),
+  /** Memory id this row supersedes (newer statement replaces older truth). */
+  supersedes: z.string().nullable().default(null),
+  /** Memory id this row directly contradicts (conflicting claim, keep both). */
+  contradicts: z.string().nullable().default(null),
+  /** Optional provenance source class: manual | session | report | upstream | handoff. */
+  source: z.string().nullable().default(null),
+  /** Optional trigger/condition under which this memory should be recalled. */
+  conditions: z.string().nullable().default(null),
 });
 
 const TaskSchema = z.object({
@@ -201,6 +210,72 @@ function repeatOverlap(previous, incoming) {
   return repeatOverlapRatio(previous, incoming) >= REPEAT_OVERLAP;
 }
 
+/**
+ * Validate a memory-to-memory supersedes/contradicts target: must be a real
+ * memory in the same workspace (fail loud on typos / cross-workspace refs).
+ */
+function validateRelationTarget(workspace, target, kind, memories) {
+  if (target === null || target === void 0 || target === "") return null;
+  const mem = memories.find((m) => m.id === target);
+  if (mem === void 0 || mem.workspace !== workspace) {
+    throw new EngramError("ENGRAM_INVALID_ARGS", `${kind} target memory "${target}" does not exist in this workspace`);
+  }
+  return target;
+}
+
+/** Build supersede/contradiction lookup maps from a memory pool (deterministic). */
+function memoryRelationMaps(pool) {
+  const supersededBy = new Map(); // target id -> newer row
+  const contradictedBy = new Map(); // target id -> rows[]
+  for (const m of pool) {
+    if (m.supersedes !== null && m.supersedes !== void 0) supersededBy.set(m.supersedes, m);
+    if (m.contradicts !== null && m.contradicts !== void 0) {
+      const list = contradictedBy.get(m.contradicts) ?? [];
+      list.push(m);
+      contradictedBy.set(m.contradicts, list);
+    }
+  }
+  return { supersededBy, contradictedBy };
+}
+
+/**
+ * Conservative replacement/negation cues that justify an auto-supersede edge.
+ * Kept explicit and small on purpose: a plain fact update must NOT silently
+ * stale-mark its sibling — only "replaced / switched / no longer / 改用 / 不再"
+ * style statements do.
+ */
+const SUPERSEDE_CUES = [
+  "supersedes", "replaces", "replaced", "deprecated", "no longer", "instead",
+  "switched", "migrated", "dropped", "removed",
+  "改用", "换成", "切换", "改为", "取代", "替代", "迁移", "废除", "弃用", "不再",
+];
+
+/**
+ * Deterministic auto-supersede candidate (config.autoSupersede, default OFF).
+ * Fires only when ALL hold:
+ *   - the new entry has a non-empty entity anchor,
+ *   - its text carries a replacement/negation cue (SUPERSEDE_CUES),
+ *   - an older ACTIVE memory shares that entity AND kind AND ≥1 token with it.
+ * The most recent such memory is superseded; already-superseded rows and
+ * cross-kind/entity rows are never picked. Zero LLM, conservative by design.
+ */
+function autoSupersedeCandidate(all, entry, text) {
+  const kind = entry.kind ?? "fact";
+  if (typeof entry.entity !== "string" || entry.entity.length === 0) return null;
+  const lowered = text.toLowerCase();
+  if (!SUPERSEDE_CUES.some((cue) => lowered.includes(cue))) return null;
+  const newTokens = new Set(tokenizeLocal(text));
+  let best = null;
+  for (const m of all) {
+    if (m.kind !== kind || m.entity !== entry.entity || m.status !== "active") continue;
+    if (m.supersedes !== null) continue;
+    const overlap = tokenizeLocal(m.text).some((t) => newTokens.has(t));
+    if (!overlap) continue;
+    if (best === null || (m.updatedAt ?? m.createdAt ?? 0) > (best.updatedAt ?? best.createdAt ?? 0)) best = m;
+  }
+  return best;
+}
+
 /** Identity validation (mirrors shipped defineDomain; fails loud at load). */
 export const engramDomainSpec = defineDomain({
   name: "dsh_engram",
@@ -290,7 +365,7 @@ export async function openEngramDomain(facility) {
      * is falsy) every workspace. Optional kind/status filters; `q` reuses the
      * deterministic recall scorer.
      */
-    searchMemories({ workspace, q, kind, status, limit = 100 } = {}) {
+    searchMemories({ workspace, q, kind, tag, status, limit = 100 } = {}) {
       const bounded = Math.max(1, Math.min(500, Math.trunc(limit) || 100));
       let pool = [...memories.entries()].map(([, m]) => m);
       if (workspace) pool = pool.filter((m) => m.workspace === workspace);
@@ -298,6 +373,7 @@ export async function openEngramDomain(facility) {
       // (GC archives expired memories; the archive view is their pointer).
       if (status !== "archived") pool = pool.filter(notExpiredNow);
       if (kind) pool = pool.filter((m) => m.kind === kind);
+      if (tag) pool = pool.filter((m) => (m.tags ?? []).includes(tag));
       if (status) pool = pool.filter((m) => m.status === status);
       if (q !== void 0 && String(q).trim().length > 0) {
         return bm25Rank(pool, String(q).trim(), bounded);
@@ -362,12 +438,19 @@ export async function openEngramDomain(facility) {
      * near-repeat of a past ERROR re-warms that entry (failure revival).
      */
     async storeMemory(entry, config) {
-      const text = String(entry.text).trim();
+      // Redact secrets before anything else: before the char cap, before the
+      // dedup hash, and before the revive overlap ratio — so sensitive text
+      // never lands in storage and two identical secrets collapse the same
+      // way as two identical plain texts.
+      const text = redactText(String(entry.text).trim());
       if (text.length === 0) throw new EngramError("ENGRAM_INVALID_ARGS", "memory text must not be empty");
       if ([...text].length > config.maxMemoryChars) {
         throw new EngramError("ENGRAM_CAP_EXCEEDED", `memory text is ${[...text].length} characters, over the cap of ${config.maxMemoryChars}`);
       }
-      const dup = allMemories(entry.workspace).find((m) => hashText(m.text) === hashText(text) && m.kind === (entry.kind ?? "fact"));
+      const all = allMemories(entry.workspace);
+      let supersedes = validateRelationTarget(entry.workspace, entry.supersedes ?? null, "supersedes", all);
+      const contradicts = validateRelationTarget(entry.workspace, entry.contradicts ?? null, "contradicts", all);
+      const dup = all.find((m) => hashText(m.text) === hashText(text) && m.kind === (entry.kind ?? "fact"));
       if (dup !== void 0) {
         // Repeat of the exact same failure is itself a signal: refresh recency
         // AND climb the hit counter (errors only) so the [ENGRAM] index can
@@ -396,6 +479,13 @@ export async function openEngramDomain(facility) {
       if (allMemories(entry.workspace).length >= config.maxMemoriesPerWorkspace) {
         throw new EngramError("ENGRAM_CAP_EXCEEDED", `workspace already holds ${config.maxMemoriesPerWorkspace} active memories (the cap)`);
       }
+      // Auto-supersede (config.autoSupersede, OFF by default): only when the
+      // writer did not name a target AND the hired heuristic fires (see
+      // autoSupersedeCandidate) — explicit supersedes always wins.
+      if (supersedes === null && config?.autoSupersede === true) {
+        const auto = autoSupersedeCandidate(all, entry, text);
+        if (auto !== null) supersedes = auto.id;
+      }
       const expiresAt =
         entry.expiresAt !== void 0 && entry.expiresAt !== null
           ? entry.expiresAt
@@ -418,6 +508,10 @@ export async function openEngramDomain(facility) {
         filePath: entry.filePath ?? null,
         signal: typeof entry.signal === "number" ? Math.max(0, Math.min(1, entry.signal)) : 0.5,
         status: "active",
+        supersedes,
+        contradicts,
+        source: entry.source ?? null,
+        conditions: entry.conditions ?? null,
         expiresAt,
       };
       await memories.put(stored.id, stored);
@@ -444,12 +538,81 @@ export async function openEngramDomain(facility) {
       const active = allMemories(workspace).filter(notExpiredNow);
       const bounded = Math.max(1, Math.min(50, Math.trunc(limit) || 20));
       if (query !== void 0 && String(query).trim().length > 0) {
+        const { supersededBy } = memoryRelationMaps(active);
         const ranked = bm25Rank(active, String(query).trim(), bounded);
-        if (maxPerSession === void 0 || maxPerSession === null) return ranked;
-        return dedupeBySession(ranked, maxPerSession); // 候选① per-session cap
+        // Superseded = stale truth: an active memory marked itself as replacing
+        // that row. Keep it re-fetchable, but never let it win the ranking —
+        // demote it to the tail so the current statement surfaces first.
+        const main = ranked.filter((m) => !supersededBy.has(m.id));
+        const stale = ranked.filter((m) => supersededBy.has(m.id));
+        const merged = main.concat(stale).slice(0, bounded);
+        if (maxPerSession === void 0 || maxPerSession === null) return merged;
+        return dedupeBySession(merged, maxPerSession); // 候选① per-session cap
       }
       return active.sort(byRecency).slice(0, bounded);
     },
+    /**
+     * Optional cross-workspace recall (issue #5, recallScope: "global").
+     * Ranks across EVERY workspace's active pool with the same deterministic
+     * BM25 scorer, then applies a small origin penalty so an out-of-workspace
+     * hit needs meaningfully stronger lexical relevance to displace an
+     * in-workspace one. Results are annotated with `_origin` (the workspace key)
+     * so the tools layer can surface a [W:<workspace>] marker — the model then
+     * knows the context a cross-workspace entry came from. Default strictly
+     * preserves per-workspace isolation; this is only invoked when the caller
+     * opts in (config recallScope="global" or an explicit scope="global" call).
+     */
+    recallGlobal(query, limit = 20, { maxPerSession, excludeWorkspace } = {}) {
+      const bounded = Math.max(1, Math.min(50, Math.trunc(limit) || 20));
+      let pool = [...memories.entries()].map(([, m]) => m).filter((m) => m.status === "active").filter(notExpiredNow);
+      if (excludeWorkspace !== void 0 && excludeWorkspace !== null) {
+        pool = pool.filter((m) => m.workspace !== excludeWorkspace);
+      }
+      if (pool.length === 0) return [];
+      // Tag every row with its origin workspace for the display layer.
+      const tagged = pool.map((m) => ({ ...m, _origin: m.workspace }));
+      const trimmed = String(query ?? "").trim();
+      const half = Math.max(1, bounded * 3);
+      let ranked;
+      if (trimmed.length === 0) {
+        ranked = tagged.sort(byRecency).slice(0, bounded);
+      } else {
+        ranked = bm25Rank(tagged, trimmed, half);
+      }
+      // Origin penalty: an out-of-workspace hit is discounted by 20% (a
+      // same-workspace entry with comparable relevance wins ties). bm25Rank
+      // drops its internal score, but the returned order is monotonic in it;
+      // we only re-stabilize near-equal neighbours so cross-workspace hits
+      // never displace an equally-relevant in-workspace one.
+      if (excludeWorkspace !== void 0 && excludeWorkspace !== null && ranked.length > 1) {
+        ranked = ranked.slice().sort((a, b) => {
+          const crossA = (a._origin ?? a.workspace) !== excludeWorkspace;
+          const crossB = (b._origin ?? b.workspace) !== excludeWorkspace;
+          if (crossA === crossB) return 0;
+          return crossA ? 1 : -1; // same-workspace first within ties
+        });
+      }
+      const out = [];
+      const seen = new Set();
+      for (const m of ranked) {
+        if (seen.has(m.id)) continue;
+        seen.add(m.id);
+        out.push(m);
+        if (out.length >= bounded) break;
+      }
+      if (maxPerSession !== void 0 && maxPerSession !== null) return dedupeBySession(out, maxPerSession);
+      return out;
+    },
+    /**
+     * Memory-to-memory relation lookup maps for a workspace (deterministic):
+     *   supersededBy: id -> { newer } (a row marked m.supersedes === id)
+     *   contradictedBy: id -> [ rows ] (rows marked m.contradicts === id)
+     * Built purely from the active pool; used by recall rendering and the
+     * [ENGRAM] index to surface "stale truth" honestly without deleting.
+     */
+    memoryRelations(workspace) {
+      return memoryRelationMaps(allMemories(workspace).filter(notExpiredNow));
+    },
     timeline(workspace, entity, limit = 30) {
       const active = allMemories(workspace).filter(notExpiredNow);
       const bounded = Math.max(1, Math.min(100, Math.trunc(limit) || 30));
@@ -468,6 +631,19 @@ export async function openEngramDomain(facility) {
       await memories.put(id, { ...m, status: "archived", updatedAt: now() });
       return true;
     },
+    /**
+     * Append a tag to an ACTIVE memory (idempotent; does NOT touch updatedAt,
+     * so a resolution annotation never re-ranks an error into recall).
+     * Used by the failure→fix closure to mark resolved errors. Zero LLM.
+     */
+    async tagMemory(workspace, id, tag) {
+      const m = memories.get(id);
+      if (m === void 0 || m.workspace !== workspace || m.status !== "active") return false;
+      if (typeof tag !== "string" || tag.length === 0) return true;
+      const tags = (m.tags ?? []).includes(tag) ? m.tags : [...(m.tags ?? []), tag];
+      await memories.put(id, { ...m, tags });
+      return true;
+    },
     /** Lazy TTL sweep (write path only; async). Returns archived count. */
     async expireSweep(workspace) {
       let n = 0;
@@ -853,6 +1029,235 @@ export async function openEngramDomain(facility) {
       await entities.delete(id);
       return true;
     },
+    // ── export / import (data contract, format "dsh-engram/export" v1) ─
+    /**
+     * Dump every row of the four memory tables — including archived memories /
+     * tasks — so a backup or migration never loses provenance. `workspace`
+     * restricts to one workspace; falsy dumps every workspace. The dump is the
+     * plain contract a consumer (or a future dsh release) can round-trip back
+     * through `importAll` — it carries `meta.format` + `meta.version` so
+     * forwards-incompatible formats can be rejected by the importer.
+     */
+    exportAll(workspace) {
+      const pick = (table) => [...table.entries()].map(([, v]) => v).filter((v) => v.workspace === workspace);
+      const all = workspace
+        ? { memories: pick(memories), tasks: pick(tasks), links: pick(links), entities: pick(entities) }
+        : {
+            memories: [...memories.entries()].map(([, v]) => v),
+            tasks: [...tasks.entries()].map(([, v]) => v),
+            links: [...links.entries()].map(([, v]) => v),
+            entities: [...entities.entries()].map(([, v]) => v),
+          };
+      return {
+        meta: { format: "dsh-engram/export", version: 1, exportedAt: now(), workspace: workspace ?? null },
+        ...all,
+      };
+    },
+    /**
+     * Restore a dump produced by `exportAll` (same format/version), honoring
+     * the same write-path invariants as `storeMemory`: memory text is run
+     * through the deterministic secret redactor before it can land on disk.
+     *
+     * Modes:
+     *   - `merge` (default) — idempotent: writes only rows whose id is absent,
+     *     kept per-row (each row keeps its own `workspace`).
+     *   - `replace` — wipes the given `workspace` from all four tables first,
+     *     then writes only rows belonging to it (a full restore; the caller
+     *     owns the destructive step).
+     *
+     * Bad rows never abort the whole import: structural/validation failures
+     * (missing id/workspace, empty text, text over the char cap, id already
+     * present in merge, workspace memory cap in merge) are skipped and listed
+     * in the report. `dryRun: true` computes the identical plan without
+     * writing a single row.
+     *
+     * @param payload - the dump (`{ meta?, memories?, tasks?, links?, entities? }`).
+     * @param opts - `{ mode, dryRun, workspace, config }` (workspace mandatory for replace).
+     * @returns { mode, dryRun, written: {table: n}, skipped: [{table,id,reason}] }
+     */
+    async importAll(payload, { mode = "merge", dryRun = false, workspace, config } = {}) {
+      if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+        throw new EngramError("ENGRAM_INVALID_ARGS", "import payload must be an object (a dsh-engram/export dump)");
+      }
+      if (mode !== "merge" && mode !== "replace") {
+        throw new EngramError("ENGRAM_INVALID_ARGS", "import mode must be 'merge' or 'replace'");
+      }
+      if (mode === "replace" && (typeof workspace !== "string" || workspace.length === 0)) {
+        throw new EngramError("ENGRAM_INVALID_ARGS", "replace mode requires the workspace to restore into");
+      }
+      const maxMemoryChars = config?.maxMemoryChars ?? 1600;
+      const maxPerWs = config?.maxMemoriesPerWorkspace ?? 2000;
+      const tables = {
+        memories: Array.isArray(payload.memories) ? payload.memories : [],
+        tasks: Array.isArray(payload.tasks) ? payload.tasks : [],
+        links: Array.isArray(payload.links) ? payload.links : [],
+        entities: Array.isArray(payload.entities) ? payload.entities : [],
+      };
+      const written = { memories: 0, tasks: 0, links: 0, entities: 0 };
+      const skipped = [];
+      const rowTable = (name) => ({ memories, tasks, links, entities })[name];
+      const rowsOf = (table, ws) => [...table.entries()].map(([, v]) => v).filter((v) => v.workspace === ws);
+
+      // Destructive mode: drop every row of the target workspace up front
+      // (planned under dryRun, executed otherwise).
+      if (mode === "replace") {
+        for (const [name, table] of Object.entries({ memories, tasks, links, entities })) {
+          for (const row of rowsOf(table, workspace)) {
+            if (!dryRun) await table.delete(row.id);
+          }
+        }
+      }
+
+      // Per-workspace running count of ACTIVE memories — the invariant the
+      // workspace cap protects (index-block size); archived rows never count,
+      // and the cap is per workspace, not global.
+      const activeByWs = new Map();
+      for (const [, m] of memories.entries()) {
+        if (m.status === "active") activeByWs.set(m.workspace, (activeByWs.get(m.workspace) ?? 0) + 1);
+      }
+
+      const putRow = async (name, key, row) => {
+        if (!dryRun) await rowTable(name).put(key, row);
+      };
+
+      // Schema defaults, mirroring storeMemory / the zod schemas: an imported
+      // row must behave exactly like one that went through the live write path
+      // (listMemories/recall only see status==="active", tasks need a state,
+      // etc.) — so absent optional fields get their canonical default, never
+      // `undefined`.
+      const normalizeMemory = (row, key, ws, text) => ({
+        kind: row.kind ?? "fact",
+        tags: Array.isArray(row.tags) ? row.tags.slice() : [],
+        entity: row.entity ?? null,
+        seq: Number.isFinite(row.seq) ? row.seq : 0,
+        ...row,
+        id: key,
+        workspace: ws,
+        text,
+        status: row.status ?? "active",
+        hits: Number.isFinite(row.hits) ? row.hits : 0,
+        lastAccessAt: row.lastAccessAt ?? null,
+        filePath: row.filePath ?? null,
+        signal: typeof row.signal === "number" ? row.signal : 0.5,
+        supersedes: row.supersedes ?? null,
+        contradicts: row.contradicts ?? null,
+        source: row.source ?? null,
+        conditions: row.conditions ?? null,
+        expiresAt: row.expiresAt ?? null,
+        sessionId: row.sessionId ?? "import",
+        createdAt: Number.isFinite(row.createdAt) ? row.createdAt : now(),
+        updatedAt: Number.isFinite(row.updatedAt) ? row.updatedAt : now(),
+      });
+      const normalizeTask = (row, key, ws) => ({
+        ...row,
+        id: key,
+        workspace: ws,
+        state: row.state ?? "draft",
+        artifact: row.artifact ?? null,
+        evaluation: row.evaluation ?? null,
+        memoryRefs: Array.isArray(row.memoryRefs) ? row.memoryRefs.slice() : [],
+        deps: Array.isArray(row.deps) ? row.deps.slice() : [],
+        assignee: row.assignee ?? null,
+        claimedAt: row.claimedAt ?? null,
+        stateChangedAt: Number.isFinite(row.stateChangedAt) ? row.stateChangedAt : 0,
+        archivedAt: row.archivedAt ?? null,
+        sessionId: row.sessionId ?? "import",
+        createdAt: Number.isFinite(row.createdAt) ? row.createdAt : now(),
+        updatedAt: Number.isFinite(row.updatedAt) ? row.updatedAt : now(),
+      });
+      const normalizeLink = (row, key, ws) => ({
+        ...row,
+        id: key,
+        workspace: ws,
+        relation: row.relation ?? "relates-to",
+        confidence: typeof row.confidence === "number" ? row.confidence : 1,
+        sessionId: row.sessionId ?? "import",
+        createdAt: Number.isFinite(row.createdAt) ? row.createdAt : now(),
+      });
+      const normalizeEntity = (row, key, ws) => ({
+        ...row,
+        id: key,
+        workspace: ws,
+        description: row.description ?? "",
+        kind: row.kind ?? "",
+        sessionId: row.sessionId ?? "import",
+        createdAt: Number.isFinite(row.createdAt) ? row.createdAt : now(),
+        updatedAt: Number.isFinite(row.updatedAt) ? row.updatedAt : now(),
+      });
+
+      for (const row of tables.memories) {
+        const key = typeof row?.id === "string" && row.id.length > 0 ? row.id : "";
+        const ws = typeof row?.workspace === "string" && row.workspace.length > 0 ? row.workspace : workspace;
+        if (key === "") {
+          skipped.push({ table: "memories", id: null, reason: "missing id" });
+          continue;
+        }
+        if (mode === "merge" && memories.get(key) !== void 0) {
+          skipped.push({ table: "memories", id: key, reason: "exists" });
+          continue;
+        }
+        if (typeof ws !== "string" || ws.length === 0) {
+          skipped.push({ table: "memories", id: key, reason: "missing workspace" });
+          continue;
+        }
+        if (mode === "replace" && ws !== workspace) {
+          skipped.push({ table: "memories", id: key, reason: "outside restored workspace" });
+          continue;
+        }
+        const text = redactText(String(row.text ?? "")).trim();
+        if (text.length === 0) {
+          skipped.push({ table: "memories", id: key, reason: "empty text" });
+          continue;
+        }
+        if ([...text].length > maxMemoryChars) {
+          skipped.push({ table: "memories", id: key, reason: "over maxMemoryChars" });
+          continue;
+        }
+        if (mode === "merge" && (row.status ?? "active") === "active" && (activeByWs.get(ws) ?? 0) >= maxPerWs) {
+          skipped.push({ table: "memories", id: key, reason: "workspace memory cap" });
+          continue;
+        }
+        if ((row.status ?? "active") === "active") activeByWs.set(ws, (activeByWs.get(ws) ?? 0) + 1);
+        try {
+          await putRow("memories", key, normalizeMemory(row, key, ws, text));
+          written.memories += 1;
+        } catch (error) {
+          skipped.push({ table: "memories", id: key, reason: `invalid row: ${String(error?.message ?? error)}` });
+        }
+      }
+
+      for (const [name, rows] of Object.entries({ tasks: tables.tasks, links: tables.links, entities: tables.entities })) {
+        for (const row of rows) {
+          const key = typeof row?.id === "string" && row.id.length > 0 ? row.id : "";
+          if (key === "") {
+            skipped.push({ table: name, id: null, reason: "missing id" });
+            continue;
+          }
+          if (mode === "merge" && rowTable(name).get(key) !== void 0) {
+            skipped.push({ table: name, id: key, reason: "exists" });
+            continue;
+          }
+          const ws = typeof row?.workspace === "string" && row.workspace.length > 0 ? row.workspace : workspace;
+          if (typeof ws !== "string" || ws.length === 0) {
+            skipped.push({ table: name, id: key, reason: "missing workspace" });
+            continue;
+          }
+          if (mode === "replace" && ws !== workspace) {
+            skipped.push({ table: name, id: key, reason: "outside restored workspace" });
+            continue;
+          }
+          const normalize = { tasks: normalizeTask, links: normalizeLink, entities: normalizeEntity }[name];
+          try {
+            await putRow(name, key, normalize(row, key, ws));
+            written[name] += 1;
+          } catch (error) {
+            skipped.push({ table: name, id: key, reason: `invalid row: ${String(error?.message ?? error)}` });
+          }
+        }
+      }
+
+      return { mode, dryRun, written, skipped };
+    },
     // ── usage / observability ────────────────────────────────────────
     /** Merge one tool-call event into the (workspace, day) rollup row. */
     async bumpUsage(workspace, day, { counts = {}, failures = 0, recall = {} }) {

package/lib/todo-sink.js

@@ -0,0 +1,146 @@
+/**
+ * dsh-engram: session-end todo auto-sink (audit follow-up).
+ *
+ * The todo plane (`todo_write`) is per-session working memory: last-write-wins,
+ * dies with the session. The promote hint (P0-A) and the GUI 「沉淀到 ESR」 button
+ * cover the INTENTIONAL path, but both only fire/run while the session is alive
+ * and the funnel is narrow — a session that ends with pending todos silently
+ * evaporates its plan (the observed "todo 一直建、esr 长期空" leak).
+ *
+ * This module closes that gap at the ONE safe boundary: `session/disposed`
+ * (the session's teardown edge). The trade-off from the design audit is kept
+ * intact:
+ *   - nothing is auto-written DURING the session — todo stays cheap/ephemeral
+ *     and the [ESR] prefix stays stable;
+ *   - the sink never pollutes the active list — landed tasks are `draft`
+ *     (excluded from [ESR] active rows by buildEsrSnapshot), deduped against
+ *     existing non-stable tasks by name, and capped by `maxTasksPerWorkspace`;
+ *   - a draft still needs the deliberate `esr_claim` / `esr_task` step to
+ *     become active, so the "committed work" obligation is never created
+ *     implicitly — the session plan becomes lossless, not obligated.
+ *
+ * All functions are pure / contained and unit-testable without the harness.
+ */
+
+import { pendingTodos } from "./trigger.js";
+import { shortId, uuid } from "./util.js";
+
+/** Description stamped on every auto-sunk draft (mirrors the GUI button's note). */
+export const SINK_DESCRIPTION = "源自会话计划（会话结束自动沉淀）";
+
+/**
+ * Extract the FINAL pending todo list from a session's event log: the last
+ * `todo/write` event (whole-list snapshot) filtered to unfinished items, in
+ * order. Returns [] when the session never wrote todos or everything is done.
+ * Deterministic — this is a pure function of the session log, so it survives
+ * process restarts (no reliance on the process-local recorder snapshot).
+ */
+export function pendingTodosFromSession(session) {
+  if (session === null || typeof session !== "object") return [];
+  const events = Array.isArray(session.events) ? session.events : [];
+  for (let i = events.length - 1; i >= 0; i--) {
+    const event = events[i];
+    if (event === null || typeof event !== "object" || event.type !== "todo/write") continue;
+    // Event data is the same { todos: TodoItem[] } shape todo_write args wear.
+    return pendingTodos(event.data);
+  }
+  return [];
+}
+
+/**
+ * Decide which pending todos should sink into ESR, and in what order. Pure:
+ *   - names already held by a non-stable task are skipped (dedupe — a task the
+ *     promote hint / GUI button already created is not re-created);
+ *   - within-list duplicates sink only once;
+ *   - the workspace cap (`maxTasksPerWorkspace`, counting drafts) is honoured:
+ *     once `activeCount + created` reaches `maxTasks`, the rest are reported as
+ *     `atCap` instead of created.
+ *
+ * @param {string[]} todos pending todo names, in plan order
+ * @param {Array<{name?: string}>} existingTasks non-stable tasks of the workspace
+ * @param {{ maxTasks?: number, activeCount?: number }} opts
+ * @returns {{ toCreate: string[], existed: string[], atCap: string[] }}
+ */
+export function planTodoSink(todos, existingTasks, opts = {}) {
+  const maxTasks = Number.isFinite(opts.maxTasks) && opts.maxTasks > 0 ? opts.maxTasks : 10;
+  const activeCount = opts.activeCount !== void 0
+    ? opts.activeCount
+    : (Array.isArray(existingTasks) ? existingTasks.length : 0);
+  const existing = new Set(
+    (Array.isArray(existingTasks) ? existingTasks : [])
+      .map((t) => String(t?.name ?? "").trim().toLowerCase())
+      .filter(Boolean),
+  );
+  const toCreate = [];
+  const existed = [];
+  const atCap = [];
+  const seen = new Set();
+  for (const todo of todos ?? []) {
+    const name = String(todo ?? "").trim().slice(0, 200);
+    if (name.length === 0) continue;
+    const key = name.toLowerCase();
+    if (seen.has(key)) continue; // within-list duplicate → single sink
+    seen.add(key);
+    if (existing.has(key)) {
+      existed.push(name);
+      continue;
+    }
+    if (activeCount + toCreate.length >= maxTasks) {
+      atCap.push(name);
+      continue;
+    }
+    toCreate.push(name);
+  }
+  return { toCreate, existed, atCap };
+}
+
+/**
+ * Sink a finished session's pending todos into ESR as DRAFT tasks. Best-effort,
+ * never throws into the caller — failures surface via the returned counts plus
+ * whatever the caller logs. Returns { created, existed, atCap } name lists.
+ *
+ * @param {object} domain the opened engram store domain (putTask/listTasks/activeTaskCount)
+ * @param {string} workspace normalized workspace key
+ * @param {string[]} todos pending todo names
+ * @param {{ sessionId?: string, maxTasks?: number, description?: string, now?: number }} opts
+ */
+export async function sinkPendingTodos(domain, workspace, todos, opts = {}) {
+  const record = { created: [], existed: [], atCap: [] };
+  if (!Array.isArray(todos) || todos.length === 0) return record;
+  if (domain === null || typeof domain !== "object" || typeof domain.putTask !== "function") return record;
+  const sessionId = opts.sessionId ?? "auto-sink";
+  const nowMs = typeof opts.now === "function" ? opts.now() : Number.isFinite(opts.now) ? opts.now : Date.now();
+  const existingTasks = typeof domain.listTasks === "function"
+    ? domain.listTasks(workspace, { includeStable: false })
+    : [];
+  const activeCount = typeof domain.activeTaskCount === "function"
+    ? domain.activeTaskCount(workspace)
+    : existingTasks.length;
+  const { toCreate, existed, atCap } = planTodoSink(todos, existingTasks, {
+    maxTasks: opts.maxTasks,
+    activeCount,
+  });
+  record.existed = existed;
+  record.atCap = atCap;
+  for (const name of toCreate) {
+    await domain.putTask({
+      id: `tsk_${shortId(uuid())}`,
+      workspace,
+      name,
+      description: opts.description ?? SINK_DESCRIPTION,
+      state: "draft",
+      artifact: null,
+      evaluation: null,
+      memoryRefs: [],
+      sessionId,
+      createdAt: nowMs,
+      updatedAt: nowMs,
+      stateChangedAt: 0,
+      deps: [],
+      assignee: null,
+      claimedAt: null,
+    });
+    record.created.push(name);
+  }
+  return record;
+}