phronomy 0.26.0 → 0.27.0

data/docs/decisions/043-storage-execution-constraint-notifications.md

@@ -0,0 +1,75 @@
+# ADR-043: Storage-Owned Execution Constraint Notifications
+
+The raw fixed-repository/error portions are amended by [ADR-058](058-neutral-storage-primitives.md). Domain ownership and applicable transaction/uncertainty decisions remain in force.
+
+
+**Status**: Accepted
+**Date**: 2026-09-21
+**Refines**: [033-domain-persistence-ownership](033-domain-persistence-ownership.md) and the Beta Backend error contract in [persistence-backends](../persistence-backends.md)
+
+## Problem
+
+InMemory and the SQLite/PostgreSQL reference backends raised `AgentBusyError`
+for stored nonterminal-execution constraints. A storage implementation therefore
+selected a feature lifecycle exception, even though domain repositories already
+owned record conversion and public operation semantics.
+
+## Decision
+
+`Storage::ActiveExecutionConflictError < Storage::ConflictError` identifies only
+a stored nonterminal execution preventing another admission or an idle-only
+operation for the same owner. It contains no Agent/Team class, domain object,
+callback, or new persisted field. Generic duplicate IDs, stale revisions and
+other precondition failures remain ordinary `Storage::ConflictError` values;
+connection errors and uncertain outcomes retain their existing error types.
+
+Raw execution repositories use this subtype from `create_active`, `assert_idle!`,
+and any existing `save` branch that detects the same active-owner constraint.
+Agent and MultiAgent execution repository facades translate only this subtype
+to the existing public `AgentBusyError`, preserving its message and Ruby cause.
+They do not catch every `ConflictError` or reinterpret database exceptions.
+The existing Team public error remains unchanged; choosing a different Team
+lifecycle exception would be a separate API decision.
+
+Constraint detection and the write remain inside the same backend consistency
+boundary. No preflight lookup is moved above the backend. Domain translation
+occurs inside the existing transaction block so the mapped exception still
+causes rollback before commit. SQL statements, lock order, connection binding,
+indexes, persisted records and transaction boundaries are unchanged.
+
+## Compatibility and migration
+
+This intentionally changes the Beta raw Backend error contract. Callers of
+`backend.executions` and `backend.team_executions` must catch the new storage
+subtype instead of `AgentBusyError`. Callers of the domain-facing Persistence,
+Agent and Team APIs continue receiving `AgentBusyError` for that condition.
+
+The core, InMemory and both reference SQL backends are migrated together. Apply
+the core before the new SQL sources; the new backend sources require the new
+storage constant. An old backend that still raises `AgentBusyError` passes
+through an updated domain facade unchanged, but no longer conforms to the new
+raw SPI. There is no fallback alias in Storage or Engine.
+
+The shared backend suite now checks raw notifications separately from domain
+exceptions, including duplicate-ID and stale-revision distinction and rollback.
+The storage isolation guard removes its former Agent lifecycle file exemption.
+
+## Guarantees and limits
+
+| Subject/property | Provider | Failure/boundary | Result |
+|---|---|---|---|
+| One nonterminal execution per stored owner | Existing atomic admission, backend lock/transaction/DB constraint | F2; no X0 | CONDITIONAL on the backend satisfying the existing atomic_admission contract; no new cross-process owner lease |
+| Uncommitted writes roll back when a mapped constraint escapes | Existing storage transaction with domain conversion inside its block | F0/F2; no X0 | YES for an ordinary known pre-commit constraint failure; not a claim about uncertain commits |
+| Caller-facing busy errors retain their meaning | Feature repository translation of the dedicated subtype | F0/F2; no X0 | YES for the documented domain repository paths; unrelated conflicts are not converted |
+
+This change adds no F1 outcome reconciliation, F4 rehydration, external-effect
+rollback or exactly-once guarantee. The eight repository names and Agent
+watermark that ADR-033 leaves in Storage remain an explicit intermediate state.
+Removing the exception dependency does not make the entire SPI domain-neutral.
+
+## Rejected alternatives
+
+- Move `AgentBusyError` into common definitions or alias it from Storage.
+- Translate every `ConflictError` into a busy error.
+- Check active state in the domain facade before performing a separate write.
+- Migrate only InMemory and silently leave the SQL raw contract inconsistent.

