Clarify execution control lifecycle boundaries

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