Finalize conversation and execution group documentation

docs/internal/observation.md

@@ -27,6 +27,8 @@ callback. The caller supplies normalized failure metadata; the recorder never
 parses an error string or receives provider bodies, credentials, headers, or
 other content. Events are values with no mutable containers. Callback panics
 propagate to the caller.
+The immediate parent run ID is set before start delivery and is retained as
+selection metadata changes. It describes ancestry, not implicit group membership.
 Resolved prompt and profile IDs are the exact runtime identities selected for
 the invocation, including namespace qualification when supplied by an engine
 view.
@@ -48,6 +50,13 @@ attempts above the first in a generation, and repair generations with at least
 one dispatch. A terminal event is an aggregate and must not be added to its
 attempt events.
 
+An execution group is a zero-ready synchronized collector of explicitly selected
+events. It enrolls by run ID and aggregates each run's first terminal counters and
+presence-aware usage exactly once. Snapshots copy members and totals under one
+lock; terminal coverage and token completeness are distinct. Observer fan-out
+copies the callback slice and invokes callbacks synchronously without holding a
+group lock. No group history, registry, or automatic nested membership exists.
+
 Smoke diagnostics mask inherited execution-recorder state while invoking
 generation or HTTP collaborators. Their private attempt evidence is assembled
 into a `SmokeTestReport`; it does not create ordinary run events or enter an

docs/internal/overview.md

