From 85dae9b443a25a0621fb34bdfe30b8d3720ffc5e Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 13 Nov 2026 17:13:33 +0000 Subject: [PATCH] Record accepted execution group decisions --- docs/roadmap/conversation-continuation.md | 176 +++++++++++++--------- 1 file changed, 102 insertions(+), 74 deletions(-) diff --git a/docs/roadmap/conversation-continuation.md b/docs/roadmap/conversation-continuation.md index 14e9520..d2cb3b4 100644 --- a/docs/roadmap/conversation-continuation.md +++ b/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