phronomy 0.27.0 → 0.29.0

data/docs/decisions/015-tool-public-facade-and-rbs-boundary.md

@@ -9,7 +9,7 @@ Accepted.
 Phronomy has accumulated two related API-maintenance problems:
 
 1. Application-defined Tools are implemented by subclassing the internal-taxonomy
-   name `Phronomy::Agent::Context::Capability::Base`, even though the product
+   name `Phronomy::Tool::Base`, even though the product
    concept exposed to users is simply a Tool.
 2. The gem ships almost no RBS signatures, so the distinction between
    application APIs, extension SPIs, and private implementation objects is not
@@ -42,7 +42,7 @@ Phronomy::Tool::Base
 The existing implementation class remains:
 
 ```ruby
-Phronomy::Agent::Context::Capability::Base
+Phronomy::Tool::Base
 ```
 
 `Phronomy::Tool::Base` is an exact constant alias to that same class object. It
@@ -58,7 +58,7 @@ This preserves:
   name.
 
 Consequently, `Phronomy::Tool::Base.name` intentionally remains
-`"Phronomy::Agent::Context::Capability::Base"`. If a future public contract
+`"Phronomy::Tool::Base"`. If a future public contract
 requires the runtime class name itself to become `Phronomy::Tool::Base`, that is
 a separate migration decision.
 

data/docs/decisions/027-llm-adapter-provider-boundary.md

@@ -46,6 +46,8 @@ reconciliation must not silently promote its API stability.
 2. `Phronomy::LLMAdapter::Base#complete` and `#stream` are the public
    Provider-call extension boundary. Phronomy owns the framework-side
    asynchronous/offload wrappers around that synchronous adapter contract.
+   [ADR-059](059-backend-contracts-and-async-clients.md) locates those wrappers
+   in the private `LLMAdapter::AsyncClient`, separate from Base and RubyLLM.
 3. `Phronomy::LLMAdapter::RubyLLM` remains the default configured LLM adapter
    and RubyLLM remains Phronomy's default Provider integration.
 4. A custom LLMAdapter may replace Provider-call behavior, but the LLMAdapter

data/docs/decisions/030-agent-handoff-domain-and-durable-responsibility.md

@@ -1,5 +1,7 @@
 # ADR-030: Agent Handoff Domain and Durable Responsibility
 
+> r8 unit 4 supersedes the Agent/Handoff ownership and storage portions below. See [the unit 4 migration](../migrations/r8-unit4.md). Earlier statements describe their original change only.
+
 ## Status
 
 Accepted. V2 revision 2, 2026-09-06.

data/docs/decisions/031-durable-multi-agent-coordination.md

@@ -1,5 +1,7 @@
 # ADR-031: Durable Multi-Agent Semantic Coordination
 
+> Agent/MultiAgent ownership is amended by [ADR-064](064-agent-execution-and-multi-agent-responsibility.md).
+
 ## Status
 
 Accepted. V2 revision 2, 2026-09-06.

data/docs/decisions/032-storage-backend-composition.md

@@ -9,6 +9,11 @@ The raw fixed-repository/error portions are amended by
 [ADR-058](058-neutral-storage-primitives.md). Domain ownership and applicable
 transaction/uncertainty decisions below remain in force.
 
+Domain-facing exception ownership is further amended by
+[061-persistence-failure-contracts](061-persistence-failure-contracts.md).
+Raw backend exceptions remain owned by Storage; domain repository exits now
+translate their known categories to independent Persistence exceptions.
+
 ## Context
 
 The previous `Persistence` class combined raw storage contracts with domain

data/docs/decisions/034-handoff-runner-coordination-ownership.md

@@ -1,5 +1,7 @@
 # ADR-034: Handoff Runner Coordination Ownership
 
+> r8 unit 4 supersedes the Agent/Handoff ownership and storage portions below. See [the unit 4 migration](../migrations/r8-unit4.md). Earlier statements describe their original change only.
+
 ## Status
 
 Accepted for the H1 step on `refactor/architecture`, 2026-09-18.

