@carloswon/cairn-memory 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/CHANGELOG.md +77 -0
  2. package/README.md +17 -1
  3. package/dist/src/core/types.d.ts +4 -0
  4. package/dist/src/governance/revision-proposal.d.ts +80 -0
  5. package/dist/src/governance/revision-proposal.js +243 -0
  6. package/dist/src/governance/revision-proposal.js.map +1 -0
  7. package/dist/src/interfaces/app-service.d.ts +82 -1
  8. package/dist/src/interfaces/app-service.js +249 -7
  9. package/dist/src/interfaces/app-service.js.map +1 -1
  10. package/dist/src/interfaces/cli/main.js +470 -45
  11. package/dist/src/interfaces/cli/main.js.map +1 -1
  12. package/dist/src/interfaces/console/annotations.d.ts +96 -0
  13. package/dist/src/interfaces/console/annotations.js +274 -0
  14. package/dist/src/interfaces/console/annotations.js.map +1 -0
  15. package/dist/src/interfaces/console/assets/ui-js.js +289 -4
  16. package/dist/src/interfaces/console/assets/ui-js.js.map +1 -1
  17. package/dist/src/interfaces/console/server.js +66 -0
  18. package/dist/src/interfaces/console/server.js.map +1 -1
  19. package/dist/src/interfaces/mcp/server.d.ts +8 -0
  20. package/dist/src/interfaces/mcp/server.js +178 -22
  21. package/dist/src/interfaces/mcp/server.js.map +1 -1
  22. package/dist/src/jobs/remote.d.ts +6 -0
  23. package/dist/src/jobs/remote.js.map +1 -1
  24. package/dist/src/retrieval/preview.d.ts +22 -0
  25. package/dist/src/retrieval/preview.js +61 -0
  26. package/dist/src/retrieval/preview.js.map +1 -0
  27. package/dist/src/retrieval/search.js +5 -1
  28. package/dist/src/retrieval/search.js.map +1 -1
  29. package/dist/src/store/index.d.ts +2 -0
  30. package/dist/src/store/index.js +2 -0
  31. package/dist/src/store/index.js.map +1 -1
  32. package/dist/src/store/memories.d.ts +13 -0
  33. package/dist/src/store/memories.js +29 -2
  34. package/dist/src/store/memories.js.map +1 -1
  35. package/dist/src/store/migrate.js +10 -1
  36. package/dist/src/store/migrate.js.map +1 -1
  37. package/dist/src/store/outbox.d.ts +1 -1
  38. package/dist/src/store/outbox.js.map +1 -1
  39. package/dist/src/store/project-alias.d.ts +13 -0
  40. package/dist/src/store/project-alias.js +55 -0
  41. package/dist/src/store/project-alias.js.map +1 -0
  42. package/dist/src/store/projects.d.ts +43 -0
  43. package/dist/src/store/projects.js +84 -0
  44. package/dist/src/store/projects.js.map +1 -0
  45. package/dist/src/store/schema.d.ts +11 -0
  46. package/dist/src/store/schema.js +55 -0
  47. package/dist/src/store/schema.js.map +1 -1
  48. package/dist/src/sync/apply.d.ts +4 -0
  49. package/dist/src/sync/apply.js +65 -3
  50. package/dist/src/sync/apply.js.map +1 -1
  51. package/dist/src/sync/backup-store.d.ts +63 -0
  52. package/dist/src/sync/backup-store.js +184 -0
  53. package/dist/src/sync/backup-store.js.map +1 -0
  54. package/dist/src/sync/cryptoutil.d.ts +10 -2
  55. package/dist/src/sync/cryptoutil.js +22 -1
  56. package/dist/src/sync/cryptoutil.js.map +1 -1
  57. package/dist/src/sync/events.d.ts +17 -2
  58. package/dist/src/sync/events.js.map +1 -1
  59. package/dist/src/sync/orchestrate.js +5 -1
  60. package/dist/src/sync/orchestrate.js.map +1 -1
  61. package/dist/src/sync/pull.js +1 -1
  62. package/dist/src/sync/pull.js.map +1 -1
  63. package/dist/src/sync/push.d.ts +2 -0
  64. package/dist/src/sync/push.js +28 -2
  65. package/dist/src/sync/push.js.map +1 -1
  66. package/dist/src/sync/syncd-store.d.ts +7 -0
  67. package/dist/src/sync/syncd-store.js +18 -0
  68. package/dist/src/sync/syncd-store.js.map +1 -1
  69. package/docs/cairn-security.md +14 -0
  70. package/docs/cairn-usage.md +127 -0
  71. package/package.json +2 -2
package/CHANGELOG.md CHANGED
@@ -2,6 +2,83 @@
2
2
 
3
3
  本文件记录 `@carloswon/cairn-memory` 的显著变更。格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
4
4
 
