phronomy 0.25.0 → 0.27.0

data/docs/decisions/051-execution-outcome-worker-ownership.md

@@ -0,0 +1,151 @@
+# ADR-051: Execution Outcome 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),
+[030-agent-handoff-domain-and-durable-responsibility](030-agent-handoff-domain-and-durable-responsibility.md),
+[047-recovered-execution-continuation-contract](047-recovered-execution-continuation-contract.md)
+and [050-approval-resume-snapshot-and-commit-ownership](050-approval-resume-snapshot-and-commit-ownership.md).
+
+## Problem
+
+ExecutionCoordinator owned both EventLoop execution control and Offload result
+persistence. HandoffExecutionCoordinator overrode outcome selection and depended
+on its parent's transaction helpers. Extracting only one side would preserve
+that hidden dependency or accidentally change Handoff precedence. Moving the
+long bodies unchanged would also leave persistence policy mixed with individual
+record fields.
+
+## Decision
+
+### Select and persist outcomes in operation workers
+
+`Agent::ExecutionOutcomeCommitter#commit_outcome` selects completion, failure,
+approval suspension or owned-child waiting from a captured command. It handles
+persistence exceptions through the existing operation-specific readback rules.
+`Agent::HandoffOutcomeCommitter` specializes that selection and atomic Source
+transfer, sharing ordinary completion, failure and suspension persistence.
+Handoff selection retains its separate callback/error/suspension/transfer order;
+it does not acquire the ordinary worker's child-coordination wait branch.
+
+HandoffExecutionCoordinator retains its class identity and inheritance, but now
+only selects the Handoff worker. This selection is internal, not a public SPI.
+Coordinator captures input, submits the worker, validates the returned revision
+and session, applies live state and delivers results. Worker code never calls
+back into Coordinator. Command state and intermediate results remain local to
+one operation; workers hold only Agent service context and Persistence.
+
+Agent context is still required by the existing coordination hook, error
+translation, saved Manifest reader and transcript materializer. This is not a
+claim that all Agent references or dependency cycles have been removed.
+`WorkerInputRestricted` marks both worker types; it is not a recursive validator
+of arbitrary application-owned values.
+
+### Keep transactions visible in the purpose-level methods
+
+`commit_completed` encodes completion records, appends Journal, saves Execution
+and coordination, advances Root and materializes the caller-facing transcript
+inside one transaction, then constructs the result. Record fields and repository
+arguments belong to its helpers. Transcript materialization stays inside the
+transaction so failure rolls back the transition.
+
+`commit_failed_outcome` persists audit-only records and the translated failure.
+The Context revision stays unchanged because none of those records is a Context
+candidate. Completion and Handoff advance Context only if the appended records
+contain a candidate. Suspension retains its records in Execution working state,
+advances Root to suspended and does not append Journal or advance Context.
+
+`commit_handed_off` validates Source routing and cancellation, persists projected
+Context, transfers routing to a deterministic Target execution ID, and saves
+Source Journal, Execution and Root in one transaction. Target definition lookup
+uses the transaction view; the existing saved Manifest reader keeps its service
+context. Target completion/failure stabilizes routing inside its own existing
+terminal transaction. No Provider/Tool dispatch or application delivery moves
+into these workers.
+
+### Preserve the distinct readback contracts
+
+| Operation | Existing confirmation rule after an exception | Consequence |
+| --- | --- | --- |
+| Ordinary/Handoff terminal | Same Agent, terminal Execution, expected revision + 1; then load saved Root, Journal and result | Reuse the persisted outcome; do not write a second terminal transition |
+| Child-coordination wait | Complete saved Execution payload equals the intended waiting record | Return that nonterminal wait; active status alone does not establish a match |
+| Approval suspension | It is nonterminal, so terminal readback does not confirm it | Propagate uncertain completion to the owner |
+
+Terminal confirmation is deliberately not changed to DispatchPreparation's
+full intended-payload comparison. Missing, active, mismatched or unreadable
+results do not authorize another write. Readback errors retain their existing
+propagation behavior. Recovered success retains the existing smaller result
+shape; recovered failures use `RecoverySupport.error_from_failure`, including
+its generic Phronomy::Error representation. This extraction does not normalize
+those results or introduce a stronger commit-certainty protocol.
+
+### Preserve EventLoop result authority and delivery
+
+The owner still waits for physical work quiescence before terminal persistence.
+A stale result changes no live state, admission or Task. Completed/failed/Handoff
+results release ownership and deliver their existing events before settling
+waiters. Suspension retains admission and leaves the original Task pending;
+exact observers receive the existing approval-required failure. Child waiting
+releases ownership and fails waiters with recovery required.
+
+A worker error for ordinary execution retains recovery_required admission and
+pending waiters. The existing coordination-metadata error path releases the
+owner and fails waiters. Those branches are not merged into unconditional cleanup.
+Live Handoff request/Manifest delivery handles remain outside the worker command.
+
+### Internal types
+
+ExecutionOutcomeCommitter owns `Command`, `Outcome`, `TerminalView` and
+`HandoffTerminalView`. Coordinator retains its previous constant paths as aliases
+to the same classes. All four member lists stay unchanged; their canonical Ruby
+names change. TerminalDelivery and TerminalCommitReady remain owner-local.
+These types are internal and are not serialized by class name. Public API, saved
+schemas, Agent/Handoff Coordinator identity and caller selection remain unchanged.
+
+## Guarantees and verification
+
+Using [ADR-018](018-durability-guarantees-and-failure-model.md):
+
+| Subject / property | Provider | Failure / boundary | Result |
+| --- | --- | --- | --- |
+| Terminal or Handoff transition atomicity (G5), stale write rejection (G8) | Existing transaction and repository CAS | F0/F2; no new framework X0 | CONDITIONAL on conforming Persistence backend |
+| No second terminal write after uncertain response | Operation-specific worker readback and owner recovery path | F1; no new worker X0 | YES; no stronger outcome-certainty guarantee |
+| Current execution alone may apply worker results | Existing EventLoop owner/revision/session guards | F2/F3 and delayed completion | YES within the same Runtime ownership contract |
+| Logical continuation from saved Source/Target state (G4) | Existing Handoff recovery and exact Target identity | F4; later execution can cross X0 | CONDITIONAL on existing recovery contracts |
+| Cross-process exclusion (G7), external duplicate prevention (G9), exactly once (G10) | No new protocol added | F1/F2/F4 across X0 | NO new guarantee |
+
+Behavior tests exercise completion/rejection, failure categories, suspension,
+transaction rollback, Root CAS, response loss and readback mismatches/failures,
+child waiting, atomic Source transfer, routing conflict/cancellation and Target
+completion/failure. Existing suites cover physical quiescence, stale results,
+callback policy, approval recovery and durable Handoff recovery. Unit fault
+injections do not represent real process loss or live external service failures.
+Architecture guards now inspect the actual workers and disallow repository
+reloads in Coordinator without the old terminal-helper exceptions.
+
+## Owner-control review (2026-09-22)
+
+The fifth stage keeps one execution owner and makes its remaining result paths
+read as validation, state application and continuation/delivery. Preparation
+recovery separates failed-outcome settlement from session restart. Approval
+resume separates committed-state installation and tracing from FSM entry.
+Terminal results retain visible outcome selection while private methods handle
+the distinct waiting, suspension, completion, Handoff and failure deliveries.
+Only the identical execution/admission release is shared across terminal paths.
+Initial preparation snapshot construction is named explicitly; start/resume
+admission flags, submission flags and their rescue decisions remain together.
+
+No transaction, authority condition, failure policy, public type or class owner
+changes. Direct Ready delivery tests run on the real EventLoop/ExecutionRegistry
+and check stale-result isolation, state-before-notification, notification-before-
+settlement, fallback waiters, suspension, uncertainty and recovery/resume failure
+boundaries. These tests also pass against the preceding implementation, documenting
+preserved behavior rather than a new contract. F0/F1/F3 are injected locally;
+no new X0 operation or stronger F4 guarantee is claimed.
+
+## Remaining work
+
+The execution-owner decomposition and final readability review are implemented.
+Tool restoration, SharedState, Storage domain responsibilities and Workflow
+terminal ownership remain separate work items. Further owner splitting needs a
+concrete responsibility or failure-boundary reason; file length alone is not one.

