phronomy 0.26.0 → 0.28.0

data/docs/architecture/entry-action-and-team-wording.md

@@ -0,0 +1,72 @@
+# Entry-action names and Team task wording (R10)
+
+## Scope
+
+Refactor 44 follows applied Refactor 43, core
+`5c4c039273eb2324fcc9e9943ccf40bd1ffb3abd`. It changes two private action names
+and two Team-generated strings. No new production class, alias, state, event,
+loader rule, persistence format or public method signature is introduced.
+
+## Action names describe their local work
+
+| Existing phase | Private action | Work |
+|---|---|---|
+| `filtering_input` | `apply_prepared_input_action` | Read `phronomy_filtered_input` from the prepared config and install it on the invocation. |
+| `building_context` | `build_runtime_chat_action` | Build a Chat with the prepared projection's settings and apply its instructions, Tools and messages. |
+
+These replace `filtering_input_action` and `building_context_action` respectively.
+Their bodies, arguments, return values, exceptions and ordering are unchanged.
+Input filtering and context preparation remain with the existing preparation
+owners; these actions do not repeat that work. The first action keeps its unused
+Agent argument so the existing bound-action construction remains unchanged.
+
+Phase names, transition guards, callbacks and saved resume phases remain intact.
+A phase is an existing lifecycle boundary; an entry-action name describes the
+operation performed at that boundary. Renaming phases would require a separate
+compatibility design for observation and saved executions.
+
+## Team tasks and completion handles
+
+| Surface | Before | After |
+|---|---|---|
+| `finalize.summary` parameter description | `TaskResult summary` | `Task generation summary` |
+| Newly committed `enqueue_task` result | `TaskResult #N enqueued: ...` | `Task #N enqueued: ...` |
+
+These are observable text changes, not solely internal renames. The description
+is sent to the LLM. The enqueue response is saved in Team operation metadata and
+subsequently supplied as a Tool result. The task description supplied by the
+caller is not rewritten. Tool names, argument names, types, optionality, task IDs,
+batch ordering, queue contents and cancellation behavior are unchanged.
+`Phronomy::TaskResult` continues to mean the asynchronous completion handle.
+Team integration examples now use `Task A/B/C` for business-task descriptions.
+
+The existing operation-ID deduplication returns the stored result verbatim.
+Already committed legacy `TaskResult #...` results therefore remain unchanged
+on replay, including after restart. This change does not migrate old records,
+rewrite Journals or reformat results during readback. Reusing an operation ID
+with different arguments still fails the existing identity check.
+
+## Verification and limits
+
+The package checks the existing Agent transition and Chat contracts, durable
+Team execution, full core/integration suites, offline examples, real SQLite,
+API/SPI, types, style, gem loading and independent application. One additional
+regression verifies legacy response replay after restart, no repeated writes,
+the TaskResult return type and argument-identity rejection. It also passes on
+the applied baseline.
+
+Separate processes capture a committed finalize operation before its Agent
+settlement and resume it using the other version, in both directions. Stored
+operations remain byte-equivalent at the value level, tasks are not duplicated,
+and the expected two remaining Provider calls occur. These are stubbed Provider
+checks with an InMemory snapshot; they are not live-LLM or cross-version SQL tests.
+
+The review exposed an existing [Tool schema recording gap](tool-schema-recording-gap.md)
+on RubyLLM 1.16.0. R10 does not repair it or weaken definition checks. Successful
+continuation here does not prove that incompatible parameter definitions are
+rejected. The generated parameter description changes, while the current saved
+Tool definition omits parameter details.
+
+R09 is applied and verified. R10 is implemented and locally verified, pending
+application verification. The newly discovered schema issue remains open, so
+closing the original R/D inventory must not be described as absence of defects.

data/docs/architecture/execution-abstraction-review.md

