DSH plugin 接 StorageBackend：DomainSpec、StorageForms 与变更事件

DSH plugin 的存储子系统有一条清晰分界：枢纽只做汇合，后端拥有介质，数据形式拥有语义。 所以 ctx.storage 里没有任何 IO——它是「名称 → 后端」的表；真正的写盘发生在 dsh-storage-json（整文件原子重发）或 dsh-storage-sqlite（一行一文档）里；而产品包与插件一律通过 ctx.storageDomain 的类型化 API 访问数据，绝不直接碰后端。这套划分带来两个直接结论：选哪个后端是消费方自己的路由配置，不是枢纽的全局选择；写入必须先落盘再更新内存，最后才发 domain/changed。

DSH plugin 的存储枢纽：后端管介质，数据形式管语义

一句话结论：ctx.storage 是汇合点而不是存储本体；它只登记后端与挂载数据形式。

1. 后端是并排的：ctx.storage.backend 是一张名称到后端的表，多个后端可以同时挂载。
2. 路由不在枢纽：哪个后端服务哪个消费方，由消费方自己的配置决定（领域层的路由表）。
3. 注册返回 disposer：register(name, backend) 重复名称或查找未知名称都会抛 StorageError。
4. dispose 只注销名称：后端由拥有它的插件在注销之后自行关闭。
5. 生命周期键：每个后端插件会发布 storageBackendServiceKey(name)，数据形式注入它，避免激活与注册竞态。
6. 数据形式可挂载：mount(form, facility) 是一个 effect；同一键二次挂载抛 duplicate-mount，未挂载就解析会抛 form-not-mounted——组合方要按这个顺序安排插件。

DSH plugin 的后端约定：StorageBackend、KvFacet 与 KvUnit

一句话结论：一个后端拥有一个介质、提供可选操作组；unit 内每次调用原子且持久，但并发写入的先后由调用方负责。

interface StorageBackend {
  readonly kv?: KvFacet
  close(): Promise<void>   // 幂等，所有在途写入排空后释放介质
}

1. 可选 facet：后端不能提供某类数据就不实现该 facet，解析时会明确失败而不是静默降级。
2. unit 描述符：KvFacet.open(descriptor) 打开具名 unit，描述符含名称、当前格式版本、可选兼容版本、表名清单与是否有全局单例槽。
3. 命名约束：unit 名与表名必须匹配 UNIT_NAME_RE——既能当文件名也能当 SQL 标识符片段；记录键是任意字符串，绝不进入路径。
4. 原子性边界：unit 不对并发写入做串行化，顺序由调用方负责；但每次单独调用在介质上是原子的，resolve 后即已持久。
5. 错误语义：single 布局版本不同拒绝 version-mismatch；per-record 文档版本不在接受集合内读作不存在；介质无法解析拒绝 malformed-medium。
6. 两种现成后端：json 为每个 unit 整文件原子重发人类可读文件；sqlite 每行一份文档，适合频繁更新。

DSH plugin 的领域声明：DomainSpec、layout 与 invalidRecords

一句话结论：领域由拥有包声明一次，schema 用 zod 写；声明错误在模块加载时就抛，不等碰介质。

1. 基本信息：name 必须匹配 UNIT_NAME_RE，同时作为后端 unit 名；version 是非负整数。
2. 布局二选一：single（默认，整个 unit 一份文档）或 per-record（每条记录一份文档）。
3. 兼容版本：compatibleVersions 列出当前 schema 仍能接受的旧版本；per-record 后端会读带这些版本戳的文档，并接受一份旧版整 unit 文件做一次性引导。
4. 坏记录策略：默认整次 open 以 invalid-record 拒绝——适合权威数据；可丢弃的派生数据可用 'backup-and-skip'，把坏记录移开并继续。
5. global 槽：可选单例；schema 不接受 null，因为 null 是介质的「从未写入」哨兵。
6. 声明工具：defineDomain(spec) 固定字面量类型并在加载时校验；domainTable(schema) 声明表；descriptorOf(spec) 投影出后端描述符。

DSH plugin 的打开与读写：写链与 domain/changed

一句话结论：读是同步内存态，写走逐领域写链——先落盘、再更新内存、最后发事件；失败时内存不动。

1. 打开：ctx.storageDomain.open(spec) 按严格顺序执行，任一步失败整体失败（already-open、backend-not-found、facet-unsupported、version-mismatch、malformed-medium、invalid-record）。
2. 句柄稳定：domain.table(name) 重复调用返回同一实例；global 在首次 set 之前返回 spec 的 initial。
3. 读取：get/entries/keys/size 来自权威内存态，快照迭代器在排队写入落地期间保持稳定。
4. 写入：put、delete、update、global.set 都在同一条逐领域写链上排队；后端拒绝时内存原样不动，读取绝不偏离介质。
5. 更新语义：update(key, fn) 是写链 slot 上的原子读—改—写，键缺失拒绝 missing-key；delete 不存在的键返回 false，不写不发事件。
6. 事件：每次持久写入在后端确认后发 domain/changed；put 携带新快照（不含旧值），deleted 是不带值的墓碑；事件仅限进程内。

DSH plugin 的路由与生命周期：backend、routes 与 close

一句话结论：路由是领域插件的配置，句柄由调用方关闭，facility 只兜底卸载时仍开着的领域。

1. 路由配置：backend 是必填默认路由，routes 按领域名逐个覆盖；枢纽不参与选择。
2. 谁打开谁关闭：调用方拥有返回的句柄，用 Domain.close() 释放——通常挂成自己的 ctx.effect disposer。
3. 关闭语义：立即拒新写、排空已排队写入（事件仍会发）、释放 unit，然后释放名称供后续重新打开；幂等。
4. 兜底：插件卸载时仍打开的领域由 facility 关闭；closeAll() 是卸载路径。
5. 诊断：get(name) 是无类型的诊断查找，不要拿它替代类型化句柄。
6. 验证：写入后立刻读应看到新值；后端拒绝时读应保持旧值——这两条能确认写链没有倒置。

DSH plugin 排查注意事项

一句话结论：存储问题先看「哪一层拒绝」，再区分路由、schema 与并发顺序。

1. backend-not-found / facet-unsupported → 查领域路由配置与后端是否实现 kv facet。
2. invalid-record → 查 schema 与已存数据；派生数据可考虑 backup-and-skip。
3. missing-key → update 前确认键存在，或改用 put。
4. 内存与介质不一致 → 检查是否就地修改了返回对象，必须用 put/update 替换。
5. 并发写顺序乱 → unit 不串行化并发写，顺序由调用方保证。
6. 修复状态如实：本文的枢纽/后端/数据形式分工、DomainSpec 字段、写链顺序与 domain/changed 语义均取自官方「存储」页面；接口签名以该页 Cordis API 与你所用版本为准。

来源：存储、backend.ts、dsh-storage-json README。