Record accepted execution group decisions

docs/roadmap/conversation-continuation.md

@@ -1,9 +1,9 @@
 # Conversation Continuation And Application-Directed Interaction
 
-Status: continuation and coordinator behavioral decisions accepted; optional
-execution groups accepted as a separable addition with open decisions below.
-No implementation is authorized by this document. Exact public types and
-signatures remain for implementation planning.
+Status: continuation, coordinator, and optional execution-group behavioral
+decisions accepted; ready for API and staged implementation planning. Execution
+groups remain independently deliverable. No implementation is authorized by this
+document. Exact public types and signatures remain for implementation planning.
 
 ## North Star: Content-Neutral, Generally Useful Capabilities
 
@@ -571,9 +571,10 @@ capabilities require separate consumer justification.
 
 ## Separable Addition: Optional Execution Groups
 
-**Status: accepted direction; the four decisions below remain open.** Audita's
-follow-up request identifies a distinct need: a validator call can belong to the
-same logical operation as a continuation without extending its conversation.
+**Status: all four group decisions accepted; exact public API remains for
+implementation planning.** Audita's follow-up request identifies a distinct
+need: a validator call can belong to the same logical operation as a continuation
+without extending its conversation.
 Conversation ancestry describes which exchange supplies history; accounting
 membership describes which executions the application chooses to report together.
 Neither relationship implies the other.
@@ -601,86 +602,110 @@ and do not add terminal totals to the attempts they already summarize.
 
 ### Group Decision 1: How Does An Application Select Membership?
 
-**Recommendation:** first evaluate a group collector compatible with the existing
-observer API. Attaching it explicitly to a request would enroll the observed run;
-a coordinator could receive an explicit selection for its own continuation runs.
-Callback calls would still require their own selection. This reuses the existing
-source of execution facts and avoids a second accounting path.
+**Status: accepted.** Start with an observer-compatible collector using existing
+execution observations. Applications explicitly attach the collector to selected
+ordinary requests. Prepared requests retain the selection, with membership
+beginning when execution emits observations; preparation alone, discarded handles,
+and failed claims do not enroll a run through observations.
 
-The design must allow the application to keep its existing observer alongside
-the group. Specify ordinary and prepared execution attachment and coordinator
-propagation without inheriting membership into arbitrary nested calls. Preparation
-alone is not an executed member; discarded handles and failed claims do not
-currently emit execution observations.
+Coordinator selection explicitly covers its continuation runs. Calls made inside
+application callbacks join only through their own explicit selection. There is
+no implicit context-based membership or automatic enrollment of the starting
+exchange's run.
 
-**Alternative:** explicit group options on requests and the coordinator, backed
-by ordinary observation internally. This makes membership clearer and separates
-it from application event delivery, but adds public API plumbing. Choose after
-sketching the smallest workable interfaces for ordinary, prepared, coordinated,
-and callback-initiated calls. Do not select a context-based implicit scope.
+Preserving an application's existing observer alongside one or more group
+collectors is supported usage. Provide a small observer-composition helper so
+consumers need not rebuild event forwarding throughout their adapters. Preserve
+ordinary synchronous delivery and panic behavior; do not add asynchronous queues,
+panic recovery, or guaranteed delivery to later observers after an earlier
+observer panics. Interrupted delivery can leave accounting incomplete.
+
+**API planning:** sketch ordinary, prepared, coordinated, and callback-initiated
+usage with the collector and composition helper. Explicit group fields remain a
+fallback if those sketches demonstrate awkward usage; they would still use the
+same observation machinery internally. The observer-compatible approach is the
+selected starting point, not an unresolved product decision.
 
 ### Group Decision 2: What Is The Group's Lifetime?
 
