phronomy 0.26.0 → 0.27.0

data/docs/architecture/agent-transition-ownership.md

@@ -0,0 +1,89 @@
+# Agent invocation transition ownership
+
+## Role and scope
+
+An Agent invocation moves between preparation, Provider calls, Tool processing,
+approval suspension and completion. Three collaborators need the same policy:
+AgentInvocation consumes external payloads; PhaseMachineBuilder creates the
+executable state machine; AgentInvocationSessionBuilder configures FSMSession's
+advance, wait and terminal boundaries. Independently maintained event lists and
+transition copies could disagree about what the current phase can accept.
+
+Refactor 39 gives that shared policy one private owner, InvocationTransitions in
+agent/execution. This is Agent data in the existing transition Hash format, not
+a new cross-feature DSL or Engine extension. It is not a new execution object.
+
+## Ownership and reading order
+
+| Owner | Responsibility |
+|---|---|
+| InvocationTransitions | Initial phase, declared/automatic/approval-wait states, Tool event vocabulary and ordered external transition definitions. |
+| PhaseMachineBuilder | Translate those external definitions to state_machines; retain automatic state_completed transitions and synchronous entry-action validation. |
+| AgentInvocationSessionBuilder | Assemble the invocation, event sink, entry actions and machine; pass shared state and transition metadata to FSMSession. |
+| AgentInvocation | Apply payloads and expose the current guard predicates; use the shared Tool event vocabulary. |
+| FSMSession | Generic advancement, event delivery and wait/terminal handling. No Agent-specific decisions. |
+
+Read the policy table for legal external sources and guard priority, the machine
+builder for execution mechanics, and the session builder for action wiring.
+The EXTERNAL_EVENTS Hash, each transition array and each row are frozen so one
+session cannot edit another session's policy. Guard lambdas contain no captured
+invocation state; they inspect the context supplied at transition time.
+Old private constants and the external_events factory are removed without aliases.
+
+## Preserved event and phase contract
+
+The six Tool events are authorized, approval_required, completed, failed,
+rejected and cancelled, each with the tool_ prefix. Each moves waiting_for_tools
+to evaluating_tools. LLM completion from calling_llm tries these in order:
+
+1. callback_failed? to failed;
+2. handoff_failed? to failed;
+3. handoff_requested? to handed_off;
+4. tool_call_pending? to starting_tools;
+5. unconditional fallback to output_filtering.
+
+Guards short-circuit. A nil context skips guarded rows and takes the fallback;
+guard exceptions propagate unchanged. Each evaluation uses the latest context,
+without caching a selected destination. Session applies the event payload first.
+
+LLM failure/setup failure leads from calling_llm to failed. Tool setup failure
+leads from dispatching_tools to failed, while tool_dispatch_prepared returns it
+to evaluating_tools. Resume moves suspended to waiting_for_tools. Application
+callback failure is accepted from the existing nine active phases only.
+
+Automatic phases remain idle, filtering_input, building_context, starting_tools,
+evaluating_tools, recording_tool_results and output_filtering. calling_llm,
+waiting_for_tools and dispatching_tools wait for external events. suspended ends
+a segment with halted; resume uses a fresh Session identity. The four declared
+terminal phases remain handed_off, completed, blocked and failed.
+
+FSMSession reads only the from field when determining external-event admission
+and waiting. It does not execute metadata guards or choose their destinations;
+state_machines does that. Known-but-undeclared and unknown events retain their
+existing error behavior; context-consumed stale events retain their early exit.
+The internal order of event registration now follows the shared table. Transition
+order within each event, which determines behavior, is preserved. The generated
+machine's private event-enumeration order is not a supported public contract.
+
+## Verification and limits
+
+Independent behavioral tests run on both Refactor 38 and the candidate: all 195
+external-event/source-state combinations, all sixteen LLM condition combinations
+including short-circuit order, nil context and guard exceptions, fifteen Session
+boundaries, context-before-guard ordering, approval suspension/resume/dispatch,
+and invalid source-state handling. Existing Agent, causal durability, Handoff,
+Workflow and Engine tests continue to cover their collaborating behavior.
+
+The candidate also runs the full core/integration suites, offline examples and
+real SQLite, API/SPI snapshots, RBS, style, annotations and isolated gem checks.
+No SQL, stored format, entry action implementation, Tool restoration, cancellation
+or Coordinator sequencing is changed. The new contract tests isolate entry actions
+and do not claim live Provider coverage. Live PostgreSQL/LLM and remote CI are
+not executed for this candidate. Refactor 39 was independently verified after application at core 4d57614a,
+tree 654241da4b2b7f32d988602d28127bc1fa155641. All 10 files and the full tree
+matched, and core/integration/examples/SQLite/API/type/gem checks passed.
+The published SVG is applied39-01.
+
+R06 is applied and complete. R07 now has a Refactor 40 candidate; R08/D08, R09
+and R10 remain afterward. R09's inheritance behavior and R10's action names
+are not altered by the transition-ownership work.