data/docs/decisions/052-tool-invocation-restoration-ownership.md

@@ -0,0 +1,92 @@
+# ADR-052: Tool Invocation Restoration Ownership
+
+**Status**: Accepted on the architecture refactoring branch
+**Date**: 2026-09-22
+**Refines**: [046-agent-responsibility-layout-and-shared-records](046-agent-responsibility-layout-and-shared-records.md)
+and [047-recovered-execution-continuation-contract](047-recovered-execution-continuation-contract.md).
+
+## Problem
+
+InvocationRestorer decoded saved Tool batches and directly assigned
+ToolInvocation's status, result, authorization decision and approval evidence.
+Moving restoration into its own module in ADR-046 left that knowledge of another
+object's representation intact. ADR-047 explicitly retained it as separate work.
+A change to ToolInvocation's state representation therefore required Recovery to
+track its instance variables as well as the saved format.
+
+## Decision
+
+Keep the existing classes and introduce the internal
+`ToolInvocation#restore_state!(status:, result: nil, approval_item: nil)` operation.
+It is Ruby-public for the Recovery caller and classified `@api private`; it is
+not an Application extension SPI. Its input is materialized semantic state,
+not an Execution record or a persistence repository.
+
+InvocationRestorer retains saved snapshot key normalization, Tool Call and Tool
+lookup, construction of ordinary or missing-Tool invocations, and matching the
+approval item by invocation ID. It converts the saved status to a Symbol and
+passes the saved result and matched approval item to the newly constructed
+ToolInvocation. No ToolInvocation instance variable is assigned by Recovery.
+The separate AgentInvocation batch-ID assignment is outside this change.
+
+ToolInvocation owns the supported-state dispatch and approval evidence copy:
+
+| Saved state | Existing behavior retained |
+| --- | --- |
+| awaiting_approval | Validate arguments unless already terminal, restore require_approval and the waiting state |
+| authorized | Validate arguments unless already terminal, restore allow and the authorized state |
+| completed | Restore the saved result, including nil or false, and completed state |
+| rejected | Restore rejection and its decision |
+| failed | Restore the existing generic Tool preflight failure |
+| cancelled | Restore cancellation |
+| Other state | Raise ExecutionRehydrationRequiredError before applying approval evidence |
+
+The entry method reads as saved-state application followed by saved approval
+evidence application. Private methods contain each operation's implementation.
+Evidence copying preserves the existing immutable facts and reason semantics,
+including an explicit nil facts value. A missing approval item leaves constructor
+defaults intact. Saved display evidence is not a new policy evaluation input.
+
+The caller supplies a newly constructed invocation before session installation.
+This is not a general rollback or arbitrary live-state replacement interface.
+The existing EventLoop ownership and continuation validation remain unchanged.
+The old internal `InvocationRestorer.restore_tool_snapshot!` entry is removed;
+no forwarding compatibility wrapper is introduced for this private helper.
+
+## Compatibility and limits
+
+No public API, RBS contract, saved schema, approval decision, external replay
+eligibility, missing-Tool rule, or callback sequence changes. The existing
+validation behavior is retained, including the handling of current Tool
+validation errors and missing definitions; this refactor does not add a new
+schema-migration or saved-state validation policy. It does not restore arbitrary
+Application Tool instance variables.
+
+Restoration itself does not run authorization policy, execute a Tool, acquire a
+Runtime, perform persistence I/O or notify listeners. This does not suppress the
+existing recovery installation notification of an outstanding approval request.
+Load-time notification and later approval/rejection dispatch keep their existing
+owners. External outcome-unknown resolution and framework operation recovery
+remain with RecoveryCoordinator and the execution owner.
+
+Under [018-durability-guarantees-and-failure-model](018-durability-guarantees-and-failure-model.md),
+this change concerns operation-local reconstruction from already materialized
+facts. Unsupported input is an F0 rejection without X0 dispatch by this operation.
+Same logical execution resumption after F4 remains CONDITIONAL on the existing
+confirmed saved state and operation-specific recovery contract. F1 outcome
+resolution is unchanged. No new external-effect exactly-once guarantee follows.
+
+## Verification
+
+Replace tests that mock another object's instance-variable writes with real
+ToolInvocation behavior tests. Run identical assertions against the old owner
+boundary and the new operation. Cover all six states, unsupported states, saved
+results, missing definitions, immutable approval evidence, and dispatch gating
+before and after approval. Existing restart tests exercise approval and rejection
+through actual recovery installation and session continuation. Run the ordinary
+and integration suites, API snapshot, annotations, RBS, examples and SQLite
+persistence checks. No test count implies a stronger F4 or X0 guarantee.
+
+SharedState coordination ownership, Storage domain responsibilities and Workflow
+terminal persistence remain separate work. This decision completes only the Tool
+restoration ownership item carried forward by ADR-047.

