Define the execution controls implementation plan
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user