base-layer/promptkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity

Clarify execution control lifecycle boundaries

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-14 17:07:02 +00:00
parent 5ad1b7aa6e
commit f17e0620a5
1 changed files with 57 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

78
docs/roadmap/execution-controls.md
View File

@@ -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 An application can select a duration for each requested continuation. When that
continuation starts, establish a fresh child deadline before preparation and use continuation starts, establish a fresh child deadline before preparation and use
it for the entire operation: preparation, admission waiting, retries, generation, it for the entire operation: preparation, admission waiting, retries, generation,
structural validation, and structural repair. Do not restart the budget between structural validation, and structural repair, including the prepared-details
phases or attempts. 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 Respect parent cancellation and earlier parent deadlines. A local timeout ends
the affected operation and coordination under the existing operational-error 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 before returning to the application's next-turn callback. Assessment calls from
that callback retain their own application-selected contexts and budgets. that callback retain their own application-selected contexts and budgets.
A completed operation does not become canceled merely because its child context Determine the execution result and any local-timeout identity before publishing
is cleaned up after execution. Preserve the existing coordinator behavior for the terminal observation, so the returned error and observed outcome agree.
completed responses, parent cancellation before callback delivery, and the single A slow terminal observer or subsequent child-context cleanup must not
undelivered response. No automatic replay or new recovery policy is added. 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 No selected timeout means existing context behavior. This adds no framework-wide
recommended duration or mandatory cap. Additional-turn, transport-retry, recommended duration or mandatory cap. Additional-turn, transport-retry,
structural-repair, and provider-generation budgets keep their existing meanings. structural-repair, and provider-generation budgets keep their existing meanings.
Cancellation remains cooperative; a deadline does not forcibly terminate 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 ### Opt-In Prepared Details Before Generation
Provide explicitly selected access to caller-owned details of the logical request Provide explicitly selected access to caller-owned details of the logical request
that will execute, after successful preparation and before its first generation selected for execution, after successful preparation and before its first
attempt. Reuse the existing prepared-details representation and credential generation attempt. Reuse the existing prepared-details representation and
redaction where practical. Include assembled captured history, rendered follow-up credential redaction where practical. Include assembled captured history, rendered
messages, caller-appended messages, and ordinary resolved execution metadata. follow-up messages, caller-appended messages, and ordinary resolved execution
metadata.
Use the execution's prepared snapshot rather than rendering or reading inputs Use the execution's prepared snapshot rather than rendering or reading inputs
again. Retaining or modifying delivered details must not mutate the execution. again. Retaining or modifying delivered details must not mutate the execution.
The application can retain them after provider failure or cancellation even when Once delivered, details remain available to the application after provider failure
no ordinary result or exchange is returned. If preparation fails, no complete or cancellation even when no ordinary result or exchange is returned. Diagnostic
snapshot is required. Cancellation before notification does not promise delivery; 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). 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 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 groups continue receiving ordinary execution facts without duplicate lifecycle
events or counting attempts twice. events or counting attempts twice.
Avoid changing the coordinator to an explicit public prepare/run sequence merely Preserve ordinary admission, preparation-failure observation, and ownership
to obtain details: that would change ordinary admission and preparation-failure behavior. A simple replacement of ordinary `Run` with the public
observation behavior. Reuse the execution path and its existing ownership `PrepareExecution`/`RunPrepared` sequence would change those behaviors. This does
boundaries. Follow the accepted split-preparation and callback semantics below; not freeze the internal call structure: consolidation or refactoring is welcome
do not silently ignore a newly supplied option on one entry point. 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 ## 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 split-preparation usage sketches under the accepted lifecycle below. Specify
omitted/zero/negative timeout handling using ordinary duration conventions, omitted/zero/negative timeout handling using ordinary duration conventions,
and express the selected callback timing and cleanup in the public contract. 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. Choose names and signatures without adding a broader lifecycle-hook framework.
2. **Add operation-budget handling.** Establish and clean up the child scope at 2. **Add operation-budget handling.** Establish and clean up the child scope at
the selected execution boundary. Preserve earlier parent deadlines and public the selected execution boundary. Preserve earlier parent deadlines and public
error identity through facade mapping and terminal observation classification. 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. Ensure cleanup does not affect the coordinator parent or subsequent callbacks.
3. **Expose the prepared snapshot.** Deliver detached public details from the 3. **Expose the prepared snapshot.** Deliver detached public details from the
existing prepared state before generation. Cover both ordinary execution and existing prepared state before generation. Cover both ordinary execution and
@@ -156,11 +186,17 @@ and the accepted lifecycle choices:
cancellation/deadlines remain effective. cancellation/deadlines remain effective.
- Next-turn assessment uses the parent context after release, including another - Next-turn assessment uses the parent context after release, including another
call to a backend with capacity one. Timeout identity survives public wrapping. 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 - Prepared details precede generation, contain the assembled continuation, and
remain available after later failure. Mutation of the delivered copy or source remain available after later failure. Mutation of the delivered copy or source
changes after preparation do not change the executed snapshot. changes after preparation do not change the executed snapshot.
- No duplicate preparation, provider call, notification per internal repair, or - Diagnostic access introduces no additional preparation or inference calls,
observer lifecycle is introduced. Existing credential redaction remains intact. 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 - Preparation failure, cancellation around notification, and callback panic follow
the selected delivery rules and do not strand admission or retained resources. the selected delivery rules and do not strand admission or retained resources.
- Split preparation uses its supplied context and retains the selected duration - Split preparation uses its supplied context and retains the selected duration