data/docs/decisions/035-tool-executor-capability-ownership.md

@@ -28,7 +28,7 @@ public compatibility decision.
 ## Decision
 
 1. Move the helper to
-   `Phronomy::Agent::Context::Capability::ToolExecutor`, in
+   `Phronomy::Tool::ToolExecutor`, in
    `agent/context/capability/tool_executor.rb`. Classify this helper as private
    API and remove the old internal constant without a compatibility alias.
 2. Use the new helper from Capability Base and Agent ToolInvocation. Preserve

data/docs/decisions/038-responsibility-based-source-layout.md

@@ -1,5 +1,11 @@
 # ADR-038: Responsibility-Based Source Layout
 
+> Current boundary: r8 unit 6 supersedes the historical Chat/SDK ownership and
+> adapter extension SPI below. Agent uses LLMAdapter values; the backend owns SDK
+> construction/interception; Tool owns canonical schema validation. See
+> `docs/architecture/r8-unit6.md` and `docs/migrations/r8-unit6.md`.
+
+
 ## Status
 
 Accepted on the architecture refactoring branch; configuration/runtime lifecycle
@@ -17,6 +23,14 @@ Amends the extraction scope of
 [037-common-definition-ownership](037-common-definition-ownership.md).
 Its common-ownership rule and public Error contract remain unchanged.
 
+## Amendment: neutral runtime settings
+
+[060-runtime-settings-and-application-configuration](060-runtime-settings-and-application-configuration.md)
+amends configuration placement and Engine access: application configuration and
+global accessors belong to `runtime_composition/`, while `configuration/` owns
+only neutral `RuntimeSettings`. Concrete defaults remain composition-owned;
+public configuration and Runtime reset behavior remain unchanged.
+
 ## Context
 
 The application loading entry point and the direct `lib/phronomy/` directory

data/docs/decisions/039-runtime-configuration-lifecycle-ownership.md

@@ -13,6 +13,14 @@ Amends the configuration ownership in
 Its loading rules, direct-root allowlist, and compatibility requirements remain
 in force.
 
+## Amendment: neutral runtime settings
+
+[060-runtime-settings-and-application-configuration](060-runtime-settings-and-application-configuration.md)
+amends configuration placement and Engine access: application configuration and
+global accessors belong to `runtime_composition/`, while `configuration/` owns
+only neutral `RuntimeSettings`. Concrete defaults remain composition-owned;
+public configuration and Runtime reset behavior remain unchanged.
+
 ## Context
 
 `Phronomy.reset_runtime!` shuts down the default Runtime and replaces global

data/docs/decisions/040-configuration-default-composition.md

@@ -11,6 +11,14 @@ Their loading, public compatibility, and Runtime reset rules remain in force.
 The provider-call and framework-owned async boundary in
 [027-llm-adapter-provider-boundary](027-llm-adapter-provider-boundary.md) is unchanged.
 
+## Amendment: neutral runtime settings
+
+[060-runtime-settings-and-application-configuration](060-runtime-settings-and-application-configuration.md)
+amends configuration placement and Engine access: application configuration and
+global accessors belong to `runtime_composition/`, while `configuration/` owns
+only neutral `RuntimeSettings`. Concrete defaults remain composition-owned;
+public configuration and Runtime reset behavior remain unchanged.
+
 ## Context
 
 `Configuration` holds settings read by Engine and other framework components.
@@ -72,7 +80,10 @@ runtime factory invocation. Construction does not call `Runtime.instance`:
 the adapter's default pool is acquired later when an async method is called.
 The previous graph cycle was not infinite constructor recursion.
 
-`LLMAdapter::Base` still owns framework async wrappers and references Runtime.
+At this decision's implementation point, `LLMAdapter::Base` still owned the
+framework async wrappers and referenced Runtime.
+[ADR-059](059-backend-contracts-and-async-clients.md) subsequently moves that
+dependency to the private `LLMAdapter::AsyncClient`.
 Runtime, pools, tracing, and Agent retain other dependencies and cycles. This
 step does not claim complete provider independence or an acyclic repository.
 

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

