sage-mem 1.0.2 → 1.2.0

package/README.md

@@ -151,7 +151,7 @@ Every image below is **rendered from the UI code in this repository** (the same
 
 ![File list: one Markdown file per memory, greyed rows are archived](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/images/files-list.png)
 
-*File list — the header always shows 「体检 N 个问题」(audit: N issues) and 「待重启生效」(restart to apply), so you know whether you should deal with it without opening anything; greyed rows are archived and can be restored at any time.*
+*File list — the header always shows 「体检 N 个问题」(audit: N issues) and 「待重启生效」(restart to apply), so you know whether you should deal with it without opening anything; greyed rows are archived and can be restored at any time, or deleted for good with 「彻底删除」(irreversible, asks once more).*
 
 ![Tools drawer: archive candidates / reserved-name editing, zero footprint when closed](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/images/tools-drawer.png)
 
@@ -171,7 +171,7 @@ Every image below is **rendered from the UI code in this repository** (the same
 
 ![Archive candidates: each states "why archiving is suggested", executed only after confirmation](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/images/archive-candidates.png)
 
-*Archive candidates — each states "why archiving is suggested" (idle days vs the threshold for that type); files are touched only after you confirm one by one or select all. Archiving moves a file into `archive/`, it **does not delete**.*
+*Archive candidates — each states "why archiving is suggested" (idle days vs the threshold for that type); files are touched only after you confirm one by one or select all. Archiving moves a file into `archive/`, it **does not delete**; to actually delete an archived entry, click 「彻底删除」(delete permanently) in the archive view and confirm once more.*
 
 ![Memory star map: dark stars are archived memories](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/images/starmap-archive.png)
 
@@ -492,6 +492,14 @@ memory/ directory (markdown files, 4 types)
 
 No worker, no SQLite, no HTTP port, no long-running process.
 
+Module boundaries (since 1.2.0):
+
+- `lib/index.js` — the **composition root** plus the three gateways. The typert manifest pins `sourceLocation` to this file, so the gateway classes stay here (moving them would be a contract drift)
+- `lib/recall/` — the injection chain: selection (`select`) / rendering and budget (`compose`) / text (`text`) / session state (`state`)
+- `lib/assembly/` — the four mounts: autodream / retrieval tools / observation / write gate
+- `lib/memory/` — pure memory-layer functions and file operations; `lib/autodream/` — the autodream engine
+- Dependency direction: `memory` never imports `autodream`, `recall` depends only on `memory`, `assembly` never imports the composition root (`test/structure-test.mjs` turns red if that changes)
+
 ## Contributing
 
 ```bash

package/README.zh.md

@@ -153,7 +153,7 @@ SAGE_MEM_DIR=/path/to/your/memory
 
 ![文件列表：每条记忆一个 Markdown 文件，灰底的是已归档](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/images/files-list.png)
 
-*文件列表 —— 头部常显「体检 N 个问题」与「待重启生效」，不用点开就知道该不该处理；灰底条目是已归档，随时可以恢复。*
+*文件列表 —— 头部常显「体检 N 个问题」与「待重启生效」，不用点开就知道该不该处理；灰底条目是已归档，随时可以恢复，也可以点「彻底删除」真的删掉（不可恢复，要再确认一次）。*
 
 ![工具抽屉：归档候选 / 保留名编辑，关着时零占位](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/images/tools-drawer.png)
 
@@ -173,7 +173,7 @@ SAGE_MEM_DIR=/path/to/your/memory
 
 ![归档候选：每条写清「为什么建议归档」，确认后才执行](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/images/archive-candidates.png)
 
-*归档候选 —— 每条写清「为什么建议归档」（闲置天数 vs 该类型阈值），逐条或全选后确认才动文件。归档是把文件移进 `archive/`，**不删除**。*
+*归档候选 —— 每条写清「为什么建议归档」（闲置天数 vs 该类型阈值），逐条或全选后确认才动文件。归档是把文件移进 `archive/`，**不删除**；真要删掉一条归档件，得在档案馆里单独点「彻底删除」并再确认一次。*
 
 ![记忆星图：暗星是已归档的记忆](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/images/starmap-archive.png)
 
@@ -496,6 +496,14 @@ memory/ 目录（markdown 文件，4 类）
 
 没有 worker、没有 SQLite、没有 HTTP 端口、没有常驻进程。
 
+模块边界（1.2.0 起）：
+
+- `lib/index.js` —— **组合根** + 三个 Gateway。typert manifest 的 `sourceLocation` 钉在这个文件上，所以 Gateway 类不搬走（搬 = 契约漂移）
+- `lib/recall/` —— 注入链：选材（`select`）/ 渲染与预算（`compose`）/ 文本（`text`）/ 会话状态（`state`）
+- `lib/assembly/` —— 四块挂载：autodream / 检索工具 / 观测 / 写入门
+- `lib/memory/` —— 记忆层的纯函数与文件操作；`lib/autodream/` —— 自动做梦引擎
+- 依赖方向：`memory` 不认识 `autodream`，`recall` 只依赖 `memory`，`assembly` 不反向依赖组合根（`test/structure-test.mjs` 会红）
+
 ## 参与开发
 
 ```bash

package/lib/assembly/autodream-mount.js

@@ -0,0 +1,24 @@
+/**
+ * autodream 的挂载（1.2.0 从 `MemoryGateway` 构造函数原样搬出）。
+ *
+ * 整个包在 try 里：autodream 起不来（比如 timer 服务缺失、状态目录没权限）
+ * 不该把 sage-mem 最核心的那件事——「记忆按问题注入」——一起拖死。
+ * 这是本插件唯一一处「降级而不是失败」的设计，理由就在这里。
+ */
+import { warnLog } from '../memory/util.js'
+
+/** @param {object} ctx @param {{AutodreamEngine:Function, AutodreamGateway:Function, memoryDir:string, sessionsRoot:string, reservedFiles:string[]}} deps */
+export function mountAutodream(ctx, { AutodreamEngine, AutodreamGateway, memoryDir, sessionsRoot, reservedFiles }) {
+  try {
+    const engine = new AutodreamEngine(ctx, { memoryDir, sessionsRoot, reservedFiles })
+    new AutodreamGateway(ctx, engine)
+    engine.start()
+    // 卸载时把定时器与锁收干净。effect 拿不到就交给 unref 兜底（不阻止进程退出）。
+    if (typeof ctx.effect === 'function') ctx.effect(() => () => engine.dispose())
+  } catch (err) {
+    warnLog(ctx, `autodream 初始化失败（记忆本体不受影响）：${err?.message ?? err}`)
+    // 异常路径额外打一行到 stderr：warnLog 走 ctx.logger，某些启动阶段它还没接上，
+    // 而「autodream 静默不工作」正是最难查的那种故障（曾为此排查很久）。
+    console.error('[sage-mem] autodream init failed:', err && err.stack ? err.stack : err)
+  }
+}

package/lib/assembly/index.js

@@ -0,0 +1,13 @@
+/**
+ * 组合根的四块挂载（1.2.0 的模块边界）。
+ *
+ * 每块一个文件、一个 `mountXxx(ctx, …)`：组合根的构造函数只负责按顺序调用它们。
+ * 顺序是语义的一部分（autodream → 工具 → 观测 → 写门），所以这里按同一顺序再导出。
+ *
+ * ⚠️ `mountWriteGate` 必须**同步**调用（注册窗口在 fs 就绪之前就关），
+ * 这条约束写在 `write-gate-mount.js` 头注里，并由 `write-gate-wiring-test.mjs` 第 7 组看着。
+ */
+export { mountAutodream } from './autodream-mount.js'
+export { mountMemoryTools } from './tools-mount.js'
+export { mountObserve } from './observe-mount.js'
+export { mountWriteGate } from './write-gate-mount.js'

package/lib/assembly/observe-mount.js

@@ -0,0 +1,37 @@
+/**
+ * 「模型自己翻了记忆目录」的观测挂载（1.2.0 从构造函数原样搬出）。
+ *
+ * 宿主的 `tools/result` 把**每一次**工具调用的 `exec`（含 name / arguments）交给我们，
+ * 于是「模型用内置 read/grep 读了哪份记忆」第一次变得可观测 —— 此前台账只记得下
+ * 「插件注入了什么」，记不下「模型主动翻了什么」。
+ *
+ * 三条纪律：
+ *   1. **只记能可靠判定的**（`observe.js` 认 read/grep/glob 的路径参数；`pwsh` 一律不认，
+ *      那是**已知观测盲区** —— 不许把「看不到」说成「没读」）。
+ *   2. **按 session × 文件去重**：翻页（read 的 offset 不同）不刷计数，那是同一个动作。
+ *   3. **失败绝不影响任何东西**：观测是副产品，它的问题不许冒泡到工具调用链上。
+ */
+import { accessEventKey, classifyToolExecution, createDeduper } from '../memory/observe.js'
+import { recordRead } from '../memory/access.js'
+
+export function mountObserve(ctx, memoryDir) {
+  const observedReads = createDeduper()
+  try {
+    ctx.on('tools/result', (exec) => {
+      try {
+        const cls = classifyToolExecution(exec?.name, exec?.arguments, memoryDir)
+        if (cls.kind !== 'active_read' || !cls.file) return
+        const key = accessEventKey({
+          sessionId: exec?.agent?.id ?? '',
+          file: cls.file,
+          // revision 要读盘才算得出，这里拿不到 —— 所以去重粒度是「session × 文件」。
+          // 写明这条口径，免得以后有人以为它按内容去重。
+          revision: '',
+          kind: cls.kind,
+        })
+        if (!key || !observedReads.shouldCount(key)) return
+        recordRead(cls.file, '')
+      } catch { /* 观测失败静默：它不该有任何存在感 */ }
+    })
+  } catch { /* 老宿主没有这个事件：不影响注入 */ }
+}

package/lib/assembly/tools-mount.js

@@ -0,0 +1,44 @@
+/**
+ * 检索工具（`search_memory` / `read_memory`）的挂载（1.2.0 从构造函数原样搬出）。
+ *
+ * 工具是否注册成功。拿不到宿主的 `tools` 服务时为 false —— 状态卡据此换文案：
+ * 有工具就教它「用 search_memory 搜」，没有就退回「直接读记忆目录」。
+ *
+ * 为什么是个可变量：注册是**异步就绪**的（`ctx.inject` 要等依赖服务上线），而注入链
+ * 每步都跑 —— 前几步可能还没就绪、后几步才就绪，这是正常的。
+ * 因此返回 `{ ready: () => boolean }` 而不是一个布尔值：值拷贝会让注入链永远读到 false。
+ *
+ * ⚠️ **用 `ctx.inject` 挂子 fiber，绝不给本类加 `static inject = ['tools']`。**
+ * 理由（`docs/decisions.md` D5，有官方依据）：`inject` 是**硬依赖** —— 声明了它的插件
+ * 要等依赖就绪才会被加载。宿主没有 `tools` 服务时，整个 sage-mem 会一直待机，
+ * **记忆注入跟着一起消失**。而工具只是锦上添花，不值得拿核心功能去换。
+ * `ctx.inject` 只让这个子回调等依赖就绪，主插件照常工作；依赖永远不来就只有它不生效。
+ *
+ * 另一条实测事实（`docs/host-facts.md`）：不声明 inject 时 `ctx.get('tools')` 只给
+ * `undefined`（那一刻服务还没被提供，而插件不会重跑），所以「先探测再注册」在这里
+ * 是行不通的 —— 必须走 `ctx.inject`。
+ */
+import { createMemoryTools } from '../tools/memory-tools.js'
+import { warnLog } from '../memory/util.js'
+
+export function mountMemoryTools(ctx) {
+  const state = { ready: false }
+  try {
+    if (typeof ctx.inject === 'function') {
+      ctx.inject(['tools'], (inner) => {
+        try {
+          const { searchMemory, readMemory } = createMemoryTools(ctx)
+          inner.tools.register(searchMemory)
+          inner.tools.register(readMemory)
+          state.ready = true
+        } catch (err) {
+          // 注册失败 ≠ 注入失败。出声一次，然后什么也不做。
+          warnLog(ctx, `检索工具注册失败（记忆注入不受影响）：${err?.message ?? err}`)
+        }
+      })
+    }
+  } catch (err) {
+    warnLog(ctx, `检索工具挂载失败（记忆注入不受影响）：${err?.message ?? err}`)
+  }
+  return { ready: () => state.ready }
+}

package/lib/assembly/write-gate-mount.js

@@ -0,0 +1,92 @@
+/**
+ * 写入门（版本守卫）的挂载（1.2.0 从构造函数原样搬出）。
+ *
+ * 实测（`scripts/events-probe.mjs`，本机 headless，2026-10-15）：这两个事件**只对
+ * 「工具发起」的写入**触发 —— 模型调内置 `write` / `edit` 打到记忆文件时会走这里；
+ * 而**插件自己**调 `ctx.fs.writeText` 时一次都不发（实测 0 次），那条路由调用方自己传
+ * `expected`（见 `lib/autodream/tools.js` 的 `writeMemoryText`）。
+ * 监听器**不需要声明 inject** 也能收到，所以这里不挂子 fiber。
+ *
+ * 它买到的东西：**模型的 `write` 没法在一个记忆文件被改过之后静默覆盖它** ——
+ * 守卫过不了，宿主会以 `FS_STALE_VERSION` 明确拒绝（实测确实会被拒）。
+ * 这属于「把静默的坏结果变成显式的失败」，不是「阻止写入」：这个事件**没有拒绝动作**，
+ * 我们也不发明一个（见 write-gate.js 的头注释）。
+ *
+ * 单槽纪律：返回 `undefined` 才是「不管」。目录外**必须**返回 undefined，否则会占掉槽位、
+ * 影响整块盘的写入（write-gate.js 的 `outside_memory` 判在 `caller_wins` 之前正是为此）。
+ *
+ * ⚠️⚠️ **本函数必须在 `apply()` 里被直接调用，绝不能挪进 `ctx.inject(['fs'], …)`，也不能给
+ * 插件加 `static inject = ['fs']`。** 这不是风格偏好，是实测出来的硬约束：
+ * 这两个事件有一个**注册窗口**，窗口在 fs 服务就绪**之前**就关了。
+ *   不 inject、apply 里直接挂     → 收到 1 次 ✅
+ *   顶层 `inject:['fs']`           → **0 次**
+ *   顶层 `inject:['tokenMeter']`   → **0 次**（与 fs 无关，是时机问题）
+ *   `ctx.inject(['fs'], sub)` 子 fiber → **0 次**
+ *   不 inject、但 apply 之后 2.5 秒再挂 → **0 次**（晚挂收不到）
+ * 证据：`scripts/host-facts-probe.mjs` 的七组对照 + `docs/host-facts.md` 3.3 节。
+ * 之所以特别标注：**按 D5 的规范直觉（可选服务要用 ctx.inject 挂子 fiber）改这里，
+ * 会让写门静默失效** —— 编译得过、测试可能也过，只是永远不触发。
+ * 而我们**不需要** inject：实测不声明 inject 时，处理器**内部** `ctx.get('fs')` 照样拿得到服务
+ * （`{hasFs:true, hasStat:true}`），取版本就靠它。
+ */
+import { memoryPathOf } from '../memory/paths.js'
+import { decideEditGuard, decideWriteIntent } from '../memory/write-gate.js'
+
+/**
+ * 探目标的当前版本。**区分「不存在」与「不知道」**。
+ *
+ * 这个区分不是洁癖：`!!info` 会把「拿不到 fs 服务」也写成 `exists:false`，判定表据此给
+ * `createIfAbsent` —— 而目标**其实是存在的**记忆文件时，那是一次**误拦**（写入必然失败，
+ * 模型收到一句看不懂的错误）。拿不准就不干涉，比猜一个安全。
+ */
+function makeProbeTarget(ctx) {
+  return async (target) => {
+    try {
+      const fs = typeof ctx.get === 'function' ? ctx.get('fs') : undefined
+      if (!fs || typeof fs.stat !== 'function' || !target) return { known: false }
+      const info = await fs.stat(target)
+      return { known: true, exists: !!info, version: info?.version ?? null }
+    } catch {
+      return { known: false }
+    }
+  }
+}
+
+export function mountWriteGate(ctx, memoryDir) {
+  const probeTarget = makeProbeTarget(ctx)
+  try {
+    if (typeof ctx.on === 'function') {
+      // 公共骨架：**先判位置、再决定要不要碰链子**。
+      //
+      // ⚠️ 三条纪律（都是踩出来的）：
+      //   1. **目录外连 `next()` 都不调**。宿主对**任何**工具写入都发这个事件（实测：写一个
+      //      临时文件也发），无条件调 next() + stat 等于给整个系统的每次写文件都加一次系统调用，
+      //      而我们本来就什么都不该做。直接 `return next()` 把决策权原样交出去。
+      //   2. **一旦调了 `next()`，就必须把它给的东西交回去**。`next()` 返回的是下游（或调用方
+      //      自己）已经做出的决定；此时再 `return undefined` 会把这个决定**丢掉** ——
+      //      我们本想「不干涉」，实际却比干涉还糟。
+      //   3. **探不到版本就不碰**（见 probeTarget）：把「不知道」当「不存在」会误拦真实存在的文件。
+      const gateEvent = (decide) => async (target, actor, next) => {
+        try {
+          const memoryPath = memoryPathOf(target?.displayPath, memoryDir)
+          if (!memoryPath.ok) return typeof next === 'function' ? next() : undefined
+          const caller = typeof next === 'function' ? await next() : undefined
+          const probed = await probeTarget(target)
+          if (!probed.known) return caller
+          const chosen = decide({
+            memoryPath,
+            exists: probed.exists,
+            version: probed.version,
+            caller,
+          })
+          // 我们给出决定就用我们的；决定不了（undefined）就把 `caller` 原样交回去，不吞。
+          return chosen === undefined ? caller : chosen
+        } catch {
+          return undefined /* 写门在宿主的写入链路上：抛出去会把一次正常写入炸掉 */
+        }
+      }
+      ctx.on('fs/write-intent', gateEvent((facts) => decideWriteIntent(facts).intent))
+      ctx.on('fs/edit-intent', gateEvent((facts) => decideEditGuard(facts).guard))
+    }
+  } catch { /* 老宿主没有这两个事件：写入按宿主默认语义走 */ }
+}

package/lib/{autodream-audit.js → autodream/audit.js}

@@ -23,8 +23,8 @@
 
 import { readdir, readFile } from 'node:fs/promises'
 import { join } from 'node:path'
-import { ARCHIVE_DIR_NAME, inspectMemoryEntry } from './memory/scan.js'
-import { warnLog } from './memory/util.js'
+import { ARCHIVE_DIR_NAME, inspectMemoryEntry } from '../memory/scan.js'
+import { warnLog } from '../memory/util.js'
 
 /** 索引文件名。它本身不是一条记忆，是索引。 */
 const INDEX_FILE = 'MEMORY.md'

package/lib/autodream/engine.js

@@ -33,8 +33,8 @@
  * 这里保留**同名同签名**的方法，以 `.call(this, …)` 转发 —— 纯搬移、零行为变更。
  */
 
-import { auditMemoryDir } from '../autodream-audit.js'
-import { autodreamToolSchemas, createToolRunner } from '../autodream-tools.js'
+import { auditMemoryDir } from './audit.js'
+import { autodreamToolSchemas, createToolRunner } from './tools.js'
 import { CONFIG_VERSION, DEFAULT_CONFIG, DEFAULT_TOKEN_BUDGET, FAILURE_BACKOFF_MS, FEATURE_DIR, LEGACY_SNAPSHOT_DIR, LEGACY_STATE_FILE, SCHEDULE_INTERVAL_MS, STARTUP_CHECK_DELAY_MS, STATE_DIR } from './config.js'
 import { countSessionsSince, newRunId, stampHuman } from './util.js'
 import { flushAccess, ledgerFileFor, pickArchiveCandidates, readAccessLedger } from '../memory/access.js'

package/lib/autodream/llm-loop.js

@@ -8,7 +8,7 @@
  * 之所以不用真正的子代理：见 engine.js 顶部第 2 条设计决定。
  */
 
-import { buildAutodreamSystemPrompt, buildAutodreamUserPrompt } from '../autodream-prompt.js'
+import { buildAutodreamSystemPrompt, buildAutodreamUserPrompt } from './prompt.js'
 import { randomUUID } from 'node:crypto'
 
 export class BlockAssembler {

package/lib/autodream/report.js

@@ -6,7 +6,7 @@
  * 与拆分前完全一致，没有引入任何模块级可变状态。
  */
 
-import { formatAudit } from '../autodream-audit.js'
+import { formatAudit } from './audit.js'
 import { LEGACY_REPORT_DIR, REPORT_DIR } from './config.js'
 import { OP_LABEL, formatDelta, readJson, safeName, stampHuman } from './util.js'
 import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises'

package/lib/{autodream-tools.js → autodream/tools.js}

@@ -27,14 +27,14 @@
 import { readFile, readdir, stat } from 'node:fs/promises'
 import { join, basename } from 'node:path'
 import { createHash } from 'node:crypto'
-import { auditMemoryDir, formatAudit, parseFrontmatterLite } from './autodream-audit.js'
-import { archiveMemory } from './memory/archive.js'
-import { MAX_FILE_BYTES, STATE_ROOT } from './memory/config.js'
-import { writeFileAtomic, warnLog } from './memory/util.js'
-import { buildConflict, writeConflict } from './memory/conflicts.js'
-import { memoryPathOf } from './memory/paths.js'
-import { decideWriteIntent } from './memory/write-gate.js'
-import { inspectMemoryEntry, reservedIdentitySet } from './memory/scan.js'
+import { auditMemoryDir, formatAudit, parseFrontmatterLite } from './audit.js'
+import { archiveMemory } from '../memory/archive.js'
+import { MAX_FILE_BYTES, STATE_ROOT } from '../memory/config.js'
+import { writeFileAtomic, warnLog } from '../memory/util.js'
+import { buildConflict, writeConflict } from '../memory/conflicts.js'
+import { memoryPathOf } from '../memory/paths.js'
+import { decideWriteIntent } from '../memory/write-gate.js'
+import { inspectMemoryEntry, reservedIdentitySet } from '../memory/scan.js'
 
 /** 单次 read_memory 返回的正文上限（字符）。超过就截断并明确告诉模型。 */
 const READ_LIMIT = 20000

package/lib/client.js

@@ -1605,6 +1605,9 @@ const StarmapRuntime = (function (require, _react) {
 		// 归档文件的读 / 写（B1b）：形状与活跃记忆那套的 readSchema / writeSchema 对称。
 		const archivedReadSchema = parseSchema({ "name": isStr, "content": isStr });
 		const archivedWriteSchema = parseSchema({ "ok": isBool, "file": isStr });
+		// 「彻底删除」的入参：归档代次（`archivedAt`）。它不是装饰 —— 宿主拿它核对
+		// 「要删的是不是用户确认过的那一版」。老归档件没有留痕时传空串，所以只校类型。
+		const archiveStampSchema = strSchema;
 
 		// ── autodream 的 codec ──
 		// 刻意写得宽：这几个方法返回的是配置 / 状态对象，字段会随版本增删。
@@ -1734,6 +1737,21 @@ const StarmapRuntime = (function (require, _react) {
 					result: { mode: "strict", typeSymbol: "sage-mem/types#ArchivedWriteResult", schema: archivedWriteSchema, create: () => archivedWriteSchema },
 					sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
 				},
+				{
+					// 彻底删除一条归档件（不可恢复）。第二个参数是归档代次：宿主拿它核对
+					// 「要删的是不是用户确认过的那一版」，传错（比如列表过期）会被拒绝。
+					id: "sage-mem#memory/deleteArchived",
+					service: "memory",
+					namespace: "memory",
+					method: "deleteArchived",
+					invocation: { kind: "direct" },
+					parameters: [
+						{ name: "name", wire: "name", source: "json", codec: { mode: "strict", typeSymbol: "sage-mem/types#ArchivedFileName", schema: strSchema, create: () => strSchema } },
+						{ name: "archivedAt", wire: "archivedAt", source: "json", codec: { mode: "strict", typeSymbol: "sage-mem/types#ArchiveStamp", schema: archiveStampSchema, create: () => archiveStampSchema } },
+					],
+					result: { mode: "strict", typeSymbol: "sage-mem/types#ArchiveResult", schema: archiveSchema, create: () => archiveSchema },
+					sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
+				},
 				// ── 面板 API（D1）：体检 / 归档候选 / 设置 / 保留名原样读写 ──
 				// 结果形状都在演进（审计清单、候选表、设置项），顶层用 objCodec 接住、
 				// 内部宽松 —— 与 autodream 那几个 codec 同一套理由：host 加字段不该让旧界面整体报错。
@@ -2555,7 +2573,7 @@ const StarmapRuntime = (function (require, _react) {
 
 		/**
 		 * 归档区的一条。与活动卡片共用骨架（类型章 / 标题 / 标签 / 描述），刻意的差异：
-		 * 虚线边框 + 整体压灰（退役感）、多一行归档留痕、动作是「编辑 / 恢复」。
+		 * 虚线边框 + 整体压灰（退役感）、多一行归档留痕、动作是「编辑 / 恢复 / 彻底删除」。
 		 *
 		 * ⚠️ 灰的只有**内容**（`.smem-card--archived` 那几条只点标题/类型章/标签/正文的字色）。
 		 * 按钮一律保持原样 —— 按钮一灰，用户就以为不能按。
@@ -2563,7 +2581,10 @@ const StarmapRuntime = (function (require, _react) {
 		 * ⚠️ 编辑走**原样文本**：readArchived 拿到的全文直接进 textarea，保存时原样交回
 		 * writeArchived。绝不走活跃记忆那套 buildFrontmatter 重建 —— 重建会吞字段，
 		 * 归档文件里还有 archived_at / archived_reason 这种留痕，更动不得。
-		 * 也不提供删除：归档 = 不删，host 侧也没有那条 remote。
+		 *
+		 * 「彻底删除」是 v1.1.0 加的**唯一**一个不可逆入口，所以它走两段式：
+		 * 点一下只展开一句「真的删、不能恢复」的确认条，再点「确认彻底删除」才动手。
+		 * 归档的承诺（只移不删）没有被它破坏 —— 归档动作仍然一个字节都不删。
 		 */
 		function ArchivedCard(props) {
 			const item = props.item;
@@ -2603,19 +2624,39 @@ const StarmapRuntime = (function (require, _react) {
 								h("button", { type: "button", className: "smem-btn", key: "cancel", disabled: props.busy, onClick: props.onCancel }, "取消"),
 							]),
 						])
-					: h("div", { className: "smem-card-foot", key: "foot" },
-							h("div", { className: "smem-actions", key: "acts" }, [
-								h("button", {
-									type: "button", className: "smem-btn", key: "edit",
-									disabled: props.busy,
-									onClick: function () { props.onEdit(item.file); },
-								}, "编辑"),
-								h("button", {
-									type: "button", className: "smem-btn smem-btn-primary", key: "restore",
-									disabled: props.busy,
-									onClick: function () { props.onRestore(item.file); },
-								}, props.restoring ? "恢复中…" : "恢复"),
-							])),
+					: props.deleting
+						? h("div", { className: "smem-ar-confirm", key: "del" }, [
+								h("div", { key: "what" },
+									"彻底删除「" + item.file + "」：它会从 archive/ 里被真的删掉，不能恢复。" +
+									"要保留它就先点「恢复」，把它放回活动记忆。"),
+								h("div", { className: "smem-ar-hint", key: "hint" },
+									"这一步之后没有任何界面能把内容找回来 —— 只剩你自己在磁盘上留过备份。"),
+								h("div", { className: "smem-row", key: "btns" }, [
+									h("button", { type: "button", className: "smem-btn smem-btn-danger", key: "yes", disabled: props.busy, onClick: function () { props.onConfirmDelete(item.file); } }, "确认彻底删除"),
+									h("button", { type: "button", className: "smem-btn", key: "no", disabled: props.busy, onClick: props.onCancelDelete }, "取消"),
+								]),
+							])
+						: h("div", { className: "smem-card-foot", key: "foot" },
+								h("div", { className: "smem-actions", key: "acts" }, [
+									h("button", {
+										type: "button", className: "smem-btn", key: "edit",
+										disabled: props.busy,
+										onClick: function () { props.onEdit(item.file); },
+									}, "编辑"),
+									h("button", {
+										type: "button", className: "smem-btn smem-btn-primary", key: "restore",
+										disabled: props.busy,
+										onClick: function () { props.onRestore(item.file); },
+									}, props.restoring ? "恢复中…" : "恢复"),
+									// 放在最后、且用 danger-ghost：它是这张卡上唯一不可逆的动作，
+									// 不该跟「恢复」长得一样。
+									h("button", {
+										type: "button", className: "smem-btn smem-btn-danger-ghost", key: "purge",
+										disabled: props.busy,
+										title: "从 archive/ 里彻底删掉，不可恢复（要留就先恢复）",
+										onClick: function () { props.onAskDelete(item.file); },
+									}, "彻底删除"),
+								])),
 			]);
 		}
 
@@ -3804,6 +3845,10 @@ const StarmapRuntime = (function (require, _react) {
 			const archiveReason = sArchiveReason[0], setArchiveReason = sArchiveReason[1];
 			const sRestoring = react.useState(null);
 			const restoring = sRestoring[0], setRestoring = sRestoring[1];
+			// 「彻底删除」的二次确认：正在问哪一条（null = 没在问）。
+			// 与 editing 互斥 —— 同一张卡上不能既在改又在删。
+			const sArchDelete = react.useState(null);
+			const archDelete = sArchDelete[0], setArchDelete = sArchDelete[1];
 			// 归档文件的「原样文本」编辑器：正在编辑谁、编辑框里是什么、读/存进行中
 			const sArchEdit = react.useState(null);
 			const archEdit = sArchEdit[0], setArchEdit = sArchEdit[1];
@@ -4073,6 +4118,7 @@ const StarmapRuntime = (function (require, _react) {
 				}
 				setBusy(true); setError(null); setNotice("");
 				setRestoring(file);
+				setArchDelete(null);
 				remote.restore(file)
 					.then(function (r) {
 						if (r && r.ok === false) { setError(r.error || "恢复被拒绝"); return; }
@@ -4084,6 +4130,31 @@ const StarmapRuntime = (function (require, _react) {
 					.then(function () { setBusy(false); setRestoring(null); });
 			}
 
+			/**
+			 * **彻底删除**一条归档件（不可恢复）。
+			 *
+			 * 第二个参数是归档代次（列表上看到的 `archivedAt`）：宿主拿它核对「要删的是不是
+			 * 我确认过的那一版」。不传它会变成「按名字删」—— 名字底下的内容刚才可能已经换人了。
+			 */
+			function deleteArchivedFile(file) {
+				if (typeof remote.deleteArchived !== "function") {
+					setError("宿主侧还没有 deleteArchived 接口（插件版本较旧）");
+					return;
+				}
+				const item = archiveItems.filter(function (x) { return x.file === file; })[0];
+				const stamp = (item && item.archivedAt) || "";
+				setBusy(true); setError(null); setNotice("");
+				remote.deleteArchived(file, stamp)
+					.then(function (r) {
+						if (r && r.ok === false) { setError(r.error || "删除被拒绝"); return; }
+						setArchDelete(null);
+						setNotice("已彻底删除 " + file + " —— 归档区里也没有它了，找不回来");
+						load();
+					})
+					.catch(function (e) { setError(String((e && e.message) || e)); })
+					.then(function () { setBusy(false); });
+			}
+
 			/**
 			 * 打开归档文件的**原样文本**编辑器。
 			 *
@@ -4098,6 +4169,7 @@ const StarmapRuntime = (function (require, _react) {
 					return;
 				}
 				setError(null); setNotice("");
+				setArchDelete(null);
 				setArchEdit(file);
 				setArchText("");
 				setArchLoad(true);
@@ -4368,6 +4440,7 @@ const StarmapRuntime = (function (require, _react) {
 							item: it,
 							busy: busy,
 							restoring: restoring === it.file,
+							deleting: archDelete === it.file,
 							editing: archEdit === it.file,
 							loading: archLoad && archEdit === it.file,
 							saving: archSaving && archEdit === it.file,
@@ -4377,6 +4450,10 @@ const StarmapRuntime = (function (require, _react) {
 							onSave: saveArchEdit,
 							onCancel: cancelArchEdit,
 							onRestore: restoreFile,
+							// 两个「危险动作的确认」互斥：问到一半又去改文本，界面就会同时摆两个确认条。
+							onAskDelete: function (file) { setArchDelete(file); setArchEdit(null); },
+							onCancelDelete: function () { setArchDelete(null); },
+							onConfirmDelete: deleteArchivedFile,
 						});
 					}
 					return h(Card, {
@@ -4407,7 +4484,7 @@ const StarmapRuntime = (function (require, _react) {
 					? [
 							h("div", { className: "smem-ar-banner", key: "banner" },
 								"档案馆里的记忆不参与检索与星图，原文仍在记忆目录的 archive/ 下 —— 恢复后它就回到活动列表；" +
-								"「编辑」是原样文本编辑，改完存回同一份文件。"),
+								"「编辑」是原样文本编辑，改完存回同一份文件；「彻底删除」会真的从 archive/ 里删掉它（不可恢复，删除前还要再确认一次）。"),
 							list,
 						]
 					: list;