data/docs/decisions/044-agent-default-and-one-shot-composition.md

@@ -0,0 +1,106 @@
+# ADR-044: Agent Default and One-Shot Composition
+
+**Status**: Accepted on the architecture refactoring branch
+**Date**: 2026-09-21
+**Refines**: [038-responsibility-based-source-layout](038-responsibility-based-source-layout.md)
+and [040-configuration-default-composition](040-configuration-default-composition.md)
+
+## Problem
+
+`Agent::Base` selected the concrete default with `Persistence.in_memory`.
+`Agent.run_once`, defined beside Agent lifecycle namespace loading, also selected
+and constructed Persistence. Both files therefore depended on the higher-level
+Persistence composition API, but for different reasons.
+
+Default selection is an injected construction dependency of Agent execution.
+One-shot execution is itself a composition API. Treating both as lower-level
+Agent execution obscured those responsibilities. Replacing one-shot storage with
+the configured shared Persistence would change isolation and existing behavior.
+
+## Decision
+
+1. Agent owns the private `Agent::DefaultPersistence` construction contract. A
+   zero-argument factory is bound once and frozen during application loading.
+   `Base` invokes it only after the explicit `persistence:` and configured
+   `configuration.persistence` values have both been excluded, preserving their
+   existing truthy fallback order. It neither caches the constructed instance
+   nor writes it to configuration. Subclasses consume the same binding.
+2. `runtime_composition/agent_defaults.rb` selects `Persistence.in_memory` in
+   that factory. Binding does not invoke it, create settings, or start Runtime.
+   The binding is not a public plugin registry, an alternative application
+   configuration mechanism, or a new Runtime service locator. Runtime and
+   configuration resets do not replace or reinstall it.
+3. `agent/composition/run_once.rb` owns the actual `Agent.run_once` definition.
+   It remains `Phronomy::Agent.run_once`, with the same parameters, forwarding,
+   result, and exception behavior. It constructs fresh ephemeral Persistence on
+   every call even when global Persistence is configured. It does not consume
+   Base's fallback factory. Rejecting simultaneous `on_event:` and a block still
+   occurs before storage or Agent construction.
+4. `agent/api/agent.rb` retains `StreamEvent` and lifecycle extension loading.
+   It has no delegate to the higher-level one-shot implementation. The
+   application entry explicitly requires the namespace extensions, factory
+   binding, and one-shot method definition after Zeitwerk setup and global
+   configuration access installation. The composition directory and binding
+   file are ignored by Zeitwerk because they wire existing constants rather
+   than introduce matching public namespaces. Agent execution never requires
+   the application entry or either composition file.
+5. Normal application loading, first constant access, repeated requires, and
+   eager loading retain constant identity and exactly one lifecycle extension.
+   Explicit namespace loading also handles the internal unbound factory
+   contract having been loaded first. Arbitrary partial loading of framework
+   implementation files remains outside the public application-loading API.
+
+## Compatibility and guarantees
+
+The public constructor and one-shot API, event callback paths, stored records,
+transaction boundaries, Agent ownership, and shutdown behavior are unchanged.
+The existing API snapshot is not regenerated. It does not cover the `run_once`
+singleton signature, which is checked explicitly along with real invocation,
+creation-time context/Knowledge, and both forms of event listener.
+
+The factory's exception propagates unchanged through the existing Agent
+creation/ownership handling. Classified failures such as ConfigurationError
+release the reservation; unclassified failures such as IOError retain the
+existing fail-closed recovery-required reservation. Do not make every factory
+failure retryable as a side effect of moving default selection. Existing
+explicit Persistence injection works without invoking the factory.
+
+This is source dependency inversion, not removal of the runtime construction
+call: `Base` still invokes the bound factory when a default is needed. The
+one-shot implementation still depends explicitly on Agent and Persistence.
+Both selecting and invoking the one-shot composition remain above execution.
+The private factory slot is immutable after boot; returned Persistence
+instances remain separate, mutable storage instances.
+
+No F1 uncertain-commit reconciliation, F4 recovery guarantee, external-effect
+rollback, or exactly-once guarantee is added. The previous in-memory durability
+limits remain. Runtime retains created Agents according to existing ownership
+rules; moving `run_once` does not introduce new cleanup or lifetime behavior.
+
+## Dependency interpretation
+
+Remove `agent -> persistence/api` and `agent/api -> persistence/api`.
+Add explicit composition dependencies from `runtime_composition` to Agent and
+Persistence and from `agent/composition` to Persistence. One-shot composition
+also calls the injected Agent definition's `create` method; namespace declarations
+and injected calls do not count as static constant-reference edges. The
+`Tools::Agent` call to `Agent.run_once` now targets its actual definition in
+`agent/composition`. Treat the new Agent composition directory as B1; it is
+not a new Ruby namespace.
+The internal Base-to-factory reference remains within Agent's directory.
+
+The remaining reverse dependency `agent -> workflow/execution` is the separate
+worker-input classification change (E). This change does not resolve all
+directory/file cycles, Storage's domain-specific repository names, or the
+Engine FSM terminal persistence responsibilities.
+
+## Verification
+
+Cover fallback precedence, fresh instances and subclass construction, resets,
+classified failure/retry and unclassified fail-closed behavior, supplied-factory
+independence, normal/preloaded/eager
+loading, one-shot isolation from global Persistence, argument/result/exception
+identity, context/Knowledge forwarding, callback conflict ordering, and both
+event listener forms. Run existing Agent ownership/event tests, default and
+integration suites, style, API snapshot, RBS, and annotation gates. Verify
+examples against the changed core without modifying their public call sites.