@@ -5,6 +5,10 @@
 **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)
 
+Source placement is superseded by [ADR-063](063-execution-contracts-and-services.md):
+the same marker now lives in `execution/concurrency/`. Its namespace,
+18-type inventory and worker-input behavior remain unchanged.
+
 ## Problem
 
 Tool authorization snapshots exclude framework-managed live objects from value

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

@@ -1,5 +1,7 @@
 # ADR-051: Execution Outcome Worker Ownership
 
+> Handoff specialization and commit proof are amended by [ADR-064](064-agent-execution-and-multi-agent-responsibility.md).
+
 **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),

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

@@ -30,7 +30,7 @@ The private session protocol is:
 - `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.
+  `Phronomy::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

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

@@ -6,6 +6,11 @@ Accepted. Applied and verified in Refactor 35 (Storage S2b/S2c), core
 `ebd99623f94c8b2db2d74355bfa39f01550778a0` and examples
 `68a0bbd0e354b9e00bbfed728ad2b769b389ed8a`.
 
+Domain-facing exception ownership is further amended by
+[061-persistence-failure-contracts](061-persistence-failure-contracts.md).
+Raw backend exceptions remain owned by Storage; domain repository exits now
+translate their known categories to independent Persistence exceptions.
+
 ## Context
 
 S1 inventoried 37 raw methods across eight required domain slots. Moving their

data/docs/decisions/059-backend-contracts-and-async-clients.md

@@ -0,0 +1,74 @@
+# ADR-059: Backend Contracts, Implementations and Execution Clients
+
+## Status
+
+Accepted; P1/P2/P3/P4 (LLM, VectorStore, Embeddings, Storage/ContentStore and
+diagram tooling) implemented. Final P5 review remains pending, as recorded in
+[Backend responsibilities](../architecture/backend-groups.md).
+
+ContentStore's classification and directory split are superseded by
+[ADR-062](062-content-store-service.md): content management is a service over
+Storage, outside Backend Contracts and Backend Implementations. The other
+contract/client/backend separations remain in force.
+
+## Context
+
+The synchronous LLMAdapter SPI and its RubyLLM implementation shared a directory
+with private async methods that referenced Runtime. Adapter authors were told
+to implement only synchronous methods, but Base still coupled the SPI to Engine.
+Numbered diagram bands also implied an ordering between independent concerns.
+
+## Decision
+
+1. Use independent responsibility groups with stable identifiers. Engine,
+   Contracts, Async Clients and Implementations are distinct; coordinates and
+   group numbers do not define dependency permissions. For readability, restore
+   the earlier B1-B6 horizontal display bands and topical columns; these are
+   presentation metadata independent of the responsibility annotations. Place
+   separated Contracts in B5, distinct from Engine, and Async Clients in B4.
+   Keep Implementations separately grouped in B4; mark unsplit backends there
+   as pending instead of presenting their contracts as already separated.
+2. Keep `LLMAdapter::Base` synchronous. Move internal async wrappers into
+   `LLMAdapter::AsyncClient`; Agent supplies its configured adapter to the client.
+   The public SPI, configuration setting and RubyLLM constant remain unchanged.
+3. Separate contract/client/implementation directories, using explicit Zeitwerk
+   collapse to retain feature namespaces. Do not make a common Async namespace,
+   add a Base-to-client factory, or install an include/prepend compatibility hook.
+4. Implementations depend on Contracts. Contracts and implementations do not
+   reference Engine or clients; clients use Contracts and Engine through normal
+   constant references or object injection, without selecting concrete providers.
+5. Preserve original TaskResult, non-waiting admission failure, token semantics,
+   no additional operation timeout, provider-owned retries and EventLoop callback
+   delivery. Resolve the default pool at operation time; do not cache it across
+   Runtime resets. Explicit pool injection leaves lifecycle ownership to its owner.
+6. Generate SVG and boundary evidence from each committed source revision.
+   Maintain the individual module boxes, IDs, full dependency matrix and source
+   evidence. A phase cannot declare completion while legacy dependencies remain.
+
+The vector/embedding SPI and namespace clauses are amended by
+[ADR-065](065-vector-and-embeddings-common-operations.md).
+
+## Consequences
+
+This supersedes the remaining LLM Base-to-Runtime coupling described in ADR-040.
+ADR-027's synchronous public provider-call boundary and materialization caveat
+still apply: this change does not make RubyLLMMaterializer provider-neutral.
+P2 keeps the LLM client internal. P3 introduces public VectorStore/Embeddings
+AsyncClients and moves async receivers off the synchronous backends. Their
+argument conventions and execution semantics are unchanged; the receiver
+migration is intentional and documented. Storage operations do not change in
+P3. P4 adds public raw `transaction_async` and a private submit path for existing
+Agent/Workflow/coordination units. The latter opens no transaction and leaves
+uncertain-result policy with each owner. P4 originally moved ContentStore's
+implementation into a backend directory; ADR-062 removes that unnecessary split
+and classifies it as a content service. Other repository cycles remain visible.
+
+Transparent module/caption panels and hidden incoming arrows to M33/M41/M44 are
+presentation settings only. The full measured graph, matrix and boundary rules
+remain unchanged by that filtering.
+
+Boundary tests cover direct and indirect reverse dependencies and keep group
+IDs independent from policy. Runtime tests cover sync-only custom adapters,
+worker/EventLoop separation, rejection, exceptions, cancellation and Runtime
+reset. CI produces artifacts with the actual source SHA rather than committing
+a diagram containing its own commit hash.

