git:20260923.4575b13 to git:20260928.0bc633c

0 added, 7 removed. Audit A to A.

# Storage Module Rules

## 范围与职责

适用于 `src/host/storage/`。

以「单文件即单资源 + 原子发布 + 进程内/跨进程锁」保存与读取 Host 的持久化文档，并对外提供可复用的原子文件原语与崩溃恢复能力。

判断归属：该修改是否改变「什么被持久化、以什么形状持久化、并发写入如何被串行化」？只改变业务语义判断应放到对应领域模块。

## 状态所有权

- - 数据目录布局、`revision`、`updatedAt`、资源归属字段（如 `sessionId`）与写入字段剥除策略由 storage 决定并对外表现为稳定语义。

- 调用方不得绕过 storage 直接写同一数据文件；需要新资源类型时在 storage 增加明确入口，而不是在别处拼路径。

- 只读方只能拿到值副本（如映射读取返回新对象），不得让调用方持有内部可变结构。

- storage 回答「存了什么」，不回答「是否该存在」。

## 读取语义

- 单资源读取遇损坏 JSON **必须抛出带路径的可诊断错误**，不得伪装成「不存在」。

- 列表读取跳过损坏项以保证可用性，但不得吞掉权限等其他错误（避免把权限问题伪装成空列表）。

- 新增读取入口必须明确选边（单资源 / 列表），并在注释与测试中固化该选择。

## 原子性与锁

- 所有写入必须经组合锁原语（磁盘锁在外、进程内锁在内），不得裸写文件。

- **读改写必须在同一临界区内完成**。

- 新增写路径必须复用既有原子原语，新增公共写方法必须能说明：其读改写位于同一临界区，且失败路径不残留临时文件或锁。

- ## 生命周期与跨文件边界

- - 目录初始化必须幂等；新增目录必须同时进入布局常量，不得散落硬编码路径。

- - 删除与创建语义必须对称：级联删除的从属文件必须显式列出并注释其归属关系。

- - **跨文件事务不在保证范围内**：例如服务文档与其会话映射文件由不同锁键保护，删除服务后并发写入仍可能重建从属文件。调用方必须在写入前校验主资源存在并保证写顺序；新增此类从属文件必须写明该不变式。

## 时间戳与版本

- `createdAt = 调用方值 ?? 既有值 ?? now`；`updatedAt` 与 `revision` 恒由 storage 生成，调用方传入值不得覆盖。

- 乐观锁只在调用方显式传入 `expectedRevision` 时生效（不得用文档内的 revision 隐式当作冲突期望）。

## 兼容与退役字段

- 旧字段只保留读取兼容语义，重新保存后被剥除；禁止新增已退役字段的写入；

- 前端临时标记与仅服务端拥有的字段必须在写入路径统一处理，不得依赖调用方自觉清理。

## 验证补充

- 并发写同一资源无丢更新（读改写仍在同一临界区）；

- 失败路径无临时文件与锁残留；

- 单资源读对损坏 JSON 仍抛可诊断错误、列表读仍保持可用；

- 无旧路径残留、磁盘形状与公共错误码未被意外改变。

## 核心原则

1. 持久化事实由 storage 单独拥有。

2. 读改写不出临界区，锁顺序固定。

3. 单资源读可诊断，列表读可用。原子原语可复用。

4. 时间戳与版本由 storage 记账。

5. 跨文件一致性由调用方保证并写明不变式。

6. 磁盘形状与公共错误码属对外契约。