data/docs/decisions/053-shared-state-coordination-ownership.md

@@ -0,0 +1,71 @@
+# ADR-053: SharedState Coordination Ownership
+
+## Status
+
+Accepted on the architecture refactoring branch, 2026-09-22.
+This resolves the deferred SharedState ownership decision in
+[046-agent-responsibility-layout-and-shared-records](046-agent-responsibility-layout-and-shared-records.md).
+
+## Context
+
+SharedState creates an invocation-local findings store, equips several Agent
+definitions with read/write Tools, invokes members in declaration order, repeats
+cycles until a configured limit, and aggregates the findings. It is not an
+individual Agent's state container or execution coordinator. These responsibilities
+belong to MultiAgent, alongside the other multi-Agent coordination patterns.
+
+Its implementation also mixes cycle orchestration with individual member calls,
+and researcher instrumentation with the bodies of injected Tool definitions.
+Moving a file alone would leave those abstraction levels mixed.
+
+## Decision
+
+1. Move the implementation to `multi_agent/shared_state.rb`, exposing the
+   Experimental `Phronomy::MultiAgent::SharedState` and its nested `KnowledgeStore`.
+   Remove `Phronomy::Agent::SharedState` without an alias on this branch, following
+   the coordination ownership precedent in
+   [034-handoff-runner-coordination-ownership](034-handoff-runner-coordination-ownership.md).
+   Update examples, RBS and the [migration guide](../migrations/shared-state-multi-agent.md)
+   together. Ordinary consumers continue to `require "phronomy"`.
+2. Express invocation as termination validation, store creation, member
+   coordination and result aggregation. Express each cycle as ordered member
+   invocation followed by stopping decisions. Build the two injected Tool
+   definitions in named private methods. Keep these responsibilities in the same
+   class; no new execution manager or general coordination abstraction is needed.
+3. Preserve the DSL, method parameters, prompt text, Tool descriptions/schema,
+   cooperative execution mode, original Tool aliases, result shape and exceptions.
+   Members remain sequential; findings from an earlier member are visible to the
+   next member in the same cycle. `terminate_when` still takes precedence over
+   timeout after each complete cycle, and timeout does not interrupt a member.
+4. Preserve the generated Agent definition ID prefix
+   `Phronomy::Agent::SharedState::Instrumented/` and instrumentation version 1.
+   This string is semantic identity, not a Ruby constant lookup or old-name alias.
+   Namespace placement alone must not change the wrapped definition revision.
+
+## Consequences and limits
+
+This is a breaking rename of an Experimental public API, including the nested
+store class name. The Stable/Beta API snapshot does not enumerate SharedState;
+an unchanged snapshot does not establish complete public API compatibility.
+
+The store is still newly created for each invocation and is not durable shared
+Agent state. The coordinator adds no resume, cancellation, asynchronous execution,
+transaction, F4 or X0 guarantee. `invoke` still accepts `config:` without
+forwarding it to the member calls. Revising that behavior is a separate change.
+
+No persistence schema or saved-record migration is introduced. Individual Agent
+persistence keeps its existing rules; this move does not make the in-memory
+coordination lifetime resumable. The method extraction slightly increases source
+length and does not eliminate unrelated dependency cycles.
+
+Storage domain responsibilities and Workflow terminal ownership remain separate
+work items. This decision does not reopen the completed ExecutionCoordinator split.
+
+## Verification obligations
+
+Verify new namespace loading, absence of the old alias, repeated eager-load
+identity and no Runtime startup during loading. Exercise existing coordination,
+stopping, aggregation, Tool alias and definition identity tests. Check the full
+and integration suites, offline examples, RBS, annotations, style and built gem
+contents, including removal of the old implementation path. Record executed
+results and untested environments separately in the delivery review.