5
+ ## [0.6.0] - 2026-11-13
6
+
7
+ ### Added
8
+ - **MCP 工具面进程内冻结**:ListTools 结果在单个 server 进程生命周期内字节稳定——onboarding 条件工具在启动时判定一次,运行中库状态翻转(另一进程 import、会话内治理动作)不再增减工具,消除「不升级不重启」前提下唯一的工具 schema 变化向量(该向量曾造成 prompt 前缀缓存整包重算)。判定失败 fail-closed 降级不拒启。
9
+ - **检索条目携带作用域边界属性**:`memory_search` / `memory_context` 每条命中带 `scope_preset`(人读作用域名)+ `sensitivity` + `sync_policy`,无需另发详情调用。DSH 插件注入闸由空转变为真实生效(fail-closed:标签缺失=不可注入,计入面板「已过滤」),面板左右栏为注入条目渲染作用域徽章。
10
+ - **两段式检索:列表给预览,全文按需取**:`memory_search` / `memory_context` 条目返回有界预览(300 字符、frontmatter 感知、确定性单行)+ `truncated` + `content_length`,不再返回全文;`memory_get` 支持唯一 id 前缀(≥8 字符,歧义报候选绝不猜测)与批量 `ids`(上限 10,逐条作用域检查,不可读条目只返回标记不带正文);DSH 注入行携带 16 字符记忆标识,模型可据此下钻。诚实口径:省的是单次检索 token 与长尾,不是端到端倍数。
11
+ - **检索可按项目身份过滤**:`memory_search` 增可选 `project` 参数(UUID 或已登记别名),项目作用域记忆可被召回;别名解析**只查不建**,未登记报错并指引 `project_resolve`;携带项目身份不放宽设备/Agent/读允许名单检查。DSH 插件新增 `projectPath` 配置:懒解析一次并缓存,解析失败降级为不带项目召回并在面板如实提示;未配置时行为与从前逐字节一致。
12
+ - **`cairn sync push` 推送前提示上行缺口**:推送前做一次只读缺口检查(与 `doctor` / `backfill` 共用 `findUpstreamGap`),有缺口就向 stderr 报条数并说明「这些记忆尚未入队,本次推送不包含它们」、指向 `cairn sync backfill --apply`;推送照常执行、退出码不变、不入队,零缺口时完全静默。此前缺口只出现在 `doctor` 的 `notes` 里,不主动查就不知道。
13
+ - **受限的备份对象删除(`DELETE /chunks/<key>`)**:syncd 只放行解码后含 `/backups/` 的对象,同步链的 chunk/manifest 一律 403(只追加语义,删了会让对端拉取永久卡在缺口);删除复用既有 `safeKey()` 防穿越,对象不存在也返回 200(幂等)。`/manifests/` 不开放删除。
14
+ - **`cairn backup --purge-remote <name>`**:显式删除单个远端备份对象,删前打印对象名与大小;远端不支持删除(旧版 syncd)时明确报错,不做假成功。
15
+ - **保留策略在 syncd 后端真正生效**:`SyncdRemoteStore.deleteObject` 接通后,超出保留份数的旧备份会被实际淘汰;旧版 syncd 的 404 被识别为「不支持删除」并降级为 `pruneWarning`(不会静默假装已清理)。
16
+
17
+ ## [Plugin 0.5.0] - 2026-11-13
18
+
19
+ 注入行带记忆标识、面板作用域徽章、项目身份召回。需要内核 0.6.0 配合(检索条目为预览形状)。
20
+
21
+ ### Added
22
+ - **注入行携带记忆标识**:格式 `[<id 前 16 字符>|<kind>] <预览>`,模型看到「有这条记忆」后可据此调 `memory_get` 下钻全文。为什么是 16:uuidv7 前 12 hex 是毫秒时间戳,同一毫秒写入的记忆共享前 ≥13 字符,8 字符前缀在新建库上必然歧义。
23
+ - **面板作用域徽章**:左栏注入条目与右栏活动记录展示作用域标签(device 类警示色调),一眼分清「这条会跨设备」。
24
+ - **项目身份召回**:新增 `projectPath` 配置(路径或 git URL 别名)——配置后自动召回携带项目标识,项目作用域记忆可被召回;解析失败**降级**为不带项目召回并在面板状态卡如实提示;未配置时行为与从前逐字节一致。
25
+ - **注入闸 fail-closed**:注入前过滤基于内核返回的真实敏感度/同步策略判定;标签缺失(半更新/异常返回)宁可漏注不错注,被拦条数计入面板「已过滤」。
26
+
27
+ ### Changed
28
+ - 召回命中改用内核 0.6.0 的预览形状(线协议 `preview` 替代全文 `content`),映射在 `toRecallHit` 单点完成——顺带修掉了「直接把线协议条目当 RecallHit 用、snake/camel 恒读 undefined」的隐性错误。
29
+
30
+ ## [0.5.0] - 2026-11-12
31
+
32
+ 项目身份与作用域治理、AI 提案卡、设备备份上云。四个 OpenSpec 变更归档,主规格 10/10 严格通过。
33
+
34
+ ### Added
35
+ - **设备备份的云端加密容灾(`cairn backup --upload`)**:本地一致性快照用设备专属密钥加密后上传到远端(独立前缀 `backups/<设备>/`,与同步事件链互不干扰)。只有生成它的设备能解开(密钥派生混入 deviceId,其他设备拿到密文也无密钥材料);保留策略默认保留最近 5 份、只淘汰本设备前缀且删除前列出(syncd 暂无 DELETE 路由,诚实降级为只上传不删除)。`backup --list-remote` 列出本设备备份;`restore --from-remote` 下载 → 解密 → sha256 比对 → 快照校验后还原,**默认到新路径**,覆盖当前库必须 `--force` 且自动先备份当前库。
36
+ - **AI 修订提案(方案卡,`cairn revision`)**:Agent 针对批注出具「改什么、为什么改」的结构化提案(MCP `revision_propose` / `revision_list`),人通过 CLI `revision list|show|apply|reject` 或控制台「修订提案」视图确认后才生效。采纳复用既有 `reviseMemory` 修订链(不可变历史 + 秘密复检 + 上行入队),权威记 `user_confirmed`;版本一致性两层校验,记忆已被改过则拒绝并标陈旧;工具面**刻意不含 apply**——Agent 只有提案权,没有写入权。
37
+ - **作用域迁移(`cairn rescope`)**:活动记忆可换作用域,不删不重建——id、修订历史、证据链、权威级别全保留,只改 `scope_id`。安全阀:冲突状态拒绝、缺 projectId 拒绝(不静默降级)、`user_explicit` 记忆需 `--force`。迁移与 outbox 重建同事务:作废旧作用域 pending 上行、按新作用域重新入队。批量 `--ids-file` 逐条报告,单条失败不中断;`--pending` 处理控制台「需迁移作用域」批注(先列清单再逐条执行)。退出码合同:用法 2 / 治理拒绝 3 / 冲突 4。
38
+ - **`scope_exit` 迁出通知事件**(schema v6):记忆迁出可同步作用域时,对端把本地副本标为「不再持有」(archived + meta 标记,**无墓碑、不删数据**),检索与投影不再返回;迁回时强制重发修订快照(`reentry` 标记)自动解除标记;迟到修订按幂等跳过;旧版本收到未知事件类型跳过并审计、不阻断整链。云端既有密文不随迁出删除。
39
+ - **批注类别 `needs_rescope`**:控制台可标记「需迁移作用域」,与 `pending_forget` 同一哲学——批注只表达意图,执行在终端 `cairn rescope --pending`。
40
+ - **稳定的项目身份(UUID + 别名)**:项目主键改为 UUIDv7,路径与 git 地址只作为 `project.aliases` 里的别名。仓库改名(GitHub → Gitee、org 改名)或换设备改路径后,追加一条别名即可让新旧地址解析到同一个项目,既有记忆归属不变。新增 `cairn project resolve|list`、`cairn project alias add <project-id> <path-or-url>`,以及 MCP 工具 `project_resolve` / `project_list`——CLI 与 MCP 共用 `src/store/projects.ts` 同一实现。
41
+ - **别名归一化**:`https://Host/o/r.git`、`git@host:o/r.git`、`ssh://git@host/o/r.git` 视为同一项目(去凭据、host 小写、去 `.git`);路径统一盘符大小写与分隔符并去尾斜杠,但**保留目录名大小写**(Linux 上 `Proj` 与 `proj` 是两个目录)。不做模糊匹配、不校验路径是否存在(跨设备解析必需)、不自动上溯父目录。
42
+ - **别名冲突拒绝**:把已属于其他项目的别名追加到当前项目时抛 `E_CONFLICT_STATE`(退出码 4)并报告归属,不改任何数据;别名追加写 `project` 类目审计。
43
+
44
+ - **记忆批注与待处置队列(WebUI 标注 → Agent 处置)**:控制台新增「批注」视图;记忆列表支持多选批量标记,记忆详情可对单条写下处置意见(需要修改 / 需要合并 / 可以删除 / 存疑待查 / 无需处理 / 标记待删)。批注落在 `<home>/console/annotations.json`,**不建表、不参与云同步、不进入上行包**;记忆正文、状态与修订链完全不动。记忆修订后批注标「意见可能已过时」并灰显(不删)。
45
+ - **`cairn forget --pending [--dry-run]`**:WebUI 只能把记忆标为待删;真正删除只在这个终端入口执行,且**先打印全部待删清单(id + 摘要 + 标注时间)再逐条遗忘并逐条报告**。删除复用既有 `forgetMemory`,走同一套 tombstone 与 outbox 上行语义。
46
+ - **MCP `memory_annotations_list` / `memory_annotation_resolve`**:Agent 可拉取用户的批注并按 `resolved` / `ignored` 回写;读取不返回记忆正文全文,回写只改批注状态并记录处置者与时间。
47
+ - **`cairn doctor` 的待办批注提示**:只进 `notes` 一行,不进 `problems`、不改退出码。
48
+ - 批注写入前复用 `scanText`:命中秘密或注入规则即拒绝,不回显原文、不脱敏保存。
49
+
50
+ ### Changed
51
+
52
+ - 新建项目默认显示名取归一化后的别名(原始 URL 可能带凭据,不落 `project.name`)。已有项目行与其 `id` 一律不动。
53
+
54
+ ## [Plugin 0.4.2] - 2026-11-12
55
+
56
+ DSH 插件:上下文压缩后重注入。
57
+
58
+ ### Added
59
+
60
+ - **DSH 插件压缩后重注入**(`@carloswon/cairn-dsh-memory`):插件在本会话内追踪「涉及过的记忆」——注入过的,以及经 MCP `memory_get` / `memory_add` / `memory_update` 读过写过的;`compaction/end`(无 `error`)时按独立预算(`budgetBytes × reinjectBudgetRatio`,默认一半)重渲染并在下一步 `pre-step` 投递,不依赖下一句是否命中关键词。表头与常规召回措辞不同;重注入的 id 立刻回填去重集合,避免下一步重复注入;追踪集合纯内存、上限 `trackMax`(默认 200,超出按最近使用淘汰)。压缩失败不重注入、不清去重。回滚:`reinjectOnCompaction: false`。
61
+
62
+ ### Changed
63
+
64
+ - 插件版本与内核不再强绑:内核 0.5.0 与插件 0.4.2 各自独立发版,部署时按各自版本对齐。
65
+
66
+ ## [Plugin 0.4.1] - 2026-11-10
67
+
68
+ 修复 `@carloswon/cairn-dsh-memory@0.4.0` 导致 DSH 启动进入恢复模式的缺陷。
69
+
70
+ ### Fixed
71
+
72
+ - **插件包 0.4.0 不可用**:`src/client.js` 的 `window.__ModuleLoader__.load({ id })` 仍注册改名前的短名
73
+ `cairn-dsh-memory`,而宿主按 `package.json` 的 `name`(`@carloswon/cairn-dsh-memory`)建立 client 图行。
74
+ 两者不一致时 `ClientEntries.arrive()` 查不到该 factory,会退回单包 URL **再执行一次** bundle,
75
+ 第二次 `register()` 撞到已存在的 id 并抛出
76
+ `duplicate factory registration for "cairn-dsh-memory"`,整个 client entry 无法激活,
77
+ 渲染进程重试耗尽后进入恢复模式。现注册 id 改为与包名完全一致。
78
+ - 注册 id 必须等于包名这一点已写入 `client.js` 注释,避免再次改包名时漏改。
79
+
80
+ > 0.4.0 已在 npm 标记为 deprecated,仅用于留档。
81
+
5
82
  ## [0.4.0] - 2026-11-10
