PysolateExplained
打开文档导航
本科生解释查看 Markdown 源文件

Receipt、effect truth 与 ambiguity

一句话

Pysolate 让 Host 分层记录它观察到的状态：Run/attempt outcome 可证明整体 not_started，capability receipt 记录 ok、error、denied、timeout 或 ambiguous，native transport 还单独报告 in-flight/unknown ambiguity。

先看一个例子

一个 Agent 向远端服务提交任务。请求发出后连接超时，Python 只看见 TimeoutError。

这个错误有至少两种解释：请求根本没离开本机；或者远端已经处理，只是响应在回来时丢了。此时自动重试可能是正确恢复，也可能把任务提交两遍。错误字符串本身无法告诉系统是哪一种。

Pysolate 因而记录调用在 Host 侧走到了哪里，并在证据不足时承认“不知道”。

真实机制

Broker 为被接纳的 operation 生成 Host-authored receipt。它绑定本次 Run、Plan、call、capability、operation index、request digest、outcome，以及成功时的 response digest；需要 approval 或 source binding 时还会绑定相应 identity。

这些状态属于不同层：

  • Run/attempt not_started：typed ExecutionOutcome 证明 workspace 与 effect 都没开始，例如 placement 收到 request-bound runtime_unsupported。not_started 不是 capability receipt status。
  • Capability receipt：approval 在 dispatch 前拒绝、过期或取消时记录 denied，handler 返回后记录 ok、error 或 timeout。当前 Broker 在 handler 已执行、但 approval audit completion 失败时记录 ambiguous。
  • Native transport ambiguity：同一 call_id 仍在执行或 channel 无法确定状态时，RPC 层返回 call_in_flight/ambiguous。Run response validation、publish 和 cleanup failure 又属于 Run 层，不能混成 receipt ambiguity。

Receipt 旁边还可以有 bounded transport evidence 和 observation event。它们共同构成 Host-owned effect truth：记录系统边界观察到的路径，而不是相信 Guest 自报结果。Guest 不能把自己构造的 receipt 字段升级成 Host evidence。

Native RPC 对相同 call_id 的已完成请求可以返回保存的 Broker response；如果原调用仍在进行，则报告 call_in_flight/ambiguous，而不是再次 dispatch。

当前还有两类 body-free 记录容易被误叫成 receipt。Prepared Family 的 member/acceptance record 记录输入、member、workspace 与 terminal identity；source-bound pass outcome 记录 registration、stage 与优化处置。它们都不表示 capability handler 已 dispatch，也不能证明外部世界状态。只有真正经过 Broker 的 operation 才产生 capability receipt。

为什么重要

技术上： retry、fallback 和 reconciliation 可以依据 typed lifecycle state，而不是解析 ImportError、timeout 文本或 provider message。当前 runtime 能在同一 native channel 内复用已完成 response，并对 in-flight/unknown fail closed；它没有通用 provider-side 或 durable reconciliation endpoint。

产品和业务上： 对可能计费、写入或触发外部动作的调用，重复执行往往比显式报错更危险。保留 ambiguous 后，上层可以另行实现人工确认或远端查询，而不是让 runtime 静默制造第二次操作。

不能推出什么

  • Receipt 证明 Host 记录了哪条调用路径，不证明远端世界最终一定处于某个状态。
  • Digest 证明请求或响应 bytes 的 identity，不证明其业务含义正确。
  • Terminal event 和 cleanup 不是 rollback；已经发生的外部 effect 不会自动撤销。
  • Family/pass record 不能替代 capability receipt、workspace receipt 或 external reconciliation。

术语卡

  • Receipt：Host 为一次 capability operation 生成的身份与结果记录。
  • Effect truth：Host 对 effect 生命周期实际观察到的状态。
  • Ambiguous：系统无法证明 effect 已完成或未发生的状态。
  • Reconciliation：在不重放 effect 的前提下复用已完成响应，或由上层另行查询/人工确认；当前 runtime 只实现其中的窄 channel-local 部分。
  • Transport evidence：受限保存的协议状态、媒体类型、body 长度与 digest，不保留 raw body。

继续阅读