data/docs/decisions/054-workflow-terminal-save-single-owner.md

@@ -0,0 +1,76 @@
+# ADR-054: One Workflow Terminal Save Implementation
+
+## Status and scope
+
+Accepted on the architecture refactoring branch, 2026-09-22.
+Amends only the Workflow recovery prepend requirement in
+[038-responsibility-based-source-layout](038-responsibility-based-source-layout.md).
+The durable barrier in
+[026-workflow-runtime-admission-and-durable-terminal-barrier](026-workflow-runtime-admission-and-durable-terminal-barrier.md)
+and the receiver ownership in
+[042-feature-owned-execution-state](042-feature-owned-execution-state.md)
+remain unchanged.
+
+## Problem
+
+WorkflowRunner defines terminal save submission, but WorkflowRecovery defines
+the same method and is prepended during application loading. It never calls
+`super`. The active implementation reconciles uncertain save outcomes against
+durable pre/post state; the shadowed implementation does not. Reading or editing
+the Runner alone can therefore target code that is not actually used.
+
+## Decision
+
+Move the currently active submission and F1 reconciliation into WorkflowRunner.
+Delete the shadowed implementation, the private WorkflowRecovery module and its
+explicit installation. Do not introduce a new class or compatibility alias for
+the removed private override.
+
+Express terminal save submission as admission marking, immutable command
+construction, Offload submission and session-local result delivery. Named private
+methods own saving/reconciliation and delivery separately. The existing Command
+and Result Data classes retain their identity and members.
+
+The worker saves once. Portable ConflictError, NotFoundError, SerializationError
+and UnsupportedBackendError remain known failures without readback. Other save
+errors use the existing authoritative snapshot comparison: exact post-state is
+success, pre-state preserves the original failure, and conflict or failed
+readback remains outcome-unknown. No automatic save retry is introduced.
+
+The existing session sink receives `workflow_terminal_persistence_result`.
+Offload completion errors still become outcome-unknown, and rejected sink
+delivery retains its existing warning. Runner still marks admission and captures
+the snapshot on EventLoop; workers only use that captured command for persistence.
+
+## Compatibility and guarantees
+
+This is an internal ownership/readability change. Public Workflow/Persistence
+APIs, Backend SPI, snapshots, revisions, error messages and the session event
+protocol are unchanged. Removing the prepend can make WorkflowRunner load lazily
+under ordinary `require "phronomy"`; first access and eager loading must retain
+the same recovery behavior without starting Runtime.
+
+F1 save certainty remains CONDITIONAL on authoritative readback matching the
+existing expected pre-state or intended post-state rules. It is not established
+merely by receiving an exception. F0 portable failures follow the existing known
+failure path. Runtime release, success notification and Task settlement still
+wait for EventLoop-owned session acceptance; uncertain outcomes keep the existing
+recovery-required behavior. F4 readability depends on the backend retaining
+confirmed data. X0 external effects are outside this save, and this change adds
+no execution replay, distributed ownership or exactly-once guarantee.
+
+FSMSession still owns interpretation of the Workflow terminal persistence
+event. Moving that policy out of Engine is a separate next step; this decision
+does not claim that the entire Workflow terminal ownership issue is resolved.
+Storage's fixed repository slots and Agent watermark also remain separate work.
+
+## Verification
+
+Characterize the effective submission path before and after the change, including
+immutable snapshots, known errors, F1 post/pre/conflicting/unreadable outcomes,
+single-save behavior and failed Offload completion delivery. Preserve existing
+real-runtime tests for delayed save, stream barriers, admission release and
+uncertain outcomes. Verify ordinary/eager loading without the override, full and
+integration suites, API/RBS/annotations/style, offline examples and built gem
+contents. Keep results from tests actually run distinct from unavailable live
+Provider or database-server evidence.

