From f17e0620a5eca5cd457b3d235270fe235bd264c2 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 14 Nov 2026 17:07:02 +0000 Subject: [PATCH] Clarify execution control lifecycle boundaries --- docs/roadmap/execution-controls.md | 78 ++++++++++++++++++++++-------- 1 file changed, 57 insertions(+), 21 deletions(-) diff --git a/docs/roadmap/execution-controls.md b/docs/roadmap/execution-controls.md index 1acadc7..d692358 100644 --- a/docs/roadmap/execution-controls.md +++ b/docs/roadmap/execution-controls.md @@ -58,8 +58,21 @@ lifecycle; the coordinator does not delegate execution to an application executo An application can select a duration for each requested continuation. When that continuation starts, establish a fresh child deadline before preparation and use it for the entire operation: preparation, admission waiting, retries, generation, -structural validation, and structural repair. Do not restart the budget between -phases or attempts. +structural validation, and structural repair, including the prepared-details +notification. Do not restart the budget between phases or attempts. + +The selected timeout covers work according to the entry point: + +| Entry point | Selected timeout behavior | +| --- | --- | +| `Run`, including coordinated turns | Starts before preparation and covers preparation and execution. | +| `PrepareExecution` | Retains the duration for later execution; preparation uses its supplied context. | +| `RunPrepared` | Starts the retained duration when invoked, covering the remaining execution. | + +Idle time between split preparation and execution does not consume the retained +execution budget. Applications wanting one budget across both calls can pass the +same caller-created deadline context through them. `Prepare` and `ValidateRequest` +continue using their supplied contexts without starting the execution timeout. Respect parent cancellation and earlier parent deadlines. A local timeout ends the affected operation and coordination under the existing operational-error @@ -67,30 +80,39 @@ rule; it does not cancel the parent or siblings. Release child-context resources before returning to the application's next-turn callback. Assessment calls from that callback retain their own application-selected contexts and budgets. -A completed operation does not become canceled merely because its child context -is cleaned up after execution. Preserve the existing coordinator behavior for -completed responses, parent cancellation before callback delivery, and the single -undelivered response. No automatic replay or new recovery policy is added. +Determine the execution result and any local-timeout identity before publishing +the terminal observation, so the returned error and observed outcome agree. +A slow terminal observer or subsequent child-context cleanup must not +retroactively turn a completed operation into a timeout. Preserve the existing +coordinator behavior for completed responses, parent cancellation before +next-turn callback delivery, and the single undelivered response. No automatic +replay or new recovery policy is added. No selected timeout means existing context behavior. This adds no framework-wide recommended duration or mandatory cap. Additional-turn, transport-retry, structural-repair, and provider-generation budgets keep their existing meanings. Cancellation remains cooperative; a deadline does not forcibly terminate -application callbacks or injected collaborators that ignore their context. +application callbacks or injected collaborators that ignore their context, or +guarantee that the public call returns by that deadline. ### Opt-In Prepared Details Before Generation Provide explicitly selected access to caller-owned details of the logical request -that will execute, after successful preparation and before its first generation -attempt. Reuse the existing prepared-details representation and credential -redaction where practical. Include assembled captured history, rendered follow-up -messages, caller-appended messages, and ordinary resolved execution metadata. +selected for execution, after successful preparation and before its first +generation attempt. Reuse the existing prepared-details representation and +credential redaction where practical. Include assembled captured history, rendered +follow-up messages, caller-appended messages, and ordinary resolved execution +metadata. Use the execution's prepared snapshot rather than rendering or reading inputs again. Retaining or modifying delivered details must not mutate the execution. -The application can retain them after provider failure or cancellation even when -no ordinary result or exchange is returned. If preparation fails, no complete -snapshot is required. Cancellation before notification does not promise delivery; +Once delivered, details remain available to the application after provider failure +or cancellation even when no ordinary result or exchange is returned. Diagnostic +access is available only when execution reaches the prepared-notification point, +not for every failed operation. Preparation failure requires no complete snapshot; +ordinary admission failure or timeout may occur before preparation completes. +Do not add rendering or rearrange admission solely to manufacture diagnostics for +those failures. Cancellation before notification does not promise delivery; follow the context checks in [Decision 3](#3-what-is-the-prepared-details-callback-contract). This access exposes logical prepared content, not raw HTTP envelopes or internal @@ -106,11 +128,16 @@ contracts. Request observers, coordinator observers, and explicitly selected groups continue receiving ordinary execution facts without duplicate lifecycle events or counting attempts twice. -Avoid changing the coordinator to an explicit public prepare/run sequence merely -to obtain details: that would change ordinary admission and preparation-failure -observation behavior. Reuse the execution path and its existing ownership -boundaries. Follow the accepted split-preparation and callback semantics below; -do not silently ignore a newly supplied option on one entry point. +Preserve ordinary admission, preparation-failure observation, and ownership +behavior. A simple replacement of ordinary `Run` with the public +`PrepareExecution`/`RunPrepared` sequence would change those behaviors. This does +not freeze the internal call structure: consolidation or refactoring is welcome +where it preserves the selected lifecycle. + +Document which controls each entry point applies or retains. Execution-only +controls need not take effect during `Prepare` or `ValidateRequest`; accepting +request-shaped input there does not itself justify rejecting such controls or +starting a timer. Follow the accepted split-preparation and callback semantics. ## Work From The Baseline @@ -118,10 +145,13 @@ do not silently ignore a newly supplied option on one entry point. split-preparation usage sketches under the accepted lifecycle below. Specify omitted/zero/negative timeout handling using ordinary duration conventions, and express the selected callback timing and cleanup in the public contract. + Document the entry-point distinctions and conditional diagnostic availability. Choose names and signatures without adding a broader lifecycle-hook framework. 2. **Add operation-budget handling.** Establish and clean up the child scope at the selected execution boundary. Preserve earlier parent deadlines and public error identity through facade mapping and terminal observation classification. + Determine the outcome before terminal delivery and prevent observer latency + or child-context cleanup from changing it afterward. Ensure cleanup does not affect the coordinator parent or subsequent callbacks. 3. **Expose the prepared snapshot.** Deliver detached public details from the existing prepared state before generation. Cover both ordinary execution and @@ -156,11 +186,17 @@ and the accepted lifecycle choices: cancellation/deadlines remain effective. - Next-turn assessment uses the parent context after release, including another call to a backend with capacity one. Timeout identity survives public wrapping. +- A slow terminal observer or child-context cleanup does not change a completed + outcome into a local timeout; the returned error and terminal observation agree. - Prepared details precede generation, contain the assembled continuation, and remain available after later failure. Mutation of the delivered copy or source changes after preparation do not change the executed snapshot. -- No duplicate preparation, provider call, notification per internal repair, or - observer lifecycle is introduced. Existing credential redaction remains intact. +- Diagnostic access introduces no additional preparation or inference calls, + notification per internal repair, or duplicate observer lifecycle. Ordinary + retries and structural repair remain allowed. Credential redaction remains + intact. +- Admission or preparation failure before the notification point does not require + diagnostic delivery or additional rendering to produce a snapshot. - Preparation failure, cancellation around notification, and callback panic follow the selected delivery rules and do not strand admission or retained resources. - Split preparation uses its supplied context and retains the selected duration