phronomy 0.26.0 → 0.28.0

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

@@ -0,0 +1,83 @@
+# ADR-058: Neutral Storage primitives and scoped transactions
+
+## Status
+
+Accepted. Applied and verified in Refactor 35 (Storage S2b/S2c), core
+`ebd99623f94c8b2db2d74355bfa39f01550778a0` and examples
+`68a0bbd0e354b9e00bbfed728ad2b769b389ed8a`.
+
+Domain-facing exception ownership is further amended by
+[061-persistence-failure-contracts](061-persistence-failure-contracts.md).
+Raw backend exceptions remain owned by Storage; domain repository exits now
+translate their known categories to independent Persistence exceptions.
+
+## Context
+
+S1 inventoried 37 raw methods across eight required domain slots. Moving their
+classes did not remove Agent watermark or active-owner policy from shared
+storage. S2a fixed concrete transaction and update differences first. S2b now
+changes the extension contract while preserving domain APIs and durable data.
+
+## Decision
+
+1. Replace the eight-slot Backend/Repositories SPI with declared Resources and
+   Records, Streams, Blobs accessed through View. Storage has no domain codecs,
+   active-execution interpretation, content digest or Agent watermark method.
+2. Keep schemas, encoding, initial revisions, active-state interpretation and
+   metadata validation in their features. Composition gathers declarations and
+   builds domain wrappers. Team/Workflow schema loader roots do not load runtime.
+3. Use named equality indexes, conditional unique constraints, immutable metadata,
+   revision CAS, stream head CAS and a closed guarded-condition set. Parent guards
+   precede child locks. Required parent absence is uniformly NotFoundError.
+4. Keep one transaction domain, scoped views, same-connection savepoints and root
+   handle routing. Reject expired/cross-thread views and failed physical scopes.
+   Reject non-local block exits with TransactionError and rollback. A successful
+   optional read returning nil is not a failed physical operation.
+5. Report neutral UniqueConstraintError(resource ID, constraint name) and
+   ConditionFailedError(condition). Only owning domain repositories map exact
+   active constraints to AgentBusyError. Remove the old domain-named error alias.
+6. Share neutral SQL operations in examples/shared/storage, with explicit dialect
+   differences and separate domain/table composition. Keep all existing tables,
+   indexes, envelope formats, payloads, IDs and content bytes. Nullable unique-key
+   fields are distinct, matching SQL default uniqueness semantics.
+
+## Supersession scope
+
+This amends ADR-032's raw eight-slot contract, ADR-033's remaining fixed raw
+boundary, ADR-043's domain-named raw exception and ADR-057's old-SPI-only limit.
+Their domain ownership, composition, savepoint and uncertainty decisions remain.
+No historical artifact is silently reinterpreted as a current SPI specification.
+
+## Public contract and migration
+
+Persistence's constructor, in_memory, eight accessors, result queries and public
+capabilities remain. Backend SPI 2 is intentionally breaking; legacy duck-typed
+backends fail capability validation. There is no compatibility facade or alias.
+See the [contract](../persistence-backends.md), [migration guide](../migrations/neutral-storage-spi.md),
+RBS and explicit SPI 2 snapshot. Ordinary product API snapshots remain separate.
+
+## Validation and remaining gates
+
+Shared conformance tests cover opaque data, CAS, named constraints, parents,
+Unicode cursor ordering, streams, binary blobs, all-resource rollback, nested
+savepoints, view lifetime, thread confinement and non-local exits. Domain tests
+retain F0/F1/F4 behavior and X0 limitations. SQLite old/new/old round-trip checks
+cover all eight resources and unchanged schema. The applied SPI 2 pair passed
+[PostgreSQL 17.11 CI](https://github.com/Raizo-TCS/phronomy-examples/actions/runs/35827495677)
+on Ruby 3.2/3.3/3.4, with 119 examples per version and fresh-pool reload. Both
+checkout SHAs were verified. Earlier SPI CI was not used as substitute evidence.
+No stronger commit certainty, distributed Workflow admission or external-effect
+retry is introduced.
+
+## S3 internal responsibility clarification
+
+Refactor 36 keeps all public SPI 2 signatures and Resource identity rules.
+Resource normalizes a schema object or resource ID before GuardRef/Condition
+construction; the cooperation method is `@api private`, not a new backend
+extension point. Generic Validation handles scalar validation and copying and
+must not depend on Resource. View still enforces catalog membership and exact
+schema identity. This removes the internal Resource/Validation cycle without
+changing a public name, transaction, stored record or physical backend.
+
+See the [closure review](../architecture/refactoring-closure.md) for retained
+placements and the separate distribution application gate.

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

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

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

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

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

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

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

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

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

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

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

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

data/docs/decisions/065-vector-and-embeddings-common-operations.md

@@ -0,0 +1,38 @@
+# ADR-065: Vector and Embeddings common operations
+
+Status: accepted for the authorized r8 unit 5 implementation. Actual-service
+verification is reported separately from the design decision.
+
+This amends ADR-059's vector/embedding extension and namespace provisions.
+Its synchronous backend boundary, separate AsyncClients and no production worker
+Threads rule remain in force. It implements C10/C11 and DP09/DP10 from the agreed
+contract foundation target.
+
+VectorStore::Base and Embeddings::Base own the public operation templates,
+validation and cancellation checkpoint. Concrete backends override protected
+perform_* hooks, retaining algorithms, database/SDK adaptation and physical state.
+VectorStore does not require an embedding provider, and Embeddings does not depend
+on VectorStore. Documents groups the existing Loader/Splitter helpers without
+creating another domain Contract.
+
+Placement is decided by domain meaning and observable rules, not shared use.
+Generic reusable code does not become a Contract merely because multiple callers
+need it. Database response parsing and SDK/serialization adaptation remain
+implementation responsibilities even when several backends perform similar work.
+
+Malformed public inputs fail before backend I/O. Malformed backend results fail
+explicitly. Provider exceptions are adapted at the provider boundary, never by
+rescuing arbitrary application failures in the common framework. No generic retry,
+commit reconciliation or stronger concurrency guarantee is added.
+
+Backends must reject malformed external data before converting it to the public
+result. Redis RESP2 fields/counts/distances and Pgvector rows/JSON are decoded
+inside their own backends, with `VectorStore::InvalidResultError` as the public
+failure for invalid data. Legitimate absent metadata and Redis's documented
+expired-document response are distinguished from corruption. The common Base
+then validates the domain result; it contains no external-protocol decoder.
+
+Old namespaces and public-template overrides are intentionally replaced without
+compatibility aliases. Runtime API, RBS, contract tests, examples and migration
+guidance move together. See [unit 5](../architecture/r8-unit5.md) and
+[migration](../migrations/r8-unit5.md).

data/docs/decisions/066-llm-and-tool-operation-contracts.md

@@ -0,0 +1,20 @@
+# ADR-066: LLM and Tool operation contracts
+
+Status: Accepted for the r8 unit 6 candidate; application verification is separate.
+
+C09 owns model-turn values, operation invariants, usage and failures. C06 owns Tool
+requests, schemas, validation, authorization and execution rules. Shared usage is
+not a placement criterion. SDK wire parsing/rendering and callback interception
+remain in the RubyLLM backend. Agent owns context, approval, durable execution and
+recovery; AsyncClient submits the complete backend operation to Execution.
+
+Tool::Base becomes independent of RubyLLM::Tool. The schema used for advertisement
+is also the validation source for both declaration paths. C09 depends only on C06
+value/schema semantics, never executable Tool instances. Protected hooks allow a
+minimal independent backend; public complete/stream enforce the common contract.
+No forwarding namespace or legacy SDK-shaped adapter SPI is retained.
+
+Consequences and compatibility are recorded in
+[unit 6 architecture](../architecture/r8-unit6.md) and
+[unit 6 migration](../migrations/r8-unit6.md). Existing pending execution schema
+comparisons remain strict; deployment must account for changed Tool definitions.

data/docs/decisions/067-agent-progress-and-engine-connection.md

@@ -0,0 +1,29 @@
+# ADR-067: Agent progress owns policy; composition supplies its execution connection
+
+Status: accepted for r8 unit 7 candidate. Supersedes the construction ownership
+portion of the Agent transition design; durable guarantees are unchanged.
+
+## Decision
+
+Keep progress rules, entry operations, admission, approval and recovery decisions
+inside Agent. Introduce the private ExecutionEnvironment connection and an Engine
+implementation. Bind a live Agent to the environment of its ownership registry.
+Move concrete session/phase-machine construction to agent/runtime_binding.
+Keep state_machines out of InvocationTransitions. Extract the serial receiver
+lifecycle framework to Execution with an Engine-owned channel implementation.
+
+## Why
+
+The old session builder mixed domain operations with concrete FSM construction.
+Repeated Runtime.instance lookups made execution connection selection implicit.
+Moving all code into a binding would relocate the same semantic mixture.
+A contract owns executable rules, not just signatures or forwarding methods.
+
+## Consequences
+
+The application invoke/stream/approval/recovery API is unchanged. Internal
+AgentInvocationSessionBuilder is removed with no alias. Private receiver
+constructors now accept a channel. Internal embedders must adopt the composition
+port and respect serial mutation, bounded submission, shutdown and session
+incarnation rules. Tool child and other domain FSM decomposition remain separate
+work. See ../architecture/r8-unit7.md for scope and verification.

data/docs/decisions/068-agent-tool-child-progress-and-tool-operation.md

@@ -0,0 +1,36 @@
+# ADR-068: Agent owns Tool child progress; Tool owns its operation protocol
+
+Status: accepted for the r8 unit 8 candidate. Extends
+[067-agent-progress-and-engine-connection](067-agent-progress-and-engine-connection.md)
+to Tool children and refines the operation boundary in
+[066-llm-and-tool-operation-contracts](066-llm-and-tool-operation-contracts.md).
+
+## Decision
+
+Keep Tool child transitions, approval waiting, dispatch eligibility, outcome
+application and parent notification in C04. Use one ordered transition definition
+for both concrete FSM construction and source admission. Move FSMSession and
+state_machines construction into Agent runtime_binding. Pass the original Agent
+execution environment explicitly to child authorization and execution.
+
+C06 owns standard/custom Tool operation dispatch, execution-mode validity,
+completion protocol and result adaptation. It accepts the C13 submitter protocol
+for standard offloaded work. Agent uses the public operation rather than
+inspecting the implementation owner and calling the private default executor.
+Custom Tool#call_async overrides keep their public signature and own mechanism.
+
+## Reason
+
+The previous builder mixed Agent rules with concrete connections and duplicated
+transition definitions. Agent also selected Tool implementation paths in both
+invocation and result binding. Moving whole classes to an adapter or assigning
+all Tool-related progress to C06 would preserve or misplace those responsibilities.
+
+## Consequences
+
+The boundary now supports independent Agent policy tests and Engine adaptation
+tests. No concrete Runtime or Agent type enters C06. Existing durable identity,
+approval/recovery, causal revision and physical-quiescence guarantees remain.
+No new exactly-once or in-flight version compatibility is claimed. See
+[the unit 8 scope](../architecture/r8-unit8.md) and
+[migration instructions](../migrations/r8-unit8.md).