data/docs/decisions/055-terminal-observer-failure-settlement.md

@@ -0,0 +1,60 @@
+# ADR-055: Settle Terminal Observer Failures
+
+## Status
+
+Accepted on the architecture refactoring branch, 2026-09-23.
+Clarifies terminal observer failure ordering in
+[026-workflow-runtime-admission-and-durable-terminal-barrier](026-workflow-runtime-admission-and-durable-terminal-barrier.md).
+It does not move Workflow terminal policy out of FSMSession; that remains W2b.
+
+## Problem
+
+FSMSession marked itself done before delivering a pending stable-state observer
+notification. If that observer raised at a wait state or a declared terminal
+state, the existing error handler saw done and returned without an error event.
+The synchronous stream caller remained blocked and Workflow admission stayed
+owned. Durable executions could already have saved their terminal snapshot.
+
+The existing observer-exception test covered an automatic transition's ordinary
+stable notification, before terminalization. It did not cover the deferred
+terminal notification. Six real-runtime observations on both pre-Refactor-31 and
+applied Refactor-31 source reproduce four affected cases and two unaffected
+automatic-transition controls. This is not a regression introduced by Refactor 31.
+
+## Decision
+
+Keep the existing terminal lifecycle selection, invoke the pending stable
+observer, and set done only after the observer returns successfully. If it
+raises, the existing start/handle/request error boundary emits the ordinary
+error event with the original exception. EventLoop retires the session and the
+existing Runner completion path releases admission before failing the caller.
+
+Preserve successful notification-before-terminal-event ordering. All transitions
+remain on EventLoop. Do not introduce a new class, callback retry, extra save,
+Task settlement path, or direct admission mutation from the observer.
+
+## Durable meaning and limits
+
+A durable terminal observer runs only after the session accepts a known-success
+save result. Observer failure therefore means notification failed; it does not
+mean the save failed, and must not erase, roll back, or repeat the saved record.
+The caller receives the original observer exception. Applications must not
+assume that every raised stream exception proves non-commit, nor replay external
+effects automatically. This adds no exactly-once or crash-atomic notification
+guarantee; existing F1/F4/X0 limits remain.
+
+Known save failure and unresolved save uncertainty are unchanged. In particular,
+the outcome-unknown path still retires the session without falsely settling the
+Workflow Task or releasing its recovery-required admission.
+
+## Verification
+
+Add public stream regressions for wait/declared-terminal boundaries, each with
+and without persistence. Require the same exception object, one notification
+on EventLoop, caller completion, session retirement and admission release.
+For durable cases, also require the existing snapshot and revision 1 to remain.
+Keep test cleanup bounded so these tests can demonstrate failure on old source.
+
+Run the shared FSMSession/Agent/Tool tests, Workflow admission and F1 tests, full
+and integration suites, API/RBS/style, examples and real SQLite. Keep W2b policy
+extraction in a later package after application verification of this fix.

