diff --git a/docs/architecture/agent-failure-containment-and-recovery.md b/docs/architecture/agent-failure-containment-and-recovery.md new file mode 100644 index 0000000000..307e792287 --- /dev/null +++ b/docs/architecture/agent-failure-containment-and-recovery.md @@ -0,0 +1,219 @@ +# Agent failure containment and recovery + +[中文版](agent-failure-containment-and-recovery.zh-CN.md) + +LoopX has substantial mechanisms for execution failure, stale state, lost +responses and uncertain settlement effects. Containing an incorrect conclusion +and restoring the last correct business state remain partial. A durable record +proves what was recorded; correctness also needs relevant, current validation. + +This implementation map is based on source revision +`44931b6d22a50b949d43354e6ea498fb6b68d231`. It describes existing owners and their +limits, introduces no new runtime contract, and does not certify an installed +configuration or production failover. The +[overall roadmap](rfcs/loopx-overall-roadmap-v0.md) owns prioritization, especially +S2 durable authority, S10 reliability and S11 evaluation. + +## What is implemented + +| Required outcome | Existing mechanism | Remaining boundary | +| --- | --- | --- | +| Detect failure early | Typed admission/identity/lease checks; independent task validation; optional diagnostics and progress review | Most task validation follows the Host's bounded Turn. No general check proves every intermediate conclusion correct. | +| Contain propagation | Unknown-effect holds; lease expiry stops the owned process; source/version checks; current dependency and adoption readback; reviewed memory candidates | These cover specific authority and evidence boundaries. They do not retract every context, artifact or downstream completion derived from an incorrect claim. | +| Recover from trusted state | Durable Turn phases and effect readback; canonical state recovery; explicit Agent/Session continuation | Trust covers identity, recorded phases and declared verification scope. Arbitrary workspace rollback, external-effect rollback and automatic semantic failover are not established. | + +An Agent can make a wrong assumption and continue calling tools successfully. +Without a relevant validator or review, the transport, journal and lease may all +remain healthy. This is the central distinction between execution reliability +and reasoning correctness. + +## Four execution and evidence chains + +### 1. Classify failure before deciding to retry + +[`host_failure.py`](../../loopx/control_plane/turn_driver/host_failure.py) +classifies Host failures. `managed_step_receipt_from_journal` in +[`managed_step.py`](../../loopx/control_plane/turn_driver/managed_step.py) rejects +non-retryable failures. `decide_loop_disposition` in +[`loop_controller.py`](../../loopx/control_plane/turn_driver/loop_controller.py) +selects bounded retry, wait or repair from the typed result and remaining budget. + +Timeout has a two-attempt ceiling; capacity, overload, rate-limit and transport +failures have a three-attempt ceiling. Backoff is exponential, capped at 300 +seconds. These are scheduling hints for the outer caller, not an implicit sleep +or a universal retry loop. + +`hostRetryPolicyCheck` and `recoveryDecision` in +[`turn_journal.ts`](../../loopx/control_plane/turn_driver/turn_journal.ts) check +failure metadata, attempt consistency and budget. Explicit failed-Turn retry +retains compatibility for some non-retryable terminal failures; +`output_budget_exhausted` is rejected. This explicit repair surface is different +from automatic retry and does not establish that repeating the task will fix it. +See the [Turn loop contract](../reference/protocols/turn-loop-controller-v0.md). + +The benefit is bounded handling of known transient failures. A failed validator +or an unknown effect needs repair or reconciliation rather than blind rerun. + +### 2. Validate a Turn, then reconcile settlement effects + +`run_loopx_turn_once` in +[`executor.py`](../../loopx/control_plane/turn_driver/executor.py) runs the Host, +then `_task_validation_stage` checks the declared task postcondition before +settlement. Validation failure blocks the successful settlement path. A typed +stop result can make validation `not_required`; that is not a passed validator. + +`reduceTurnSettlementTransaction` in +[`settlement.ts`](../../loopx/control_plane/turn_driver/settlement.ts) owns the +ordered durable-writeback → quota-spend → terminal-closeout (when required) +decision. `settlementProviderAction` in +[`settlement_provider.ts`](../../loopx/control_plane/turn_driver/settlement_provider.ts) +decides the current provider action. +An effect intent is prepared before provider I/O. Recovery reads its outcome: + +- Committed with matching identity: record the missing checkpoint, without + repeating the effect. +- Absent: execute the same admitted intent. +- Unknown, unreadable or without a usable resolver: hold later effects. + +This prevents a lost response from automatically causing another side effect. +It does not undo file writes or API calls already made inside the Host. It also +does not provide a distributed transaction across arbitrary providers. The +[provider-effect acceptance RFC](rfcs/provider-effect-acceptance-v0.md) remains +design only, with no qualified runtime provider for its stronger guarantees. + +`runLeasedHostProcess` in +[`leased_host_process.ts`](../../loopx/control_plane/turn_driver/leased_host_process.ts) +checks execution proof before launch, during renewal and after output. A hung +renewal cannot extend the last proved deadline; expiry aborts and drains the +owned POSIX process group. Windows process-tree termination is explicitly best +effort, so that path cannot inherit the stronger drain guarantee. +This contains lost execution authority, not bad reasoning, +and cannot reverse an already admitted external effect. + +### 3. Require current sources and current result use + +`_verified_recalled_claims` in +[`Decision Context assembler`](../../loopx/capabilities/decision_context/assembler.py) +matches recalled content to an exact current authority read. Failed reads or +incomplete disposition do not advance the reviewed cursor. This prevents stale +recall from being presented as current source evidence. Exact source agreement +does not prove the source or its interpretation is true. + +[`Reward Memory candidate review`](../../loopx/capabilities/reward_memory/candidate_review.py) +checks freshness, conflict and scope during candidate construction. Reviewed +acceptance uses the stored candidate guard; retirement follows the active-record +lifecycle. [`application.py`](../../loopx/capabilities/reward_memory/application.py) +separately gates future recall against the current basis. Retirement does not +retract content already delivered into every +Agent context, undo derived artifacts or reverse effects. + +`accepted_result`, `require_dependencies` and `result_relationships` in +[`delegation_results.py`](../../loopx/control_plane/collaboration/delegation_results.py) +bind outputs and consumed inputs to hashes, rerun current validators and +re-evaluate adoption. Changed inputs can make a dependency or adoption +unavailable. Source current-read does not recursively qualify its own incoming +dependencies, so unavailable ancestry can remain hidden from a later consumer. +This readback does not automatically revoke canonical done/accepted state. The separate +[`Todo execution dependency`](../../loopx/control_plane/coordination/todo_execution_dependency.ts) +gate rejects missing, cyclic or unfinished predecessors; `todo_done` is a status +condition, not recursive proof of artifact truth. + +The benefit is that old success and message delivery cannot alone establish +current acceptance or actual adoption. General claim refutation and downstream +context retraction are still missing from these inspected owners. + +### 4. Resume proved phases or explicitly hand over current work + +The Turn journal resumes an incomplete phase from its recorded prefix. It +preserves prepared intents and receipts so that recovery can reconcile an +interrupted settlement instead of dispatching a completed Host again. + +`executeTodoContinuation` in +[`todo_continuation.ts`](../../loopx/control_plane/coordination/todo_continuation.ts) +supports explicit Agent/Session handover using current canonical Todo facts, +source session, note fingerprint and acceptance guards. The leased path also +checks execution dependencies; the soft-claim path does not generally provide +that dependency check. Hard-lease handover requires claim transfer and the +receiver's current proof; adoption is +revision-bound and read back. Receiving a note alone grants no execution right. + +The note retains attempted approaches and next steps, but its summary is still +sender-provided. Artifact availability is an existence check, not independent +proof of correct content. This is a governed continuation workflow, not an +automatic choice of the last correct workspace followed by rollback and core +replacement. + +## What each checkpoint proves + +| Checkpoint | Preserved or checked basis | Does not establish | +| --- | --- | --- | +| Turn journal | Goal/Agent/Todo identity, phase prefix, Host result, validation and effect receipts | Correct intermediate reasoning; a snapshot of all files or external effects | +| `checkpoint-context` / vision supplement | Current Goal, Todo, dependencies and source component hashes; unchanged read basis before supplement commit | That the model understood the source or repaired the implementation | +| AuthorityStore checkpoint / reviewed archive restore | Canonical projection, events and lineage; restore to a separate destination | Automatic restoration of the active workspace or all providers | +| Decision Context capture recovery | Reviewed cursor and private capture material within its declared recovery scope | Task or business-state rollback | +| Continuation note and adoption | Current task ownership, note basis, lease and receiver eligibility | That every inherited conclusion is correct | + +Relevant sources: [checkpoint context](../../loopx/control_plane/goals/checkpoint_context_io.py), +[read-context snapshot](../../loopx/control_plane/goals/checkpoint_read_context.ts), +[authority archive](../reference/authority-archive.md), +[capture recovery](../../loopx/capabilities/decision_context/capture_recovery.py). + +## Detection signals are scoped evidence + +[`Reliability diagnostics`](../../loopx/capabilities/reliability_diagnostics/README.md) +is an opt-in, default-off L1 observer. Its projection has no execution authority. +An active stage with at least five minutes of silence is a stall suspicion; +current liveness needs an explicit current `--as-of` value. Without it, status +uses the last event time for historical replay. Repetition compares consecutive +tool names, with a threshold of three, rather than parameters or business meaning. +Its recovered-error count means later step/Turn progress was observed; it does +not prove restored business correctness. + +The existing execution path uses +[`replan_history.ts`](../../loopx/control_plane/work_items/replan_history.ts) and +[`replan_semantics.ts`](../../loopx/control_plane/work_items/replan_semantics.ts). +Repeated typed progress across distinct Turns can require replan; a new ACK or +evidence name alone cannot qualify a semantic delta. These rules depend on +reported observations and their evidence owners. They are not a general +correctness oracle. Optional external review is also separate from L1 observation. + +## Validation and remaining delivery + +Existing regression surfaces include: + +- [Host failure](../../tests/test_loopx_turn_host_failure.py), + [loop controller](../../tests/test_loop_turn_loop_controller.py), + [journal](../../tests/control_plane_ts/turn_journal.test.ts) and + [settlement recovery](../../tests/test_loopx_turn_settlement_recovery.py). +- [Decision Context](../../tests/capabilities/test_decision_context_assembler.py), + [memory recall](../../tests/capabilities/test_reward_memory_agent_scoped_recall.py) + and [delegation result use](../../tests/test_delegation_result_use.py). +- [Diagnostics](../../tests/capabilities/test_reliability_diagnostics.py) and + [typed progress](../../tests/control_plane/test_progress_observation.py). + +These test designs include failures, stale sources, changed inputs and interrupted +effects. Fixture providers and disposable local state qualify their named +contracts; passing them does not establish live model correction, arbitrary +remote exactly-once effects or production recovery time. Diagnostics deployment, +overhead and long-running non-interference need separate evidence. + +The RFCs specify three remaining integration gaps in these partially implemented +paths: + +1. [Current-use checks for explicit delegation ancestry](rfcs/shared-goal-alignment-and-governed-amendment-v0.md#38-invalid-evidence-and-affected-consumers): + refuse new dependent use when its declared basis is unavailable, preserving + historical completion and bounding traversal/verification cost. +2. [Original-task repair and revalidation](rfcs/composable-state-machines-recovery-verification-v0.md#source-grounded-implementation-sequence): + carry independent failure evidence to an actionable recovery path, recheck + the current criterion and reconcile the original effects. +3. [Criterion-bound shadow assessment](rfcs/optional-semantic-assistance-jev-v0.md#detection-result-and-handoff-to-the-owning-rule): + expose actual evidence coverage, missing basis and separate judgment + dimensions, without promoting a non-triggering signal to correctness. + +The [composable recovery RFC](rfcs/composable-state-machines-recovery-verification-v0.md) +retains the open full M2 recovery boundary. The +[reliability diagnostics RFC](rfcs/long-running-agent-reliability-diagnostics-governed-delivery-v0.md) +owns observer qualification and governed intervention. The +[alignment RFC §3.7](rfcs/shared-goal-alignment-and-governed-amendment-v0.md#37-current-work-and-goal-requirements) +retains the open full-requirement ledger and global-closeout boundary. This map +does not close those acceptances or introduce a parallel roadmap. diff --git a/docs/architecture/agent-failure-containment-and-recovery.zh-CN.md b/docs/architecture/agent-failure-containment-and-recovery.zh-CN.md new file mode 100644 index 0000000000..26c4017824 --- /dev/null +++ b/docs/architecture/agent-failure-containment-and-recovery.zh-CN.md @@ -0,0 +1,97 @@ +# Agent 失败控制与恢复 + +[English](agent-failure-containment-and-recovery.md) + +LoopX 已经实质处理执行故障、陈旧状态、响应丢失和结算效果不明。对于错误结论的传播,以及从最后一个正确业务状态恢复,目前仍是部分实现。持久记录证明“记录了什么”;正确性还需要相关、当前的独立验证。 + +本实现地图依据源码版本 `44931b6d22a50b949d43354e6ea498fb6b68d231`,汇总现有 owner 与边界,不新增运行合同,不证明某个安装配置已启用或生产 Failover 已通过。[整体路线图](rfcs/loopx-overall-roadmap-v0.zh-CN.md)继续拥有优先级,尤其是 S2 持久权威状态、S10 可靠性与 S11 评估。 + +## 三个目标的落实程度 + +| 用户需要的结果 | 已有机制 | 尚未覆盖的边界 | +| --- | --- | --- | +| 尽早发现错误 | 类型化准入、身份与 lease 检查;独立任务验证;可选诊断与进展审查 | 任务验证通常发生在 Host 的有界 Turn 返回后。没有通用机制证明每个中间结论都正确。 | +| 限制错误传播 | 未知 effect 阻断;lease 失效停止所拥有的进程;来源与版本检查;依赖/采用的当前读回;记忆候选审阅 | 这些机制各有权威和证据边界,不能自动撤回所有受错误结论影响的上下文、产物与下游完成状态。 | +| 从可信状态恢复 | Turn 阶段与 effect 持久读回;canonical 状态恢复;显式跨 Agent/Session 接管 | 可信对象是身份、阶段记录和声明范围内的验证。任意文件回滚、外部副作用撤销、自动语义 Failover 尚未成立。 | + +例如,Agent 在第十步做出错误假设,后续工具仍正常返回:传输、journal 与 lease 都可能健康。如果没有相关 validator 或独立复核,这些机制不能自动发现第十步的假设错了。这是执行可靠性与推理正确性的关键区别。 + +## 四条真实执行与证据链 + +### 1. 先分类失败,再决定是否重试 + +[`host_failure.py`](../../loopx/control_plane/turn_driver/host_failure.py)分类 Host 故障;[`managed_step.py`](../../loopx/control_plane/turn_driver/managed_step.py)的 `managed_step_receipt_from_journal` 拒绝非 retryable 故障;[`loop_controller.py`](../../loopx/control_plane/turn_driver/loop_controller.py)的 `decide_loop_disposition` 根据类型化结果与剩余预算选择有限重试、等待或修复。 + +Timeout 的尝试上限为两次;capacity、overload、rate-limit、transport 故障为三次。退避指数增长,最多 300 秒。这是外层调用者的调度依据,不是隐式 sleep 或通用无限重试循环。 + +[`turn_journal.ts`](../../loopx/control_plane/turn_driver/turn_journal.ts)的 `hostRetryPolicyCheck` / `recoveryDecision` 校验故障字段、尝试次数一致性和预算。显式 failed-Turn retry 为部分非 retryable 终态故障保留兼容路径,`output_budget_exhausted` 被拒绝。这属于显式修复入口,与自动重试不同,也不证明重复执行能修好问题。合同见 [Turn loop](../reference/protocols/turn-loop-controller-v0.md)。 + +这条链的收益是让已知瞬时故障得到有界处理。Validator 失败或副作用未知,需要修复或对账,不能靠盲目 rerun 消除。 + +### 2. 验证 Turn,再对账结算效果 + +[`executor.py`](../../loopx/control_plane/turn_driver/executor.py)的 `run_loopx_turn_once` 执行 Host,再由 `_task_validation_stage` 检查声明的任务后置条件,之后才进入结算。验证失败阻断成功结算;类型化 stop result 可以令验证为 `not_required`,它不等于 validator 通过。 + +[`settlement.ts`](../../loopx/control_plane/turn_driver/settlement.ts)的 `reduceTurnSettlementTransaction` 拥有 durable-writeback → quota-spend → terminal-closeout(需要时)的有序决策;[`settlement_provider.ts`](../../loopx/control_plane/turn_driver/settlement_provider.ts)的 `settlementProviderAction` 决定当前 provider 操作。在 provider I/O 前记录 effect intent,恢复时读回结果: + +- 已提交且身份匹配:补记丢失的 checkpoint,不重复效果。 +- 确认不存在:执行同一个已准入 intent。 +- 未知、无法读取或没有可用 resolver:阻断后续效果。 + +因此,响应丢失不会自动变成再次执行副作用。但它不能撤销 Host 内已发生的文件写入或 API 调用,也不提供跨任意 provider 的分布式事务。[Provider-effect acceptance RFC](rfcs/provider-effect-acceptance-v0.zh-CN.md)的更强保证仍是设计,尚无完成运行接入与资格验证的 provider。 + +[`leased_host_process.ts`](../../loopx/control_plane/turn_driver/leased_host_process.ts)的 `runLeasedHostProcess` 在启动前、续约和输出结束后校验执行证明。续约卡住不会延长最近一次证明的截止时间;到期会 abort 并 drain 所拥有的 POSIX 进程组。Windows 的进程树终止明确为 best effort,不能继承更强的 drain 保证。它控制执行授权失效,不能识别错误推理,也不能逆转已准入的外部效果。 + +### 3. 后续使用必须有当前来源与结果依据 + +[`Decision Context assembler`](../../loopx/capabilities/decision_context/assembler.py)的 `_verified_recalled_claims` 将 recalled content 与当前 authority 的 exact read 对照。读取失败或 disposition 不完整,不能推进 reviewed cursor。这能防止旧记忆冒充当前来源证据;内容完全一致仍不证明来源或解释正确。 + +[`Reward Memory candidate review`](../../loopx/capabilities/reward_memory/candidate_review.py)在生成候选时检查 freshness、conflict 与 scope;审阅接受使用候选已保存的 guard,退休遵循 active 记录的生命周期。[`application.py`](../../loopx/capabilities/reward_memory/application.py)另外检查后续 recall 的当前依据。Retire 不会自动撤回已经进入所有 Agent Context 的内容、撤销衍生产物或逆转效果。 + +[`delegation_results.py`](../../loopx/control_plane/collaboration/delegation_results.py)的 `accepted_result`、`require_dependencies` 与 `result_relationships` 绑定输出/实际输入 hash,重跑当前 validator,并重新检查 adoption。输入改变可以使依赖或采用关系 unavailable;source current-read 不递归资格化自己的 incoming dependencies,后续 consumer 因而可能看不到上游依据不可用。这种读回也不会自动撤销 canonical done/accepted 状态。另一条 [`Todo execution dependency`](../../loopx/control_plane/coordination/todo_execution_dependency.ts)准入链会拒绝缺失、循环和未完成前件;`todo_done` 是状态条件,不是递归验证产物真值。 + +实际收益是:旧的成功记录、收到消息,都不能单独证明当前验收或实际采用。所查 owner 尚未提供通用的结论反驳与下游上下文撤回协议。 + +### 4. 续执行已证明阶段,或显式交接当前任务 + +Turn journal 根据持久化的合法阶段前缀继续未完成阶段,保留 prepared intent 与 receipt。恢复因此可以对账中断的结算,而不必重新派发已经完成的 Host。 + +[`todo_continuation.ts`](../../loopx/control_plane/coordination/todo_continuation.ts)的 `executeTodoContinuation` 支持显式跨 Agent/Session 接管,检查当前 canonical Todo facts、source session、note fingerprint 与 acceptance guard。Leased 路径另查 execution dependencies,soft-claim 路径不普遍提供这一依赖检查。Hard lease 接管需要转移 claim 和接收者自己的 current proof;adoption 绑定 revision 并读回。收到 note 本身不授予执行权。 + +Note 能保留尝试过的路径与下一步,但 summary 仍由发送者提供;artifact availability 检查的是存在性,不是内容正确的独立证明。这是受控的 continuation 工作流,尚不是自动选取最后正确 workspace、回滚并更换 core 的完整闭环。 + +## Checkpoint 到底可信在哪里 + +| Checkpoint | 保存或校验的依据 | 不能据此证明 | +| --- | --- | --- | +| Turn journal | Goal/Agent/Todo 身份、阶段前缀、Host result、验证与 effect receipt | 中间推理正确;所有文件和外部效果已快照 | +| `checkpoint-context` / vision supplement | 当前 Goal、Todo、依赖与 source component hash;补记前读取依据未变化 | 模型已经正确理解来源或修复实现 | +| AuthorityStore checkpoint / reviewed archive restore | Canonical projection、事件与 lineage;恢复到独立 destination | 自动恢复活跃 workspace 或全部 provider | +| Decision Context capture recovery | 声明恢复范围内的 reviewed cursor 与私有 capture material | 任务或业务状态回滚 | +| Continuation note 与 adoption | 当前任务归属、note basis、lease 与 receiver eligibility | 继承的每条结论正确 | + +对应源码与合同:[checkpoint context](../../loopx/control_plane/goals/checkpoint_context_io.py)、[read-context snapshot](../../loopx/control_plane/goals/checkpoint_read_context.ts)、[authority archive](../reference/authority-archive.md)、[capture recovery](../../loopx/capabilities/decision_context/capture_recovery.py)。 + +## 检测信号不能越过自身证据范围 + +[`Reliability diagnostics`](../../loopx/capabilities/reliability_diagnostics/README.zh-CN.md)是显式 opt-in、默认关闭的 L1 observer,其 projection 没有执行权。活跃阶段静默至少五分钟是 stall 嫌疑;实时活性判断需要显式传当前 `--as-of`,不传则用末事件时间作历史重放。Repetition 按连续相同 tool name 达三次判断,不比较参数或业务语义。Recovered-error count 仅表示错误后观察到 step/Turn 进展,不能证明业务已恢复正确。 + +真正影响执行的既有 replan 使用 [`replan_history.ts`](../../loopx/control_plane/work_items/replan_history.ts) 与 [`replan_semantics.ts`](../../loopx/control_plane/work_items/replan_semantics.ts)。不同 Turn 的重复 typed progress 可以要求 replan;新增 ACK 或 evidence 名字本身不能构成合格 semantic delta。这仍依赖合法上报与证据 owner,不是通用正确性判定器。可选外部审查与 L1 被动观察也有独立边界。 + +## 验证方式与尚待交付的结果 + +现有回归入口包括: + +- [Host failure](../../tests/test_loopx_turn_host_failure.py)、[loop controller](../../tests/test_loop_turn_loop_controller.py)、[journal](../../tests/control_plane_ts/turn_journal.test.ts)、[settlement recovery](../../tests/test_loopx_turn_settlement_recovery.py)。 +- [Decision Context](../../tests/capabilities/test_decision_context_assembler.py)、[memory recall](../../tests/capabilities/test_reward_memory_agent_scoped_recall.py)、[delegation result use](../../tests/test_delegation_result_use.py)。 +- [Diagnostics](../../tests/capabilities/test_reliability_diagnostics.py)、[typed progress](../../tests/control_plane/test_progress_observation.py)。 + +这些测试设计包含失败、陈旧来源、输入改变和 effect 中断等负例。Fixture provider 与一次性本地状态验证各自合同;通过不等于真实模型纠错、任意远端 exactly-once 或生产恢复时间合格。诊断部署、开销与长时间 non-interference 需要独立证据。 + +RFC 明确了这些部分实现路径中仍需补齐的三项整合缺口: + +1. [显式委派来源链的当前使用检查](rfcs/shared-goal-alignment-and-governed-amendment-v0.zh-CN.md#38-失效证据与受影响消费者):声明依据不可用时拒绝新的依赖使用,保留历史完成,限制遍历与验证成本。 +2. [原任务修复与复验](rfcs/composable-state-machines-recovery-verification-v0.zh-CN.md#基于源码的实现顺序):把独立失败依据传入可操作恢复路径,按当前 criterion 复验,再对账原效果。 +3. [绑定 criterion 的 shadow 评估](rfcs/optional-semantic-assistance-jev-v0.zh-CN.md#检测结果与所属规则的衔接):显示实际证据覆盖、缺失依据和独立判断维度,不能把未触发信号升级为正确性证明。 + +[Composable recovery RFC](rfcs/composable-state-machines-recovery-verification-v0.zh-CN.md)保留完整 M2 recovery 的开放边界;[Reliability diagnostics RFC](rfcs/long-running-agent-reliability-diagnostics-governed-delivery-v0.zh-CN.md)拥有 observer 资格验证与受控干预;[Alignment RFC §3.7](rfcs/shared-goal-alignment-and-governed-amendment-v0.zh-CN.md#37-当前工作与-goal-要求)保留 full-requirement ledger 与 global closeout 的未完成范围。本地图不关闭这些验收,也不另建平行路线图。 diff --git a/docs/architecture/rfcs/composable-state-machines-recovery-verification-v0.md b/docs/architecture/rfcs/composable-state-machines-recovery-verification-v0.md index 9a67fbebd3..2b68db8414 100644 --- a/docs/architecture/rfcs/composable-state-machines-recovery-verification-v0.md +++ b/docs/architecture/rfcs/composable-state-machines-recovery-verification-v0.md @@ -5,7 +5,7 @@ - **Delivery maturity:** Partial implementation; bounded Turn recovery coverage, full M2 remains open - **Authors / owners:** Control-plane domain maintainers and testing maintainers - **Created:** 2026-10-01 -- **Last normative revision:** 2026-10-01 +- **Last normative revision:** 2026-10-08 - **Implementation baseline:** `98acf52e7e41c193959bd45db622c65298273714` - **Related contracts:** [Effect Interpreter](agent-loop-effect-interpreter-v0.md), [TS migration](typescript-control-plane-migration-v0.md), [shared authority](shared-goal-authority-state-provider-v0.md), [quality layers](../../development/testing-and-quality.md), [overall roadmap](loopx-overall-roadmap-v0.md) - **Language mirror:** [中文版](composable-state-machines-recovery-verification-v0.zh-CN.md) @@ -38,6 +38,11 @@ writeback followed by a lost response can invite a duplicate effect. A cleared gate can leave its successor permanently quiet. Local tests of each owner do not establish the causal relationship across these boundaries. +A valid Host result can contain an incorrect artifact. Its failure evidence must +reach the owning admission and recovery path before more work relies on it. +A resumed process, advanced journal phase or accepted handover alone does not +prove that the business error was corrected. + ### Invariants - One owner decides each domain transition; projections and receipts cannot @@ -125,6 +130,63 @@ or blind retry. Pure decision replay, receipt recovery and counterfactual simulation follow the separate [Effect Interpreter](agent-loop-effect-interpreter-v0.md) contracts. +### Detection, containment and recovery evidence + +These are composition cases, not a new shared error enum or production incident +ledger. Optional assessment follows the +[bounded detection contract](optional-semantic-assistance-jev-v0.md#detection-result-and-handoff-to-the-owning-rule); +current use of affected evidence follows +[alignment §3.8](shared-goal-alignment-and-governed-amendment-v0.md#38-invalid-evidence-and-affected-consumers). + +| Observation and owning evidence | Permitted containment | Required recovery evidence | +| --- | --- | --- | +| Identity, permission or lease check fails | Refuse new protected execution/commit; stop an owned process only under its qualified Host contract | Current authorized owner and valid preconditions; old output grants no new authority | +| Typed transient Host failure | Existing bounded retry policy, same logical intent and checked attempt budget | Current admission and resolved effect uncertainty; backoff alone proves no repair | +| Independent task/acceptance check fails for a named criterion | Block successful acceptance/settlement in that scope; retain the failed candidate and original identities | Actual repair or permitted replan, then a current check of the criterion and declared inputs | +| Validator unavailable, inconclusive or necessary input unreadable | Preserve lack of evidence and the existing fail-closed gate | Obtain usable evidence; inability to check does not prove content false | +| Observer/model suspects drift | Advisory or an explicitly enabled existing replan path | Domain investigation/current verification; confidence or a non-triggering signal cannot clear a confirmed failure | +| Explicit consumer basis becomes invalid/unavailable | Refuse new current use at its dependency/acceptance boundary; preserve history and unrelated work | Current permitted source and consumer eligibility; confirmed semantic failure also requires criterion revalidation | +| Provider outcome is unknown | Retain intent and hold later effects | Same-operation authoritative readback; no replacement identity | + +Each recovery trace retains the challenged criterion/precondition, source and +validator basis, affected Goal/Todo/Turn/artifact/effect identities, committed or +unknown effects, permitted next action and the check that releases the +restriction. Reuse existing records and fields. This is not a universal wire +packet; a necessary extension belongs to its real producer and consumer. + +Correct JSON and hashes around a wrong calculation still fail a criterion that +checks the calculation. File existence cannot qualify that stronger claim. Bind +the declared verifier to its version, scope and current source basis; silently +weakening it is not repair. Non-executable criteria name the authorized review +and deciding evidence, rather than treating another model's confidence as proof. +Check before consequential acceptance/use and after relevant basis changes, +with explicit cost and coverage limits; per-step hidden-reasoning verification +is not required. Late detection distinguishes prevented, committed and unknown +effects. Local recovery cannot silently compensate another provider's effect. + +```text +observation + declared criterion/source basis + → owning check: failure, insufficient evidence, or bounded concern + → scoped admission/acceptance decision with original identities + → authorized repair, replan, takeover or same-operation reconciliation + → current verification + unresolved-effect readback + → resume eligible work, or retain a visible scoped restriction +``` + +These arrows compose existing owners, not a global state machine. Taking over +unfinished repair work does not require its completion validator to pass first. +It requires current ownership, honest failed/unknown facts and existing execution +admission. Before claiming recovery, the receiver independently satisfies the +affected completion/use condition. + +The last trusted recovery point is a **named verified basis**: identities, +declared artifact/source versions, applicable validation and effect receipts. +If only the phase journal survives, claim phase recovery only. Missing artifacts, +versions or verification scope require an explicit limit and authorized +reconstruction/revalidation. This is not automatic workspace rollback or +arbitrary external-state restoration. Replan acceptance, context delivery, +process progress and business recovery remain distinct. + ### Safety and conditional progress Safety assertions hold for every explored prefix. Progress assertions explicitly @@ -181,6 +243,8 @@ slice through its existing protocol; this RFC authorizes no data migration. | Implementation agreement | Pinned base/head production-entrypoint traces and independent durable readback | Intended semantics preserved; disclosed changes independently justified | Real affected backend required | | Test sensitivity | A historical defect or deliberate semantic mutation | The relevant invariant fails before/faulted and passes after repair | Do not derive expectations from candidate output | | User-visible continuity | Affected CLI and packaged App/Lark journeys | Truthful state, next action and original-context result | Omitted entrypoints explicitly unqualified | +| Business error containment | Valid identity/hash with content violating the declared criterion | Independent failure blocks new successful acceptance/use in that scope | Malformed-packet detection alone is insufficient | +| Recovery basis | Artifact, verifier, criterion or source changes between check and recovery | Old success cannot qualify a new basis; unknown effects still require readback | No arbitrary filesystem/external-effect rollback claim | Record seed or deterministic enumeration, trace bound, normalized observations, failure/skipped counts and a minimal counterexample in existing PR evidence. @@ -238,6 +302,49 @@ and App/Lark delivery remain outside it. M2 therefore remains open. Its next owning work is the existing ownership-to-settlement acceptance with a real lease/GoalRef fence, followed by M3's actual delivery callers. +### Source-grounded implementation sequence + +These are unimplemented composition deltas within existing M2/M3 and roadmap +R2/R3/R4, not new milestones. Source owners were rechecked at +`44931b6d22a50b949d43354e6ea498fb6b68d231`. + +| Bounded outcome | Existing entry and owner | Current gap and decisive exit | +| --- | --- | --- | +| Unavailable declared ancestry prevents new dependent use | `Delegations._read_current/start`, `delegation_results.require_dependencies/adoption_evidence`, `delegation.ts` | Alignment §3.8: source → A → B with A input invalidated must refuse current dependent use even if A output is unchanged. Qualify real read/start/adopt/settlement and packaged evidence readback; keep historical completion. | +| Independent check failure reaches an actionable original-task recovery journey | `executor._task_validation_stage`, `ValidatedTurnReceipt`, canonical `turn_loop_controller_contract_v0.json`, `turn_journal.ts` | Preserve qualified failure scope and repair/replan detail; complete bounded repair or verifier-only retry, current validation and original-effect settlement. Host assertions cannot become trusted validation. | +| Optional semantic review explains its evidence and coverage | Existing progress-review receipt/loader and canonical Goal acceptance inspection | Bind a selected criterion and evidence coverage in shadow readback; show missing/stale basis and separate judgment dimensions. Model quality and intervention qualify separately. | + +For the second outcome, `_task_validation_stage` already saves the independent +result and blocks settlement. `ValidatedTurnReceipt` omits that validation's +`recovery_kind`; the canonical controller intentionally maps legacy +`validation_failed` to generic repair. Preserving a trusted validator's replan +request is a disclosed contract extension, not a violation of today's rule. +Change the canonical contract, `scripts/generate_turn_contract.py` and the +existing `validation_failed`/`repair` definitions in +`loopx/semantics/vocabulary_v0.json`, retaining legacy omitted detail as generic +repair. Do not hand-edit generated code or add +a parallel Python decision source. Review missing, malformed and contradictory +detail and old/new reader compatibility before selecting a wire change. + +Failed-Turn retry at `validation_stage=task_postcondition` already reuses the +cached Host result and reruns validation without invoking the Host again. +**Doing repair work** needs its own current bounded execution admission, followed +by revalidation. Reuse criterion/verifier pins where the acceptance owner supplies +them. A generic command without retained verification basis cannot become a +durable business checkpoint because its exit code was zero. A replacement check +cannot erase an old unknown effect. + +Start with independent counterexamples in existing fixtures, then production +entrypoints with real validator commands and a disposable supported backend. +Cover missing evidence, stale verifier/source, same-operation replay, failure +during repair, stop/takeover and lost effect response. The Todo/Turn view must +expose the failed check and scope, support authorized repair/recheck, and read +back success or continued failure in the packaged App; CLI and affected Lark +entries share the owner. A command-copy button or backend receipt alone does not +complete the journey. Bound repeated verification and source-chain traversal +using measured workloads. Roll back code through its owner while retaining +receipts, completed effects and unresolved recovery obligations. + ## 12. Open decisions The first M2 implementation must choose its smallest sufficient exploration diff --git a/docs/architecture/rfcs/composable-state-machines-recovery-verification-v0.zh-CN.md b/docs/architecture/rfcs/composable-state-machines-recovery-verification-v0.zh-CN.md index bc828e726b..95bf06b563 100644 --- a/docs/architecture/rfcs/composable-state-machines-recovery-verification-v0.zh-CN.md +++ b/docs/architecture/rfcs/composable-state-machines-recovery-verification-v0.zh-CN.md @@ -5,7 +5,7 @@ - **交付成熟度:** 部分实现;已有有界 Turn 恢复验证,完整 M2 仍开放 - **作者 / 负责人:** 控制面领域维护者与测试维护者 - **创建:** 2026-10-01 -- **最近规范修订:** 2026-10-01 +- **最近规范修订:** 2026-10-08 - **实现基线:** `98acf52e7e41c193959bd45db622c65298273714` - **相关契约:** [Effect Interpreter](agent-loop-effect-interpreter-v0.zh-CN.md)、[TS 迁移](typescript-control-plane-migration-v0.zh-CN.md)、[共享权威](shared-goal-authority-state-provider-v0.zh-CN.md)、[质量分层](../../development/testing-and-quality.md)、[总路线](loopx-overall-roadmap-v0.zh-CN.md) - **语言镜像:** [English](composable-state-machines-recovery-verification-v0.md) @@ -32,6 +32,10 @@ PR 证据。本 RFC 不增加产品 capability、provider、wire schema、运行 effect;gate 解除后 successor 可能一直 quiet。逐个 owner 的局部测试不能证明这些 边界之间的因果关系。 +合法 Host result 也可能携带错误产物。失败证据须在更多工作依赖它之前到达所属 +准入和恢复路径。进程恢复、journal 阶段推进或接管成功,都不能单独证明业务错误 +已被修正。 + ### 不变量 - 每个领域转换只有一个 owner;projection 和 receipt 不能铸造新权限。 @@ -100,6 +104,52 @@ provider acceptance 继续由各自执行边界负责。 纯决策回放、receipt 恢复和假设模拟遵循 [Effect Interpreter](agent-loop-effect-interpreter-v0.zh-CN.md) 的独立合同。 +### 检测、控制与恢复证据 + +下表是组合情形,不是新的共享错误枚举或生产事件账本。可选评估遵循 +[有界检测合同](optional-semantic-assistance-jev-v0.zh-CN.md#检测结果与所属规则的衔接), +受影响证据的当前使用遵循[对齐 §3.8](shared-goal-alignment-and-governed-amendment-v0.zh-CN.md#38-失效证据与受影响消费者)。 + +| 观察与所属证据 | 可采取的控制 | 恢复需要的证据 | +| --- | --- | --- | +| 身份、权限或 lease 检查失败 | 拒绝新的受保护执行/提交;仅按已资格化 Host 合同停止所拥有进程 | 当前合法 owner 与有效前提;旧输出不授予新权限 | +| 类型化瞬时 Host 故障 | 既有有限重试政策、同一逻辑 intent 与已检查次数预算 | 当前准入与已解决的效果不确定性;退避不证明修复 | +| 独立 task/acceptance 检查发现具名 criterion 失败 | 阻断该范围的成功验收/结算;保留失败 candidate 与原身份 | 实际修复或合法重规划,再按当前依据检查 criterion 及声明输入 | +| Validator 不可用、无定论或必要输入不可读 | 保留证据缺失与既有 fail-closed gate | 取得可用证据;无法检查不等于内容为假 | +| Observer/模型怀疑偏离 | Advisory,或显式启用的既有 replan 路径 | 领域调查/当前验证;信心或未触发信号不解除已确认失败 | +| 显式消费依据失效/不可用 | 在所属依赖/验收边界拒绝新的当前使用;保留历史与无关工作 | 当前获准来源与 consumer eligibility;语义失败已确认时另需 criterion 重验 | +| Provider 效果未知 | 保留 intent,阻断后续效果 | 同 operation 的权威读回;不能生成替代身份 | + +每条恢复轨迹保留:被质疑的 criterion/前提、source 与 validator basis、受影响 +Goal/Todo/Turn/artifact/effect 身份、已提交或未知效果、获准下一步及解除限制所需 +检查。复用已有记录与字段,不设计通用 wire packet;必要扩展归真实 producer 和 +consumer 所有。 + +JSON 与 hash 正确的错误计算结果,仍不满足计算正确的 criterion;文件存在不能 +验收更强的主张。声明 verifier 须绑定版本、范围与当前来源,悄悄放宽检查不算修复。 +不可执行的 criterion 应指明获授权评审与决定性证据,不能把另一个模型的信心当 +证明。在会产生后果的验收/使用前及相关依据变化后检查,并明确成本和覆盖限制; +不要求验证每个隐藏推理步骤。发现较晚时,区分被阻止、已经提交和仍未知的效果。 +本地恢复不能隐式补偿其他 provider 的效果。 + +```text +观察 + 声明的 criterion/source basis + → 所属检查:失败、证据不足或有界疑虑 + → 原身份下的有范围准入/验收决定 + → 获授权修复、重规划、接管或同 operation 对账 + → 当前验证 + 未解决效果读回 + → 继续合格工作,或保留可见的有范围限制 +``` + +箭头组合既有 owner,不创建全局状态机。接管尚未完成的修复任务,不要求先通过 +完成 validator;要求当前归属、如实传递失败/未知事实和既有执行准入。声明恢复 +之前,接收者须独立满足受影响的完成/使用条件。 + +最近可信恢复点是**具名且经过验证的依据**:身份、声明产物/来源版本、适用验证与 +效果 receipt。若只保存阶段 journal,就只能声明阶段恢复;产物、版本或验证范围 +缺失时,应明确限制,在既有权限内重建和重验。这不等于自动回滚 workspace 或 +任意外部状态。Replan 接受、context 送达、流程继续和业务恢复保持独立。 + ### 安全性与有条件推进 每个被探索前缀都必须满足安全性。推进断言显式写明适用前提:provider 最终可用、 @@ -146,6 +196,8 @@ provider 会使相应前提不成立;必须暴露这个事实,不能判定 | 实现一致 | pinned base/head 生产入口轨迹及独立持久回读 | 保留预期语义,有意变化独立论证 | 必须真实受影响 backend | | 测试敏感 | 历史缺陷或刻意语义 mutation | 修复前/注入后失败,修复后通过 | 不从候选输出生成预期 | | 用户接续 | 受影响 CLI 与打包 App/Lark 旅程 | 状态、下一动作和原上下文结果真实 | 未覆盖入口明确未资格化 | +| 业务错误控制 | 身份/hash 合法,但内容违反声明 criterion | 独立失败阻断该范围新的成功验收/使用 | 仅发现报文格式非法不够 | +| 恢复依据 | 检查与恢复之间产物、verifier、criterion 或 source 改变 | 旧成功不验收新依据;未知效果仍须读回 | 不声称任意文件/外部效果回滚 | 在既有 PR 证据中记录 seed 或确定性枚举、轨迹上限、归一化观察、失败/跳过数和 最小反例。缩减不得丢掉触发故障的因果前提。只长期保留保护持久行为的反例; @@ -195,6 +247,39 @@ PostgreSQL authority、successor 调度和 App/Lark 送达尚未覆盖。因此 后续沿用现有 ownership-to-settlement 验收,在真实 lease/GoalRef fence 下 补齐,再进入 M3 的实际送达 caller。 +### 基于源码的实现顺序 + +以下是既有 M2/M3 与路线图 R2/R3/R4 中尚未实现的组合增量,不新增里程碑。 +Source owner 在 `44931b6d22a50b949d43354e6ea498fb6b68d231` 复核。 + +| 有界结果 | 既有入口与 owner | 当前缺口与决定性出口 | +| --- | --- | --- | +| 声明来源链不可用时,阻止新的依赖使用 | `Delegations._read_current/start`、`delegation_results.require_dependencies/adoption_evidence`、`delegation.ts` | 遵循对齐 §3.8:source → A → B 中 A input 失效,即使 A output 不变也须拒绝当前依赖使用;验证真实 read/start/adopt/settlement 和打包证据读回,保留历史完成。 | +| 独立检查失败进入原任务可操作的恢复旅程 | `executor._task_validation_stage`、`ValidatedTurnReceipt`、canonical `turn_loop_controller_contract_v0.json`、`turn_journal.ts` | 传递已资格化失败范围与 repair/replan 细节;完成有界修复或只运行 verifier 的重试、当前验证与原效果结算。Host 声明不能冒充可信验证。 | +| 可选语义审查说明证据和覆盖范围 | 既有 progress-review receipt/loader 与 canonical Goal acceptance inspect | 在 shadow 读回绑定选中 criterion 和证据覆盖;显示缺失/陈旧依据及独立判断维度。模型质量和干预另行资格化。 | + +第二项中,`_task_validation_stage` 已保存独立结果并阻断结算;`ValidatedTurnReceipt` +未携带该验证的 `recovery_kind`,canonical controller 有意将 legacy +`validation_failed` 统一映射 generic repair。保留可信 validator 的 replan 请求是 +须披露的合同扩展,不是当前实现违反规则。修改 canonical 合同、 +`scripts/generate_turn_contract.py` 与 `loopx/semantics/vocabulary_v0.json` 中 +既有 `validation_failed`/`repair` 定义,旧记录缺少 detail 时继续 generic repair; +不手改 generated code,不新增平行 Python 决策源。选择 wire 变更前审查缺失、非法、 +矛盾细节以及新旧 reader 兼容。 + +`validation_stage=task_postcondition` 的 failed-Turn retry 已会复用缓存 Host +result,只重跑 validation,不再次调用 Host。**实际修复工作**需要自己的当前有界 +执行准入,然后复验。Acceptance owner 已提供 criterion/verifier pins 时复用它们; +未保留验证依据的 generic command 不能仅因退出码为零就成为持久业务 checkpoint。 +替代检查不能抹掉旧的 unknown effect。 + +先在既有 fixture 中建立独立反例,再用真实 validator 命令与一次性受支持 backend +验证生产入口。覆盖证据缺失、verifier/source 过期、同 operation 重放、修复再失败、 +停止/接管与 effect 响应丢失。Todo/Turn 视图须显示失败检查和范围,支持获授权 +修复/复验,并在打包 App 读回成功或继续失败;CLI 与受影响 Lark 入口共用 owner。 +复制命令按钮或后端 receipt 不能独自完成旅程。用实际测量限制重复验证和来源链遍历 +成本;经既有 owner 回退代码,同时保留 receipt、已提交效果和未解决恢复义务。 + ## 12. 未决事项 首个 M2 实现由测试与领域维护者选择足够小的探索方法及边界。优先复用 fixture diff --git a/docs/architecture/rfcs/optional-semantic-assistance-jev-v0.md b/docs/architecture/rfcs/optional-semantic-assistance-jev-v0.md index b54883f031..3d4af87063 100644 --- a/docs/architecture/rfcs/optional-semantic-assistance-jev-v0.md +++ b/docs/architecture/rfcs/optional-semantic-assistance-jev-v0.md @@ -3,7 +3,7 @@ - **RFC status:** Accepted - **Supersedes / closes:** none - **Delivery maturity:** Research proposal; a separate D1-only optional shadow implementation is proposed in Appendix A. No model qualification or automatic correction is established. The default-off sentinel capability and its recorded differential live in [`loopx/capabilities/progress_review`](../../../loopx/capabilities/progress_review/README.md); those numbers do not prove implementation qualification or product adoption. -- **Created:** 2026-09-19. **Last normative revision:** 2026-09-20. +- **Created:** 2026-09-19. **Last normative revision:** 2026-10-08. - **Implementation baseline:** `9f1916960306b3650d795895b89f331eeae2516e`; source ownership and trigger behavior rechecked at PR revision `27812bd0fb437f831a541b564bcb5be8a96ff77e`. Historical upstream inspection is recorded in Appendix A, not a whole-system certification. - **Authors / owners:** Proposal author; existing domain maintainers own any direction selected. No new runtime authority or assigned implementation owner. - **Language mirror:** [中文版](optional-semantic-assistance-jev-v0.zh-CN.md) @@ -194,6 +194,69 @@ For D1, study goal relationship and evidence increment separately. Preserve nece Use artifact-based input as the primary comparison. Keep author claims separate and evaluate absent/neutral/praising/critical self-description as an ablation on the same artifacts. Measure classification and probability shifts; do not assert that labeling claims untrusted eliminates influence, or that removing all explanations is universally best. Any context needed to explain a prerequisite must have attributable support. Source text remains untrusted even after author summaries are removed. +#### Detection result and handoff to the owning rule + +An assessment must identify a falsifiable question: which declared criterion, +claim or dependency is challenged, on which revision, and what observation would +resolve the challenge. A run that uses valid tools, changes identifiers and +passes unrelated tests can still preserve a wrong assumption. Conversely, a +negative experiment or necessary prerequisite can advance the Goal. Tool success, +activity, novelty and author confidence cannot decide between those cases. + +Keep three responsibilities separate: + +1. **Acquire evidence.** Bind the current Goal/criterion basis, attributable + Turn and artifact versions, the relevant before/after observations and + verifier identity/result. Declare selected files, omitted dependencies, + truncation and missing history. A manually written assessment basis is not + automatically the canonical Goal acceptance revision. An exact read proves + provenance; a hash cannot prove content true or coverage complete. +2. **Assess the bounded question.** Report the actual dimensions and unresolved + evidence. Goal relationship and evidence increment remain separate: work can + be off Goal and produce new evidence. A combined drift signal of `false` + means that signal's intervention condition did not hold, not that all work + was correct or on Goal. Missing or stale evidence remains unevaluated or + uncertain under the existing receipt contract; it is not a negative finding + and cannot clear a confirmed domain failure. +3. **Let the existing owner decide the consequence.** Shadow assessment is + advisory; an explicitly enabled `assist` policy may require the existing + replan obligation from a qualified signal. That policy decision does not + establish that a business criterion failed. A current domain validator or + authorized review may establish that + a named criterion is violated; it must retain its evidence, scope and + authority. The existing acceptance, replan, dependency or effect owner then + decides refusal, repair, replan or reconciliation. No assessment score grants + stop, mutation, rollback or completion authority. + +For an authorized caller, evaluate at the smallest useful boundary before a +consequential result is accepted, consumed by another task or admitted as a +protected effect. A final-only review cannot contain all earlier effects; a +per-token/per-tool model reviewer is not required. Declare the evidence window, +deadline, cost budget and missed-boundary behavior. Keep mandatory deterministic +checks effective when optional assessment is unavailable. Measure detection +delay, false intervention against legitimate work and missed failures. Sample +cases that never generated an alert as well as alerted cases; alert-only review +cannot estimate missed failures. + +Source recheck at `44931b6d22a50b949d43354e6ea498fb6b68d231`: +the optional `packages/loopx-jev` capture reads a declared file set and its net +change; it does not observe every intermediate assertion. Core +[`external_progress_review_trigger`](../../../loopx/control_plane/work_items/external_progress_review.py) +consumes attributable receipts at a pinned assessment revision. In `assist`, a +qualified streak can open the existing replan obligation; a newer completed +non-triggering verdict can end that streak. This is the current signal policy, +not a business-correctness certificate. The +[`progress-review` contract](../../../loopx/capabilities/progress_review/README.md) +and its owner retain off/shadow/assist compatibility. Any change to the combined +signal or its clearing policy needs explicit disclosure and counterexamples; +this design does not silently change it. + +The downstream contract is [evidence invalidation in shared work](shared-goal-alignment-and-governed-amendment-v0.md#38-invalid-evidence-and-affected-consumers) +and [recovery qualification](composable-state-machines-recovery-verification-v0.md#detection-containment-and-recovery-evidence). +First connect existing verifier results and dependency readback to those owners. +Additional model inference is conditional on the comparison in section 6; it is +not a prerequisite for fixing a demonstrated deterministic gap. + ### 5.3 Provider facts and deferred mechanisms The [TypeSafe API](https://docs.typesafe.ai/api) accepts state, keyed typed questions and a requested model, returning keyed answers and an actual model. [Confidence](https://docs.typesafe.ai/confidence) is derived from the Choice/Score probability distribution; Noul has no separate confidence field. Raw probabilities do not cure biased evidence, and neither value is measured engineering correctness or authority. Retain provider-specific semantics rather than inventing equivalent confidence for other models. diff --git a/docs/architecture/rfcs/optional-semantic-assistance-jev-v0.zh-CN.md b/docs/architecture/rfcs/optional-semantic-assistance-jev-v0.zh-CN.md index bf13a7ad72..286e7354d2 100644 --- a/docs/architecture/rfcs/optional-semantic-assistance-jev-v0.zh-CN.md +++ b/docs/architecture/rfcs/optional-semantic-assistance-jev-v0.zh-CN.md @@ -3,7 +3,7 @@ - **RFC status:** 已接受 - **替代 / 关闭:** 无 - **Delivery maturity:** 研究提案;附录 A 单独提出仅 D1 的可选 shadow 实现,没有建立模型质量资格或自动纠正效果。默认关闭的哨兵 capability 及其录制对照见 [`loopx/capabilities/progress_review`](../../../loopx/capabilities/progress_review/README.zh-CN.md);这些数字不证明实现资格或产品采用。 -- **Created:** 2026-09-19。**Last normative revision:** 2026-09-20。 +- **Created:** 2026-09-19。**Last normative revision:** 2026-10-08。 - **Implementation baseline:** `9f1916960306b3650d795895b89f331eeae2516e`;在 PR 版本 `27812bd0fb437f831a541b564bcb5be8a96ff77e` 重新核对源码归属与触发器行为。历史 upstream 检查记于附录 A,不构成全系统认证。 - **Authors / owners:** 提案作者;被选方向由现有领域维护者负责。不新增运行时权威,也未指派实施 owner。 - **Language mirror:** [English](optional-semantic-assistance-jev-v0.md) @@ -194,6 +194,50 @@ D1 分别研究目标关系与证据增量。保留必要前置、合理阻塞 主要比较采用基于产物的输入。作者声明分离保存,在相同产物上增加无自述/中性/自夸/自贬的消融比较。观察分类和概率变化,不能断言标记为不可信就消除了影响,也不能断言删除全部解释总是最好。解释前置必要性的上下文应有可归属支持;即使删除作者摘要,源码内容仍是不可信输入。 +#### 检测结果与所属规则的衔接 + +评估须指向一个可证伪的问题:质疑的是哪个已声明 criterion、结论或依赖,依据哪个 +版本,什么观察能够解决质疑。合法调用工具、更换标识、通过无关测试,仍可能保留 +错误假设;负面实验或必要前置工作也可能推进 Goal。工具成功、活动量、新颖性与 +作者信心均不能单独判定这两类情况。 + +三种责任分别保留: + +1. **取得证据。** 绑定当前 Goal/criterion 依据、可归属 Turn、产物版本、相关前后 + 观察及 verifier 身份/结果。声明选中文件、遗漏依赖、截断和缺失历史。手写评估 + basis 不自动等于 canonical Goal acceptance revision;exact read 证明来源, + hash 不证明内容真实或覆盖完整。 +2. **评估有限问题。** 保留实际判断维度与未解决证据。目标关系和证据增量独立: + 工作可能偏离目标,同时产生新证据。组合 drift signal 为 `false` 只表示该 + 信号的干预条件不成立,不代表所有工作正确或符合目标。缺失/过期证据按现有 + receipt 合同保持未评估或不确定,不是反向证据,也不能解除已确认的领域失败。 +3. **由既有 owner 决定后果。** Shadow 评估属于 advisory;显式启用的 `assist` + 政策可根据合格信号要求处理既有 replan 义务。该政策决定不等于确认业务 criterion + 失败。当前领域 validator 或获授权评审可以确认具名 criterion 被违反, + 但须保留证据、范围与权限;再由 + acceptance、replan、dependency 或 effect owner 决定拒绝、修复、重规划或对账。 + 评估分数不授予停止、修改、回滚或完成权限。 + +获授权 caller 应选择会产生实际后果之前的最小有效边界,例如结果被验收、被其他 +任务消费或被准入为受保护 effect 之前。仅在最后评审无法控制此前全部效果;不要求 +逐 token/逐工具调用模型审查。须声明证据窗口、截止时间、成本预算及错过检查点后的 +行为。可选评估不可用时,必要的确定性检查仍生效。除检测延迟外,还要测量对合法 +工作的误干预与漏报。告警和从未告警的记录都要抽查;只审查告警记录无法估计漏报。 + +源码在 `44931b6d22a50b949d43354e6ea498fb6b68d231` 复核:可选 +`packages/loopx-jev` capture 读取声明文件集合及净变化,不观察每条中间断言。 +核心 [`external_progress_review_trigger`](../../../loopx/control_plane/work_items/external_progress_review.py) +消费身份可归属、评估版本已固定的回执。`assist` 可把合格连续信号转为既有 replan +义务;较新的已完成、未触发 verdict 可以结束该连续信号。这是当前信号政策,不是 +业务正确证明。[progress-review 合同](../../../loopx/capabilities/progress_review/README.zh-CN.md) +继续拥有 off/shadow/assist 兼容性。修改组合信号或解除政策须明确披露并提供反例, +本设计不隐式改变当前行为。 + +后续连接[共享工作中的证据失效](shared-goal-alignment-and-governed-amendment-v0.zh-CN.md#38-失效证据与受影响消费者) +与[恢复资格](composable-state-machines-recovery-verification-v0.zh-CN.md#检测控制与恢复证据)。 +优先把现有 verifier 结果与依赖读回接到这些 owner;增加模型推理仍取决于第 6 节 +比较,不能成为修复已证实确定性缺口的前置条件。 + ### 5.3 提供方事实与延后机制 [TypeSafe API](https://docs.typesafe.ai/api) 接受 state、按 key 组织的类型化问题及请求模型,返回同 key 答案和实际模型。[Confidence](https://docs.typesafe.ai/confidence) 来自 Choice/Score 概率分布;Noul 没有独立 confidence 字段。原始概率不能修复有偏证据,两种数值都不等于实测工程正确率或权限。保留提供方特有语义,不为其他模型伪造等价 confidence。 diff --git a/docs/architecture/rfcs/shared-goal-alignment-and-governed-amendment-v0.md b/docs/architecture/rfcs/shared-goal-alignment-and-governed-amendment-v0.md index 62b721b86c..68b60e3e50 100644 --- a/docs/architecture/rfcs/shared-goal-alignment-and-governed-amendment-v0.md +++ b/docs/architecture/rfcs/shared-goal-alignment-and-governed-amendment-v0.md @@ -4,7 +4,7 @@ - Supersedes / closes: none - Tracking issue: [#3836](https://github.com/huangruiteng/loopx/issues/3836) - Date: 2026-09-02 -- Last updated: 2026-09-16 +- Last updated: 2026-10-08 - Scope: peer Agents collaborating around one shared Goal while preserving canonical intent, per-Agent execution frontiers, claim/lease ownership, and auditable replan/amendment decisions @@ -332,6 +332,84 @@ S11; this RFC does not silently enable a new acceptance policy. The next complet slice should map existing structured criteria through a work switch and restart, reject dropped coverage, and invalidate stale evidence under the same owner. +### 3.8 Invalid evidence and affected consumers + +This is a proposed qualification contract for existing acceptance and explicit +result-use owners, not a new global error state, taint graph or automatic +amendment policy. Historical completion and current eligibility to use evidence +are separate facts. Preserve the original receipt, declared basis and outcome; +re-evaluate current applicability rather than rewriting a completed Todo to +make the history appear consistent. + +Source unavailability, changed version/scope and an owner-confirmed false claim +have different meanings. An unreadable source establishes no current evidence; +it does not establish that its content is false. A semantic refutation needs a +current criterion and attributable counterevidence accepted by the owning +validator or authorized review. Exact bytes and successful transport alone +cannot resolve it. Optional assessment follows the +[detection handoff contract](optional-semantic-assistance-jev-v0.md#detection-result-and-handoff-to-the-owning-rule). + +For an explicit relationship whose contract requires current evidence: + +1. Identify the source operation/artifact version, criterion and actual declared + consumer input. Keep the cause and affected scope readable. Do not infer + consumption from message delivery, shared keywords or all files in a workspace. +2. Revalidate that basis before new acceptance, adoption or the owning protected + execution boundary. An unchanged consumer output passing its local validator + does not independently prove the validity of its declared source chain. + Bind the decision to the observed versions at the actual admission boundary; + an earlier UI read or cached success cannot authorize later use. Preserve + unrelated work; do not stop every Agent because one source is missing. +3. Expose unavailable current use through the existing typed readback and guard. + Reads do not mutate history, clear leases, retract messages or spawn repair. + Do not reuse `goal_acceptance_stale` for arbitrary source failure: its current + owner means a changed acceptance/work binding. +4. Recovery obtains current source evidence, restores the exact permitted basis + or validates a replacement through its existing owner, then checks consumer + eligibility again. Restored bytes prove version availability only. A confirmed + semantic failure additionally needs its relevant criterion revalidated; a + model saying “fixed”, a fresh ACK or a new evidence ID is insufficient. + +Sender context is a record of prior reasoning. When affected work resumes or is +handed over, the existing context owner must carry the invalidated basis, the +unresolved point, current evidence and the next required check. This qualifies +new context delivery, not erasure of all previous sessions or proof that a model +understood the correction. Already committed external effects retain their own +reconciliation or explicitly authorized compensation contract. + +**Implementation boundary, source `44931b6d22a50b949d43354e6ea498fb6b68d231`:** +[`Delegations._read_current`](../../../loopx/collaboration_mcp.py) rechecks an +accepted operation's own rules and outputs; `read` subsequently attaches +[`result_relationships`](../../../loopx/control_plane/collaboration/delegation_results.py). +That operation can remain accepted while an incoming dependency is unavailable. +`dependencies` reads a source through `_read_current`, so this source's own +incoming dependency is not transitively checked. A bounded file-I/O diagnostic +with synthetic local validation reproduced this for source → A → B: A's input +changed, its output stayed unchanged, A showed an unavailable dependency and B's +direct use still qualified. This is not a live worker or canonical-store test. + +The nearest implementation slice qualifies **current use of explicitly linked +local delegation results**, while retaining historical accepted/done receipts. +Reuse [`delegation.ts`](../../../loopx/control_plane/collaboration/delegation.ts) +for typed eligibility and `delegation_results.py` for host observations. Apply +the same current-use check to read, start, adoption and settlement; do not change +`todo_done` into recursive artifact validation. Traverse only requester-scoped, +declared links, with per-read cycle detection, shared-source memoization and +measured depth/operation/time bounds. An unvisited tail is unavailable, never +assumed accepted. Cache no success across admissions. This does not provide an +atomic snapshot against arbitrary concurrent file writers. + +Qualify direct and transitive invalidation, a shared-source diamond, cycles, +source loss, unchanged erroneous content caught by a real declared validator, +and invalidation between start and settlement. Verify no-link parity, unchanged +historical records, bounded verifier cost and recovery without duplicate worker +dispatch. The packaged team/evidence view must show current unavailability and +its reason, allow a current recheck after authorized source/input repair and +read the result back. If repair requires new execution, use a separately admitted +task; rechecking an accepted operation must not redispatch its worker. +CLI/MCP/Chat share the same owner. Full Goal-wide reverse propagation, +all-session context correction and business rollback remain outside this slice. + ## 4. Authority matrix ### 4.1 What `GoalAmendmentAuthority` means @@ -586,6 +664,9 @@ the provider-neutral authority store contract. Replan classifies a discovered gap before choosing a writer: +- a failed check or invalid evidence within unchanged intent first follows its + existing task/acceptance/result-use repair or revalidation path; reading the + failure grants no new authority and need not amend the shared work graph; - a route correction wholly inside canonical intent opens or settles an Agent-scoped replan obligation; - a cross-lane dependency/work-graph gap opens a shared amendment obligation; @@ -600,6 +681,11 @@ Settlement requires either a committed receipt for that exact obligation, a rejected/no-change decision with a structured rationale accepted by policy, or a superseding obligation that explicitly preserves the causal chain. +For an evidence-caused obligation, retain the source/version and affected +criterion through repair and recheck. Settling a replan records an accepted +route decision; it does not itself clear the failed business criterion or an +unknown effect. Their owners require their own current recovery evidence. + After commit, an Agent whose `based_on_goal_revision` is stale may observe but cannot make controlled semantic writes until it rebases or receives an explicit grandfathered-work disposition. This connects shared change to existing diff --git a/docs/architecture/rfcs/shared-goal-alignment-and-governed-amendment-v0.zh-CN.md b/docs/architecture/rfcs/shared-goal-alignment-and-governed-amendment-v0.zh-CN.md index 75bc4f9f8a..bdf42a0ef5 100644 --- a/docs/architecture/rfcs/shared-goal-alignment-and-governed-amendment-v0.zh-CN.md +++ b/docs/architecture/rfcs/shared-goal-alignment-and-governed-amendment-v0.zh-CN.md @@ -4,7 +4,7 @@ - 替代 / 关闭:无 - 跟踪 Issue:[#3836](https://github.com/huangruiteng/loopx/issues/3836) - 日期:2026-09-02 -- 最后更新:2026-09-16 +- 最后更新:2026-10-08 - 范围:多个对等 Agent 围绕同一个共享 Goal 协作,同时保留 canonical intent、每个 Agent 的执行 frontier、claim/lease 所有权,以及可审计的 replan/amendment 决策 @@ -282,6 +282,64 @@ canonical acceptance 与当前 Todo 精确详情读取。普通产品 heartbeat R1/R4/R5 与 S11,本 RFC 不隐式开启新的 acceptance policy。下一完整切片应让既有 结构化 criterion 穿过任务切换和重启,在同一 owner 拒绝覆盖丢失并使过期证据失效。 +### 3.8 失效证据与受影响消费者 + +本节是既有 acceptance 与显式 result-use owner 的待实现资格合同,不新增全局错误 +状态、taint graph 或自动 amendment 政策。历史完成与当前证据使用资格是不同事实。 +保留原 receipt、声明依据与结果,重新检查当前适用性;不能靠改写已完成 Todo 让 +历史看起来一致。 + +来源不可用、版本/范围改变、owner 确认结论错误,含义不同。来源读不到只能说明 +当前证据不可得,不能说明内容为假。语义反驳须有当前 criterion 与可归属反证,由 +所属 validator 或获授权评审确认;字节一致和传输成功无法单独解决。可选评估遵循 +[检测衔接合同](optional-semantic-assistance-jev-v0.zh-CN.md#检测结果与所属规则的衔接)。 + +对合同要求当前证据的显式关系: + +1. 指明 source operation/artifact version、criterion 和实际声明的 consumer input, + 保留原因与影响范围。不能从消息送达、共同关键词或 workspace 全部文件推断消费。 +2. 在新的验收、adoption 或所属受保护执行边界之前重验依据。Consumer 输出不变且 + 本地 validator 通过,并不能独立证明声明来源链仍有效。决定须在实际准入边界绑定 + 观察到的版本,不能用较早的 UI 读取或缓存成功授权后续使用。无关工作继续, + 不因一个 source 缺失就停止全部 Agent。 +3. 通过现有 typed readback/guard 表达当前使用不可用。读取不修改历史、释放 lease、 + 撤回消息或启动修复。不能把任意来源失效塞进 `goal_acceptance_stale`:其现有 + owner 表达的是 acceptance/work binding 改变。 +4. 恢复时取得当前证据,恢复精确获准依据或经既有 owner 验证替代版本,再检查 + consumer eligibility。字节恢复只证明版本可得;已确认的语义失败还须重新验证 + 相关 criterion。模型说“修好了”、新 ACK 或新 evidence ID 均不足以解除。 + +发送者 context 记录此前推理。受影响工作恢复或交接时,既有 context owner 须带入 +失效依据、未解决问题、当前证据与下一项必要检查。这证明新的 context delivery, +不代表清除全部旧 session,也不证明模型理解了纠正。已经提交的外部 effect 继续 +服从自己的对账或显式授权补偿合同。 + +**实现边界,源码 `44931b6d22a50b949d43354e6ea498fb6b68d231`:** +[`Delegations._read_current`](../../../loopx/collaboration_mcp.py)重验 accepted +operation 自己的规则与输出;`read` 随后才附加 +[`result_relationships`](../../../loopx/control_plane/collaboration/delegation_results.py)。 +它可以保持 accepted,同时 incoming dependency 已 unavailable。`dependencies` +通过 `_read_current` 读取 source,因而不继续检查 source 自己的 incoming dependency。 +有界文件 I/O 诊断配合 synthetic local validation 复现了 source → A → B:A input +改变、output 不变,A 显示依赖不可用,B 的直接使用仍合格。该诊断不是 live worker +或 canonical store 测试。 + +最近的实现切片是:资格化**显式关联的本机委派结果的当前使用**,保留历史 accepted/ +done receipt。复用 [`delegation.ts`](../../../loopx/control_plane/collaboration/delegation.ts) +决定 typed eligibility,`delegation_results.py` 采集 host 观察。在 read、start、 +adoption 与 settlement 使用同一 current-use 检查;不把 `todo_done` 改成递归产物 +验证。只沿 requester 范围内的声明关系,采用单次读取的循环检测、共享来源缓存及 +经测量的深度/operation/时间界限。未访问的尾部保持 unavailable,不能假定 accepted; +不跨准入缓存成功。对任意并发文件 writer,不声称原子快照。 + +验收覆盖直接/传递失效、共享来源菱形、循环、来源丢失、真实声明 validator 发现 +字节不变的错误内容,以及 start 后 settlement 前失效。验证无关联输入行为等价、 +历史记录不变、verifier 成本有界、恢复不重复派发 worker。打包 team/evidence 视图 +须显示当前不可用及原因,在获授权修复来源/输入后支持当前复验并读回结果。 +修复若需要新的执行,使用另行准入的任务;复验 accepted operation 不得重新派发其 +worker。CLI/MCP/Chat 共用 owner。全 Goal 反向传播、全部 session context 纠正与 +业务回滚仍在该切片之外。 + ## 4. Authority matrix ### 4.1 `GoalAmendmentAuthority` 到底是什么 @@ -497,6 +555,8 @@ provider-neutral authority store contract 后面。 Replan 在选择 writer 前先分类发现的 gap: +- intent 不变时的检查失败或证据失效,先走既有 task/acceptance/result-use 修复或 + 重验路径;读取失败证据不授予新权限,也不一定需要修改共享工作图; - 完全位于 canonical intent 内的 route correction 打开或结算 Agent-scoped replan obligation; - cross-lane dependency/work-graph gap 打开 shared amendment obligation; @@ -509,6 +569,10 @@ Replan 在选择 writer 前先分类发现的 gap: 该精确 obligation 对应的 committed receipt;被 policy 接受的 reject/no-change 结构化 rationale;或显式保留因果链的 superseding obligation。 +证据导致的 obligation 在修复和复验中保留 source/version 与受影响 criterion。 +结算 replan 证明路径决策已接受,不能顺带解除失败的业务 criterion 或 unknown +effect;这些仍由各自 owner 要求当前恢复证据。 + Commit 后,`based_on_goal_revision` 已过期的 Agent 可以观察,但在 rebase 或取得 显式 grandfathered-work disposition 前,不能执行 controlled semantic write。 这样 shared change 就能连接现有 per-Agent Goal Vision,同时不会把一个 Agent 的 diff --git a/docs/development/control-plane-course/08-evidence-refresh-and-self-repair.md b/docs/development/control-plane-course/08-evidence-refresh-and-self-repair.md index d5ed8310b9..4538de8d05 100644 --- a/docs/development/control-plane-course/08-evidence-refresh-and-self-repair.md +++ b/docs/development/control-plane-course/08-evidence-refresh-and-self-repair.md @@ -122,6 +122,10 @@ Acceptance 证据应来自能直接证明结果的对象: - assistant 的完成声明; - 没有 acceptance evidence 的 `no_followup`。 +Checkpoint 证明的对象必须明确:来源与阶段一致性不等于业务结论正确, +续跑 journal 也不等于回滚 workspace。已有机制与剩余边界见 +[Agent 失败控制与恢复](../../architecture/agent-failure-containment-and-recovery.zh-CN.md)。 + 一个好的 evidence ref 足够紧凑,可以恢复判断,又不复制 raw log: ```text