@@ -0,0 +1,88 @@
+# Execution abstraction revision (local review candidate, 2026-09-29)
+
+This candidate supersedes the unapplied Results split. It is based on main
+653e255a, with the earlier execution-boundary prototype included. It is not a
+record of application to main. The historical D02 reports describe their original
+revisions; the control ownership decision below supersedes them for this candidate.
+
+## Responsibilities
+
+| Owner | Owns | Consumers should know |
+|---|---|---|
+| Execution Contracts (G58, B5) | Context, TaskResult/Outcome, cancellation/deadline values, shared errors, neutral scope/result implementation | Public inputs, result handles and errors |
+| Execution Services (G59, B4) | Fan-out, child control lifetime, invocation admission checks, completion adaptation, worker submission and deadline registration | Start/observe APIs and domain value/error policies |
+| Engine Internals (G14, B5) | Runtime resources, EventLoop, FSMSession | Only runner/lifecycle/composition owners connect here |
+| Engine Concurrency (G61, B5) | Pools and queues | Engine supplies scheduling and wait-policy context |
+
+Bands are visual organization, not a dependency order. Backend Contracts remain
+in B5. `execution_contract/errors`, `execution_result` and
+`execution_result/concurrency` are removed. Their neutral implementation is
+integrated into the existing `execution_contract` and its `concurrency` child.
+M79/M80/M81 and G60 are retired. TaskResult is not returned to Services: doing so
+would recreate Engine→Services. The two contract directories remain mutually
+referencing within G58; the design does not claim zero cycles or pure declarations.
+
+## Actual hiding, beyond renaming dependency hubs
+
+| Consumer | Previous knowledge | Current entry point |
+|---|---|---|
+| Agent::ExecutionCoordinator | Extracted context scope, checked open/cancelled state, selected scope error | InvocationControls.attach + check_start!; Agent still owns admission and its result production |
+| MultiAgent::Orchestrator | Called Execution's private fan-out, constructed OperationBinding, linked tokens, selected context, closed subscriptions | Execution.run_async(max_concurrency:) + start_child; supplies child invocation |
+| Tools::Agent / generated subagent tools | Created deferred result and relayed completion/failure callbacks | AsyncOperation.call/capture; supplies output/error policy |
+| Agent::ToolBinding | Called TaskResult.__map_completion, a special internal composition path | AsyncOperation.map; supplies filters |
+| Workflow builder (earlier included change) | Used FSM's finish vocabulary | Workflow::Completion; runner translates to FSM |
+
+InvocationControls extends the existing service helper and absorbs the removed
+OperationBinding's lifetime logic. It is not a pass-through factory that still
+forces callers to manage cleanup. AsyncOperation encapsulates notification
+multiplicity, startup/transformation failure, and physical completion. Domain
+consumers still legitimately depend on TaskResult return types and cancellation
+inputs; hiding those via aliases would not improve the abstraction.
+
+ExecutionCoordinator, WorkflowRunner and durable reconciliation coordinators
+remain result producers. Their lifecycle, registry and terminal policy code has
+not all been turned into a generic facade. The public user-facing async APIs and
+backend contracts retain their namespaces.
+
+## Investigation heuristic
+
+Detect each M0→M1, M1→M2, M0→M2 triangle in the complete Ruby + RBS graph.
+Prioritize adjacent descending display bands, then other descending bands, then
+all remaining graph triangles. Keep sidebar modules and visually hidden arrows.
+Do not remove edges or make a triangle a CI violation solely on that basis.
+
+For M0's direct M2 usage, inspect its actual source operation:
+
+- Internal detail: Orchestrator linked child tokens and closed subscriptions;
+  Execution now owns this through start_child.
+- Connection: a runner registers its session with Runtime; this can belong to
+  that runner. Move it only if its current owner mixes unrelated responsibilities.
+- Shared/public contract: AsyncClient returns TaskResult and callers handle its
+  result. Keep the declared RBS dependency instead of erasing the type.
+
+Multiple M1 paths may identify the same direct edge. Reports include both the
+triangle count and the number of distinct M0→M2 pairs. RBS-only direct edges are
+marked, not automatically accepted. Directory aggregation can combine different
+classes/functions, so a graph path is not proof of a call chain. Dynamic dispatch
+can also leak details without any constant-reference triangle.
+
+`dependency_triangles.json` preserves all three edges' source evidence;
+`dependency_triangles.csv` is the review queue. Entries start as unreviewed.
+A separate narrow AST regression gate rejects the already-corrected private
+scope methods and selected consumers' manual result settlement. It does not
+purport to detect every possible abstraction leak.
+
+## Compatibility and verification scope
+
+Execution.run/run_async accept additive max_concurrency. No new backend methods
+are required from application authors. The included earlier candidate removes
+InvocationContext#effective_timeout_token/#effective_cancellation_token and the
+internal Deadline#attach_to, CancellationScope, old FSM vocabulary ownership.
+This revision removes internal OperationBinding and TaskResult.__map_completion.
+There are no backward aliases that point neutral contracts back at services.
+
+Tests cover bounded admission, cancellation before queued start, explicit child
+context identity, cleanup after completion/start failure, duplicate callback
+notifications, original error identity, recovery errors, and physical completion.
+Existing Agent, Tool, Workflow, persistence/recovery and async tests remain gates.
+The delivered evidence report records actual execution results and limitations.

