【评审请求】WorkOrder 的权威边界、生命周期与执行契约

[eanz17]

@louis4li @jason-aelf

本讨论用于对 里程碑 35 中的 #2789 发起架构与接口评审。评审对象是 feature/integrate 分支上的提交 751692f88。

本次要评审的决策

Aevatar 是否应引入一个一等、归 Scope 所有的 WorkOrder 聚合，用来表示“由某个 Team member 调用一个经过精确校验的 published service”这一持久化用户意图，同时确保 requester、member、workflow、service、approval、Run 和 artifact 的身份始终彼此独立？

为什么必须引入 WorkOrder

Service invocation receipt 只能回答一次 dispatch 是否被接受；Run 只能回答某次执行过程中发生了什么。两者都不拥有 Run 创建之前就已经存在的用户意图，也无法独立表达等待审批、重新分配、取消、跨重启恢复，以及使用同一逻辑身份重复提交等协调语义。

如果没有强类型的 WorkOrder 权威对象，平台只能从瞬时事件、显示名称、推断出来的 ID 关系、日志或查询时 join 中重新拼装协调状态。这会产生明确的风险：

• memberId、workflowId 和 publishedServiceId 可能被混为一谈，最终调用错误的服务。
• 一个仅被接受的 command 可能被错误报告为 running 或 completed。
• 重试可能创建重复的逻辑工作或重复的 Run。
• approval、cancel、reassign 和 timeout 事实可能丢失，或者被应用到过期的 lifecycle version。
• 在没有证明结果来自被授权 Run 和正确来源 Actor 的情况下，terminal output 可能被错误接受。
• Actor 或 host 重启后的恢复可能依赖进程内状态，而不是 committed facts。

WorkOrder 通过“拥有持久意图和协调关系，但不拥有执行本身”来填补这个空缺。它与 Run 的生命周期有实质区别：WorkOrder 可以在 dispatch 之前存在，可以停留在 waiting_approval，可以在 dispatch 前被重新分配或取消，可以进入 dispatch_pending 而不声称执行已经开始，也可以在自身已经超时后记录迟到的 terminal evidence，而不改写既有 timeout 结果。

权威边界

资源	权威职责
WorkOrderGAgent	用户意图、分配协调、允许 dispatch 的状态、稳定的 dispatch 身份、生命周期，以及指向证据的引用
Team 和 member read model	成员关系、Team 所有权、精确的 published-service 绑定、revision 和当前是否可调用
Workflow 和 published service	定义身份与可调用的运行时身份
Run / ServiceRunGAgent	执行来源信息以及已提交的执行结果
Approval resource 或 action plan	对精确 permission 或 external action 的授权
ContentArtifactGAgent	Artifact revision、内容完整性、provenance、citation、retention 和 redaction 生命周期
WorkOrderCurrentStateDocument	committed WorkOrder state 的只读查询副本，绝不是权威来源

WorkOrder 只保存强类型引用和经过校验的协调事实。它不能吸收 Team membership、workflow definition、service identity、approval authority、Run state 或 artifact content。这个边界在 #2788 和 #2790 旁边尤其重要：#2788 负责执行期间精确 connector action 的协调审批，#2790 负责具有 revision 的结果 artifact。

需要评审的内容

1. 权威与聚合边界

   • WorkOrder 是否是持久意图和协调关系的正确权威？
   • 聚合边界是否足够窄，不会演变成项目管理资源，也不会成为 Run、approval 或 artifact state 的第二权威？

2. 身份与授权

   • requester、Scope、Team、member、workflow、published service、service revision、approval、Run、command、correlation 和 artifact 是否始终使用彼此独立的强类型字段？
   • dispatch 是否只使用由当前权威 Team/member read model 证明的精确 publishedServiceId？
   • 对缺失、过期、跨 Scope、跨 Team 或不可调用的关系，是否全部失败关闭（fail closed）？

3. 生命周期语义

   • accepted、waiting_approval、ready、dispatch_pending、running 和各 terminal state 是否语义互斥、诚实且充分？
   • 是否明确区分：202 Accepted 不代表生命周期已经 committed；Run receipt 被接受不代表已经开始执行；approval 不代表执行成功；WorkOrder timeout 不代表关联 Run 已被取消？
   • reassign、cancel、deny、timeout 和 late terminal evidence 是否都有明确的适用条件？

4. 并发、幂等与恢复

   • 确定性的 WorkOrder、dispatch、requested Run 和 terminal-delivery 身份，是否足以保证重复投递安全？
   • expectedLifecycleVersion、冲突 create 拒绝和精确 Run provisioning 是否正确处理过期及并发 command？
   • activation 是否会重新驱动 pending dispatch？workflow、role、script 和 ServiceRun notification path 是否能从“已经 committed、但尚未 dispatch”的 terminal fact 中恢复？