data/docs/decisions/060-runtime-settings-and-application-configuration.md

@@ -0,0 +1,86 @@
+# ADR-060: Runtime Settings and Application Configuration
+
+## Status
+
+The settings membership is amended by
+[r8 unit21](../architecture/r8-unit21.md): Tool owns its result limit and Tracing
+owns tracer/recording settings. RuntimeSettings retains logger and execution
+resource values. The original decision below records the earlier checkpoint;
+lazy composition, public compatibility and the strict dependency rules remain.
+
+Accepted for this refactoring. Amends the configuration ownership in
+[038-responsibility-based-source-layout](038-responsibility-based-source-layout.md),
+[039-runtime-configuration-lifecycle-ownership](039-runtime-configuration-lifecycle-ownership.md)
+and [040-configuration-default-composition](040-configuration-default-composition.md).
+
+## Context
+
+Engine consumes pool sizes, time thresholds, a logger and an injected tracer.
+Application `Configuration` also exposes an LLM adapter, Agent input hook and
+other domain options. Their correct public RBS types reveal an Engine-to-domain
+path when Engine reads the whole Configuration. A two-reference baseline allowed
+this old type debt through the regression gate. Weakening the types, hiding
+arrows or misassigning RBS owners would not repair the dependency.
+
+## Decision
+
+1. `configuration/` owns private `RuntimeSettings`: neutral runtime values and
+   injected logger/tracer objects, with no application-specific type references.
+   Engine and automatic tracing read this limited object.
+2. Application `Configuration` and the global `configuration`, `configure`,
+   `reset_configuration!` and `with_configuration` operations belong to
+   `runtime_composition/`. Canonical Ruby names, constructor and public RBS types
+   remain unchanged. The directory is collapsed by Zeitwerk; no public
+   `RuntimeComposition` namespace is introduced.
+3. Configuration composes RuntimeSettings and explicitly delegates its existing
+   runtime-setting accessors. It retains adapter, Agent and application options.
+   RBS follows the actual Ruby owner: application declarations live under
+   `sig/phronomy/runtime_composition/`, internal settings under `sig/_private/`.
+4. Composition installs a lazy, typed provider returning only RuntimeSettings.
+   Every read resolves the current object so reset/scoped restoration cannot
+   leave Engine reading an expired configuration. Binding does not initialize
+   global configuration or start Runtime. This provider is private framework
+   wiring, not an application extension point or a new execution service.
+5. Copying Configuration copies its settings container while retaining injected
+   component identities. This preserves the previous flat object's shallow-copy
+   behavior, including nested scopes, exception restoration and a first scope
+   entered before global configuration exists. This change adds no thread-local
+   configuration semantics or live pool resizing.
+6. Remove the two-reference baseline. Require the complete Ruby + RBS union to
+   pass all existing responsibility rules. Also reject settings paths reaching
+   any non-common responsibility.
+
+## Direct dependencies are evaluated by responsibility
+
+LLM error/TokenUsage contracts are already abstract vocabulary, so routing them
+through a concrete adapter would make coupling worse. Backend implementation,
+schema, migration, async bridge and conformance-suite dependencies on Storage
+contracts are intentional. Domain repositories translate records, guards and
+backend errors and legitimately know that SPI.
+
+Domain runners that raise StorageConflictError for ownership/revision decisions
+are a separate candidate for a persistence/domain error contract. Existing
+recovery distinguishes known failure from uncertain commit outcomes; introduce
+such a vocabulary only with an explicit compatibility and failure-classification
+design. Do not substitute a forwarding wrapper or broadly catch StandardError.
+
+Engine's TaskResult, Runnable and FSM contracts are the execution abstractions
+used by runners and async clients. A higher-level Agent facade is not a
+replacement for the mechanism that implements Agent itself. Ordinary synchronous
+evaluation work can use `Blocking.call_async`: LlmJudge now does so instead of
+accessing Runtime's pool. Dedicated-pool cleanup, concurrency-limited orchestration
+and tracing with nonwaiting admission handling retain their specialized owners.
+
+## Verification and graph interpretation
+
+Preserve public signature declarations, settings defaults/accessor semantics,
+subclass construction, cold loading, reset/scoped restoration and runtime pool
+configuration. Check scorer provider/admission failures, the full regression
+suite, RBS validation and strict dependency rules. No network provider is needed
+for these behavior checks.
+
+SVG topology must show the actual declaration owners and keep all evidence,
+even for display-hidden arrows. Application configuration shares the composition
+directory with lifecycle/default wiring; its directory SCC may grow because
+unrelated members aggregate. Report directory SCCs and Ruby file SCCs separately;
+do not claim that all cycles have disappeared or that fewer arrows is the goal.

