Claude Code CLI 2.1.235 Storage v5：32 个 namespace、写入合同与真实边界¶

版本：2.1.235 | 证据：目标版本 readable bundle 的 Static consumer 和 key/adapter 合同

Storage v5 不是一个“新数据库目录”的同义词。它首先是一套逻辑存储接口：业务代码用 typed key 描述 settings、task、plugin cache、mailbox、daemon 等状态，再由可选 adapter 实现 read、write、update、list、subscribe 和发布纪律。这个版本最关键的边界是：bundle 内的 tryCreateV5Backend() 函数体直接返回空，不能据此声称独立本地 CLI 已经自行创建并全面启用 v5 backend。

60 秒理解这套存储层¶

读者问题： 为什么源码里到处能看到 storageV5 和 32 个 namespace，本机文件却仍在原来的 .claude 路径；为什么有的写入叫 atomic，有的又是 in-place？

一句话模型： 业务 consumer 先把状态编码成受校验的逻辑 key，在收到外部注入的 adapter 时用前置条件和 publish discipline 更新值，否则按各 consumer 的既有磁盘路径回退；namespace 只定义寻址和边界，不自动提供统一锁、迁移或保留策略。

贯穿场景：Claude Code 更新全局配置。consumer 先读 globalConfig，在进程内写队列中合并变化；有 adapter 时用 followAtomic 写逻辑 key，并订阅外部变化，同时保留 backup/corrupted recovery copies 和裁剪旧副本；没有 adapter 时继续使用既有配置文件路径。这里的可靠性来自 globalConfig consumer 自己的队列、备份和恢复逻辑，不是所有 32 个 namespace 自动共享这些能力。

一、先划清“存在”和“启用”¶

tengu_hover_rest 只决定是否尝试使用¶

pinStorageV5() 读取 tengu_hover_rest，要求布尔值，并把本进程第一次决定 pin 住。后续再次读取到不同值只记录 conflict，仍保留首次决定。这样能避免同一进程前半段写旧路径、后半段突然切换 backend。

但 pin 后调用的 tryCreateV5Backend() 在 2.1.235 中是：

function tryCreateV5Backend() {
  if (!storageV5Enabled) return;
  return;
}

因此本版可证结论只有：

1. 客户端拥有完整 typed-key 与 adapter consumer；
2. feature flag 会在进程内 pin；
3. 许多调用链接受从外部 context 传入的 storageV5；
4. 本地独立构造函数没有创建 backend；
5. adapter 缺失时，大量 consumer 继续走既有文件路径或跳过 v5 专属分支。

不能从 namespace 清单倒推出“所有状态已经迁移”“本机存在一个隐藏数据库”“远端自动同步所有 .claude 文件”。adapter 的实际提供者、服务端实现和 rollout 条件需要 host/运行探针证明，保持 Boundary。

证据：feature pin 与空函数见 cli.readable.js 410908-410919；可选 adapter 在 Agent、compact、plugin、task、daemon 等 context 中向下传递。

二、typed key 解决什么问题¶

1. key 不是可拼接的路径字符串¶

key factory 返回形如：

{
  "namespace": "pluginCache",
  "marketplace": "source",
  "plugin": "name",
  "version": "version",
  "relPath": [".claude-plugin", "plugin.json"]
}

adapter 接收结构化 key，再决定怎样映射物理存储。业务代码不能把 ../../、绝对路径或带分隔符的单 segment 混进 key。relPath 也不是一条未经解析的字符串，而是 segment array。

2. 通用 segment 拒绝规则¶

每个必填 segment 必须是非空字符串，并拒绝：

• 只由点或空格组成的值；
• /、反斜线和 NUL；
• 大小写/尾随点空格归一化后命中保留设备名或 set-aside 形状；
• 内部临时形状 .<16 hex>.aside；
• relPath/agentRelPath 中任一非法 segment。

这不是普通输入美化，而是物理映射前的安全合同。Windows 设备名、大小写折叠、尾随点/空格、JSONL stream 与 session sibling 文件都可能让两个表面不同的 key 指到同一叶值，所以校验在 namespace 层统一完成。

3. namespace 专属校验¶

4. scope 和 key 是两种操作¶

