社区导读

简体中文

English

简体中文

English

外观

源文件索引：packages/storage ​

本页由 study-tools/generate-source-index.mjs 根据官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec 生成，共 28 个代码或界面源文件。每个标题对应一个真实路径；用途和拆分原因是面向初学者的结构化解释，自动索引不等于人工精读。

图例 ​

本页所有条目共用以下说明：

  • 自动索引只提供定位线索，复杂行为需要回到源码和测试确认。
  • 条目中的行数、声明、结构线索和静态 import 数字是文件级定位证据，用来约束“为什么这样设计”的解释范围；它们用于定位，不替代人工源码阅读。
  • 源码链接固定到官方提交；如果当前条目与运行版本不同，应先重新生成索引再下结论。

packages/storage/storage-domain/src/domain.ts ​

  • 所属层：packages/storage：可复用的 Harness 功能包
  • 文件角色：领域模型
  • 这个文件有什么用：它表达存储、领域模型的领域状态、创建方式和约束，让存储与界面层依赖稳定语义。
  • 为什么这样设计：领域规则放在模型层，存储、协议和 UI 只做转换；同一语义可以被不同入口复用，也更容易用纯数据测试。
  • 文件级设计证据：源码顶部注释把它定位为“Runtime of one open domain: authoritative in-memory state, the single per-domain write chain, and change-event emission. Reads are synchronous from memory; every write queues on the chain, awaits backend durability FIRST, then mutates memory, then emits dom...”；固定提交中扫描到的声明包括 DomainGlobal、KvTable、DomainGlobalHandleOf、Domain、DomainImpl；本地静态 import 图显示它直接依赖 5 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/storage/storage-domain/README.md、packages/storage/storage-domain/src/error.ts、packages/storage/storage-domain/src/events.ts、packages/storage/storage-domain/src/spec.ts、packages/storage/storage-domain/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：apps/web/tests/sidebar-subagent-activity.e2e.ts、packages/feedback/message-feedback/tests/invariant.spec.ts、packages/feedback/message-feedback/tests/loader-composition.spec.ts、packages/feedback/message-feedback/tests/message-feedback.spec.ts、packages/host/apiproxy/tests/api-proxy-agent-preset.spec.ts、packages/host/apiproxy/tests/api-proxy-approval.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读相关类型和事件，再读当前状态或存储实现，沿着 packages/storage/storage-domain/src/error.ts、packages/storage/storage-domain/src/events.ts、packages/storage/storage-domain/src/spec.ts 和 packages/storage/storage-domain/src/index.ts 理解状态变化，最后对照 apps/web/tests/sidebar-subagent-activity.e2e.ts、packages/feedback/message-feedback/tests/invariant.spec.ts、packages/feedback/message-feedback/tests/loader-composition.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 357 行；扫描到的声明包括 DomainGlobal、KvTable、DomainGlobalHandleOf、Domain、DomainImpl、KvTableImpl；源码顶部原注释（英文，仅作回查线索）：Runtime of one open domain: authoritative in-memory state, the single per-domain write chain, and change-event emission. Reads are synchronous from memory; every write queues on the chain, awaits backend durability FIRST, then mutates memory, then emits dom...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/storage/storage-domain/src/error.ts ​

  • 所属层：packages/storage：可复用的 Harness 功能包
  • 文件角色：错误模型
  • 这个文件有什么用：这个文件统一错误的类型、名称或转换方式。统一错误格式能让日志、用户界面和重试策略看懂同一件事。
  • 为什么这样设计：固定提交的文件顶部注释把它定位为“Error vocabulary of the domain data form. @module @deepseek-ai/dsh-storage-domain/src/error”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
  • 文件级设计证据：源码顶部注释把它定位为“Error vocabulary of the domain data form. @module @deepseek-ai/dsh-storage-domain/src/error”；固定提交中扫描到的声明包括 DomainErrorCode、InvalidRecordDetail、DomainErrorOptions、DomainError；本地静态 import 图显示它直接依赖 0 个源文件，并被 2 个源文件直接引用。
  • 直接协作者：packages/storage/storage-domain/README.md、packages/storage/storage-domain/src/domain.ts、packages/storage/storage-domain/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：apps/web/tests/sidebar-subagent-activity.e2e.ts、packages/feedback/message-feedback/tests/invariant.spec.ts、packages/feedback/message-feedback/tests/loader-composition.spec.ts、packages/feedback/message-feedback/tests/message-feedback.spec.ts、packages/host/apiproxy/tests/api-proxy-agent-preset.spec.ts、packages/host/apiproxy/tests/api-proxy-approval.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读 packages/storage/storage-domain/README.md 和入口，再读当前实现，沿着相关类型、协议或实现和 packages/storage/storage-domain/src/domain.ts、packages/storage/storage-domain/src/index.ts 确认输入输出，最后对照 apps/web/tests/sidebar-subagent-activity.e2e.ts、packages/feedback/message-feedback/tests/invariant.spec.ts、packages/feedback/message-feedback/tests/loader-composition.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 53 行；扫描到的声明包括 DomainErrorCode、InvalidRecordDetail、DomainErrorOptions、DomainError；源码顶部原注释（英文，仅作回查线索）：Error vocabulary of the domain data form. @module @deepseek-ai/dsh-storage-domain/src/error。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/storage/storage-domain/src/events.ts ​

  • 所属层：packages/storage：可复用的 Harness 功能包
  • 文件角色：事件契约
  • 这个文件有什么用：它列出存储、领域模型、事件可以发送和接收的事件。用事件传递信息，能让生产者和消费者少互相导入，插件也更容易替换。
  • 为什么这样设计：事件和钩子是插件之间的连接点。把连接点单独定义，可以让新增能力接入流程而不必修改所有旧消费者。
  • 文件级设计证据：源码顶部注释把它定位为“Change-event vocabulary of the domain data form. Every durable write emits one event after the backend resolves durability, carrying the new snapshot and an operation discriminant — never the old value (a diffing consumer keeps its own previous snapshot). T...”；固定提交中扫描到的声明包括 DomainChangedBase、DomainChangedPut、DomainChangedDeleted、DomainChanged；本地静态 import 图显示它直接依赖 0 个源文件，并被 5 个源文件直接引用。
  • 直接协作者：packages/storage/storage-domain/README.md、packages/storage/storage-domain/src/domain.ts、packages/storage/storage-domain/src/index.ts、packages/storage/storage-domain/src/invariant.ts
  • 对应测试：packages/storage/storage-domain/tests/domain.spec.ts、packages/storage/storage-domain/tests/invariant.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 测试支持：packages/storage/storage-domain/tests/helpers/memory-backend.ts
  • 阅读顺序：先读 packages/storage/storage-domain/README.md、入口和消费者，再读当前契约，沿着 packages/storage/storage-domain/src/domain.ts、packages/storage/storage-domain/src/index.ts、packages/storage/storage-domain/src/invariant.ts 看它怎样约束运行时，最后对照 packages/storage/storage-domain/tests/domain.spec.ts、packages/storage/storage-domain/tests/invariant.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 48 行；扫描到的声明包括 DomainChangedBase、DomainChangedPut、DomainChangedDeleted、DomainChanged；源码顶部原注释（英文，仅作回查线索）：Change-event vocabulary of the domain data form. Every durable write emits one event after the backend resolves durability, carrying the new snapshot and an operation discriminant — never the old value (a diffing consumer keeps its own previous snapshot). T...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/storage/storage-domain/src/index.ts ​