data/docs/architecture/execution-boundaries.md

@@ -0,0 +1,28 @@
+# Execution dependency ownership
+
+Use the highest existing operation that expresses the caller's responsibility.
+A facade is useful when it owns real coordination, not just because it reduces
+arrows. These cases distinguish shared contracts from executable machinery.
+
+| Caller / operation | Dependency after this change | Decision |
+|---|---|---|
+| ToolBinding result filter | TaskResult private completion mapping | Remove duplicate physical-completion handling; source completion alone must not finish the filtered result |
+| Tracing span finish | Blocking.call_async | Generic default-pool work; observe rejection in the returned result |
+| Approval listener dispatch | Blocking.call_async | Generic default-pool work; log admission and later callback errors |
+| Agent/Workflow synchronous entry guard | Runtime.in_event_loop_context? | Query context without creating Runtime |
+| Prompt parser, Runnable users | Execution Contracts | Public callable/value contract, not pool internals |
+| Agent lifecycle/state, capability and journal input markers | Execution Contracts | Methodless classification; preserve direct include and validation |
+| Tool and async-client RBS token/result references | Execution Contracts / Execution Services | Keep real public type use in the graph; do not invent a domain facade for a token |
+| LLM, VectorStore, Embeddings and Storage AsyncClients | Contracts + TaskResult + Runtime/pools | Intended bridge; keep specialized submission, token and admission rules |
+| Agent ExecutionCoordinator / MultiAgent binding | Concurrency operation binding | Own cancellation/deadline scope across an operation; generic Blocking is not equivalent |
+| Agent and Workflow runners / execution registries | Runtime, FSM session and control delivery | Framework connection and single-writer ownership; retain these explicit dependencies |
+| Engine worker pool | TaskResult and execution errors | Produces shared results; the service/Engine relationship is not acyclic |
+
+The full dependency graph still includes references through shared error classes,
+markers and RBS. Moving their source owners changes the interpretation of the
+old Engine fan-in; it does not remove their actual use. The architecture gate
+enforces Contracts-to-Contracts/Common only and rejects domain/backend/client
+dependencies from Services or Engine. Layout is independent of those rules.
+
+See [ADR-063](../decisions/063-execution-contracts-and-services.md) for the source
+layout, behavior change and compatibility boundary.

data/docs/architecture/execution-metadata-and-values.md

