@modusensus/dsh-mneme 0.4.1 → 0.4.3-beta.1

package/src/mirror.js

@@ -128,21 +128,33 @@ export function createMirror(dir) {
     for (const m of memories) {
       (byType[m.type] ??= []).push(m);
     }
+    // Per-type physical outcomes (audit peer D): a failed write for one type
+    // must not abort the whole render. Each type is written (or pruned) in its
+    // own try/catch and the result reported so the caller can persist per-type
+    // committed/failed receipts — a file that was already written is a real
+    // physical commit even when a sibling type errors.
+    const results = {};
     for (const type of Object.keys(TYPE_FILE)) {
-      const file = filePath(type);
-      const items = (byType[type] ?? [])
-        .slice()
-        .sort((a, b) => (a.updated_at < b.updated_at ? 1 : -1));
-      if (items.length === 0) {
-        // no memories of this type: drop any stale mirror file so deleted
-        // memories do not "resurrect" via readHumanEdits
-        rmSync(file, { force: true });
-        continue;
+      try {
+        const file = filePath(type);
+        const items = (byType[type] ?? [])
+          .slice()
+          .sort((a, b) => (a.updated_at < b.updated_at ? 1 : -1));
+        if (items.length === 0) {
+          // no memories of this type: drop any stale mirror file so deleted
+          // memories do not "resurrect" via readHumanEdits
+          rmSync(file, { force: true });
+        } else {
+          const header = `# ${TYPE_FILE[type]} — dsh-mneme 镜像\n\n<!-- 手工编辑此文件会被合并回记忆库（人工优先）。 -->\n\n`;
+          const body = items.map(renderMemory).join("\n");
+          writeFileSync(file, header + body, "utf8");
+        }
+        results[type] = { ok: true };
+      } catch (error) {
+        results[type] = { ok: false, error: error?.message ?? String(error) };
       }
-      const header = `# ${TYPE_FILE[type]} — dsh-mneme 镜像\n\n<!-- 手工编辑此文件会被合并回记忆库（人工优先）。 -->\n\n`;
-      const body = items.map(renderMemory).join("\n");
-      writeFileSync(file, header + body, "utf8");
     }
+    return results;
   }
 
   return { filePath, sync, readHumanEdits };

package/src/service.js

@@ -9,9 +9,9 @@ export function createService({ store, mirror, config, onWrite, logger }) {
   // passed in the constructor). Fired on the same write events as onWrite.
   let dreamHook = null;
 
-  // Optional sleep scheduler hook (v0.4.1), installed via setSleepHook after
-  // creation. Fired on the same write events: it tells the sleep scheduler the
-  // store just changed so the idle-detection clock resets.
+  // Optional sleep scheduler hook (v0.4.0), installed via setSleepHook after
+  // creation. Fired on the same write events as onWrite: it tells the sleep
+  // scheduler the store just changed so the idle-detection clock resets.
   let sleepHook = null;
 
   // Optional vector embedder, installed via setEmbedder after creation. After
@@ -42,7 +42,7 @@ export function createService({ store, mirror, config, onWrite, logger }) {
   // replays them exactly once against the committed state.
   let txDepth = 0;
 
-  // Serial task queue (sleep v0.4.1). Long-running background passes — dream
+  // Serial task queue (sleep v0.4.0). Long-running background passes — dream
   // consolidation, sleep cycles — must never overlap: two sleep runs racing
   // would double-demote or double-mint patterns. enqueue chains the task onto
   // a promise tail so N callers can queue work that runs strictly one at a
@@ -205,7 +205,9 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     for (const mem of keywordHits) {
       if (!merged.has(mem.id)) merged.set(mem.id, { ...mem, _source: "keyword", _score: 0.7 });
     }
-    return Array.from(merged.values()).sort((a, b) => b._score - a._score).slice(0, topK);
+    const hits = Array.from(merged.values()).sort((a, b) => b._score - a._score).slice(0, topK);
+    touchRecalled(hits);
+    return hits;
   }
 
   /**
@@ -223,7 +225,9 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     // store.findMemoriesByAttr —— 空 value 契约 = 返回该 attr_key 的全部
     // 当前有效记忆（v0.3.0，store.js 已实现）。
     const rows = store.findMemoriesByAttr(key, value ?? "");
-    return rows.slice(0, topK);
+    const hits = rows.slice(0, topK);
+    touchRecalled(hits);
+    return hits;
   }
 
   /**
@@ -253,6 +257,23 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     return base * (0.5 + (row.importance ?? 3) / 10);
   }
 
+  /**
+   * Sleep touch (v0.4.0): when sleep is enabled, any memory surfaced by recall
+   * or auto-injection gets its last_accessed_at bumped, so the "unrecalled N
+   * days → demote/archive" tiering counts real access. Best-effort and gated on
+   * config.sleepModeEnabled — when sleep is off this is a complete no-op (no
+   * writes on the hot recall path). A touch failure must never break search/inject.
+   */
+  function touchRecalled(memories) {
+    if (config?.sleepModeEnabled !== true || !Array.isArray(memories) || memories.length === 0) return;
+    for (const m of memories) {
+      if (!m?.id) continue;
+      try {
+        store.touchLastAccess(m.id);
+      } catch { /* touch is best effort */ }
+    }
+  }
+
   async function searchMemories(query, options = {}) {
     const { mode = "auto", topK = 20, threshold, useRerank = true, recordRecall = false } = options;
     const q = String(query ?? "").trim();
@@ -261,15 +282,11 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     // entity:/attr: 前缀路由（v0.3.0 Phase 3）。entitySearchEnabled 关闭时走原逻辑。
     if (config?.entitySearchEnabled) {
       if (q.startsWith("entity:")) {
-        const hits = searchByEntity(q.slice(7).trim(), options);
-        touchRecalled(hits);
-        return hits;
+        return searchByEntity(q.slice(7).trim(), options);
       }
       if (q.startsWith("attr:")) {
         const [key, value] = q.slice(5).split("=");
-        const hits = searchByAttr(key, value, options);
-        touchRecalled(hits);
-        return hits;
+        return searchByAttr(key, value, options);
       }
     }
 
@@ -456,23 +473,6 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     return { action: "created", memory: created };
   }
 
-  /**
-   * Sleep touch (v0.4.1): when sleep is enabled, any memory surfaced by recall
-   * or auto-injection gets its last_accessed_at bumped, so the "unrecalled N
-   * days → demote/archive" tiering counts real access. Best-effort and gated on
-   * config.sleepEnabled — when sleep is off this is a complete no-op (no writes
-   * on the hot recall path). A touch failure must never break search/inject.
-   */
-  function touchRecalled(memories) {
-    if (config?.sleepEnabled !== true || !Array.isArray(memories) || memories.length === 0) return;
-    for (const m of memories) {
-      if (!m?.id) continue;
-      try {
-        store.touchAccess(m.id);
-      } catch { /* touch is best effort */ }
-    }
-  }
-
   /**
    * Candidate memories for automatic context injection:
    * summaries first, then all preferences, then non-forgotten items with
@@ -648,26 +648,53 @@ export function createService({ store, mirror, config, onWrite, logger }) {
         }
       }
 
-      // 全量渲染
-      mirror.sync(reconcileHumanEdits(list));
-
-      // 成功：CAS/fence 绑定到本地 gen，旧 worker（gen 已过期）会被拦截。
-      // 此步失败说明核心 clean 状态没写成功，向上层报失败（不再静默）。
-      try {
-        store.markMirrorCleanForGeneration(gen, now);
-      } catch (stateError) {
-        logger?.warn?.("syncMirror: markMirrorCleanForGeneration failed:", stateError);
-        return { success: false, error: stateError?.message ?? String(stateError) };
+      // Per-type physical outcome (audit peer D): mirror.sync writes each type
+      // file independently and reports per-type success/failure. A type whose
+      // file was physically committed must be marked committed even when a
+      // sibling type errors — the old code batch-failed every type on any error,
+      // leaving committed files mislabeled as failed and masking partial state.
+      // Absent entries (a type with no memories) count as success: sync prunes
+      // the stale file, which is itself a completed physical state.
+      let allOk = true;
+      const results = mirror.sync(reconcileHumanEdits(list)) ?? {};
+      for (const type of Object.keys(TYPE_FILE)) {
+        const r = results[type];
+        const ok = !r || r.ok === true;
+        if (!ok) allOk = false;
+        try {
+          if (ok) {
+            store.setTypeStatus(type, { status: "committed", applied_gen: gen, last_error: null });
+          } else {
+            store.setTypeStatus(type, { status: "failed", last_error: r.error ?? "mirror sync failed" });
+          }
+        } catch (stateError) {
+          logger?.warn?.(`syncMirror: setTypeStatus(${type}) failed:`, stateError);
+        }
       }
-      // 逐 type 标记为 committed（peer blocker 4: per-type receipt）
-      for (const type of coveredTypes) {
+
+      // 全部 type 物理收敛：CAS/fence 绑定到本地 gen，旧 worker（gen 已过期）会被
+      // 拦截。此步失败说明核心 clean 状态没写成功，向上层报失败（不再静默）。
+      if (allOk) {
         try {
-          store.setTypeStatus(type, { status: "committed", applied_gen: gen, last_error: null });
+          store.markMirrorCleanForGeneration(gen, now);
         } catch (stateError) {
-          logger?.warn?.(`syncMirror: setTypeStatus(${type}) committed failed:`, stateError);
+          logger?.warn?.("syncMirror: markMirrorCleanForGeneration failed:", stateError);
+          return { success: false, error: stateError?.message ?? String(stateError) };
         }
+        return { success: true };
+      }
+
+      // 部分 type 失败：持久 dirty（债务绑定到新轮次），下次 recover 只补未收敛
+      // 的 type。committed 的 type 已应用本轮 gen，不因兄弟失败被回滚。
+      const failedTypes = Object.entries(results)
+        .filter(([, r]) => r && r.ok === false)
+        .map(([t]) => t);
+      try {
+        store.markMirrorDirty(`mirror sync failed for: ${failedTypes.join(", ")}`, now);
+      } catch (stateError) {
+        logger?.warn?.("syncMirror: markMirrorDirty failed:", stateError);
       }
-      return { success: true };
+      return { success: false, error: `mirror sync failed for: ${failedTypes.join(", ")}` };
     } catch (error) {
       const errMsg = error?.message ?? String(error);
       logger?.warn?.("syncMirror failed:", error);
@@ -691,14 +718,17 @@ export function createService({ store, mirror, config, onWrite, logger }) {
   }
 
   // afterSync: run syncMirror and surface a failure to the operator instead of
-  // swallowing it (peer blocker 2). The mirror debt has already been persisted
-  // by markMirrorDirty inside syncMirror, so a restart recovers — but the
-  // calling write path must not report clean while the mirror is known-stale.
+  // swallowing it (peer blocker 2 + audit peer B). The mirror debt has already
+  // been persisted by markMirrorDirty inside syncMirror, so a restart recovers —
+  // but the calling write path must not report clean while the mirror is
+  // known-stale. Returns the sync result so the caller can attach an explicit
+  // degraded/pending receipt to its return value instead of faking success.
   function afterSync(label) {
     const r = syncMirror();
     if (!r?.success && !r?.deferred) {
       logger?.warn?.(`${label}: mirror sync failed (will recover on restart):`, r?.error);
     }
+    return r;
   }
 
   // recoverMirror: 启动/手动 reconcile 时根据持久 dirty 状态决定是否恢复同步
@@ -873,9 +903,20 @@ export function createService({ store, mirror, config, onWrite, logger }) {
           memory_id: id
         });
       }
-      afterSync("write");
+      const sync = afterSync("write");
       notifyWrite();
       scheduleEmbed(updated);
+      // Audit peer B: when the mirror sync failed, the store write landed but
+      // the mirror did not converge — return an explicit degraded receipt rather
+      // than a plain success. Non-enumerable so existing deepEqual assertions on
+      // the memory shape keep passing.
+      if (!sync?.success && !sync?.deferred) {
+        Object.defineProperty(updated, "_mirror", {
+          value: { status: "degraded", error: sync?.error ?? "mirror sync failed" },
+          enumerable: false,
+          configurable: true
+        });
+      }
       return updated;
     },
     // Compare-and-set update: applies the patch only when the row still carries
@@ -902,9 +943,17 @@ export function createService({ store, mirror, config, onWrite, logger }) {
           memory_id: id
         });
       }
-      afterSync("write");
+      const sync = afterSync("write");
       notifyWrite();
       scheduleEmbed(updated);
+      // Audit peer B: mirror sync failure on a CAS write must surface too.
+      if (!sync?.success && !sync?.deferred) {
+        Object.defineProperty(updated, "_mirror", {
+          value: { status: "degraded", error: sync?.error ?? "mirror sync failed" },
+          enumerable: false,
+          configurable: true
+        });
+      }
       return updated;
     },
     setForget: (id, f) => {
@@ -917,11 +966,22 @@ export function createService({ store, mirror, config, onWrite, logger }) {
       afterSync("write");
       return updated;
     },
+    // sleep-mode storage (v0.4.0). demoteToSummary / restoreContent mutate
+    // content so they ride the normal write-hook path (mirror re-renders).
+    // touchLastAccess is a read-stamp — deliberately NO write hook (a recall
+    // must not dirty the mirror). getUnrecalledSince is a pure read.
     demoteToSummary: (id, summary, opts) => {
       const updated = store.demoteToSummary(id, summary, opts);
       afterSync("write");
       return updated;
     },
+    restoreContent: (id) => {
+      const updated = store.restoreContent(id);
+      afterSync("write");
+      return updated;
+    },
+    touchLastAccess: (id, at) => store.touchLastAccess(id, at),
+    getUnrecalledSince: (cutMs, opts) => store.getUnrecalledSince(cutMs, opts),
     // autoDream audit trail: passthroughs deliberately bypass write hooks —
     // an audit write is bookkeeping, and notifyWrite would loop back into the
     // dream scheduler that just recorded the run.
@@ -944,6 +1004,12 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     // migrates entity_attrs on merge. Bookkeeping writes like the audit
     // passthroughs above — never write-hook-triggering memory mutations.
     saveRelation: (r) => store.saveRelation(r),
+    listEntities: (o) => store.listEntities(o),
+    getRelations: (id) => store.getRelations(id),
+    saveAttr: (r) => store.saveAttr(r),
+    createEntity: (r) => store.createEntity(r),
+    findEntityByName: (n) => store.findEntityByName(n),
+    findEntityById: (id) => store.findEntityById(id),
     getAttrsByMemory: (id) => store.getAttrsByMemory(id),
     migrateAttrsToMemory: (fromId, toId, now) => store.migrateAttrsToMemory(fromId, toId, now)
   };

package/src/store.js

@@ -13,6 +13,8 @@ CREATE TABLE IF NOT EXISTS memories (
   archived    INTEGER NOT NULL DEFAULT 0,
   source      TEXT,
   embedding   TEXT,
+  last_accessed_at  TEXT,
+  _full_content     TEXT,
   created_at  TEXT NOT NULL,
   updated_at  TEXT NOT NULL
 );
@@ -38,7 +40,8 @@ CREATE TABLE IF NOT EXISTS dream_runs (
   applied        INTEGER NOT NULL DEFAULT 0,
   summary_stored INTEGER NOT NULL DEFAULT 0,
   receipt        TEXT NOT NULL,
-  policy_epoch   INTEGER NOT NULL DEFAULT 0  -- 裁决规则版本：规则升级后旧裁决降级为历史证据
+  policy_epoch   INTEGER NOT NULL DEFAULT 0,  -- 裁决规则版本：规则升级后旧裁决降级为历史证据
+  run_type       TEXT NOT NULL DEFAULT 'auto'  -- auto | sleep：睡眠周期的审计区分
 );
 CREATE INDEX IF NOT EXISTS idx_dream_runs_created ON dream_runs(created_at);
 
@@ -180,8 +183,8 @@ CREATE TABLE IF NOT EXISTS mirror_state (
   last_error TEXT,                   -- 最近失败原因
   last_attempt TEXT,                 -- 最近尝试时间（ISO）
   success_at TEXT,                   -- 最近成功时间（ISO）
-  generation INTEGER NOT NULL DEFAULT 0 CHECK (generation >= 0 AND generation <= 9007199254740991),         -- 期望的同步轮次（desired）
-  applied_generation INTEGER NOT NULL DEFAULT 0 CHECK (applied_generation >= 0 AND applied_generation <= 9007199254740991), -- 已成功应用的轮次
+  generation INTEGER NOT NULL DEFAULT 0 CHECK (generation >= 0 AND generation <= 9007199254740991 AND generation = CAST(generation AS INTEGER)),         -- 期望的同步轮次（desired）
+  applied_generation INTEGER NOT NULL DEFAULT 0 CHECK (applied_generation >= 0 AND applied_generation <= 9007199254740991 AND applied_generation = CAST(applied_generation AS INTEGER)), -- 已成功应用的轮次
   type_status TEXT                               -- JSON: 逐 type 状态 {type: {dirty, applied_gen, last_error}}
 );
 `;
@@ -228,9 +231,6 @@ function toRow(row) {
     source: row.source ?? undefined,
     created_at: row.created_at,
     updated_at: row.updated_at,
-    // Sleep (v0.4.1): last_accessed_at drives the unrecalled tiering;
-    // _full_content holds the pre-demotion body for a memory reduced to its
-    // summary. Both are internal — the mirror render must not expose them.
     last_accessed_at: row.last_accessed_at ?? undefined,
     _full_content: row._full_content ?? undefined
   };
@@ -397,11 +397,14 @@ function parseJsonArray(raw) {
 
 export function createStore(path) {
   const db = new DatabaseSync(path);
-  db.exec("PRAGMA journal_mode = WAL;");
-  // Concurrent writers (peer probe: 8 independent processes) must wait for the
-  // write lock instead of failing immediately with SQLITE_BUSY — otherwise the
-  // atomic generation increment loses whole writes, not just increments.
+  // Set busy_timeout BEFORE the journal-mode switch (audit peer: 8-process WAL
+  // init). Switching a fresh DB to WAL takes an exclusive lock; when several
+  // processes open the same path simultaneously, that lock can fail with
+  // SQLITE_BUSY before the timeout is armed. With the timeout installed first,
+  // the WAL transition (and every later write) blocks and retries instead of
+  // failing outright, so concurrent init converges to a stable 447/447.
   db.exec("PRAGMA busy_timeout = 5000;");
+  db.exec("PRAGMA journal_mode = WAL;");
   db.exec(SCHEMA);
 
   // Schema migrations for legacy databases (idempotent).
@@ -412,6 +415,12 @@ export function createStore(path) {
   if (!columns.includes("embedding")) {
     db.exec("ALTER TABLE memories ADD COLUMN embedding TEXT");
   }
+  if (!columns.includes("last_accessed_at")) {
+    db.exec("ALTER TABLE memories ADD COLUMN last_accessed_at TEXT");
+  }
+  if (!columns.includes("_full_content")) {
+    db.exec("ALTER TABLE memories ADD COLUMN _full_content TEXT");
+  }
 
   // Legacy dream_runs without policy_epoch → backfill with the default epoch.
   const dreamCols = db.prepare("PRAGMA table_info(dream_runs)").all().map((c) => c.name);
@@ -422,16 +431,6 @@ export function createStore(path) {
     db.exec("ALTER TABLE dream_runs ADD COLUMN run_type TEXT NOT NULL DEFAULT 'auto'");
   }
 
-  // Sleep (v0.4.1) columns: last_accessed_at tracks recall/inject touch for the
-  // "unrecalled N days → demote/archive" tiering; _full_content holds the pre-demotion
-  // body when a memory is reduced to its summary. Both are additive-only.
-  if (!columns.includes("last_accessed_at")) {
-    db.exec("ALTER TABLE memories ADD COLUMN last_accessed_at TEXT");
-  }
-  if (!columns.includes("_full_content")) {
-    db.exec("ALTER TABLE memories ADD COLUMN _full_content TEXT");
-  }
-
   // Legacy mirror_state without v0.3.6 generation columns → add each missing
   // column idempotently (old DBs open cleanly, no data loss).
   const mirrorCols = db.prepare("PRAGMA table_info(mirror_state)").all().map((c) => c.name);
@@ -445,6 +444,24 @@ export function createStore(path) {
     db.exec("ALTER TABLE mirror_state ADD COLUMN type_status TEXT");
   }
 
+  // Audit peer F: a legacy DB may hold a non-integer generation/applied_generation
+  // (pre-v0.3.9 the JS gate truncated with Math.trunc and SQLite's CHECK only
+  // enforced >= 0). Such a value is ambiguous — it cannot map to a real applied
+  // round — so surface it as a hard error on open instead of silently reading it
+  // as a coherent generation. Fail-closed: the operator must repair or reset the
+  // state row rather than continue with a lie.
+  for (const col of ["generation", "applied_generation"]) {
+    const bad = db.prepare(
+      `SELECT id FROM mirror_state WHERE ${col} IS NOT NULL AND ${col} != CAST(${col} AS INTEGER) LIMIT 1`
+    ).get();
+    if (bad) {
+      throw new RangeError(
+        `mirror_state.${col} holds a non-integer value (legacy dirty state); ` +
+        `repair or reset the row before opening this database`
+      );
+    }
+  }
+
   // Per-instance monotonic timestamp guard: consecutive writes within the same
   // millisecond must still produce strictly increasing timestamps (test asserts
   // updated_at != created_at). State lives in the store closure, not module scope.
@@ -571,24 +588,35 @@ export function createStore(path) {
     const embedding = patch.embedding !== undefined
       ? (Array.isArray(patch.embedding) && patch.embedding.length ? JSON.stringify(patch.embedding) : null)
       : existing.embedding ?? null;
-    const result = db.prepare(
-      `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, embedding=?, updated_at=?
-       WHERE id=? AND updated_at=?`
-    ).run(
-      type,
-      patch.title ?? existing.title,
-      patch.content ?? existing.content,
-      JSON.stringify(patch.tags ?? existing.tags),
-      Number.isInteger(patch.importance) ? patch.importance : existing.importance,
-      patch.source !== undefined ? patch.source : (existing.source ?? null),
-      embedding,
-      now,
-      id,
-      expectedUpdatedAt
-    );
-    if (result.changes === 0) return undefined; // CAS miss: a concurrent write won
-    // Only bump desired generation on a successful CAS — a miss writes nothing.
-    runAtomically(() => { incrementGeneration(); });
+    // The CAS UPDATE and the desired-generation bump must commit together (audit
+    // peer A): if the UPDATE autocommits first and the process dies before the
+    // increment, the store is mutated while generation == applied_generation and
+    // dirty == false — recoverMirror sees no debt and the mirror stays stale.
+    // Wrapping both in one transaction means a CAS miss rolls back cleanly too
+    // (no write, no generation bump).
+    let applied = false;
+    runAtomically(() => {
+      const result = db.prepare(
+        `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, embedding=?, updated_at=?
+         WHERE id=? AND updated_at=?`
+      ).run(
+        type,
+        patch.title ?? existing.title,
+        patch.content ?? existing.content,
+        JSON.stringify(patch.tags ?? existing.tags),
+        Number.isInteger(patch.importance) ? patch.importance : existing.importance,
+        patch.source !== undefined ? patch.source : (existing.source ?? null),
+        embedding,
+        now,
+        id,
+        expectedUpdatedAt
+      );
+      if (result.changes === 0) return; // CAS miss: a concurrent write won
+      // Only bump desired generation on a successful CAS — a miss writes nothing.
+      incrementGeneration();
+      applied = true;
+    });
+    if (!applied) return undefined;
     return getById(id);
   }
 
@@ -610,46 +638,67 @@ export function createStore(path) {
     return getById(id);
   }
 
-  /** Recall/inject touch. Records last_accessed_at WITHOUT bumping the mirror
-   *  generation — sleep's "unrecalled N days → demote/archive" tiering must not
-   *  spin the desired generation (that would mislead the mirror peer into
-   *  thinking the touched memory's content changed). Only bumps a timestamp,
-   *  so it is safe on hot recall paths. */
-  function touchAccess(id) {
-    const result = db.prepare(
-      "UPDATE memories SET last_accessed_at = ? WHERE id = ?"
-    ).run(nowIso(), id);
-    return result.changes > 0;
-  }
-
-  /** Sleep demotion (v0.4.1): move the full body into _full_content and replace
-   *  content with a one-line summary. Skips when already demoted (_full_content
-   *  present) so a replayed sleep run never double-wraps. Bumps the mirror
-   *  generation because content visibly changes in the mirror file.
-   *
-   *  minRefTimeMs (optional): the sleep tiering's freshness cutoff. A memory
-   *  whose reference time (last_accessed_at ?? updated_at ?? created_at) is
-   *  newer than the cutoff is skipped — phaseDemotion snapshots ref times up
-   *  front, and a recall touch landing between the snapshot and this call must
-   *  not demote a freshly-accessed memory. The check and the update run in the
-   *  same synchronous transaction, so the read-then-write is atomic. */
+  // --- sleep-mode storage support (v0.4.0) ---------------------------------
+  // touchLastAccess stamps the read time on recall/inject paths. It deliberately
+  // does NOT bump the mirror generation: reads must not mark the mirror dirty.
+  function touchLastAccess(id, at) {
+    if (!getById(id)) return false;
+    db.prepare("UPDATE memories SET last_accessed_at = ? WHERE id = ?")
+      .run(at ?? nowIso(), id);
+    return true;
+  }
+
+  // Shrink an aged memory to `summary`, parking its full body in _full_content.
+  // Idempotent: an already-demoted memory (non-null _full_content) is left
+  // untouched. minRefTimeMs guards the fast path — if last_accessed_at moved
+  // after the caller's snapshot (>= minRefTimeMs), the memory is hot again and
+  // is skipped. Returns the updated memory, or undefined when skipped/absent.
   function demoteToSummary(id, summary, { minRefTimeMs } = {}) {
+    let changed = false;
     runAtomically(() => {
-      const row = db.prepare(
-        "SELECT content, _full_content, last_accessed_at, updated_at, created_at FROM memories WHERE id = ?"
-      ).get(id);
-      if (!row || row._full_content) return; // idempotent: never double-wrap
-      if (minRefTimeMs != null) {
-        const ref = row.last_accessed_at ?? row.updated_at ?? row.created_at;
-        const t = ref ? new Date(ref).getTime() : NaN;
-        if (!Number.isNaN(t) && t >= minRefTimeMs) return; // freshly touched: keep full
+      const row = db.prepare("SELECT last_accessed_at, content, _full_content FROM memories WHERE id = ?").get(id);
+      if (!row || row._full_content) return;
+      if (minRefTimeMs !== undefined && row.last_accessed_at) {
+        const lastMs = Date.parse(row.last_accessed_at);
+        if (lastMs >= minRefTimeMs) return; // touched after snapshot — still hot
       }
       db.prepare(
-        "UPDATE memories SET _full_content = ?, content = ?, updated_at = ? WHERE id = ?"
-      ).run(row.content ?? "", summary ?? "", nowIso(), id);
+        "UPDATE memories SET content = ?, _full_content = ?, updated_at = ? WHERE id = ?"
+      ).run(summary, row.content, nowIso(), id);
       incrementGeneration();
+      changed = true;
     });
-    return getById(id);
+    return changed ? getById(id) : undefined;
+  }
+
+  // Undo demoteToSummary: pull the parked body back into content.
+  function restoreContent(id) {
+    let changed = false;
+    runAtomically(() => {
+      const row = db.prepare("SELECT content, _full_content FROM memories WHERE id = ?").get(id);
+      if (!row || !row._full_content) return;
+      db.prepare(
+        "UPDATE memories SET content = ?, _full_content = NULL, updated_at = ? WHERE id = ?"
+      ).run(row._full_content, nowIso(), id);
+      incrementGeneration();
+      changed = true;
+    });
+    return changed ? getById(id) : undefined;
+  }
+
+  // Live memories that have not been touched since `cutMs` (never-touched ones
+  // fall back to created_at). Ordered by last access ascending — the coldest
+  // first. Used by sleep phase 2 to pick archival-demotion candidates.
+  function getUnrecalledSince(cutMs, { limit = 500 } = {}) {
+    const cutIso = new Date(cutMs).toISOString();
+    const rows = db.prepare(
+      `SELECT * FROM memories
+       WHERE forgotten = 0 AND archived = 0
+         AND (last_accessed_at IS NULL OR last_accessed_at < ?)
+       ORDER BY COALESCE(last_accessed_at, created_at) ASC, id
+       LIMIT ?`
+    ).all(cutIso, limit);
+    return rows.map(toRow);
   }
 
   function list({ type, limit = 50, offset = 0, includeForgotten = false, includeArchived = false } = {}) {
@@ -1246,6 +1295,16 @@ export function createStore(path) {
     ).all(entityId, entityId).map(toRelation);
   }
 
+  /** All entities (optionally name-filtered, newest first). Used by sleep phase 4
+   *  orphan detection: an entity with zero relations is a candidate for relation
+   *  completion. */
+  function listEntities({ limit = 1000 } = {}) {
+    const rows = db.prepare(
+      "SELECT * FROM entities ORDER BY last_seen DESC, name ASC LIMIT ?"
+    ).all(limit);
+    return rows.map(toEntity);
+  }
+
   // --- mirror sync state (F-NEW-03) -----------------------------------------
 
   /**
@@ -1286,8 +1345,15 @@ export function createStore(path) {
       if (key === "dirty") {
         value = value ? 1 : 0;
       } else if (key === "generation" || key === "applied_generation") {
-        value = Math.trunc(Number(value));
-        if (!Number.isFinite(value) || value < 0 || value > Number.MAX_SAFE_INTEGER) {
+        // Fail-closed integer enforcement (audit peer F): never truncate. A
+        // fractional value like 1.5 previously passed the JS gate via
+        // Math.trunc while SQLite's CHECK (>= 0) silently accepted it too, so a
+        // dirty legacy row could carry a non-integer generation that reads as a
+        // coherent applied round. Reject non-integers outright — the caller must
+        // pass a whole number, and a stale dirty value stays visible instead of
+        // being "repaired" into a misleading clean integer.
+        value = Number(value);
+        if (!Number.isInteger(value) || value < 0 || value > Number.MAX_SAFE_INTEGER) {
           throw new RangeError(`mirror_state.${key} out of range: ${value}`);
         }
       } else if (key === "type_status" && value != null && typeof value !== "string") {
@@ -1437,8 +1503,10 @@ export function createStore(path) {
     remove,
     setForget,
     setArchived,
-    touchAccess,
+    touchLastAccess,
     demoteToSummary,
+    restoreContent,
+    getUnrecalledSince,
     list,
     all,
     search,
@@ -1467,6 +1535,7 @@ export function createStore(path) {
     createEntity,
     findEntityByName,
     findEntityById,
+    listEntities,
     updateEntity,
     saveAttr,
     invalidateOldAttr,