add explicit replay store recovery

Author: tiye

Agents.md

@@ -144,8 +144,10 @@ chrome-devtools take_screenshot --fullPage --filePath .tmp-devtools-full.png
 - UI 事件优先用 `on_store_click(name, action = ..., dispatch = ...)` / `on_store_input(...)` 发送 typed action，不直接操作 state tree。
 - domain action 事件优先用 `on_action_click(name, action = ..., dispatch = ...)` / `on_action_input(...)` / `on_action_enter(...)`，不要在每个 element 内重复 forwarding closure。
 - 只有包含额外分支、组合更新或直接 model 输入的 handler 才使用 `on_local_*`。
-- 一个 store 把 state 类型、action 类型、纯 reducer 和 versioned codecs 定义在一起；codec 只在 store 定义处出现，不传进组件调用。
-- `Store_spec(...)`、`State_codec(...)`、`Action_codec(...)` 的定义统一使用 labelled fields，显式写出 `name/schema/version/decode/encode/reduce`，不要依赖难以辨认的位置参数顺序。
+- 一个 store 把 state 类型、action 类型、纯 reducer、action codec 和显式 recovery policy 定义在一起；codec 只在 store 定义处出现，不传进组件调用。
+- store 统一通过 labelled `snapshot_store(...)` / `replay_store(...)` 构造，不让业务模块直接依赖 `Store_spec(...)` 的内部字段顺序。`State_codec(...)`、`Action_codec(...)` 仍显式写出 `schema/version/decode/encode`。
+- `snapshot_store(...)` 适合累积、toggle 或无法安全压缩的状态；`replay_store(...)` 只适合有明确 session 边界的纯 component actions，并使用 `Replay_start` / `Replay_replace(slot)` / `Replay_reset` 声明恢复语义。
+- replay slot 必须是有限、稳定的语义名称；不要用动态业务 id/用户输入制造 slot，也不要通过丢弃最早 action 强行限制日志。无法安全压缩时回到 snapshot store。
 - scope/path/slot/tree 属于 framework/runtime 细节；业务 view 只声明 keyed boundary，不手工拼 path。
 - 单个 keyed boundary 优先写成 `component(group, key) { ... }` / `feature_root(group, key) { ... }`，用 Koka trailing-lambda 语法让 lifecycle 边界有鲜明特征；列表仍用 labelled `components(...)` 保持 key/render 映射清楚。
 - `component(...)` / `components(...)` 表示 ordinary child：当前 feature 仍 render、但 child 不再出现时，其 local store 与 effect metadata 会自动清理。filter/条件分支隐藏 child 等同 unmount。
