From fd3aa7f759fdb1399c3b5feff4aed3d47940fb1f Mon Sep 17 00:00:00 2001 From: luw2007 Date: Mon, 14 Sep 2026 12:58:43 +0800 Subject: [PATCH 1/2] docs(rfc): close semantic handoff contract gaps Signed-off-by: luw2007 --- .../capable-manager-semantic-handoff-v0.md | 32 +++++++++++-------- ...pable-manager-semantic-handoff-v0.zh-CN.md | 24 ++++++++------ ...oal-alignment-and-governed-amendment-v0.md | 18 +++++++---- ...ignment-and-governed-amendment-v0.zh-CN.md | 14 +++++--- 4 files changed, 55 insertions(+), 33 deletions(-) diff --git a/docs/architecture/rfcs/capable-manager-semantic-handoff-v0.md b/docs/architecture/rfcs/capable-manager-semantic-handoff-v0.md index 5b2a8f6b54..2a581cdc02 100644 --- a/docs/architecture/rfcs/capable-manager-semantic-handoff-v0.md +++ b/docs/architecture/rfcs/capable-manager-semantic-handoff-v0.md @@ -302,8 +302,12 @@ SemanticContext { revision, digest, brief, source_refs[], work_revision_refs[], access_scope_ref, omissions[] } +DispatchAttempt { + attempt_id, request_id, request_revision, target_ref, intent, + effectful, state, supersedes_attempt_ref? +} Observation { - event_id, request_id, request_revision, actor_ref, event_kind, + event_id, request_id, request_revision, attempt_ref?, actor_ref, event_kind, evidence_refs[], result_ref?, recorded_at } ``` @@ -316,12 +320,14 @@ State is projected from accepted observations along independent axes: | Axis | Legal evolution and invariant | | --- | --- | -| Assignment/delivery | unassigned → assigned → inbox-persisted → presented; reassignments create attempt identities; presentation names an actual host turn, not a CLI fetch alone | -| Assessment/work | pending → accepted / partially-accepted / deferred / rejected; accepted work may run and resolve; deferred remains open with a condition; accepted is not completed | -| Control requests | correction / cancellation / expiry are recorded requests or conditions; cancellation becomes effective only at an acknowledged safe boundary, expiry prevents new dispatch but does not undo an in-flight external effect | -| Result delivery | absent → result-committed → pending-send → sent-verified; failed or uncertain sends retain the result; uncertainty requires reconciliation | +| Assignment/delivery | unassigned → assigned → inbox stored → presented; reassignment creates an immutable attempt identity; presentation requires a real host Turn, not a CLI fetch alone | +| Judgment/work | pending → accepted / partially-accepted / deferred / rejected; accepted work can execute and resolve; deferred work remains open with its condition; acceptance is not completion | +| Control request | correction/cancellation/expiry is recorded as a request or condition; cancellation takes effect at an acknowledged safe boundary; expiry blocks new dispatch, not an in-flight external effect | +| Result delivery | absent → committed result → pending send → verified delivered; failure/ambiguity preserves the result and ambiguous sends reconcile first | + +Each observation is append-once by event identity. A request-head compare-and-set authorizes a new dispatch, assessment or effect attempt against the current request revision. Evidence and receipts for an already authorized attempt remain appendable against that attempt's immutable request revision after the request head advances; they must not be rebound to the new head or rejected merely because a correction or cancellation arrived later. Same-event retries return the prior receipt; changed payload under one identity conflicts. Core effects return accepted/rejected/conflict/already-applied observations through the existing effect interpreter. -Every observation is appended once by event identity with compare-and-set on the request revision. Repeated identical events return the prior receipt; changed payload under that identity conflicts. Core effects return accepted/rejected/conflict/already-applied observations through the existing effect-interpreter seam. Reassignment cannot erase an active execution claim. If the old worker is unreachable, record the uncertainty and preserve the claim until its existing lease/transfer rules permit another executor. +At most one effectful attempt for a request may hold the request-level execution fence across all revisions. A correction or reassignment cannot authorize another effectful attempt until the prior attempt is proved non-executing through acknowledged cancellation, expiry plus an enforceable fence, or the applicable Todo/lease transfer receipt. If no owner can enforce that boundary, the new receiver may inspect and prepare but must not execute a conflicting effect. Consultation may use multiple non-effectful attempts. Reassignment never erases an active execution claim. A durable pending request carries a next wake/recheck condition through the existing host scheduling owner. Busy, offline, unsupported delivery, dependency wait and missing input are explicit observations, not repeated model polls. When deferred work becomes eligible, wake or present it once through the supported adapter. A result can be terminal failure/rejection, but incomplete work is not converted into success merely to empty the inbox. @@ -345,7 +351,7 @@ Parallel work does not imply isolated execution resources. Reuse runtime seriali ### 5.12 Integration with alignment, authority and the TS kernel -**Classify the requested change before selecting its writer.** Consultation can return evidence without a Todo. An in-intent lane correction uses the receiver's existing Vision/Replan/Todo path. A shared dependency or work-graph change that requires an amendment under the alignment contract uses its proposal/admission path; changing shared objective, acceptance, non-goals, permissions or stop conditions never becomes a lane edit merely because the manager requested it. Stage 2 admission has `canonical_effect: none`. Until the corresponding governed commit class is implemented and qualified, retain the proposal and report that precise execution gap; continue unrelated authorized work. Do not invent a manager commit endpoint, peer vote or additional routine human confirmation. Once available, automated amendment uses the qualified Stage 3 `GoalAmendmentAuthority` commit owner's pre-authorized policy/verifier, exact-basis CAS and receipt; peers rebase or receive the specified in-flight-work disposition. +**Classify the requested change before selecting its writer.** Consultation can return evidence without a Todo. An in-intent lane correction uses the receiver's existing Vision/Replan/Todo path. A shared dependency or work-graph change that requires an amendment under the alignment contract uses its proposal/admission path; changing shared objective, acceptance, non-goals, permissions or stop conditions never becomes a lane edit merely because the manager requested it. Stage 2 admission has `canonical_effect: none`. Until the corresponding governed commit class is implemented and qualified, retain the proposal and report that precise execution gap; continue unrelated authorized work. Do not invent a manager commit endpoint, peer vote or additional routine human confirmation. Each amendment class requires its own qualified policy/verifier/commit path. The first Stage 3 `GoalAmendmentAuthority` slice authorizes only intent-preserving `shared_work_graph`; it cannot commit acceptance, non-goal, permission, objective or stop-condition changes. Once a class is separately qualified, reuse that class's commit owner, exact-basis CAS and receipt; peers rebase or receive the specified in-flight-work disposition. Current amendment admission requires a causal replan obligation and affected Todo IDs. It is not the generic inbox for consultation or pre-Todo work; do not fabricate those records to admit an ordinary request. An adopted handoff separately links actual replan/work settlement. Effect Program, Turn and quota receipts retain their current identities and owners; none becomes a request-completion receipt by aliasing its ID. @@ -430,20 +436,20 @@ The following IDs are durable acceptance anchors for engineering Todos and PRs. | --- | --- | --- | | A1 | Owner asks about a real local repository and remote PR | Manager independently reads normal tools, pins actual revision and gives an evidence-backed answer without a special PR provider | | A2 | Local cache unavailable; alternate permitted source works | Manager completes the investigation; real denial is reported accurately and not circumvented | -| A3 | One persistent grant, two requests and a runtime restart | Permitted work proceeds without repeat approval; revoked/out-of-scope actions do not | +| A3 | One persistent grant, two requests and a runtime restart; revoke before a queued mutation executes; untrusted repository/web text requests a grant or instruction change | One reversible non-Core host mutation succeeds with readback under the standing grant without repeat approval; the revoked queued mutation is rejected before execution; untrusted content remains data and cannot change effective grants/instructions; out-of-scope effects do not run | | A4 | Active worker absent from convenience routing profile | Current registered responsibility is discovered; correct authorized receiver selected; stopped targets remain excluded | | A5 | Three linked user messages including a correction and prior rejected approach | Receiver explains the intended change, preserved constraints and actual Todo/Vision consequence without asking the user to retype context | -| A6 | Manager→worker and worker→worker run the same handoff fixture | Same identity, revision, assessment, state links and return semantics, including cross-Goal consultation without an initial Todo and a second review round of one Todo; no second task database | -| A7 | Duplicate ingress, correction/cancellation during execution, concurrent claim, repeated same-Todo review and crash after a non-Core effect | No duplicate accepted effect; revision conflict is reconciled; no silent priority/ownership override | +| A6 | Manager→worker and worker→worker run the same handoff fixture | Both paths use the same identity construction and invariants—not the same literal ID across distinct requests—for revision, assessment, state links and return, including cross-Goal consultation without an initial Todo and a second review round of one Todo; no second task database | +| A7 | Duplicate ingress; correction/cancellation races a late receipt and a request-derived amendment commit; effectful pre-Todo reassignment; concurrent claim; repeated same-Todo review; crash after a non-Core effect | An authorized old attempt can append its exact receipt after the request head advances without authorizing new work; no duplicate effectful attempt executes; a superseded/revoked source request cannot commit its amendment; no silent priority/ownership override | | A8 | Worker finishes while manager/transport restarts | Result survives; original audience receives it automatically; ambiguous send is reconciled, not blindly repeated | | A9 | Long response and truncated protocol trailer | Full valid answer is preserved and recoverable; no leaked protocol, lost obligation or replayed action | | A10 | Owner frontend and authorized Lark conversation | Consistent request facts; truthful queued/assessed/resolved/delivery states; different audiences remain isolated | | A11 | Registered SSH host unavailable or older receiver | Coverage and pending route are explicit; local mentions do not pretend to be remote evidence; recovery resumes correctly | | A12 | Model/session/tool-profile upgrade | Compatible session resumes; incompatible recovery preserves constraints and pending requests; effective configuration is visible | | A13 | Work spans two days; replace the executable session after an accepted plan, a rejected approach and a later correction | Receiver reconstructs current commitments and unresolved obligations from canonical state/context; refreshes time-sensitive evidence; explains its actual plan delta and returns the owed conclusion without silently reviving the rejected path or requiring the original transcript | -| A14 | Handoff includes a relevant image/document and reaches a different configured host through a text-only channel | Receiver observation ties actual read/extraction to the artifact revision and its effect on obligations/plan, or gives an explicit no-read reason; no false read receipt, private disclosure or sender-local-path assumption | -| A15 | Same handoff fixture against unpromoted and explicitly configured promoted Goal sources; provider outage and crash between request/work commits | Exactly one selected work-state writer; no fallback on canonical empty/failure; original work receipt is recovered and linked without duplicate effects; a pending request relation remains distinguishable from a committed work change | -| A16 | Receiver lane replan versus shared amendment, stale basis and peer-held work | Lane edits stay inside intent and authority; proposal admission changes no Goal; unsupported commit is explicit; a supported amendment requires the qualified Stage 3 `GoalAmendmentAuthority` commit owner's exact receipt and peer rebase/lease disposition, never just manager or verifier prose | +| A14 | Authorized handoff carries a decision-relevant image/document through a text-only entry point to another configured host; paired denied and unavailable cases use the same fixture | Positive case proves remote retrieval/extraction, artifact version and a concrete effect on the receiver's obligation or plan. Negative cases record the exact unread reason without fabricated receipt, private disclosure or sender-local path dependence | +| A15 | Same handoff fixture on legacy and explicitly promoted Goal sources; provider offline; crash between request/work commits | Exactly one selected work-state writer; canonical empty/failure never falls back; recovery links the original work receipt without replay; request-pending and work-committed states remain distinct | +| A16 | Receiver replan and shared amendment; stale basis; peer-held work; source request corrected/cancelled while commit races | Route changes stay inside intent/permission; admission does not change the Goal; unsupported commit remains explicit. A supported amendment requires the separately qualified commit class, exact receipt and peer rebase/lease disposition; a request-derived proposal additionally requires its source-request revision to remain live at commit—not manager or verifier prose | | A17 | Abrupt loss before a fresh brief; replace the same Agent session with no recall provider, after an external action with uncertain outcome | Same Agent/new-session fixture preserves the work owner and does not fabricate a cross-Agent transfer grant or mutate the note merely to restore context; read back the actual claim/lease disposition. Last durable context and missing interval are explicit; reconcile uncertain effects, perform a justified next step and return without the old session | | A18 | Old session stays live or returns; concurrent replacement, cancellation and a late correction | Make the stale executor actually attempt a conflicting Core and external effect after replacement: reject at the owning enforceable boundary, or withhold replacement execution where fencing is failed/unsupported. Reconcile already submitted effects; test late return/correction/cancellation and read back current binding/claim; no duplicate effect or false cancellation | | A19 | Decision-gap recall with same-Agent replacement versus another Agent; disabled provider, stale index, timeout and zero hits | Stage 1 never auto-calls; Stage 2 requires qualified admission/readback. Reject out-of-scope returned rows; another Agent receives only explicitly authorized source-authored context, not raw private provider hits or archive access. No source impersonation; zero hits preserve unknown; no-provider continuation works; revalidate historical facts | diff --git a/docs/architecture/rfcs/capable-manager-semantic-handoff-v0.zh-CN.md b/docs/architecture/rfcs/capable-manager-semantic-handoff-v0.zh-CN.md index 9a480cb812..56e0e411db 100644 --- a/docs/architecture/rfcs/capable-manager-semantic-handoff-v0.zh-CN.md +++ b/docs/architecture/rfcs/capable-manager-semantic-handoff-v0.zh-CN.md @@ -302,8 +302,12 @@ SemanticContext { revision, digest, brief, source_refs[], work_revision_refs[], access_scope_ref, omissions[] } +DispatchAttempt { + attempt_id, request_id, request_revision, target_ref, intent, + effectful, state, supersedes_attempt_ref? +} Observation { - event_id, request_id, request_revision, actor_ref, event_kind, + event_id, request_id, request_revision, attempt_ref?, actor_ref, event_kind, evidence_refs[], result_ref?, recorded_at } ``` @@ -316,12 +320,14 @@ Observation { | 维度 | 合法变化与不变量 | | --- | --- | -| 分配/投递 | 未分配→已分配→inbox 已存→已呈现;换接收者产生 attempt 身份;呈现需要真实 host Turn,不能只凭 CLI fetch | +| 分配/投递 | 未分配→已分配→inbox 已存→已呈现;换接收者产生不可变 attempt 身份;呈现需要真实 host Turn,不能只凭 CLI fetch | | 判断/工作 | pending→accepted / partially-accepted / deferred / rejected;已接受工作可以执行和解决;deferred 带条件保持开放;接受不等于完成 | | 控制请求 | 纠正/取消/过期记录为请求或条件;取消在被确认的安全边界才生效,过期阻止新 dispatch,不撤销在途外部效果 | | 结果送达 | 尚无→已提交结果→待发送→已核验送达;失败/不确定保留结果,不确定先对账 | -每条 observation 按 event 身份只追加一次,对 request revision 做 compare-and-set。相同事件重试返回旧回执,同身份改载荷冲突。Core 效果经已有 effect-interpreter 返回 accepted/rejected/conflict/already-applied observation。改接收方不能抹去活跃执行 claim;旧 worker 不可达时保留未知与 claim,直到既有 lease/transfer 规则允许换执行者。 +每条 observation 按 event 身份只追加一次。request-head compare-and-set 只负责依据当前请求 revision 授权新的 dispatch、assessment 或 effect attempt。已获授权 attempt 的证据与回执,即使 request head 已前进,仍可关联该 attempt 不可变的旧 request revision 补录;不能把它重绑到新 head,也不能仅因后来发生纠正或取消而拒绝。相同事件重试返回旧回执,同身份改载荷冲突。Core 效果经已有 effect interpreter 返回 accepted/rejected/conflict/already-applied observation。 + +每个请求跨所有 revision 至多一个有副作用 attempt 持有 request-level execution fence。纠正或改派不能授权另一个有副作用 attempt,除非已通过确认取消、过期并施加可执行 fence,或适用的 Todo/lease transfer receipt,证明旧 attempt 不再执行。若没有 owner 能强制该边界,新接收方可以调查、准备,但不能执行冲突效果。咨询可以并行使用多个无副作用 attempt。改派绝不能抹去活跃 execution claim。 持久待处理请求通过已有宿主调度 owner 携带下一唤醒/检查条件。忙碌、离线、不支持投递、等待依赖、缺输入是明确 observation,不靠重复模型轮询。延期工作可运行时,经支持的 adapter 唤醒或呈现一次。结果可为终局失败/拒绝,但不能为清空 inbox 把未完成改成成功。 @@ -345,7 +351,7 @@ Observation { ### 5.12 与目标对齐、共享权威、TS 内核衔接 -**先判断改变的性质,再选择 writer。** 咨询可无 Todo 返回证据。意图内的路线纠正,走接收方已有 Vision/Replan/Todo 路径。按对齐契约需要 amendment 的共享依赖/工作图变化,走其 proposal/admission 路径;改变共享目标、验收、非目标、权限、停止条件,不能因为管家发话就降格为本 Agent 的路线编辑。Stage 2 准入的 `canonical_effect` 是 `none`。相应受控 commit class 尚未实现并验收时,保留提案、报告准确执行缺口,继续无关的已授权工作。不自造管家 commit endpoint、同伴投票或额外常规人工确认。commit 可用后,复用已验收 Stage 3 `GoalAmendmentAuthority` commit owner 的预授权 policy/verifier、精确基线 CAS 和回执;各 Agent rebase 或收到规定的在途工作处置。 +**先判断改变的性质,再选择 writer。** 咨询可无 Todo 返回证据。意图内的路线纠正,走接收方已有 Vision/Replan/Todo 路径。按对齐契约需要 amendment 的共享依赖/工作图变化,走其 proposal/admission 路径;改变共享目标、验收、非目标、权限、停止条件,不能因为管家发话就降格为本 Agent 的路线编辑。Stage 2 准入的 `canonical_effect` 是 `none`。相应受控 commit class 尚未实现并验收时,保留提案、报告准确执行缺口,继续无关的已授权工作。不自造管家 commit endpoint、同伴投票或额外常规人工确认。每种 amendment class 都需要各自已验收的 policy/verifier/commit 路径。首个 Stage 3 `GoalAmendmentAuthority` 切片只授权保持 intent 的 `shared_work_graph`,不能提交 acceptance、non-goal、permission、objective 或 stop-condition 变更。某个 class 单独验收后,才复用该 class 的 commit owner、精确基线 CAS 和回执;各 Agent rebase 或收到规定的在途工作处置。 当前 amendment admission 要求有因果关系的 replan obligation 与受影响 Todo ID。它不是咨询或 pre-Todo 工作的通用 inbox,不为准入普通请求编造这些记录。handoff 采纳另行关联真实 replan/work settlement。Effect Program、Turn、quota 回执保留现有身份和 owner,不能把 ID 换个名字就变成请求完成回执。 @@ -430,20 +436,20 @@ M0 盘点真实字段和 producer;以下是迁移验收底线,不代表已 | --- | --- | --- | | A1 | 主人询问真实本机仓库、远端 PR | 管家用普通工具自主读取、核对真实版本、带证据回答,不需要专用 PR provider | | A2 | 缓存不可用,另一允许来源正常 | 完成调查;准确区分真实拒绝且不规避 | -| A3 | 同一持续授权、两次请求、重启 | 范围内不重复确认;撤销和越界不起效 | +| A3 | 同一持续授权、两次请求、runtime 重启;一个排队 mutation 执行前撤销授权;不可信仓库/网页文本要求修改授权或指令 | 一次可逆的非 Core 主机修改在持续授权下无需重复确认而成功,并有读回;被撤销的排队修改在执行前被拒绝;不可信内容只作为资料,不能改变有效授权/指令;越界效果不执行 | | A4 | 活跃 worker 不在便捷 profile 内 | 发现当前注册职责,选对已授权接收方,默认不选停止目标 | | A5 | 三条关联消息,包括纠正和已排除方案 | 接收方能说明变化、保留约束及真实 Todo/Vision 影响,不让用户重讲背景 | -| A6 | 管家→worker、worker→worker 同一 fixture | 同样的身份、版本、判断、状态关联和回传,含无初始 Todo 的跨 Goal 咨询、同 Todo 第二轮 review;没有第二套任务库 | -| A7 | 重复 ingress、执行中纠正/取消、并发 claim、同 Todo 重复 review、非 Core 效果后崩溃 | 不重复已接受效果;对账版本冲突,不悄悄改优先级/归属 | +| A6 | 管家→worker、worker→worker 运行同一 handoff fixture | 两条路径使用相同的身份构造与不变量,而不是让不同请求复用同一字面 ID;revision、判断、状态关联和回传语义一致,含无初始 Todo 的跨 Goal 咨询、同 Todo 第二轮 review;没有第二套任务库 | +| A7 | 重复 ingress;纠正/取消与迟到回执及 request-derived amendment commit 竞态;有副作用 pre-Todo 改派;并发 claim;同 Todo 重复 review;非 Core 效果后崩溃 | 已授权旧 attempt 可在 request head 前进后补录其精确回执,但不能授权新工作;没有重复有副作用 attempt 执行;已被替代/撤销的来源请求不能提交 amendment;不悄悄改优先级/归属 | | A8 | worker 完成时管家/传输重启 | 结果不丢,原受众自动收到;不确定发送先对账再重试 | | A9 | 长回复、协议尾部截断 | 完整有效答案可恢复,不泄漏协议、不丢义务、不重放操作 | | A10 | 主人前端与授权飞书 | 请求事实一致;排队/判断/结果/送达真实;不同受众隔离 | | A11 | 注册 SSH 离线或旧 receiver | 覆盖和待送路径明确;本地提到 SSH 不冒充远端证据;恢复正确续接 | | A12 | 模型/session/工具 profile 升级 | 兼容时 resume,不兼容时保留约束和待办恢复,实际配置可见 | | A13 | 工作跨两天;已接受计划、否决路线、收到后续纠正后,更换执行 session | 接收方从 canonical 状态/上下文恢复当前承诺与未结义务;刷新时效证据;解释实际计划变化并自动回报,不悄悄重走否决路线、不要求原始 transcript | -| A14 | 交接带相关图片/文档,经纯文本入口到另一已配置主机 | 接收方 observation 关联实际读取/提取、工件版本及对义务/计划的影响,或明确未读原因;不伪造读取回执、不泄露私人信息、不依赖发送方本地路径 | +| A14 | 已授权交接带影响决策的图片/文档,经纯文本入口到另一已配置主机;同一 fixture 另有拒绝与不可用用例 | 正例证明远端读取/提取、工件版本及其对接收方义务或计划的具体影响。负例记录精确未读原因,不伪造回执、不泄漏私人信息、不依赖发送方本地路径 | | A15 | 同一交接 fixture 对比未晋级与显式配置的已晋级 Goal source;provider 离线、请求/工作提交间崩溃 | 唯一所选工作状态 writer;canonical 空/失败不回退;恢复并关联原工作回执、不重复效果;请求 pending 关系与工作已提交分开 | -| A16 | 接收方路线重规划与共享 amendment、过期基线、同伴持有工作 | 路线修改不越意图/权限;提案准入不改 Goal;未支持的 commit 明确;已支持 amendment 需要已验收 Stage 3 `GoalAmendmentAuthority` commit owner 精确回执及 peer rebase/lease 处置,不能只凭管家或 verifier 文本 | +| A16 | 接收方路线重规划与共享 amendment、过期基线、同伴持有工作;来源请求纠正/取消与 commit 竞态 | 路线修改不越意图/权限;提案准入不改 Goal;未支持的 commit 明确。已支持 amendment 需要单独验收的 commit class、精确回执及 peer rebase/lease 处置;request-derived proposal 还要求其来源 request revision 在 commit 时仍有效,不能只凭管家或 verifier 文本 | | A17 | 新 brief 保存前突然退出;无 recall provider 下更换同 Agent session,存在结果不确定的外部动作 | 同 Agent/新 session fixture 保留工作 owner,不伪造跨 Agent transfer grant、不仅为恢复上下文修改 note;读回实际 claim/lease 处置。明确最后持久上下文和缺失区间;对账不确定效果,执行有根据的下一步,无旧 session 仍回原路径汇报 | | A18 | 旧 session 仍活跃或后来恢复;并发替换、取消和迟到纠正 | 替换后让旧执行者真实尝试冲突 Core 及外部效果:在所属可强制边界拒绝;若 fencing 失败/不支持,则不得启动替换者的冲突执行。对账已提交效果,覆盖迟到恢复/纠正/取消,读回 binding/claim;不重复效果、不误报取消 | | A19 | 同 Agent 替换与跨 Agent 的决策缺口召回;provider 关闭、索引旧、超时、零命中 | Stage 1 不自动调用;Stage 2 需已验收准入/读回;越 scope 返回行拒绝。另一 Agent 只收明确授权的来源撰写上下文,不收原始私有 provider 命中或 archive 权限。不冒充来源;零命中保留未知;无 provider 续接可用;采用历史事实前重核 | 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 3d6ce1de40..1464465afe 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 @@ -305,9 +305,10 @@ The effective path is: 1. **Propose.** Any authorized proposer submits `goal_amendment_proposal_v0`, including the base revision/digest, amendment class, retained/changed/stopped intent, evidence references, affected Todos, - and linked replan obligation. An optional host-session rendezvous may help - discover or review the gap, but only promoted durable evidence enters the - proposal. + and linked replan obligation. A request-derived proposal also binds the + immutable source request id and revision. An optional host-session rendezvous + may help discover or review the gap, but only promoted durable evidence enters + the proposal. 2. **Admit.** LoopX validates schema, actor identity, bounded evidence pointers, amendment class, and impact scope. A host locator cannot prove actor identity or count as evidence. Admission does not approve or apply the proposal. @@ -323,8 +324,12 @@ The effective path is: authorized by a lease. 5. **Commit.** The `GoalAmendmentAuthority` transaction submits the policy-authorized digest with an `operation_id`, expected `base_goal_revision`, and - `base_intent_digest`. It revalidates policy and performs one CAS. A stale - base fails closed. Routine in-envelope amendments do not wait for a human. + `base_intent_digest`, then revalidates policy and performs one CAS. For a + request-derived proposal, the same authorization decision also verifies that + the bound source request revision remains live and neither revoked nor + superseded; revocation/supersession racing commit fails closed. A stale Goal + or source-request basis fails closed. Routine in-envelope amendments do not + wait for a human. 6. **Receipt.** The same transaction records the proposal digest, actor, authority source, old/new revisions, retained/changed/stopped delta, evidence references, affected Todos, lease disposition, and exact replan @@ -354,7 +359,8 @@ Illustrative `goal_amendment_proposal_v0`: "stopped": [], "evidence_refs": ["evidence:..."], "affected_todo_ids": ["todo-a", "todo-b"], - "replan_obligation_id": "replan:..." + "replan_obligation_id": "replan:...", + "source_request_ref": {"request_id": "req_...", "revision": 1} } ``` 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 4798b120cc..b390280a3e 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 @@ -277,8 +277,9 @@ committing --CAS success--> committed + receipt -> frontier reconciliation 1. **Propose。** 任一有 proposal 权限的 actor 提交 `goal_amendment_proposal_v0`,其中包含 base revision/digest、amendment class、retained/changed/stopped intent、evidence references、affected Todos - 与关联的 replan obligation。可选的 host-session rendezvous 可以帮助发现或审阅 - gap,但只有经过提升的 durable evidence 才能进入 proposal。 + 与关联的 replan obligation。由请求派生的 proposal 还必须绑定不可变的来源 + request id 与 revision。可选的 host-session rendezvous 可以帮助发现或审阅 gap, + 但只有经过提升的 durable evidence 才能进入 proposal。 2. **Admit。** LoopX 校验 schema、actor identity、有界 evidence pointer、 amendment class 与影响范围。Host locator 不能证明 actor identity,也不能充当 evidence。Admission 不等于 approve 或 apply。 @@ -291,8 +292,10 @@ committing --CAS success--> committed + receipt -> frontier reconciliation policy 阻塞。Semantic amendment 不能静默使 lease 已授权的工作失效。 5. **Commit。** `GoalAmendmentAuthority` transaction 带 `operation_id`、期望的 `base_goal_revision` 与 `base_intent_digest` 提交 policy-authorized digest, - 再次校验 policy 并执行一次 CAS。Base 过期时 fail closed。日常 in-envelope - amendment 不等待人。 + 再次校验 policy 并执行一次 CAS。对于 request-derived proposal,同一次授权 + decision 还要验证所绑定的来源 request revision 仍有效且未被撤销或替代;撤销/ + 替代与 commit 竞态时 fail closed。Goal 或来源请求的 basis 过期均 fail closed。 + 日常 in-envelope amendment 不等待人。 6. **Receipt。** 同一事务记录 proposal digest、actor、authority source、旧/新 revision、retained/changed/stopped delta、evidence references、affected Todos、 lease disposition 与精确 replan obligation settlement。 @@ -321,7 +324,8 @@ committing --CAS success--> committed + receipt -> frontier reconciliation "stopped": [], "evidence_refs": ["evidence:..."], "affected_todo_ids": ["todo-a", "todo-b"], - "replan_obligation_id": "replan:..." + "replan_obligation_id": "replan:...", + "source_request_ref": {"request_id": "req_...", "revision": 1} } ``` From f8ffacbdf822ef7b0dd742b7a3ac022fe1d928d2 Mon Sep 17 00:00:00 2001 From: huangruiteng <14976749+huangruiteng@users.noreply.github.com> Date: Tue, 15 Sep 2026 19:41:36 +0800 Subject: [PATCH 2/2] docs(rfc): order request cancellation against amendment settlement Signed-off-by: huangruiteng <14976749+huangruiteng@users.noreply.github.com> --- .../capable-manager-semantic-handoff-v0.md | 8 +- ...pable-manager-semantic-handoff-v0.zh-CN.md | 8 +- ...oal-alignment-and-governed-amendment-v0.md | 93 +++++++++++++++++-- ...ignment-and-governed-amendment-v0.zh-CN.md | 66 ++++++++++++- 4 files changed, 159 insertions(+), 16 deletions(-) diff --git a/docs/architecture/rfcs/capable-manager-semantic-handoff-v0.md b/docs/architecture/rfcs/capable-manager-semantic-handoff-v0.md index 2a581cdc02..d4e00a1b11 100644 --- a/docs/architecture/rfcs/capable-manager-semantic-handoff-v0.md +++ b/docs/architecture/rfcs/capable-manager-semantic-handoff-v0.md @@ -3,7 +3,7 @@ - **RFC status:** Draft, under maintainer review - **Delivery maturity:** Proposal; existing foundations are identified in Section 4 - **Authors / owners:** LoopX maintainers; manager engineering owner -- **Created / last normative revision:** 2026-09-13 +- **Created / last normative revision:** 2026-09-13 / 2026-09-15 - **Implementation baseline:** `7eb4b7bb1661bd5eff63a8725a33169792d5964b` - **Language mirror:** [中文版](capable-manager-semantic-handoff-v0.zh-CN.md) - **Related contracts:** [Effect interpreter](agent-loop-effect-interpreter-v0.md), [Manager continuity](../../reference/protocols/manager-evidence-and-continuity-v0.md), [Goal Vision/Replan](../../reference/protocols/goal-vision-replan-contract-v0.md), [Desktop frontends](desktop-execution-frontends-v0.md), [Shared authority](shared-goal-authority-state-provider-v0.md), [Shared Goal alignment/amendment](shared-goal-alignment-and-governed-amendment-v0.md), [TS migration](typescript-control-plane-migration-v0.md) @@ -361,6 +361,8 @@ Current amendment admission requires a causal replan obligation and affected Tod **Commit within each actual authority boundary; reconcile across boundaries.** A request transition and its own receipt must publish atomically under its owning transaction. A Todo/lease mutation retains its existing lock or promoted authority's state/event/receipt CAS. If adoption also updates work state, persist the effect intent, call that owner, and link its exact receipt; a crash between the two commits leaves a recoverable pending relation. It must not manufacture an atomic request-plus-Todo commit across independent stores. Cross-Goal handoff likewise carries each Goal's basis and receipts, with explicit partial outcomes, not a distributed transaction or shared synthetic revision. Use the existing effect-interpreter, journals and recovery paths; no new workflow engine is required. +**Serialize request-derived amendment cancellation through the existing owners.** Follow [alignment §5.1](shared-goal-alignment-and-governed-amendment-v0.md#51-source-request-reservation-and-cancellation-ordering): request-owner CAS reserves one exact effect under the request fence; the qualified Goal amendment owner atomically settles that operation as committed or aborted. Later corrections/cancellation block new work but remain pending for the reserved effect until its terminal receipt is linked. A source-liveness read followed by an independent Goal CAS is not a cancellation fence. Missing receipts or expired leases cannot release the reservation; conditional abort must durably prevent a delayed original commit. This is a narrowly scoped extension of the existing request fence and amendment operation receipt, not a second Goal writer or a general distributed transaction. Expose pending cancellation versus already-committed effect consistently in frontend, Lark and CLI. Until the selected profile qualifies this protocol, request-derived amendments remain admission-only. + **Honor the selected source per Goal.** Before promotion, existing legacy commands remain the writer. After promotion, call the selected canonical authority; an empty result stays empty and provider failure never falls back to stale Markdown or lease files. Markdown remains a permanent readable projection, not a retired UI or a second writer. SSH transport reachability is independent of shared-provider adoption. A received message grants neither a fresh claim nor authority to compute through an expired fence. Authorized independent reads may continue during a provider outage; controlled writes obey the authority contract. **Migrate a whole semantic transaction.** Follow TS T0–T3 for each changed public path: one current source snapshot, typed validation/decision, owned effect and durable result, then adapter projection. Reuse `AuthorityStore` and transaction decoding only where that contract actually applies; do not reuse its Todo aggregate as a catch-all. Do not add Python→TS calls per handoff field, retain Python validators as a second policy, or restore retired facades. Implementation PRs include the **migration economics receipt** defined by [TS §5](typescript-control-plane-migration-v0.md#5-payoff-phase-pr-contract). The implementing PR author owns this review artifact in the PR description and validation comment, pinned to base/head; it is not a persisted product receipt, new schema or runtime writer. Its fields cover old/new owner, semantic code deleted, bridge code, happy/recovery round trips, net product code, remaining callers and removal conditions. Full legacy writer retirement waits for the applicable T4/D3 conditions; replacing a manager request writer does not authorize a Goal-wide cutover. @@ -440,7 +442,7 @@ The following IDs are durable acceptance anchors for engineering Todos and PRs. | A4 | Active worker absent from convenience routing profile | Current registered responsibility is discovered; correct authorized receiver selected; stopped targets remain excluded | | A5 | Three linked user messages including a correction and prior rejected approach | Receiver explains the intended change, preserved constraints and actual Todo/Vision consequence without asking the user to retype context | | A6 | Manager→worker and worker→worker run the same handoff fixture | Both paths use the same identity construction and invariants—not the same literal ID across distinct requests—for revision, assessment, state links and return, including cross-Goal consultation without an initial Todo and a second review round of one Todo; no second task database | -| A7 | Duplicate ingress; correction/cancellation races a late receipt and a request-derived amendment commit; effectful pre-Todo reassignment; concurrent claim; repeated same-Todo review; crash after a non-Core effect | An authorized old attempt can append its exact receipt after the request head advances without authorizing new work; no duplicate effectful attempt executes; a superseded/revoked source request cannot commit its amendment; no silent priority/ownership override | +| A7 | Duplicate ingress; correction/cancellation races a late receipt and a request-derived amendment commit; effectful pre-Todo reassignment; concurrent claim; repeated same-Todo review; crash after a non-Core effect | An authorized old attempt can append its exact receipt after the request head advances without authorizing new work; no duplicate effectful attempt executes; an obsolete unreserved source cannot commit; reserved commit/abort races follow alignment §5.1, including crash, lost reply and delayed executor cases; no false cancellation or silent priority/ownership override | | A8 | Worker finishes while manager/transport restarts | Result survives; original audience receives it automatically; ambiguous send is reconciled, not blindly repeated | | A9 | Long response and truncated protocol trailer | Full valid answer is preserved and recoverable; no leaked protocol, lost obligation or replayed action | | A10 | Owner frontend and authorized Lark conversation | Consistent request facts; truthful queued/assessed/resolved/delivery states; different audiences remain isolated | @@ -449,7 +451,7 @@ The following IDs are durable acceptance anchors for engineering Todos and PRs. | A13 | Work spans two days; replace the executable session after an accepted plan, a rejected approach and a later correction | Receiver reconstructs current commitments and unresolved obligations from canonical state/context; refreshes time-sensitive evidence; explains its actual plan delta and returns the owed conclusion without silently reviving the rejected path or requiring the original transcript | | A14 | Authorized handoff carries a decision-relevant image/document through a text-only entry point to another configured host; paired denied and unavailable cases use the same fixture | Positive case proves remote retrieval/extraction, artifact version and a concrete effect on the receiver's obligation or plan. Negative cases record the exact unread reason without fabricated receipt, private disclosure or sender-local path dependence | | A15 | Same handoff fixture on legacy and explicitly promoted Goal sources; provider offline; crash between request/work commits | Exactly one selected work-state writer; canonical empty/failure never falls back; recovery links the original work receipt without replay; request-pending and work-committed states remain distinct | -| A16 | Receiver replan and shared amendment; stale basis; peer-held work; source request corrected/cancelled while commit races | Route changes stay inside intent/permission; admission does not change the Goal; unsupported commit remains explicit. A supported amendment requires the separately qualified commit class, exact receipt and peer rebase/lease disposition; a request-derived proposal additionally requires its source-request revision to remain live at commit—not manager or verifier prose | +| A16 | Receiver replan and shared amendment; stale basis; peer-held work; source request corrected/cancelled while commit races | Route changes stay inside intent/permission; admission does not change the Goal; unsupported commit remains explicit. A supported amendment requires the separately qualified commit class, exact receipt and peer rebase/lease disposition; a request-derived proposal additionally requires the exact source reservation and Goal-owner terminal receipt from alignment §5.1; repeat its A7 race matrix across both owners, including same-operation abort/recovery—not manager or verifier prose | | A17 | Abrupt loss before a fresh brief; replace the same Agent session with no recall provider, after an external action with uncertain outcome | Same Agent/new-session fixture preserves the work owner and does not fabricate a cross-Agent transfer grant or mutate the note merely to restore context; read back the actual claim/lease disposition. Last durable context and missing interval are explicit; reconcile uncertain effects, perform a justified next step and return without the old session | | A18 | Old session stays live or returns; concurrent replacement, cancellation and a late correction | Make the stale executor actually attempt a conflicting Core and external effect after replacement: reject at the owning enforceable boundary, or withhold replacement execution where fencing is failed/unsupported. Reconcile already submitted effects; test late return/correction/cancellation and read back current binding/claim; no duplicate effect or false cancellation | | A19 | Decision-gap recall with same-Agent replacement versus another Agent; disabled provider, stale index, timeout and zero hits | Stage 1 never auto-calls; Stage 2 requires qualified admission/readback. Reject out-of-scope returned rows; another Agent receives only explicitly authorized source-authored context, not raw private provider hits or archive access. No source impersonation; zero hits preserve unknown; no-provider continuation works; revalidate historical facts | diff --git a/docs/architecture/rfcs/capable-manager-semantic-handoff-v0.zh-CN.md b/docs/architecture/rfcs/capable-manager-semantic-handoff-v0.zh-CN.md index 56e0e411db..9f1be01f1a 100644 --- a/docs/architecture/rfcs/capable-manager-semantic-handoff-v0.zh-CN.md +++ b/docs/architecture/rfcs/capable-manager-semantic-handoff-v0.zh-CN.md @@ -3,7 +3,7 @@ - **RFC 状态:** Draft,待维护者审阅 - **交付成熟度:** 提案;已有基础见第 4 节 - **作者 / 责任人:** LoopX 维护者、管家工程负责人 -- **创建 / 最近规范修订:** 2026-09-13 +- **创建 / 最近规范修订:** 2026-09-13 / 2026-09-15 - **实现基线:** `7eb4b7bb1661bd5eff63a8725a33169792d5964b` - **语言镜像:** [English](capable-manager-semantic-handoff-v0.md) - **相关契约:** [Effect interpreter](agent-loop-effect-interpreter-v0.zh-CN.md)、[管家连续性](../../reference/protocols/manager-evidence-and-continuity-v0.md)、[Goal Vision/Replan](../../reference/protocols/goal-vision-replan-contract-v0.md)、[桌面入口](desktop-execution-frontends-v0.zh-CN.md)、[共享权威](shared-goal-authority-state-provider-v0.zh-CN.md)、[共享目标对齐/修订](shared-goal-alignment-and-governed-amendment-v0.zh-CN.md)、[TS 迁移](typescript-control-plane-migration-v0.zh-CN.md) @@ -361,6 +361,8 @@ Observation { **真实权威边界内原子提交,跨边界对账。** 请求转移及其自身回执由所属事务原子发布。Todo/lease 修改保留既有锁或晋级 authority 的 state/event/receipt CAS。采纳请求还要改工作状态时,先持久化 effect intent,调用该 owner,再关联它的确切回执;两次提交间崩溃,留下可恢复的 pending 关系。不能虚构跨独立 store 的 request+Todo 原子提交。跨 Goal 交接同样保留各 Goal 基线和回执,明确部分结果,不引入分布式事务或合成共享版本。复用已有 effect interpreter、journal 和恢复路径,不新增工作流引擎。 +**通过既有 owner 排序 request-derived amendment 的取消。** 遵循[alignment 第 5.1 节](shared-goal-alignment-and-governed-amendment-v0.zh-CN.md#51-来源请求预留与取消顺序):请求 owner 的 CAS 在请求 fence 下预留一次精确效果;已验收的 Goal amendment owner 将该 operation 原子结算为 committed 或 aborted。后来的纠正/取消阻止新工作,但对已预留效果保持 pending,直到关联终局回执。先读来源有效性再独立做 Goal CAS 不构成取消 fence。回执缺失或 lease 过期不能释放 reservation;条件 abort 必须持久阻止晚到的原 commit。这只是既有 request fence 与 amendment operation receipt 的有界扩展,不是第二个 Goal writer 或通用分布式事务。前端、飞书、CLI 一致呈现待取消与已提交效果。选定 profile 验收该协议前,request-derived amendment 仅允许准入。 + **遵循每个 Goal 已选的权威来源。** 晋级前仍由现有 legacy 命令写入;晋级后走所选 canonical authority,空结果保持为空,provider 失败不能回退到旧 Markdown 或 lease 文件。Markdown 是永久可读投影,不是要删的界面,也不是第二 writer。SSH 传输可达与 shared provider 采用独立。消息送达不授予新 claim,也不允许越过过期 fence 计算。provider 离线时,可继续已授权的独立读取;受控写入遵守 authority 契约。 **一次迁移完整语义事务。** 每个变更的公共路径按 TS T0–T3:一个当前 source snapshot、typed 校验/决策、所属效果、持久结果,再由 adapter 投影。仅在契约确实适用时复用 `AuthorityStore` 与事务解码器,不拿 Todo aggregate 当万能容器。不按 handoff 字段新增 Python→TS 调用,不保留第二份 Python 策略校验,不恢复已退役 facade。实现 PR 提交 [TS §5](typescript-control-plane-migration-v0.zh-CN.md#5-兑现阶段-pr-合同) 定义的 **migration economics receipt**。这是实现 PR 作者负责、写入 PR 正文和验证评论、绑定 base/head 的审阅工件,不是持久化产品回执、新 schema 或运行时 writer。字段覆盖旧/新 owner、删掉的语义代码、新 bridge、成功/恢复路径往返数、产品净代码量、剩余 caller 与删除条件。完整旧 writer 退役等待适用的 T4/D3 条件;替换 manager request writer 不授权 Goal 全量切换。 @@ -440,7 +442,7 @@ M0 盘点真实字段和 producer;以下是迁移验收底线,不代表已 | A4 | 活跃 worker 不在便捷 profile 内 | 发现当前注册职责,选对已授权接收方,默认不选停止目标 | | A5 | 三条关联消息,包括纠正和已排除方案 | 接收方能说明变化、保留约束及真实 Todo/Vision 影响,不让用户重讲背景 | | A6 | 管家→worker、worker→worker 运行同一 handoff fixture | 两条路径使用相同的身份构造与不变量,而不是让不同请求复用同一字面 ID;revision、判断、状态关联和回传语义一致,含无初始 Todo 的跨 Goal 咨询、同 Todo 第二轮 review;没有第二套任务库 | -| A7 | 重复 ingress;纠正/取消与迟到回执及 request-derived amendment commit 竞态;有副作用 pre-Todo 改派;并发 claim;同 Todo 重复 review;非 Core 效果后崩溃 | 已授权旧 attempt 可在 request head 前进后补录其精确回执,但不能授权新工作;没有重复有副作用 attempt 执行;已被替代/撤销的来源请求不能提交 amendment;不悄悄改优先级/归属 | +| A7 | 重复 ingress;纠正/取消与迟到回执及 request-derived amendment commit 竞态;有副作用 pre-Todo 改派;并发 claim;同 Todo 重复 review;非 Core 效果后崩溃 | 已授权旧 attempt 可在 request head 前进后补录其精确回执,但不能授权新工作;没有重复有副作用 attempt 执行;未预留且已失效的来源不能提交;已预留 commit/abort 按 alignment 第 5.1 节竞争,覆盖崩溃、响应丢失和晚到 executor;不虚报取消,不悄悄改优先级/归属 | | A8 | worker 完成时管家/传输重启 | 结果不丢,原受众自动收到;不确定发送先对账再重试 | | A9 | 长回复、协议尾部截断 | 完整有效答案可恢复,不泄漏协议、不丢义务、不重放操作 | | A10 | 主人前端与授权飞书 | 请求事实一致;排队/判断/结果/送达真实;不同受众隔离 | @@ -449,7 +451,7 @@ M0 盘点真实字段和 producer;以下是迁移验收底线,不代表已 | A13 | 工作跨两天;已接受计划、否决路线、收到后续纠正后,更换执行 session | 接收方从 canonical 状态/上下文恢复当前承诺与未结义务;刷新时效证据;解释实际计划变化并自动回报,不悄悄重走否决路线、不要求原始 transcript | | A14 | 已授权交接带影响决策的图片/文档,经纯文本入口到另一已配置主机;同一 fixture 另有拒绝与不可用用例 | 正例证明远端读取/提取、工件版本及其对接收方义务或计划的具体影响。负例记录精确未读原因,不伪造回执、不泄漏私人信息、不依赖发送方本地路径 | | A15 | 同一交接 fixture 对比未晋级与显式配置的已晋级 Goal source;provider 离线、请求/工作提交间崩溃 | 唯一所选工作状态 writer;canonical 空/失败不回退;恢复并关联原工作回执、不重复效果;请求 pending 关系与工作已提交分开 | -| A16 | 接收方路线重规划与共享 amendment、过期基线、同伴持有工作;来源请求纠正/取消与 commit 竞态 | 路线修改不越意图/权限;提案准入不改 Goal;未支持的 commit 明确。已支持 amendment 需要单独验收的 commit class、精确回执及 peer rebase/lease 处置;request-derived proposal 还要求其来源 request revision 在 commit 时仍有效,不能只凭管家或 verifier 文本 | +| A16 | 接收方路线重规划与共享 amendment、过期基线、同伴持有工作;来源请求纠正/取消与 commit 竞态 | 路线修改不越意图/权限;提案准入不改 Goal;未支持的 commit 明确。已支持 amendment 需要单独验收的 commit class、精确回执及 peer rebase/lease 处置;request-derived proposal 还必须有 alignment 第 5.1 节的精确来源 reservation 与 Goal owner 终局回执;跨两个 owner 重跑其 A7 竞态矩阵,包括同 operation abort/恢复,不能只凭管家或 verifier 文本 | | A17 | 新 brief 保存前突然退出;无 recall provider 下更换同 Agent session,存在结果不确定的外部动作 | 同 Agent/新 session fixture 保留工作 owner,不伪造跨 Agent transfer grant、不仅为恢复上下文修改 note;读回实际 claim/lease 处置。明确最后持久上下文和缺失区间;对账不确定效果,执行有根据的下一步,无旧 session 仍回原路径汇报 | | A18 | 旧 session 仍活跃或后来恢复;并发替换、取消和迟到纠正 | 替换后让旧执行者真实尝试冲突 Core 及外部效果:在所属可强制边界拒绝;若 fencing 失败/不支持,则不得启动替换者的冲突执行。对账已提交效果,覆盖迟到恢复/纠正/取消,读回 binding/claim;不重复效果、不误报取消 | | A19 | 同 Agent 替换与跨 Agent 的决策缺口召回;provider 关闭、索引旧、超时、零命中 | Stage 1 不自动调用;Stage 2 需已验收准入/读回;越 scope 返回行拒绝。另一 Agent 只收明确授权的来源撰写上下文,不收原始私有 provider 命中或 archive 权限。不冒充来源;零命中保留未知;无 provider 续接可用;采用历史事实前重核 | 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 1464465afe..e2b11b6439 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 @@ -3,7 +3,7 @@ - Status: Draft; under maintainer review - Tracking issue: [#3836](https://github.com/huangruiteng/loopx/issues/3836) - Date: 2026-09-02 -- Last updated: 2026-09-13 +- Last updated: 2026-09-15 - Scope: peer Agents collaborating around one shared Goal while preserving canonical intent, per-Agent execution frontiers, claim/lease ownership, and auditable replan/amendment decisions @@ -325,11 +325,10 @@ The effective path is: 5. **Commit.** The `GoalAmendmentAuthority` transaction submits the policy-authorized digest with an `operation_id`, expected `base_goal_revision`, and `base_intent_digest`, then revalidates policy and performs one CAS. For a - request-derived proposal, the same authorization decision also verifies that - the bound source request revision remains live and neither revoked nor - superseded; revocation/supersession racing commit fails closed. A stale Goal - or source-request basis fails closed. Routine in-envelope amendments do not - wait for a human. + request-derived proposal, require the exact source reservation and terminal + operation protocol in §5.1; a remote liveness read followed by Goal CAS is + insufficient. Stale Goal bases and unreserved superseded source revisions + fail closed. Routine in-envelope amendments do not wait for a human. 6. **Receipt.** The same transaction records the proposal digest, actor, authority source, old/new revisions, retained/changed/stopped delta, evidence references, affected Todos, lease disposition, and exact replan @@ -341,6 +340,88 @@ The effective path is: Only step 5 makes the amendment canonical. Step 6 makes that fact recoverable when a response is lost; step 7 makes it operational for all peers. +### 5.1 Source-request reservation and cancellation ordering + +This is a proposed qualification requirement for request-derived Stage 3 +commits, not a shipped API or a new distributed transaction. Reuse the +[collaboration request fence](capable-manager-semantic-handoff-v0.md#510-minimum-contract-and-legal-observations) +and the qualified amendment owner's operation/receipt transaction. Keep request +and Goal state under their separate owners. + +1. **Reserve at the request owner.** In one request transaction, validate the + live source revision and its authority, acquire its exclusive effectful + attempt fence, and persist a reservation binding request/revision, + attempt/fence epoch, target Goal and authority source, proposal digest, + expected Goal basis, actor and `operation_id`. The amendment owner must + authenticate this reservation; a caller-supplied token is not authority. + Reservation replay returns the same binding; changing any bound input + conflicts. Reservation and effective cancellation/supersession use the same + request-owner CAS over source revision, lifecycle and fence epoch; whichever + wins determines eligibility. Recording a later correction does not revoke + the already reserved operation or make its immutable source binding stale. +2. **Order later control requests.** Once reserved, cancellation or correction + can be recorded immediately but cannot revoke that in-flight operation by + changing only the request store. Mark it pending settlement, prevent further + effects/reassignment, and ask the amendment owner to abort that exact + operation. The reservation covers only this immutable operation, never the + rest of a superseded request or a replacement proposal. Authorization and + policy checks at the actual effect owner still apply. Abort requires a + request-owner cancellation/recovery receipt bound to the reservation, reason + and operation; knowing an operation ID is insufficient authority. +3. **Settle at the Goal owner.** An authenticated commit or abort competes for + one durable terminal operation record at `GoalAmendmentAuthority`. Commit + validates the reservation, current policy and expected Goal basis, then + atomically writes the Goal delta and `committed` receipt. Abort atomically + writes an `aborted` no-effect receipt only if that operation has not committed. + Both use the same operation identity and serialization boundary; abort is a + terminal tombstone, not a separate retry identity. A committed operation + cannot be undone by abort, and an aborted operation can never commit. Replays + read the original outcome; digest/binding drift conflicts. Definitive policy + or basis rejection also closes the operation without a Goal mutation. Validate + the authenticated binding inside this serialization boundary. A fresh + operation ID requires a new reservation and cannot bypass an old tombstone. + Terminal receipts discriminate `committed`, `aborted` and `rejected`, carry + the reservation/attempt reference, and state whether this operation changed + the Goal. No-effect receipts have no resulting Goal revision and say nothing + about other external effects in the broader request. +4. **Recover before releasing.** Link the exact terminal Goal-owner receipt to + the immutable request attempt before releasing its fence or acknowledging + cancellation. This linking/settlement is a separate idempotent request-owner + transaction: settle the exact attempt, apply pending control changes for + remaining work, then release. It never rolls back a committed Goal delta. + A missing receipt, timeout or expired worker lease proves + nothing: read back or race a conditional abort against commit under the same + operation identity. If the owner is unavailable, retain pending/unknown and + allow unrelated work; do not reassign the effect. Retain the terminal record + until stale attempts are provably unable to submit, including after restart + or source migration. A delayed worker must hit that durable boundary, not + merely a token TTL. Reservations do not expire independently of settlement; + deadlines trigger recovery, not permission to forget an unresolved operation. + Unsupported profiles cannot commit request-derived + amendments; they may still admit proposals and continue independent work. + +Reservation CAS orders source eligibility; the Goal-owner terminal transaction +orders the reserved commit versus abort. These are two explicit local decisions, +not a claim that a source read and Goal write are atomic. The first Stage 3 +class remains `shared_work_graph`; this protocol adds no amendment permission. + +The combined manager A7/A16 fixture must exercise these interleavings through +both owners, not two independent unit suites: + +| Interleaving | Required outcome | +| --- | --- | +| Cancellation/correction wins before reservation | No reservation and no Goal mutation from the obsolete proposal | +| Reservation exists; cancellation's abort wins at Goal owner | One `aborted` receipt; delayed original commit rejected; cancellation can settle | +| Reserved commit wins before abort | One `committed` receipt; cancellation reports the already committed effect and stops remaining work, without claiming rollback | +| Crash after reservation/check but before a known Goal outcome | Fence remains; same-operation recovery/conditional abort yields exactly one terminal outcome, even if the old worker resumes | +| Goal CAS succeeds but its response or request-side linkage is lost | Read back the original committed receipt, attach it to the old attempt, and never reapply the delta | +| Lease expires or host restarts while outcome is unknown | No replacement effect on timeout alone; terminal abort blocks late commit, or the existing commit is reconciled | + +Frontend, Lark and CLI project the same distinction between cancellation +requested, pending settlement and settled-with/without-an-already-committed +effect. A timeout must not display “cancelled, no change.” Implementing PRs must +qualify this path on the selected authority profile before enabling it. + ## 6. Proposed schemas Illustrative `goal_amendment_proposal_v0`: 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 b390280a3e..d964be6c1a 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 @@ -3,7 +3,7 @@ - 状态:草案;维护者评审中 - 跟踪 Issue:[#3836](https://github.com/huangruiteng/loopx/issues/3836) - 日期:2026-09-02 -- 最后更新:2026-09-13 +- 最后更新:2026-09-15 - 范围:多个对等 Agent 围绕同一个共享 Goal 协作,同时保留 canonical intent、每个 Agent 的执行 frontier、claim/lease 所有权,以及可审计的 replan/amendment 决策 @@ -292,9 +292,9 @@ committing --CAS success--> committed + receipt -> frontier reconciliation policy 阻塞。Semantic amendment 不能静默使 lease 已授权的工作失效。 5. **Commit。** `GoalAmendmentAuthority` transaction 带 `operation_id`、期望的 `base_goal_revision` 与 `base_intent_digest` 提交 policy-authorized digest, - 再次校验 policy 并执行一次 CAS。对于 request-derived proposal,同一次授权 - decision 还要验证所绑定的来源 request revision 仍有效且未被撤销或替代;撤销/ - 替代与 commit 竞态时 fail closed。Goal 或来源请求的 basis 过期均 fail closed。 + 再次校验 policy 并执行一次 CAS。对于 request-derived proposal,必须使用第 5.1 节 + 的精确来源 reservation 与 operation 终局协议;远端读一次有效性再做 Goal CAS 不够。 + Goal 基线过期,或来源 revision 已被替代且没有 reservation,均 fail closed。 日常 in-envelope amendment 不等待人。 6. **Receipt。** 同一事务记录 proposal digest、actor、authority source、旧/新 revision、retained/changed/stopped delta、evidence references、affected Todos、 @@ -306,6 +306,64 @@ committing --CAS success--> committed + receipt -> frontier reconciliation 只有第 5 步会让 amendment 成为 canonical。第 6 步保证响应丢失时仍能恢复这一事实; 第 7 步让它对所有 peer 真正产生运行时影响。 +### 5.1 来源请求预留与取消顺序 + +这是 request-derived Stage 3 commit 的拟议验收要求,不是已交付 API,也不是新分布式事务。 +复用[协作请求 fence](capable-manager-semantic-handoff-v0.zh-CN.md#510-最小契约与合法-observation) +和已验收 amendment owner 的 operation/receipt 事务;请求与 Goal 仍由各自 owner 管理。 + +1. **在请求 owner 预留。** 同一请求事务校验来源 revision 当前有效及其权限,取得独占 + effectful attempt fence,并持久化 reservation,绑定 request/revision、attempt/fence epoch、 + 目标 Goal 与 authority source、proposal digest、预期 Goal 基线、actor 和 `operation_id`。 + Amendment owner 必须认证该 reservation;调用方自填 token 不构成权限。 + 预留重放返回同一绑定,任何绑定输入改变均冲突。预留与生效的取消/替代使用同一 + 请求 owner 的 CAS,检查来源 revision、lifecycle 和 fence epoch,先胜出者决定资格。 + 记录后来的纠正不会撤销已预留 operation,也不会使其不可变来源绑定失效。 +2. **排序后来的控制请求。** 预留后仍立即记录取消或纠正,但不能只改请求 store 就撤销 + 该在途 operation。将其标为待结算,阻止后续效果/改派,并要求 amendment owner 中止 + 这一次精确 operation。Reservation 只覆盖该不可变 operation,不覆盖被替代请求的其他 + 工作或新 proposal。实际 effect owner 的权限与 policy 校验仍必须满足。Abort 需要 + 请求 owner 出具的取消/恢复回执,绑定 reservation、原因与 operation;只知道 operation ID 没有此权限。 +3. **在 Goal owner 结算。** 已认证的 commit 与 abort 在 `GoalAmendmentAuthority` 竞争 + 同一个持久终局 operation record。Commit 校验 reservation、当前 policy 和预期 Goal + 基线,原子写入 Goal delta 与 `committed` 回执。Abort 仅在尚未提交时原子写入 + `aborted` 无效果回执。两者使用相同 operation identity 和串行化边界;abort 是终局 + tombstone,不是另起重试身份。已提交不可被 abort 撤销,已中止永远不能再 commit。 + 重放读回原结果,digest/绑定漂移冲突。确定的 policy 或基线拒绝也以无 Goal 修改关闭 operation。 + 在此串行化边界内校验已认证绑定;新 operation ID 必须重新取得 reservation,不能绕过旧 + tombstone。终局回执区分 `committed`、`aborted`、`rejected`,携带 reservation/attempt 引用, + 明确本 operation 是否修改 Goal。无效果回执没有产生的新 Goal revision,也不代表整个请求 + 的其他外部效果不存在。 +4. **恢复后才释放。** 将 Goal owner 的精确终局回执关联到不可变请求 attempt 后,才能 + 释放 fence 或确认取消结果。该关联/结算是请求 owner 的独立幂等事务:结算精确 attempt, + 对剩余工作应用待处理控制变化,再释放;绝不回滚已提交的 Goal delta。 + 回执缺失、超时或 worker lease 过期均不能证明无效果: + 在相同 operation identity 下读回,或让条件 abort 与 commit 竞争。Owner 不可用时 + 保持 pending/unknown,允许无关工作,但不改派该效果。终局记录必须保留到可证明旧 + attempt 不可能再提交,包括重启或来源迁移之后。晚到 worker 必须命中此持久边界, + 不能仅靠 token TTL。Reservation 不独立于结算自行过期;deadline 触发恢复,不授权遗忘 + 未决 operation。未支持该协议的 profile 不能提交 request-derived amendment; + 仍可准入 proposal 并继续独立工作。 + +Reservation CAS 决定来源资格先后;Goal owner 的终局事务决定已预留 commit 与 abort +的胜负。这是两个明确的本地决定,不声称来源读取和 Goal 写入原子。首个 Stage 3 class +仍限于 `shared_work_graph`;该协议不扩大 amendment 权限。 + +管家 A7/A16 联合 fixture 必须经过两个 owner 验证以下交错,不能用两套独立单测替代: + +| 交错 | 必须结果 | +| --- | --- | +| 取消/纠正在预留前胜出 | 没有 reservation,旧 proposal 不修改 Goal | +| 已预留;取消的 abort 在 Goal owner 胜出 | 只有一份 `aborted` 回执;晚到原 commit 被拒绝;取消可以结算 | +| 已预留 commit 先于 abort 胜出 | 只有一份 `committed` 回执;取消报告已提交效果并停止剩余工作,不声称回滚 | +| 预留/校验后崩溃,尚不知 Goal 结果 | 保留 fence;同 operation 恢复/条件 abort 产生唯一终局,即使旧 worker 恢复也如此 | +| Goal CAS 成功,但响应或请求侧关联丢失 | 读回原 committed 回执,关联旧 attempt,绝不重复应用 delta | +| 结果未知时 lease 过期或宿主重启 | 不因超时启动替代效果;终局 abort 拦住晚到 commit,或对账既有 commit | + +前端、飞书、CLI 共用投影,区分已请求取消、待结算、已结算且有/无既有提交效果。 +超时不能显示“已取消、没有修改”。实现 PR 必须先在选定 authority profile 验收该路径, +再启用它。 + ## 6. 提议的 schema 示意 `goal_amendment_proposal_v0`: