cleveragents/cleveragents-core
4
0
Fork 3
Code Issues 6.0k Pull Requests 115 Actions Packages Projects Releases Wiki Activity

docs(spec): clarify fail_fast cancel semantics and A2A facade idempotency #7410

Closed
HAL9000 wants to merge 1 commits from spec/arch-failfast-cancel-semantics into master
pull from: spec/arch-failfast-cancel-semantics
merge into: cleveragents:master
Conversation 6 Commits 1 Files Changed 1
+38

1 Commits

Author SHA1 Message Date
HAL9000 4015698e95 docs(spec): clarify fail_fast cancel semantics and A2A facade idempotency
CI / lint (pull_request) Successful in 42s
Details
CI / helm (pull_request) Successful in 25s
Details
CI / push-validation (pull_request) Successful in 29s
Details
CI / typecheck (pull_request) Successful in 1m14s
Details
CI / build (pull_request) Successful in 3m18s
Details
CI / quality (pull_request) Successful in 3m50s
Details
CI / security (pull_request) Successful in 4m4s
Details
CI / e2e_tests (pull_request) Successful in 6m17s
Details
CI / integration_tests (pull_request) Successful in 7m22s
Details
CI / unit_tests (pull_request) Successful in 8m7s
Details
CI / docker (pull_request) Successful in 1m35s
Details
CI / coverage (pull_request) Successful in 13m51s
Details
CI / status-check (pull_request) Successful in 1s
Details
CI / benchmark-publish (pull_request) Has been skipped
Details
CI / benchmark-regression (pull_request) Successful in 56m56s
Details 
Two spec gaps identified from UAT and bug hunt findings:

1. fail_fast cancel semantics (UAT #7394):
   The spec defined fail_fast as a SubplanConfig option but did not specify
   what state unstarted subplans should transition to when fail_fast triggers.
   UAT found that unstarted subplans end up in 'complete' state instead of
   'cancelled', which is a spec violation.

   Clarification: When fail_fast=true and a parallel subplan errors, all
   queued (not yet started) subplans MUST transition to 'cancelled' state.
   'cancelled' is semantically distinct from 'complete' — it means the
   subplan was never started due to a sibling failure.

2. A2A facade idempotency contract (bug #7389):
   The spec described A2A extension methods but did not specify that they
   must be idempotent. Bug found that _handle_plan_apply() raises
   InvalidPhaseTransitionError when called on an already-applied plan,
   breaking idempotency.

   Clarification: All _cleveragents/plan/* methods MUST be idempotent.
   Before invoking the underlying service, check the current plan phase.
   If already at or past the target phase, return current state without
   re-invoking. Raising InvalidPhaseTransitionError to the A2A caller
   is a spec violation.

Refs: UAT #7394, bug #7389
 2026-04-12 16:24:35 +00:00