phronomy 0.27.0 → 0.28.0

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).

data/docs/decisions/README.md

@@ -88,7 +88,7 @@ resolved explicitly.
 | [`037-common-definition-ownership`](037-common-definition-ownership.md) | Amended | Yes | Defines the common responsibility group and initially extracts the shared base exception; [038-responsibility-based-source-layout](038-responsibility-based-source-layout.md) extends the extraction scope while preserving ownership rules and exception contracts. |
 | [`038-responsibility-based-source-layout`](038-responsibility-based-source-layout.md) | Amended | Yes | Reserves the direct root for version/namespace loading, groups common definitions and feature implementation/contracts, and preserves canonical constants and lifecycle loading through explicit Zeitwerk roots. ADR-039 separates cross-owner Runtime lifecycle coordination. |
 | [`039-runtime-configuration-lifecycle-ownership`](039-runtime-configuration-lifecycle-ownership.md) | Amended | Yes | Separates application Runtime reset and configuration replacement into runtime_composition; configuration access and Engine mechanics retain their own ownership and existing API behavior. ADR-040 separates concrete-default selection without changing Runtime reset. |
-| [`040-configuration-default-composition`](040-configuration-default-composition.md) | Accepted | Yes | Settings consume internal fresh-instance factories; runtime_composition selects and binds the concrete adapter/tracer defaults. Preserves Configuration.new and the adapter SPI. |
+| [`040-configuration-default-composition`](040-configuration-default-composition.md) | Amended | Yes | Settings consume internal fresh-instance factories; runtime_composition selects and binds the concrete adapter/tracer defaults. Preserves Configuration.new and the adapter SPI. |
 | [`041-feature-owned-identity-registries`](041-feature-owned-identity-registries.md) | Accepted | Yes | Agent and MultiAgent own identity registries; Runtime retains them through generic lookup, drain/wait, and optional finalization. Preserves product APIs and single-owner lifetime; Execution state is separately assigned by ADR-042. |
 
 | [`042-feature-owned-execution-state`](042-feature-owned-execution-state.md) | Accepted | Yes | Agent/Workflow own execution state; Engine retains generic receiver delivery, synchronization and shutdown boundaries. Single-writer and durable barriers remain. |
@@ -110,6 +110,15 @@ resolved explicitly.
 
 | [`058-neutral-storage-primitives`](058-neutral-storage-primitives.md) | Accepted | Yes | Neutral Records/Streams/Blobs SPI 2 and scoped transaction lifecycle; amends 032, 033, 043 and 057. |
 
+| [`059-backend-contracts-and-async-clients`](059-backend-contracts-and-async-clients.md) | Accepted | Yes | P1/P2 separates synchronous LLM contracts, implementations and internal clients; independent responsibility groups replace numbered layers. VectorStore/Storage migration remains pending. |
+| [`060-runtime-settings-and-application-configuration`](060-runtime-settings-and-application-configuration.md) | Accepted | Yes | Separates neutral Engine settings from typed application Configuration; preserves public settings/lifecycle semantics and requires the complete Ruby + RBS boundary gate without exceptions. |
+
+| [`061-persistence-failure-contracts`](061-persistence-failure-contracts.md) | Accepted | Yes | Independent domain failure contracts and explicit raw Storage translation; public rescue-clause migration, preserved transaction/admission/uncertainty semantics. |
+| [`062-content-store-service`](062-content-store-service.md) | Accepted | Yes | Content management over neutral Storage; removes the unnecessary backend subdivision and preserves content/Persistence behavior. |
+
+| [`063-execution-contracts-and-services`](063-execution-contracts-and-services.md) | Accepted | Yes | Shared execution contracts and result/call services separated from Engine internals; preserves public APIs and fixes filtered physical completion. |
+| [`068-agent-tool-child-progress-and-tool-operation`](068-agent-tool-child-progress-and-tool-operation.md) | Accepted | Yes | C04 Tool child progress and original environment; C06 operation dispatch/result adaptation; child FSM in runtime_binding. |
+
 ## Legacy duplicate `011`
 
 The repository intentionally preserves both legacy files:
@@ -203,3 +212,11 @@ Current explanatory architecture starts at
 segregated under `docs/archive/design/` and are non-normative. Explanatory
 architecture documents describe the reconciled current system but do not
 supersede ADRs merely by being newer.