-**Recommendation:** expose summary snapshots from a caller-held group, with no
-mandatory close or wait operation. Applications already own the work and decide
-when to read or discard the group. Support concurrent selected executions and
-summary reads without imposing serial scheduling.
+**Status: accepted.** Provide detached, internally consistent summary snapshots
+from a caller-held group, supporting concurrent selected executions and snapshot
+reads. Reading or modifying a snapshot must not alter the collector or other
+snapshots. No mandatory close, seal, or wait lifecycle is introduced. Applications
+own execution scheduling and decide when to read or discard the group.
 
-A snapshot must distinguish observed terminal runs from members whose terminal
-facts are not yet available. A missing terminal event can reflect ongoing work
-or interruption such as a panic; it is not evidence of zero usage or success.
-Do not promise terminal observations beyond the existing observation contract.
+Distinguish runs with terminal observations from observed runs without them.
+Missing terminal observations remain visible as incomplete accounting; the group
+does not infer whether the cause is active work, interrupted observer delivery,
+or something else. Preserve the existing observation contract rather than
+promising additional terminal delivery.
 
-**Alternative:** an explicit seal/close or wait lifecycle could provide a fixed
-membership boundary or completion wait. It adds lifecycle rules and overlaps
-with application orchestration; defer unless a consumer demonstrates that need.
+“All observed members have terminal observations” does not mean “the application
+operation is complete.” Additional runs may join later, and PromptKit cannot know
+whether the application selected every relevant call. The application decides
+when a snapshot represents its final report.
+
+**Alternative considered, not selected:** a close/seal or wait lifecycle could
+provide fixed membership or a completion wait, but would duplicate application
+coordination without a demonstrated need.
 
 ### Group Decision 3: May Groups Overlap?
 
-**Recommendation:** allow a run to belong to more than one explicitly selected
-group, counting each run identity once within each group. This accommodates both
-an operation summary and a broader application summary without requiring a
-hierarchical group model. Overlapping group totals are not necessarily additive.
+**Status: accepted.** Allow explicit membership in multiple groups, counting each
+run identity once within each group. Groups are independent accounting views;
+overlapping totals are not generally additive.
 
-**Alternative:** require one group per run. This simplifies membership plumbing,
-but restricts useful accounting views and makes applications rebuild the broader
-aggregation themselves. There is no demonstrated need for that restriction.
-Do not add group nesting, automatic parent membership, or group scheduling merely
-to support overlap.
+An application can obtain both operation-level and overall summaries by attaching
+the respective collectors to each selected execution. This requires no group
+nesting, inherited membership, scheduling, or facility for merging overlapping
+summaries.
+
+**Alternative considered, not selected:** one group per run would simplify
+membership plumbing but restrict useful views and force consumers to rebuild
+broader aggregation. There is no demonstrated need for that restriction.
 
 ### Group Decision 4: Which Facts Does A Summary Expose And Aggregate?
 
-**Recommendation:** start with member run identities, terminal-observation status,
-and a small selection of existing execution counters and presence-aware usage
-totals. Select the exact fields during API design; avoid a comprehensive new
-report schema or new outcome hierarchy. Summaries describe execution facts, not
-application acceptance or monetary cost. Summed run durations, if included,
-must not be presented as elapsed group time when runs overlap.
+**Status: accepted.** The initial summary exposes:
 
-Prefer aggregating one terminal event per run. Terminal observations already
-summarize retries, structural repairs, reported usage, and failure-path facts,
-including executions that return no ordinary result. This is simpler than
-reconstructing those totals from attempt events. Preserve each usage field's
-known/completeness distinctions and expose missing terminal coverage separately,
-so a total over finished members cannot imply complete accounting for all members.
+- Member run identities and terminal-observation coverage.
+- Existing execution counters: provider attempts, transient retries, and
+  structural repairs.
+- Available token-usage totals with their known/completeness information.
 
