Frame conversation roadmap around content-neutral capabilities

docs/roadmap/conversation-continuation.md

@@ -1,8 +1,40 @@
-# Conversation Continuation And Application-Directed Repair
+# Conversation Continuation And Application-Directed Interaction
 
 Status: proposed feature roadmap; open decisions await discussion. No
 implementation is authorized by this document. Recommendations below are not
-accepted contracts.
+accepted contracts, except for the guiding principle explicitly recorded below.
+
+## North Star: Content-Neutral, Generally Useful Capabilities
+
+**Accepted direction:** evaluate each capability for its usefulness across
+different downstream applications. PromptKit must be able to implement it and
+explain its value without assuming or inferring the meaning of the content
+passed through prompts and responses.
+
+PromptKit can own conversation and execution mechanics: captured messages,
+continuations, independent branches, execution relationships, budgets,
+cancellation, observations, and usage. Applications own the interpretation of
+responses and their reasons for choosing the next action. Repair, analysis,
+clarification, and branching exploration are examples of consumer workflows
+that could use the same mechanisms.
+
+Coordination and looping remain open questions. Neither is presumed necessary
+or excluded. Assess their value as generally useful capabilities, rather than
+as an implementation of Audita's repair loop. A coordinator, if selected,
+would execute application-directed interactions without needing to understand
+why the application requests another turn or stops.
+
+Apply two questions to proposed public concepts and implementation machinery:
+
+1. Can their value be explained using conversation and execution concepts alone?
+2. Can different applications use them without translating their domain into
+   repair-specific concepts?
+
+Audita supplies concrete evidence of need and acceptance examples; its workflow
+does not define PromptKit's abstraction. Terms such as rejected candidate,
+accepted revision, and withdrawal belong to the consuming application. This
+direction concerns the new capabilities and does not rename or expand
+PromptKit's existing structural-output repair functionality.
 
 ## Purpose And Scope
 
@@ -16,12 +48,12 @@ The proposed capabilities are:
 - Capture a rendered request and its final assistant content, then continue it
   using ordinary configured prompts without reconstructing the original request.
 - Allow independent continuations from one captured exchange.
-- Coordinate bounded revisions for one branch using application-supplied
+- Consider coordination and bounded looping using application-supplied next
-  assessment and follow-up request construction.
+  actions and follow-up requests.
 
 Continuation has direct value by removing consumer capture, reconstruction,
-prefix comparison, and history assembly. The revision coordinator could also
+prefix comparison, and history assembly. A coordinator could also remove
-remove repeated lifecycle work, provided its public contract remains small.
+repeated lifecycle work, if its general value justifies its public contract.
 Audita would continue owning candidate selection, domain validation, feedback
 meaning, branch scheduling, accepted sibling proposals, and transcript changes.
 Its domain-specific repair code would not move wholesale into PromptKit.
@@ -42,8 +74,9 @@ the complete sequence of provider requests, including structural repair.
 content, roles, and cache metadata, followed by the final assistant content
 returned by the run. An initial run that needed structural repair would retain
 its final content without adding the internal corrective instructions to the
-logical conversation. This matches Audita's requested history and keeps
+logical conversation. This supplies reusable context for subsequent turns while
-transport attempts and structural repair separate from application turns.
+keeping transport attempts and structural repair separate from application
+turns. It also matches Audita's requested history.
 
 Make capture opt-in. A continuation would append its rendered follow-up messages
 and final response to produce a new exchange, leaving the source exchange and
@@ -88,71 +121,81 @@ resolution, explicit overrides, credential lifetime, and the ordering of
 follow-up definition messages and caller-appended messages. Preserve authored
 roles rather than silently rewriting follow-up system or developer messages.
 
-### 3. Where Does Application Assessment Run In The Capacity Lifecycle?
+### 3. Should PromptKit Coordinate Turns, And Where Does Application Work Run?
 