data/docs/decisions/061-persistence-failure-contracts.md

@@ -0,0 +1,89 @@
+# ADR-061: Domain Persistence failure contracts
+
+- Status: Accepted
+- Date: 2026-09-26
+- Amends: [032-storage-backend-composition](032-storage-backend-composition.md) and [058-neutral-storage-primitives](058-neutral-storage-primitives.md), only for the exception surface exposed above raw Storage.
+
+## Context
+
+Agent execution, ownership, Handoff, Recovery, Team coordination and Workflow
+interpret durable failures, but previously referenced raw Storage exception
+classes even when they did not perform raw storage operations. A domain state
+contradiction and a physical compare-and-swap rejection had the same owner.
+Moving or aliasing those classes would keep backend and domain contracts coupled.
+
+## Decision
+
+Define independent public errors in `persistence/contract/`, under the existing
+`Phronomy::Persistence` namespace: Error, ConflictError, StateConflictError,
+NotFoundError, SerializationError and UnsupportedBackendError. Error inherits
+Phronomy::Error. StateConflictError inherits Persistence::ConflictError; the other
+four categories inherit Persistence::Error. No class inherits a Storage error,
+and no compatibility alias is introduced. The contract depends only on Common.
+
+The selected upper domain consumers raise StateConflictError for their own
+ownership/revision/state contradictions. Backend CAS conflicts, including
+repository precondition conflicts, expose Persistence::ConflictError. Existing
+conflict retry/catch sites also accept StateConflictError by inheritance.
+
+An internal `Persistence::StorageBoundary` maps exactly four Storage categories
+(ConflictError, NotFoundError, SerializationError, UnsupportedBackendError) to
+the corresponding Persistence category. It preserves message and backtrace and
+sets the original exception as `cause`. Mapping happens at domain repository
+exits and Persistence construction/transaction exits. Existing repository-local
+constraint interpretation runs first: only the matching active-owner unique
+constraint or exact NoRows condition becomes AgentBusyError. Other raw conflict
+subclasses map to Persistence::ConflictError with their metadata in `cause`.
+
+Domain repositories continue to own codecs and record validation. Decode checks
+remain inside the physical atomic block, so a malformed write response still
+rolls back before translation. The translator creates no transaction or task.
+The same boundary covers root and transaction repository views, watermark checks,
+and persisted manifest reading. A private ContentRepository adapts the existing
+StoredContents primitive methods for the upper failure contract; the independent
+ContentStore backend retains its content identity and integrity semantics.
+
+Unknown exceptions, Storage::TransactionError, ContentStore::IntegrityError,
+AgentBusyError and already translated Persistence errors pass through unchanged.
+Persistence::Error is a base type, not a blanket known-not-committed classifier.
+Each existing caller retains its exact category set, including intentional
+three-category/four-category differences and ArgumentError/ConfigurationError.
+A lost commit acknowledgement must not become a known rejection or trigger a
+new retry. F0/F1/F4 recovery and X0 limitations are unchanged.
+
+## Loading and ownership
+
+Contracts can be loaded without Storage, Engine, Agent or a driver. Ordinary
+framework loading explicitly installs the canonical Persistence service before
+Zeitwerk setup, so an earlier contract load cannot suppress service methods or
+change class identity. This does not construct a backend or start a Runtime.
+The API class is still defined in `persistence/api/persistence.rb`. Namespace
+reopenings in helpers are not its declaration owner for dependency analysis.
+
+## Public migration and preservation
+
+Calls through Persistence now expose Persistence errors rather than Storage
+errors. This is an intentional public exception contract change; applications
+must migrate relevant rescue clauses. Raw backend/driver code keeps Storage
+errors. See the [migration guide](../migrations/persistence-failure-contracts.md).
+
+Existing public method/RBS declarations remain; six error classes are added.
+SPI 2, tables, record envelopes, revisions, content IDs and all eight repository
+transaction semantics remain unchanged. Stored error class names are diagnostic
+data: new failures may name Persistence errors, while old saved names remain
+readable without rewriting or constantizing them.
+
+## Verification and diagram
+
+Tests inject real backend failures through all eight repository accessors and
+check cause/trace, no double translation, unknown-error identity, commit-response
+loss, nested savepoints, post-write validation rollback and AgentBusyError.
+Existing domain recovery, admission, conformance and integration suites remain
+required. Raw Storage isolation tests continue to reject domain/Engine loading.
+
+Ruby + RBS boundary validation rejects raw Storage references from the eight
+reviewed upper directories and rejects non-Common reachability from Persistence
+Contracts. It does not whitelist the new dependencies. G55 shows the translation
+boundary and G56 the independent domain failure contracts in the existing banded
+layout. All measured edges remain in evidence and the matrix; presentation-only
+incoming-arrow filters do not change boundary results.