key 精确指向一个值；scope 用于 list/deleteScope/listSubkeys 等集合操作。scope 不能携带已经把范围缩到一个 leaf 的字段，例如 task scope 只能按 list ID 缩小，不能带 task ID；mailbox scope 不能指定 teammate；cache scope 必须指定 store，但不能同时把 id 当范围。

这种区分防止一个看似“列目录”的 API 被偷偷用成跨项目或跨 session 的任意前缀扫描。

三、写协议：atomic 不是万能标签¶

1. 三种 publish discipline¶

publish discipline 由每次 write 传入，而不是 namespace 固定属性。同一 namespace 的不同文件可以选择不同纪律。

2. 四类前置条件¶

没有传 precondition 不应自动解释成 compare-and-swap。要判断并发安全，必须看具体 consumer 是否使用 update/updateText、显式 precondition、进程内队列或外部锁。

3. update/updateText 是原子读改写入口¶

mailbox 使用 updateText 把“读 inbox、合并/ack/清坏记录、写回”放进一次 adapter 更新。globalConfig 也有 update 路径，并在进程内串行化写请求。它们比“先 read 再 write”更能避免 lost update。

但不能把这个结论扩展到全部 namespace：大量 callsite 直接 write，有的写 item、有的 append stream、有的靠业务 owner 保证单 writer。2.1.235 没有证据显示每个 namespace 都有独立锁文件、统一 lease 或跨 key transaction。

四、物理叶值硬化¶

即使 logical key 合法，物理文件仍可能在检查与打开之间被替换。底层文件路径可见以下防护：

1. lstat 拒绝非普通文件；
2. open 使用 no-follow 能力，symlink 返回 ELOOP；
3. 拒绝目录、设备和其他非普通节点；
4. 拒绝 link count 表明存在第二个名字的 hard link；
5. 打开后再次核对对象仍位于原 key，拒绝 LeafMoved；
6. host 无法验证 hardened read 时返回 HardeningUnavailable，而不是假装成功；
7. value leaf 有 mode 和大小上限。

这类防护保护“某个 key 的 bytes 没被重定向到另一文件”，不等于内容可信。Plugin manifest、settings、mailbox 和 remote-settings 仍需各自 schema、来源和 policy 校验。

证据：key/scope 校验与 hardening 见 cli.readable.js 110185-110229、110250-110560；segment 基础规则见 38040-38090。

五、32 个 namespace 逐项参考¶

“真实 consumer”列只写目标 bundle 中能定位到的 reader/writer。没有足够 active callsite 的条目标 Boundary，不按名字补故事。

六、几个需要单独下钻的 namespace¶

transcript：逻辑追加流，物理文件会被条件重写¶

把 transcript 写成“append-only JSONL”只描述了正常写入接口，没有描述磁盘生命周期。2.1.235 的 writer 先按 entry 类型决定怎样追加，再在本地 GC 开启时执行 UUID 删除和 transcript compact；所以消息语义仍是事件流，物理 bytes 却会被截断、重组和原子替换。

两张策略表分别控制“追加什么”和“压实时留下什么”¶

策略表证据在 cli.readable.js 404545-404547。它解释了为什么压实不能简单写成“删除旧行”：某些消息要去重，某些状态要跨 boundary 保留最后值，某些引用要累计，错误裁剪会破坏 resume、fork、checkpoint 或 UI 状态。

触发阈值和自适应 backstop¶

• 实际文件小于 5 MiB 时不压实；这是 legacy stat.size 与 V5 size + torn tail 共用的最低门槛。
• writer 统计当前 session 自上次 compact 后新增的 bytes；初始 backstop 是 20 MiB。
• compact 若回收不到旧大小的 10%，backstop 翻倍，最高 160 MiB；回收达到 10% 则重置为 20 MiB，避免低收益频繁全文件扫描。
• 写入 compact boundary 一类需要立即清理的记录时，writer 会把 backstop 重置到 20 MiB 并在同一串行写队列请求 compact；普通追加则在累计 bytes 达阈值后触发。
• 慢速 UUID tombstone 清理只处理不超过 50 MiB 的 transcript；V5 慢路径按 1 MiB 分页。V5 fast path 用版本条件最多重试 3 次，随后放弃而不是覆盖并发 writer。

