phronomy 0.27.0 → 0.29.0

data/docs/architecture/r8-unit5.md

@@ -0,0 +1,115 @@
+# r8 unit 5: VectorStore and Embeddings common contracts
+
+Core baseline: `29818f5d0577ac5287c5429d6d169ef5fd1c0225`.
+Examples baseline: `c410fc88112ad5e4648ba2e51335023885d9373b`.
+The contract concept and foundation target remain the design goal. This unit
+implements C10/C11 common operation ownership and DP09/DP10 placement. It does
+not complete the other domain Contracts or the outstanding unit 4 acceptance gates.
+
+## Ownership and completion conditions
+
+Contract membership follows domain semantics, not frequency of reuse. A Contract
+defines its domain's concepts, legal inputs/results, invariants, extension points
+and observable failure/operation rules. Its framework executes those rules.
+Code used by several callers is not automatically a Contract; a generic utility,
+concrete adapter helper or composition operation can have several callers too.
+
+| Placement decision in this unit | Domain reason |
+| --- | --- |
+| VectorStore id/vector/metadata inputs and ordered search results | These describe the public vector storage/retrieval operation independently of a database |
+| Embeddings text/vector inputs and results | These describe text embedding independently of the provider SDK and downstream storage |
+| Validation, pre-operation cancellation checkpoint and InvalidResultError | These enforce the operation's observable invariants and failure rules |
+| Float-array normalization | This realizes the declared vector representation; it does not make arbitrary serialization a Contract concern |
+| Redis RESP2 decoding, distance-to-similarity conversion, Pgvector row/JSON decoding | These are concrete backend adaptations and remain in the corresponding backend |
+| Document loading/splitting | These are document utilities separated from VectorStore; this move does not create a new Contract |
+| Async submission and timeout settlement | These remain Execution responsibilities, connected through each AsyncClient |
+
+| Responsibility | Owner | Completion evidence |
+| --- | --- | --- |
+| Vector operation entry, cancellation checkpoint, input/result validation, chaining | `VectorStore::Base` | A hook-only custom backend receives validated inputs; malformed inputs perform no I/O; malformed outputs fail explicitly |
+| Search/storage algorithms, physical dimension state, database encoding | `VectorStore::{InMemory,Pgvector,RedisSearch}` | Existing algorithm and adapter tests run through inherited public operations |
+| Text input and finite embedding result validation | `Embeddings::Base` | A hook-only provider works without SDK, Engine or VectorStore; malformed outputs are rejected |
+| Embedding provider call and SDK exception translation | `Embeddings::RubyLLMEmbeddings` | Provider exceptions retain their cause; cancellation and application failures retain their identity |
+| Submission, timeout, admission and completion handle | Each feature's `AsyncClient` and Execution | Existing pool, cancellation, timeout and Runtime reset tests |
+| Document input and splitting | `Documents::Loader` / `Documents::Splitter` | Existing document tests; no VectorStore or Embeddings dependency |
+
+Common behavior lives in the existing Base classes. There is no forwarding
+Contract, Base-to-client factory, compatibility alias or mandatory embedding
+provider in VectorStore. Protected `perform_*` methods are the extension SPI;
+applications call the inherited public operations. Ruby can override any method,
+but overriding the public template is outside the documented backend SPI.
+
+## Defined operation behavior
+
+`VectorStore#add` checks cancellation, a String id, Hash metadata, a vector of
+finite real numbers and the backend's known dimension before entering the
+storage hook. It supplies a fresh Float array and returns the store. `remove`
+and `clear` also return the store. A search validates input and positive `k`
+before entering its hook, including an empty Redis store. Decimal strings for
+`k` remain supported; fractional values no longer truncate silently.
+
+Search results must be an Array of at most `k` Hashes with String `:id`, finite
+numeric `:score`, Hash `:metadata`, and descending score order. A count must be
+a non-negative Integer. Violations raise `VectorStore::InvalidResultError`.
+Backend transport failures propagate without retries. Redis count failures no
+longer become a successful zero count. Backend-specific index creation, metadata
+encoding and query construction remain in the backend; they are not new common
+storage primitives. Existing dimension-zero InMemory vectors remain supported.
+
+Backends must not invent successful values while decoding malformed external
+responses. RedisSearch validates its RESP2 count, field pairs, document keys,
+numeric distances and JSON object metadata before producing the public result.
+A genuine zero-match reply is `[0]`. A missing whole reply is invalid. Redis's
+documented null document contents after expiration/update are omitted; they do
+not imply a corrupt response, and the total can exceed the returned page size.
+Missing/null Redis metadata and a SQL NULL metadata column still mean empty
+metadata. Invalid JSON text, empty JSON text, JSON scalars/arrays and invalid
+scores raise `InvalidResultError`. Pgvector also rejects invalid row ids rather
+than turning them into strings. JSON parse failures preserve their original cause;
+transport/database exceptions propagate unchanged and no read is retried.
+
+The response decoders stay private to each backend. Base does not know Redis
+commands, RESP versions, ActiveRecord rows, JSON columns or SDK exceptions.
+The existing RESP2 support boundary and known-dimension/index initialization
+requirements remain; this unit does not add RESP3 support.
+
+Protocol references: [FT.SEARCH](https://redis.io/docs/latest/commands/ft.search/)
+and [FT.INFO](https://redis.io/docs/latest/commands/ft.info/), checked 2026-10-03.
+
+`Embeddings#embed` checks cancellation and String input, invokes `perform_embed`
+once, and validates a non-empty finite vector before returning Float values.
+Malformed output raises `Embeddings::InvalidResultError`. The RubyLLM backend
+translates `RubyLLM::Error` to `Embeddings::TransportError`, preserving `cause`.
+This error does not imply that external work was or was not accepted. There is
+no automatic retry and no classification of an arbitrary application exception
+as a provider failure.
+
+Cancellation is cooperative. The common checkpoint occurs before the backend
+operation; a provider may inspect the same signal during its work. A successful
+write is not changed into cancellation by a post-write check. Timeout and result
+settlement remain Execution responsibilities; an external call may continue.
+
+Input errors are F0 failures before X0 I/O. For a write that has crossed X0,
+failure/timeout is not proof of a rollback or of a missing external effect.
+This unit adds no F1 outcome reconciliation, F4 recovery, cross-process exclusion
+or exactly-once external-effect guarantee. InMemory dimension inference and
+backend concurrency constraints retain their documented limits.
+
+## Refactoring completion tracking
+
+| Contracts | Current boundary status | Remaining work |
+| --- | --- | --- |
+| C10 VectorStore / C11 Embeddings | Common contract behavior implemented in unit 5 | Real Pgvector/Redis/provider service verification remains an implementation gate, reported separately |
+| C05 Context / C07 Persistence / C08 ContentStore / C12 Storage / C13 Execution / C15 Tracing | Main common foundations implemented in units 1-4 | Additional domain acceptance conditions and overall dependency review are not waived |
+| C09 LLM / C06 Tool | Partial | Public values/failures, SDK-neutral operation boundary, Tool SDK inheritance and execution connection |
+| C04 Agent / C01 MultiAgent | Unit 4 ownership boundary implemented | FSM/Runtime/composition dependencies |
+| C02 Workflow | Partial | FSM connection and durable child identity/resume/outcome reconciliation |
+| C03 Generation / C16 Filter / C17 OutputParser | Existing common implementation | Finish responsibility-level conformity review; absence of certification is not evidence that all code is missing |
+
+Next implement C09/C06 together where their SDK boundary interacts, then finish
+C04/C01/C02 execution connections and durable collaboration. Inspect the existing
+C03/C16/C17 implementations against explicit conditions before scheduling rewrites.
+
+The package records commands actually executed and unexecuted backend gates.
+See [migration](../migrations/r8-unit5.md) and
+[ADR-065](../decisions/065-vector-and-embeddings-common-operations.md).

data/docs/architecture/r8-unit6.md

@@ -0,0 +1,71 @@
+# r8 unit 6: C09 LLM and C06 Tool
+
+Contract placement is determined by ownership of meaning and operations. Reuse
+alone is not a reason to put code into a contract. This unit completes the scoped
+LLM/Tool operation boundary; it does not complete every contract in the target.
+
+| Owner | Meaning and operations |
+| --- | --- |
+| C09 LLM, `LLMAdapter` | Immutable Request, Message, Response, StreamChunk and TokenUsage; complete/stream templates; input/result/cancellation checks; public failures |
+| C06 Tool, `Tool` | CallRequest, declarations, advertised schema, argument validation/coercion, authorization evaluation and execution/error rules |
+| RubyLLM backend | SDK chat construction, options, message/Tool rendering, chunk/response decoding, SDK exception translation and SDK Tool interception |
+| Agent | Select context, prepare executable Tools, run approval and Tool batches, consume LLM results, persist and recover execution facts |
+| Execution / AsyncClient | Scheduling, cancellation signals, deadlines and worker submission; AsyncClient submits the whole LLM operation |
+
+Tool requests are ordinary assistant Response values. They do not authorize or
+execute a Tool. Only the backend knows RubyLLM's message callback and its private
+interception signal. SDK Tool declarations have a rejecting execute method; an
+accidental SDK auto-execution fails instead of bypassing Agent authorization.
+A minimal backend needs only protected perform_complete/perform_stream hooks.
+Agent does not require a Chat-like object, SDK methods or executable Tool handles
+from it. Streaming returns a final Response in addition to typed chunk events.
+
+TokenUsage and the four existing LLM failures move from the root namespace into
+LLMAdapter, with no aliases. Unknown usage remains nil, distinct from zero.
+ContextLengthError remains a direct Phronomy::Error; rate limiting and
+authentication remain TransportError subtypes. InvalidResultError identifies
+malformed results rather than a valid empty response. SDK errors retain cause;
+application callback errors and cancellation retain their original identity.
+
+`Tool::Base` no longer inherits RubyLLM::Tool. Both `param` and explicit `parameters`
+(Hash/schema DSL) produce a C06 Schema. `validate_arguments` is the public, pure
+preflight operation used before approval; `call` uses the same schema/rules before
+execute. Legacy private type/coercion/nesting algorithms are removed. Parameters
+that were advertised but not enforced by the explicit-schema path now fail before
+approval or execute. See the migration document for the supported schema dialect.
+
+SDK initialization, setters, completion and decoding run within AsyncClient's
+worker operation. Cancellation is checked before and after the backend operation,
+after SDK construction, and before delivering chunks. A deadline is an Execution
+cancellation signal. It can settle the caller while a blocking SDK constructor is
+still running; it does not forcibly stop a thread. When that constructor returns,
+the cancellation checkpoint prevents starting a new provider request. Already
+sent external work is not rolled back. Local input_budget uses existing model
+registry metadata; live capacity discovery is not added to the contract.
+
+Saved context materializes Phronomy Message/CallRequest values. SDK rendering
+occurs later inside the backend, including structured-content JSON rendering and
+opaque thought_signature metadata. Existing durable thought_signature and usage
+field spellings remain readable. New Tool batch metadata stores the validated
+argument snapshot alongside raw arguments so public authorization projection
+compares what was approved, including coercion and intentional null. Historical
+snapshots retain their explicit old decoding rule. Recovery resolution accepts a Response or its
+canonical Hash, not arbitrary SDK objects. Record identities, transaction/CAS
+rules, approval ownership and F0/F1/F4 classifications remain with Agent and
+Persistence. No exactly-once or automatic retry guarantee is introduced.
+
+## Architecture evidence
+
+M47 (`llm_contract`) is retired into M15 (`llm_adapter`); the identifier is not
+reused and historical diagrams remain historical. C09 is allowed to reference
+C06 Schema/CallRequest. Directory aggregation also shows C09 -> Tool -> Execution,
+because Tool::Base owns an execution template in the same directory as the values.
+The directory gate permits that specific route; AST checks reject direct C09
+mechanism references, Tool::Base consumption and SDK/Agent/Engine leaks. The full
+Ruby/RBS matrix retains the route instead of hiding it. Standalone loading and a
+minimal backend execution test additionally establish that C09 values do not
+load Tool::Base, Agent, Engine or the SDK.
+
+Remaining work includes Agent/MultiAgent/Workflow FSM and Runtime connections,
+Workflow durable children and cross-record outcome evidence, live provider
+verification, and the broader semantic review of existing dependency triangles.

data/docs/architecture/r8-unit7.md

@@ -0,0 +1,70 @@
+# r8 unit 7: C04 Agent progress and execution connection
+
+Contract placement follows ownership of meaning, invariants, operations and
+failures. It is not determined by reuse. This unit improves C04; it does not mark
+all of C04, C06 or the overall target complete.
+
+| Owner | Responsibility after this change |
+| --- | --- |
+| Agent InvocationTransitions | Phase vocabulary, ordered automatic/external transitions, guard evaluation, iteration bound |
+| Agent InvocationActions | Prepared input, LLM dispatch, Tool batch orchestration and result/event interpretation |
+| Agent ExecutionCoordinator / RecoveryCoordinator | Admission, durable preparation, approval, terminal outcome, recovery and causal revision checks |
+| Agent ExecutionEnvironment | Private process-local connection required by the Agent framework; session construction/registration, serial owner and operation submission |
+| Agent EngineEnvironment / EngineSessionBuilder / PhaseMachineBuilder | Runtime registration, EventLoop channel, FSMSession construction and state_machines adaptation |
+| ExecutionReceiver | Serial-owner admission, delivery and lifecycle framework for feature-owned live state |
+| Engine ExecutionReceiverBinding | Concrete EventLoop registration, locking, queued delivery and routing |
+
+Previously AgentInvocationSessionBuilder combined Agent entry operations with
+FSMSession creation. PhaseMachineBuilder held automatic progress rules, while
+InvocationTransitions held only external transitions. Execution/recovery also
+selected Runtime.instance repeatedly. The split now leaves both transition sets
+and their priority with Agent. The Engine builder only installs those definitions
+and synchronous entry callbacks into state_machines. InvocationActions retains
+Agent semantics instead of moving the old class wholesale into an adapter.
+
+An Agent captures the environment of its ownership registry at construction.
+Execution and recovery reuse it; changing the composition provider does not move
+a live Agent to another Runtime. Cancellation records its durable request before
+posting a notification through that same environment, including after a provider
+change. Detached Agent cancellation is rejected by the existing live-owner check.
+The default provider is installed lazily by runtime_composition/agent_defaults.rb.
+This is an internal composition port, not a new supported application plugin API.
+
+ExecutionRegistry remains Agent-owned. Its generic serial receiver framework
+moves from Engine to Execution and receives a channel. The actual EventLoop
+transport stays in Engine. WorkflowExecutionRegistry uses that same channel to
+preserve its existing receiver lifecycle; Workflow policy is not migrated here.
+This placement follows ownership of execution admission/lifecycle, not merely
+that Agent and Workflow share a base class.
+
+Provider Call identity is passed explicitly to AgentInvocation from the already
+prepared durable execution. AgentInvocation no longer queries global Runtime to
+find it. FSMSession IDs remain ephemeral routing incarnation IDs. Approval and
+recovery create a fresh session while preserving durable execution/LLM/Tool IDs.
+No storage schema, CAS revision, parent admission, atomicity or F0/F1/F4 policy
+changes. External effects are not exactly-once. Cancel/timeout do not forcibly
+stop workers or undo effects; terminal persistence still waits for physical
+quiescence. Stale session/revision results remain rejected on the serial owner.
+
+## Evidence and limits
+
+The tests execute the transition policy in a standalone Ruby process without
+Engine or state_machines, enumerate all 32 Tool outcome priority combinations,
+compare the Engine adapter's behavior, and check environment retention and
+cancellation routing. Existing recovery, approval, callback failure, single-writer,
+stale-result and shutdown tests remain part of full/integration validation.
+An AST gate rejects concrete Engine constants and state_machines loading in Agent
+execution, recovery, lifecycle and ExecutionEnvironment. This is a scoped gate,
+not proof that every dependency in the system is correct.
+
+The measured graph adds M88/G62 for agent/runtime_binding; retired IDs are not
+reused. Ruby and RBS references remain in the evidence, including cycles caused
+by other uncompleted boundaries. Regenerate the measured diagram from the exact
+candidate; do not treat it as the acyclic target design.
+
+Still pending: Agent's Tool child FSM/session builder and its Runtime selection;
+MultiAgent and Workflow FSM/Runtime connections; Workflow durable children and
+cross-record outcome evidence; broader dependency-triangle review. The C06 Tool
+operation/schema contract established in unit 6 remains intact, but its Agent-side
+execution connection is not declared complete by this unit. LLM AsyncClient's
+execution backend selection also remains the existing C09/C13 composition.

data/docs/architecture/r8-unit8.md

@@ -0,0 +1,78 @@
+# r8 unit 8: C04 Tool child progress and C06 operation boundaries
+
+Contract placement follows ownership of domain meaning, invariants and operations.
+C04 owns the lifecycle of a Tool invocation inside an Agent. Calling a Tool does
+not transfer that lifecycle to C06. This unit completes the scoped Tool child FSM
+separation left by unit 7; it does not certify all of C04 or the overall target.
+
+| Owner | Responsibility |
+| --- | --- |
+| Agent ToolInvocationTransitions | Child phases, ordered automatic/external transitions, legal event sources and recursion bound |
+| Agent ToolInvocationActions / ToolInvocation | Validation/authorization orchestration, approval waiting, dispatch eligibility, outcome application and parent notification |
+| Agent ExecutionEnvironment | The original Agent connection for authorization and default Tool submissions, operation supervision and session creation |
+| Agent ToolSessionBuilder / PhaseMachineBuilder in runtime_binding | Concrete FSMSession/EventSink construction and state_machines adaptation of Agent-owned rules |
+| Tool Operation | Tool execution-mode validity, standard/custom async operation dispatch, completion protocol and result adaptation |
+| Tool ToolExecutor | Default cooperative/offloaded Tool operation, using the injected C13 submission protocol |
+| Execution / _ExecutionSubmitter | Execution submission and completion semantics; concrete resource selection stays in the supplied connection |
+
+## What changed
+
+ToolInvocationSessionBuilder previously repeated external transitions in both its
+event map and state_machines DSL while also constructing sessions and executing
+Agent entry operations. The new child policy owns one immutable transition set.
+The concrete phase machine and FSMSession source admission read that set. The
+existing parent FSM adapter accepts a policy, so no second domain-aware FSM
+implementation is introduced. Entry operations remain executable Agent code.
+
+ToolInvocation now requires its owning execution environment for authorization
+and execution. It no longer selects Runtime.instance, inspects EventLoop, creates
+an ExecutionRegistry connection or selects ToolExecutor. The parent Agent and
+recovery already retain the environment from unit 7; the same environment now
+supplies Tool child entry operations. Authorization captures immutable command
+data before submission. Worker completion delivers an outcome, and serial event
+delivery applies live state.
+
+Tool::Operation.call_async is the C06 operation entry for composition-aware
+callers. It selects the standard or custom Tool protocol and validates the
+execution mode and completion handle. Its submitter must implement C13 submit;
+it receives no Agent-specific type. The default offloaded path uses the supplied
+connection, while cooperative work executes inline without a worker. Custom
+call_async implementations keep their existing keyword signature and config,
+return their original handle and continue to own their execution mechanism.
+In particular, an override that calls super still uses the existing Base
+protocol; this change does not inject hidden Runtime state into overrides.
+
+Tool::Operation.with_result_transform owns the synchronous/custom-async Tool
+decoration mechanism formerly embedded in Agent::ToolBinding. Agent still chooses
+its configured filters and their meaning. Custom async mapping uses
+AsyncOperation.map and preserves physical completion after logical cancellation.
+As before, an override that itself calls an already decorated synchronous method
+can transform twice; this unit does not rewrite arbitrary application overrides.
+
+## Preserved behavior and limits
+
+Authorization completion keeps cancelled > failed > rejected > approval wait >
+authorized priority. Execution completion keeps cancelled > failed > completed.
+Validation keeps failure > completed schema handling > authorization. Explicit
+approve/reject/dispatch/cancel events keep their legal source phases.
+Start execution still precedes mark_running!, preserving dispatch eligibility.
+
+Approval/recovery create fresh FSMSession routing IDs while retaining durable
+execution, Tool call and invocation IDs. Parent sinks are session-local. This
+change does not alter persistence schema, CAS revisions, approval snapshots,
+causal dispatch preparation, stale-result handling, single-writer ownership or
+terminal persistence after physical quiescence. Cancellation/timeout do not undo
+external effects or forcibly stop workers; exactly-once effects are not promised.
+
+The new tests cover all 48 child guard combinations, legal event sources,
+standalone policy loading without Engine/state_machines, worker-result isolation,
+owning-environment submission, fresh recovery routing, custom call_async and
+physical-completion-aware result transformation. Existing parent transition,
+approval, recovery and shutdown suites remain acceptance gates. The AST gate now
+also rejects concrete Engine/FSM references and ToolExecutor selection in Agent
+tool_execution. Static gates are scoped; they do not prove every dependency valid.
+
+MultiAgent/Workflow FSM and Runtime connections, Workflow durable children,
+other concrete composition choices, overall dependency review and additional
+live-service/persistence acceptance tests remain. Regenerate the measured graph
+from the exact candidate; target diagrams are not measured dependency evidence.

data/docs/architecture/r8-unit9.md

@@ -0,0 +1,73 @@
+# R8 unit 9: preserve application-defined Tool result transformations
+
+## Ownership
+
+The application owns which transformations run, their order and their
+multiplicity. Agent's ToolBinding captures and composes its configured filters.
+C06 Tool owns the operation/decorator mechanism that executes that composition.
+C13 Execution owns completion adaptation, failure/cancellation propagation and
+physical-completion tracking. Shared use is not the reason for C06 ownership.
+
+There is no universal "one filter per public invocation" policy. Each configured
+stage must retain its position and multiplicity. Registering the same filter
+twice or nesting result decorators remains meaningful application composition.
+
+## Defect
+
+In unit 7 and unit 8 a custom call_async delegating with super reached Base's
+default async bridge, which invoked the decorated synchronous call. A second
+decoration then transformed the custom async completion. One configured stage
+therefore ran twice. If the custom implementation additionally mapped the result,
+the first transformation also ran on an intermediate value rather than the
+custom operation's final result.
+
+## Internal delegation
+
+Operation.with_result_transform records the exact synchronous wrapper method
+only when that decorator also installs an async completion wrapper. Base's
+call_async obtains a bound synchronous delegate from Operation. That delegate
+skips the leading framework wrappers whose async counterparts already own their
+stages. ToolExecutor receives the callable explicitly and invokes it inline or
+inside the submitted worker, on the original Tool instance.
+
+Selection stops at application methods and sync-only decorator stages. Exact
+method matching avoids bypassing a later application replacement, including a
+singleton call override. No Thread/Fiber local flag, per-instance busy flag,
+cloning, value tagging, equality check or filter-identity deduplication is used.
+
+## Application calls remain application calls
+
+Only Base's standard async-to-sync bridge is internal delegation. A custom
+implementation that explicitly calls the public call method invokes that
+method's configured transformations. Its async completion can then have its own
+transformation. The framework does not guess whether the application intended
+that explicit call to be raw execution.
+
+For example, with a bracket transform:
+
+| Composition | Result for x |
+| --- | --- |
+| One stage, custom call_async delegates using super | [x] |
+| Two registrations of the bracket transform | [[x]] |
+| Custom maps super's raw value to custom:x, then one stage | [custom:x] |
+| Custom explicitly calls the decorated public call and prefixes custom: | [custom:[x]] |
+
+Applications wanting Base's normal execution as an implementation step should
+use super. Applications can also call their configured filters explicitly; those
+calls are never deduplicated. A custom override inserted between decorators is
+an application boundary, not a wrapper the framework may silently bypass.
+
+## Preserved completion contract
+
+Custom completions still use AsyncOperation.map. Original failures retain their
+identity, source cancellation remains cancellation, and physical completion waits
+for both source work and active transformations. Cancelling a mapped result still
+does not implicitly cancel its source. Default cooperative/offloaded dispatch,
+the owning submitter, public keyword arguments, effective names, receiver state,
+and schema/authorization rules remain intact.
+
+## Scope
+
+This is a core-only correction. Public signatures and stored schemas are unchanged.
+It does not complete the remaining C01/C02 connections, all C04 composition,
+the source dependency cycles, or the broader acceptance gates.

data/docs/architecture/refactoring-closure.md

@@ -21,7 +21,7 @@ because the later W/S sequence has reached its final step.
 
 | Owner | Name and location | Reason |
 |---|---|---|
-| Application facade | `Phronomy::Persistence`, `persistence/api` | Users address domain repositories and queries. This class is not the neutral backend contract. |
+| Persistence framework | `Phronomy::Persistence`, `persistence/` | Neutral atomic scopes. Domain stores own queries; composition supplies adapters. The previous shared facade is removed in [r8 unit 3](r8-unit3.md). |
 | Domain persistence | Agent, MultiAgent and Workflow `persistence` directories | Codecs, durable meanings, result queries and business constraints belong to the feature. |
 | Resource declarations | Agent persistence, Team/Workflow `storage_contract`, ContentStore | Schemas describe domain metadata; the nested roots keep existing Ruby identities without loading feature runtime just to obtain declarations. |
 | Common storage | `Phronomy::Storage`, `storage` | Resource/Record/Stream/Blob, conditions and transactions describe backend-neutral mechanisms. |
@@ -332,3 +332,12 @@ and coordinated examples migration. The schema issue is addressed in this candid
 old empty-schema manifests require completion on the original version before upgrade.
 Local verification and the exact package trees are recorded in the distribution.
 User application verification remains outstanding; this is not a published release.
+
+
+## Execution abstraction review candidate (2026-09-29)
+
+The historical D02 decisions above describe their applied revisions. The current
+unapplied [execution abstraction candidate](execution-abstraction-review.md)
+places child control lifetime behind Execution.start_child and invocation checks
+behind InvocationControls, removing direct OperationBinding ownership from
+Orchestrator. Do not mark this candidate applied until main is verified.

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

@@ -372,3 +372,19 @@ and coordinated examples migration. The schema issue is addressed in this candid
 old empty-schema manifests require completion on the original version before upgrade.
 Local verification and the exact package trees are recorded in the distribution.
 User application verification remains outstanding; this is not a published release.
+
+
+## Execution abstraction review candidate (2026-09-29)
+
+The historical D02 decisions above describe their applied revisions. The current
+unapplied [execution abstraction candidate](execution-abstraction-review.md)
+places child control lifetime behind Execution.start_child and invocation checks
+behind InvocationControls, removing direct OperationBinding ownership from
+Orchestrator. Do not mark this candidate applied until main is verified.
+
+## r8 unit 7 scoped update
+
+Agent progress/entry operations and top-level execution/recovery connection are
+separated as described in [r8-unit7.md](r8-unit7.md). This supersedes earlier
+AgentInvocationSessionBuilder construction references. Tool child, MultiAgent
+and Workflow connections remain. Overall contract completion is not claimed.

data/docs/architecture/storage-execution-boundaries.md

@@ -0,0 +1,54 @@
+# Storage execution units in P4
+
+The following 16 submission sites delegate to internal
+`Storage::AsyncClient.submit(pool:)`. Only submission ownership changes: their
+blocks, result callbacks, domain transactions and error/reconciliation policy
+remain in their original owners. Each submitted unit still uses the exact
+pool selected by the owner, with `on_full: :raise` and no new timeout/token.
+
+| Owner / source under `lib/phronomy/` | Unit | Result application |
+|---|---|---|
+| `agent/execution/execution_coordinator.rb` | Provider dispatch preparation | ProviderDispatchPreparationReady on EventLoop |
+| same | Tool dispatch preparation | ToolDispatchPreparationReady on EventLoop |
+| same | Uncertain Provider dispatch reconciliation | ProviderDispatchPreparationReconciliationReady |
+| same | Uncertain Tool dispatch reconciliation | ToolDispatchPreparationReconciliationReady |
+| same | Initial invocation preparation | InitialPreparationReady |
+| same | Recovery of initial preparation | InitialPreparationRecoveryReady |
+| same | Approval resume commit | ResumeCommitReady; existing admission handling |
+| same | Terminal outcome commit | TerminalCommitReady; existing save/readback and live-state policy |
+| `agent/execution/exact_execution.rb` | Exact execution read, recovery and materialization | Original observer completion / owner installation |
+| same | Exact execution reconciliation and result materialization | Original observer completion |
+| `agent/recovery/recovery_coordinator/resolution.rb` | Resolution preparation, save/readback and materialization | ResolveReady; validate before applying live state |
+| `workflow/execution/workflow_runner.rb` | Durable snapshot load | Original load-ready command |
+| same | Terminal snapshot save and uncertain-result readback | Original terminal persistence delivery |
+| `multi_agent/durable_subagent_coordinator.rb` | Reserved child load/create/recovery and input materialization | Original exact child execution observer |
+| `multi_agent/team_coordinator.rb` | External cancellation's durable transition | Existing cancellation/readback policy |
+| same | Durable Team Tool operation and reconciliation | Original Tool completion/error policy |
+
+The three MultiAgent sites are included because they perform the same kind of
+durable work as Agent and Workflow. They do not introduce a new shared domain
+transaction or move Team rules into Storage.
+
+## Boundaries deliberately retained
+
+| Existing boundary | Reason |
+|---|---|
+| Agent approval listener dispatch | Application callback; not a storage operation |
+| ToolExecutor / ToolInvocation authorization pool | Tool execution and authorization; their token/timeout contracts remain distinct |
+| LLM / VectorStore / Embeddings clients | Already own their feature-specific execution boundaries |
+| Tracing and evaluation scorer | Telemetry / scoring work, not storage |
+| MCP cleanup pool | Transport cleanup, not storage |
+| Synchronous Agent load/create, domain repository methods and recovery helpers | Stay synchronous; their existing callers own the offload boundary |
+
+Internal submit does not call `backend.transaction`. Public
+`Storage::AsyncClient#transaction_async` opens exactly one outer raw transaction
+on the worker and yields its view. They are separate entry points because a
+durable domain unit may already have transactions, reconciliation reads and
+materialization in a defined order. Adding an outer transaction would change
+that order's commit visibility, connection lifetime and uncertain-result behavior.
+
+Runtime tests cover original TaskResult identity, single submission, rollback,
+nested savepoints, scope lifetime, cancellation/timeout and preserved failures.
+Existing Agent/Workflow/Team tests continue to exercise admission, uncertain
+commits and live-state application. Real SQLite verification complements these
+tests; static dependency lines alone do not prove transaction behavior.

data/docs/architecture/tool-schema-recording-gap.md

@@ -1,5 +1,11 @@
 # Historical finding: Tool parameter schema is absent from saved definitions
 
+> 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`.
+
+
 ## Observed mismatch
 
 During Refactor 44 verification, Ruby 3.3.6 with RubyLLM 1.16.0 reproduced the

data/docs/architecture/tracing.md

@@ -164,7 +164,7 @@ redefine the behavior of Application code that directly calls the public
 
 ## 10. TokenUsage
 
-`Phronomy::TokenUsage` has four fields:
+`Phronomy::LLMAdapter::TokenUsage` has four fields:
 
 ```text
 input

data/docs/architecture/workflow-terminal-ownership-design.md

@@ -10,7 +10,7 @@ Implementation baseline: core `01cd2f57549f6d1e60825254f4520d0f123e651c`
 
 FSMSession drives one live state machine on EventLoop. WorkflowRunner assembles
 Workflow transitions, stream observation and any durable terminal save.
-AgentInvocationSessionBuilder uses the same engine for input, LLM and Tool
+InvocationActions and EngineSessionBuilder uses the same engine for input, LLM and Tool
 progression; ToolInvocationSessionBuilder uses it for authorization, approval
 and Tool execution. Therefore the session stays in Engine.
 
@@ -23,7 +23,7 @@ and interpreted its save outcomes. WorkflowTerminalPolicy now owns that rule.
 |---|---|
 | FSMSession | Identity/sink, transitions, live context, pending terminal kind/notification flag, event acceptance and final notification/event ordering. |
 | WorkflowTerminalPolicy | Start the injected save callback; recognize the Workflow result event; map its outcome to a generic terminal decision. |
-| FSMProtocol::TerminalDecision | Immutable `action` and `error` value shared by a domain policy and the session. No live session authority. |
+| Phronomy::TerminalDecision | Immutable `action` and `error` value shared by a domain policy and the session. No live session authority. |
 | WorkflowRunner | Construct a policy for durable execution; retain snapshot capture, one save, F1 readback and caller completion. |
 | WorkflowExecutionRegistry | Admission, owner tokens, session routing binding and recovery-required ownership. |
 | EventLoop | Event routing, management events, retirement, source completion and shutdown. |

data/docs/architecture.md

@@ -23,6 +23,13 @@ reviewed explicitly rather than resolved by recency.
 
 ## Design principles
 
+The current r8 refinement of Agent parent/Tool child progress and concrete
+execution connections is described in [unit 8](architecture/r8-unit8.md), building
+on [unit 7](architecture/r8-unit7.md). C04 owns Agent progress and approval/recovery;
+C06 owns Tool operations; C13 supplies execution submission/completion. Concrete
+FSM construction stays in Agent runtime_binding. These scoped changes do not
+declare the full contract target or remaining dependency cycles complete.
+
 These are design heuristics for new and revised architecture. They do not
 override an Accepted ADR, an established public/extension contract, or an
 explicit compatibility decision.
@@ -105,7 +112,8 @@ synchronous FSM callback exceptions. Recovery owns shared rehydration
 requirements. Workflow implementation lives under `workflow/execution/`;
 Agent namespace/event loading lives under `agent/api/`, separately from the shared
 Agent lifecycle exceptions in `agent/lifecycle_contract/`. LLM values and
-call-boundary exceptions live under `llm_contract/`.
+call-boundary exceptions live under `llm_adapter/`, together with the SDK-neutral
+operation contract. See [r8 unit 6](architecture/r8-unit6.md).
 
 Agent consumes its private fresh-Persistence factory only when neither an
 explicit instance nor a configured instance is available. Concrete selection
@@ -175,14 +183,13 @@ confirmed resume. Internal Coordinator type aliases remain, with changed
 canonical names and an added Command snapshot field. See
 [ADR-050](decisions/050-approval-resume-snapshot-and-commit-ownership.md).
 
-`Agent::ExecutionOutcomeCommitter` owns ordinary completion, failure, suspension
-and child waiting; `Agent::HandoffOutcomeCommitter` adds atomic Source transfer.
-The Handoff Coordinator now only selects its worker. Transaction boundaries,
-operation-specific readback and Handoff selection precedence remain unchanged.
-Coordinator retains quiescence, submission, stale-result validation, live-state
-application, admission and Task/listener delivery. Command/view/outcome types are
-worker-owned with internal Coordinator aliases and changed canonical Ruby names.
-See [ADR-051](decisions/051-execution-outcome-worker-ownership.md).
+`Agent::ExecutionOutcomeCommitter` and `Agent::ExecutionChange` own Agent
+completion, failure, suspension, dispatch preparation and commit proof. A limited
+participant joins its own domain changes to the same scope. MultiAgent owns
+subagent reservations and Handoff routing; it passes extension state and transfer
+receipts, never Agent records or arbitrary update blocks. The EventLoop owner
+continues to apply confirmed results and deliver callbacks. See
+[r8 unit 4](architecture/r8-unit4.md).
 
 The remaining execution owner expresses result handling as validation, committed
 state installation, and continuation or delivery. Private methods keep these
@@ -224,8 +231,10 @@ The Agent entry explicitly preserves Agent lifecycle extension installation.
 Configuration accessors now live beside Configuration, rather than inside the
 loader. Configuration constructs fresh components through internally bound
 factories; composition selects their concrete types. Static source-reference
-graphs do not follow these injected calls. LLMAdapter's async bridge still uses
-Runtime, and other dependency cycles remain.
+graphs do not follow these injected calls. LLMAdapter's private AsyncClient now
+owns the Runtime dependency; its synchronous Base and RubyLLM implementation
+are independent of Engine. VectorStore/Embeddings migration and other cycles
+remain. See [Backend responsibilities](architecture/backend-groups.md).
 
 Agent and Team implement their identity registries in `agent/` and
 `multi_agent/`. Runtime strongly retains one of each when registered, using only
@@ -254,6 +263,7 @@ generated semantic definition IDs retain their previous values. See
 
 | Area | Current document |
 |---|---|
+| Backend Contracts, Implementations, Async Clients and dependency diagrams | [Backend responsibilities](architecture/backend-groups.md) |
 | Agent state, identity, ownership, and Context authority | [Agent Context](architecture/agent-context.md) |
 | Per-LLM-call Context Policy and Manifest construction | [Context Management](architecture/context-management.md) |
 | Journal-backed Knowledge and retrieval integration | [Knowledge and RAG](architecture/knowledge-and-rag.md) |
@@ -296,3 +306,6 @@ Durable multi-agent coordination is described by [ADR-029](decisions/029-semanti
 TeamExecution is a purpose-specific CAS authority delegating coordinator/workers
 to ordinary Agents, with no Team FSMSession or second Workflow engine.
 Static subagent reservation lives in the existing parent AgentExecution metadata.
+
+Current C10/C11 common operation ownership and independent Embeddings/Documents
+placement are specified in [r8 unit 5](architecture/r8-unit5.md).