Define the execution controls implementation plan

This commit is contained in:
2026-11-14 17:15:46 +00:00
parent f17e0620a5
commit 0e4f590f5a
3 changed files with 596 additions and 36 deletions

View File

@@ -1,8 +1,8 @@
# Execution Controls For Coordinated Turns
Status: all four design decisions accepted; ready for API and staged
implementation planning from v0.22.0. No code changes are authorized by this
roadmap. Public names and signatures are not yet selected.
Status: all four design decisions accepted. This document defines the target
state from v0.22.0; [implementation.md](implementation.md) selects the concrete
API and staged implementation work. The feature is not yet implemented.
## Purpose
@@ -139,37 +139,17 @@ 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
## Affected Areas
1. **Design the public API.** Write small ordinary-run, coordinated-turn, and
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
the selected prepared-execution lifecycle without a second preparation pass.
Preserve credential handling and release resources on cancellation or panic.
Avoid snapshot-copy work when the capability is not selected.
4. **Integrate and verify coordination.** Have ordinary execution honor the
selected controls on the callback-returned request under the accepted approach.
Preserve capture and observer composition; verify the next-turn callback runs
with the parent context after admission and child-budget cleanup.
5. **Document and demonstrate.** Update public GoDoc, the
[consumer guide](../consumers/pkg-promptkit.md), relevant internal lifecycle
documentation, and a focused offline example when implementation lands.
Show how applications retain diagnostics on failure and bound independent
assessment calls. Reconcile Audita's scenarios against the final API.
The target spans request controls, execution-context lifetime, detached prepared
details, public error projection, and ordinary coordinator integration. It is an
additive runtime feature; no collection-format or ConfigKit changes are needed.
Public GoDoc will own exact API contracts, the
[consumer guide](../consumers/pkg-promptkit.md) will explain use, and internal
lifecycle documentation will describe the implementation when it lands.
This is an additive runtime feature; no collection-format or ConfigKit changes
are needed. Keep implementation proportional to the two requested controls.
The implementation plan owns API selections, task sequencing, concrete changes,
and validation steps. Keep that work proportional to the two requested controls.
## Validation Targets
@@ -213,8 +193,8 @@ and the accepted lifecycle choices:
## Accepted Decisions
All four decisions below are accepted. No significant product decisions remain
open. Exact public names, signatures, timeout-value conventions, and the Go
representation of timeout identity remain for API and implementation planning.
open. The implementation plan selects public names, signatures, timeout-value
conventions, and the Go representation of timeout identity.
### 1. Narrow Execution Controls Or Caller-Delegated Execution?
@@ -295,8 +275,8 @@ inspectable operation-timeout identity when this newly selected budget causes
termination. Keep parent cancellation/deadlines and provider-local failures
under their existing identities. The marker must survive public wrapping and
must not be inferred from any arbitrary `DeadlineExceeded` returned by a
collaborator. Choose its Go representation during API design; no new
error-report hierarchy or terminal-event category is implied.
collaborator. Its Go representation is selected in the implementation plan;
no new error-report hierarchy or terminal-event category is implied.
This lets callers distinguish the requested local budget from an earlier parent
or provider deadline without retaining the internal child context. Define cause