版本化 runtime snapshot 并定义兼容迁移 / Version runtime snapshots and define compatible migration

[tiye]

中文

用户问题

组件 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.

[tiye]

中文

Roadmap 已由 PR #20 同步。本 issue 是下一实现批次；#18 的 HMR cleanup 顺序将以这里确定的 snapshot flush/boot 契约为前置条件。

English

PR #20 synchronizes the roadmap. This issue is the next implementation batch; the HMR cleanup ordering in #18 depends on the snapshot flush/boot contract established here.

[tiye]

中文

PR #21 已提交：#21

实现已覆盖 versioned envelope、legacy headerless decode/re-encode、unknown/malformed 顶层版本回退、局部损坏隔离和 effect metadata exclusion。业务 view API 未变化。

验证结果：71 / 71 Koka tests、yarn check、旧 snapshot 浏览器启动、整页 reload 与真实 Vite HMR replacement 恢复均通过，浏览器无 warning/error。

请优先 review header detection 对 legacy 格式的区分，以及“顶层版本失败回退空树、entry 失败只丢弃自身”的边界。

English

PR #21 is ready: #21

The implementation covers the versioned envelope, legacy headerless decode/re-encode, unknown/malformed top-level fallback, partial-corruption isolation, and effect-metadata exclusion. The business-view API is unchanged.

Verification passed: 71 / 71 Koka tests, yarn check, browser boot from a legacy snapshot, full-page reload recovery, and a real Vite HMR replacement, with no browser warnings or errors.

Please prioritize the header detection boundary for the legacy format and the rule that top-level-version failure restores an empty tree while an entry failure drops only that entry.