这些值分别对应 DEm=5 MiB、xfr=20 MiB、MEm=160 MiB、OEm=50 MiB、UlT=1 MiB，见 401217-401328、404491。

Legacy 文件路径：快照、保留完整尾行、fsync、原子换位¶

legacy compactor 先记录 inode/size，并抽样读取头部、中部、尾部各 4 KiB。快照尾字节不是换行时，它以 snapshot_mid_line 放弃，避免把 torn tail 当完整 JSONL。随后它只读取最初 size 范围，按策略表写入权限 0600 的临时文件；发布前再次检查 inode、size 未缩小且三段抽样未变化。

如果原文件在压实期间只发生尾部追加，compactor 会读取 snapshot 之后的增量，只把截止到最后一个换行的完整记录附到临时文件。这样可以保留并发尾追加，同时不发布半条 JSON。临时文件 fsync 后，它再次核对 inode 与抽样；任何中段修改、截断或文件替换都记为 source-changed（遥测值 source_changed）并删除临时文件。最后才通过原子 rename 替换目标，并重新追加 session metadata。这个协议保护的是同一文件的完整发布，不是跨文件事务。

Storage v5 路径：witness + 条件原子 replace¶

V5 先用 witness stat 取得 size、version 和 tornTailBytes。tornTailBytes > 0 直接按 snapshot_mid_line 放弃；否则按 4 MiB 页向前读取，只处理 snapshot size 之前的 records。生成新流后调用：

replaceRecords(
  key,
  compactedRecords,
  preserveFrom: snapshotSize,
  precondition: ifUnchangedThrough(lastReadSeq, witnessVersion),
  publishDiscipline: atomic,
  mode: 0600,
  parent: mustExist
)

preserveFrom 要求 backend 把 snapshot 后的新 records 接到新主体后面；ifUnchangedThrough 则保证已读取区间没被别的 writer 改掉。前置条件失败映射为 source_changed，backend 检测同一 inode 有其他硬链接时映射为 SharedInode，非法 token/参数、publish rename fallback 和普通 I/O 也分别落到不同诊断。V5 compact 本身只做一次受保护 replace；“最多 3 次”属于 UUID tombstone 的 fast path，不应混写成 compact 自动重试三次。

证据：legacy/V5 compact 主路径 401330-401498；阈值和策略常量 404491、404545-404547；串行写队列与 backstop 触发 401023-401100、401520-401548。

history 与 log：两个被旧提取窗口漏掉的活跃 stream¶

history 是 prompt 输入历史，不是 session transcript。reader 从尾到头分页，合并当前进程尚未落盘的 pending entries，按 timestamp/session 去重，并按 paste hash 回填文本；writer 等待 paste 存储完成后才 append。V5 append 失败会保留 pending entries；失败计数从 0 到 5 都会执行写入，因此是初始尝试加最多 5 次重试、最多 6 次写尝试，每轮间隔 500ms。legacy 路径对 history.jsonl 取锁，锁 stale 10 秒，获取最多重试 3 次。证据见 156893-157085。

log 是按 session/channel 寻址的诊断 stream。channel 只允许 debug、telemetry、apiDump；一方 telemetry 失败队列按 runId append，启动时 list 旧 run stream，迁移 legacy flat JSON batch，发送成功后删除，部分失败时重建剩余 records。默认发送参数是 batch 200、delay 100ms、base backoff 500ms、最大 30s、最多 8 次；达到上限会删除旧失败 batch。/debug 则把当前 session 的 debug key交给日志读取器。两类 channel 内容和 retention 不同，不能用“log namespace 会自动轮转”概括。证据见 77534-77755、542220-542244。

globalConfig：真正有完整恢复链¶

globalConfig 的可靠性不是“写 JSON”四个字：

1. 初次从 adapter 或旧路径读文本；
2. parse 后更新进程内 snapshot；
3. 所有写请求进入进程内串行队列；
4. adapter 可 subscribe key 变化，外部更新触发 reload；
5. 正常写使用 followAtomic；
6. 写前/错误时创建 backup 或 corrupted recovery copy；
7. 列举 recovery copies，按时间保留并删除超额旧副本；
8. update 路径再次读取并合并，降低覆盖并发变化的概率。

