发布 agent-safe store catalog 与校验 action dispatch / Publish an agent-safe store catalog and validated action dispatch

[tiye]

中文

用户问题

Respo 希望向 actions/store 模式发展，但当前 devtools 或 AI agent 若要发现组件状态和可用 action，只能依赖内部 runtime tree、测试 inspection helper 或业务私有知识。直接暴露 raw tree 会绕过类型、codec、权限和生命周期边界，也容易把 ephemeral component state 误当成可持久业务数据。

面向用户的目标

工具可以通过稳定、只读、可序列化的 catalog 发现 store/action capability，并且只能通过已注册 codec 校验后发送 action；不能直接写 runtime tree。domain action 与 ephemeral component action 在协议中清楚区分。

范围

• 定义只读 store/action catalog entry，至少包含 target/scope、schema、version、ownership/recovery kind 和安全显示信息。
• 复用 action_envelope 与已注册 codec 校验输入 payload。
• 提供 runtime/inspection 层的 catalog 查询和 validated dispatch boundary。
• 区分 domain action、component store action 与不可安全投递的 capability。
• 对未知 target/schema/version、malformed payload 和未授权 action 默认拒绝。
• 用 Todo 或 Lab 完成一个端到端发现并投递 typed action 的 proof。
• 增加 Koka tests，并记录 agent/devtools 使用规则和安全边界。

验收标准

• catalog 完全可序列化且不包含 closure、raw state entry 或 DOM handle。
• 工具能枚举一个真实 feature 的 typed action target 和 schema/version。
• 合法 payload 经 codec 解码后走现有 typed dispatch/reducer/observation 链路。
• unknown schema/version、malformed payload 和不允许的 action 不改变 domain model 或 component store。
• domain 与 ephemeral component action 在 catalog/envelope 中可明确区分。
• 业务 view 不导入 runtime/inspection，也不增加 agent 专用 props。
• 不提供 raw state-tree write API。
• yarn test:koka 与 yarn check 通过，并有一条 host-level integration proof。

非目标

• 自动 replay 历史 domain action 或外部 effect action。
• 在本 issue 中实现完整权限 UI、远程身份认证或多租户策略。
• 将 component snapshot 作为 agent memory 或业务数据库。
• 允许 agent 绕过业务 reducer 直接修改 component state。

English

User problem

Respo is moving toward an actions/store model, but devtools or AI agents currently need internal runtime-tree knowledge, testing inspection helpers, or feature-private knowledge to discover component state and available actions. Exposing the raw tree would bypass type, codec, permission, and lifecycle boundaries and could make ephemeral component state look like persistent domain data.

User-facing goal

Tools can discover store/action capabilities through a stable, read-only, serializable catalog and can submit actions only after validation through registered codecs. They cannot write the runtime tree directly. Domain actions and ephemeral component actions are clearly distinguished by the protocol.

Scope

• Define read-only store/action catalog entries containing at least target/scope, schema, version, ownership/recovery kind, and safe display information.
• Reuse action_envelope and registered codecs to validate incoming payloads.
• Provide catalog queries and a validated dispatch boundary in runtime/inspection layers.
• Distinguish domain actions, component-store actions, and capabilities that are not safe to dispatch.
• Reject unknown targets/schemas/versions, malformed payloads, and unauthorized actions by default.
• Complete one end-to-end discovery and typed-action dispatch proof with Todo or Lab.
• Add Koka tests and document agent/devtools usage rules and safety boundaries.

Acceptance criteria

• The catalog is fully serializable and contains no closures, raw state entries, or DOM handles.
• A tool can enumerate a real feature typed-action target and schema/version.
• A valid payload is decoded by its codec and follows the existing typed dispatch/reducer/observation path.
• Unknown schema/version, malformed payload, and disallowed actions do not change the domain model or component store.
• Domain and ephemeral component actions are explicitly distinguishable in the catalog/envelope.
• Business views import no runtime/inspection module and gain no agent-specific props.
• No raw state-tree write API is exposed.
• yarn test:koka and yarn check pass with one host-level integration proof.

Non-goals

