Record remaining conversation capture decisions

docs/roadmap/conversation-continuation.md

@@ -1,8 +1,8 @@
 # Conversation Continuation And Application-Directed Interaction
 
-Status: feature roadmap under discussion; accepted directions and remaining
+Status: behavioral decisions accepted; ready for API and staged implementation
-open decisions are identified below. No implementation is authorized by this
+planning. No implementation is authorized by this document. Exact public types
-document. Recommendations remain proposals unless explicitly marked accepted.
+and signatures remain for implementation planning.
 
 ## North Star: Content-Neutral, Generally Useful Capabilities
 
@@ -71,7 +71,7 @@ single-use execution capability; continuation needs its own semantics.
 
 ### 1. What Does A Captured Exchange Contain?
 
-**Status: core decision accepted; remaining lifecycle details open.** Capture
+**Status: accepted; exact capture API remains for implementation planning.** Capture
 represents the logical conversation. Structural-output repair attempts and
 corrective instructions are internal execution details, not conversation turns.
 
@@ -83,10 +83,56 @@ instructions from the logical conversation. This supplies reusable context for
 subsequent turns while keeping transport attempts and structural repair separate
 from application turns. It also matches Audita's requested history.
 
-Capture is opt-in. A continuation would append its rendered follow-up messages
+**Accepted capture availability:** when capture is requested, follow the ordinary
-and final response to produce a new exchange, leaving the source exchange and
+distinction between a completed result and an operational error:
-other branches unchanged. Previously rendered history would not require the
+
-original input files or templates to be rendered again.
+| Execution outcome | Capture behavior |
+| --- | --- |
+| Completed response that satisfies its output contract | Capture the logical exchange. |
+| Completed response with failed structural validation, including repair exhaustion | Capture the final returned response; preserve the failed validation status in the ordinary result. |
+| Operational error with no completed result | Produce no new exchange; the preceding exchange remains usable. |
+| Completed response followed by cancellation before coordinator callback delivery | Preserve the undelivered response under Decision 4's accepted optional-result behavior. |
+
+Capture does not imply validation success or application acceptance. The
+coordinator delivers completed results with their ordinary validation status;
+the application decides whether to stop or continue, potentially using another
+output contract. Failed structural validation is not reclassified as an
+operational error. Only the final returned content enters the logical history,
+never intermediate structural-repair responses or corrective instructions.
+
+**Accepted opt-in behavior:** support capture per execution through both ordinary
+and prepared execution. Ordinary execution returns the captured exchange
+alongside its usual result. For prepared execution, retain the capture choice
+with the prepared handle and create the exchange when that exact execution
+completes. Preparation alone produces no completed exchange because it has no
+assistant response. A continuation operation implies capture so it can produce
+the next reusable exchange.
+
+Construct capture from the request actually executed. Consumers must not need
+to reconstruct history or pair independently prepared data with a response.
+An ordinary request option is the preferred API direction; separate capture
+methods are also viable. Select the precise representation during API planning.
+
+**Accepted ownership and lifetime:** a captured exchange is an immutable,
+reusable snapshot held by the caller. Continuing it appends the rendered
+follow-up messages and final response to produce a new exchange, leaving the
+source exchange and other branches unchanged. Independent branches may share
+their starting exchange. Inspection values cannot mutate retained history.
+Previously rendered history does not require the original input files or
+templates to be rendered again.
+
+A completed exchange retains no backend admission lease, direct credential,
+or execution callback. Ordinary Go memory management handles its lifetime when
+references are released; it adds no `Close` or `Discard` lifecycle. The existing
+single-use prepared execution lifecycle remains separate.
+
+**Accepted engine independence:** another engine instance in the same process
+may continue a captured exchange. The receiving engine resolves the new prompt,
+profile, output contract, and credentials under Decision 2's rules. It does not
+need the originating engine to rerender prior messages. This permits retaining
+conversations while an application rebuilds its engine with new configuration.
+It does not imply persistence, restartable sessions, serialization for later
+resumption, or cross-process portability.
 
 **Alternative considered, not selected:** retain the corrective messages and
 responses that led to the final output. This provides more execution detail,