data/docs/decisions/045-worker-input-restriction-ownership.md

@@ -0,0 +1,100 @@
+# ADR-045: Worker Input Restriction Ownership
+
+**Status**: Accepted on the architecture refactoring branch
+**Date**: 2026-09-21
+**Refines**: [024-event-loop-single-writer-agent-runtime](024-event-loop-single-writer-agent-runtime.md)
+and [038-responsibility-based-source-layout](038-responsibility-based-source-layout.md)
+
+## Problem
+
+Tool authorization snapshots exclude framework-managed live objects from value
+data and application behavior handles. `ToolInvocation` identified those objects
+by enumerating 18 Agent, Workflow and execution types. The Agent-side boundary
+therefore depended on concrete Workflow types solely to reject them as input.
+
+Moving that list into a shared helper would retain the wrong ownership. Treating
+all frozen objects or all callables as safe would weaken the existing boundary;
+rejecting all opaque application objects would break ACS-11.
+
+## Decision
+
+1. The execution boundary owns the internal, methodless
+   `Concurrency::WorkerInputRestricted` marker in `engine/concurrency/`.
+   It declares that instances of an owning type are excluded from the existing
+   authorization worker value/behavior boundary. It contains no feature list,
+   registration mechanism, class-name matching, constant lookup or callbacks.
+2. Each previously restricted type directly includes the marker in its own
+   definition. WorkflowContext includes it as a module so implementations and
+   their subclasses retain the restriction. Other classes pass it through
+   normal Ruby inheritance. Nested types are marked only when they were in
+   the original rejection set; marking FSMSession does not mark every nested
+   class, so its EventSink opts in separately.
+3. `ToolInvocation` checks only `is_a?(Concurrency::WorkerInputRestricted)`.
+   Recursive Hash-key/value and Array traversal, String copying/freezing,
+   exception type/messages and behavior-handle checks remain unchanged.
+   Frozen marked instances remain restricted.
+4. Each owner explicitly requires the small marker file. The marker can load
+   alone without Agent, Workflow, Runtime or application bootstrap. Normal,
+   preloaded, repeated and eager application loading retain marker identity
+   and do not create settings or start Runtime. The marker adds no methods to
+   public APIs; the existing API snapshot is not regenerated.
+
+## Existing restriction inventory
+
+| Owner | Types that include the marker |
+|---|---|
+| Agent execution/state | `Agent::Base`, `AgentRoot`, `AgentExecution`, `AgentInvocation`, `ToolInvocation`, `JournalProjection`, `ExecutionCoordinator` (all under Agent) |
+| Agent capability | `Agent::Context::Capability::Base` |
+| Workflow | `Workflow`, `WorkflowRunner`, `WorkflowContext` |
+| Execution | `Runtime`, `TaskResult`, `EventLoop`, `FSMSession`, `FSMSession::EventSink` |
+| Concurrency | `Concurrency::CancellationToken`, `Concurrency::OffloadPool` |
+
+These are the same 18 root types as the previous predicate. Regression tests
+retain this inventory to prevent an accidentally unmarked existing type from
+becoming admissible. Future framework types subject to this boundary must opt
+in at their owning definition and add an input-boundary test.
+
+## Scope and compatibility
+
+This marker is internal classification, not a public safety certification or
+serialization SPI. It does not reject all Runnable implementations, all
+Phronomy objects, class/module objects, or every worker command. Other operation
+snapshots and OffloadPool APIs are unchanged.
+
+Application-owned opaque values and behavior handles remain permitted by
+identity. Their instance variables, callback receivers and closure captures
+are not traversed. Applications remain responsible for worker safety under
+the existing ACS-11 contract. The marker is not a security sandbox.
+
+The ancestry of the 18 types intentionally gains one methodless module.
+Public methods, constructors, value copying, events, ownership, cancellation,
+transaction boundaries, persistence formats and exception behavior are
+unchanged. No F1 uncertain-commit reconciliation, F4 recovery, external-effect
+rollback or exactly-once guarantee is added.
+
+## Dependency interpretation
+
+The Agent-to-Workflow execution dependency disappears. Workflow types and
+Agent types instead refer downward to an execution-boundary contract.
+Existing Engine types refer within the execution foundation. Explicit
+marker loading adds require edges; it does not move feature references into
+the marker. A methodless include is still a real source dependency.
+
+This completes the specific A-E reverse-dependency proposals. It does not
+eliminate all directory/file cycles, Storage's domain-specific repository
+names, or FSMSession's Workflow terminal persistence responsibilities.
+
+## Verification
+
+Verify the 18-type inventory for direct instances and subclasses, frozen and
+unfrozen, root values, Hash keys/values, nested Arrays and all three behavior
+handle names. Exercise actual authorization command capture for Workflow,
+WorkflowRunner and WorkflowContext via context/policy/facts/requirement paths,
+and reject a marked value returned from a facts callable. Preserve opaque
+application data, callables and unmarked Runnable/Outcome values.
+
+Also verify a new marked type without changing the evaluator, standalone and
+normal/preloaded/eager loading, no Workflow type references in Agent source,
+and the marker's absence of feature knowledge. Run the existing snapshot
+boundary suite, full and integration tests, style, unchanged API snapshot,
+RBS, annotations and examples against the candidate core.