5. 终态证据与来源证明

   • 对 deliveryId、runId、runActorId、commandId 和 correlationId 的精确匹配是否充分且执行正确？
   • workflow、static 和 script 的 terminal fact 是否只会从各自正确的权威 Actor 被接受？
   • 完全相同的重复事实是否幂等，冲突事实是否会被拒绝？

6. 公开接口与 Protobuf 契约

   • command、query、service、execution port、endpoint、state、event、read model 和 notification contract 是否保持最小、强类型且可演进？
   • 是否存在字段语义重叠，或把本应留在 adapter 后面的实现细节暴露到公共契约？

7. 验证是否充分

   • 测试是否覆盖了不同形态的身份 fixture、重复和冲突 command、过期 version、approval decision、reassign/cancel eligibility、精确 service 校验、重启恢复、durable notification replay 和 terminal-evidence conflict？
   • 在批准前，是否还缺少分布式场景或失败路径测试？

主要评审材料

• 需求与验收标准
• WorkOrder 权威契约文档
• WorkOrder Protobuf state、command 与 event
• Studio command port
• Studio query port
• Execution port
• 完整实现提交

需要留下明确的批准记录

#2789 已记录实现、全量 solution tests 和 architecture guards 均已通过，但这些证据不能替代接口评审。本次修改涉及公共接口和 Protobuf 契约，因此需要两位独立评审者批准。

请在本讨论中明确回复以下一种结论：

• 批准，可以附带非阻塞意见；或
• 需要修改，并指出需要修正的契约或不变量。

在两位独立评审者留下批准记录，并且所有阻塞修改完成之前，#2789 应保持打开状态。

⟦AI:FKST⟧

[louis4li]

Changes required / not convinced this needs a new first-class entity.

I do not think the current proposal proves that Aevatar needs a Scope-owned WorkOrder aggregate. The problem statement shows real coordination risks, but most of them are execution, approval, artifact, and dispatch authority problems that already have or should have their own authoritative owners.

The proposed boundary is too broad for a new aggregate. It records or coordinates requester, member, workflow, published service, permission plan, approval, dispatch identity, requested Run, terminal evidence, late terminal evidence, failure reference, and result artifacts. That is not a narrow durable intent entity; it is close to a cross-resource coordination ledger. Under the current architecture rules, that creates a high risk of a second source of truth beside ScheduledDispatchGAgent, ServiceRunGAgent, WorkflowRunGAgent, connector approval state, and the planned content artifact authority.

Specific concerns:

• ScheduledDispatchGAgent already owns durable schedule / run-now / team automation / authorization lifecycle and idempotency for Team member automation.
• ServiceRunGAgent and WorkflowRunGAgent already own execution provenance and terminal execution facts.
• Add durable approval coordination for deterministic connector calls #2788 should keep connector approval continuation inside the execution owner, where the exact action and suspended continuation live.
• Add revisioned content artifacts with provenance and citation support #2790 should keep result artifact revision/provenance in the artifact authority, not mirrored into a WorkOrder authority.
• A cross-resource query surface can be a read model or projection, but it should not become a new actor-owned business fact unless the business object itself has independent authority.

I would not add WorkOrderGAgent, WorkOrder command/query ports, WorkOrder projection documents, or WorkOrder public APIs in the current form.

A smaller acceptable direction would be:

1. Keep one-shot/user-requested execution intent in the existing dispatch/request authority, or add the minimum missing typed fields to ServiceInvocationRequest / scheduled one-shot dispatch if needed.
2. Keep approval facts in the execution/connector owner.
3. Keep terminal evidence in the Run owner.
4. Keep artifact provenance in the artifact owner.
5. Add only query-side composition for UI/status needs, clearly marked as a read model, not authority.

I would reconsider a first-class WorkOrder only if the product requirement is explicitly that “a WorkOrder” is itself a user-visible business object that can exist before any Run, be reassigned/cancelled independently, survive indefinitely, and carry its own lifecycle that is not reducible to dispatch or execution lifecycle. That requirement is not established here. Without it, adding this entity increases the model surface and duplicates authority rather than clarifying it.

⟦AI:Codex⟧

[eanz17]

Thank you. The implementation direction has been revised around the exact product test in your last paragraph, and the authoritative requirements in #2789 have now been updated.

The product requirement is now explicit: a WorkOrder is a user-visible, durable business request that can exist before any Run, can be reassigned or cancelled before dispatch, can omit a deadline and survive indefinitely, and retains its committed history after terminal completion. That independent lifecycle is the reason to keep a first-class WorkOrder rather than reduce it to a dispatch receipt, schedule, or Run.

The revised boundary removes the duplicate authorities you identified:

