From d3bc439bb8f15b7cd4617958767ad9c4fac240ff Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 14 Nov 2026 19:45:18 +0000 Subject: [PATCH] Clarify prepared notification timing and context --- docs/roadmap/remediation.md | 10 ++++++++-- types.go | 19 ++++++++++++------- 2 files changed, 20 insertions(+), 9 deletions(-) diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index 5adbd3c..5593bf9 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -7,7 +7,7 @@ testing, documentation, and agent policies. ## 1. Complete The Public Prepared-Notification Contract -Priority: P3. Status: open. Owning stage: Stage 8. +Priority: P3. Status: complete. Owning stage: Stage 8. Location: [RunRequest.OnPrepared GoDoc](../../types.go#L97). @@ -37,6 +37,12 @@ for every failed request, forced callback interruption, or terminal observation after panic. This is a documentation completion, not a runtime change. Existing behavioral tests already cover these semantics; duplicate tests are unnecessary. +Completion: expanded the field's GoDoc to state invocation cardinality, +non-repetition during retry/repair, and operation-context scope, including the +distinction from the coordinator's next-turn callback context. Runtime behavior +is unchanged. GoDoc rendering and the existing focused race-enabled notification, +retry/repair, and coordinated-budget tests passed. + ## Stage Review Summary | Stage | Result | @@ -48,7 +54,7 @@ behavioral tests already cover these semantics; duplicate tests are unnecessary. | 5 — Phase budgets | Tests cover preparation, capacity waiting, retry backoff, generation/repair, validation, notification time, and stable terminal outcomes. | | 6 — Ownership and failures | Public tests cover detached messages, cache metadata, nested parameters, schema, credentials, frozen sources, retained diagnostics, and panic cleanup. | | 7 — Coordination | Fresh turn budgets, parent-context assessment, released capacity, sibling use, observer composition, and explicit grouping are covered. | -| 8 — Documentation and example | Maintained example and consumer/internal documentation reflect the feature; complete the canonical GoDoc as described in finding 1. | +| 8 — Documentation and example | Maintained example, consumer/internal documentation, and the completed canonical GoDoc reflect the feature; finding 1 is resolved. | No runtime correctness defect, additional architectural gap, or inadvertently strengthened caller restriction or guarantee was identified in this review. diff --git a/types.go b/types.go index 64ea93e..b3507b7 100644 --- a/types.go +++ b/types.go @@ -95,13 +95,18 @@ type RunRequest struct { // collaborators that ignore context cannot be forcibly interrupted. OperationTimeout time.Duration `json:"-" yaml:"-"` // OnPrepared synchronously receives detached, credential-redacted details of - // the logical request after preparation and admission, before generation, - // if execution reaches that point. Admission remains held, and callback time - // consumes OperationTimeout. The callback owns the delivered mutable values; - // its closure is shared and must synchronize any shared state. It has no - // error return, and a panic propagates after resource cleanup. Prepare and - // ValidateRequest do not invoke it; PrepareExecution retains the selected - // function for RunPrepared and Discard releases it. + // the logical request after preparation and admission, before the first + // generation, at most once per logical execution if it reaches that point. + // Transient retries and structural repair do not repeat the notification. + // Its context is the operation-scoped context, subject to OperationTimeout + // and parent cancellation/deadlines. In [Engine.Coordinate], this differs + // from the parent context passed to the next-turn callback. + // Admission remains held, and callback time consumes OperationTimeout. The + // callback owns the delivered mutable values; its closure is shared and must + // synchronize any shared state. It has no error return, and a panic propagates + // after resource cleanup. Prepare and ValidateRequest do not invoke it; + // PrepareExecution retains the selected function for RunPrepared and Discard + // releases it. OnPrepared func(context.Context, PreparedRun) `json:"-" yaml:"-"` // CaptureExchange requests an immutable snapshot of a completed run, even // when its structural validation fails. Operational errors return no result.