中文

用户问题

组件 state entry 各自带 schema/version，但整个 runtime snapshot 还没有明确的顶层格式版本。JavaScript HMR 或 localStorage 中保存的旧 snapshot 遇到 wire format 变化时，框架无法可靠区分旧格式、未知新格式和局部损坏，组件作者也难以判断升级是否会丢失全部临时状态。

面向用户的目标

框架升级后，兼容的旧 snapshot 能继续恢复；不兼容或损坏的数据只安全回退相关状态，不阻断应用 boot。组件作者仍只定义 store recovery policy，不接触 snapshot envelope。

范围

• 为 runtime snapshot 增加明确的顶层标识与格式版本。
• 定义当前格式和现有无 envelope 格式之间的兼容读取策略。
• 保持 entry 级 schema/version 校验，并隔离 malformed entry。
• 明确 unsupported future version、空 snapshot 和非法编码的安全回退。
• 更新 store recovery、lifecycle、README/PLAN 中的升级契约。
• 增加 Koka round-trip/compatibility tests 和浏览器 reload/HMR 恢复回归。

验收标准

• 新编码结果包含可识别的顶层格式版本。
• 当前 decoder 能恢复合规的旧无 envelope snapshot。
• unknown top-level version 不导致 boot 失败，并安全回退到 initial state。
• 一个 malformed entry 不会丢弃同一 snapshot 中其他有效 entry。
• snapshot 仍排除 effect closure/metadata，不包含 domain model。
• 业务 view 和 store 调用点不新增 snapshot 参数或 runtime import。
• yarn test:koka、yarn check 与浏览器 reload/HMR 恢复链路通过。

非目标

• 把 component snapshot 变成领域数据持久化方案。
• 在本 issue 中提供任意 schema 的通用迁移 DSL。
• 加密 localStorage 或同步 snapshot 到服务端。
• 自动 replay domain action 或外部 effect action。

English

User problem

Individual component state entries carry schema/version data, but the complete runtime snapshot has no explicit top-level format version. When a JavaScript HMR hand-off or localStorage snapshot crosses a wire-format change, the framework cannot reliably distinguish a legacy format, an unknown future format, and partial corruption. Component authors cannot tell whether an upgrade will discard all transient state.

User-facing goal

Compatible legacy snapshots continue to restore after a framework upgrade. Incompatible or malformed data falls back only where necessary and never prevents application boot. Component authors continue to select a store recovery policy without handling the snapshot envelope.

Scope

• Add an explicit top-level marker and format version to runtime snapshots.
• Define compatible reading for the current format and the existing envelope-free format.
• Preserve entry-level schema/version validation and isolate malformed entries.
• Define safe fallback for unsupported future versions, empty snapshots, and invalid encoding.
• Update store-recovery, lifecycle, README, and PLAN upgrade contracts.
• Add Koka round-trip/compatibility tests and browser reload/HMR recovery coverage.

Acceptance criteria

• Newly encoded snapshots contain a recognizable top-level format version.
• The current decoder restores valid legacy envelope-free snapshots.
• An unknown top-level version does not break boot and safely falls back to initial state.
• One malformed entry does not discard other valid entries from the same snapshot.
• Snapshots still exclude effect closures/metadata and the domain model.
• Business views and store call sites gain no snapshot arguments or runtime imports.
• yarn test:koka, yarn check, and browser reload/HMR recovery pass.

Non-goals

• Turning component snapshots into domain-data persistence.
• Providing a general migration DSL for arbitrary schemas in this issue.
• Encrypting localStorage or synchronizing snapshots to a server.
• Automatically replaying domain actions or external-effect actions.