+
+- [`064-agent-execution-and-multi-agent-responsibility`](064-agent-execution-and-multi-agent-responsibility.md)
+
+- [`065-vector-and-embeddings-common-operations`](065-vector-and-embeddings-common-operations.md) — accepted for r8 unit 5; amends the vector/embedding SPI and namespace provisions of ADR-059.
+
+- [`066-llm-and-tool-operation-contracts`](066-llm-and-tool-operation-contracts.md)
+
+- [`067-agent-progress-and-engine-connection`](067-agent-progress-and-engine-connection.md) — Agent progress rules and Engine connection ownership.

data/docs/execution-boundaries-preview.md

@@ -0,0 +1,45 @@
+# Execution boundary candidate (unapplied)
+
+Base: main 653e255a34fe4062d4beca47530e084fdd3a6ba9.
+This is an unpublished prototype for source-derived architecture review.
+
+TaskResult, Outcome, result composition, physical completion and ScopeState
+belong to Execution Results. They depend on Contracts and Common, without
+acquiring Runtime or calling Execution Services. Engine and Services share
+these neutral results. OffloadPool uses an injected timer protocol; its wait
+guard uses WaitPolicy. Services owns operation binding, timer subscriptions,
+worker submission and invocation-control adaptation.
+
+Workflow::Completion owns the public DSL finish value `:__finish__`.
+WorkflowPhaseMachineBuilder, beside WorkflowRunner, translates it to the FSM
+terminal state. FSMSession retains terminal detection and persistence gating.
+TerminalDecision is an execution contract, independent of Workflow and FSM
+state vocabulary.
+
+## Intentional compatibility changes
+
+* InvocationContext#effective_timeout_token and #effective_cancellation_token
+  are removed. Although annotated private, both occurred in the Stable API
+  snapshot. This candidate updates those two entries explicitly. Applications
+  pass cancellation_token/deadline into InvocationContext; the invoking
+  service applies them. Code needing a standalone token constructs
+  Concurrency::CancellationToken directly.
+* Deadline#attach_to is removed. Deadline is a time value, not a timer owner.
+  Internal Workflow control adaptation moves to InvocationControls.
+* Unused private CancellationScope is removed. Private
+  Workflow::PhaseMachineBuilder becomes WorkflowPhaseMachineBuilder in the
+  Runner source directory. FSMProtocol::TerminalDecision becomes
+  Phronomy::TerminalDecision. Direct requires of moved internal files change.
+* An already expired Workflow deadline now cancels immediately. An explicitly
+  supplied token still takes precedence over that deadline, as before.
+
+TaskResult/map/flat_map/all_settled and AsyncClient public operations remain.
+WorkerSubmission preserves injected-pool ownership, original result identity,
+operation-time Runtime resolution and synchronous admission errors. Blocking
+continues converting admission errors to failed results. MCP keeps its named
+cleanup pool. Engine connections remain with registries/coordinators/runners.
+
+RBS declares scope, timer, receiver and terminal-policy protocols in sig/.
+Validation checks signature consistency, not whole-program type correctness.
+The static diagram includes Ruby and RBS evidence; injected implementations
+and callback behavior also require runtime tests.

data/docs/features.md

@@ -46,12 +46,17 @@ rather than implicitly inheriting the parent revision. The Stable
 |---|---|
 | **Knowledge** — Journal-backed persistent Agent context registered with `knowledge:` / `add_knowledge`, selected per LLM call by Context Policy | Beta |
 | **`VectorStore#size`** — Document count for InMemory, RedisSearch, and Pgvector backends | Beta |
-| **VectorStore async convenience** — `add_async` / `search_async` / `remove_async` / `clear_async` offload the synchronous Backend SPI through Phronomy and return `TaskResult`; native async override is not part of the current Backend SPI | Beta |
-| **Embedding async convenience** — `embed_async` offloads synchronous `embed` through Phronomy and returns `TaskResult` | Beta |
+| **Storage::AsyncClient** — `transaction_async` runs a raw backend transaction on one worker and returns TaskResult; [usage and lifetime rules](migrations/storage-async-client.md) | Beta |
+| **VectorStore::AsyncClient** — `add_async` / `search_async` / `remove_async` / `clear_async` offload the synchronous Backend SPI through Phronomy and return `TaskResult`; native async override is not part of the current Backend SPI | Beta |
+| **VectorStore::Embeddings::AsyncClient** — `embed_async` offloads synchronous `embed` through Phronomy and returns `TaskResult` | Beta |
 | **Model Context Protocol (MCP) Tool** — `Phronomy::Tools::Mcp` integration through the official `mcp` gem | Beta |
 | **Agent Tool** — `Phronomy::Tools::Agent.from_agent` exposes a child Agent as a Tool without occupying a worker while waiting | Beta |
 | **Vector Search Tool** — `Phronomy::Tools::VectorSearch` wraps VectorStore and Embeddings adapters | Beta |
 