packages/storage/storage-domain/src/invariant.ts ​

  • 所属层：packages/storage：可复用的 Harness 功能包
  • 文件角色：运行时不变量
  • 这个文件有什么用：它检查存储、领域模型必须始终成立的条件，在错误刚出现时报告，而不是等到更深层才出现难以解释的结果。
  • 为什么这样设计：把不变量集中在一个位置，调用者和测试就能用同一条规则检查状态；错误在边界处报告，比在后续 UI 或网络请求中才暴露更容易修复。
  • 文件级设计证据：源码顶部注释把它定位为“Package-owned invariant companion for @deepseek-ai/dsh-storage-domain: every domain/changed event must agree with the emitting domain's authoritative in-memory state (the owned event-stream ↔ mutable-data relationship of this package). Writes emit strictly ...”；固定提交中扫描到的声明包括 name、inject、apply；本地静态 import 图显示它直接依赖 3 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/storage/storage-domain/README.md、packages/runtime-diagnostics/invariants/src/index.ts、packages/storage/storage-domain/src/events.ts、vendor/cordis/src/index.ts、packages/storage/storage-domain/tests/invariant.spec.ts
  • 对应测试：packages/storage/storage-domain/tests/invariant.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 测试支持：packages/storage/storage-domain/tests/helpers/memory-backend.ts
  • 阅读顺序：先读相关类型和事件，再读当前状态或存储实现，沿着 packages/runtime-diagnostics/invariants/src/index.ts、packages/storage/storage-domain/src/events.ts、vendor/cordis/src/index.ts 和 packages/storage/storage-domain/tests/invariant.spec.ts 理解状态变化，最后对照 packages/storage/storage-domain/tests/invariant.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 67 行；扫描到的声明包括 name、inject、apply；源码顶部原注释（英文，仅作回查线索）：Package-owned invariant companion for @deepseek-ai/dsh-storage-domain: every domain/changed event must agree with the emitting domain's authoritative in-memory state (the owned event-stream ↔ mutable-data relationship of this package). Writes emit strictly ...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/storage/storage-domain/src/spec.ts ​

  • 所属层：packages/storage：可复用的 Harness 功能包
  • 文件角色：存储后端实现
  • 这个文件有什么用：这个文件实现 JSON、SQLite 或领域存储后端的一项读写、原子性或单位转换职责。
  • 为什么这样设计：领域语义与 JSON/SQLite 后端分开，未来更换存储或加入原子写入时不会重写上层 Session 逻辑。
  • 文件级设计证据：源码顶部注释把它定位为“Domain declaration vocabulary. A spec object is the single source of a domain's identity, layout, and record schemas: the owning package defines it once with defineDomain and both the type surface and the runtime (validation, descriptor projection) derive f...”；固定提交中扫描到的声明包括 DomainGlobalSpec、DomainTableSpec、DomainSpec、TableKeyOf、TableValueOf；本地静态 import 图显示它直接依赖 1 个源文件，并被 2 个源文件直接引用。
  • 直接协作者：packages/storage/storage-domain/README.md、packages/storage/storage/src/index.ts、packages/storage/storage-domain/src/domain.ts、packages/storage/storage-domain/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：apps/web/tests/sidebar-subagent-activity.e2e.ts、packages/feedback/message-feedback/tests/invariant.spec.ts、packages/feedback/message-feedback/tests/loader-composition.spec.ts、packages/feedback/message-feedback/tests/message-feedback.spec.ts、packages/host/apiproxy/tests/api-proxy-agent-preset.spec.ts、packages/host/apiproxy/tests/api-proxy-approval.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读 packages/storage/storage-domain/README.md 和入口，再读当前实现，沿着 packages/storage/storage/src/index.ts 和 packages/storage/storage-domain/src/domain.ts、packages/storage/storage-domain/src/index.ts 确认输入输出，最后对照 apps/web/tests/sidebar-subagent-activity.e2e.ts、packages/feedback/message-feedback/tests/invariant.spec.ts、packages/feedback/message-feedback/tests/loader-composition.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 112 行；扫描到的声明包括 DomainGlobalSpec、DomainTableSpec、DomainSpec、TableKeyOf、TableValueOf、GlobalValueOf、domainTable、defineDomain；源码顶部原注释（英文，仅作回查线索）：Domain declaration vocabulary. A spec object is the single source of a domain's identity, layout, and record schemas: the owning package defines it once with defineDomain and both the type surface and the runtime (validation, descriptor projection) derive f...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/storage/storage-domain/tests/domain.spec.ts ​

  • 所属层：packages/storage：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查存储、领域模型的具体场景，包括“defineDomain”、“rejects invalid names and versions loudly”、“rejects a global schema that accepts null (the never-written sentinel)”、“DomainFacility.open”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“defineDomain”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：固定提交中扫描到的声明包括 harness；本地静态 import 图显示它直接依赖 5 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/storage/storage-domain/README.md、packages/storage/storage-domain/src/events.ts、packages/storage/storage-domain/src/index.ts、packages/storage/storage-domain/tests/helpers/memory-backend.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 测试支持：packages/storage/storage-domain/tests/helpers/memory-backend.ts
  • 阅读顺序：先看它直接导入的被测实现 packages/storage/storage-domain/src/events.ts、packages/storage/storage-domain/src/index.ts、packages/storage/storage/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 358 行；扫描到的声明包括 harness；扫描到的测试主题包括 “defineDomain”、“rejects invalid names and versions loudly”、“rejects a global schema that accepts null (the never-written sentinel)”、“DomainFacility.open”、“opens, reads back stored records, and rejects a second open of the same name”、“routes per domain name and fails loud on an unregistered route target”。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/storage/storage-domain/tests/helpers/memory-backend.ts ​