data/docs/decisions/046-agent-responsibility-layout-and-shared-records.md

@@ -0,0 +1,110 @@
+# ADR-046: Agent Responsibility Layout and Shared Records
+
+**Status**: Amended on the architecture refactoring branch
+**SharedState amendment**: [053-shared-state-coordination-ownership](053-shared-state-coordination-ownership.md) moves the deferred multi-Agent coordination responsibility to MultiAgent. The original placement below is retained as history.
+**Continuation amendment**: [047-recovered-execution-continuation-contract](047-recovered-execution-continuation-contract.md) removes the remaining Recovery-to-private-control calls and shares session registration. The original extraction scope below is retained as history.
+**Date**: 2026-09-21
+**Refines**: [038-responsibility-based-source-layout](038-responsibility-based-source-layout.md)
+and [024-event-loop-single-writer-agent-runtime](024-event-loop-single-writer-agent-runtime.md)
+
+## Problem
+
+Agent's direct directory contained 41 files with unrelated responsibilities.
+Recovery also obtained the ordinary execution coordinator solely to invoke its
+private record encoder and content writer. RecoverySupport mixed recovery
+vocabulary, durable reads, and construction of live invocations.
+
+Moving files alone does not resolve that coupling. Moving transaction decisions
+into a shared encoder would instead give it too many responsibilities.
+
+## Decision
+
+Apply and verify the changes in two stages: source placement first, then shared
+record generation and restoration responsibilities.
+
+### Source placement
+
+Collapse the following directories with Zeitwerk, preserving existing Agent
+constant names and the application entry point `require "phronomy"`:
+
+| Directory | Responsibility |
+| --- | --- |
+| `agent/lifecycle/` | Agent identity, ownership and fallback construction contract |
+| `agent/execution/` | Invocation, phase transitions, admission and execution coordination |
+| `agent/tool_execution/` | Tool invocation, authorization, approval and interception |
+| `agent/context_assembly/` | Candidate selection, budgeting and Provider context materialization |
+| `agent/journal/` | Canonical execution records and their projection |
+| `agent/handoff/` | Agent-owned Handoff contracts, state and execution coordination |
+| `agent/recovery/` | Durable recovery classification, resolution and live restoration |
+
+The three files below `recovery_coordinator/` move with their owning class into
+`recovery/recovery_coordinator/`. That directory retains its real nested Ruby
+namespace; it is not independently collapsed. Existing API, composition,
+context contracts, capabilities, concerns and persistence directories retain
+their responsibilities. `base.rb`, `async_event_api.rb` and `shared_state.rb`
+remain directly under Agent. SharedState's multi-Agent orchestration is a
+separate future ownership decision, not evidence of generic shared data.
+
+Update relative requires and source-reading regression guards. Do not provide
+old-path forwarding shims: arbitrary implementation-file requires are not a
+public partial-loading API. Existing constant identities, method signatures,
+ancestry, lifecycle extension installation and stored class names are preserved.
+
+### Shared record generation
+
+`Agent::RuntimeRecordEncoder` under `execution/` receives execution facts, the
+Agent identity, root generation, context eligibility and an existing transaction.
+It writes content and returns JournalRecord and LLMCallRecord values. Ordinary
+execution and recovery resolution both call it directly. It has no Agent live
+object, coordinator, Runtime lookup, transaction opener, journal append, execution
+save, commit/reconciliation decision or task settlement responsibility.
+The encoder belongs to execution because it interprets Tool interception and
+Provider settlement; the journal value/projection directory must not depend on
+Tool execution solely to classify those facts.
+
+Keep call sequence numbering, interception-as-success, abandoned call recording,
+Tool message duplicate detection, context eligibility, content formats and
+canonical-value failure messages. The caller still owns the transaction and
+F1 outcome reconciliation. Encoding is not a pure function because it writes
+content using that caller-owned transaction.
+
+### Saved context and live restoration
+
+`Agent::SavedContextReader` under `context_assembly/` reads persisted manifests,
+materializes projections, and obtains saved Provider output/usage. Execution
+preparation reconciliation, Handoff and Recovery consume this common reader.
+Reading occurs in the same worker/caller preparation phase as before, outside
+EventLoop state application.
+
+`Agent::InvocationRestorer` under `recovery/` constructs live Chat, AgentInvocation
+and ToolInvocation state from already-materialized facts. Suspended and resolved
+continuations share the same invocation/chat construction sequence. Tool status,
+approval facts, listener, invocation mode, coordination configuration, cancellation
+and message order are preserved. It does not perform persistence reads or decide
+which continuation to execute. RecoverySupport retains recovery metadata and
+subject vocabulary rather than forwarding to the extracted helpers.
+
+## Compatibility and limits
+
+No public API or extension SPI is changed, and the existing API snapshot is not
+regenerated. These three helpers are internal (`@api private`). Removed methods
+on the internal RecoverySupport module and ExecutionCoordinator are not public
+application contracts. No persistence schema, durability level, exactly-once
+claim, cancellation rule, external effect replay rule or ownership rule changes.
+
+ExecutionCoordinator still owns several operations and remains large. Recovery
+still calls its private continuation/terminal entry points; this decision only
+removes the record-generation and content-writing coupling. Moving directories
+reveals previously internal cycles; counts across different grouping schemes are
+not directly comparable. No claim of eliminating all Agent cycles is made.
+
+## Verification
+
+Verify the placement-only checkpoint before extracting helpers. Run ordinary
+and recovery tests, F1 response-loss and I/O-boundary checks, restart/output-filter
+coverage, full and integration suites, API byte comparison, RBS, annotations,
+style and examples. Compare the complete encoded records and captured content
+against the baseline under fixed timestamps and IDs, including success, structured
+output, failure, interception, abandoned calls, duplicate Tool messages and
+context eligibility. Verify gem packaging includes every moved/new source and
+loads without the old implementation paths.