• Automatically replaying historical domain actions or external-effect actions.
• Implementing a complete permission UI, remote authentication, or multi-tenant policy in this issue.
• Treating component snapshots as agent memory or a business database.
• Allowing an agent to bypass business reducers and mutate component state directly.

[tiye]

中文

Roadmap 已由 PR #20 同步。本 issue 保持为后续探索批次；在 #17/#18 稳定 runtime 恢复与 cleanup 之前，不提前暴露 agent-facing mutation surface。

English

PR #20 synchronizes the roadmap. This remains a later exploration batch; no agent-facing mutation surface will be exposed before #17/#18 stabilize runtime recovery and cleanup.

[tiye]

中文

Roadmap 调整

本 issue 的安全边界和目标保持不变，但优先级调整为 priority: later。

从使用者路径重新评估后，当前更直接的阻碍发生在 agent/tooling 之前：新用户还需要理解三条 author imports，quick start 不能直接运行，常见 Koka 编译错误也缺少面向组件作者的诊断路径。因此先推进：

1. 提供单一组件作者导入入口 / Provide a single component-author import #23 单一 component-author import；
2. 交付可运行的首个组件示例 / Ship a runnable first-component example #24 可运行 first-component example；
3. 发布组件编译错误 cookbook / Publish a component compile-error cookbook #25 component compile-error cookbook；
4. 再实现本 issue 的 catalog/validated dispatch；
5. 提供只读 action/store 调试面板 / Provide a read-only action/store inspector #26 在该安全 catalog 上构建只读 action/store inspector。

这个顺序不会削弱 agent-safe 要求，反而先稳定人类用户使用的公共入口，再让 tools/agents 依赖同一套已验证 surface。

English

Roadmap adjustment

The safety boundary and goals of this issue remain unchanged, but its priority moves to priority: later.

Re-evaluating the project from the user journey shows more immediate blockers before agent/tooling integration: new users still need to understand three author imports, the quick start is not directly runnable, and common Koka compile errors lack a component-author diagnostic path. The revised order is:

1. 提供单一组件作者导入入口 / Provide a single component-author import #23 single component-author import;
2. 交付可运行的首个组件示例 / Ship a runnable first-component example #24 runnable first-component example;
3. 发布组件编译错误 cookbook / Publish a component compile-error cookbook #25 component compile-error cookbook;
4. this catalog/validated-dispatch issue;
5. 提供只读 action/store 调试面板 / Provide a read-only action/store inspector #26 read-only action/store inspector built on that safe catalog.

This order does not weaken agent-safety requirements. It stabilizes the public surface for human users first, then lets tools and agents depend on the same verified surface.

[tiye]

中文

进度同步

#23（单一 component-author import）、#24（可运行 first component）和 #25（组件错误与诊断 cookbook）现均已合并。至此，“先稳定人类组件作者的导入、首次成功路径和常见错误反馈”这一前置目标已经完成。

#19 因而成为下一项可启动的开发者工具基础工作：先设计完全可序列化、只读的 catalog 与 validated dispatch boundary，再考虑更高层的 inspector。当前没有开始实现，因此保留 priority: later，避免把计划误标为进行中。启动时仍必须遵守本 issue 的边界：不暴露 raw runtime tree/closure，不提供绕过 reducer 的写入 API，并以 Todo 或 Lab 做 end-to-end proof。

依赖关系

#26 继续依赖本 issue 提供的安全 catalog；在 #19 的 target/schema/version/ownership contract 和拒绝策略验证之前，不单独实现 inspector。

English

Progress update

#23 (single component-author import), #24 (runnable first component), and #25 (component error and diagnosis cookbook) are now merged. This completes the prerequisite of stabilizing the human component-author import, first-success path, and common-error feedback.

#19 is therefore the next candidate for developer-tooling foundation work: first design a fully serializable, read-only catalog and a validated-dispatch boundary, then consider a higher-level inspector. No implementation has started, so priority: later remains accurate rather than marking planned work as in progress. The issue boundaries still apply: expose no raw runtime tree/closure, provide no reducer-bypassing write API, and prove the flow end to end with Todo or Lab.

Dependencies

#26 continues to depend on the safe catalog from this issue. Do not implement the inspector independently before #19 validates its target/schema/version/ownership contract and rejection policy.