@@ -193,7 +195,7 @@ button(
 - component store 由 `use_store(...)` 返回的 dispatch 自动发 observation，业务 view 不重复埋点。
 - app/runtime 边界通过 `run_runtime_action_observed(...)` 获取有序 action 列表；不需要观察的测试或内部调用使用 `run_runtime_action(...)`。
 - observation 表示“已发送 intent”，不表示 reducer 成功或外部 effect 已提交。confirm 拒绝的 action 仍可被观察。
-- 未建立权限、effect response 和幂等策略前，不自动 replay，也不把 action log 混入 component-state snapshot。
+- `replay_store(...)` 的 scoped pure component-action log 可以进入 component snapshot，但与统一 observation stream 分开；未建立权限、effect response 和幂等策略前，不自动 replay domain/external-effect actions。
 - 新增 domain action 时，codec 与 action/reducer 放在同一 feature 模块，并覆盖 schema/version/payload 的 round-trip 测试。
 
 ## Element 调用约定
@@ -219,6 +221,7 @@ div([
 - scheduled effects 按组件求值顺序收集；不要把跨组件的 effect 顺序当作数据依赖。
 - snapshot entry 必须保留稳定 path、schema、version、payload；decoder 对 malformed payload、schema/version 不匹配安全回退。
 - `respo/component-scope` 是 runtime-owned lifecycle marker，会进入 snapshot；业务模块不得读取、构造或修改。ordinary child sweep 由 framework visitation 驱动，不在 reducer 中重建 path。
+- replay entry 使用 `respo/replay:<action-schema>`，只由 `replay_store(...)` 读写；业务 view 仍只使用 `(state, dispatch) = use_store(...)`。恢复策略与选择标准见 `docs/store-recovery.md`。
 - `src/main.js` 负责 localStorage 与 Vite HMR hand-off。修改浏览器桥时要验证 replacement 前 flush、dispose 和 `pagehide` 三条路径。
 - snapshot 只是组件临时状态恢复机制，不替代业务数据持久化。
 - lifecycle 规则和旧 snapshot 兼容限制见 `docs/component-lifecycle.md`。

PLAN.md

@@ -47,8 +47,12 @@
 
 ### Typed component store
 
-- `store_spec<s,a>` 将 state codec、action codec 和纯 reducer 组合在一起；
-- store 与 codec 定义使用完整 labelled fields，使 runtime identity、snapshot schema、action schema 与 reducer 职责在声明处清晰分组；
+- `store_spec<s,a>` 将 action codec、纯 reducer 和显式 recovery policy 组合在一起；
+- `snapshot_store(...)` 保存完整 typed state，适合累积、toggle 或不能安全压缩的 reducer；
+- `replay_store(...)` 保存当前 session 内压缩后的 typed component actions，不要求 state codec；
+- replay policy 只提供 `Replay_start` / `Replay_replace(slot)` / `Replay_reset`，框架不通过截断任意 action 历史换取有界日志；
+- Todo editor 使用 replay recovery，Lab incident 继续使用 snapshot recovery，组件调用保持同一个 `use_store(...)` reducer pair；
+- store 与 codec 定义使用完整 labelled fields，使 runtime identity、recovery、action schema 与 reducer 职责在声明处清晰分组；
 - 组件调用收敛为 `(state, dispatch) = use_store(spec, initial = ...)`，对齐 React `useReducer`；
 - `on_store_click(...)` / `on_store_input(...)` 使用 labelled `action + dispatch` 直接发 typed action；
 - binding record 与 `.current` / `.send` 不再暴露给业务 view；
@@ -80,6 +84,7 @@
 - snapshot 使用 path + schema + version + payload；
 - ordinary child ownership marker 会进入 snapshot；feature 恢复后可继续判断 stale child，旧版无 marker 的孤立 entry 不做不安全的 path 推断；
 - malformed snapshot、unknown schema 和 version mismatch 会安全回退；
+- replay store 使用 `respo/replay:<action-schema>` entry，从当前 `initial` 和 decoded component actions 恢复；
 - key segment 使用无碰撞 canonical encoding；现有 slug/数字路径保持不变，旧版空串、下划线开头或保留字符 key 的 snapshot 允许一次性回退 initial state；
 - `src/main.js` 在事件后合并保存，并在 HMR replacement、dispose、`pagehide` 前 flush；
 - 同一 snapshot 同时支持开发时 JS 替换和普通页面的 localStorage 恢复。
@@ -108,6 +113,8 @@ feature_marker(name)
 component(group, key) { ... }
 components(items, group = ..., key = ..., render = ...)
 
+snapshot_store(name = ..., state_codec = ..., action_codec = ..., reduce = ...)
+replay_store(name = ..., action_codec = ..., replay = ..., reduce = ...)
 use_store(spec, initial = ...)
 state_effect(name = ..., deps = ..., action = ...)
 on_store_click(name, action = ..., dispatch = ...)
@@ -150,12 +157,13 @@ feature_dom_marker(group = ..., key = ..., name = ...)
 - 评估是否提供框架级 codec combinators，减少 feature 手写 encode/decode；
 - 保持 decoder 失败时回退 initial state，不让单个坏 entry 阻断 boot。
 
-### 2. 定义 replay 与权限策略
+### 2. 评估 replay authoring 与权限策略
 
-- 为可安全 replay 的纯 action 增加显式 metadata，不从 codec 存在性推断；
+- Todo editor 已用显式 start/replace/reset policy 验证 session 型 replay；下一步先按 #8 的使用者标准评估定义规模与 HMR 行为，再决定是否推广；
+- 只有天然有界 session 使用 component replay，不能安全压缩的 store 保持 snapshot；
 - 外部 effect action 默认只允许 inspect，replay 需要 capability/permission；
 - 定义 confirmation、request、timer 等 effect 的 recorded response 与去重策略；
-- action log persistence 与 component-state snapshot 分开版本和保留周期；
+- agent/domain action log persistence 与 scoped component replay entry 分开版本、权限和保留周期；
 - devtools/agents 只能通过已注册 codec 解码和投递，不能写 raw state tree。
 
 ### 3. 拆分 component facade 与 runtime/testing API
@@ -186,8 +194,10 @@ feature_dom_marker(group = ..., key = ..., name = ...)
 ## GitHub 跟踪
 
 - [#7 Hide feature identity and remove cross-component store path coordination](https://github.com/Respo/explore-react.koka/issues/7)：已由 PR #10 合并；
-- [#8 Prototype action-replay component stores for HMR recovery](https://github.com/Respo/explore-react.koka/issues/8)：后续独立实验，不把外部 effect replay 混入本轮重构。
-- [#9 Define lifecycle cleanup for unreachable child component stores](https://github.com/Respo/explore-react.koka/issues/9)：当前实现批次；由 framework visitation 处理永久移除的 keyed child。
+- [#8 Reduce typed store boilerplate with explicit replay recovery](https://github.com/Respo/explore-react.koka/issues/8)：当前实现批次；以 Todo editor 的定义成本与恢复体验作为是否推广的标准；
+- [#9 Define lifecycle cleanup for unreachable child component stores](https://github.com/Respo/explore-react.koka/issues/9)：已由 PR #11 合并；
+- [#12 Simplify domain and local-store transitions in component events](https://github.com/Respo/explore-react.koka/issues/12)：等待 #8 明确 session 完成语义后再评估公共 abstraction；
+- [#13 Publish a progressive-disclosure component authoring surface](https://github.com/Respo/explore-react.koka/issues/13)：在 recovery API 稳定后整理 quick start、authoring API 与 module 边界。
 
 ## 验证标准
 
@@ -201,7 +211,8 @@ feature_dom_marker(group = ..., key = ..., name = ...)
 6. HMR replacement 后 component store 能从最新 snapshot 恢复；
 7. malformed/旧版本 snapshot 不导致 boot 失败；
 8. listener registry 没有 duplicate id 或 semantic drift warning；
-9. ordinary child unmount 会清理 store/effect/marker，整个 feature unmount 仍保留 snapshot。
+9. ordinary child unmount 会清理 store/effect/marker，整个 feature unmount 仍保留 snapshot；
+10. replay editor 的重复 input 只保留最新 draft，finish/cancel 回到最新 `initial`，malformed/version mismatch 安全回退。
 
 ## 非目标
 

README.md

@@ -205,7 +205,7 @@ setters. A store combines:
 - a state type;
 - a serializable action type;
 - one pure update function;
-- versioned codecs used by the runtime and snapshot boundary.
+- one explicit recovery choice at the store definition.
 
 ```koka
 pub struct task_editor_state(editing : bool, draft : string)
@@ -223,26 +223,34 @@ fun reduce_task_editor(current : task_editor_state, action : task_editor_action)
     Finish_edit -> current(editing = False)
     Cancel_edit(title) -> Task_editor_state(False, title)
 
-pub val task_editor_store : store_spec<task_editor_state,task_editor_action> = Store_spec(
+pub val task_editor_store : store_spec<task_editor_state,task_editor_action> = replay_store(
   name = "editor",
-  state_codec = State_codec(
-    schema = "todo/task-editor",
-    version = 1,
-    decode = decode_task_editor,
-    encode = encode_task_editor),
   action_codec = Action_codec(
     schema = "todo/task-editor-action",
     version = 1,
     decode = decode_task_editor_action,
     encode = encode_task_editor_action),
+  replay = fn(action) {
+    match action
+      Begin_edit(_) -> Replay_start
+      Change_draft(_) -> Replay_replace("draft")
+      Finish_edit -> Replay_reset
+      Cancel_edit(_) -> Replay_reset
+  },
   reduce = reduce_task_editor)
 ```
 
 Store definitions use labelled fields deliberately. `name` owns runtime
-identity, `state_codec` owns snapshot compatibility, `action_codec` owns the
-observable wire action, and `reduce` is the pure transition. Avoid positional
-`Store_spec(...)`, `State_codec(...)`, and `Action_codec(...)` calls: they are
-shorter but make schema/version and encode/decode order too easy to misread.
+identity, `action_codec` owns the observable wire action, and `reduce` is the
+pure transition. `replay` declares a bounded editor session: begin replaces an
+old session, repeated draft changes replace the same stable slot, and
+finish/cancel return to the call site's latest `initial` value.
+
+Use `snapshot_store(...)` when state cannot be safely represented by
+`Replay_start` / `Replay_replace(slot)` / `Replay_reset`. Counters, arbitrary
+toggle history, and accumulative collections normally keep an explicit state
+codec. The runtime never truncates arbitrary actions because doing so can
+change reducer semantics.
 
 The component-facing call mirrors React's reducer pair:
 
@@ -271,9 +279,11 @@ button(
     dispatch = dispatch))
 ```
 
-The codecs are defined once beside the store. They are not passed through every
-component call. Explicit scope/path/tree access is reserved for framework and
-testing code.
+The required codecs are defined once beside the store. They are not passed
+through every component call. Explicit scope/path/tree access is reserved for
+framework and testing code. See
+[`docs/store-recovery.md`](docs/store-recovery.md) for the recovery decision,
+replay modes, migration behavior, and complete examples.
 
 Feature render and panel APIs return only `vnode`. The app boundary owns the
 runtime tree through `runtime_frame`, and one `run_component(...)` pass collects
@@ -364,12 +374,13 @@ logger. The browser runtime uses `run_runtime_action_observed(...)` to log the
 same stream, while `run_runtime_action(...)` deliberately handles and discards
 it for callers that do not need observation.
 
-This is an intent log, not a replay engine. Dispatch is observed before the
-reducer/workflow runs, so an action remains visible even when confirmation
-rejects it. Replaying actions that invoke browser or service effects needs a
-separate policy for permissions, deduplication, and recorded responses. Until
-that policy exists, the runtime does not automatically persist or replay the
-action stream.
+This observation stream is an intent log, not a general replay engine. Dispatch
+is observed before the reducer/workflow runs, so an action remains visible even
+when confirmation rejects it. A component may explicitly choose
+`replay_store(...)`; that store persists only its own scoped pure actions and
+does not consume the observation stream. Replaying actions that invoke browser
+or service effects still needs a separate policy for permissions,
+deduplication, and recorded responses.
 
 ## State snapshots, HMR, and reloads
 
@@ -382,6 +393,8 @@ defensive:
 - malformed snapshot data is ignored instead of reaching a component decoder;
 - component state is restored only when its keyed scope and store schema still
   match;
+- replay stores use `respo/replay:<action-schema>` entries and rebuild state
+  from the current `initial` plus decoded component actions;
 - `respo/component-scope` metadata preserves ordinary-child ownership across
   HMR/reload so stale child branches can be swept on the next feature render.
 

demo/lab/state.kk

@@ -39,7 +39,7 @@ fun decode_incident_local_action(version : int, payload : string) : maybe<incide
   else if payload.head == "d" then Just(Change_incident_draft(payload.tail))
   else Nothing
 
-pub val incident_local_store : store_spec<incident_local_state,incident_local_action> = Store_spec(
+pub val incident_local_store : store_spec<incident_local_state,incident_local_action> = snapshot_store(
   name = "incident",
   state_codec = State_codec(
     schema = "lab/incident-local",

demo/tests.kk

@@ -27,11 +27,13 @@ pub fun demo_test_results() : <div> list<test_result>
     ordinary_component_lifecycle_test(),
     persistent_feature_lifecycle_test(),
     generic_state_codec_test(),
+    replay_empty_payload_test(),
     malformed_store_payload_test(),
     auto_hook_scope_test(),
     listener_registry_guard_test(),
     typed_action_listener_test(),
     todo_editor_store_protocol_test(),
+    todo_editor_replay_session_test(),
     unified_action_observation_test(),
     vnode_click_payload_matches_route_test(),
     harness_cancel_edit_test(),

demo/tests/statecases.kk

@@ -143,11 +143,42 @@ pub fun generic_state_codec_test() : <div> test_result
   val open_after = read_named_local_state(next_tree, scope_name, "open", False)
   Test_result("Implicit use_state codec", "draft=" ++ draft ++ ", open-before=" ++ open_before.show ++ ", open-after=" ++ open_after.show, draft == "hello" && not(open_before) && draft_after == "hello world" && open_after)
 
+pub fun replay_empty_payload_test() : <div> test_result
+  val scope_name = component_local_path("tests", "empty-replay-payload")
+  val empty_codec = Action_codec(
+    schema = "tests/empty-action",
+    version = 1,
+    decode = fn(version, payload) if version == 1 then Just(payload) else Nothing,
+    encode = fn(value : string) value)
+  val empty_store : store_spec<string,string> = replay_store(
+    name = "empty",
+    action_codec = empty_codec,
+    replay = fn(_action) Replay_start,
+    reduce = fn(_current, action) action)
+  val (run, _observed) = capture_actions(fn() run_local_state(Nil, fn() feature_root("tests", "empty-replay-payload") {
+    val (_current, dispatch) = use_store(empty_store, initial = "fallback")
+    dispatch("")
+  }))
+  val (_unit, tree, _effects) = run
+  val restored = read_store_state(
+    decode_state_snapshot(encode_state_snapshot(tree)),
+    scope_name,
+    empty_store,
+    "fallback")
+  val framed = match find(tree, fn(entry) entry.path == named_local_state_path(scope_name, "empty"))
+    Just(entry) -> entry.payload == "a"
+    Nothing -> False
+  Test_result("Replay framing preserves empty action payload", "restored='" ++ restored ++ "', framed=" ++ framed.show, restored == "" && framed)
+
 pub fun malformed_store_payload_test() : <div> test_result
   val todo_scope = "tests/malformed-todo"
   val todo_initial = Task_editor_state(False, "todo fallback")
-  val todo_tree = [State_entry(named_local_state_path(todo_scope, "editor"), "todo/task-editor", 1, "")]
+  val todo_tree = [State_entry(named_local_state_path(todo_scope, "editor"), "respo/replay:todo/task-editor-action", 1, "%")]
   val todo_state = read_store_state(todo_tree, todo_scope, task_editor_store, todo_initial)
+  val todo_version_tree = [State_entry(named_local_state_path(todo_scope, "editor"), "respo/replay:todo/task-editor-action", 9, "bOld")]
+  val todo_version_state = read_store_state(todo_version_tree, todo_scope, task_editor_store, todo_initial)
+  val todo_legacy_tree = [State_entry(named_local_state_path(todo_scope, "editor"), "todo/task-editor", 1, "1Old")]
+  val todo_legacy_state = read_store_state(todo_legacy_tree, todo_scope, task_editor_store, todo_initial)
   val todo_action_safe = match decode_store_action(task_editor_store, Action_envelope(source = "component", target = todo_scope, schema = "todo/task-editor-action", version = 1, payload = ""))
     Nothing -> True
     _ -> False
@@ -160,7 +191,7 @@ pub fun malformed_store_payload_test() : <div> test_result
     _ -> False
   val malformed_snapshot_safe = is-empty(decode_state_snapshot("path|schema|1|bad%"))
   val empty_snapshot_payload_valid = length(decode_state_snapshot("path|schema|1|")) == 1
-  val passed = todo_state.draft == "todo fallback" && lab_state.draft == "lab fallback" && todo_action_safe && lab_action_safe && malformed_snapshot_safe && empty_snapshot_payload_valid
+  val passed = todo_state.draft == "todo fallback" && todo_version_state.draft == "todo fallback" && todo_legacy_state.draft == "todo fallback" && lab_state.draft == "lab fallback" && todo_action_safe && lab_action_safe && malformed_snapshot_safe && empty_snapshot_payload_valid
   Test_result("Malformed store payloads are rejected", "todo=" ++ todo_action_safe.show ++ ", lab=" ++ lab_action_safe.show ++ ", snapshot=" ++ malformed_snapshot_safe.show, passed)
 
 pub fun auto_hook_scope_test() : <div> test_result