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

中文

用户问题

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.

Start by reading the existing action_envelope, registered codecs, and runtime/inspection layers, then inspect the Todo or Lab feature as the proposed end-to-end proof. Use the catalog and dispatch requirements as the acceptance map; run yarn test:koka and yarn check, and verify the host-level integration proof rejects unknown, malformed, or unauthorized actions without changing state.