@@ -0,0 +1,86 @@
+# Shared execution metadata and value conversion
+
+> 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`.
+
+
+Refactor 38 addresses the remaining R03 and R11 responsibilities against core
+`e7e6618493df03c2eb386d78a9303796e1e13cdc`. The candidate must be applied and
+verified before those items are closed. Tool restoration itself was completed
+earlier and its validation and state reconstruction remain unchanged.
+
+## Ownership
+
+Ordinary dispatch creates durable facts before sending an external operation.
+Recovery reads those same facts after an interruption. Their stored vocabulary
+therefore belongs to the execution contract, not to a recovery procedure.
+
+| Responsibility | Owner | Callers |
+|---|---|---|
+| Metadata keys/version, Tool batch capture and metadata merge | `Agent::ExecutionMetadata` in `agent/execution` | Initial/dispatch preparation, Coordinator, approval commit, recovery and MultiAgent |
+| Stable Tool invocation identity | `Agent::ToolInvocation.semantic_id` | Ordinary Tool preparation and recovery subject construction |
+| Ruby tree conversion before JSON serialization | `Values::Serializable.convert` in `common/values` | RuntimeRecordEncoder, RecoverySupport, ExecutionMetadata and dispatch preparation |
+| Recovery descriptors and outcome interpretation | `Agent::RecoverySupport` | Recovery and the existing failure reconstruction path |
+
+ExecutionMetadata is a stateless vocabulary and snapshot helper. It does not
+start an invocation, increment revisions, open a transaction or perform recovery.
+Its `with_values` preserves the old execution revision. ToolInvocation's
+`semantic_id` computes the same prefixed SHA-256 value over the same four IDs
+and NUL separators; it never constructs, authorizes or runs a Tool.
+
+RecoverySupport's shared constants and snapshot/merge/identity operations are
+removed, with all repository callers updated. No compatibility aliases are
+added for these private implementation names. `ExecutionOutcomeCommitter`
+still uses `RecoverySupport.error_from_failure` for actual failure reconstruction;
+this change does not claim to remove every execution/recovery dependency.
+
+## Conversion contract
+
+Serializable rebuilds Hash and Array containers, stringifies Hash keys and
+Symbol values, retains scalar objects, and recursively processes `to_h` results.
+It preserves input order and the previous last-value-wins behavior for keys
+that become equal. It does not deep-copy String values, freeze results, reject
+non-Hash `to_h` results, or catch exceptions raised by application conversion.
+
+The unsupported-value error remains ArgumentError. Callers supply their
+existing diagnostic prefix, including for errors inside nested values:
+
+| Boundary | Exact prefix before `: <class>` |
+|---|---|
+| RuntimeRecordEncoder.json_value | `unsupported canonical runtime value` |
+| RecoverySupport.canonical_copy and existing snapshot writers | `Recovery value is not canonically serializable` |
+
+The two existing conversion entry points remain short adapters because they
+own different error contracts. They no longer implement separate recursive
+algorithms. Snapshot writers retain their historical diagnostic despite its
+Recovery wording, to avoid a behavior change in this responsibility refactoring.
+
+Serializable does not establish canonical JSON validity. CanonicalJSON still
+owns numeric range, non-finite/negative-zero and encoding checks. Immutable.copy
+still owns copying and freezing. ProviderCallOutcome.normalize still has its
+different unsupported-value-to-String behavior. Domain codecs keep their key
+validation and collision rules. These operations are intentionally not merged.
+
+## Compatibility and verification
+
+Stored metadata keys, version 1, Tool identity bytes and serialized values are
+unchanged. Transactions, revision checks, dispatch order, Tool restoration,
+approval notifications and external-effect behavior remain with their existing
+owners. Public API, signatures, raw Storage SPI and database schema are unchanged.
+
+The conversion behavior tests run against both the applied baseline and the
+candidate, including nested unsupported values and application exceptions.
+Existing Tool batch tests follow their new owner; the stored identity fixture
+guards compatibility. Recovery, causal durability, approval/resume and
+MultiAgent tests exercise the changed callers. Full core/integration suites,
+common examples, real SQLite, API/SPI snapshots, RBS, annotations and packaged
+gem loading complete the candidate checks. Live PostgreSQL and live providers
+are not part of this candidate's execution evidence.
+
+This improves ownership and removes a duplicated recursive algorithm. The
+dependency diagram's module and file cycles remain; their disappearance is not
+the completion criterion. The applied SVG remains applied37-01 until the next
+application verification. The other initial proposal groups are R06, R07,
+R08/D08, R09 and R10; overall refactoring is not complete.

data/docs/architecture/generator-verifier-ownership.md

@@ -0,0 +1,111 @@
+# GeneratorVerifier ownership and event contract
+
+## Role and problem
+
+GeneratorVerifier exposes the draft/review/retry pattern. An application supplies
+two Agent classes, prompt builders, optional result parsers and convergence
+settings. invoke runs the Workflow and returns the existing Result, optionally
+raising LowConfidenceError. Agent completion arrives as Workflow events; Workflow
+entry actions return context immediately rather than awaiting Agent Tasks.
+
+R08 and D08 describe the same issue: a 199-line build_workflow mixes the graph
+with Agent startup, response parsing/normalization and failure notification.
+Nested PipelineState also occupies the public facade's source file. Separating
+only the file without removing receiver-to-facade private calls would leave the
+responsibility problem in place.
+
+## Owners and reading order
+
+| Owner | Responsibility |
+|---|---|
+| GeneratorVerifier | Public settings and Result; cached Workflow assembly, invocation, default JSON parser fallbacks and final confidence/raise policy. |
+| GeneratorVerifier::WorkflowBuilder | Draft/review/finalize/failed graph, request IDs, prompt creation, Agent startup and convergence guard. |
+| GeneratorVerifier::AgentResultReceiver | Separate draft/review payload conversion, common terminal-event classification and failure notification to the supplied Workflow. |
+| GeneratorVerifier::PipelineState | Existing Workflow fields, request correlation, stale/duplicate rejection and EventLoop-owned state mutation. |
+
+The last three constants are private. WorkflowBuilder and AgentResultReceiver
+are new internal classes; PipelineState is the existing class moved with its
+body and canonical name unchanged. The implementation lives in three files under
+generation/generator_verifier. The public facade and Result keep their names and
+locations; no loader changes or compatibility aliases are introduced.
+
+The initial D08 sketch suggested multi_agent/generator_verifier_workflow.rb.
+Since the prior layout work established generation as this pattern's owner,
+the internal files now stay there instead of creating a second feature owner.
+The new directory adds a module in directory-based analysis, not a public API.
+
+WorkflowBuilder#build reads as a graph: named entries, then ordered transitions.
+start_draft/start_review describe request preparation and dispatch. The receiver's
+draft_payload and review_payload retain different meanings. Their common listener
+has only the two internally selected phases; it is not a public configurable
+pipeline. It shares the same terminal/error rules rather than combining response
+formats into an options-driven generic parser.
+
+Default parsers remain explicit callables captured by the facade. Clamp and
+citation normalization move to their receiver owner. The old __send__ calls back
+to facade helpers disappear. The existing private Agent event-sink entry point
+is still called via send; changing that cooperation API is outside this scope.
+
+## Preserved ordering and failure contract
+
+- Each Agent is constructed once, lazily during the first successful Workflow
+  build. The cached Workflow and Agent instances are reused. Each invoke gets a
+  fresh Workflow context. No locking or new concurrency policy is introduced.
+- Each request gets a new UUID and a merged context before prompt construction.
+  The listener captures that request ID and the context's stable Workflow ID.
+  Workflow closures see the completed Workflow assignment before any entry runs.
+- Entry actions start asynchronous Agent work and return next_state, never a
+  TaskResult. Inline completion remains valid because signal queues a Workflow
+  event. Unknown/nonterminal Agent events are ignored.
+- done parses output, normalizes the phase-specific payload and signals the
+  matching completed event. StandardError from parsing, normalization or success
+  notification is signalled as the corresponding failed event with the same
+  exception object. Failure-notification exceptions are not retried or wrapped.
+- error/timeout/cancelled use the payload error or the same phase-specific
+  fallback message. approval_required remains a pipeline failure. A false return
+  from signal is returned without a retry or a new failure event.
+- PipelineState accepts only the current request ID. It clears the accepted ID,
+  increments iteration after draft completion, appends feedback after review,
+  and consumes old/duplicate results before any transition. The receiver does
+  not mutate context or add its own deduplication; stale done payloads can still
+  be parsed before the state rejects their correlated event.
+- Review completes when both the lower normalized score meets threshold and
+  approval is literal true, or when the iteration limit has been reached.
+  Otherwise it returns to draft and passes the last feedback to its prompt.
+- Final Result trust remains confidence >= threshold. At the iteration limit,
+  high confidence with approved=false can therefore still produce trusted=true.
+  A nonpositive limit still executes one draft/review cycle. These are observed
+  existing semantics, not behavior fixes hidden in this extraction.
+
+Public initialize/invoke parameters, Result fields/trusted? alias, parser
+fallbacks, score/citation normalization, error messages and PipelineState fields
+remain unchanged. Agent/Workflow/Engine/Storage behavior and SQL are not modified.
+Private clamp/normalize_citations implementations relocate; private overrides are
+not treated as additional supported public APIs.
+
+## Verification and trade-off
+
+Thirty-nine behavior examples pass unchanged on Refactor 40 and the candidate.
+They cover inline completion, ignored progress, pending Task returns, both phases'
+error/timeout/cancelled/approval failures, parser and notification failures,
+request correlation, duplicate/old callbacks, clamping, literal approval, final
+trust, iteration limits, caching, fresh state and config forwarding. Existing
+delayed-callback and WebMock integration examples cover the real Workflow path.
+
+A separate process comparison preserves public methods, parameters, constants,
+Result shape, the private state name/field schema/defaults and Runtime inactivity.
+Stable/Beta snapshots do not list GeneratorVerifier, so this explicit comparison
+supplements those existing gates. Core/integration/examples/real SQLite, type,
+style, annotations and isolated gem checks are included in distribution evidence.
+Live PostgreSQL, live LLM, candidate CI and performance are not run for this scope.
+
+The facade is 369 -> 118 lines. Workflow definition is 199 -> 34 lines, with a
+12-line facade assembly method. The three internal files are 112/89/57 lines,
+for 376 total, seven more than before. Two new classes and one moved class cost
+additional files; they give graph, receiver and state independent reading units.
+Directory-level dependency counts increase with that physical partition; cycle
+membership is unchanged. This is responsibility separation, not cycle removal.
+
+Refactor 41 is applied and independently verified at core e87eb77f, tree
+14dc8a546a4fd96e19e0713f7480ca2efa3c331a. All nine files and the full tree match.
+R08/D08 is closed. The published diagram is applied41-01. R09 and R10 remain.

data/docs/architecture/multi-agent-handoff.md

@@ -20,20 +20,27 @@ returns control to the caller. Handoff changes the active Agent for the current
 coordination lifetime.
 
 Normative Handoff intent is
-[ADR-030](../decisions/030-agent-handoff-domain-and-durable-responsibility.md).
+[ADR-030](../decisions/030-agent-handoff-domain-and-durable-responsibility.md),
+with the Runner ownership amendment in
+[ADR-034](../decisions/034-handoff-runner-coordination-ownership.md).
+
+MultiAgent owns the cross-Agent turn, Handoff edges, Policy, routing and reservations.
+Agent owns generic control requests, finalized Context projection and its own
+execution commits. See [r8 unit 4](r8-unit4.md).
 
 ## 2. Public API
 
 ```ruby