packages/storage/storage-domain/tests/invariant.spec.ts ​

  • 所属层：packages/storage：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查存储、领域模型的具体场景，包括“domain change-event invariants”、“accepts every write shape emitted by the real write paths”、“rejects an event for a domain that is not open”、“rejects a put event whose value is not the in-memory record”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“domain change-event invariants”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：固定提交中扫描到的声明包括 setup；本地静态 import 图显示它直接依赖 7 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/storage/storage-domain/README.md、packages/runtime-diagnostics/invariants/src/index.ts、packages/storage/storage-domain/src/events.ts、packages/storage/storage-domain/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 测试支持：packages/storage/storage-domain/tests/helpers/memory-backend.ts
  • 阅读顺序：先看它直接导入的被测实现 packages/runtime-diagnostics/invariants/src/index.ts、packages/storage/storage-domain/src/events.ts、packages/storage/storage-domain/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 91 行；扫描到的声明包括 setup；扫描到的测试主题包括 “domain change-event invariants”、“accepts every write shape emitted by the real write paths”、“rejects an event for a domain that is not open”、“rejects a put event whose value is not the in-memory record”、“rejects a deletion event while the record is still in memory”、“rejects a global event whose value is not the in-memory global”。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/storage/storage-json/src/atomic.ts ​

  • 所属层：packages/storage：可复用的 Harness 功能包
  • 文件角色：存储后端实现
  • 这个文件有什么用：这个文件实现 JSON、SQLite 或领域存储后端的一项读写、原子性或单位转换职责。
  • 为什么这样设计：领域语义与 JSON/SQLite 后端分开，未来更换存储或加入原子写入时不会重写上层 Session 逻辑。
  • 文件级设计证据：源码顶部注释把它定位为“Atomic whole-file replacement for the JSON backend. Publish protocol: write a same-directory temp file, fsync it, then rename() over the target. Rename is an atomic replace on POSIX and on Windows (libuv maps it to MoveFileExW(..., MOVEFILE_REPLACE_EXISTING...”；固定提交中扫描到的声明包括 writeAtomic、fsyncDirectory；本地静态 import 图显示它直接依赖 0 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/storage/storage-json/README.md、packages/storage/storage-json/src/unit.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/feedback/message-feedback/tests/invariant.spec.ts、packages/feedback/message-feedback/tests/loader-composition.spec.ts、packages/feedback/message-feedback/tests/message-feedback.spec.ts、packages/storage/storage-json/tests/json-backend.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读 packages/storage/storage-json/README.md 和入口，再读当前实现，沿着相关类型、协议或实现和 packages/storage/storage-json/src/unit.ts 确认输入输出，最后对照 packages/feedback/message-feedback/tests/invariant.spec.ts、packages/feedback/message-feedback/tests/loader-composition.spec.ts、packages/feedback/message-feedback/tests/message-feedback.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 53 行；扫描到的声明包括 writeAtomic、fsyncDirectory；源码顶部原注释（英文，仅作回查线索）：Atomic whole-file replacement for the JSON backend. Publish protocol: write a same-directory temp file, fsync it, then rename() over the target. Rename is an atomic replace on POSIX and on Windows (libuv maps it to MoveFileExW(..., MOVEFILE_REPLACE_EXISTING...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/storage/storage-json/src/format.ts ​

  • 所属层：packages/storage：可复用的 Harness 功能包
  • 文件角色：格式编解码
  • 这个文件有什么用：它定义 JSON storage unit 的磁盘格式和内存状态：当前 net state、version、global 值以及 tables；文件保持可读并按稳定的插入顺序写出。
  • 为什么这样设计：JSON 后端存在的价值就是人能读懂磁盘状态；把当前净状态、稳定写出顺序和 JSON-safe 约束放进格式层，调试和迁移可以检查文件本身而不依赖数据库工具。
  • 文件级设计证据：源码顶部注释把它定位为“On-disk JSON unit format: the file is always the current net state, kept human-readable (pretty-printed, stable key order from insertion) — that legibility is this backend's reason to exist. @module @deepseek-ai/dsh-storage-json/src/format”；固定提交中扫描到的声明包括 UnitState、serialize、parse；本地静态 import 图显示它直接依赖 1 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/storage/storage-json/README.md、packages/storage/storage/src/index.ts、packages/storage/storage-json/src/unit.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/feedback/message-feedback/tests/invariant.spec.ts、packages/feedback/message-feedback/tests/loader-composition.spec.ts、packages/feedback/message-feedback/tests/message-feedback.spec.ts、packages/storage/storage-json/tests/json-backend.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读 packages/storage/storage-json/README.md 和入口，再读当前实现，沿着 packages/storage/storage/src/index.ts 和 packages/storage/storage-json/src/unit.ts 确认输入输出，最后对照 packages/feedback/message-feedback/tests/invariant.spec.ts、packages/feedback/message-feedback/tests/loader-composition.spec.ts、packages/feedback/message-feedback/tests/message-feedback.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 84 行；扫描到的声明包括 UnitState、serialize、parse；源码顶部原注释（英文，仅作回查线索）：On-disk JSON unit format: the file is always the current net state, kept human-readable (pretty-printed, stable key order from insertion) — that legibility is this backend's reason to exist. @module @deepseek-ai/dsh-storage-json/src/format。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/storage/storage-json/src/index.ts ​

  • 所属层：packages/storage：可复用的 Harness 功能包
  • 文件角色：模块入口
  • 这个文件有什么用：它把存储相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
  • 为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
  • 文件级设计证据：源码顶部注释把它定位为“JSON storage backend: one human-readable file per unit under a configured root, published by atomic whole-file rewrite. Registers as backend json on the storage hub. @module @deepseek-ai/dsh-storage-json”；固定提交中扫描到的声明包括 name、inject、Config、JsonStorageBackend、apply；本地静态 import 图显示它直接依赖 4 个源文件，并被 3 个源文件直接引用。
  • 直接协作者：packages/storage/storage-json/README.md、packages/storage/storage-json/src/unit.ts、packages/storage/storage/src/index.ts、vendor/cordis/src/index.ts、packages/feedback/message-feedback/tests/helpers.ts
  • 对应测试：packages/feedback/message-feedback/tests/loader-composition.spec.ts、packages/storage/storage-json/tests/json-backend.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 测试支持：packages/feedback/message-feedback/tests/helpers.ts、packages/storage/storage/tests/contract.ts
  • 阅读顺序：先读 packages/storage/storage-json/README.md、入口和消费者，再读当前契约，沿着 packages/feedback/message-feedback/tests/helpers.ts、packages/feedback/message-feedback/tests/loader-composition.spec.ts、packages/storage/storage-json/tests/json-backend.spec.ts 看它怎样约束运行时，最后对照 packages/feedback/message-feedback/tests/loader-composition.spec.ts、packages/storage/storage-json/tests/json-backend.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 114 行；扫描到的声明包括 name、inject、Config、JsonStorageBackend、apply、validateDescriptor；源码顶部原注释（英文，仅作回查线索）：JSON storage backend: one human-readable file per unit under a configured root, published by atomic whole-file rewrite. Registers as backend json on the storage hub. @module @deepseek-ai/dsh-storage-json。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/storage/storage-json/src/invariant.ts ​

  • 所属层：packages/storage：可复用的 Harness 功能包
  • 文件角色：运行时不变量
  • 这个文件有什么用：它检查存储必须始终成立的条件，在错误刚出现时报告，而不是等到更深层才出现难以解释的结果。
  • 为什么这样设计：把不变量集中在一个位置，调用者和测试就能用同一条规则检查状态；错误在边界处报告，比在后续 UI 或网络请求中才暴露更容易修复。
  • 文件级设计证据：源码顶部注释把它定位为“Package-owned invariant companion for @deepseek-ai/dsh-storage-json. @module @deepseek-ai/dsh-storage-json/invariant”；固定提交中扫描到的声明包括 name、inject、apply；本地静态 import 图显示它直接依赖 2 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/storage/storage-json/README.md、packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts、packages/storage/storage-json/tests/json-backend.spec.ts
  • 对应测试：packages/storage/storage-json/tests/json-backend.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 测试支持：packages/storage/storage/tests/contract.ts
  • 阅读顺序：先读相关类型和事件，再读当前状态或存储实现，沿着 packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts 和 packages/storage/storage-json/tests/json-backend.spec.ts 理解状态变化，最后对照 packages/storage/storage-json/tests/json-backend.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 32 行；扫描到的声明包括 name、inject、apply；源码顶部原注释（英文，仅作回查线索）：Package-owned invariant companion for @deepseek-ai/dsh-storage-json. @module @deepseek-ai/dsh-storage-json/invariant。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/storage/storage-json/src/unit.ts ​

  • 所属层：packages/storage：可复用的 Harness 功能包
  • 文件角色：存储后端实现
  • 这个文件有什么用：这个文件实现 JSON、SQLite 或领域存储后端的一项读写、原子性或单位转换职责。
  • 为什么这样设计：领域语义与 JSON/SQLite 后端分开，未来更换存储或加入原子写入时不会重写上层 Session 逻辑。
  • 文件级设计证据：源码顶部注释把它定位为“One opened JSON unit. The in-memory state is authoritative; every write primitive mutates it and republishes the whole file atomically. Writes are NOT queued here — per the backend contract, write ordering belongs to the caller (the domain layer's write cha...”；固定提交中扫描到的声明包括 openJsonUnit、JsonKvUnit；本地静态 import 图显示它直接依赖 3 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/storage/storage-json/README.md、packages/storage/storage-json/src/atomic.ts、packages/storage/storage-json/src/format.ts、packages/storage/storage/src/index.ts、packages/storage/storage-json/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/feedback/message-feedback/tests/invariant.spec.ts、packages/feedback/message-feedback/tests/loader-composition.spec.ts、packages/feedback/message-feedback/tests/message-feedback.spec.ts、packages/storage/storage-json/tests/json-backend.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读 packages/storage/storage-json/README.md 和入口，再读当前实现，沿着 packages/storage/storage-json/src/atomic.ts、packages/storage/storage-json/src/format.ts、packages/storage/storage/src/index.ts 和 packages/storage/storage-json/src/index.ts 确认输入输出，最后对照 packages/feedback/message-feedback/tests/invariant.spec.ts、packages/feedback/message-feedback/tests/loader-composition.spec.ts、packages/feedback/message-feedback/tests/message-feedback.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 141 行；扫描到的声明包括 openJsonUnit、JsonKvUnit；源码顶部原注释（英文，仅作回查线索）：One opened JSON unit. The in-memory state is authoritative; every write primitive mutates it and republishes the whole file atomically. Writes are NOT queued here — per the backend contract, write ordering belongs to the caller (the domain layer's write cha...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/storage/storage-json/tests/json-backend.spec.ts ​

  • 所属层：packages/storage：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查存储的具体场景，包括“json backend specifics”、“publishes a human-readable pretty-printed file”、“defers materialization until the first write”、“rejects a malformed medium”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“json backend specifics”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：固定提交中扫描到的声明包括 freshRoot；本地静态 import 图显示它直接依赖 6 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/storage/storage-json/README.md、packages/runtime-diagnostics/invariants/src/index.ts、packages/storage/storage-json/src/index.ts、packages/storage/storage-json/src/invariant.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 测试支持：packages/storage/storage/tests/contract.ts
  • 阅读顺序：先看它直接导入的被测实现 packages/runtime-diagnostics/invariants/src/index.ts、packages/storage/storage-json/src/index.ts、packages/storage/storage-json/src/invariant.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 228 行；扫描到的声明包括 freshRoot；扫描到的测试主题包括 “json backend specifics”、“publishes a human-readable pretty-printed file”、“defers materialization until the first write”、“rejects a malformed medium”、“rejects a foreign unit header”、“rejects double-open of one unit as a plain caller error”。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/storage/storage-sqlite/src/index.ts ​

  • 所属层：packages/storage：可复用的 Harness 功能包
  • 文件角色：模块入口
  • 这个文件有什么用：它把存储相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
  • 为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
  • 文件级设计证据：源码顶部注释把它定位为“SQLite storage backend for the storage hub: one database file hosts every routed unit, document-per-row (key TEXT / value TEXT JSON). Registers as backend sqlite; the disposer unregisters first, then closes the medium. @module @deepseek-ai/dsh-storage-sqlite”；固定提交中扫描到的声明包括 name、inject、Config、SqliteStorageBackend、apply；本地静态 import 图显示它直接依赖 5 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/storage/storage-sqlite/README.md、packages/storage/storage-sqlite/src/schema.ts、packages/storage/storage-sqlite/src/unit.ts、packages/storage/storage/src/index.ts、packages/storage/storage-sqlite/tests/sqlite-backend.spec.ts
  • 对应测试：packages/storage/storage-sqlite/tests/sqlite-backend.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 测试支持：packages/storage/storage/tests/contract.ts
  • 阅读顺序：先读 packages/storage/storage-sqlite/README.md、入口和消费者，再读当前契约，沿着 packages/storage/storage-sqlite/tests/sqlite-backend.spec.ts 看它怎样约束运行时，最后对照 packages/storage/storage-sqlite/tests/sqlite-backend.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 168 行；扫描到的声明包括 name、inject、Config、SqliteStorageBackend、apply；源码顶部原注释（英文，仅作回查线索）：SQLite storage backend for the storage hub: one database file hosts every routed unit, document-per-row (key TEXT / value TEXT JSON). Registers as backend sqlite; the disposer unregisters first, then closes the medium. @module @deepseek-ai/dsh-storage-sqlite。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/storage/storage-sqlite/src/invariant.ts ​

  • 所属层：packages/storage：可复用的 Harness 功能包
  • 文件角色：运行时不变量
  • 这个文件有什么用：它检查存储必须始终成立的条件，在错误刚出现时报告，而不是等到更深层才出现难以解释的结果。
  • 为什么这样设计：把不变量集中在一个位置，调用者和测试就能用同一条规则检查状态；错误在边界处报告，比在后续 UI 或网络请求中才暴露更容易修复。
  • 文件级设计证据：源码顶部注释把它定位为“Package-owned invariant companion for @deepseek-ai/dsh-storage-sqlite. @module @deepseek-ai/dsh-storage-sqlite/invariant”；固定提交中扫描到的声明包括 name、inject、apply；本地静态 import 图显示它直接依赖 2 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/storage/storage-sqlite/README.md、packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts、packages/storage/storage-sqlite/tests/invariant.spec.ts
  • 对应测试：packages/storage/storage-sqlite/tests/invariant.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 阅读顺序：先读相关类型和事件，再读当前状态或存储实现，沿着 packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts 和 packages/storage/storage-sqlite/tests/invariant.spec.ts 理解状态变化，最后对照 packages/storage/storage-sqlite/tests/invariant.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 32 行；扫描到的声明包括 name、inject、apply；源码顶部原注释（英文，仅作回查线索）：Package-owned invariant companion for @deepseek-ai/dsh-storage-sqlite. @module @deepseek-ai/dsh-storage-sqlite/invariant。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/storage/storage-sqlite/src/schema.ts ​

  • 所属层：packages/storage：可复用的 Harness 功能包
  • 文件角色：配置与数据形状
  • 这个文件有什么用：它定义存储、数据 schema可接受的配置或输入形状，并在数据进入深层逻辑前集中校验。
  • 为什么这样设计：先把形状和规则集中声明，执行代码只负责使用已经检查过的数据；这样错误更早暴露，读代码时也有一张共同的地图。
  • 文件级设计证据：源码顶部注释把它定位为“Schema + open-time helpers for the SQLite storage backend: the physical layout version, the database open/configure sequence (permissions, pragmas, version stamp/reject), and the unit metadata tables. Unit record tables are created per descriptor in unit.ts...”；固定提交中扫描到的声明包括 STORAGE_SQLITE_SCHEMA_VERSION、JournalMode、openDatabase、recordTableName、createDatabaseFile；本地静态 import 图显示它直接依赖 1 个源文件，并被 2 个源文件直接引用。
  • 直接协作者：packages/storage/storage-sqlite/README.md、packages/storage/storage/src/index.ts、packages/storage/storage-sqlite/src/index.ts、packages/storage/storage-sqlite/src/unit.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/storage/storage-sqlite/tests/sqlite-backend.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读 packages/storage/storage-sqlite/README.md，再读本配置/脚本，沿着 packages/storage/storage-sqlite/src/index.ts、packages/storage/storage-sqlite/src/unit.ts 确认它如何影响入口和产物，最后对照对应 gate 或快照测试。
  • 代码证据：固定提交归档实际读取结果：约 120 行；扫描到的声明包括 STORAGE_SQLITE_SCHEMA_VERSION、JournalMode、openDatabase、recordTableName、createDatabaseFile、configureDatabase；源码顶部原注释（英文，仅作回查线索）：Schema + open-time helpers for the SQLite storage backend: the physical layout version, the database open/configure sequence (permissions, pragmas, version stamp/reject), and the unit metadata tables. Unit record tables are created per descriptor in unit.ts...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/storage/storage-sqlite/src/unit.ts ​

  • 所属层：packages/storage：可复用的 Harness 功能包
  • 文件角色：存储后端实现
  • 这个文件有什么用：这个文件实现 JSON、SQLite 或领域存储后端的一项读写、原子性或单位转换职责。
  • 为什么这样设计：领域语义与 JSON/SQLite 后端分开，未来更换存储或加入原子写入时不会重写上层 Session 逻辑。
  • 文件级设计证据：源码顶部注释把它定位为“One opened SQLite KV unit: prepared per-table statements over the u_<unit>_<table> record tables plus this unit's row in the shared unit_globals table. Each primitive is a single statement, so atomicity comes from SQLite itself — no explicit transactions, a...”；固定提交中扫描到的声明包括 SqliteKvUnit；本地静态 import 图显示它直接依赖 2 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/storage/storage-sqlite/README.md、packages/storage/storage-sqlite/src/schema.ts、packages/storage/storage/src/index.ts、packages/storage/storage-sqlite/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/storage/storage-sqlite/tests/sqlite-backend.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读 packages/storage/storage-sqlite/README.md 和入口，再读当前实现，沿着 packages/storage/storage-sqlite/src/schema.ts、packages/storage/storage/src/index.ts 和 packages/storage/storage-sqlite/src/index.ts 确认输入输出，最后对照 packages/storage/storage-sqlite/tests/sqlite-backend.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 156 行；扫描到的声明包括 SqliteKvUnit；源码顶部原注释（英文，仅作回查线索）：One opened SQLite KV unit: prepared per-table statements over the u_<unit>_<table> record tables plus this unit's row in the shared unit_globals table. Each primitive is a single statement, so atomicity comes from SQLite itself — no explicit transactions, a...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/storage/storage-sqlite/tests/invariant.spec.ts ​

  • 所属层：packages/storage：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查存储的具体场景，包括“invariant companion”、“registers under the package name with an explained-empty installer”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“invariant companion”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：本次固定提交归档没有扫描到顶部注释、顶层声明或专门的结构线索；本地静态 import 图显示它直接依赖 3 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/storage/storage-sqlite/README.md、packages/runtime-diagnostics/invariants/src/index.ts、packages/storage/storage-sqlite/src/invariant.ts、vendor/cordis/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/runtime-diagnostics/invariants/src/index.ts、packages/storage/storage-sqlite/src/invariant.ts、vendor/cordis/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 12 行；扫描到的测试主题包括 “invariant companion”、“registers under the package name with an explained-empty installer”。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/storage/storage-sqlite/tests/sqlite-backend.spec.ts ​

  • 所属层：packages/storage：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查存储的具体场景，包括“sqlite backend specifics”、“opens an in-memory database”、“materializes STRICT record tables and stamps the schema version”、“rejects a mismatched database schema version”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“sqlite backend specifics”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：固定提交中扫描到的声明包括 backendAt、freshDbPath；本地静态 import 图显示它直接依赖 4 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/storage/storage-sqlite/README.md、packages/storage/storage-sqlite/src/index.ts、packages/storage/storage/src/index.ts、packages/storage/storage/tests/contract.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 测试支持：packages/storage/storage/tests/contract.ts
  • 阅读顺序：先看它直接导入的被测实现 packages/storage/storage-sqlite/src/index.ts、packages/storage/storage/src/index.ts、vendor/cordis/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 272 行；扫描到的声明包括 backendAt、freshDbPath；扫描到的测试主题包括 “sqlite backend specifics”、“opens an in-memory database”、“materializes STRICT record tables and stamps the schema version”、“rejects a mismatched database schema version”、“rejects invalid unit and table names before touching the medium”、“rejects a second open of the same unit name”。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/storage/storage/src/backend.ts ​

  • 所属层：packages/storage：可复用的 Harness 功能包
  • 文件角色：外部能力适配层
  • 这个文件有什么用：它把外部协议转换成存储能理解的内部协议。转换集中在边界，核心逻辑就不必到处处理供应商差异。
  • 为什么这样设计：把“接口是什么”和“这一版怎样实现”分开，替换实现或写测试替身时不必改动使用者。
  • 文件级设计证据：源码顶部注释把它定位为“Backend-facing vocabulary of the storage hub: a backend owns one medium (a file-tree root, a database file) and exposes operation groups over it. This module defines the normative contract text for backend implementers; the shared conformance suite in tests...”；固定提交中扫描到的声明包括 UNIT_NAME_RE、StorageBackend、KvFacet、KvUnitDescriptor、KvUnit；本地静态 import 图显示它直接依赖 0 个源文件，并被 3 个源文件直接引用。
  • 直接协作者：packages/storage/storage/README.md、packages/storage/storage/src/index.ts、packages/storage/storage/src/registry.ts、packages/storage/storage/tests/contract.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：apps/web/tests/sidebar-subagent-activity.e2e.ts、packages/feedback/message-feedback/tests/invariant.spec.ts、packages/feedback/message-feedback/tests/loader-composition.spec.ts、packages/feedback/message-feedback/tests/message-feedback.spec.ts、packages/host/apiproxy/tests/api-proxy-fork.spec.ts、packages/host/apiproxy/tests/api-proxy-workspace.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读 packages/storage/storage/README.md 和入口，再读当前实现，沿着相关类型、协议或实现和 packages/storage/storage/src/index.ts、packages/storage/storage/src/registry.ts、packages/storage/storage/tests/contract.ts 确认输入输出，最后对照 apps/web/tests/sidebar-subagent-activity.e2e.ts、packages/feedback/message-feedback/tests/invariant.spec.ts、packages/feedback/message-feedback/tests/loader-composition.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 104 行；扫描到的声明包括 UNIT_NAME_RE、StorageBackend、KvFacet、KvUnitDescriptor、KvUnit；源码顶部原注释（英文，仅作回查线索）：Backend-facing vocabulary of the storage hub: a backend owns one medium (a file-tree root, a database file) and exposes operation groups over it. This module defines the normative contract text for backend implementers; the shared conformance suite in tests...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/storage/storage/src/error.ts ​

  • 所属层：packages/storage：可复用的 Harness 功能包
  • 文件角色：错误模型
  • 这个文件有什么用：这个文件统一错误的类型、名称或转换方式。统一错误格式能让日志、用户界面和重试策略看懂同一件事。
  • 为什么这样设计：固定提交的文件顶部注释把它定位为“Error vocabulary for the storage hub and its backends. @module @deepseek-ai/dsh-storage/src/error”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
  • 文件级设计证据：源码顶部注释把它定位为“Error vocabulary for the storage hub and its backends. @module @deepseek-ai/dsh-storage/src/error”；固定提交中扫描到的声明包括 StorageErrorCode、StorageError；本地静态 import 图显示它直接依赖 0 个源文件，并被 2 个源文件直接引用。
  • 直接协作者：packages/storage/storage/README.md、packages/storage/storage/src/index.ts、packages/storage/storage/src/registry.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：apps/web/tests/sidebar-subagent-activity.e2e.ts、packages/feedback/message-feedback/tests/invariant.spec.ts、packages/feedback/message-feedback/tests/loader-composition.spec.ts、packages/feedback/message-feedback/tests/message-feedback.spec.ts、packages/host/apiproxy/tests/api-proxy-fork.spec.ts、packages/host/apiproxy/tests/api-proxy-workspace.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读 packages/storage/storage/README.md 和入口，再读当前实现，沿着相关类型、协议或实现和 packages/storage/storage/src/index.ts、packages/storage/storage/src/registry.ts 确认输入输出，最后对照 apps/web/tests/sidebar-subagent-activity.e2e.ts、packages/feedback/message-feedback/tests/invariant.spec.ts、packages/feedback/message-feedback/tests/loader-composition.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 35 行；扫描到的声明包括 StorageErrorCode、StorageError；源码顶部原注释（英文，仅作回查线索）：Error vocabulary for the storage hub and its backends. @module @deepseek-ai/dsh-storage/src/error。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/storage/storage/src/index.ts ​

packages/storage/storage/src/invariant.ts ​

  • 所属层：packages/storage：可复用的 Harness 功能包
  • 文件角色：运行时不变量
  • 这个文件有什么用：它检查存储必须始终成立的条件，在错误刚出现时报告，而不是等到更深层才出现难以解释的结果。
  • 为什么这样设计：把不变量集中在一个位置，调用者和测试就能用同一条规则检查状态；错误在边界处报告，比在后续 UI 或网络请求中才暴露更容易修复。
  • 文件级设计证据：源码顶部注释把它定位为“Package-owned invariant companion for @deepseek-ai/dsh-storage. @module @deepseek-ai/dsh-storage/invariant”；固定提交中扫描到的声明包括 name、inject、apply；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/storage/storage/README.md、packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts
  • 对应测试：没有确认到直接测试；公共入口可能仍有间接覆盖。
  • 测试关联依据：固定提交中没有找到直接或传递的本地静态 import，也没有找到明显的同包同名测试；公共入口可能仍有间接覆盖。
  • 阅读顺序：先读相关类型和事件，再读当前状态或存储实现，沿着 packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts 和所在包的入口或服务理解状态变化，最后对照同包中与它同名或覆盖相近场景的测试。
  • 代码证据：固定提交归档实际读取结果：约 32 行；扫描到的声明包括 name、inject、apply；源码顶部原注释（英文，仅作回查线索）：Package-owned invariant companion for @deepseek-ai/dsh-storage. @module @deepseek-ai/dsh-storage/invariant。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/storage/storage/src/registry.ts ​

packages/storage/storage/tests/contract.ts ​

  • 所属层：packages/storage：可复用的 Harness 功能包
  • 文件角色：共享测试契约
  • 这个文件有什么用：它为存储定义多种实现都必须通过的共同测试规则，避免 JSONL、SQLite 或不同宿主各自测试出不同标准。
  • 为什么这样设计：多个实现共享同一组契约测试，才能比较它们是否遵守相同的外部行为；契约与具体实现分开也能减少复制断言。
  • 文件级设计证据：源码顶部注释把它定位为“Shared KV-backend conformance suite. Each backend's spec file calls runKvBackendContract with a factory bound to its own medium; the suite asserts every clause of the src/backend.ts contract so both backends are held to identical semantics. @module”；固定提交中扫描到的声明包括 KvBackendContractHarness、runKvBackendContract；本地静态 import 图显示它直接依赖 1 个源文件，并被 2 个源文件直接引用。
  • 直接协作者：packages/storage/storage/README.md、packages/storage/storage/src/backend.ts、packages/storage/storage-json/tests/json-backend.spec.ts、packages/storage/storage-sqlite/tests/sqlite-backend.spec.ts
  • 对应测试：packages/storage/storage-json/tests/json-backend.spec.ts、packages/storage/storage-sqlite/tests/sqlite-backend.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；这些测试用例实际使用了本支持文件。
  • 阅读顺序：先读 packages/storage/storage/README.md 和入口，再读当前实现，沿着 packages/storage/storage/src/backend.ts 和 packages/storage/storage-json/tests/json-backend.spec.ts、packages/storage/storage-sqlite/tests/sqlite-backend.spec.ts 确认输入输出，最后对照 packages/storage/storage-json/tests/json-backend.spec.ts、packages/storage/storage-sqlite/tests/sqlite-backend.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 102 行；扫描到的声明包括 KvBackendContractHarness、runKvBackendContract；扫描到的测试主题包括 “kv backend contract: ${label}”、“opens a missing unit as empty and serves loadAll immediately”、“round-trips records and global durably across reopen”、“putRecord overwrites and deleteRecord is idempotent”、“rejects a version mismatch on reopen without touching the data”、“rejects operations after unit close, and close is idempotent”；源码顶部原注释（英文，仅作回查线索）：Shared KV-backend conformance suite. Each backend's spec file calls runKvBackendContract with a factory bound to its own medium; the suite asserts every clause of the src/backend.ts contract so both backends are held to identical semantics. @module。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/storage/storage/tests/registry.spec.ts ​

  • 所属层：packages/storage：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查存储的具体场景，包括“BackendRegistry”、“registers, resolves, and disposes names”、“rejects duplicate names”、“Storage service”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“BackendRegistry”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：本次固定提交归档没有扫描到顶部注释、顶层声明或专门的结构线索；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/storage/storage/README.md、packages/storage/storage/src/index.ts、vendor/cordis/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/storage/storage/src/index.ts、vendor/cordis/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 89 行；扫描到的测试主题包括 “BackendRegistry”、“registers, resolves, and disposes names”、“rejects duplicate names”、“Storage service”、“derives stable lifecycle service keys for named backends”、“mounts on the context and exposes registry plus form mounting”。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。