因此它可以被描述为“consumer-level 恢复链”。不能把 backup/retention 复制到 task、paste 或 identity。

证据：cli.readable.js 89674-90156。

mailbox：原子 inbox，而不是消息数据库¶

mailbox key 指向一个 teammate inbox 文本。consumer 用 updateText：解析现有记录、验证 sender/recipient/protocol frame、合并新消息或 ack、清除 malformed/stale 记录，再一次性写回。

这样能避免两个 teammate 同时投递时简单 read/write 覆盖，但仍没有跨多个 inbox 的事务。broadcast 若要写多个 teammate key，中途失败可能形成部分投递；恢复要靠 message ID、ack/redelivery 语义，而不是 storage namespace 自动回滚。

证据：cli.readable.js 279148-279245。

pluginCache：bytes、使用租约和 orphan 是三份状态¶

Plugin cache 不只存下载后的文件：

• .in_use/<pid> 表示某进程正在使用该 version；
• 退出或卸载时删除对应 in-use marker；
• .orphaned_at 记录版本何时成为孤儿；
• sweep 读取 marker/stat 后决定是否删除；
• manifest 仍需 schema、来源和 policy 校验。

一个 plugin version 在磁盘存在，不等于 registry enabled；registry enabled 也不等于当前 session 已 load；.in_use 存在还要考虑进程已崩溃的 stale marker。三者必须分别观察。

证据：cli.readable.js 184850-185860。

task：item、meta 和 high-water mark 分开¶

task namespace 把三种逻辑值拆开：

• item：listId + taskId；
• list metadata：listId + meta:true；
• high-water mark：listId + highWaterMark:true。

校验拒绝一个 key 同时扮演两种角色，也拒绝 task ID 伪装 .meta。高水位能帮助分配新 ID 或追踪列表进度，但三个 key 不构成自动事务；创建 item 后高水位写失败、删除多 item 中途失败等情况仍要由 task consumer 修复。

证据：cli.readable.js 202100-202330。

state：一个 namespace，不是一个数据模型¶

state(id) 只是 generic single-value key factory。remote-settings 与 stats-cache、update-lock、daemon-auth-status、active-time-ledger 的生命周期完全不同。跨版本比较不能写“state namespace 改了”就结束，必须比较具体 ID、reader/writer、publish discipline 和失效条件。

已观察 ID 至少包括：

• remote settings、policy limits、keybindings、loop file；
• GitHub PR/status cache、model/daemon auth cache；
• computer-use lock、daemon config/status/lock/log；
• update lock、last update result、scheduled status；
• active-time ledger、last cleanup、stats cache；
• deep-link register failure、user-memory。

这个列表是目标 bundle callsite，不保证 remote config 在运行时只会返回这些值，也不保证每个 ID 在当前账号可达。

七、失败、恢复和诊断矩阵¶

八、性能、成本、隐私与安全¶

九、如何验证某台机器是否真的在用¶

不要只搜索 tengu_hover_rest。需要同时拿到：

1. 该进程 pin 的 flag 值；
2. storageV5 adapter 的实际非空来源；
3. 目标 consumer 是否选择 adapter 分支；
4. 具体 key、operation、publish discipline 与 result；
5. 旧磁盘路径是否仍被读写；
6. subscribe/update/list 的可观察结果；
7. 重启后 durable value 是否仍存在；
8. 并发 writer 下 precondition/update 是否按合同拒绝或合并。

最小正向探针应使用一个可逆的低敏感 key，在 adapter 分支写入、读取、条件冲突、删除，再重启验证；同时监控旧路径，证明没有把 fallback 误判成 v5。当前仓库未把这样的 exact-binary backend 正向探针登记为 Probe，所以本文保持 Static。

十、证据范围¶

这些 Static 证据能证明 logical key、adapter API、写选项、真实 consumer 和本地文件硬化。它不能证明 Anthropic 服务端 storage 实现、账号 rollout、物理加密、远端 replication、quota、retention SLA 或 crash consistency；也不能证明本机独立 CLI 已创建 backend。没有 active consumer 的 identity、recording、scratch、sessionLog 保持 Boundary，后续版本出现 callsite 时再升级证据等级。