版本化 runtime snapshot 并兼容旧格式 / Version runtime snapshots with legacy compatibility

[tiye]

中文

用户可见结果

runtime snapshot 现在始终以 respo/runtime-snapshot|1 顶层 header 开始，包括空 runtime tree。升级后的框架仍能读取现有无 header、每行四字段的 snapshot，并在下一次保存时自然写成 versioned envelope。组件作者继续只选择 snapshot_store(...) 或 replay_store(...)，不接触 envelope。

安全与生命周期

• unknown、非数字或字段数错误的顶层版本安全回退为空 runtime tree，由组件使用各自 initial，不会阻断 boot。
• 已识别格式中的 malformed entry 或非法 URI encoding 只丢弃自身，其他合法 entry 继续恢复。
• entry 自己的 schema/version 校验保持不变；transport version 不绕过 typed store recovery。
• respo/effect render metadata 继续排除在 snapshot 外，domain model 也不进入该通道。
• 保留 koka-respo:component-state:v1 localStorage key，以便发现并恢复升级前保存的数据。
• 业务 view 没有新增 snapshot 参数，也没有新增 explore/react/runtime import。

文档

更新 README、store recovery、component lifecycle、PLAN 与 Agents 指引，说明 envelope/entry 两层版本职责、legacy migration、安全回退和 localStorage key 策略。

验证

• yarn test:koka：71 / 71 通过，新增 versioned header、空树、round-trip、effect exclusion、legacy decode/re-encode、partial corruption、unknown/malformed version 覆盖。
• yarn check：Koka 编译和 Vite production build 通过。
• 浏览器启动成功恢复上一版本遗留的无 header snapshot。
• Todo editor draft 在整页 reload 后恢复。
• 修改 draft 后运行真实 yarn build:koka 触发 Vite replacement，draft 继续保持。
• 浏览器无 warning/error。

关联 issue

Closes #17

English

User-visible result

Runtime snapshots now always start with a respo/runtime-snapshot|1 top-level header, including an empty runtime tree. The upgraded framework still reads the existing headerless four-field-per-line format and naturally writes a versioned envelope on the next save. Component authors continue to select only snapshot_store(...) or replay_store(...) and never handle the envelope.

Safety and lifecycle

• Unknown, non-numeric, or malformed top-level versions safely restore an empty runtime tree so components use their own initial values without blocking boot.
• A malformed entry or invalid URI encoding inside a recognized format drops only that entry; other valid entries still restore.
• Entry-level schema/version validation remains unchanged, so the transport version cannot bypass typed-store recovery.
• respo/effect render metadata remains excluded from snapshots, and the domain model never enters this channel.
• The existing koka-respo:component-state:v1 localStorage key is retained so pre-upgrade values remain discoverable.
• Business views gain no snapshot parameters or explore/react/runtime imports.

Documentation

Update README, store recovery, component lifecycle, PLAN, and Agents guidance with the envelope/entry version responsibilities, legacy migration, safe fallback, and localStorage-key policy.

Verification

• yarn test:koka: 71 / 71 passed, including new coverage for the versioned header, empty tree, round trip, effect exclusion, legacy decode/re-encode, partial corruption, and unknown/malformed versions.
• yarn check: Koka compilation and the Vite production build passed.
• Browser boot restored a headerless snapshot left by the previous runtime version.
• A Todo editor draft restored after a full page reload.
• Running a real yarn build:koka after another draft change triggered Vite replacement and preserved the draft.
• The browser reported no warnings or errors.

Related issue

Closes #17