data/docs/decisions/056-workflow-terminal-policy-ownership.md

@@ -0,0 +1,87 @@
+# ADR-056: Workflow-Owned Terminal Policy
+
+## Status
+
+Accepted on the architecture refactoring branch, 2026-09-23.
+Amends the implementation ownership in
+[ADR-026](026-workflow-runtime-admission-and-durable-terminal-barrier.md).
+Preserves the ordering and failure semantics clarified by
+[ADR-055](055-terminal-observer-failure-settlement.md).
+
+## Context
+
+FSMSession is used by WorkflowRunner, AgentInvocationSessionBuilder and
+ToolInvocationSessionBuilder. It belongs to Engine, but it directly recognized
+Workflow persistence events and interpreted success, known failure and unknown
+save outcomes. Moving the entire session would couple Agent and Tool to Workflow.
+Runner already owns the one terminal save and F1 reconciliation (ADR-054), and
+WorkflowExecutionRegistry already owns admission and owner tokens (ADR-042).
+
+## Decision
+
+WorkflowRunner injects a WorkflowTerminalPolicy only for durable execution.
+Ephemeral Workflow, Agent and Tool sessions keep their immediate terminal path.
+The policy holds the persistence callback, not live session state or admission.
+
+The private session protocol is:
+
+- `start(terminal_type:, context:, event_sink:)` begins the barrier on EventLoop.
+  Its return value does not authorize completion. Results use the bound sink.
+- `handles?(event)` recognizes a policy event, including an early event that
+  must be discarded by the session before any terminal request.
+- `decision_for(event)` interprets an accepted event and returns the immutable
+  `FSMProtocol::TerminalDecision(action:, error:)` value.
+
+WorkflowTerminalPolicy maps success to `complete`, known failure to `fail` with
+its original error or the existing fallback error, and outcome unknown to
+`retire` with its diagnostic error. Invalid Workflow outcomes remain errors.
+FSMSession knows these generic actions, not the Workflow event or outcome values.
+An unsupported action fails through the existing session error path.
+
+FSMSession alone owns the pending terminal type, stable-notification flag and
+acceptance state. It enters `awaiting_terminal` before starting the policy,
+ignores ordinary events during that wait, ignores early policy events, and
+accepts at most one terminal decision. The policy must not maintain a second
+pending lifecycle or mutate the session from a worker.
+
+`complete` delivers any deferred stable notification before marking done and
+posting the terminal event. `fail` uses the existing failure path. `retire`
+marks the session retired and uses EventLoop's existing recovery-required
+management route without settling a result. Runner persistence/F1 code,
+Registry ownership and EventLoop retirement/shutdown code remain unchanged.
+
+## Uncertainty and shutdown
+
+Retirement for an unknown save result removes the concrete routing session and
+retains recovery-required admission. It does not complete or fail the caller.
+The old sink cannot target a subsequent incarnation. Normal Runtime shutdown
+clears Registry ownership and terminates the dispatcher, but does not synthesize
+a Workflow result: the unresolved caller remains pending. Unexpected dispatcher
+failure has its separate existing waiter cleanup. These are preserved behaviors,
+not a new guarantee of automatic recovery or a stronger F1/F4/X0 contract.
+
+## Compatibility and non-goals
+
+`terminal_barrier:` is replaced by private `terminal_policy:` with no alias.
+The internal lifecycle names change to `awaiting_terminal` and `retired`.
+Neither constructor injection nor these states are a new public plugin API.
+Without an injected policy, Engine no longer reserves a Workflow-only event
+name. Workflow's producer emits that event only for its durable execution path.
+Session identity, EventSink correlation, public Workflow/Agent/Tool APIs,
+Workflow result types, durable records and Storage SPI are unchanged.
+
+Do not move snapshot persistence into the policy, settle caller Tasks there,
+rename outcome strings while leaving interpretation in Engine, introduce a
+subclass/prepend override, or duplicate admission. A small new policy and value
+type clarify ownership; reducing the total line count is not the objective.
+
+## Verification
+
+The generic session contract uses a non-Workflow event and policy, exercising
+early/ordinary/duplicate events, completion, failure, retirement, submission
+error, malformed decisions and the immediate default path. Workflow tests cover
+invalid outcomes and the existing missing-error fallback through Runner wiring.
+Real Runtime tests cover F1 pre-state, conflicting/unreadable readback, retained
+admission and normal shutdown, stale sinks across incarnations, and submission
+rejection. Existing delayed-save, halted-stream, observer-failure, Agent/Tool and
+F1 tests remain acceptance gates; rejected result delivery must not retry save.