-handoff = Phronomy::Agent::Handoff.new(
+handoff = Phronomy::MultiAgent::Handoff.new(
   source_agent: triage,
   target_agent: billing,
   description: "Transfer billing responsibility",
   policy: policy
 )
 
-runner = Phronomy::Agent::HandoffRunner.new(
+runner = Phronomy::MultiAgent::HandoffRunner.new(
   main_agent: triage,
+  persistence: stores.multi_agent,
   handoffs: [handoff]
 )
 
@@ -50,7 +57,7 @@ schemas. The generated Tool name is private transport encoding, not Handoff
 identity or public semantic contract.
 
 Phronomy intercepts the Provider Tool Call into a typed private
-`HandoffRequest`. It does not execute an ordinary `ToolInvocation` or emit a
+`Agent::ControlRequest`. It does not execute an ordinary `ToolInvocation` or emit a
 sentinel Tool result.
 
 ## 4. Handoff Policy

data/docs/architecture/persistence-refactoring-plan.md

@@ -0,0 +1,50 @@
+# Persistence responsibility refactoring plan
+
+The Storage staged implementation reaches its bounded S3 cleanup in Refactor 36;
+application verification remains. The broader initial review still has open
+proposals recorded in the remaining responsibility plan.
+[ADR-033](../decisions/033-domain-persistence-ownership.md) established domain
+ownership; [ADR-058](../decisions/058-neutral-storage-primitives.md) now defines
+the neutral Storage SPI. Historical raw contracts are not the current API.
+See the [remaining responsibility plan](remaining-refactoring-plan.md) for the
+applied commit pair and the [closure review](refactoring-closure.md) for the
+final naming, placement and evidence boundary.
+
+## Target and current ownership
+
+Domain repositories own record meanings, codecs, revisions and business
+constraints. Storage owns typed neutral resources, Records/Streams/Blobs,
+conditions and transaction scopes. Concrete InMemory and SQL drivers implement
+physical operations. Composition selects implementations and assembles domain
+wrappers; Storage does not import concrete domain implementations.
+
+The public `Phronomy::Persistence` facade remains the application entry point.
+It is distinct from `Phronomy::Storage`, the backend extension contract.
+Directories express responsibility; existing public constants need not be
+renamed to match every directory. The dependency graph is not a tree.
+
+## Stages
+
+| Stage | Result |
+|---|---|
+| 1. Domain ownership | Refactor 09 moved schemas, repositories and queries to their domains. Later layout work placed record definitions and ownership contracts beside those features. |
+| 2. Neutral contract | Refactors 34 and 35 unified the failure/transaction boundaries and replaced eight raw repository slots with Resources, Records/Streams/Blobs and guarded conditions. Core, InMemory, SQLite and PostgreSQL were migrated together. Applied SPI 2 passed S2c, including real PostgreSQL. |
+| 3. Naming and placement | Refactor 36 retains the facade/SPI names, feature schemas, composition and reference-driver locations. Resource owns schema-reference normalization; generic Validation does not depend on Resource. Documentation records current status and historical boundaries. Distribution application verification remains separate. |
+
+## Invariants and gates
+
+All repositories and ContentStore continue to join one backend transaction.
+Splitting classes must not split commits. Codec response validation stays inside
+the atomic boundary. IDs, revisions, journal positions, active constraints,
+record type/version/payload and the F0/F1/F4/X0 limits remain unchanged.
+
+Product API and Storage SPI snapshots, RBS, existing domain/backend conformance,
+unit/integration suites, SQL examples and isolated gem loading verify the
+implemented boundary. Record which tests ran against which tree: Refactor 35's
+PostgreSQL CI is evidence for Refactor 35, not a claim that unpublished
+Refactor 36 ran remotely. Refactor 36 does not change SQL or its public protocol.
+
+Keep the applied-source diagram until the delivered candidate is applied and
+verified. Remaining directory cycles and runtime collaboration are recorded,
+not described as eliminated by moving files. Future behavior, performance or
+distributed-operation work requires its own scope and evidence.

data/docs/architecture/persistence.md

@@ -9,8 +9,49 @@
 
 ## 1. Durable boundary
 
-`Phronomy::Persistence` is the single durable-state backend abstraction for
-stateful Agents and durable Workflows.
+`Phronomy::Persistence` owns domain-neutral atomic scopes over a `Storage::Backend`.
+`Agent::Store` and `MultiAgent::Store` own domain operations and result queries;
+Workflow consumes its checkpoint repository directly. These roles share a
+coordinator when operations must commit together. Storage implementations do not
+inherit a domain service. See [r8 unit 3](r8-unit3.md) for construction and migration.
+
+The `storage/` directory owns record carriers, portable errors, repository views,
+and the Backend contract. `storage/backends/` owns physical storage implementations.
+The `agent/persistence/`, `multi_agent/persistence/`, and `workflow/persistence/`
+directories own their domain codecs and repositories. Agent and Team result
+queries live with those domains. `storage/record_codec.rb` contains only shared
+record-envelope and scalar validation; it does not select a domain schema.
+`persistence_composition/` assembles the domain repositories over one raw view.
+`content_store/` is a content management service over Storage, not a physical
+backend family. Its Base shares text/JSON conversion with StoredContents and
+the Persistence content facade. StoredContents generates content IDs, verifies
+digest identity and uses the injected view's Blobs. Its StorageSchema belongs
+to this service. Storage owns byte immutability, transactions and physical I/O.
+The service and its schema live together; there is no `content_store/backends/`
+directory or backend-selection API. See [ADR-062](../decisions/062-content-store-service.md).
+Domain stores receive their record adapters from `PersistenceComposition` and
+retain their observation-thread guards. The common Persistence does not select
+domains, assemble repositories, or delegate domain result queries. Domain-only
+record protocols bind to the exact scope when participating; there is no shared
+all-domain repository facade.
+See [ADR-032](../decisions/032-storage-backend-composition.md) and
+[ADR-033](../decisions/033-domain-persistence-ownership.md).
+
+`persistence/errors.rb` owns the shared domain-facing failure classes. Repository
+boundaries translate four known raw Storage categories to Persistence categories,
+retaining the original exception as `cause`. Upper domain state contradictions
+use `Persistence::StateConflictError < Persistence::ConflictError`. Unknown and
+commit-outcome-uncertain exceptions are not reclassified. Backend contracts never
+depend on these upper errors. See [ADR-061](../decisions/061-persistence-failure-contracts.md)
+and the [rescue-clause migration](../migrations/persistence-failure-contracts.md).
+
+Shared value copying belongs to `Values::Immutable` in `values/`. Agent records,
+Team records, Recovery classifications, and Persistence result views use this
+internal helper without borrowing an Agent implementation. It copies and freezes
+Hash, Array, and String trees; other values pass through unchanged. Its separate
+canonical JSON check delegates to `CanonicalJSON`. Each domain codec and repository owns its record schema, key normalization,
+identity, and revision validation. Moving this helper
+does not change record formats, transaction ownership, or recovery guarantees.
 
 | Repository | Durable authority |
 |---|---|
@@ -18,7 +59,7 @@ stateful Agents and durable Workflows.
 | `agents` | AgentRoot |
 | `journals` | Append-only Agent journal |
 | `executions` | AgentExecution and owned child coordination |
-| `workflow_states` | Workflow snapshots |
+| Workflow checkpoint repository | Workflow snapshots |
 | `handoff_states` | Active responsibility and exact Target reservation |
 | `teams` | TeamRoot |
 | `team_executions` | Team tasks, assignments and outcomes |
@@ -107,7 +148,7 @@ Phronomy does not claim arbitrary external exactly-once side effects.
 ## 7. Durable codec
 
 Durable backend exchange uses immutable
-`Phronomy::Persistence::DurableRecord` values with:
+`Phronomy::Storage::DurableRecord` values with:
 
 ```text
 record_type