phronomy 0.26.0 → 0.27.0

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.

data/docs/decisions/058-neutral-storage-primitives.md

@@ -0,0 +1,78 @@
+# ADR-058: Neutral Storage primitives and scoped transactions
+
+## Status
+
+Accepted. Applied and verified in Refactor 35 (Storage S2b/S2c), core
+`ebd99623f94c8b2db2d74355bfa39f01550778a0` and examples
+`68a0bbd0e354b9e00bbfed728ad2b769b389ed8a`.
+
+## Context
+
+S1 inventoried 37 raw methods across eight required domain slots. Moving their
+classes did not remove Agent watermark or active-owner policy from shared
+storage. S2a fixed concrete transaction and update differences first. S2b now
+changes the extension contract while preserving domain APIs and durable data.
+
+## Decision
+
+1. Replace the eight-slot Backend/Repositories SPI with declared Resources and
+   Records, Streams, Blobs accessed through View. Storage has no domain codecs,
+   active-execution interpretation, content digest or Agent watermark method.
+2. Keep schemas, encoding, initial revisions, active-state interpretation and
+   metadata validation in their features. Composition gathers declarations and
+   builds domain wrappers. Team/Workflow schema loader roots do not load runtime.
+3. Use named equality indexes, conditional unique constraints, immutable metadata,
+   revision CAS, stream head CAS and a closed guarded-condition set. Parent guards
+   precede child locks. Required parent absence is uniformly NotFoundError.
+4. Keep one transaction domain, scoped views, same-connection savepoints and root
+   handle routing. Reject expired/cross-thread views and failed physical scopes.
+   Reject non-local block exits with TransactionError and rollback. A successful
+   optional read returning nil is not a failed physical operation.
+5. Report neutral UniqueConstraintError(resource ID, constraint name) and
+   ConditionFailedError(condition). Only owning domain repositories map exact
+   active constraints to AgentBusyError. Remove the old domain-named error alias.
+6. Share neutral SQL operations in examples/shared/storage, with explicit dialect
+   differences and separate domain/table composition. Keep all existing tables,
+   indexes, envelope formats, payloads, IDs and content bytes. Nullable unique-key
+   fields are distinct, matching SQL default uniqueness semantics.
+
+## Supersession scope
+
+This amends ADR-032's raw eight-slot contract, ADR-033's remaining fixed raw
+boundary, ADR-043's domain-named raw exception and ADR-057's old-SPI-only limit.
+Their domain ownership, composition, savepoint and uncertainty decisions remain.
+No historical artifact is silently reinterpreted as a current SPI specification.
+
+## Public contract and migration
+
+Persistence's constructor, in_memory, eight accessors, result queries and public
+capabilities remain. Backend SPI 2 is intentionally breaking; legacy duck-typed
+backends fail capability validation. There is no compatibility facade or alias.
+See the [contract](../persistence-backends.md), [migration guide](../migrations/neutral-storage-spi.md),
+RBS and explicit SPI 2 snapshot. Ordinary product API snapshots remain separate.
+
+## Validation and remaining gates
+
+Shared conformance tests cover opaque data, CAS, named constraints, parents,
+Unicode cursor ordering, streams, binary blobs, all-resource rollback, nested
+savepoints, view lifetime, thread confinement and non-local exits. Domain tests
+retain F0/F1/F4 behavior and X0 limitations. SQLite old/new/old round-trip checks
+cover all eight resources and unchanged schema. The applied SPI 2 pair passed
+[PostgreSQL 17.11 CI](https://github.com/Raizo-TCS/phronomy-examples/actions/runs/35827495677)
+on Ruby 3.2/3.3/3.4, with 119 examples per version and fresh-pool reload. Both
+checkout SHAs were verified. Earlier SPI CI was not used as substitute evidence.
+No stronger commit certainty, distributed Workflow admission or external-effect
+retry is introduced.
+
+## S3 internal responsibility clarification
+
+Refactor 36 keeps all public SPI 2 signatures and Resource identity rules.
+Resource normalizes a schema object or resource ID before GuardRef/Condition
+construction; the cooperation method is `@api private`, not a new backend
+extension point. Generic Validation handles scalar validation and copying and
+must not depend on Resource. View still enforces catalog membership and exact
+schema identity. This removes the internal Resource/Validation cycle without
+changing a public name, transaction, stored record or physical backend.
+
+See the [closure review](../architecture/refactoring-closure.md) for retained
+placements and the separate distribution application gate.

data/docs/decisions/README.md

@@ -62,7 +62,7 @@ resolved explicitly.
 | [`011-delegate-transport-policy-to-adapters`](011-delegate-transport-policy-to-adapters.md) | Accepted | Yes | Legacy duplicate numeric prefix; use the full canonical key. |
 | [`012-canonical-execution-log-and-context-policy`](012-canonical-execution-log-and-context-policy.md) | Accepted | Yes | Current Journal / Manifest / Context authority. |
 | [`013-journal-backed-knowledge-as-context-candidates`](013-journal-backed-knowledge-as-context-candidates.md) | Accepted | Yes | Current persistent Knowledge authority. |
-| [`014-unified-persistence-durable-state`](014-unified-persistence-durable-state.md) | Accepted | Yes | Durable-backend and live-owner/no-reload intent remains current; live Agent execution mutation is refined by ADR-024, same-process Agent identity/admission ownership by ADR-025, and same-process Workflow admission/terminal-barrier ordering by ADR-026. Workflow identity terminology is superseded by ADR-020, generic `InvocationContext` / Agent correlation semantics by ADR-021, and concrete FSMSession/Agent-Tool routing identity by ADR-023. |
+| [`014-unified-persistence-durable-state`](014-unified-persistence-durable-state.md) | Accepted | Yes | Durable-backend and live-owner/no-reload intent remains current; [032-storage-backend-composition](032-storage-backend-composition.md) refines storage contract ownership and replaces the backend inheritance SPI; live Agent execution mutation is refined by ADR-024, same-process Agent identity/admission ownership by ADR-025, and same-process Workflow admission/terminal-barrier ordering by ADR-026. Workflow identity terminology is superseded by ADR-020, generic `InvocationContext` / Agent correlation semantics by ADR-021, and concrete FSMSession/Agent-Tool routing identity by ADR-023. |
 | [`015-tool-public-facade-and-rbs-boundary`](015-tool-public-facade-and-rbs-boundary.md) | Accepted | Yes | Current Tool façade / extension-SPI / RBS boundary. |
 | [`016-semantic-multi-agent-handoff`](016-semantic-multi-agent-handoff.md) | Superseded | No | Superseded by [ADR-030](030-agent-handoff-domain-and-durable-responsibility.md), including Agent-domain ownership and exact Target recovery. |
 | [`017-design-authority-and-adr-governance`](017-design-authority-and-adr-governance.md) | Accepted | Yes | Repository-wide architecture authority and ADR governance. |
@@ -72,14 +72,43 @@ resolved explicitly.
 | [`021-generic-agent-invocation-identity-removal`](021-generic-agent-invocation-identity-removal.md) | Accepted | Yes | Removes generic Agent/InvocationContext identity and canonical Journal `correlation_id`; CG-02 is closed, with targeted legacy durable-key read compatibility and no eager rewrite. |
 | [`022-agent-execution-parent-identity-and-runtime-routing-boundary`](022-agent-execution-parent-identity-and-runtime-routing-boundary.md) | Accepted | Yes | Canonicalizes Agent-owned Tool/approval logical parent as `execution_id`; CG-03a is reconciled, ADR-023 supplies incarnation routing, and ADR-024 supplies EventLoop result/live-state authority. |
 | [`023-fsm-session-incarnation-identity-and-routing`](023-fsm-session-incarnation-identity-and-routing.md) | Accepted | Yes | FSMSession-owned incarnation identity, session-local Agent/Tool/Multi-Agent routing, and stale-target drop remain current. Its transitional Workflow identity-reservation/admission bridge is superseded by ADR-026; Agent result authority is completed by ADR-024. |
-| [`024-event-loop-single-writer-agent-runtime`](024-event-loop-single-writer-agent-runtime.md) | Accepted | Yes | EventLoop is the single writer of Phronomy-managed live Agent execution state; removes Activation/ActivationRegistry and defines operation-specific Offload result application with current FSM + semantic-ID authority. |
-| [`025-process-local-agent-ownership-and-runtime-admission`](025-process-local-agent-ownership-and-runtime-admission.md) | Accepted | Yes | One mutable live Agent owner per `agent_id` per Runtime; EventLoop is the primary same-process top-level admission authority while Persistence admission remains durable defense. |
-| [`026-workflow-runtime-admission-and-durable-terminal-barrier`](026-workflow-runtime-admission-and-durable-terminal-barrier.md) | Accepted | Yes | EventLoop-owned opaque Workflow admission owner, admission-before-hydration ordering, and FSMSession-integrated durable terminal save barrier with fail-closed uncertain outcomes. |
+| [`024-event-loop-single-writer-agent-runtime`](024-event-loop-single-writer-agent-runtime.md) | Amended | Yes | EventLoop is the single writer of Phronomy-managed live Agent execution state; removes Activation/ActivationRegistry and defines operation-specific Offload result application with current FSM + semantic-ID authority.  Implementation ownership/delivery amended by [042-feature-owned-execution-state](042-feature-owned-execution-state.md). |
+| [`025-process-local-agent-ownership-and-runtime-admission`](025-process-local-agent-ownership-and-runtime-admission.md) | Amended | Yes | One mutable live Agent owner per `agent_id` per Runtime; EventLoop is the primary same-process top-level admission authority while Persistence admission remains durable defense. ADR-041 moves registry implementation to Agent while retaining Runtime-scoped lifetime.  Implementation ownership/delivery amended by [042-feature-owned-execution-state](042-feature-owned-execution-state.md). |
+| [`026-workflow-runtime-admission-and-durable-terminal-barrier`](026-workflow-runtime-admission-and-durable-terminal-barrier.md) | Amended | Yes | EventLoop-owned opaque Workflow admission owner, admission-before-hydration ordering, and FSMSession-integrated durable terminal save barrier with fail-closed uncertain outcomes.  Implementation ownership/delivery amended by [042-feature-owned-execution-state](042-feature-owned-execution-state.md). |
 | [`027-llm-adapter-provider-boundary`](027-llm-adapter-provider-boundary.md) | Accepted | Yes | Phronomy-owned Provider-call extension boundary; RubyLLM is the default adapter/integration while current input materialization remains RubyLLM-specific. |
 | [`028-preparing-recovery-replay-contract`](028-preparing-recovery-replay-contract.md) | Accepted | Yes | Adds replay-safe same-`execution_id` recovery for durably admitted Agent `:preparing` executions when replayability is durably established; unsupported Runtime-only dependencies fail closed. |
 | [`029-semantic-completion-and-application-effect-boundary`](029-semantic-completion-and-application-effect-boundary.md) | Accepted | Yes | V2 revision 2; framework semantic coordination and Application effect boundary. |
-| [`030-agent-handoff-domain-and-durable-responsibility`](030-agent-handoff-domain-and-durable-responsibility.md) | Accepted | Yes | V2 revision 2; framework semantic coordination and Application effect boundary. |
-| [`031-durable-multi-agent-coordination`](031-durable-multi-agent-coordination.md) | Accepted | Yes | V2 revision 2; framework semantic coordination and Application effect boundary. |
+| [`030-agent-handoff-domain-and-durable-responsibility`](030-agent-handoff-domain-and-durable-responsibility.md) | Accepted | Yes | V2 revision 2; framework semantic coordination and Application effect boundary. Runner ownership amended by [034-handoff-runner-coordination-ownership](034-handoff-runner-coordination-ownership.md); other V2 semantics remain. |
+| [`031-durable-multi-agent-coordination`](031-durable-multi-agent-coordination.md) | Accepted | Yes | V2 revision 2; framework semantic coordination and Application effect boundary. Runner ownership amended by [034-handoff-runner-coordination-ownership](034-handoff-runner-coordination-ownership.md); other V2 semantics remain. |
+| [`032-storage-backend-composition`](032-storage-backend-composition.md) | Accepted | Yes | Separates raw Storage contracts/backends from domain Persistence by composition; replaces the Persistence subclass SPI and its facade-building helper. ADR-014 single transaction domain and ownership guarantees remain; [033-domain-persistence-ownership](033-domain-persistence-ownership.md) refines codec/repository ownership. |
+| [`033-domain-persistence-ownership`](033-domain-persistence-ownership.md) | Amended | Yes | Domain-owned codecs, repositories, and result queries over the unchanged Storage SPI; explicit composition preserves one transaction domain. Error boundary refined by [043-storage-execution-constraint-notifications](043-storage-execution-constraint-notifications.md). |
+| [`034-handoff-runner-coordination-ownership`](034-handoff-runner-coordination-ownership.md) | Accepted | Yes | H1 moves the public HandoffRunner to MultiAgent; Agent execution, Handoff records, and Runtime shutdown semantics are preserved. Further Handoff separation is deferred. |
+| [`035-tool-executor-capability-ownership`](035-tool-executor-capability-ownership.md) | Accepted | Yes | T1 places the private default Tool executor beside Capability Base; public Tool identity, execution modes, Runtime injection, and Agent authorization/result ownership are preserved. |
+| [`036-context-contract-ownership`](036-context-contract-ownership.md) | Accepted | Yes | C1 groups Context Policy/hook contracts, values, Manifest representation, and Plan validation in a collapsed directory; public Agent constants, extension protocols, and stored formats are preserved. |
+| [`037-common-definition-ownership`](037-common-definition-ownership.md) | Amended | Yes | Defines the common responsibility group and initially extracts the shared base exception; [038-responsibility-based-source-layout](038-responsibility-based-source-layout.md) extends the extraction scope while preserving ownership rules and exception contracts. |
+| [`038-responsibility-based-source-layout`](038-responsibility-based-source-layout.md) | Amended | Yes | Reserves the direct root for version/namespace loading, groups common definitions and feature implementation/contracts, and preserves canonical constants and lifecycle loading through explicit Zeitwerk roots. ADR-039 separates cross-owner Runtime lifecycle coordination. |
+| [`039-runtime-configuration-lifecycle-ownership`](039-runtime-configuration-lifecycle-ownership.md) | Amended | Yes | Separates application Runtime reset and configuration replacement into runtime_composition; configuration access and Engine mechanics retain their own ownership and existing API behavior. ADR-040 separates concrete-default selection without changing Runtime reset. |
+| [`040-configuration-default-composition`](040-configuration-default-composition.md) | Accepted | Yes | Settings consume internal fresh-instance factories; runtime_composition selects and binds the concrete adapter/tracer defaults. Preserves Configuration.new and the adapter SPI. |
+| [`041-feature-owned-identity-registries`](041-feature-owned-identity-registries.md) | Accepted | Yes | Agent and MultiAgent own identity registries; Runtime retains them through generic lookup, drain/wait, and optional finalization. Preserves product APIs and single-owner lifetime; Execution state is separately assigned by ADR-042. |
+
+| [`042-feature-owned-execution-state`](042-feature-owned-execution-state.md) | Accepted | Yes | Agent/Workflow own execution state; Engine retains generic receiver delivery, synchronization and shutdown boundaries. Single-writer and durable barriers remain. |
+| [`043-storage-execution-constraint-notifications`](043-storage-execution-constraint-notifications.md) | Accepted | Yes | Raw backends report Storage-owned active-execution conflicts; feature repositories preserve public busy errors within the same transaction. Beta raw error SPI migration. |
+| [`044-agent-default-and-one-shot-composition`](044-agent-default-and-one-shot-composition.md) | Accepted | Yes | Agent consumes an owner-defined fresh-Persistence factory; application composition selects the default and owns the unchanged one-shot API. |
+| [`045-worker-input-restriction-ownership`](045-worker-input-restriction-ownership.md) | Accepted | Yes | Each restricted type declares an execution-boundary marker; authorization input validation preserves the existing rejection and opaque application-value contracts without enumerating feature types. |
+| [`046-agent-responsibility-layout-and-shared-records`](046-agent-responsibility-layout-and-shared-records.md) | Amended | Yes | Agent responsibility directories preserve constants; shared record encoding, saved context reads and live restoration have separate owners. Continuation control refined by [047-recovered-execution-continuation-contract](047-recovered-execution-continuation-contract.md); deferred SharedState ownership resolved by [053-shared-state-coordination-ownership](053-shared-state-coordination-ownership.md). |
+| [`047-recovered-execution-continuation-contract`](047-recovered-execution-continuation-contract.md) | Accepted | Yes | Recovery hands semantic commands to the execution owner; EventLoop identity/revision checks and shared session registration replace private control calls. |
+| [`048-dispatch-preparation-worker-ownership`](048-dispatch-preparation-worker-ownership.md) | Accepted | Yes | Dispatch worker owns prerequisite persistence and readback; the execution owner retains EventLoop validation, apply and dispatch. Operation-specific boundaries and purpose-level method bodies are preserved. |
+| [`049-initial-preparation-worker-ownership`](049-initial-preparation-worker-ownership.md) | Accepted | Yes | Initial preparation and preparing recovery share a persistence worker; admission outcomes, commit certainty and EventLoop ownership stay distinct. Pure failure classification is shared without sharing transaction control. |
+| [`050-approval-resume-snapshot-and-commit-ownership`](050-approval-resume-snapshot-and-commit-ownership.md) | Accepted | Yes | Validated approval commands own immutable recovery snapshots. A worker commits decision, Execution and Root; the execution owner retains admission, live state and session resumption. |
+| [`051-execution-outcome-worker-ownership`](051-execution-outcome-worker-ownership.md) | Accepted | Yes | Ordinary and Handoff outcome workers own atomic persistence and operation-specific readback; EventLoop retains result authority and delivery. |
+| [`052-tool-invocation-restoration-ownership`](052-tool-invocation-restoration-ownership.md) | Accepted | Yes | ToolInvocation owns saved state application; Recovery retains snapshot decoding and identity matching. Existing restoration and replay rules are preserved. |
+| [`053-shared-state-coordination-ownership`](053-shared-state-coordination-ownership.md) | Accepted | Yes | Moves Experimental SharedState and its invocation-local store to MultiAgent without an old-name alias; preserves coordination behavior and generated definition identity. Resolves the deferred SharedState ownership in ADR-046. |
+| [`054-workflow-terminal-save-single-owner`](054-workflow-terminal-save-single-owner.md) | Accepted | Yes | Consolidates the active F1-aware terminal save in WorkflowRunner and removes its private prepend override. Amends ADR-038 loading; preserves the durable barrier and leaves FSMSession policy ownership as separate work. |
+| [`055-terminal-observer-failure-settlement`](055-terminal-observer-failure-settlement.md) | Accepted | Yes | Keeps the error path open until terminal stable notification returns. Observer failure settles the caller and releases admission without retrying or undoing an already confirmed save. Clarifies ADR-026; W2b ownership extraction remains separate. |
+| [`056-workflow-terminal-policy-ownership`](056-workflow-terminal-policy-ownership.md) | Accepted | Yes | Workflow owns persistence-result interpretation through a private policy; Engine retains generic session gating and complete/fail/retire actions. Preserves ADR-026/055 ordering and uncertainty without a public plugin API. |
+| [`057-storage-transaction-boundaries`](057-storage-transaction-boundaries.md) | Accepted | Yes | Enforces active-owner exclusion on InMemory updates, validates SQL Journal batches before writes and defines explicit nested savepoints with propagated failures. Preserves the existing SPI and record formats; the neutral SPI remains separate work. |
+
+| [`058-neutral-storage-primitives`](058-neutral-storage-primitives.md) | Accepted | Yes | Neutral Records/Streams/Blobs SPI 2 and scoped transaction lifecycle; amends 032, 033, 043 and 057. |
 
 ## Legacy duplicate `011`
 

data/docs/design/durable-semantic-coordination/IMPLEMENTATION_DESIGN_V2.md

@@ -1,5 +1,11 @@
 # Phronomy Durable Semantic Coordination — Implementation Design V2
 
+> Runner namespace update (2026-09-18): this document preserves the V2
+> implementation/migration record. The current Runner is
+> `Phronomy::MultiAgent::HandoffRunner` under
+> [ADR-034](../../decisions/034-handoff-runner-coordination-ownership.md).
+> Handoff and HandoffPolicy remain in Agent at this stage.
+
 ## 0. Status and authority
 
 **Accepted implementation design — V2 revision 2 (2026-09-06).**

data/docs/design/durable-semantic-coordination/IMPLEMENTATION_REPORT.md

@@ -1,5 +1,11 @@
 # Durable Semantic Coordination V2 revision 2 — Implementation report
 
+> Runner namespace update (2026-09-18): this document preserves the V2
+> implementation/migration record. The current Runner is
+> `Phronomy::MultiAgent::HandoffRunner` under
+> [ADR-034](../../decisions/034-handoff-runner-coordination-ownership.md).
+> Handoff and HandoffPolicy remain in Agent at this stage.
+
 作成日: 2026-09-07。設計承認日: 2026-09-06。
 対象baseline: `5472116cd99a63ec27875024c955ea82be612d6b`。
 承認済みADR-029/030/031とRC-01〜05に対する新規実装です。

data/docs/features.md

@@ -20,7 +20,7 @@ for production deployments.
 | **Workflow** — Stateful, branching workflows with `wait_state` and explicit events | Stable |
 | **Agent** — Stateful ReAct-style agents with stable `agent_id`, one mutable live owner per Runtime, persistence-backed execution state, canonical history, and conversation context | Stable |
 | **Tool authoring façade** — `Phronomy::Tool::Base` is the public authoring name for the existing Capability base class; the legacy namespace remains compatible | Beta |
-| **Unified Persistence** — One durable backend abstraction for Agent state and Workflow `workflow_states`; live Agent/Workflow state remains owned by Runtime/session authority between durable commits; custom backends implement the documented Backend SPI and repository/transaction semantics | Beta |
+| **Unified Persistence** — One transaction domain for Agent, Team, and Workflow state; a domain-facing `Persistence` composes a record-oriented `Storage::Backend`; live Agent/Workflow state remains owned by Runtime/session authority between durable commits; custom backends implement the documented Backend SPI, including Storage-owned active-execution constraint notifications translated by domain repositories, and repository/transaction semantics | Beta |
 | **LLMAdapter SPI** — `Phronomy::LLMAdapter::Base#complete` / `#stream` define the Beta call-adapter extension boundary; Phronomy owns async/offload wrapping | Beta |
 | **Before-Large-Language-Model (LLM) Input Hook** — Three-tier per-call LLM input customization via `before_llm_input` and `LLMInputPatch` | Stable |
 | **Context Management** — Journal + Context Policy + per-LLM-call Manifest with token-budget-aware selection and protocol-safe Tool Call / Tool message dependencies | Stable |
@@ -79,14 +79,20 @@ rather than implicitly inheriting the parent revision. The Stable
 
 ## Agent and workflow patterns
 
+Agent Tool batches use a single ordinary RubyLLM chat path. Agent owns Tool
+authorization, dispatch and the barrier before the next Provider request;
+concurrency remains governed by Tool execution modes and Runtime capacity.
+The obsolete `parallel_tool_execution` configuration accessor has been removed.
+See the [migration guide](migrations/parallel-tool-chat-removal.md).
+
 | Feature | Stability |
 |---|---|
 | **Workflow asynchronous pattern** — Start async work, return immediately, and continue through `Workflow#signal` | Beta |
-| **Durable Agent Handoff** — `Agent::Handoff` and `Agent::HandoffRunner` persist responsibility, immutable Context and exact Target reservation in one Persistence domain; current graph wiring is required for continuation | Beta |
+| **Durable Handoff** — `Agent::Handoff` and `MultiAgent::HandoffRunner` persist responsibility, immutable Context and exact Target reservation in one Persistence domain; current graph wiring is required for continuation | Beta |
 | **GeneratorVerifier** — Generator-Verifier loop with injectable prompts/parsers | Beta |
 | **`Phronomy::MultiAgent::Orchestrator`** — Parallel subagent dispatch, fan-out, and `subagent` DSL | Beta |
 | **`Phronomy::MultiAgent::TeamCoordinator`** — LLM coordinator with stateful worker Agents | Beta |
-| **SharedState** — Peer-agent shared-state coordination | Experimental |
+| **`Phronomy::MultiAgent::SharedState`** — Sequential peer-agent coordination through an invocation-local findings store; see the [namespace migration](migrations/shared-state-multi-agent.md) | Experimental |
 | **Human-in-the-loop approval** — durable suspension publishes `:approval_required` through the Agent listener; `approve` / `approve_async` resumes the same logical `execution_id` with a fresh FSMSession incarnation | Beta |
 | **`tool_approval_policy`** — Application-defined allow/approve/reject policy using a value-only `ApprovalEvaluationRequest` without live Agent/Tool references | Beta |
 

data/docs/getting-started.md

@@ -85,7 +85,7 @@ application does not need to pass the previous `messages` array back into every
 invocation.
 
 ```ruby
-persistence = Phronomy::Persistence::InMemory.new
+persistence = Phronomy::Persistence.in_memory
 
 agent = ResearchAgent.create(
   agent_id: "research-session-42",
@@ -115,7 +115,7 @@ A Runtime has at most one mutable live Agent object for an `agent_id`. If the
 Agent is already live, repeated `load` returns that exact Ruby object and does
 not reload Persistence. If it is not live, `load` hydrates the durable Agent
 once. Loading an ID that does not exist durably raises
-`Persistence::NotFoundError`.
+`Storage::NotFoundError`.
 
 Use `get` when only a process-local lookup is wanted:
 
@@ -131,7 +131,7 @@ While the Agent is live, it owns its current AgentRoot/Journal view and
 Runtime/EventLoop owns process-local identity/admission/execution authority.
 Phronomy persists snapshots at defined durability boundaries but does not reload
 mutable Agent/Execution/Journal state before every LLM or Tool step. A conflicting
-external durable write is surfaced as `Persistence::ConflictError` rather than
+external durable write is surfaced as `Storage::ConflictError` rather than
 silently merged into the live instance.
 
 The active transcript and Knowledge views can be advanced independently without
@@ -250,7 +250,7 @@ end
 write_draft  = ->(state) { state.merge(draft: "Draft content") }
 review_draft = ->(state) { state.merge(feedback: "Feedback on: #{state.draft}") }
 
-persistence = Phronomy::Persistence::InMemory.new
+persistence = Phronomy::Persistence.in_memory
 
 workflow = Phronomy::Workflow.define(
   ReviewContext,

data/docs/migrations/0.15.md

@@ -16,6 +16,11 @@ follow the current contracts documented in
 | `InvocationContext#provider_limits` | Configure the provider client directly |
 | `stream_queue_max_size` | No replacement; the shared EventLoop queue is unbounded by design. Monitor `Metrics.snapshot[:event_loop_queue_depth]` instead |
 
+The historical `parallel_tool_execution` switch mentioned above was subsequently
+removed by the architecture refactor. Current code should follow the
+[Chat migration guide](parallel-tool-chat-removal.md); it is not an on/off
+control for Agent Tool concurrency.
+
 ## Timeout ownership
 
 Phronomy owns logical lifecycle deadlines and cooperative cancellation. Provider,

data/docs/migrations/durable-semantic-coordination-v2.md

@@ -1,5 +1,11 @@
 # Durable semantic coordination V2 migration
 
+> Runner namespace update (2026-09-18): this document preserves the V2
+> implementation/migration record. The current Runner is
+> `Phronomy::MultiAgent::HandoffRunner` under
+> [ADR-034](../decisions/034-handoff-runner-coordination-ownership.md).
+> Handoff and HandoffPolicy remain in Agent at this stage.
+
 This Beta clean break applies to baseline `5472116cd99a63ec27875024c955ea82be612d6b`.
 
 | Previous surface | Current surface |

data/docs/migrations/handoff-runner-multi-agent.md

@@ -0,0 +1,35 @@
+# HandoffRunner moves to MultiAgent
+
+This change applies to H1 on `refactor/architecture` after core commit
+`fe2ad7cea6945a240858b18645dc4ae285e8ce64`. The released 0.26.0 gem does not
+yet provide this new Runner name.
+
+| Previous API | API on this refactoring branch |
+|---|---|
+| `Phronomy::Agent::HandoffRunner` | `Phronomy::MultiAgent::HandoffRunner` |
+| `Phronomy::Agent::Handoff` | Unchanged |
+| `Phronomy::Agent::HandoffPolicy` | Unchanged |
+
+The previous Runner name is removed without an alias. Update direct `require`
+paths from `phronomy/agent/handoff_runner` to `phronomy/multi_agent/handoff_runner`
+if used; ordinary `require "phronomy"` continues to use Zeitwerk.
+
+Runner initialization still accepts `main_agent:` and `handoffs:`. Its `invoke`,
+`cancel` and `result` methods, `main_agent`/`handoffs` readers and `MAX_HANDOFFS`
+constant retain their behavior. Existing Handoff edges and Policy objects remain
+in the Agent namespace during this first step.
+
+Update the core and examples together. When using examples from the corresponding
+refactoring branch, set `PHRONOMY_PATH` to the matching local core checkout before
+resolving bundles or running verification. The examples API preflight rejects an
+older core and checks exact removed constants without mistaking
+`MultiAgent::HandoffRunner` for `MultiAgent::Handoff`.
+
+No persisted-record migration or SQL schema change is required. Existing
+HandoffState, Context and execution records are read using the same format,
+identity and revision rules. Recovery still requires compatible current Agent
+definitions and Handoff graph wiring; changing the Runner namespace does not
+relax that requirement.
+
+The ownership rationale and remaining work are recorded in
+[ADR-034](../decisions/034-handoff-runner-coordination-ownership.md).

data/docs/migrations/neutral-storage-spi.md

@@ -0,0 +1,43 @@
+# Migrating to neutral Storage SPI 2 (Refactor 35)
+
+Apply matching core and examples changes together. Existing SQL databases need
+no schema or payload migration. Applications continue using Persistence domain
+repositories. Direct Backend implementations and callers must migrate.
+
+| Previous extension point | SPI 2 |
+|---|---|
+| Eight repository keywords to Backend | `resources: [Resource, ...]` |
+| `backend.agents`, `backend.executions`, etc. | `backend.view.records(resource)`; domain names stay on Persistence |
+| Journal raw repository | `view.streams(resource)` with `Entry::Append` inputs |
+| Raw ContentStore repository | `view.blobs(resource)`; `ContentStore::StoredContents` owns digest behavior |
+| `Storage::Repositories` transaction view | `Storage::View` bound to a transaction scope |
+| `assert_agent_watermark!` on raw Backend | Agent-owned Watermark composes GuardRef, RevisionIs and StreamHeadIs |
+| ActiveExecutionConflictError | UniqueConstraintError with exact resource/constraint; NoRows condition for idle |
+| Three domain-named raw capabilities | spi_version 2 and six neutral capabilities |
+
+A driver implements the protected physical operations used by Records, Streams,
+Blobs and guards, plus `storage_transaction`. Reuse the common scope lifecycle;
+do not override `transaction` with a view that bypasses it. Return independent
+Entry values and never decode domain payload to reconstruct index metadata.
+A non-subclass backend must provide the same public protocol and semantics.
+The SQL reference driver receives immutable physical mappings independently of
+resource declarations; no resource-ID case switch selects domain SQL behavior.
+
+Repository wrappers obtained inside a transaction expire with that transaction.
+Do not retain them in application objects. Cache root repositories/handles when
+needed: they route to the current transaction on the same thread. Recover from
+an operation failure only outside an explicit inner savepoint. Catching a failure
+inside its failed scope prevents further work and commit. Complete transaction
+blocks normally; return/break/throw raises TransactionError after rollback.
+
+Initial Workflow/Handoff saves still use expected_revision nil and return the
+existing domain result. Storage Records itself requires explicit insert versus
+replace. Missing required parent records now consistently raise NotFoundError;
+this closes prior InMemory/SQLite/PG differences for orphan raw writes. Nonempty
+keys and text attributes must be valid UTF-8 without NUL. Nullable unique keys
+are distinct. Domain Journal limit zero remains an empty result.
+
+Run the shipped domain and neutral conformance suites, the dedicated SPI 2/RBS
+checks and each physical driver's concurrency/failure tests. For PostgreSQL run
+the real server gate with the matching candidate core, then verify fresh-pool
+reload. Existing S2a CI is historical evidence, not validation of this SPI.

data/docs/migrations/parallel-tool-chat-removal.md

@@ -0,0 +1,49 @@
+# Removal of the internal parallel Chat path
+
+This change belongs to the incremental architecture refactor following 0.26.0.
+It does not publish a new gem version.
+
+## Application changes
+
+Remove assignments to `Phronomy.configuration.parallel_tool_execution`, including
+assignments inside `Phronomy.configure`. Both the reader and writer are removed;
+there is no compatibility accessor or replacement switch. The former setting
+selected a Chat subclass but did not gate concurrency in the Agent-owned Tool
+execution path. A previous value of `false` did not guarantee serial execution.
+
+`Phronomy::MultiAgent::ParallelToolChat` and its file are removed. Do not require
+the old file or instantiate that private class. No `Agent::ParallelToolChat`
+replacement or alias is introduced. Applications that need Agent-owned Tool
+approval, cancellation and execution tracking should enter through the Agent
+invoke/stream APIs. Direct RubyLLM chat use is outside that Agent lifecycle.
+
+## Retained behavior
+
+Both complete and streaming calls use ordinary `RubyLLM::Chat`. Before the first
+Tool body runs, the existing RubyLLM callback lets Agent capture every Tool call
+in the complete assistant message. Agent manages Tool authorization, approval,
+dispatch, cancellation and result collection under ADR-010 and ADR-024.
+
+On success, every result is associated with its original call ID and recorded
+in request order. All results are included in the next Provider request, after
+the batch completes. Runtime capacity and each Tool's execution mode still
+determine how work can overlap. This change does not introduce a serial Tool
+mode or a partial-result Provider continuation.
+
+The old direct-Chat fallback and its RubyLLM-specific callback/Halt behavior are
+removed with the private class. They are not a second supported Agent execution
+API. Agent-level event callbacks keep their existing contract.
+
+## Existing stored records
+
+New standard model-config records omit `parallel_tool_execution`. Existing
+ContentStore records and manifest hashes are not rewritten. An existing record
+may still contain that field; materialization preserves its bytes and Agent's
+Chat builder ignores it, just as it ignores other unused model-config fields.
+There is no manifest version change or compatibility branch that reinstates the
+removed Chat class.
+
+The regression suite checks materialization and Chat construction for stored
+records containing both historical boolean values. Existing recovery tests
+continue to cover the supported recovery contracts; this change does not add
+execution-resumption or external-effect guarantees.