AGENTS.md@src/host/assets git:20260928.3d30763A

Immutable. This exact content never changes and is served at /api/v1/blob/0e5ce6ec697efa46.

# Assets Module Rules

## 范围与职责

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

以**单文件 SQLite（`<root>/assets.db`）**保存两类持久化事实，并对外提供其读写入口：

- **资产**：模版的晋升形态。带版本控制、Active 指针、回滚与退役；分角色资产与工作流资产两类；
- **经验**：复盘沉淀的知识单元（task_type + task_context + insight）。

判断归属：该修改是否改变「资产/经验被持久化成什么形状、版本如何推进、Active 如何指向」？
只改变业务语义判断（该不该晋升、该不该复用）应放到调用方模块。

## 时间戳与版本

- 时间戳一律 epoch 毫秒，由本模块记账（`AssetStoreDeps.now` 可注入，测试确定化）。
- `created_at` 是**资产诞生时间**，升版时沿用既有版本行的值；`updated_at` 每次写入刷新。
- `version_id` 从 1 开始、按资产独立递增（`max(version_id) + 1`）；版本行 id 固定
  `<asset_id>@<version_id>`，它是工作流版本行反向引用角色版本行的键，属对外契约。
- 回滚只移动 Active 指针，不新增版本、不改历史行。

## 核心原则

1. 资产事实由本模块单独拥有，磁盘形状与错误码属对外契约。
2. 读改写不出事务，失败不留半成品。
3. 历史不可变，Active 即指针；统计是缓存，可重建且有唯一维护点。
4. 时间戳与版本号由本模块记账，注入式时钟保证测试确定。
5. 列表读可用、单资源读可诊断；重建宁可报错也不产半成品。