data/docs/decisions/047-recovered-execution-continuation-contract.md

@@ -0,0 +1,116 @@
+# ADR-047: Recovered Execution Continuation Contract
+
+**Status**: Accepted on the architecture refactoring branch
+**Date**: 2026-09-21
+**Refines**: [046-agent-responsibility-layout-and-shared-records](046-agent-responsibility-layout-and-shared-records.md),
+[024-event-loop-single-writer-agent-runtime](024-event-loop-single-writer-agent-runtime.md)
+and [028-preparing-recovery-replay-contract](028-preparing-recovery-replay-contract.md).
+
+## Problem
+
+Recovery chose a continuation from saved facts but also registered its Agent FSM
+and reached five private ExecutionCoordinator entry points through `send`.
+Initial execution, approval resume, framework Tool recovery and resolved-result
+recovery independently wired parent session completion. Recovery therefore had
+to understand the execution owner's terminal and session implementation.
+
+## Decision
+
+### Recovery describes the continuation; execution validates and starts it
+
+Use the execution owner's existing `deliver_on_event_loop` boundary with two
+internal command types:
+
+- `RecoverPreparationCommand` identifies the installed execution and expected
+  revision, with separate execution and load completion observers.
+- `ContinueRecoveredCommand` supplies that identity/revision, a semantic
+  continuation, the restored invocation, its materialized projection, the
+  execution observer and a failure when applicable.
+
+Recovery still classifies saved facts, requests factual resolution, materializes
+saved inputs off EventLoop and restores live invocations on EventLoop. It no
+longer registers an Agent FSM, supplies FSM state/event names, owns its terminal
+callback, or names private execution-control methods.
+
+The execution owner validates EventLoop affinity, coordinator/Agent ownership,
+current revision, nonterminal execution and absence of an installed FSM. It
+also checks the continuation's saved phase and invocation identity before any
+replacement, admission change or session dispatch. A mismatched continuation
+must not replace or release another lifecycle's state. Stale initial preparation
+fails both observers without releasing that newer lifecycle.
+
+The execution owner interprets the six continuation intents:
+
+| Intent | Execution-owned action |
+| --- | --- |
+| Approval rejection | Resume the saved rejected approval and its Tool sessions |
+| Framework Tool batch | Resume the authorized framework Tool sessions |
+| Saved framework calls | Enter ordinary Provider-result handling |
+| Saved Provider output | Enter ordinary Provider-result/output-filter handling |
+| Saved Tool results | Enter ordinary Tool-result/follow-up handling |
+| Resolved failure | Enter the ordinary terminal persistence barrier |
+
+Delivery is synchronous within the existing EventLoop turn. This is an internal
+handover, not an additional queued turn or an Offload operation. Commands are
+process-local controls, not persisted records or an application extension SPI.
+The existing private terminal/preparation methods remain private.
+
+### One owner wires Agent and Tool sessions
+
+`Agent::ExecutionSessionRunner` owns parent session registration, resumed session
+construction, resumed child registration and parent completion wiring. Ordinary
+initial execution, approval resume and recovery use it. It reports completion
+through an execution-owner-supplied callback; the owner delivers an internal
+`SessionFinishedCommand` to itself, including the concrete FSM incarnation and
+invocation. This preserves Handoff coordinator dispatch without making the
+runner depend on the coordinator's concrete class or command definitions.
+
+The coordinator retains admission, completion observers, stale-callback checks,
+physical-quiescence waiting, terminal snapshot creation and persistence. The
+runner performs no persistence I/O, saved-fact interpretation, retry decision or
+caller-facing result settlement. Parent registration precedes child registration
+as before. Its live Runtime/callback handles carry the existing worker-input
+restriction marker.
+
+## Compatibility and failure model
+
+Public API snapshots, RBS contracts, stored formats, recovery subjects, approval
+decisions and external replay eligibility remain unchanged. A restored rejected
+approval now registers its internal execution observer at the same pre-session
+boundary used by the other continuation intents; terminal settlement still
+occurs only through the coordinator's existing barrier.
+
+Under [018-durability-guarantees-and-failure-model](018-durability-guarantees-and-failure-model.md):
+
+| Subject / property | Provider and condition | Failure / boundary | Result |
+| --- | --- | --- | --- |
+| Current live execution: reject stale or foreign continuation before state replacement | Execution-owner identity/revision/FSM validation on EventLoop | F2/F3; no X0 dispatch by rejected command | YES |
+| Caller completion follows the authoritative terminal outcome | Existing coordinator terminal barrier and quiescence checks; runner reports FSM completion only | F0/F1/F3; existing external effects remain outside transaction | YES under the existing Persistence contract |
+| Confirmed recovery state: resume the same logical execution | Recovery classification/materialization plus the execution owner; replay-safe preparation or resolved external facts are required | F1/F4; X0 may have occurred before recovery | CONDITIONAL on the existing operation-specific recovery contract |
+| Arbitrary external-effect exactly-once execution | No new external idempotency or transaction protocol | F1/F4 across X0 | NO new guarantee |
+
+The command boundary is process-local validation, not cross-process exclusion.
+No broader exactly-once or automatic replay claim follows from this change.
+
+## Verification and remaining work
+
+Exercise rejected commands on a real EventLoop/ExecutionRegistry: wrong owner,
+coordinator, revision, installed FSM, terminal state, invocation identity and
+continuation phase. Verify both preparation observers and a late session
+completion. Existing recovery, approval, F1/F4, output-filter, cancellation,
+Handoff and full-suite tests cover valid dispatch and terminal behavior.
+
+ExecutionCoordinator still owns preparation, causal barriers, admission and
+terminal operations. This decision removes Recovery's private control coupling
+and duplicated session wiring; it does not complete decomposition of that class.
+Tool snapshot restoration's direct field coupling, SharedState ownership,
+Storage domain responsibilities and Workflow terminal persistence remain
+separate work.
+
+## Tool restoration amendment (2026-09-22)
+
+[052-tool-invocation-restoration-ownership](052-tool-invocation-restoration-ownership.md)
+completes the direct Tool field coupling item above. ToolInvocation owns saved
+state application; Recovery retains decoding and identity matching. The original
+scope and historical remaining-work statement above are preserved. SharedState,
+Storage domain responsibilities and Workflow terminal persistence remain open.