data/docs/decisions/057-storage-transaction-boundaries.md

@@ -0,0 +1,73 @@
+# ADR-057: Storage update constraints and explicit transaction boundaries
+
+## Status
+
+Accepted for implementation in Refactor 34 (Storage S2a).
+
+
+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.
+
+## Context
+
+The existing eight-repository SPI had three concrete behavioral differences.
+InMemory allowed an inactive Agent execution to become active while another
+execution for that Agent was active. SQL rejected that update. SQL Journal
+append serialized each record immediately before inserting it; catching an
+invalid later record inside the outer transaction could commit earlier rows
+without advancing the head. Explicit nested InMemory transactions restored an
+inner snapshot, whereas ActiveRecord's default nesting joined the outer scope.
+
+## Decision
+
+Keep the existing SPI and data formats while closing these differences.
+
+1. InMemory checks active-owner uniqueness on Agent execution updates under the
+   same Monitor as revision validation and writes. Exclude the updated identity.
+   Report `Storage::ActiveExecutionConflictError` and leave record and revision
+   unchanged on rejection. Team terminal execution reactivation remains forbidden.
+2. Both SQL Journal adapters serialize the complete batch and normalize the
+   expected position before any writes. Preserve ID checks, lock order, CAS,
+   return values and transaction-bound connection access.
+3. Explicit `Backend#transaction` / `Persistence#transaction` nesting on the same
+   backend and synchronous execution context uses savepoint semantics. Roll back
+   a failed inner scope and re-raise the same exception. The outer scope may catch
+   it and continue. Inner success is not an independent commit: outer failure
+   rolls back both. SQL uses `requires_new: true` on the same checked-out
+   connection. InMemory retains its reentrant Monitor and snapshots.
+
+The SQL wrappers also re-raise `ActiveRecord::Rollback` after ActiveRecord rolls
+back and consumes it. The Storage API does not use an exception as a successful
+return value. Repository operations on a bound view still join that scope; this
+change does not introduce per-operation savepoints or separate connections.
+
+## Compatibility and migration
+
+This intentionally changes SQL behavior. If an application catches an inner
+failure, writes from that failed inner block will no longer remain in the outer
+transaction. Catch outside the explicit inner block and re-read any conditions
+needed to continue. Catching a database failure inside the same transaction view
+and continuing is not a portable recovery contract; propagate it or isolate the
+operation in an explicit inner transaction before executing it.
+
+`ActiveRecord::Rollback` now propagates from the Storage/Persistence boundary.
+Callers relying on ActiveRecord's silent rollback must catch it outside that
+boundary. Backend authors should run the public Persistence contract suite;
+method signatures and required capability keys are unchanged.
+
+No schema, record type/version, payload, content identity or public facade
+changes are required. Unknown commit outcomes remain backend/database failures;
+this decision does not add exactly-once behavior or retry external effects.
+
+## Verification and remaining work
+
+Shared tests cover rejected update immutability, nonconflicting active updates,
+invalid later Journal records, retrying the same record IDs, inner-only rollback,
+exception identity, continued outer writes, normal results and outer rollback.
+Both raw Backend and domain Persistence transaction entry points are exercised.
+SQL-specific tests cover `ActiveRecord::Rollback` propagation.
+
+The new neutral Records/Streams/Blobs SPI, failed-view lifecycle and explicit
+non-local block-exit handling (`return` / `break` / `throw`) belong to S2b.
+Do not use non-local exits as portable commit controls. PostgreSQL live-server
+conformance and concurrency tests remain a required integration gate; source
+parity or tests with a non-PostgreSQL connection do not satisfy that gate.