phronomy 0.26.0 → 0.28.0

data/docs/architecture/r8-unit3.md

@@ -0,0 +1,130 @@
+# r8 unit 3: Persistence ownership and Team/Agent operations
+
+This is a candidate based on core `a82974a7fd2360a13af71831a0c3ddc75942fae3`
+and examples `70b7244c9f6542062849869a7106c5a627868a80`. It implements P01 and
+removes concrete adapter selection from the unit 2 admission framework. P04 is
+partially implemented for Team authorization and scheduling. It is not completion
+of the full contract architecture.
+
+## Ownership and public application construction
+
+```ruby
+stores = Phronomy::PersistenceComposition.in_memory
+# Or: PersistenceComposition.build(backend: configured_storage_backend)
+
+Phronomy.configure do |config|
+  config.agent_store = stores.agent
+  config.team_store = stores.team
+  config.workflow_store = stores.workflow
+end
+
+agent = MyAgent.create(persistence: stores.agent)
+team = MyTeam.create(persistence: stores.team)
+workflow = Phronomy::Workflow.define(MyContext, persistence: stores.workflow) do
+  # Workflow definition
+end
+
+agent_result = stores.agent.result(agent_execution_id)
+team_result = stores.team.result(team_execution_id)
+```
+
+For an isolated Agent, `PersistenceComposition.agent(backend: optional_backend)`
+constructs only the Agent/content components. Ordinary Agent defaults use this
+factory. A composition result is a construction bundle, not a query or execution
+service; pass only the relevant component to each consumer.
+
+| Owner | Operation / responsibility |
+|---|---|
+| `Persistence` | `atomic`, scope validity, participation and outer commit |
+| `Agent::Store` | Agent result/list/presence/authorization operations, injected Agent record protocol |
+| `MultiAgent::Store` | Team result/list operations, injected Team record protocol and Agent public operations |
+| Workflow checkpoint port | `load`, `save`, `delete` with instance ID and expected revision |
+| Domain `persistence/` implementations | physical resource schema, records, codecs and guards |
+| `PersistenceComposition` | selects backend and adapters, validates schemas and binds components |
+
+The stores are roles inside the existing domain framework, not new independent
+contracts. Logical acceptance and state-transition decisions remain in Admission,
+TeamCoordinator, and the owning domain operations. Record accessors on stores are
+internal protocols for their own domain, not cross-domain application APIs.
+Common Persistence neither knows these types nor imports composition.
+
+## Atomic participation remains unchanged
+
+The parent reservation is committed first. At child acceptance, the parent guard
+is acquired before reading the current reservation, then Agent input/execution
+and root revision are written in that same scope. The parent's domain owns its
+reservation/cancellation/identity checks. Agent does not interpret parent schemas.
+Only after the outer commit does Agent expose its accepted state and start work.
+
+Domain adapters are injected at construction and receive the exact scope's view.
+They never select another connection or commit independently. The coordinator
+identity, same-thread lifetime, savepoint behavior, conflict classification,
+rollback, and uncertain-commit behavior remain in force. LLM/Tool work and async
+waiting remain outside these short transactions. Wrapping ordinary async invoke
+in an application transaction is not a newly supported API.
+
+## Team uses Agent authorization, not execution metadata
+
+`Agent::Store#authorized_operations(scope, agent_id:, execution_id:,
+invocation_id:, name:, arguments:, names:)` validates the exact requested call
+against one persisted execution snapshot in the caller's scope. It checks the
+Agent owner, invocation identity, authorization state, name, arguments and
+requested operation family. It returns immutable `AuthorizedOperation` values
+with only `invocation_id`, `name`, and `arguments`, in Provider order.
+
+Team applies these operations and owns its durable operation-result ledger.
+A committed replay returns that ledger result without reapplying the batch.
+`finalize` cannot overtake earlier authorized `enqueue_task` calls. A mismatch
+raises `Persistence::StateConflictError` before Team's changes commit.
+`Agent::Store#exist?` reports authoritative absence; failed reads still raise.
+
+Team scheduling now uses its own retained assignment count. The default chooses
+the worker with the fewest assignments, breaking ties in worker order. Custom
+schedulers receive `WorkerState#assignment_count` instead of `transcript_size`.
+The count is derived from existing assignments, including failures; there is no
+extra mutable counter and no Agent journal read. This deliberately changes the
+default balancing metric. It does not estimate tokens, duration or resource load.
+
+## Removed APIs and directories
+
+- `Persistence.in_memory`, common `transaction`, `capabilities`, repository
+  accessors, result/list queries and Agent watermark facade methods are removed.
+  `Persistence.new(backend:)` constructs only the neutral coordinator.
+- Domain result queries are `stores.agent.result` / `.runs` and
+  `stores.team.result` / `.runs`; Handoff observation remains on the Agent store
+  pending the ownership work below.
+- `Configuration#persistence` is replaced by `agent_store`, `team_store`, and
+  `workflow_store`; explicit `persistence:` arguments accept the relevant port.
+- The all-domain `PersistenceComposition::Repositories` and the fixed admission
+  adapter classes are deleted. There are no legacy API aliases.
+- `persistence/api/` and the six-file `persistence/contract/` error subdivision
+  are removed. Shared failures are in `persistence/errors.rb`.
+- Team/Workflow schema declarations are consolidated into their existing domain
+  `persistence/` directories; their separate `storage_contract/` directories and
+  root schema constants are removed.
+
+Storage SPI 2 and physical SQL tables/indexes are unchanged. Existing Agent,
+Handoff and Workflow record codecs are unchanged. New Team worker entries omit
+`transcript_size`; older entries can still be decoded and the unused field is
+ignored by scheduling. Assignment history remains the authority. This does not
+add an API compatibility wrapper or change saved operation results.
+
+## Remaining work (explicitly not claimed complete)
+
+1. Subagent and Handoff still interpret Agent execution/routing records and
+   coordination data. Storage adapter class selection has been removed, but
+   renaming raw record access does not make it a proper public domain operation.
+   Resolve logical ownership, cancellation, responsibility transfer and restart
+   together before changing these paths; existing atomic transfer is preserved.
+2. Orchestrator's preparation/resume integration still accesses Agent-owned
+   execution and context details. Team's new operation projection is not a
+   general solution to those ownership questions.
+3. Domain-to-FSM connections, durable Workflow child protocols, multi-record
+   uncertain-commit evidence and the remaining semantic dependency review are
+   outside this implementation unit. Workflow FINISH translation already exists.
+4. PostgreSQL concurrency verification for this candidate requires the matching
+   core/examples branch or local PostgreSQL setup. Unit 2 CI evidence is not
+   evidence that this candidate has passed PostgreSQL.
+
+The source SVG and full Ruby/RBS evidence report remaining dependencies. Visual
+suppression of shared common-value arrows does not remove graph evidence.