-**Alternative:** accumulate attempt events for live partial totals, reconciling
-terminal events without counting the same work twice. This exposes more facts
-before completion or after a missing terminal event, but needs additional
-reconciliation rules. Prefer terminal-based totals unless live attempt accounting
-has demonstrated value. Whichever representation is selected, absent evidence
-must not become a known zero, and terminal summaries must never be added to their
-already-counted attempts.
+Aggregate one terminal observation per run, without reconstructing totals from
+attempt events or adding terminal summaries to the attempts they summarize.
+Terminal observations already include retries, structural repairs, reported
+usage, and available failure-path facts, including executions that return no
+ordinary result. Summaries describe execution facts, not application acceptance
+or monetary cost.
+
+Distinguish terminal coverage from usage completeness. A terminal observation
+can itself report incomplete usage. Conversely, fully reported usage for every
+finished member does not establish complete accounting when another observed
+member lacks a terminal observation. Preserve existing per-field usage semantics
+and expose missing terminal coverage separately. For example, two finished runs
+may supply a useful known subtotal while a third observed run without a terminal
+event leaves group accounting incomplete. Absence of evidence must not become
+known zero. Exact field names and representation remain for API planning.
+
+**Alternatives considered, not selected for the initial implementation:** live
+attempt-level totals would expose additional partial facts but require reconciling
+attempt and terminal observations. Applications can consume ordinary events for
+progress displays. Duration aggregation is also omitted absent a concrete need;
+if added later, summed execution durations must be distinguished from elapsed
+group time. Neither requires expanding the initial summary into a comprehensive
+report schema or a new outcome hierarchy.
 
 ## Proposed Delivery And Validation
 
-The six continuation/coordinator behavioral decisions are accepted. Their
-remaining work is API and staged implementation planning: exact types and
-signatures, capture opt-in syntax, message assembly details, placement of
-relationship metadata, and the concrete inspection representation. Execution
-groups have four open decisions above and a separate delivery track; resolving
-or implementing them is not a prerequisite for continuation. The recommended
-continuation delivery sequence is:
+All six continuation/coordinator decisions and all four execution-group decisions
+are accepted. No product-level decisions remain open. Remaining work is API and
+staged implementation planning: exact types and signatures, capture opt-in syntax,
+message assembly details, placement of relationship metadata, the concrete
+inspection representation, and collector/composition and summary API shapes.
+Execution groups retain a separate delivery track; their implementation is not a
+prerequisite for continuation. The recommended continuation delivery sequence is:
 
 1. Deliver capture and independent continuation through the public facade,
    allowing Audita to remove its reconstruction and prefix-verification work.
@@ -689,8 +714,8 @@ continuation delivery sequence is:
    both consumer sketches against the selected public contracts to verify that
    the same mechanism removes useful repeated work in each application.
 
-Plan execution groups independently after resolving their open decisions,
-reusing ordinary observations and preserving existing application observers.
+Plan execution groups independently under the accepted decisions, reusing
+ordinary observations and preserving existing application observers.
 They can ship separately without changing the coordinator termination contract.
 
 Use [Audita's acceptance scenarios](audita-request.md#suggested-delivery-and-acceptance-scenarios)
@@ -725,10 +750,13 @@ coverage should establish:
 Execution-group validation should separately cover explicit ordinary, prepared,
 coordinator, and callback membership; unrelated nested calls remaining outside
 the group; independent ancestry and membership; concurrent collection alongside
-an existing application observer; failure-path terminal facts; unavailable and
-explicit-zero usage; missing terminal observations; and no attempt/terminal
-double counting. If overlapping groups are selected, verify once-per-run counting
-within each group without implying that overlapping totals can be added.
+an existing application observer; detached, internally consistent snapshots;
+failure-path terminal facts; unavailable and explicit-zero usage; missing terminal
+coverage distinct from usage completeness; and no attempt/terminal double counting.
+Verify once-per-run counting within overlapping groups without implying that
+their totals can be added. Check that new members can join after a snapshot with
+full terminal coverage and that observer composition retains ordinary synchronous
+delivery and panic behavior.
 
 These are planning targets, not new implemented guarantees. Keep additional
 mechanisms and constraints tied to the selected decisions and demonstrated