Record zero-turn budget and callback cancellation decisions

docs/roadmap/conversation-continuation.md

@@ -175,12 +175,12 @@ 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:** callback cancellation boundaries, exact request/stop and
+**Details to settle:** exact request/stop and outcome types, and remaining
-outcome types, and error/report semantics belong to Decision 4. That decision
+error/report semantics belong to Decision 4. That decision records accepted
-records the accepted normal delivery of the last permitted response. Execution
+response delivery, zero-turn budget behavior, and cancellation boundaries.
-association and usage accounting belong to Decision 5. The sketches below
+Execution association and usage accounting belong to Decision 5. The sketches
-illustrate the selected responsibility split; they do not settle the remaining
+below illustrate the selected responsibility split; they do not settle the
-public contracts.
+remaining public contracts.
 
 #### Illustrative Consumer Sketches
 
@@ -263,18 +263,20 @@ 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. Callback errors, zero-turn budgets,
+earlier responses, as accepted in Decision 4. That decision also defines zero-turn
-and cancellation around delivery remain open there. Completed work must not be
+budgets and cancellation around callback delivery; remaining operational-error
-mistaken for application acceptance of its content.
+details are open there. 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 and exhaustion decision accepted; remaining
+**Status: normal response delivery, exhaustion, zero-turn budgets, and callback
-outcome and failure details open.** The coordinator uses content-neutral next
+cancellation decisions accepted; remaining outcome and failure details open.**
-actions and distinguishes application-directed completion from exhaustion.
+The coordinator uses content-neutral next actions and distinguishes
+application-directed completion from exhaustion.
 
 **Accepted normal flow:** deliver each completed response once through the
 ordinary application callback, including the last permitted response. If the
@@ -286,14 +288,54 @@ 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 and operational-failure delivery semantics remain open;
+callbacks. Cancellation can interrupt normal delivery as specified below;
-this normal-flow decision does not settle those cases. `Stop` and other API
+remaining operational-failure delivery semantics are open. `Stop` and other API
 spellings remain illustrative until public 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
 callback but requires separate consumer processing of the final response.
 
+**Accepted zero-turn behavior:** with an active context, invoke the initial
+callback once even when the additional-turn budget is zero. The callback receives
+the starting exchange and knows that no additional turns remain; this is not
+delivery of a newly generated response. It can use existing application state
+without repeating earlier assessment.
+
+- `Stop` produces application-directed completion.
+- Requesting another turn produces exhaustion without executing the request.
+- Returning an error produces an operational failure, subject to the
+  cancellation checks below.
+
+Zero bounds coordinator-driven continuation executions, not work inside the
+application callback. The callback can still consult data or make model calls.
+Applications wanting to disable all such work can skip invoking the coordinator.
+The alternative of treating zero as an immediate no-op with no callback is not
+selected: it would introduce special behavior and would not distinguish an
+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
+the context error identity. Preserve completed-turn information already obtained
+by the coordinator in the returned report without implying that the application
+processed or accepted it. This does not 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.
+PromptKit checks the context again after the callback returns and before starting
+another execution. It does not forcibly terminate callback code. Thus ordinary
+response delivery is once per completed turn during normal progression, while
+cancellation can interrupt that progression. Preserving available completed work
+on interruption does not create a separate final-response processing path during
+normal budget exhaustion.
+
+The alternative of invoking the callback after cancellation with a canceled
+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
 the interaction should stop, separately from reporting an operational error.
 PromptKit need not know whether the application is repairing, investigating,
@@ -313,12 +355,12 @@ 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;
 the operational-error contract remains to be selected.
 
-**Details to settle:** zero-turn budgets; cancellation before callback delivery,
+**Details to settle:** exact next-action and outcome types; remaining operational
-during callbacks, and before subsequent execution; exact next-action and outcome
+error and result-plus-error behavior beyond the accepted interruption report;
-types; result-plus-error behavior; and what consumes an additional-turn budget
+and what consumes an additional-turn budget when preparation or generation
-when preparation or generation fails. Keep that budget distinct from structural
+fails. Keep that budget distinct from structural repair and transport retry.
-repair and transport retry. Whether a failed execution produces a reusable
+Whether a failed execution produces a reusable exchange remains a Decision 1
-exchange remains a Decision 1 question.
+question.
 
 ### 5. How Are Related Executions And Usage Accounted For?