+Applications previously calling async methods on backend objects must
+[move those calls to explicit clients](migrations/vector-async-clients.md).
+Backend authors continue to implement the synchronous SPI only.
+
 ## Execution and reliability
 
 | Feature | Stability |
@@ -88,7 +93,7 @@ See the [migration guide](migrations/parallel-tool-chat-removal.md).
 | Feature | Stability |
 |---|---|
 | **Workflow asynchronous pattern** — Start async work, return immediately, and continue through `Workflow#signal` | Beta |
-| **Durable Handoff** — `Agent::Handoff` and `MultiAgent::HandoffRunner` persist responsibility, immutable Context and exact Target reservation in one Persistence domain; current graph wiring is required for continuation | Beta |
+| **Durable Handoff** — `MultiAgent::Handoff` and `MultiAgent::HandoffRunner` persist responsibility, immutable Context and exact Target reservation in one Persistence domain; current graph wiring is required for continuation | Beta |
 | **GeneratorVerifier** — Generator-Verifier loop with injectable prompts/parsers | Beta |
 | **`Phronomy::MultiAgent::Orchestrator`** — Parallel subagent dispatch, fan-out, and `subagent` DSL | Beta |
 | **`Phronomy::MultiAgent::TeamCoordinator`** — LLM coordinator with stateful worker Agents | Beta |

data/docs/getting-started.md

@@ -50,7 +50,7 @@ Install only the backend gems required by your application:
 ## Define a Tool and Agent
 
 Use `Phronomy::Tool::Base` as the application-facing authoring API. It is an
-exact alias of the existing `Phronomy::Agent::Context::Capability::Base`, so
+exact alias of the existing `Phronomy::Tool::Base`, so
 existing Tool definitions using the longer namespace remain compatible.
 
 ```ruby
@@ -85,7 +85,7 @@ application does not need to pass the previous `messages` array back into every
 invocation.
 
 ```ruby