data/docs/architecture/before-llm-input.md

@@ -33,6 +33,12 @@ not receive a mutable Provider chat/message array.
 
 A hook returns `Phronomy::Agent::LLMInputPatch` or `nil`.
 
+These two types live in the shared `agent/context_contract/` implementation
+directory together with the Policy input and result contracts. Zeitwerk
+collapses the directory, preserving their existing public `Phronomy::Agent`
+names. Hook registration, invocation, and result handling are unchanged; see
+[ADR-036](../decisions/036-context-contract-ownership.md).
+
 ```ruby
 Phronomy::Agent::LLMInputPatch.new(
   model_config_patch: {temperature: 0.2},

data/docs/architecture/context-management.md

@@ -50,6 +50,36 @@ RubyLLMMaterializer
 The normative Journal/Manifest split is
 [ADR-012](../decisions/012-canonical-execution-log-and-context-policy.md).
 
+### Contract ownership and physical layout
+
+The contracts shared by Agent execution, Context policies, and input hooks live
+in `lib/phronomy/agent/context_contract/`:
+
+| Files | Responsibility |
+|---|---|
+| `context_policy.rb`, `context_policy_input.rb` | Policy protocol, helper methods, and typed input material |
+| `context_plan.rb`, `context_plan_validator.rb` | Policy result and its validity rules |
+| `llm_input_manifest.rb` | Final logical input representation and its format validation |
+| `llm_input_build_context.rb`, `llm_input_patch.rb` | Input metadata and returned customization for hooks |
+
+Zeitwerk collapses this directory. The Ruby constants keep their existing
+`Phronomy::Agent::*` names; there is no `ContextContract` namespace or new
+registration mechanism. Applications continue to load `phronomy` and use the
+documented constants. The previous individual implementation file paths are
+not retained as forwarding files.
+
+`ContextPolicies::Default` remains a concrete strategy, while
+`ContextAssembler`, input builders, candidate resolution, Runtime connections,
+and persistence transactions remain on the execution side. The Manifest
+validates and converts record values; it does not write to a storage backend.
+Its format version, keys, and validation rules are unchanged.
+
+This ownership decision is defined by
+[ADR-036](../decisions/036-context-contract-ownership.md). Physical containment
+under `agent/` does not assign the contracts to the execution layer. The
+concrete policies and the shared contracts can occupy distinct groups at the
+same abstraction level.
+
 ## 2. Public Context Policy SPI
 
 Application code supplies an ordinary reusable Ruby strategy object:

data/docs/architecture/context-preparation-steps.md

@@ -0,0 +1,90 @@
+# Context preparation steps
+
+## Role and scope
+
+ContextAssembler prepares the immutable semantic input supplied to Application
+ContextPolicy and later validates and stores its decision as an LLMInputManifest.
+InitialPreparation and DispatchPreparation run preparation outside their commit
+transactions, recheck durable state, then call finalize in the commit transaction.
+The public boundary and those callers already have separate responsibilities.
+
+R07 addresses a narrower readability problem inside prepare_initial and
+prepare_followup: orchestration was mixed with individual item IDs, provenance
+and metadata, and record filtering plus Hook/Handoff merging were duplicated.
+The original proposal calls for private extraction before adding collaborators.
+Refactor 40 follows that limit: one production file changes; no class is added.
+
+## Reading order and responsibilities
+
+| Private operation | Responsibility |
+|---|---|
+| initial_instruction_items | Choose the initial Agent instruction and optional Handoff responsibility, in order. |
+| agent_instruction_item | Build the required system instruction with its stable ID, estimate and Agent provenance. |
+| handoff_instruction_item | Build the required user responsibility with its ID, estimate and Handoff origin. |
+| retained_instruction_items | Read only retained base instructions from the previous Manifest, using the existing compatibility predicate and converter. |
+| resolve_record_candidates | Filter working records by eligibility/current generation and resolve them with Journal candidates and caller-provided exclusions. |
+| merge_context_candidates | Add Hook candidates, then Handoff candidates, using the existing creation, sorting and storage operations. |
+| current_input_item | Build the initial required ask argument after all candidates, including ID, sequence, provenance and metadata. |
+
+Public preparation keeps model/Tool settings, source loading and the sequence of
+these operations visible. Record collection and candidate augmentation stay as
+two steps: follow-up computes its next call sequence after record resolution,
+exactly as before. No new options object, pipeline DSL, mutable preparation state
+or cross-feature factory is introduced. Helpers remain private to the assembler.
+
+## Preserved contracts
+
+- Initial instructions come from the Agent configuration plus optional Handoff
+  responsibility. Follow-up instructions come from the retained base Manifest.
+  Current Hook instructions are rebuilt; previous Hook/Policy-generated items
+  do not become permanent base instructions. Legacy origin handling is unchanged.
+- Working records must remain context candidates in the active transcript
+  generation. Initial preparation excludes the current input record; follow-up
+  includes eligible working records without that exclusion.
+- Record candidates are resolved before Hook and then Handoff augmentation. The
+  current-input sequence follows all candidates, including non-conversation ones.
+  IDs, source fields, trust metadata, estimates, required flags, ordering, frozen
+  values and delivery modes retain their existing values.
+- Initial input content is loaded before instruction-item construction and
+  candidate resolution. Initial instruction callbacks and patch normalization
+  retain their order. Hook content writes still precede Handoff type validation;
+  moving that validation earlier would be a behavior change and is not included.
+- Preparation is not side-effect-free: Hook/Handoff content may be stored before
+  Policy succeeds. This extraction neither adds rollback nor suppresses existing
+  exceptions. Missing-input, reserved-metadata, resolver and Policy failures keep
+  their ordering; collaborator exception objects propagate unchanged.
+- Application Policy executes once during prepare; finalize does not invoke it.
+  Finalization, its validation/encoding/store helpers, assembly policy version 8,
+  schemas, public signatures and transaction-owning callers are unchanged.
+
+The new helpers use the same constructor field evaluation and call ordering.
+They do not cache or deduplicate reads, normalize values earlier, or move work
+across the prepare/finalize boundary merely to shorten the source.
+
+## Verification and trade-off
+
+Ten behavior examples cover initial item provenance/immutability, generation and
+exclusion rules, content-write order, absent instructions/Handoff, follow-up
+retention and current hooks, the prepare/finalize boundary and failure precedence.
+The same examples pass on Refactor 39. Four independent baseline/candidate
+scenario pairs compare complete Policy input, Prepared values, Manifest bytes and
+content references, plus preparation-time content read/write order. The pairs
+cover initial and follow-up calls with/without base instructions and Handoff.
+
+Full core/integration suites, common examples and real SQLite, stable/beta API
+and Storage SPI snapshots, RBS, style, annotations and isolated gem checks are
+also run. Live PostgreSQL, live LLM, remote CI and performance are not exercised
+for this candidate; prior CI is not evidence for the candidate's core.
+
+prepare_initial is 103 -> 55 lines and prepare_followup 57 -> 47. The whole file
+is 625 -> 672 lines because seven named private methods and explicit arguments
+add structure. This is a readability and duplicated-procedure improvement, not a
+net line-count reduction or a directory-cycle change. The methods' names give
+readers a place to choose whether they need the detailed representation.
+
+R07 was independently verified after application at core b3dfbc5a, tree
+dcd9d1bf8efb1b488f9c2b3b1c4e99bdeda6096c. All six files and the full tree matched;
+core/integration/examples/SQLite/API/type/gem and four paired scenarios passed.
+R07 is complete. The published diagram is applied40-01. R08/D08 now has a Refactor
+41 candidate, with R09 and R10 remaining afterward. Their behavior and naming
+decisions are not part of Context preparation extraction.

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-metadata-and-values.md

@@ -0,0 +1,80 @@
+# Shared execution metadata and value conversion
+
+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,7 +20,13 @@ 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).
+
+The Runner owns the cross-Agent turn. Handoff edges, Policy, Context and
+Agent terminal/persistence integration remain in Agent during this first
+migration step. See the [Runner migration](../migrations/handoff-runner-multi-agent.md).
 
 ## 2. Public API
 
@@ -32,7 +38,7 @@ handoff = Phronomy::Agent::Handoff.new(
   policy: policy
 )
 
-runner = Phronomy::Agent::HandoffRunner.new(
+runner = Phronomy::MultiAgent::HandoffRunner.new(
   main_agent: triage,
   handoffs: [handoff]
 )

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,31 @@
 
 ## 1. Durable boundary
 
-`Phronomy::Persistence` is the single durable-state backend abstraction for
-stateful Agents and durable Workflows.
+`Phronomy::Persistence` is the domain-facing service for the single durable-state
+transaction domain used by Agents, Teams, and Workflows. It composes a
+`Storage::Backend`; storage implementations do not inherit the domain service.
+
+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.
+The public `Phronomy::Persistence` entry point delegates to those components and
+retains its observation-thread guard.
+The root and transaction paths use the same facade construction, with transaction
+facades bound to the raw backend view for that transaction.
+See [ADR-032](../decisions/032-storage-backend-composition.md) and
+[ADR-033](../decisions/033-domain-persistence-ownership.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 |
 |---|---|
@@ -70,7 +93,7 @@ Defined semantic durable transitions are atomic according to the Persistence
 transaction contract and conforming backend.
 
 Revision/watermark/CAS checks reject stale durable transitions with
-`Persistence::ConflictError` rather than silently merging/reloading competing
+`Storage::ConflictError` rather than silently merging/reloading competing
 state.
 
 Conflict detection is not competing-execution exclusion and cannot undo an
@@ -107,7 +130,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