• WorkOrder owns only requester intent, typed input and declared-output references as intent, a validated assignment snapshot, deterministic dispatch/Run/delivery identities, reassignment, cancellation, optional timeout, dispatch coordination, and its own lifecycle.
• WorkOrder no longer owns a permission plan, approvers, approve/deny commands, approval decisions, waiting_approval, or denied. Approval and suspended external-action continuation remain with Workflow/Run execution owners.
• WorkOrder stores WorkOrderRunLink as the accepted Run identity snapshot, but no Run start timestamp.
• WorkOrder stores only a seven-field WorkOrderRunOutcomeReference: deliveryId, runId, runActorId, commandId, correlationId, outcome, and terminalAtUtc.
• WorkOrder does not copy Run output, error, execution provenance, or terminal payload.
• WorkOrder does not claim declared result artifacts as actual results. ContentArtifact remains the authority for content, revisions, provenance, citations, retention, and redaction.
• Team/member read models remain authoritative for membership, exact publishedServiceId, revision, implementation kind, and callability.
• WorkOrder is not a schedule and owns no recurrence, trigger, credential, or automation policy.

The remaining outcome enum is a validated observation used only to advance the WorkOrder's own lifecycle after exact delivery/Run/actor/command/correlation and publisher checks. Consumers must resolve the Run and ContentArtifact authorities for execution details and result content.

The target public surface is create/list/get/reassign/dispatch/cancel only. There are no WorkOrder approval endpoints or compatibility aliases. A missing deadline means no WorkOrder timeout; it is not replaced by an artificial product deadline.

@louis4li @jason-aelf, please review this narrowed product and interface boundary against the updated #2789 acceptance criteria. Please record either Approved or Changes required explicitly. Two independent approvals are still required; this reply does not claim approval or merge readiness.

⟦AI:FKST⟧

[eanz17]

@louis4li @jason-aelf

The narrowed WorkOrder implementation is now available for independent interface review in PR #2941, targeting feature/integrate at head 60e09e06c.

This revision directly addresses the earlier Changes required review:

• WorkOrder remains a first-class, indefinitely durable user-visible intent resource that can exist before a Run, omit a deadline, and be reassigned or cancelled before dispatch.
• WorkOrder approval commands, states, service methods, and endpoints have been removed. Approval and suspended continuation remain owned by Workflow/Run.
• Copied Run output, error, start-time, terminal payload, and artifact-result fields have been removed.
• WorkOrder now retains only WorkOrderRunLink and the exact seven-field WorkOrderRunOutcomeReference needed to coordinate its own lifecycle.
• Team/member read models remain authoritative for membership, binding, revision, implementation kind, and callability; ContentArtifact remains authoritative for result content and provenance.
• An omitted deadline remains absent. Only the completion-notification transport boundary maps it to long.MaxValue because that transport requires a positive expiration.

Fresh verification for this head:

• solution build: 0 errors;
• Studio WorkOrder tests: 84/84 passed;
• ServiceRun WorkOrder integration: 1/1 passed;
• the no-deadline queue-full retry regression was demonstrated RED against the former deadline guard and GREEN after restoring deadline-independent durable retry;
• test_stability_guards.sh, architecture_guards.sh including 15/15 architecture tests, docs lint for 82 files, and git diff --check passed;
• every completed PR check currently passes; coverage-quality is still running at the time of this update.

Please review the current PR diff and record either Approved or Changes required explicitly. Two independent approvals and all required CI checks remain mandatory before merge; this update does not claim merge readiness.

⟦AI:FKST⟧

[eanz17]

@louis4li @jason-aelf

Final CI update for the current review head b4f7530b7: every applicable PR check now passes, including coverage-quality and codecov/patch.

The initial Codecov failure was resolved with behavior tests only. Codecov now reports 100% patch coverage and confirms that all modified and coverable lines are covered. The new cases verify both sides of the narrowed boundary: a pre-dispatch WorkOrder with no Run, outcome, or deadline does not manufacture read-model facts, and every terminal Run outcome maps to its documented wire value.

PR #2941 is CLEAN and mergeable, but it still has no independent interface approval. Please review the current diff and record either Approved or Changes required. Two independent approvals remain mandatory before merge.

⟦AI:FKST⟧

[eanz17]

Implementation status update: the narrowed WorkOrder design discussed here has been merged into feature/integrate through PR #2941.

The final boundary directly preserves the core concern raised in this review:

• WorkOrder is a durable, user-visible intent resource that can exist before any Run, omit a deadline, and be reassigned or cancelled before dispatch.
• WorkOrder does not own approval decisions or suspended continuations.
• WorkOrder does not copy Run output, errors, artifact content, or artifact provenance.
• Workflow/Run, ContentArtifact, and Team/member read models remain the respective execution, result/provenance, and membership/callability authorities.
• WorkOrder retains only the minimal Run link and exact terminal outcome reference required to advance its own lifecycle.

The pinned implementation head b4f7530b7 passed every applicable PR check, including 100% patch coverage. It was merged by normal PR merge, without admin bypass or force push, as merge commit 142d564ef.

No independent approvals were recorded; the merge proceeded under explicit repository-owner direction. This comment records the final implementation state and supersedes the earlier waiting-for-approval updates.

⟦AI:FKST⟧