data/docs/decisions/062-content-store-service.md

@@ -0,0 +1,52 @@
+# ADR-062: ContentStore is a content service over Storage
+
+- Status: Accepted
+- Date: 2026-09-28
+- Amends: ADR-059's ContentStore classification and source subdivision only.
+
+## Context
+
+ContentStore was grouped with synchronous backend contracts, and StoredContents
+with physical backend implementations. InMemory and SQL instead implement
+Storage::Backend. Composition always constructs StoredContents over that
+backend's view. ContentStore adds content-derived IDs, canonical text/JSON and
+digest verification; it is not another physical-storage selection point.
+
+## Decision
+
+Treat `content_store/` as a content management service. Move StoredContents from
+`content_store/backends/` into this directory, next to Base and StorageSchema.
+Delete the empty backend subdivision and its Zeitwerk collapse, without a
+forwarding file, alias or alternative implementation-selection API.
+
+Keep Base: both StoredContents and Persistence::ContentRepository use its shared
+text/JSON operations. Keep ContentRepository: it translates known Storage
+failures at the Persistence boundary. These classes are used responsibilities,
+not obsolete backend scaffolding. StorageSchema is owned by the content service.
+
+Retain the dependency from the service to neutral Storage. Storage owns physical
+I/O, immutable blobs and transactions. The content service must not select a
+physical backend or depend on Engine, Async Clients or domain orchestration;
+Storage contracts and implementations must not depend on the content service.
+
+## Compatibility and presentation
+
+Public constants and RBS, private constant identities, content IDs, resource IDs,
+database schema, exception behavior and root/transaction composition stay the
+same. In particular, StoredContents' missing-content errors are still raw Storage
+errors, translated by the Persistence facade. This change does not introduce an
+independent ContentStore exception contract or alter commit uncertainty policy.
+
+M10 moves to G57 Content Service, displayed in B3's persistence column. M73 is
+retired and never reused. G47/G48 contain no ContentStore modules. Keep the
+existing banded layout, group colors, module outlines, transparent text panels
+and presentation-only common-arrow filters. Preserve every measured Ruby/RBS
+edge, including the service-to-Storage edge; compare counts knowing that two
+source directories have become one. Historical baseline evidence is immutable.
+
+## Verification
+
+Existing loading, content, Persistence conformance and transaction tests cover
+the source move. The full Ruby + RBS boundary gate allows the intended Storage
+dependency and rejects direct/indirect reverse or concrete-backend coupling.
+The independent architecture regression also injects RBS-only violations.