-persistence = Phronomy::Persistence.in_memory
+persistence = Phronomy::PersistenceComposition.agent
 
 agent = ResearchAgent.create(
   agent_id: "research-session-42",
@@ -250,7 +250,7 @@ end
 write_draft  = ->(state) { state.merge(draft: "Draft content") }
 review_draft = ->(state) { state.merge(feedback: "Feedback on: #{state.draft}") }
 
-persistence = Phronomy::Persistence.in_memory
+persistence = Phronomy::PersistenceComposition.in_memory.workflow
 
 workflow = Phronomy::Workflow.define(
   ReviewContext,
@@ -274,7 +274,7 @@ final = workflow.send_event(state: state, event: :approve)
 puts final.approved
 ```
 
-`Persistence#workflow_states` is the durable Workflow repository. `workflow_instance_id`
+The injected Workflow checkpoint repository supplies `load`, `save`, and `delete`. `workflow_instance_id`
 identifies the durable Workflow state and remains stable across resume. Each
 concrete Runtime execution receives a separate internal `fsm_session_id`; the
 application-level `session_id` remains ordinary caller/tracing metadata. Phronomy
@@ -286,12 +286,15 @@ A global Persistence backend can be configured when Agents and Workflows should
 share one durable backend:
 
 ```ruby
+stores = Phronomy::PersistenceComposition.in_memory
 Phronomy.configure do |config|
-  config.persistence = persistence
+  config.agent_store = stores.agent
+  config.multi_agent_store = stores.multi_agent
+  config.workflow_store = stores.workflow
 end
 ```
 
-Agent `new`/`create` and Workflow definitions use the global backend when they do
+Agent `new`/`create`, Team construction, and Workflow definitions use their configured store when they do
 not inject an explicit `persistence:`. Workflow durability is fixed at the
 application/Workflow-definition boundary; there is no per-invocation backend
 switch.

data/docs/migrations/0.22.md

@@ -178,8 +178,8 @@ and no ordinary Handoff Tool result is generated.
 
 ACS-04 replaces the intermediate Context selection composition API with the
 final four-category Context Policy SPI. Application-defined policies receive an
-immutable `Phronomy::Agent::ContextPolicyInput` and return an immutable
-`Phronomy::Agent::ContextPlan`, each organized as `instruction`, `knowledge`,
+immutable `Phronomy::Context::ContextPolicyInput` and return an immutable
+`Phronomy::Context::ContextPlan`, each organized as `instruction`, `knowledge`,
 `tools`, and grouped `conversation`.
 
 Agent classes bind one Application-constructed Policy instance:

data/docs/migrations/durable-semantic-coordination-v2.md

@@ -1,5 +1,7 @@
 # Durable semantic coordination V2 migration
 
+> r8 unit 4 supersedes the Agent/Handoff ownership and storage portions below. See [the unit 4 migration](../migrations/r8-unit4.md). Earlier statements describe their original change only.
+
 > Runner namespace update (2026-09-18): this document preserves the V2
 > implementation/migration record. The current Runner is
 > `Phronomy::MultiAgent::HandoffRunner` under

data/docs/migrations/handoff-runner-multi-agent.md

@@ -1,5 +1,7 @@
 # HandoffRunner moves to MultiAgent
 
+> r8 unit 4 supersedes the Agent/Handoff ownership and storage portions below. See [the unit 4 migration](../migrations/r8-unit4.md). Earlier statements describe their original change only.
+
 This change applies to H1 on `refactor/architecture` after core commit
 `fe2ad7cea6945a240858b18645dc4ae285e8ce64`. The released 0.26.0 gem does not
 yet provide this new Runner name.

data/docs/migrations/persistence-failure-contracts.md

@@ -0,0 +1,67 @@
+# Migrate the domain Persistence failure contract
+
+This change intentionally changes the exception classes exposed by domain
+Persistence operations. Apply it together with application rescue-clause updates;
+there is no compatibility alias. Public method arguments, return values and
+backend SPI 2 do not change.
+
+## Application and domain repository callers
+
+For calls through `Persistence`, its eight repositories, Agent, Team and Workflow,
+use the upper contract:
+
+| Previous category | New category |
+|---|---|
+| `Phronomy::Storage::ConflictError` | `Phronomy::Persistence::ConflictError` |
+| `Phronomy::Storage::NotFoundError` | `Phronomy::Persistence::NotFoundError` |
+| `Phronomy::Storage::SerializationError` | `Phronomy::Persistence::SerializationError` |
+| `Phronomy::Storage::UnsupportedBackendError` | `Phronomy::Persistence::UnsupportedBackendError` |
+
+For example:
+
+```ruby
+begin
+  root = persistence.agents.load(agent_id)
+rescue Phronomy::Persistence::NotFoundError => error
+  # Handle the missing domain object here.
+  logger.info(error.message)
+end
+```
+
+`Persistence::StateConflictError < Persistence::ConflictError` identifies state,
+ownership or revision contradictions raised by upper domain operations. Catch
+ConflictError when the application handles both state and backend conflicts.
+This subtype is not an instruction to retry: retain operation-specific retry and
+recovery policies. Repository CAS/precondition rejections expose ConflictError.
+
+Translated backend failures retain their original message/backtrace and expose
+the original exception through `error.cause`. Backend constraint/resource details
+remain there. `AgentBusyError` keeps its existing meaning and original cause;
+only the owning active constraint/condition qualifies for that mapping.
+
+## Backend implementations and raw callers
+
+Do **not** globally replace Storage exception names in driver implementations or
+raw `Storage::Backend`/View/Records/Streams/Blobs callers. Those interfaces still
+raise Storage errors. The raw `persistence.backend` accessor exposes that same
+backend. Direct `ContentStore::StoredContents` use also retains its raw failure
+surface; `persistence.contents` applies the upper translation boundary.
+
+Core domain repository conformance examples now expect Persistence errors. Raw
+Storage conformance examples continue to expect Storage errors. Tests which
+inject failures at the physical backend should still inject Storage exceptions;
+tests mocking an already translated repository should inject Persistence errors.
+
+## Commit uncertainty and saved data
+
+Only the four listed categories are translated. Unknown driver/transport errors,
+including IOError, and Storage::TransactionError pass through as the same object.
+ContentStore::IntegrityError and existing domain errors also retain identity.
+Do not classify every Persistence::Error as a known rollback, and do not add a
+retry for a lost commit acknowledgement. Existing admission, transaction scope,
+rollback, nested savepoint and recovery rules continue to apply.
+
+No database migration is required. Saved records and content bytes use the same
+formats. Error class names in newly saved diagnostic payloads can use the new
+Persistence names. Old saved class strings remain diagnostic data; they are not
+resolved as live exception constants or rewritten.

data/docs/migrations/r8-unit10.md

@@ -0,0 +1,36 @@
+# Migrating to r8 unit 10
+
+Apply after core d961fc742f6c4ea4d06dc89f20eedfeb49d04099 (unit 9).
+This package changes core only. The unit 6 examples at
+ed455c52018338f7c5a4c2948ae0d7db131aa090 require no source changes.
+
+Public TeamCoordinator and HandoffRunner arguments and results are unchanged.
+No database migration or application Registry registration is needed.
+The existing registries remain MultiAgent-owned and preserve their rules.
+
+| Internal use | Replacement |
+| --- | --- |
+| AdmissionRegistry.for(runtime) | The owning MultiAgent ExecutionEnvironment.admissions |
+| TeamOwnershipRegistry.for(runtime) | The owning environment.ownership |
+| TeamOwnershipRegistry.existing_for(runtime) | The selected environment.existing_ownership for lookup only |
+| Team/Handoff Runtime.instance checks | The captured environment.current? |
+| Team cancellation Execution.submit(runtime: ...) | The captured environment.submit(...) |
+| Team persistence factory in runtime_composition/agent_defaults.rb | runtime_composition/multi_agent_defaults.rb |
+
+Registry construction remains side-effect free. Tests of domain rules can use
+Registry.new; tests of Runtime registration use MultiAgent::EngineEnvironment.
+Removed private class methods have no aliases. Internal callers are updated
+together. New connection classes are private APIs; public RBS signatures stay
+unchanged. Ordinary require "phronomy" installs defaults lazily, without creating
+global configuration, stores or a Runtime during loading.
+
+The ZIP includes complete changed files, a strict-base applier, expected-tree
+verification, a review patch, test evidence and rollback instructions. Run
+--check, --apply and --verify in a new worktree, then --verify again after commit.
+Use the existing stop/drain procedure when replacing running processes. This
+change does not add in-flight cross-version compatibility or rollback of
+external effects.
+
+For examples verification, unset BUNDLE_GEMFILE before entering the examples
+checkout and set PHRONOMY_PATH to the candidate core. Inspect and restore only
+verification-generated lockfile/vendor changes; no examples commit is needed.

data/docs/migrations/r8-unit11.md

@@ -0,0 +1,33 @@
+# Migrating to r8 unit 11
+
+Apply after core eaff581cb8806c707d47649bb561b70690fa9e57 (unit 10).
+This package changes core only. The unit 6 examples at
+ed455c52018338f7c5a4c2948ae0d7db131aa090 require no source changes.
+
+No application API changes or database migrations are required. Continue to
+load the library with require "phronomy" and use the existing context_policy
+DSL for explicit policies. The boot composition installs DefaultPolicy through
+that same DSL. Reading an unconfigured internal Base now fails explicitly
+instead of selecting a concrete Policy inside Agent.
+
+| Private implementation use | Replacement |
+| --- | --- |
+| Agent::Base concrete Policy fallback | runtime_composition/agent_defaults.rb installs the default |
+| InvocationActions constructs LLMAdapter::AsyncClient | Its captured environment.build_llm_client(adapter: ...) |
+| Agent LLM submission resolves the current global Runtime | EngineEnvironment binds the client to its retained Runtime |
+| AsyncClient constructor | Optional submitter: using existing _ExecutionSubmitter; existing arguments still work |
+
+Internal custom ExecutionEnvironment implementations must supply the new client
+capability. It is not a supported application extension API. Clients created
+without an injected submitter preserve their default Runtime behavior; explicit
+pool arguments preserve precedence. Changing the global default Runtime does
+not migrate an existing Agent's resources. Follow the existing stop/drain and
+recreate procedure when replacing running processes.
+
+The ZIP contains complete changed files, strict-base application and expected-tree
+verification, a review patch, test evidence and recovery instructions. Run
+--check, --apply and --verify in a new worktree, then --verify after commit.
+
+For examples verification, unset BUNDLE_GEMFILE before entering the examples
+checkout and set PHRONOMY_PATH to this core. Inspect and restore only generated
+lockfile/vendor changes; no examples commit is needed.

data/docs/migrations/r8-unit12.md

@@ -0,0 +1,31 @@
+# Migrating to r8 unit 12
+
+Apply after core 891ddf62da42e5218fd8f80d5a9ec0ac6b58b81d (unit 11).
+This package changes core only. The unit 6 examples at
+ed455c52018338f7c5a4c2948ae0d7db131aa090 require no source changes.
+
+Continue to use Orchestrator.subagent and Tools::Agent.from_agent as before.
+No application API or database migration is required. Orchestrator still
+inherits Agent::Base. Its generated Tool is now a direct Tool::Base subclass.
+
+| Internal assumption | Current structure |
+| --- | --- |
+| A generated subagent Tool is a Tools::Agent subclass | It implements Tool::Base directly and belongs to MultiAgent |
+| Tools::Agent owns generic asynchronous Tool validation and error handling | Tool::Base supplies private asynchronous operation rules |
+| Generic Tool handling knows Agent recovery errors | Agent-aware callers preserve those outcomes |
+
+Code that inspects generated-class ancestry or changes Tools::Agent globally
+to affect Orchestrator-generated Tools relied on the old implementation link.
+Such changes no longer apply to generated subagent operations. Existing Tool
+DSL options on the generated operation retain their semantics. The new private
+helper is not a public asynchronous implementation API.
+
+The ZIP includes complete changed files, strict-base application and
+expected-tree verification, a review patch, verification evidence and application
+instructions. Use a new worktree and run --check, --apply and --verify; run
+--verify again after committing. Follow the existing stop/drain procedure when
+replacing running processes. No new cross-version in-flight guarantee is made.
+
+For examples verification, unset BUNDLE_GEMFILE and set PHRONOMY_PATH to this
+core. Inspect and restore generated lockfile/vendor changes; no examples commit
+is needed. Live PostgreSQL and provider verification remain environment-specific.

data/docs/migrations/r8-unit13.md

@@ -0,0 +1,36 @@
+# Migrating to r8 unit 13
+
+Apply after core 87685e3544901a3b2b2d6e9841a723f8ce05c6f6 (unit 12).
+This package changes core only. Unit 6 examples at
+ed455c52018338f7c5a4c2948ae0d7db131aa090 require no source changes.
+
+Workflow.define, invoke, invoke_async, signal, stream and resume retain their
+call signatures and persistence format. No database migration is required.
+Compiled Workflows now retain the execution environment selected at compilation.
+When replacing/resetting the Runtime in a process, drain/stop existing work and
+compile new Workflow objects for the new Runtime. A Workflow whose owner has
+stopped rejects work; it does not implicitly adopt the replacement Runtime.
+
+| Internal assumption | Current structure |
+| --- | --- |
+| Runner looks up the global Runtime during each execution step | It retains a private WorkflowExecutionEnvironment |
+| Workflow registry constructs an Engine Event | It supplies an atomic target resolver to the C13 receiver channel |
+| Phase compiler owns callback rules | WorkflowActionRules owns the rules; the binding installs callbacks |
+| Workflow terminal policy belongs to domain execution files | It translates domain outcomes in workflow/runtime_binding |
+
+WorkflowPhaseMachineBuilder and WorkflowTerminalPolicy retain their constant
+names but move from workflow/execution to workflow/runtime_binding. They remain
+private; direct internal require paths or private Runner helpers must be updated.
+No application implementation of the environment port is required or supported
+as a new public API. Admission, repository operations and result classification
+remain Workflow-owned.
+
+The ZIP contains complete changed files, strict base checks, deletion handling,
+expected-tree verification, a review patch and validation evidence. Apply in a
+new worktree; run --check, --apply and --verify, then --verify after committing.
+For examples, unset BUNDLE_GEMFILE and set PHRONOMY_PATH to the new core. Inspect
+and restore generated lockfile/vendor changes. No examples commit is needed.
+
+This change does not introduce durable child execution, cross-version in-flight
+compatibility or external-side-effect rollback. Keep the existing stop/drain and
+recovery procedures when replacing running processes.

data/docs/migrations/r8-unit14.md

@@ -0,0 +1,31 @@
+# r8 unit 14 migration
+
+Apply to unit13 core commit `cf659de00b9adc2641e1c68014d756e761ccc8e1` using
+the package applier in a clean checkout. Only core changes; examples source
+remains at unit6 commit `ed455c52018338f7c5a4c2948ae0d7db131aa090`.
+
+Public Agent resolution and Workflow APIs are unchanged. There is no data
+migration, persistence format change or new application configuration.
+
+Private consumers must replace the removed `Phronomy::Recovery` namespace:
+
+| Former member | New private owner |
+| --- | --- |
+| Classification, dispositions, resolution outcomes, missing-material sentinel | `Phronomy::Agent::RecoveryRules` |
+| Subject normalization/identity and resolution material validation | `Phronomy::Agent::RecoveryRules` |
+| Revision and snapshot comparison, value normalization and record access | `Phronomy::Persistence::SnapshotComparison` |
+
+The existing public `Phronomy::ExecutionRehydrationRequiredError` keeps its name
+and superclass; its file moves to `agent/api/execution_rehydration_required_error.rb`.
+
+The old internal file `lib/phronomy/recovery/recovery.rb` is removed.
+Ordinary `require "phronomy"` loads both replacements. Direct loading of
+internal files remains unsupported; do not treat these private modules as new
+application extension APIs. Existing `Persistence::SaveOutcome` is unchanged.
+
+Use the same process stop/drain and deployment procedure as unit13. This unit
+adds no in-flight version interoperability or external side-effect rollback
+guarantee. Retain the unit13 checkout for rollback; revert the applied commit
+if necessary. Package README contains apply, validation and commit instructions.
+
+Workflow durable children (F01) are deferred and are not included in this unit.

data/docs/migrations/r8-unit15.md

@@ -0,0 +1,31 @@
+# r8 unit15 migration
+
+## Application impact
+
+No public API, data migration or configuration changes are required.
+GeneratorVerifier continues to accept draft/review Agent classes and optional
+result parser callables, with the same JSON parser defaults and fallback values.
+Each supplied Agent is created once and reused, retaining its conversation.
+
+Custom Agent classes should implement the public Agent protocol: constructor
+`on_event:`, `invoke_async` returning TaskResult, and approval notifications through
+the constructor-bound listener. Terminal results are observed on the returned
+TaskResult. A test double that emits `:done` but leaves its TaskResult pending is
+not a complete implementation of that protocol and must settle its result.
+
+The private `__invoke_async_with_event_sink` method is removed. It was not a
+supported application API. Do not substitute `invoke_async(..., on_event:)`;
+per-invocation listener arguments remain rejected. Register the listener at Agent
+construction and observe each call's result near the call site.
+
+`GeneratorVerifier::DefaultParser` and the private AgentOperation are framework
+composition details. Applications continue to use `draft_result_parser:` and
+`review_result_parser:` for custom parsing.
+
+## Operational scope
+
+The package applies only to core on top of unit14. Existing unit6 examples need
+verification against the new core but no source migration. Restart using the
+existing stop/drain procedure. Rollback is a revert of the unit15 commit; it does
+not require rewriting stored data. In-flight cross-version behavior is not a new
+guarantee of this refactor.

data/docs/migrations/r8-unit16.md

@@ -0,0 +1,26 @@
+# r8 unit16 migration
+
+No application API or persisted-data migration is required.
+
+This core-only update moves explicit-cancellation registration lifetime into the
+existing internal `Phronomy::Concurrency::ResultSubscriptions` operation. Team
+and OffloadPool use `explicit_cancellation` and `close`, rather than removing
+CancellationToken callbacks through reflection.
+
+`CancellationToken#on_cancel` remains public and returns `self`. Its private
+callback-removal method remains private. The new internal operation is not an
+application configuration option or a public subscription API.
+
+Existing cancellation and deadline behavior is preserved. Deadline expiry alone
+does not become a new Team cancellation notification. OffloadPool's existing
+deadline promotion and non-interrupting worker completion behavior remain.
+An already-dispatched cancellation callback can still run after subscription
+cleanup; this refactor does not add a stronger delivery guarantee.
+
+Tool cooperative execution and custom `call_async` implementations are unchanged.
+The standard offloaded Tool route benefits from the OffloadPool update without
+requiring Tool-specific registration code. Examples sources are unchanged.
+
+Apply from unit15 commit `9aebef9217383cebb7fa3ec8b2d17b5763cd3c5e` in a new
+`refactor/r8-unit16` worktree using the package's checked applier. Follow the
+existing process shutdown/drain procedure when replacing running code.