-**Status: open.** Select a lifecycle that permits application validators to
+**Status: open.** Evaluate whether a coordinator or loop provides generally
-call the same engine and backend, including with capacity limited to one.
+useful behavior beyond continuation primitives. If selected, determine its
+scope and a lifecycle that permits application callbacks to call the same
+engine and backend, including with capacity limited to one.
 
 The current [run flow](../internal/runner.md#run-flow) retains logical admission
 through structural validation and repair. Releasing an active generation permit
 alone does not release that admission lease.
 
-**Recommendation:** coordinate completed executions. Finish a revision run and
+**Recommendation:** assess the value across repair, analysis, and branching
-release its admission lease before invoking application assessment. Each later
+conversation examples before choosing the abstraction. If PromptKit provides
-revision receives ordinary admission. The coordinator itself holds no backend
+coordination, compose completed executions: finish a turn and release its
-capacity while awaiting application work. This reuses the existing execution
+admission lease before invoking application work. Each later turn receives
-machinery and supports validators that make their own model calls.
+ordinary admission. A coordinator would hold no backend capacity while awaiting
+application work. This reuses existing execution machinery and permits
+callbacks to make their own model calls without interpreting their purpose.
 
-**Alternative:** extend the existing structural-repair lifecycle with application
+**Alternative:** provide continuation and observation primitives while leaving
-callbacks and explicit lease release/reacquisition. This could share more loop
+looping to consumers. This keeps PromptKit's API smaller, but may leave repeated
-code, but would complicate admission ownership and combine operations with
+execution and accounting coordination downstream. Compare the actual consumer
-different schemas and validation responsibilities. It would still have to meet
+work under both approaches. Extending the structural-repair loop is another
-the same nested-call requirement.
+possible implementation route, but would require changing lease ownership and
+decoupling it from repair-specific assumptions.
 
-**Details to settle:** callback cancellation boundaries and the sequence of
+**Details to settle:** whether to provide coordination, looping, or both; scope
-request building, execution, response interpretation, and assessment. The
+over a single branch versus multiple branches; callback cancellation boundaries;
-coordinator should remain scoped to one branch; applications retain decisions
+and the sequence of request construction, execution, and application decisions.
-about scheduling branches and stopping other work after a failure.
+Applications retain the meaning of those decisions and policy for stopping
+other work after a failure.
 
-### 4. How Are Assessment Outcomes And Failures Represented?
+### 4. How Are Application Next Actions And Execution Outcomes Represented?
 
-**Status: open.** Define how acceptance, another requested revision, withdrawal,
+**Status: open.** Subject to Decision 3, define content-neutral next actions and
-unavailable assessment, exhaustion, and interruption are distinguished.
+distinguish application-directed completion, budget exhaustion, interruption,
+and operational failure.
 
-**Recommendation:** use explicit application assessment outcomes separately
+**Recommendation:** let the application request another turn or indicate that
-from operational errors. Applications interpret responses and feedback;
+the interaction should stop, separately from reporting an operational error.
-PromptKit records the selected disposition and coordinates subsequent work.
+PromptKit need not know whether the application is repairing, investigating,
-Accept supplied initial rejection findings without repeating the original
+or exploring. Permit starting from an existing exchange and application state
-assessment. A revised candidate becomes accepted only after application
+without forcing the application to repeat earlier work.
-assessment accepts it.
 
-Return sequence diagnostics that preserve completed attempts when work stops,
+Return execution diagnostics that preserve completed work when an interaction
-while clearly distinguishing the latest candidate from an accepted candidate.
+stops. A completed model call does not imply application acceptance of its
+content. Audita would map its own acceptance, rejection, withdrawal, and
+unavailable-assessment outcomes to the selected generic controls.
 Cancellation and operational errors should retain useful Go error identities.
 Applications decide whether a stopped branch affects independent work.
 
-**Alternative:** use an error-only assessment callback, treating nil as
+**Alternative:** use callback errors to signal ordinary termination as well as
-acceptance and typed errors as rejection, withdrawal, or unavailability. This
+operational failure. This can reduce the number of result types, but makes
-looks smaller, but overloads errors with ordinary domain decisions and makes
+normal control flow harder to distinguish from failure. Compare it against a
-continuation policy harder to understand.
+small explicit next-action result without introducing domain-specific statuses.
 
-**Details to settle:** the small outcome vocabulary, who supplies each outcome,
+**Details to settle:** next-action and outcome vocabulary, callback/result types,
-callback/result types, result-plus-error behavior, zero-budget behavior, and
+result-plus-error behavior, zero-budget behavior, and what consumes an
-what consumes an additional-revision attempt when preparation or generation
+additional-turn budget when preparation or generation fails. Keep such a budget
-fails. Keep this budget distinct from structural repair and transport retry.
+distinct from structural repair and transport retry. If coordination is left
+to consumers, limit this decision to continuation execution outcomes.
 
 ### 5. How Are Related Executions And Usage Accounted For?
 
-**Status: open.** Define accounting for the initial exchange, each revision,
+**Status: open.** Define accounting for the initial exchange, each continuation,
 its structural repairs and transport retries, and model calls made by
-application validators.
+application callbacks, whether or not PromptKit supplies a coordinator.
 
 The current [observation boundary](../internal/observation.md) keeps nested
 invocations independent. A callback's arbitrary model calls cannot simply be
-assumed to belong to the enclosing revision's totals.
+assumed to belong to the enclosing interaction's totals.
 
 **Recommendation:** preserve independent run accounting and add explicit
-relationships between a sequence, its revision attempts, and associated runs.
+relationships between exchanges, branches, and associated runs, with sequence
+relationships if coordination is selected.
 Choose a small association mechanism, such as a scoped observation facility or
 explicit execution references, so consumers need not rebuild lifecycle tracking.
 Shared initial work should be referenced by branches and counted once when
@@ -160,16 +203,16 @@ reporting the combined operation. Report available usage with its existing
 presence/completeness meaning; do not promise complete cost accounting.
 
 **Alternative:** have PromptKit automatically capture every nested run during an
-assessment callback. This minimizes explicit association but can include
+application callback. This minimizes explicit association but can include
 unrelated work and changes the existing invocation-isolation boundary.
-Another simpler option is to report revision usage only and let applications
+Another simpler option is to report continuation usage only and let applications
-attach validator accounting; that leaves more work in Audita and needs checking
+attach callback accounting; that leaves more work downstream and needs checking
-against its stated reporting requirement.
+against Audita's stated reporting requirement.
 
-**Details to settle:** association of concurrent validator calls, observer
+**Details to settle:** association of concurrent callback calls, observer
 composition, failure-path diagnostics, and which totals include which child
-executions. A revision budget bounds revision attempts, not all provider calls
+executions. A turn budget would bound continuation attempts, not all provider
-performed by structural repair, transport retries, or application validators.
+calls performed by structural repair, transport retries, or application work.
 
 ### 6. Where Should Continuation Inspection Live?
 
@@ -199,11 +242,14 @@ an implementation plan. The recommended sequence is:
 
 1. Deliver capture and independent continuation through the public facade,
    allowing Audita to remove its reconstruction and prefix-verification work.
-2. Build the single-branch revision coordinator on that capability, reusing
+2. If selected after evaluating general usefulness, build coordination and/or
-   ordinary execution, validation, capacity, and observation machinery.
+   bounded looping on that capability, reusing ordinary execution, validation,
+   capacity, and observation machinery.
 
 Use [Audita's acceptance scenarios](audita-request.md#suggested-delivery-and-acceptance-scenarios)
-as the consumer checks. Additional proposed coverage should establish:
+as consumer checks, alongside analysis and branching-conversation examples that
+exercise the same APIs without repair-specific concepts. Additional proposed
+coverage should establish:
 
 - The selected conversation history when the initial run needed structural
   repair, including use of its full final assistant content.