data/docs/decisions/048-dispatch-preparation-worker-ownership.md

@@ -0,0 +1,120 @@
+# ADR-048: Dispatch Preparation Worker Ownership
+
+**Status**: Accepted on the architecture refactoring branch
+**Date**: 2026-09-22
+**Refines**: [024-event-loop-single-writer-agent-runtime](024-event-loop-single-writer-agent-runtime.md),
+[042-feature-owned-execution-state](042-feature-owned-execution-state.md)
+and [047-recovered-execution-continuation-contract](047-recovered-execution-continuation-contract.md).
+
+## Problem
+
+ExecutionCoordinator mixed EventLoop ownership and application result delivery
+with the Persistence operations required before Provider/Tool dispatch. Moving
+whole methods alone would leave the Provider operation mixing control steps,
+metadata representation, transactions, application policy and materialization.
+Its worker also used input/result types nested under the execution owner, which
+would create a reverse dependency after extraction.
+
+## Decision
+
+### The execution owner captures, submits and applies
+
+ExecutionCoordinator keeps current Agent/invocation/FSM validation, operation
+capture, Offload submission, Ready delivery, semantic revision/phase checks,
+snapshot acknowledgment and physical Provider/Tool dispatch. These responsibilities
+remain on their existing threads and in their existing order. Ordinary and
+recovered execution keep the same owner and continuation contract.
+
+`Agent::DispatchPreparation` owns four internal worker operations:
+
+- `prepare_provider`: stage the next call, encode runtime records, prepare the
+  Context, commit prerequisites and materialize the confirmed input.
+- `prepare_tools`: encode runtime records and save pending Tool recovery facts.
+- `reconcile_provider`: read back the execution, classify the exact saved state
+  and restore input only for the confirmed intended result.
+- `reconcile_tools`: read back and classify the exact saved state.
+
+The worker returns values and never schedules work, advances the live Registry,
+acknowledges invocation snapshots, starts Provider/Tool calls, or settles Tasks.
+It does not refer back to ExecutionCoordinator or its private methods. The
+Coordinator creates the worker with the existing Agent service context and its
+Persistence instance. Agent hooks, ContextAssembler and coordination preparation
+retain their existing service contracts; this is not removal of all Agent
+references. The worker is marked `WorkerInputRestricted` because it retains
+framework service handles. Per-operation inputs/results remain local variables.
+
+### Preserve the operation-specific persistence boundaries
+
+Provider preparation has two transactions with application hooks/ContextPolicy
+between them. The first can encode content-addressed records but does not advance
+Execution. The second rechecks the local Agent watermark, finalizes the Manifest
+and saves the Execution. Cancellation is checked after Policy and before that
+second transaction. Tool preparation retains its single transaction.
+
+Only an exception in the guarded save transaction, after an intended result was
+captured and outside the existing known-failure classes, becomes an unknown
+outcome. Encoding failures and application Policy failures do not become an
+uncertain execution save. Post-commit materialization failure returns the saved
+Execution together with an error, so the owner still applies/acknowledges the
+known committed snapshot before reporting setup failure.
+
+Reconciliation compares both revision and complete execution contents. It returns
+`committed` only for the intended state, `not_committed` only for the exact original
+state, and `conflict` otherwise. Read failures propagate. It never retries the
+write or authorizes dispatch by itself. Terminal and coordination-wait
+reconciliation remain separate and retain their different acceptance criteria.
+
+The watermark rule remains owned by Persistence's `assert_agent_watermark!`.
+The worker and the remaining initial-preparation code only map captured Root
+fields to that contract; neither implements a second version of the rule.
+
+### Names describe the purpose; bodies describe its immediate steps
+
+The Provider entry reads as stage, encode, prepare Context, commit, materialize.
+Private helpers own metadata keys, record fields and value construction. The
+Coordinator's dispatch entry reads as validate, capture, submit. Transaction
+and rescue scopes stay explicit in the operations that own them. We do not use
+one-line delegation chains or a generic execution framework to reduce line counts.
+
+### Types belong to the operation boundary
+
+DispatchPreparation owns Provider/Tool commands, reconciliation commands and
+their results. ExecutionCoordinator retains its existing eight nested constant
+paths as aliases to these types; Ready messages and live delivery remain in the
+Coordinator. Its private uncertainty exception constant is also an alias.
+
+The aliases preserve construction, members and shared type identity, but the
+canonical Ruby class names now belong to DispatchPreparation. These are internal,
+process-local types, not persisted records or public extension contracts. This
+change makes no promise to preserve their former reflected names. Product API
+snapshots, saved formats, public exception contracts and recovery eligibility
+remain unchanged.
+
+## Failure model and verification
+
+Using [018-durability-guarantees-and-failure-model](018-durability-guarantees-and-failure-model.md):
+
+| Subject / property | Provider and condition | Failure / boundary | Result |
+| --- | --- | --- | --- |
+| Current execution: apply only a matching preparation result | Existing EventLoop owner, revision and FSM checks | F2/F3; no new X0 dispatch from stale results | YES, unchanged |
+| Provider/Tool dispatch: confirmed durable prerequisites precede physical dispatch | Operation-specific commit/readback plus owner apply; conforming Persistence is required | F0/F1; this barrier precedes the next X0 call | CONDITIONAL on confirming the intended durable state and current live ownership |
+| Application Policy: no preparation transaction held while it executes | Explicit separation of encoding, Policy and save | F0/F3; application-defined side effects remain its responsibility | YES for the framework-owned transaction boundary |
+| Confirmed records: restart readability and continuation | Existing Persistence and Recovery contracts | F4; replay or resolution depends on the external operation | CONDITIONAL, no broader resumption guarantee |
+| Arbitrary external-effect exactly-once execution | No new external protocol or distributed exclusion | F1/F4 across X0 | NO new guarantee |
+
+Existing causal-durability tests now invoke the owning worker instead of private
+Coordinator persistence methods. Architecture guards inspect the complete worker,
+including helpers, while keeping checks on EventLoop apply. Behavioral probes
+exercise Policy outside transactions, post-Policy watermark/cancellation checks,
+encoding-response loss, post-commit materialization failure, reconciliation read
+failure, materialization failure after confirmation, and same-revision content
+conflicts. Existing valid Agent/Tool execution, Recovery and Handoff suites cover
+the production wiring. Public API, loading and gem-content checks remain required.
+
+## Remaining work
+
+Initial preparation, approval snapshot isolation, and normal/Handoff outcome
+persistence are separate stages. The approval Hash/Mutex is not moved into this
+worker. The existing Coordinator and Handoff terminal machinery are unchanged.
+This stage improves responsibility and abstraction boundaries; it does not claim
+to remove every Agent dependency cycle or finish Coordinator decomposition.