Keep coordinator termination contract minimal

docs/roadmap/conversation-continuation.md

@@ -140,7 +140,7 @@ authored roles. This does not reopen the accepted execution-setting precedence.
 
 ### 3. Should PromptKit Coordinate Turns, And Where Does Application Work Run?
 
-**Status: accepted; exact callback and reporting contracts remain open.** Provide
+**Status: accepted; exact public types and accounting details remain open.** Provide
 independently usable continuation primitives and an optional sequential
 coordinator for one branch. The application selects each next request or decides
 to stop. PromptKit manages turn progression and execution bookkeeping under the
@@ -175,9 +175,9 @@ interpret the purpose of that work.
   questions without demonstrated shared answers across consumers. Applications
   can build those workflows from the selected branch-level capabilities.
 
-**Details to settle:** exact request/stop and outcome types, and remaining
+**Details to settle:** exact request/stop and outcome types, and turn-budget
-error/report semantics belong to Decision 4. That decision records accepted
+consumption belong to Decision 4. That decision records accepted response
-response delivery, zero-turn budget behavior, and cancellation boundaries.
+delivery, zero-turn budgets, cancellation, and minimal error/result semantics.
 Execution association and usage accounting belong to Decision 5. The sketches
 below illustrate the selected responsibility split; they do not settle the
 remaining public contracts.
@@ -210,11 +210,11 @@ choose_next(ctx, turn):
         vars = {"question": question}
     ))
 