data/docs/architecture/r8-unit4.md

@@ -0,0 +1,79 @@
+# r8 unit 4: Agent execution and MultiAgent responsibility
+
+Core baseline: `3c5fddcae31cc98f8e081feae9b955cf536e5834`.
+Examples baseline: `0370d09fb1608b9596e1803275f713b1a204af26`.
+The foundation mapping dated 2026-09-30 and its target/concept diagrams remain the
+refactoring goal. This change implements the C01/C04 boundary; it does not claim
+that the whole existing implementation already matches the target DAG.
+
+| Responsibility | Owner and current entry point |
+|---|---|
+| Exact execution identity, admission and observation | Agent `ReservedExecution`, `start_reserved_async`, `resume_async`, `cancel_async`, `Store#observe_execution` |
+| Finalized input, groups and provenance | Agent `ControlRequest`, `TransferContext`, `TransferProjection` with Context assembly |
+| Selection policy, Source/Target mapping and routing | MultiAgent `HandoffPolicy`, capability binding, `HandoffRunner`, `HandoffParticipant` |
+| Static subagent slot, definition, input, inherited knowledge and import progress | MultiAgent `DurableSubagentCoordinator`; immutable content snapshot |
+| Execution/Root/journal mutation and publication authority | Agent `ExecutionChange` and `ExecutionOutcomeCommitter` |
+| Whole-Agent retention and durable cancellation intent | Agent public operations; Agent-owned record resources |
+| History removal and release of its own holds | MultiAgent `Store#forget_subagents`, `Store#forget_handoff` |
+| Physical record adapters and schema | Each domain's Persistence implementation; composition assembles them |
+| Offline old-format conversion | `PersistenceComposition::Unit4Migration`; examples SQL runner |
+
+Agent interprets neither child states nor routing phases. MultiAgent uses public
+Agent values and operations; it does not read AgentExecution, raw metadata,
+journals, ContextImporter values or a private event-listener getter. Child results
+are observed from their authoritative execution, never mirrored as mutable child
+statuses in the parent snapshot. IDs for new slots are derived from canonical
+parent Agent/execution/slot identity. Migration preserves existing IDs.
+
+## Commit participant contract
+
+A current, synchronous participant declares a `binding` key/version and implements
+`commit`, `guard_change`, and `change_evidence`. `ExecutionChange` exposes semantic
+inputs only. In one outer `Persistence#atomic` scope the participant:
+
+1. Locks routing/Team guards where needed, then Agent roots in lexical ID order.
+2. Calls `change.prepare_in(scope)` before its own writes. This captures complete
+   pre-state, including cancellation intent, under those guards.
+3. Changes its own records and calls `change.commit_in(scope, state:, transfer_receipt:, pending:)` once.
+4. Returns after the outer commit. Agent publishes the captured result only then.
+
+The change is bound to the original thread, coordinator and prepared scope. It
+checks its Agent watermark and expected execution revision. A nested savepoint
+cannot authorize publication. Reconciliation compares Root, execution payload,
+appended journal, extension content, cancellation intent, and participant evidence
+in a consistent scope. Exact post-state proves commit; exact pre-state proves no
+commit; different state or failed reads require recovery. There is no write retry.
+An updated record at the expected revision alone is insufficient evidence.
+
+Subagent cancellation retains unresolved active work. Known business errors may
+follow `on_error: :skip`; unknown external outcomes cannot be skipped into success.
+Handoff Source transfer and Target terminal stabilization join the same Agent
+change. A suspended or recovery-required Target does not stabilize routing.
+Current participant key/version and Target definition must match before resuming.
+Terminal results can still be read without re-creating application wiring.
+
+## Retention and cancellation
+
+`agent.retentions` prevents purge independently of MultiAgent schema. C01 records
+its parent/child or conversation holds when reserving/creating work. History
+removal checks unfinished work, removes its references and releases only its own
+owner key in the same transaction. Other holds remain authoritative.
+`agent.cancellations` stores monotonic intent separately from execution revision,
+so an external cancel does not invalidate an in-flight worker's captured revision.
+Signal delivery follows the durable write; restored executions read that intent.
+
+`Agent::Admission` remains the same-scope acceptance boundary. A participant never
+starts a child inside a transaction or waits for its lifetime on a worker thread.
+Ordinary Agent composition does not load MultiAgent routing repositories.
+Standalone `dispatch_parallel` keeps its existing Runtime-scoped behavior.
+
+## Remaining boundaries
+
+`MultiAgent::AdmissionRegistry` still uses Runtime shutdown coordination. Agent,
+Tool and Workflow execution internals still depend on existing Engine mechanisms.
+These are later r8 work, not erased by constructor injection or diagram grouping.
+The measured source diagram includes those edges and cycles. PostgreSQL lock
+ordering needs its actual database gate; SQLite/InMemory results do not establish
+PostgreSQL behavior. The application package records executed and unexecuted gates.
+
+See [API and saved-data migration](../migrations/r8-unit4.md).

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.