6
83
 
7
84
  上行入队完备性、冷启动对账,以及 DSH 插件召回记录的口径修正。
package/README.md CHANGED
@@ -10,6 +10,22 @@ Your memory lives in a local SQLite file you own. Every device holds the authori
10
10
 
11
11
  ---
12
12
 
13
+ ## 这个项目不是什么
14
+
15
+ 同类项目里已经有好几个名字带 "cairn" 或 "dsh" 的记忆插件,先说清区别,免得装错:
16
+
17
+ | | Cairn(本项目) | DSH 专用记忆插件 |
18
+ |---|---|---|
19
+ | **适用范围** | **跨 Agent、跨设备**:WorkBuddy / CodeBuddy / Cursor / Copilot / ZCode / DSH 共用一个库 | 只服务 DSH 一个宿主 |
20
+ | **权威副本** | 本机 SQLite;换 Agent 不换记忆 | 通常绑定该宿主的运行时 |
21
+ | **DSH 插件角色** | **只是一个壳子**(`@carloswon/cairn-dsh-memory`),通过 MCP 调用内核 | 插件本身就是全部实现 |
22
+ | **没装 DSH 时** | 内核照常工作:CLI、MCP、其他宿主都能用 | 不可用 |
23
+ | **云端** | 可选加密中继,本地永远可用 | 视各自实现 |
24
+
25
+ 一句话:**DSH 插件是 Cairn 的众多入口之一,不是 Cairn 本身。** 只装插件不装内核,召回的永远是空。
26
+
27
+ ---
28
+
13
29
  ## 为什么需要它