-report, error = coordinate(
+termination, error = coordinate(
     ctx, start = initial_exchange,
     additional_turns = 3, next = choose_next
 )
-application.present_analysis(analysis, report, error)
+application.present_analysis(analysis, termination, error)
 ```
 
 PromptKit preserves the history and performs each selected execution. It does
@@ -247,11 +247,11 @@ choose_next(ctx, turn):
         vars = audita.follow_up_variables(branch)
     ))
 
-report, error = coordinate(
+termination, error = coordinate(
     ctx, start = initial_exchange,
     additional_turns = 3, next = choose_next
 )
-audita.record_branch_outcome(branch, report, error)
+audita.record_branch_outcome(branch, termination, error)
 ```
 
 The first callback uses existing findings, so initial batch validation is not
@@ -264,17 +264,18 @@ corrections and other branches remain with Audita.
 Both sketches omit application-specific error handling and depict normal turn
 progression. The final permitted response follows the same callback path as
 earlier responses, as accepted in Decision 4. That decision also defines zero-turn
-budgets and cancellation around callback delivery; remaining operational-error
+budgets, cancellation around callback delivery, and a minimal termination result.
-details are open there. Completed work must not be mistaken for application
+The sketches do not imply an archive of responses in that result: applications
-acceptance of its content.
+already receive each completed response through the callback. Completed work
+must not be mistaken for application acceptance of its content.
 The concrete interface should let both examples use the same coordination
 mechanism without manual message-history assembly or per-turn lifecycle
 bookkeeping. Callback model-call association remains part of Decision 5.
 
 ### 4. How Are Application Next Actions And Execution Outcomes Represented?
 
-**Status: normal response delivery, exhaustion, zero-turn budgets, and callback
+**Status: response delivery, exhaustion, zero-turn budgets, cancellation, and
-cancellation decisions accepted; remaining outcome and failure details open.**
+minimal error/result semantics accepted; turn-budget consumption remains open.**
 The coordinator uses content-neutral next actions and distinguishes
 application-directed completion from exhaustion.
 
@@ -288,9 +289,9 @@ application requested additional work that the budget would not permit.
 This gives consumers one response-processing path, including any application
 validation, without a separate path for the final response. Internal transport
 retries and structural repairs do not produce additional conversation-response
-callbacks. Cancellation can interrupt normal delivery as specified below;
+callbacks. Cancellation and operational errors can interrupt normal delivery as
-remaining operational-failure delivery semantics are open. `Stop` and other API
+specified below. `Stop` and other API spellings remain illustrative until public
-spellings remain illustrative until public types are selected.
+types are selected.
 
 **Alternative considered, not selected:** stop immediately when the turn budget
 is used and expose the final response only in the report. This avoids another
@@ -316,11 +317,12 @@ already-complete interaction from one requesting more work.
 
 **Accepted cancellation behavior:** check the caller's context immediately
 before callback invocation, including the initial callback. If cancellation is
-already observed, do not invoke the callback; report interruption and preserve
+already observed, do not invoke the callback; return the context error with its
-the context error identity. Preserve completed-turn information already obtained
+identity preserved. If the coordinator already obtained a completed response
-by the coordinator in the returned report without implying that the application
+that has not been delivered to the callback, preserve that single response in
-processed or accepted it. This does not require recovering a response that a
+the optional result described below. This does not imply application processing
-failed underlying execution did not return.
+or acceptance, or require recovering a response that a failed underlying
+execution did not return.
 
 Cancellation can race with callback invocation. The callback receives the same
 context and is responsible for cooperating with cancellation during its work.
@@ -336,31 +338,56 @@ context is not selected. It could help callbacks that only record results, but
 callbacks may perform substantial application work or model calls; PromptKit
 cannot assume they are merely bookkeeping.
 
-**Recommendation:** let the application request another turn or indicate that
+**Accepted operational-failure behavior:** each continuation is an ordinary
-the interaction should stop, separately from reporting an operational error.
+execution supplied with captured conversation history. Applications receive
-PromptKit need not know whether the application is repairing, investigating,
+completed responses through the callback before another continuation begins.
-or exploring. Permit starting from an existing exchange and application state
+An execution or callback error stops coordination and propagates to the caller,
-without forcing the application to repeat earlier work.
+preserving useful Go error identities. PromptKit does not automatically replay
+the failed continuation or callback. Existing transport retries and structural
+repair remain within ordinary execution. Earlier callback deliveries and
+application work remain intact; applications decide whether the failure affects
+other branches or the overall workflow.
 
-Return execution diagnostics that preserve completed work when an interaction
+**Accepted minimal return contract:** provide only the following information:
-stops. A completed model call does not imply application acceptance of its
+
-content. Audita would map its own acceptance, rejection, withdrawal, and
+- An ordinary Go error for execution failures, callback failures, and
-unavailable-assessment outcomes to the selected generic controls.
+  cancellation, preserving `errors.Is`/`errors.As` behavior.
-Cancellation and operational errors should retain useful Go error identities.
+- A small outcome value distinguishing application-directed stopping from
-Applications decide whether a stopped branch affects independent work.
+  budget exhaustion on normal termination. These outcomes are not errors.
+- An optional completed response when cancellation prevented its delivery to
+  the callback. Reuse existing response types where practical.
+
+Delivery means the callback was invoked with the response; it does not imply
+the application finished processing or accepted it. If that callback returns
+an error, the response is not classified as undelivered or automatically
+delivered again. The coordinator returns no archive of previously delivered
+responses. A small optional result accommodates the undelivered-response case;
+exact Go declarations remain for implementation planning.
+
+Failure-stage fields, additional run-ID references, a separate failure
+classification hierarchy, and aggregate reporting are not part of this minimal
+termination contract. They require a demonstrated consumer need before addition.
+This does not remove fields from existing response values or observation APIs.
+Decision 5 separately evaluates accounting, and Decision 6 inspection, without
+presuming that either needs to expand the coordinator's termination result.
+
+Audita retains its own meanings for acceptance, rejection, withdrawal, and
+assessment unavailability. A normal stop does not assert any of those outcomes.
 
 **Alternative considered, not selected for normal termination:** use callback
 errors to signal ordinary termination as well as operational failure. This can
 reduce the number of result types, but makes normal control flow harder to
-distinguish from failure. The accepted normal flow uses an explicit stop action;
+distinguish from failure. Normal stopping uses an explicit action, while failures
-the operational-error contract remains to be selected.
+use ordinary Go errors. A broader structured termination report was also
+considered and not selected: its additional metadata is unnecessary for the
+demonstrated minimal contract.
 
-**Details to settle:** exact next-action and outcome types; remaining operational
+**Details to settle:** what consumes an additional-turn budget when preparation
-error and result-plus-error behavior beyond the accepted interruption report;
+or generation fails. Keep that budget distinct from structural repair and
-and what consumes an additional-turn budget when preparation or generation
+transport retry. Exact next-action, outcome, and optional-result types remain
-fails. Keep that budget distinct from structural repair and transport retry.
+implementation planning details. Whether a completed run with failed structural
-Whether a failed execution produces a reusable exchange remains a Decision 1
+validation produces a reusable exchange remains a Decision 1 question; the
-question.
+operational-error decision does not reclassify that validation result.
 
 ### 5. How Are Related Executions And Usage Accounted For?
 
@@ -402,6 +429,8 @@ relationships in continuation details, prepared execution metadata, sequence
 reports, and observations as appropriate. Keep `InspectPrompt`, `InspectProfile`,
 and `InspectBackend` focused on their configured resources. Reuse the existing
 approach to generically renderable inspection data where new details are exposed.
+Any proposed report should demonstrate its consumer value; Decision 4's minimal
+termination contract does not promise a sequence report or response archive.
 
 **Alternative:** introduce a dedicated conversation inspection API. This may
 be useful if a retained exchange needs a richer view, but should be justified