Execution Contract
The audited v6 execution boundaries and v7 compatibility decisions.
Execution contract
This is the Stage 1 contract matrix tracked by #5044. It describes v6 as it exists; it does not promise exactly-once effects or pre-approve a v7 API. An invocation succeeding means its local boundary completed, not that an external business effect is proven.
Boundary matrix
| Boundary | Execution and state owner | Retry owner | Completion and cancellation | Persistence and recovery | Known gap / decision |
|---|---|---|---|---|---|
| Direct service RPC | Client and service handler | Caller/client wrappers | RPC response or error; the request context carries cancellation | None in the core RPC contract | Effects require an application idempotency key or reconciliation. No v7 break is required. |
Direct agent Ask | Agent harness | Agent/model provider according to their configured limits | A response completes the run; errors are classified; context cancellation cancels active work | Opt-in checkpoint records run, tool results, and stage; Resume is explicit | Providers may still own tool iteration. Moving all iteration to the harness is a v7 break. |
| Streaming agent request | Agent harness and stream producer | Same as direct agent execution | Terminal event/error closes the stream; context or disconnected consumer cancels active delivery | Checkpoint and ResumeStreamAsk use the same run identity when configured | A single provider event contract is a v7 target. |
| Durable agent approval/input | Agent harness | The resumed run; approval itself is not retried | Waiting is a distinct paused error; denial and cancellation are not success | The pause and exact tool call are saved before returning; resume requires the run and approval/input identity | Keep and strengthen in v6. Hosts must use persistent storage for restart recovery. |
| Prompt-driven flow | Flow plus model provider | Provider/model behavior | Execute returns reply or error; context cancellation is an error | No ordered-step checkpoint boundary | Route adaptive tool use through the agent harness in v7; retain plain model transformations. |
| Ordered flow steps | Flow runner | Flow/step retry policy | Each step is done or failed; cancellation is currently represented as failure metadata | A shared run record saves completed steps; explicit Resume reuses them | Add a distinct cancelled/exhausted outcome compatibly where possible. |
| Agent-dispatch flow step | Flow owns step order; child agent owns adaptive work | Flow retries dispatch; agent owns its internal retries | RPC success completes the parent step; child run ID records lineage | Parent and child checkpoint independently | Prevent nested retries from multiplying effects; initially a v6 documentation/configuration fix. |
| Flow loop | Flow step owns the whole loop | Loop body and enclosing step policies | Reaching LoopMax currently returns the latest state as success | Only the enclosing step is checkpointed, so restart can repeat iterations | Persist progress and report exhaustion distinctly. Record-shape/outcome changes may require v7. |
| Broker-triggered flow | Broker callback invokes the flow | Broker-specific redelivery plus flow retry | The handler currently acknowledges by returning nil even when execution fails | Flow checkpoint can preserve ordered work, but acknowledgment is not tied to durable acceptance | Define acknowledgment after durable acceptance and deduplicate triggers; likely v7 for a portable broker contract. |
Identity and outcome vocabulary
- Run ID identifies one agent or flow invocation. Parent ID and recorded child run IDs preserve dispatch lineage; step name identifies work inside an ordered run. Names must be unique within a flow.
- Succeeded means the invocation produced its declared result. It does not prove an external effect unless the service supplies evidence.
- Failed means execution ended with an error. Machine-readable error kinds should be preserved when available.
- Cancelled means the context ended by cancellation or deadline. It must not be reported as success.
- Waiting means durable input or approval is required. It is non-terminal and resumes only through an explicit matching operation.
- Exhausted means a retry, step, or loop budget ended before the requested condition was met. It is distinct from success and policy refusal.
- Ambiguous effect means an external action may have completed before its result was saved. Recovery must reconcile or reuse a stable idempotency key; blindly replaying is not safe.
Persisted status strings in v6 remain running, waiting, done, and failed
for compatibility. Cancellation and exhaustion can first be exposed through
error-kind metadata; a stored schema change requires versioning and migration.
Decision record
- Flows own predefined order; agents own adaptive tool selection. Plain service steps and model transformations remain available.
- The boundary that schedules a retry owns its budget. A parent must not assume a child call is effect-free; retries need an idempotency key or an explicitly safe operation.
- Save before acknowledging durable acceptance. Broker delivery must not be acknowledged merely because execution was attempted.
- Checkpoints prove recorded progress, not exactly-once effects. Ambiguous external work is reconciled by the capability owner.
- Service-only applications remain first-class. Shared outcome types must not introduce model or agent dependencies into RPC, registry, or broker APIs.
Compatibility decisions
Suitable for v6
- Preserve cancellation/error kinds and lineage consistently.
- Document retry ownership and require stable idempotency keys for effects.
- Add targeted restart tests around existing checkpoints and durable approval.
- Reject invalid resumes and make unsupported guarantees explicit.
Reserved for v7 unless proved otherwise
- Make provider
Generateone-turn-only and move tool iteration to the agent. - Change portable broker acknowledgment semantics.
- Change persisted status/schema values or flow-loop record shape.
- Unify prompt-driven flow execution with the agent harness where public behavior changes.
The executable make recovery-gate fixture replaces a flow host while retaining
its checkpoint, preserves waiting state and lineage, injects duplicate concurrent
resume, models an ambiguous effect, exhausts a retry budget, and proves that
stable idempotency keys prevent duplicate final effects. This is the v6 recovery
baseline; a portable cross-host lease or compare-and-swap checkpoint contract
remains v7 work.
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.