14
30
 
15
31
  每个 Agent 都在自己攒记忆:WorkBuddy 有一份、ZCode 有一份、DSH 又有一份。你换一台机器、换一个 Agent,记忆就断了;你无法解释某条记忆从哪来,也无法确认它真的被删掉。
@@ -156,4 +172,4 @@ npm run test:real # 真实 OBS 云同步往返(需五个 OBS_* 变量齐
156
172
 
157
173
  ## 许可证
158
174
 
159
- MIT。见 [LICENSE](./LICENSE)。
175
+ MIT。见 [LICENSE](./LICENSE)。
@@ -107,6 +107,10 @@ export interface SearchResultRecord {
107
107
  /** 未验证导入不得显示为用户确认事实(spec agent-onboarding) */
108
108
  unverifiableImport: boolean;
109
109
  expired: boolean;
110
+ /** 命中记忆的人读作用域名(scope 表 preset);作用域行缺失时缺省(add-memory-scope-visibility)。 */
111
+ scopePreset?: string;
112
+ /** 命中记忆作用域的同步策略(决定能否出本机)。 */
113
+ syncPolicy?: string;
110
114
  }
111
115
  export type SecretKind = 'private_key' | 'aws_access_key_id' | 'aws_secret_access_key' | 'github_token' | 'generic_api_key' | 'bearer_token' | 'jwt' | 'password_assignment' | 'connection_string';