@@ -18,7 +18,7 @@ contributor workflow and validation.
 | `internal/backend` | Holds a defensive, immutable lookup of final backend definitions, including diagnostic metadata, plus capacity policies validated by the configuration adapter. | [Backend registry](../../internal/backend/registry.go) |
 | `internal/configuration` | Loads root and namespaced resources through ConfigKit; validates final values, captures indexed resource views and source-relative prompt content, compiled templates, requirement metadata, identity inventories, backend and presence-aware execution profiles, and the read-only provenance inspection view. | [Typed loader](../../internal/configuration/load.go), [identity listing](../../internal/configuration/listing.go), [internal sources](sources.md#typed-configuration-loading) |
 | `internal/capacity` | Owns engine-local bounded execution admission and FIFO model-generation permits for limited backend IDs, including cancellation-safe waiter removal and client wrapping. | [Internal capacity management](capacity.md) |
-| `internal/domain` | Defines internal framework values for requests, artifacts, prompt definitions, requirement inspection, profiles, execution targets, rendering, generation, validation, and source-neutral smoke diagnostics, and owns source-neutral invariants for shared execution settings, OpenAI-compatible base endpoints, session identifiers, output contracts, and resource-identity syntax and qualification. Source parsing, required fields, other source-specific normalization, defaulting, and boundary-specific error classification remain with their callers. | [Domain declarations](../../internal/domain/domain.go), [requirement values](../../internal/domain/requirements.go), [endpoint invariant](../../internal/domain/endpoint.go) |
+| `internal/domain` | Defines internal framework values for requests, immutable conversation exchanges, artifacts, prompt definitions, requirement inspection, profiles, execution targets, rendering, generation, validation, and source-neutral smoke diagnostics, and owns source-neutral invariants for shared execution settings, OpenAI-compatible base endpoints, session identifiers, output contracts, and resource-identity syntax and qualification. Source parsing, required fields, other source-specific normalization, defaulting, and boundary-specific error classification remain with their callers. | [Domain declarations](../../internal/domain/domain.go), [exchange storage](../../internal/domain/exchange.go), [requirement values](../../internal/domain/requirements.go), [endpoint invariant](../../internal/domain/endpoint.go) |
 | `internal/engine` | Assembles caller-selected configuration into one snapshot, then constructs shared capacity, rendering, validation, generation, repair, the ordinary runner, and the smoke tester for each engine. Immutable namespace views share those collaborators and qualify caller-supplied execution, inspection, and diagnostic selections without rewriting captured references. Built-in engines provide the diagnostic HTTP collaborator; injected-client engines do not. It delegates resource inspection and identity listing directly to the captured configuration rather than the runner. | [Engine assembly](../../internal/engine/engine.go), [internal sources](sources.md#typed-configuration-loading), [internal runner](runner.md) |
 | `internal/generation` | Coordinates frozen built-in HTTP attempts and one-shot injected calls through active backend permits, including bounded status retries, cancellable backoff, ordinary attempt observations, and invocation-local evidence for diagnostics. | [Internal generation coordination](generation.md) |
 | `internal/defaults` | Defines application-neutral framework constants and constructs the default execution target. It contains no CLI, server, or inbound HTTP limits. | [Framework defaults](../../internal/defaults/defaults.go) |
@@ -30,8 +30,8 @@ contributor workflow and validation.
 | `internal/artifact` | Resolves ordinary inline and unrestricted caller-selected file references into copied artifacts with metadata and hashes. | [Internal sources and validation](sources.md) |
 | `internal/validate` | Validates basic, JSON, and JSON Schema output using operating-system filesystem or `fs.FS` schema sources and creates operation-local validation plans with canonical contained schema resources. | [Framework formats](../formats.md#schemas), [internal sources and validation](sources.md) |
 | `internal/llm` | Defines the internal generation boundary and implements outbound OpenAI-compatible chat requests from resolved execution targets, including bounded response decoding, authentication, deadline handling, per-invocation HTTP evidence and built-in diagnostic probes, and ownership of the OpenAI-compatible reserved request-field policy. | [Internal model client](llm.md) |
-| `internal/observation` | Owns invocation-local run IDs, presence-aware usage and phase accounting, and synchronous metadata event delivery for ordinary and claimed prepared runs and generation attempts; smoke diagnostics keep their private evidence outside ordinary observer events. | [Internal execution observation](observation.md) |
-| `internal/usecase` | Selects captured prompts and profiles, enumerates requirements from captured prompt syntax, applies request overrides and completion checks, coordinates ordinary and single-claim prepared execution across rendering, artifact loading, operation-local validation plans, generation, capacity, and bounded repair, and runs explicit smoke diagnostics with private cases, shared generation/capacity, and optional built-in HTTP probes. | [Internal runner](runner.md), [requirement inspection](../../internal/usecase/requirements_inspection.go), [prepared-execution implementation](../../internal/usecase/prepared_execution.go) |
+| `internal/observation` | Owns invocation-local run IDs, presence-aware usage and phase accounting, synchronous metadata event delivery and composition, and explicit terminal-based group aggregation; smoke diagnostics keep their private evidence outside ordinary observer events. | [Internal execution observation](observation.md) |
+| `internal/usecase` | Selects captured prompts and profiles, enumerates requirements from captured prompt syntax, applies request overrides and completion checks, coordinates ordinary and single-claim prepared execution across rendering, artifact loading, operation-local validation plans, generation, capacity, and bounded repair, advances a single conversation branch, and runs explicit smoke diagnostics with private cases, shared generation/capacity, and optional built-in HTTP probes. | [Internal runner](runner.md), [requirement inspection](../../internal/usecase/requirements_inspection.go), [prepared-execution implementation](../../internal/usecase/prepared_execution.go) |
 
 The internal engine assembles these internal components without exposing their
 representations. Consumers depend only on the root facade.

docs/internal/runner.md

@@ -30,6 +30,23 @@ internal callers and tests.
 Each invocation carries its state in request, prepared-run, and result values.
 The runner has no durable run or session store.
 
+Captured exchanges are immutable parent-linked domain values. Each holds only
+its new rendered suffix, final assistant message, and run identities; flattening
+iteratively makes a detached history for preparation or inspection. Preparation
+prepends this history to newly rendered definition messages and appended caller
+messages before computing the rendered hash. Follow-up selection and credentials
+remain those of the new request. Prepared execution retains capture and parent
+references in its single-claim payload, not its durable details; discard clears
+the payload. Completed runs capture the exact final output, including exhausted
+structural repair, while operational errors produce no exchange.
+
+The sequential coordinator uses ordinary facade runs and retains the current
+immutable exchange independently of callback-owned values. Each run releases its
+logical admission lease and finishes observation before application callback
+delivery. Context checks preserve a completed but undelivered result only when
+cancellation is observed before invoking the callback. Coordinator budgets count
+started runs, not transport attempts or structural repairs.
+
 ## Shared Prompt Selection
 
 The internal engine applies each namespace view to slashless caller selections
@@ -124,8 +141,8 @@ profile, or backend:
    schema metadata from it when required;
 2. load and hash input artifacts;
 3. render messages and the prompt-defined session;
-4. apply any direct session ID, then append already-normalized request messages
-   after the rendered definition messages;
+4. apply any direct session ID, then compose captured history, rendered
+   definition messages, and already-normalized request messages in that order;
 5. hash the effective rendered prompt; and
 6. construct the prepared value and preparation timing.