@@ -96,11 +142,21 @@ Fine-grained execution tracing is outside this feature's purpose. Existing
 attempt and usage observations remain separate from logical conversation
 content; this decision adds no requirement to capture internal repair text.
 
-**Details to settle:** capture availability after structural validation
+**Additional alternatives considered, not selected:**
-exhaustion or an operational failure; how callers request capture for ordinary
+
-and prepared runs; and the ownership and engine-binding of captured exchanges.
+- Capture only responses that satisfy their output contract. This would offer a
-The request's “full final assistant response” should refer to the content
+  validated-output condition but unnecessarily restrict continuing from otherwise
-supported by PromptKit, without silently adding a raw provider-envelope API.
+  available conversation content. Applications retain that choice.
+- Bind exchanges to their originating engine. Prepared executions need ownership
+  of execution-specific state, but captured conversation data has no equivalent
+  requirement under the selected fresh-execution settings model.
+- Use a mutable conversation object. This would make appending convenient but
+  require explicit copying or forking to preserve independent branches. Immutable
+  snapshots fit the selected branch behavior directly.
+
+**Implementation planning:** select the opt-in API and exchange representation
+within these behaviors. The request's “full final assistant response” refers to
+content supported by PromptKit, without adding a raw provider-envelope API.
 
 ### 2. How Are Follow-Up Execution Settings Selected?
 
@@ -141,7 +197,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 public types and accounting details remain open.** Provide
+**Status: accepted; exact public types remain for implementation planning.** 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
@@ -262,8 +318,9 @@ or unavailable, and retains those meanings in its own state. Further corrections
 can start separate coordinators from the same initial exchange; accepted sibling
 corrections and other branches remain with Audita.
 
-Both sketches omit application-specific error handling and depict normal turn
+Both sketches omit application-specific error handling, including checks for
-progression. The final permitted response follows the same callback path as
+failed structural validation before schema-specific decoding, 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, cancellation around callback delivery, and a minimal termination result.
 The sketches do not imply an archive of responses in that result: applications
@@ -404,10 +461,11 @@ considered and not selected: its additional metadata is unnecessary for the
 demonstrated minimal contract.
 
 **Implementation planning:** select exact types for next actions, outcomes, and
-the optional result under these accepted behaviors. Whether a completed run with
+the optional result under these accepted behaviors. As selected in Decision 1,
-failed structural validation produces a reusable exchange remains a Decision 1
+a completed run with failed structural validation produces a reusable exchange
-question; the operational-error decision does not reclassify that validation
+when capture is requested and retains its ordinary validation result. That
-result.
+result follows the normal response callback path, subject to cancellation;
+the operational-error behavior does not reclassify it.
 
 ### 5. How Are Related Executions And Usage Accounted For?
 
@@ -505,8 +563,10 @@ capabilities require separate consumer justification.
 
 ## Proposed Delivery And Validation
 
-Resolve the decisions above before selecting exact public signatures or writing
+All six behavioral decisions are accepted. Remaining work is API and staged
-an implementation plan. The recommended sequence is:
+implementation planning: exact types and signatures, capture opt-in syntax,
+message assembly details, placement of relationship metadata, and the concrete
+inspection representation. The recommended delivery sequence is:
 
 1. Deliver capture and independent continuation through the public facade,
    allowing Audita to remove its reconstruction and prefix-verification work.
@@ -522,6 +582,13 @@ coverage should establish:
 
 - The selected conversation history when the initial run needed structural
   repair, including use of its full final assistant content.
+- Capture of the final returned response after structural validation fails,
+  preserving its ordinary validation status through the coordinator callback.
+  Operational failures with no completed result create no new exchange.
+- Capture opt-in through ordinary and prepared execution, using the executed
+  snapshot and producing no completed exchange during preparation alone.
+- Continuation through another engine instance in the same process, retaining
+  prior content while applying the receiving engine's follow-up configuration.
 - Continuation after the original input files change or disappear, without
   altering the captured history.
 - Independent branches retaining their own history and outcomes.