data/docs/decisions/063-execution-contracts-and-services.md

@@ -0,0 +1,88 @@
+# ADR-063: Execution Contracts, Services and Engine Internals
+
+> Historical decision. Superseded by [r8 unit 1](../architecture/r8-unit1.md): Execution contracts and services are now united, with mechanism binding in Engine.
+
+**Status**: Accepted for implementation
+**Date**: 2026-09-28
+**Refines**: [038-source-layout](038-responsibility-based-source-layout.md),
+[045-worker-input](045-worker-input-restriction-ownership.md) and
+[059-backend-groups](059-backend-contracts-and-async-clients.md)
+
+## Problem
+
+Engine grouped public result/call APIs, shared value/error/marker contracts and
+private schedulers together. A WorkerInputRestricted include or an RBS token
+reference consequently appeared to be a dependency on worker machinery.
+ToolBinding also implemented its own result transformation. It forwarded the
+source's physical-completion signal before the result filter had finished;
+Agent execution quiescence could therefore observe an incomplete transformation
+as physically complete.
+
+## Decision
+
+Keep public constants and split source ownership into three responsibility groups:
+
+| Group | Directory | Owns |
+|---|---|---|
+| G58 Execution Contracts | `execution_contract/`, `execution_contract/concurrency/` | Runnable, InvocationContext, Event, FSMProtocol, shared failures, CancellationToken and WorkerInputRestricted |
+| G59 Execution Services | `execution_services/` | TaskResult, Execution, Blocking, and outcome-bearing execution errors |
+| G14 Engine Internals | `engine/`, `engine/concurrency/`, `engine/runtime/` | Runtime, EventLoop, FSMSession, receivers, pools, queues and control/result-composition machinery |
+
+Zeitwerk collapses the two new root directories. Existing `Phronomy::*` and
+`Phronomy::Concurrency::*` constants keep their identity, signatures and
+behavior. No new public namespace or forwarding file is introduced. Public RBS
+declarations remain in `sig/` but follow their actual source owners.
+
+Contracts may depend only on Execution Contracts and Common responsibilities,
+including neutral RuntimeSettings. This is a boundary contract, not a claim
+that every class is methodless: CancellationToken retains its existing state
+and callbacks, and Runnable retains its default tracing switch. InvocationContext
+can carry opaque execution bindings without constructing a scheduler.
+
+Execution Services contain real implementation. TaskResult uses Engine's result
+composition and wait guards; Engine pools create TaskResults. This mutual
+dependency remains explicit. The split does not assert an acyclic layer
+hierarchy. Backend Contracts and implementations may not reach either services
+or Engine, including through RBS references.
+
+ToolBinding delegates callback-based transformation to a private TaskResult
+entry point backed by ResultComposition. Physical completion now requires both
+source physical completion and transformation completion. The callback-only
+path preserves custom result handles, failure identity, name, no inherited
+execution scope, and the existing behavior that cancelling the filtered result
+does not cancel its source or suppress the later filter. Public map/flat_map
+scope and parent semantics are unchanged.
+
+Tracing finish and approval notification use Blocking.call_async for generic
+default-pool work. Both observe the returned failure because Blocking converts
+admission errors into failed results. Approval callbacks that fail after dispatch
+are now also logged. Checks that only ask whether code runs on EventLoop use
+Runtime.in_event_loop_context?, avoiding construction of a Runtime merely to
+answer that question.
+
+## Retained direct dependencies
+
+AsyncClients are execution bridges and retain Runtime/pool access, specialized
+pools, tokens and result types. Agent/Workflow runners and registries still own
+FSM sessions, control delivery, single-writer state and lifecycle coordination.
+Replacing these with a generic wrapper would conceal required ownership rather
+than remove it. Registry receiver lookup is not redesigned in this change.
+See the [usage inventory](../architecture/execution-boundaries.md).
+
+## Compatibility and verification
+
+`require "phronomy"` remains the public loading contract. Old implementation
+file paths move without compatibility shims. Public signatures and API snapshot,
+transactions, pool admission policy and timeout/cancellation ownership are
+unchanged. No backend author must implement another async method.
+
+Test blocked success/failure filters against a real pool, cancellation and custom
+completion handles; rejected tracing/approval dispatch and asynchronous callback
+failure; standalone marker loading and eager loading without Runtime creation;
+the public signatures and full Ruby/RBS boundary graph. Existing unit,
+integration, coverage, style, benchmark and SQLite contracts remain required.
+
+The measured SVG retains B1-B6 display bands, pastel group backgrounds, module
+boxes and transparent text. G59 is in B4 and G58 in B5; these positions grant
+no dependency permission. Incoming M33/M41/M44 arrows remain visually hidden
+while every dependency stays in the matrix, audit and boundary checks.