112
116
  export interface SecretFinding {
@@ -0,0 +1,80 @@
1
+ import { CairnStore } from '../store/open.js';
2
+ /**
3
+ * 修订提案(方案卡,OpenSpec: add-agent-managed-revision)。
4
+ *
5
+ * 核心边界(design D1):Agent 拿提案权,人拿写入权。本文件**从不写 memory / memory_revision /
6
+ * outbox**——它只读写 `<home>/console/revision-proposals.json` 这份派生数据。
7
+ * 应用(改记忆)只发生在 CLI 与本地控制台,走既有的 reviseMemory(不可变修订链 + 秘密复检 + 审计),
8
+ * 不在这里新造写入路径(D2)。
9
+ *
10
+ * 新鲜度(D3):卡片记提出时的 currentRevisionId,应用时对比,不一致拒绝并标 stale——
11
+ * 与 reviseMemory 的 expectedCurrentRevisionId 是同一套乐观锁语义,不另造一份。
12
+ *
13
+ * 秘密在生成时就扫(D6):卡片要落盘给人看,等应用才查等于已经泄露。
14
+ */
15
+ export declare const REVISIONS_FILE = "revision-proposals.json";
16
+ export declare const REVISIONS_VERSION = 1;
17
+ export declare const REVISION_STATUSES: readonly ["pending", "applied", "rejected", "stale"];
18
+ export type RevisionStatus = (typeof REVISION_STATUSES)[number];
19
+ export interface RevisionProposalRecord {
20
+ id: string;
21
+ memoryId: string;
22
+ /** 提出时的当前修订 id;应用前用它判陈旧(与 expectedCurrentRevisionId 同语义)。 */
23
+ revisionIdAtPropose: string | null;
24
+ /** 关联批注(软引用,可选;批注可能已被处置,不校验存在性)。 */
25
+ annotationId: string | null;
26
+ /** 改前摘要(首行截断;sensitive / tombstoned 记忆不给摘要)。改后永远是完整正文。 */
27
+ beforeExcerpt: string | null;
28
+ /** 拟改后的完整正文。 */
29
+ afterContent: string;
30
+ reason: string;
31
+ proposedBy: string;
32
+ proposedAt: string;
33
+ status: RevisionStatus;
34
+ resolvedAt: string | null;
35
+ resolvedBy: string | null;
36
+ rejectReason: string | null;
37
+ }
38
+ export interface RevisionProposalView extends RevisionProposalRecord {
39
+ /** 展示时判定:记忆的当前修订已不是提出时的那一份。 */
40
+ stale: boolean;
41
+ memoryStatus: string | null;
42
+ memoryExists: boolean;
43
+ }
44
+ export interface RevisionQuery {
45
+ status?: string;
46
+ memoryId?: string;
47
+ limit?: number;
48
+ }
49
+ interface RevisionsFile {
50
+ version: number;
51
+ updatedAt: string;
52
+ items: RevisionProposalRecord[];
53
+ }
54
+ export declare function revisionsPath(home: string): string;
55
+ /** 坏文件按空处理:提案是派生数据,读不出来不阻塞控制台。 */
56
+ export declare function loadRevisionsFile(home: string): RevisionsFile;
57
+ export interface ProposeInput {
58
+ memoryId: string;
59
+ afterContent: string;
60
+ reason: string;
61
+ annotationId?: string;
62
+ proposedBy: string;
63
+ }
64
+ /**
65
+ * 生成方案卡。只读记忆、只写提案文件:正文/状态/权威/修订数/作用域一个都不碰
66
+ * (spec「生成提案不改记忆」)。afterContent 与 reason 都要过扫描,命中拒绝整条且不落盘。
67
+ */
68
+ export declare function proposeRevision(store: CairnStore, input: ProposeInput): RevisionProposalRecord;
69
+ /**
70
+ * 读取提案并就地判定陈旧(对比当前修订;不删任何提案)。
71
+ * 默认只返回待审(design 威胁模型:列表默认只给待审,避免 Agent 用长列表耗尽注意力);
72
+ * `status: 'all'` 返回全部。
73
+ */
74
+ export declare function readRevisionProposals(store: CairnStore, query?: RevisionQuery): RevisionProposalView[];
75
+ export declare function getRevisionProposal(store: CairnStore, id: string): RevisionProposalView | null;
76
+ /** 终态转换:pending → applied / rejected / stale。返回更新后的记录。 */
77
+ export declare function resolveRevisionProposal(store: CairnStore, id: string, to: Exclude<RevisionStatus, 'pending'>, by: string, rejectReason?: string): RevisionProposalRecord;
78
+ /** doctor 用计数:待审提案数(不进 problems)。 */
79
+ export declare function countPendingRevisions(home: string): number;
80
+ export {};
@@ -0,0 +1,243 @@
1
+ import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import { randomUUID } from 'node:crypto';
4
+ import { err } from '../core/errors.js';
5
+ import { nowIso } from '../core/time.js';
6
+ import { scanText } from '../core/secrets.js';
7
+ /**
8
+ * 修订提案(方案卡,OpenSpec: add-agent-managed-revision)。
9
+ *
10
+ * 核心边界(design D1):Agent 拿提案权,人拿写入权。本文件**从不写 memory / memory_revision /
11
+ * outbox**——它只读写 `<home>/console/revision-proposals.json` 这份派生数据。
12
+ * 应用(改记忆)只发生在 CLI 与本地控制台,走既有的 reviseMemory(不可变修订链 + 秘密复检 + 审计),
13
+ * 不在这里新造写入路径(D2)。
14
+ *
15
+ * 新鲜度(D3):卡片记提出时的 currentRevisionId,应用时对比,不一致拒绝并标 stale——
16
+ * 与 reviseMemory 的 expectedCurrentRevisionId 是同一套乐观锁语义,不另造一份。
17
+ *
18
+ * 秘密在生成时就扫(D6):卡片要落盘给人看,等应用才查等于已经泄露。
19
+ */
20
+ export const REVISIONS_FILE = 'revision-proposals.json';
21
+ export const REVISIONS_VERSION = 1;
22
+ export const REVISION_STATUSES = ['pending', 'applied', 'rejected', 'stale'];
23
+ export function revisionsPath(home) {
24
+ return join(home, 'console', REVISIONS_FILE);
25
+ }
26
+ function emptyFile() {
27
+ return { version: REVISIONS_VERSION, updatedAt: nowIso(), items: [] };
28
+ }
29
+ function isStatus(v) {
30
+ return typeof v === 'string' && REVISION_STATUSES.includes(v);
31
+ }
32
+ function normalizeRecord(raw) {
33
+ if (raw == null || typeof raw !== 'object' || Array.isArray(raw))
34
+ return null;
35
+ const r = raw;
36
+ const id = typeof r.id === 'string' ? r.id : '';
37
+ const memoryId = typeof r.memoryId === 'string' ? r.memoryId : '';
38
+ const afterContent = typeof r.afterContent === 'string' ? r.afterContent : '';
39
+ if (id.length === 0 || memoryId.length === 0 || afterContent.length === 0)
40
+ return null;
41
+ return {
42
+ id,
43
+ memoryId,
44
+ revisionIdAtPropose: typeof r.revisionIdAtPropose === 'string' ? r.revisionIdAtPropose : null,
45
+ annotationId: typeof r.annotationId === 'string' ? r.annotationId : null,
46
+ beforeExcerpt: typeof r.beforeExcerpt === 'string' ? r.beforeExcerpt : null,
47
+ afterContent,
48
+ reason: typeof r.reason === 'string' ? r.reason : '',
49
+ proposedBy: typeof r.proposedBy === 'string' ? r.proposedBy : 'unknown',
50
+ proposedAt: typeof r.proposedAt === 'string' ? r.proposedAt : nowIso(),
51
+ status: isStatus(r.status) ? r.status : 'pending',
52
+ resolvedAt: typeof r.resolvedAt === 'string' ? r.resolvedAt : null,
53
+ resolvedBy: typeof r.resolvedBy === 'string' ? r.resolvedBy : null,
54
+ rejectReason: typeof r.rejectReason === 'string' ? r.rejectReason : null,
55
+ };
56
+ }
57
+ /** 坏文件按空处理:提案是派生数据,读不出来不阻塞控制台。 */
58
+ export function loadRevisionsFile(home) {
59
+ const p = revisionsPath(home);
60
+ if (!existsSync(p))
61
+ return emptyFile();
62
+ try {
63
+ const parsed = JSON.parse(readFileSync(p, 'utf8'));
64
+ if (parsed == null || typeof parsed !== 'object' || !Array.isArray(parsed.items))
65
+ return emptyFile();
66
+ const items = [];
67
+ for (const raw of parsed.items) {
68
+ const rec = normalizeRecord(raw);
69
+ if (rec != null)
70
+ items.push(rec);
71
+ }
72
+ return {
73
+ version: Number(parsed.version ?? REVISIONS_VERSION),
74
+ updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : nowIso(),
75
+ items,
76
+ };
77
+ }
78
+ catch {
79
+ return emptyFile();
80
+ }
81
+ }
82
+ /** 原子写入:临时文件 + rename(与 annotations.ts 同姿势,避开 Windows 句柄抖动)。 */
83
+ function saveRevisionsFile(home, data) {
84
+ const p = revisionsPath(home);
85
+ mkdirSync(join(home, 'console'), { recursive: true });
86
+ const tmp = `${p}.tmp-${process.pid}-${Date.now()}`;
87
+ writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf8');
88
+ let lastError = null;
89
+ for (let attempt = 0; attempt < 2; attempt++) {
90
+ try {
91
+ renameSync(tmp, p);
92
+ return;
93
+ }
94
+ catch (e) {
95
+ lastError = e;
96
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 30);
97
+ }
98
+ }
99
+ try {
100
+ rmSync(tmp, { force: true });
101
+ }
102
+ catch {
103
+ /* ignore */
104
+ }
105
+ throw err('E_IO', `写入修订提案文件失败: ${lastError?.message ?? '未知错误'}`);
106
+ }
107
+ function excerptOf(row) {
108
+ if (String(row['sensitivity']) === 'sensitive' || String(row['status']) === 'tombstoned')
109
+ return null;
110
+ const firstLine = String(row['content']).split('\n')[0]?.trim() ?? '';
111
+ if (firstLine.length === 0)
112
+ return null;
113
+ return firstLine.length > 80 ? `${firstLine.slice(0, 80)}…` : firstLine;
114
+ }
115
+ function scanProposalError(scan) {
116
+ if (scan.findings.length > 0) {
117
+ return err('E_SECRET_DETECTED', '修订提案疑似包含秘密,已拒绝生成(不回显原文)', {
118
+ findings: scan.findings.map((f) => ({ kind: f.kind, masked: f.masked })),
119
+ injectionFindings: scan.injectionFindings.map((f) => ({ kind: f.kind, rule: f.rule })),
120
+ });
121
+ }
122
+ return err('E_INJECTION_SUSPECTED', '修订提案疑似提示注入指令,已拒绝生成', {
123
+ injectionFindings: scan.injectionFindings.map((f) => ({ kind: f.kind, rule: f.rule })),
124
+ });
125
+ }
126
+ /**
127
+ * 生成方案卡。只读记忆、只写提案文件:正文/状态/权威/修订数/作用域一个都不碰
128
+ * (spec「生成提案不改记忆」)。afterContent 与 reason 都要过扫描,命中拒绝整条且不落盘。
129
+ */
130
+ export function proposeRevision(store, input) {
131
+ store.assertWritable();
132
+ const memoryId = input.memoryId.trim();
133
+ if (memoryId.length === 0)
134
+ throw err('E_VALIDATION', 'memoryId 不能为空');
135
+ const afterContent = input.afterContent.trim();
136
+ if (afterContent.length === 0)
137
+ throw err('E_VALIDATION', '拟改后的正文不能为空');
138
+ const reason = input.reason.trim();
139
+ if (reason.length === 0)
140
+ throw err('E_VALIDATION', '改动理由不能为空(人要看懂为什么改)');
141
+ // D6:落盘即可能泄露,所以秘密与注入扫描在生成时就做。
142
+ const scan = scanText(afterContent);
143
+ if (!scan.clean)
144
+ throw scanProposalError(scan);
145
+ const reasonScan = scanText(reason);
146
+ if (!reasonScan.clean)
147
+ throw scanProposalError(reasonScan);
148
+ const mem = store.memories.require(memoryId);
149
+ const rec = {
150
+ id: `rev_${randomUUID()}`,
151
+ memoryId,
152
+ revisionIdAtPropose: mem.currentRevisionId,
153
+ annotationId: input.annotationId?.trim() || null,
154
+ beforeExcerpt: excerptOf(mem),
155
+ afterContent,
156
+ reason,
157
+ proposedBy: input.proposedBy,
158
+ proposedAt: nowIso(),
159
+ status: 'pending',
160
+ resolvedAt: null,
161
+ resolvedBy: null,
162
+ rejectReason: null,
163
+ };
164
+ const file = loadRevisionsFile(store.paths.home);
165
+ file.items.push(rec);
166
+ file.updatedAt = nowIso();
167
+ saveRevisionsFile(store.paths.home, file);
168
+ // 审计只记标识与动作:拟改正文不进审计(摘要纪律)。
169
+ store.audit.record('revision', 'proposed', { type: 'memory', id: memoryId }, {
170
+ proposalId: rec.id,
171
+ annotationId: rec.annotationId,
172
+ proposedBy: rec.proposedBy,
173
+ });
174
+ return rec;
175
+ }
176
+ /**
177
+ * 读取提案并就地判定陈旧(对比当前修订;不删任何提案)。
178
+ * 默认只返回待审(design 威胁模型:列表默认只给待审,避免 Agent 用长列表耗尽注意力);
179
+ * `status: 'all'` 返回全部。
180
+ */
181
+ export function readRevisionProposals(store, query = {}) {
182
+ const file = loadRevisionsFile(store.paths.home);
183
+ const statusFilter = query.status == null || query.status === '' ? 'pending' : query.status;
184
+ const out = [];
185
+ for (const rec of file.items) {
186
+ if (rec.status !== statusFilter && statusFilter !== 'all')
187
+ continue;
188
+ if (query.memoryId != null && rec.memoryId !== query.memoryId)
189
+ continue;
190
+ const row = store.db.get('SELECT current_revision_id, status FROM memory WHERE id = ?', rec.memoryId);
191
+ const currentRevisionId = row ? (row['current_revision_id'] ?? null) : null;
192
+ const stale = rec.status === 'pending' && currentRevisionId !== rec.revisionIdAtPropose;
193
+ out.push({
194
+ ...rec,
195
+ stale,
196
+ memoryStatus: row ? String(row['status']) : null,
197
+ memoryExists: row != null,
198
+ });
199
+ }
200
+ out.sort((a, b) => (a.proposedAt < b.proposedAt ? 1 : -1));
201
+ return query.limit != null && query.limit > 0 ? out.slice(0, query.limit) : out;
202
+ }
203
+ export function getRevisionProposal(store, id) {
204
+ return readRevisionProposals(store, { status: 'all' }).find((r) => r.id === id) ?? null;
205
+ }
206
+ /** 终态转换:pending → applied / rejected / stale。返回更新后的记录。 */
207
+ export function resolveRevisionProposal(store, id, to, by, rejectReason) {
208
+ store.assertWritable();
209
+ if (by.trim().length === 0)
210
+ throw err('E_VALIDATION', '处置者不能为空');
211
+ if (to === 'rejected' && (rejectReason ?? '').trim().length === 0) {
212
+ throw err('E_VALIDATION', '拒绝理由不能为空');
213
+ }
214
+ const file = loadRevisionsFile(store.paths.home);
215
+ const rec = file.items.find((x) => x.id === id);
216
+ if (rec == null)
217
+ throw err('E_NOT_FOUND', `提案不存在: ${id}`);
218
+ // 应用只允许从待审发起(陈旧卡必须重新生成,不能硬应用);
219
+ // 拒绝允许从待审与陈旧发起——陈旧卡也是人要不要的东西,否则永远清不掉。
220
+ if (to !== 'rejected' && rec.status !== 'pending') {
221
+ throw err('E_CONFLICT_STATE', `提案已是终态(${rec.status}),不能重复处置`);
222
+ }
223
+ if (to === 'rejected' && (rec.status === 'applied' || rec.status === 'rejected')) {
224
+ throw err('E_CONFLICT_STATE', `提案已是终态(${rec.status}),不能重复处置`);
225
+ }
226
+ rec.status = to;
227
+ rec.resolvedAt = nowIso();
228
+ rec.resolvedBy = by;
229
+ if (to === 'rejected')
230
+ rec.rejectReason = (rejectReason ?? '').trim();
231
+ file.updatedAt = nowIso();
232
+ saveRevisionsFile(store.paths.home, file);
233
+ store.audit.record('revision', to, { type: 'memory', id: rec.memoryId }, {
234
+ proposalId: rec.id,
235
+ by,
236
+ });
237
+ return rec;
238
+ }
239
+ /** doctor 用计数:待审提案数(不进 problems)。 */
240
+ export function countPendingRevisions(home) {
241
+ return loadRevisionsFile(home).items.filter((x) => x.status === 'pending').length;
242
+ }
243
+ //# sourceMappingURL=revision-proposal.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"revision-proposal.js","sourceRoot":"","sources":["../../../src/governance/revision-proposal.ts"],"names":[],"mappings":"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"}
@@ -7,7 +7,9 @@ import { ExportInput, ExportOutput } from '../retrieval/export.js';
7
7
  import { RunOnceSummary } from '../jobs/worker.js';
8
8
  import { loadVaultConfig } from '../sync/vault.js';
9
9
  import { BackfillReport } from '../sync/backfill.js';
10
+ import { type RevisionProposalRecord, type RevisionProposalView, type RevisionQuery } from '../governance/revision-proposal.js';
10
11
  import { ImportOutcome } from '../onboarding/import.js';
12
+ import { type AnnotationQuery, type AnnotationRecord, type AnnotationView, type BatchAnnotateResult } from './console/annotations.js';
11
13
  import { Judgement, WriteAction } from '../onboarding/judgement.js';
12
14
  import { BatchProgress, BatchChunkItem } from '../onboarding/batches.js';
13
15
  import type { SkippedItem } from '../onboarding/batches.js';
@@ -152,12 +154,31 @@ export declare class AppService {
152
154
  reviseMemory(id: string, newContent: string, opts?: {
153
155
  reason?: string;
154
156
  expectedCurrentRevisionId?: string;
157
+ authority?: Authority;
155
158
  }): {
156
159
  memory: MemoryRecord;
157
160
  revision: RevisionRecord;
158
161
  };
159
162
  forgetMemory(id: string, reason: string | null): MemoryRecord;
160
163
  archiveMemory(id: string): MemoryRecord;
164
+ annotateMemory(input: {
165
+ memoryId: string;
166
+ disposition: string;
167
+ note?: string;
168
+ }): AnnotationRecord;
169
+ annotateBatch(input: {
170
+ memoryIds: string[];
171
+ disposition: string;
172
+ note?: string;
173
+ }): BatchAnnotateResult;
174
+ listAnnotations(query?: AnnotationQuery): AnnotationView[];
175
+ resolveAnnotation(input: {
176
+ id: string;
177
+ status: string;
178
+ by?: string;
179
+ }): AnnotationRecord;
180
+ /** 待删清单:只读查询,永不执行删除(删除入口是 `cairn forget --pending`)。 */
181
+ listPendingForget(): AnnotationView[];
161
182
  /**
162
183
  * 候选晋升(add-candidate-promote-command)。
163
184
  *
@@ -176,13 +197,73 @@ export declare class AppService {
176
197
  scope: ScopeRow;
177
198
  previousScopeId: string;
178
199
  };
200
+ /**
201
+ * 作用域迁移(add-scope-migration):active 记忆可改归属,与晋升刻意区分——
202
+ * 不改 status / authority / 正文。同一事务内完成:迁移 scope_id、作废旧 pending
203
+ * 上行任务、按目标作用域重新入队、迁出且曾同步过时排一条迁出通知任务。
204
+ *
205
+ * 安全阀(design D4):冲突状态拒绝(状态不明确);墓碑拒绝;缺 projectId 由
206
+ * resolveScope 抛 E_VALIDATION(不静默降级);user_explicit 需 force(减速带不是禁止)。
207
+ */
208
+ rescopeMemory(id: string, opts: {
209
+ scopePreset: ScopeSelection['preset'];
210
+ projectId?: string;
211
+ projectName?: string;
212
+ agentId?: string;
213
+ ttlDays?: number;
214
+ force?: boolean;
215
+ }): {
216
+ memory: MemoryRecord;
217
+ scope: ScopeRow;
218
+ previousScopeId: string;
219
+ willLoseSync: boolean;
220
+ scopeExitEnqueued: boolean;
221
+ };
222
+ /** 待迁移清单:只读查询,永不执行迁移(执行入口是 `cairn rescope --pending`)。 */
223
+ listPendingRescope(): AnnotationView[];
224
+ /** 生成方案卡(Agent 经 MCP 调用;本地 CLI 也可用)。只写卡,不碰记忆。 */
225
+ proposeRevisionProposal(input: {
226
+ memoryId: string;
227
+ afterContent: string;
228
+ reason: string;
229
+ annotationId?: string;
230
+ }): RevisionProposalRecord;
231
+ /** 提案列表(默认只返回待审;status='all' 返回全部)。 */
232
+ listRevisionProposals(query?: RevisionQuery): RevisionProposalView[];
233
+ /**
234
+ * 采纳提案(人的显式动作:CLI 或本地控制台点击;MCP 不提供此入口)。
235
+ *
236
+ * 版本一致性:目标记忆的当前修订必须仍是提出时的那一份;不一致 → 提案标 stale
237
+ * 并拒绝(spec「记忆已被改过」)。一致 → reviseMemory(expectedCurrentRevisionId
238
+ * 双保险)→ 权威 user_confirmed → 提案标 applied。
239
+ */
240
+ applyRevisionProposal(id: string): {
241
+ proposal: RevisionProposalRecord;
242
+ memory: MemoryRecord;
243
+ revision: RevisionRecord;
244
+ };
245
+ /** 拒绝提案:记录理由与时间,不删除提案,记忆完全不变。 */
246
+ rejectRevisionProposal(id: string, reason: string): RevisionProposalRecord;
179
247
  /** 拒绝候选:转墓碑(不是物理删除),留审计理由;恢复需显式重做(design D4)。 */
180
248
  rejectCandidate(id: string, opts: {
181
249
  reason: string;
182
250
  }): {
183
251
  memory: MemoryRecord;
184
252
  };
185
- showMemory(id: string): MemoryDetail;
253
+ /**
254
+ * 记忆 id 解析:完整 id 直接使用;前缀必须唯一且 ≥8 字符,歧义时报候选完整标识
255
+ * (add-two-stage-memory-recall D3)——绝不猜测取其一。
256
+ */
257
+ private resolveMemoryId;
258
+ /**
259
+ * MCP memory_get 批量:逐条解析与作用域检查。不可读 / 不存在 / 前缀歧义的条目
260
+ * 显式标记(readable:false 或 error),MUST NOT 返回其正文或任何可推断内容
261
+ * (spec scoped-retrieval「详情读取支持唯一前缀与批量」)。
262
+ */
263
+ showMemories(ids: string[]): {
264
+ results: unknown[];
265
+ };
266
+ showMemory(idOrPrefix: string): MemoryDetail;
186
267
  /** MCP memory_propose:只生成候选,绝不静默成为高权威活动记忆(memory-governance spec)。 */
187
268
  proposeCandidate(input: {
188
269
  content: string;