data/docs/decisions/064-agent-execution-and-multi-agent-responsibility.md

@@ -0,0 +1,36 @@
+# ADR-064: Agent execution and MultiAgent responsibility
+
+Status: accepted for the r8 unit 4 implementation. This amends the Handoff and
+coordination ownership portions of ADR-030, ADR-031, ADR-034 and ADR-051.
+Acceptance records the authorized design; database validation is reported separately.
+
+Agent owns execution identity, durable admission, semantic observations, finalized
+input projection, dispatch prerequisites, terminal changes, retention and
+cancellation intent. MultiAgent owns subagent slot reservations/import progress
+and Handoff policy, routing, target reservations and history lifecycle.
+
+A versioned, synchronous participant joins Agent's `ExecutionChange` in one outer
+Persistence scope. It receives semantic inputs, acquires ordered guards, captures
+the pre-state through `prepare_in`, writes its own records and invokes `commit_in`
+once. Agent owns validation, record writes and publication after commit. Complete
+before/after evidence reconciles ambiguous responses; revision equality alone
+does not prove success. No generic raw-record update hook or compatibility alias
+is introduced.
+
+Current application wiring is supplied on resume/load and is never serialized.
+A saved extension records only binding key, version and content reference.
+MultiAgent calls exact execution APIs rather than Agent repositories or private
+recovery machinery. Persisted holds prevent purge until the referencing domain
+atomically removes its history and releases its own holds.
+
+AgentExecution format 0.2 replaces old coordination metadata. An explicit,
+quiescent export/convert/import/verify process preserves IDs, revisions, content
+and unresolved outcomes in a separate destination. Runtime does not interpret
+old formats. The shared SQL drivers provide runnable migration and rejection of
+populated destinations. The complete migration path must be tested on each
+production backend before cutover.
+
+Runtime shutdown/AdmissionRegistry and other Engine dependencies remain later r8
+work. The measured source graph continues to expose them. See
+[implementation responsibilities](../architecture/r8-unit4.md) and
+[API/data migration](../migrations/r8-unit4.md).