phronomy 0.27.0 → 0.28.0

data/docs/migrations/r8-unit17.md

@@ -0,0 +1,28 @@
+# r8 unit17 migration
+
+This core-only update requires no application or stored-data migration.
+Continue using Phronomy.configure and the existing per-instance/per-invocation
+options. Public names, defaults, policy validation, nil semantics, and explicit
+option priority remain unchanged.
+
+Agent and Workflow read their own option values instead of application
+Configuration. MultiAgent uses its optional configured Store provider. Logging
+uses RuntimeSettings. Authorization pool sizing moves into the execution
+connection while Agent retains approval and timeout decisions.
+
+There is no settings-change notification or automatic in-flight update. Existing
+read timing is preserved, including scoped configuration restoration and reset.
+Do not capture an internal settings object as a permanent replacement for the
+current accessor, or depend on Configuration's private instance variables.
+
+Private Agent ExecutionEnvironment implementations used by internal integrations
+or tests must implement submit_authorization(timeout:, cancellation_token:, &block).
+The default Engine connection submits the same authorization work with the same
+pool name, resource defaults, overload behavior, and owning Runtime. Ordinary
+Tool implementations and application code require no changes. Tests should set
+configuration through its writers rather than intercepting an old facade getter.
+
+Apply from unit16 commit `fb551e1a1a8334b2547ecad126dd9c152c1b0f8c` in a new
+`refactor/r8-unit17` worktree using the package's checked applier. Follow the
+existing shutdown/drain procedure when replacing running code. Examples remain
+on their unit6 sources and are verified against this core through PHRONOMY_PATH.

data/docs/migrations/r8-unit18.md

@@ -0,0 +1,29 @@
+# R8 unit18 migration
+
+Apply to core at unit17 commit `26792401144118f03025952aa9ec849fb16b577f`.
+No examples source changes, public API updates, schema migrations or data rewrites
+are required. Existing cancellation records remain valid.
+
+Exact-execution resume with a cancelled token now records the request in the
+existing Agent ledger before continuing recovery/waiting. A recording failure is
+returned to the caller. Unresolved children continue to require factual resolution
+and the parent remains active; cancellation receipt does not claim completion.
+
+Cancellation metadata on the execution and MultiAgent extension is a snapshot of
+its last save. If cancellation is recorded after that save, the independent Agent
+ledger preserves intent until the next recovery/change reflects it. Use the
+existing Agent cancellation observation instead of assuming every stored
+snapshot is immediately updated.
+
+Keep the existing stop/drain procedure when replacing running processes. This
+package does not establish new compatibility guarantees for workers already
+running code from another version. Reverting this source change needs no data
+rollback, but reintroduces the cancellation-loss race.
+
+## Delivery correction package
+
+The unit18 cancellation-delivery correction applies on top of
+`a89f42e3805fb548bf9587c49e1ab226efd174db`. It removes the gap between the
+recording and notification decisions in `ExactExecution` delivery. The existing
+preparation/delivery recheck, cancellation ledger and error behavior remain.
+There are no additional API, schema or examples changes.

data/docs/migrations/r8-unit19.md

@@ -0,0 +1,28 @@
+# R8 unit19 migration
+
+Apply to core at unit18 delivery-correction commit
+`a6f370d34e90ca274ec45a6b69ad1db9cb003707`.
+No examples source change, data migration or public invocation API change is
+required. Engine-private shutdown operations and their RBS declarations change.
+
+Runtime shutdown now reports incomplete cleanup when workers remain alive. Check
+cleanup_complete? before declaring resources released. reset_runtime! continues
+to reject replacement after incomplete cleanup. Do not bypass that guard or
+assume a cancelled TaskResult means its synchronous worker has stopped.
+
+The existing Runtime stop-phase deadline, computed from cancel_grace with its
+existing minimum grace, now also bounds pool joins. It is shared across EventLoop
+and all pools; the previous additional 30 seconds per worker no longer applies
+to Runtime shutdown. timeout still controls the preceding drain phase. Choose
+grace appropriate to existing work, and configure native I/O timeouts where
+needed. No Thread#raise or hard worker termination is added.
+
+Shutdown remains terminal and returns its cached result on subsequent calls,
+including an incomplete result. This change does not add retry or resume of the
+shutdown procedure. Pool requests racing past the closed resource registry are
+rejected with PoolShutdownError; new calls rejected earlier by Runtime retain
+RuntimeShutdownError.
+
+Use the existing controlled process-replacement procedure. Reverting the source
+change needs no data rollback, but restores the resource leak and false-completion
+risks. Metrics.snapshot behavior is unchanged in this unit (E03 is deferred).

data/docs/migrations/r8-unit20.md

@@ -0,0 +1,24 @@
+# R8 unit20 migration
+
+Apply to unit19 core commit `07b78c90ef6072f66fecb04ea6891eda50493546`.
+No examples source change or data migration is required.
+
+Metrics.snapshot, Diagnostics.snapshot and Diagnostics.dump keep their arguments,
+metric keys, numeric values and output format. They no longer initialize execution
+resources and remain usable while the default Runtime is stopping or stopped.
+
+Before resource initialization, the corresponding values are zero. In particular,
+offload_pool_size is zero until the default pool exists. Previously a snapshot
+created the pool and reported its configured capacity. Do not use monitoring as
+an implicit warmup. Normal execution still initializes the resources it needs.
+
+For an existing pool, offload_pool_size remains its configured capacity after
+shutdown; use the shutdown result to assess cleanup, not this metric. Retained
+counters remain readable until default Runtime reset. After reset, observations
+return zero until new resources are initialized. Named pools are not aggregated,
+and simultaneous consistency across independently sampled counters is not added.
+
+Unit19 stopping deadlines, completion judgment and cached-result behavior remain
+unchanged. No public invocation API or persistence format changes. Reverting this
+unit needs no data rollback but restores observation-triggered initialization and
+shutdown-time diagnostic errors.

data/docs/migrations/r8-unit21.md

@@ -0,0 +1,28 @@
+# r8 unit21 migration
+
+This core-only responsibility refactor requires no application or stored-data
+migration. Continue using Phronomy.configure with tool_result_max_size, tracer
+and trace_pii, and the existing per-Tool max_result_size option. Public defaults,
+nil semantics, read timing, truncation and redaction behavior remain unchanged.
+Application-configured filter order and repetition remain unchanged too.
+
+Tool and Tracing now obtain their settings through their own internal value
+containers. Context::Assembly obtains its default tracer from Tracing while
+retaining explicit injection and constructor-time selection. Composition still
+selects concrete defaults and supplies current values; no manual per-operation
+injection or settings-change subscription is required.
+
+Internal tests or unsupported integrations constructing RuntimeSettings must
+stop passing tracer: to its constructor or reading tracer, trace_pii and
+tool_result_max_size from it. Ordinary application code should use the unchanged
+public Configuration accessors. Its private instance variables and the new
+domain settings containers are not an application extension API.
+
+Apply from unit20 commit `bda5da03da5a4da33041953cf0eebaa32de7bb81` in a new
+`refactor/r8-unit21` worktree using the package's checked applier. Verify the
+expected tree before and after committing. Follow the existing shutdown/drain
+procedure when replacing running code. Examples remain on their unit6 sources
+and are verified against this core through PHRONOMY_PATH.
+
+No data rollback is needed. Reverting this commit restores the earlier settings
+ownership; it does not remove the unit19/20 Engine corrections.

data/docs/migrations/r8-unit22.md

@@ -0,0 +1,29 @@
+# r8 unit22 migration
+
+No application source or stored-data migration is required. Apply this core-only
+package on unit21 commit `4525e71ca808acac9eb0302a59c32f00478a7782` and restart
+using the application's existing drain/shutdown procedure.
+
+- MCP public construction, execution, close, schema, authorization and result
+  formatting APIs are unchanged.
+- A completed MCP call no longer retains a cancellation callback on a shared
+  caller token. A callback already taken by concurrent cancel! may still finish.
+- Logical timeout does not end the SDK invocation's cancellation bridge. The
+  registration is released when that invocation exits.
+- If Runtime rejects transport cleanup because it has stopped, the MCP caller
+  performs the existing synchronous close fallback and still receives the MCP
+  cancellation outcome. This can include the transport's normal close latency.
+- Warning logging uses the same configured logger through neutral settings,
+  with stderr fallback when no logger is configured.
+
+Execution, Engine and Contract source are unchanged. There are no new threads,
+configuration options, timers or notification services. The existing MCP
+cleanup pool remains in use while Runtime accepts work.
+
+Custom tests that expected cancellation to reach an already-completed MCP call
+should instead cancel while the SDK call is active and verify that completed
+calls release their registrations. The SDK cancellation bridge helper is
+private; its new subscriptions keyword is not a public application API.
+
+Examples retain their unit6 source. Verify them against this core checkout using
+PHRONOMY_PATH and restore only verification-generated lockfiles/artifacts.

data/docs/migrations/r8-unit23.md

@@ -0,0 +1,20 @@
+# r8 unit23 migration
+
+This is a core-only responsibility refactor on applied unit22.
+
+- `Tools::Agent.from_agent`, synchronous `execute`, asynchronous `call_async`
+  and the public `Agent.run_once` API retain their signatures and behavior.
+- Agent Tool calls still create a fresh Agent and ephemeral store. Configured
+  application stores do not replace this per-call store.
+- `Testing::Eval::Scorer::LlmJudge` retains its constructor and scoring API.
+  Configure `llm_adapter` through the existing application configuration API.
+- LlmJudge reads the default adapter for each score, after preparing its Request.
+  Existing scoped configuration and reset behavior are retained.
+- The client factory is an internal boot binding. Applications do not need to
+  register it or adopt a new factory API.
+- No Contract, Execution, Engine, RBS, data schema or stored-record migration is
+  required. Examples require verification only, with no source changes.
+
+Use the package README to check the exact base commit, apply complete files,
+verify the resulting tree, run the validation commands and commit the result.
+Normal application loading remains `require "phronomy"`.

data/docs/migrations/r8-unit4.md

@@ -0,0 +1,67 @@
+# r8 unit 4 migration
+
+Update core and examples together. This is a refactoring-branch breaking change;
+there are no compatibility aliases or automatic old-record loaders.
+
+| Unit 3 | Unit 4 |
+|---|---|
+| `Agent::Handoff`, `Agent::HandoffPolicy` | `MultiAgent::Handoff`, `MultiAgent::HandoffPolicy` |
+| `stores.team`, `config.team_store` | `stores.multi_agent`, `config.multi_agent_store` |
+| HandoffRunner infers an Agent store | `HandoffRunner.new(main_agent:, handoffs:, persistence: stores.multi_agent)` |
+| Orchestrator receives only Agent persistence | `Orchestrator.create(persistence: stores.agent, coordination_store: stores.multi_agent)`; pass both on `load` |
+| Internal ExactExecution/metadata access by coordination | Agent reserved start, resume, cancellation and observation operations |
+| AgentExecution / HandoffState envelope `0.1` | Envelope `0.2`; explicit offline conversion required |
+| `coordination`, `multi_agent_coordination_ref`, Handoff result fields | immutable `reservation`, versioned `execution_extension`, `transfer_receipt` |
+
+Construct one `PersistenceComposition.build(backend:)` and use its domain stores.
+Ordinary Agents continue to use `persistence: stores.agent`. For custom
+participants, follow `ExecutionChange`'s RBS contract and the
+[transaction sequence](../architecture/r8-unit4.md). Do not serialize participant
+objects, callbacks or live Agent references.
+
+## Offline SQL conversion
+
+Stop all writers before exporting, including background workers and other
+processes. Keep the old database unchanged. Run commands from example 30 (SQLite)
+or 31 (PostgreSQL), with `PHRONOMY_PATH` pointing to the unit 4 core. The source DB
+must have the unit 3 schema. The destination must be a separate empty database.
+
+```sh
+export SOURCE_DATABASE_URL='sqlite3:/absolute/path/old.sqlite3'
+export DESTINATION_DATABASE_URL='sqlite3:/absolute/path/new.sqlite3'
+bundle exec ruby ../scripts/migrate_unit4.rb export source.json --quiescent
+bundle exec ruby ../scripts/migrate_unit4.rb convert source.json converted.json --quiescent
+bundle exec ruby ../scripts/migrate_unit4.rb import converted.json --quiescent
+bundle exec ruby ../scripts/migrate_unit4.rb verify converted.json --quiescent
+```
+
+Use the corresponding PostgreSQL URLs with example 31. The importer creates the
+new destination schema, including retention/cancellation tables, refuses populated
+tables, and commits all resources together. It preserves record IDs, physical and
+logical revisions, stream positions, result/error content, transfer provenance,
+knowledge order and unresolved work. A content digest, reference, owner, revision
+or format mismatch aborts conversion. A checksum binds the converted resource set
+to its validation. Do not edit converted JSON manually.
+
+Verification establishes a separate connection pool and compares the complete
+exported destination with the converted snapshot. Before switching application
+configuration, load representative Agents with their current definitions and
+participant wiring, read completed results and resume only continuations whose
+external outcomes are known. Unknown external operations remain unresolved; the
+migration neither retries them nor declares them complete. Keep both exports and
+the old DB until that operational validation is complete. Database cutover is
+explicit and is never performed by the migration command.
+
+For non-SQL backends, `Unit4Migration.convert(snapshot, quiescent: true)` is the
+pure conversion boundary. Implement offline export/import of the documented
+`phronomy.snapshot/1` resources using the backend's own driver. No live-code
+fallback is supplied.
+
+## Retention lifecycle
+
+After all results in a conversation have been consumed, call
+`runner.forget_history!` (or `stores.multi_agent.forget_handoff(main_id)`) before
+purging retained participants. For completed durable subagent history use
+`stores.multi_agent.forget_subagents(agent_id:, execution_id:)`. Active or
+unresolved work rejects history deletion. These operations release their own
+holds; they do not remove another conversation's references.

data/docs/migrations/r8-unit5.md

@@ -0,0 +1,75 @@
+# r8 unit 5 API migration
+
+Apply core and examples together. No saved Agent, MultiAgent or Workflow record
+format changes in this unit. Old constants and forwarding aliases are removed.
+
+| Previous API | Current API |
+| --- | --- |
+| `Phronomy::VectorStore::Embeddings::*` | `Phronomy::Embeddings::*` |
+| `Phronomy::VectorStore::Loader::*` | `Phronomy::Documents::Loader::*` |
+| `Phronomy::VectorStore::Splitter::*` | `Phronomy::Documents::Splitter::*` |
+
+VectorStore callers continue using `add`, `search`, `remove`, `clear` and `size`.
+Custom backends now override protected `perform_add`, `perform_search`,
+`perform_remove`, `perform_clear`, `perform_size`, and optionally
+`embedding_dimension`. The common Base performs input/result validation and
+returns `self` for add/remove/clear; the return value from these three hooks is
+ignored. See `sig/phronomy/vector_store/base.rbs` for exact arguments. RBS models
+the non-public hooks as private because it cannot express Ruby protected visibility.
+
+Custom embedding providers implement the protected hook, not the public template:
+
+```ruby
+class KeywordEmbeddings < Phronomy::Embeddings::Base
+  protected
+
+  def perform_embed(text, cancellation_token = nil)
+    # Common input/result validation and the initial cancellation checkpoint
+    # are inherited. Long-running implementations may check the signal again.
+    [text.scan(/refund/i).length.to_f, text.scan(/shipping/i).length.to_f]
+  end
+end
+
+provider = KeywordEmbeddings.new
+vector = provider.embed("refund")
+task = Phronomy::Embeddings::AsyncClient.new(adapter: provider).embed_async("shipping")
+result = task.wait_result
+```
+
+Embedding input must be a String, including an optional empty string; output must
+be a non-empty Array of finite real numbers. Provider output is copied to a Float
+array. An empty or malformed vector raises `Embeddings::InvalidResultError`.
+RubyLLM provider failures now raise `Embeddings::TransportError`; inspect `cause`
+for provider-specific details. Application exceptions are unchanged.
+
+Vector ids must be Strings and metadata must be a Hash. Numeric strings, NaN,
+infinity and complex components are rejected before backend I/O. Zero-dimensional
+vectors still work in InMemory. `k` accepts positive Integers or decimal strings,
+including `"08"`; Float truncation, hexadecimal/octal interpretation, whitespace
+and arbitrary `to_int` coercions are not part of the contract. Results must satisfy
+the public shape, score ordering and limit. Invalid backend results raise
+`VectorStore::InvalidResultError`; they are never retried automatically.
+
+Update custom backend tests to exercise inherited public operations. Do not
+silence malformed results, return a fake zero count on transport failure, or add
+an old-name alias to bypass the migration. Real Pgvector and RedisSearch deployments
+must run their actual-service conformance tests before rollout.
+
+The revised unit 5 candidate also tightens concrete backend response decoding.
+RedisSearch expects RESP2; a missing whole search reply, malformed field pairs,
+invalid counts or non-numeric distances now fail with `InvalidResultError` rather
+than becoming an empty result, zero count or similarity 1. Document contents that
+Redis explicitly reports as null during expiration/update are still omitted.
+The total match count may exceed the returned page; these valid cases are tested.
+RESP3 is not introduced by this update.
+
+For Pgvector, a NULL metadata column remains `{}`, while an empty string, invalid
+JSON, or JSON that is not an object now fails. An already-decoded Hash and a JSON
+object remain accepted. Redis missing/null metadata likewise remains `{}`.
+Pgvector rejects malformed scores and ids; integer database ids are still mapped
+to String. JSON parser errors are retained as `cause`. Connection errors remain
+unchanged and are not retried.
+
+Check pre-existing metadata for invalid JSON or non-object values before rollout;
+do not silently replace corrupt values with `{}` to make verification pass.
+These parsing rules are implemented by the respective backend, not by Base.

data/docs/migrations/r8-unit6.md

@@ -0,0 +1,109 @@
+# r8 unit 6 migration
+
+Apply core and examples together on the applied unit 5 baseline. There are no
+compatibility aliases. Update custom adapters and code rescuing LLM failures.
+
+| Previous API | Current API |
+| --- | --- |
+| `Phronomy::TokenUsage` | `Phronomy::LLMAdapter::TokenUsage` |
+| `Phronomy::TransportError` | `Phronomy::LLMAdapter::TransportError` |
+| `Phronomy::RateLimitError` | `Phronomy::LLMAdapter::RateLimitError` |
+| `Phronomy::AuthenticationError` | `Phronomy::LLMAdapter::AuthenticationError` |
+| `Phronomy::ContextLengthError` | `Phronomy::LLMAdapter::ContextLengthError` |
+| Adapter `build_chat`, `configure_chat`, `message`, `tool_call` | Backend-owned private translation; removed from the extension SPI |
+| Adapter `complete(chat, message, config:)` / `stream(...)` | Inherited `complete(request, cancellation_token:)` / `stream(...)` |
+| SDK-shaped recovery provider result | `LLMAdapter::Response` or `Response#to_h` |
+
+Implement protected hooks, leaving public validation/cancellation templates intact:
+
+```ruby
+class EchoBackend < Phronomy::LLMAdapter::Base
+  protected
+
+  def perform_complete(request, cancellation_token:)
+    Phronomy::LLMAdapter::Response.new(content: request.message || "continued")
+  end
+
+  def perform_stream(request, cancellation_token:)
+    result = perform_complete(request, cancellation_token: cancellation_token)
+    yield Phronomy::LLMAdapter::StreamChunk.new(content: result.content)
+    result
+  end
+end
+Phronomy.configure { |config| config.llm_adapter = EchoBackend.new }
+```
+
+Request contains JSON model_config, optional system/new message, immutable
+Message history and inert Tool definition Hashes. `identity` and local
+`input_budget` have defaults. Backend hooks return Response; stream yields
+StreamChunk values. Tool requests are `Tool::CallRequest(id:, name:, arguments:,
+metadata:)` values in an ordered array, with unique nonempty IDs. They never
+contain executable Tools or approval decisions. Return assistant responses only.
+Response/Message content is text, structured JSON or nil. Unknown token counts
+are nil; explicit zero is zero. TokenUsage no longer provides SDK `from_tokens`.
+
+Model/provider are nonempty Strings or nil, temperature a finite number or nil,
+max_output_tokens a positive Integer or nil, and instruction-cache/model-existence
+flags booleans or nil. The default RubyLLM backend still owns provider-specific
+options and error translation. Existing provider/application errors are not
+silently swallowed or converted into success. Custom synchronous hooks must
+check cancellation during their own long operations where they can cooperate.
+
+## Tool schemas and approval
+
+Tool::Base owns `parameter`/`param`, `parameters`/`params`, declaration inheritance,
+name/description, provider options, `validate_arguments`, `call`, and `call_async`.
+It is not a RubyLLM::Tool. Incidental inherited SDK APIs such as approval_resolver,
+split_result and SDK result/content classes are not part of the new Tool API.
+Keep Agent approval policies on the Agent/Tool authorization contract.
+
+`parameters` accepts an explicit object schema or Schematist DSL (the DSL retains
+its syntax without loading RubyLLM). JSON Schema 2020-12 is the supported dialect,
+implicit when `$schema` is absent. Root type must be object. Supported constraints
+include required/extra properties, nested objects/arrays, enum/const, numbers,
+strings/formats and combinators. Unknown keywords/formats, alternate dialects,
+custom vocabularies, `$id`/anchors and external refs fail at declaration time.
+Local `#` / `#/...` references are resolved at construction. `strict` is a provider
+annotation, not a substitute for required/additionalProperties constraints.
+Defaults are annotations and are not injected into arguments.
+
+Legacy optional `param` declarations continue to accept explicit nil and now
+advertise a nullable type (and nullable enum). A legacy optional nil is normalized
+to omission before approval/execution, preserving Ruby keyword defaults. An
+absent optional key is not injected. Explicit schemas accept null only when their own constraints allow it.
+
+Every declaration path validates before execution. `:raise` raises ToolError;
+`:return_error` returns the existing schema-error text; `:coerce` converts explicit
+primitive property/item types and then validates every constraint. It does not
+guess a branch or cast through references/combinators. Fractional values are not
+truncated to integers. Validation snapshots input containers; it does not mutate
+the caller's arguments. Top-level keys become keyword symbols. Extra keys with
+no declared/inferred parameters are rejected rather than passed to execute.
+
+Approval receives the validated/coerced snapshot. Execution reuses those values
+and validates against the same published schema. `on_error` does not turn schema
+errors into successful execution. Unqualified legacy array declarations now
+advertise unconstrained JSON items, matching their actual validation rule; use
+an explicit items schema to restrict them.
+
+## Stored and in-flight executions
+
+Storage SPI and SQL schemas are unchanged. New Tool batch metadata additionally
+records `validated_arguments`, separately from the unchanged raw request fields.
+Agent authorization projects and compares that exact snapshot (including explicit
+null in explicit schemas). Older snapshots without this field use the historical
+raw-argument/optional-nil-omission rule. Existing journal message boundaries,
+Tool call identities and recorded usage remain readable. Legacy top-level
+thought_signature is decoded into opaque CallRequest metadata and rendered by
+the backend. Old SDK usage field spellings remain accepted by SavedContextReader.
+No stored records are silently rewritten and no automatic migration is run.
+
+Saved Tool definitions are compared exactly. Removing SDK-generated annotations,
+correctly advertising nested required/extra-key rules or array item rules can
+change the definition even when application source is unchanged. Finish or
+explicitly resolve in-flight unit 5 executions on their original version before
+upgrading. Quiescent Agent history remains readable. If a saved in-flight Tool
+definition differs, recovery rejects it; do not remove that comparison or modify
+historical manifests to force continuation. Saved invalid model configuration
+also needs resolution on the original version. No new cross-version in-flight
+compatibility guarantee is made.

data/docs/migrations/r8-unit7.md

@@ -0,0 +1,31 @@
+# Migrating to r8 unit 7
+
+Apply after core b337fc77dae530269bc34d895365032873d544ad (r8 unit 6).
+Public Agent invocation, streaming, approval, cancellation and recovery signatures
+and persistence record schemas are unchanged. The current unit 6 examples need
+no source changes. Run them against the candidate using PHRONOMY_PATH and the
+correct BUNDLE_GEMFILE for each example directory.
+
+There are no compatibility aliases for removed internal APIs:
+
+| Internal use | Replacement |
+| --- | --- |
+| AgentInvocationSessionBuilder | AgentInvocation plus the owning ExecutionEnvironment.build_agent_session |
+| AgentInvocationSessionBuilder entry/prepared actions | InvocationActions |
+| ExecutionSessionRunner.new(runtime: ...) | ExecutionSessionRunner.new(environment: ...) |
+| OwnershipRegistry.for/existing_for(Runtime) | Pass an ExecutionEnvironment; EngineEnvironment adapts Runtime |
+| ExecutionReceiver subclasses initialize(event_loop:) | initialize(channel:), preserving super |
+| AgentInvocation.begin_llm_call! implicit Runtime lookup | Explicit llm_call_id from durable prepared execution |
+
+ExecutionEnvironment is a private framework connection, not an application
+configuration feature. Do not serialize environments, channels, sessions or live
+registries. The default composition is installed by requiring phronomy. State
+policy loading alone does not install a runtime. Existing persisted Agent/Tool
+identities, revisions, authorization snapshots and recovery classifications are
+retained. This change does not add support for exchanging in-flight unit 5 or
+older execution snapshots with unit 6/7 workers.
+
+Stop/drain old processes using the existing deployment procedure before replacing
+code. Deploy all internal call-site changes together. The application package
+contains a strict-base dry-run/applier, expected-tree verification, review patch,
+validation logs and rollback guidance. Run --verify before and after commit.

data/docs/migrations/r8-unit8.md

@@ -0,0 +1,33 @@
+# Migrating to r8 unit 8
+
+Apply after core a601a0654ace42640f0251b129359ca1f326e3ad (unit 7).
+This is a core-only change. The unit 6 examples at
+ed455c52018338f7c5a4c2948ae0d7db131aa090 require no source changes.
+
+Public Agent invocation/stream/approval/cancellation/recovery signatures and
+Tool#call_async(args, cancellation_token:, config:) are unchanged. Tool::Operation
+adds an explicit C06 operation entry and result transformation API; application
+Tools do not need to adopt it. The supplied submitter applies to the default
+offloaded operation only. Custom async implementations retain their existing
+execution mechanism and configuration.
+
+| Internal use | Replacement |
+| --- | --- |
+| Agent::ToolInvocationSessionBuilder.build / build_for_resume | The owning ExecutionEnvironment.build_tool_session, with resume_event/resume_phase when needed |
+| ToolInvocationSessionBuilder transition constants | Agent::ToolInvocationTransitions |
+| ToolInvocationSessionBuilder entry operations | Agent::ToolInvocationActions |
+| ToolInvocation.start_authorization/runtime: and start_execution/runtime: | Pass environment: explicitly; never reconstruct it from a new global Runtime |
+| Tool::ToolExecutor.call_async(runtime:) | Tool::Operation.call_async(submitter:) for contract consumers; default executor takes submitter: internally |
+| Agent ToolBinding's custom-async detection and mapping mechanism | Tool::Operation.with_result_transform; Agent retains filter configuration |
+
+Removed internal names have no aliases. Deploy all internal call sites together.
+Do not persist execution environments, submitters, FSM sessions or parent sinks.
+Durable IDs, record schemas, revision checks and saved approval evidence are
+unchanged. The change does not certify new in-flight cross-version compatibility.
+Use the existing stop/drain procedure before replacing running processes.
+
+The application ZIP contains strict-base --check/--apply/--verify commands,
+complete replacement files and deletions, expected-tree verification, a review
+patch, validation evidence and rollback instructions. Run --verify before and
+after commit. Verify examples with PHRONOMY_PATH pointing at the candidate and
+unset a stale BUNDLE_GEMFILE before entering each Bundler context.

data/docs/migrations/r8-unit9.md

@@ -0,0 +1,28 @@
+# R8 unit 9 migration
+
+Apply to core unit 8, commit e9f6cc16da19be82a0b7777486926ba46d070def.
+Examples source remains at unit 6, ed455c52018338f7c5a4c2948ae0d7db131aa090.
+
+No public Tool or Agent signature, stored schema, migration CLI or example source
+change is required. Existing configured filter order and repeated registrations
+are preserved. The correction removes only the extra transformation caused by
+Base's standard async-to-sync delegation under a custom async result decorator.
+
+A custom call_async using super now passes its raw delegated result through its
+own processing before the async decorator applies the configured transform.
+Code accidentally relying on the duplicate/intermediate transformation should
+express the required stages explicitly in application filter configuration.
+
+A custom call_async explicitly calling public call retains that call's filters;
+the enclosing async result decorator also retains its stage. Do not substitute
+call for super when the intent is to delegate to Base's normal async execution.
+The framework does not suppress application-authored calls or infer their intent.
+
+Private changes: Base uses Tool::Operation.synchronous_delegate; ToolExecutor
+accepts a bound synchronous_call keyword. Applications should not use these
+private bridge helpers. Custom async implementations retain their existing
+execution mechanism and keyword protocol.
+
+Use the normal process stop/drain and restart procedure. This unit does not add
+cross-version in-flight compatibility or rollback of external Tool side effects.
+See docs/architecture/r8-unit9.md for operation-boundary examples.

data/docs/migrations/storage-async-client.md

@@ -0,0 +1,103 @@
+# Storage asynchronous execution and ContentStore ownership
+
+P4 adds the public Beta `Phronomy::Storage::AsyncClient`. Synchronous storage
+backends and `Persistence#transaction` keep their existing interfaces. Backend
+authors implement no scheduler or async methods.
+
+## Public transaction API
+
+Construct `Storage::AsyncClient.new(backend: raw_backend, pool: nil)` around a
+Storage SPI 2 backend. For an existing Persistence facade, use
+`persistence.backend`. The transaction block receives a **raw Storage::View**,
+not the domain repositories yielded by `Persistence#transaction`.
+
+`transaction_async(cancellation_token: nil, timeout: nil) { |view| ... }`
+returns the pool's original TaskResult. The complete transaction runs on one
+worker, using the backend's normal connection and scope. Do not split a
+transaction across workers or wait for another TaskResult inside its block.
+Explicit synchronous `backend.transaction` calls within the block retain nested
+savepoint behavior.
+
+### Complete offline example
+
+This requires a checkout containing P4; the previously released 0.27.0 gem does
+not contain the new client. It uses only the public raw storage contract.
+
+```ruby runnable
+require "phronomy"
+require "json"
+
+resource = Phronomy::Storage::Resource.new(id: "example.notes", kind: :records)
+backend = Phronomy::Storage::Backends::InMemory.new(resources: [resource])
+client = Phronomy::Storage::AsyncClient.new(backend: backend)
+
+begin
+  record = Phronomy::Storage::DurableRecord.new(
+    record_type: "example.note", format_version: "0.1", payload: {"text" => "saved"}
+  )
+  task = client.transaction_async do |view|
+    rows = view.records(resource)
+    rows.insert(key: "note-1", revision: 1, attributes: {}, record: record)
+    rows.fetch("note-1").record.payload
+  end
+  puts JSON.generate(task.wait_result)
+ensure
+  Phronomy.reset_runtime!
+end
+```
+
+The output is `{"text":"saved"}`. Return a value from the transaction. A bound
+view or resource handle becomes invalid after the block finishes, even if it
+was returned through TaskResult. Scope also rejects access from another thread.
+Exceptions and invalid non-local block exits roll back through the existing
+backend rules; no new transaction implementation is introduced.
+
+## Admission, cancellation and ownership
+
+Construction starts no Runtime. Each call resolves the current default pool,
+unless an explicit caller-owned `pool:` was supplied. Runtime reset does not
+transfer ownership of an injected pool.
+
+Admission uses `on_full: :raise`: a full or stopped pool raises immediately.
+Queue wait counts toward `timeout`. Cancellation/timeout before worker pickup
+skips the transaction. After work starts, TaskResult may settle while the
+physical transaction continues and commits. A timeout or cancellation is **not
+a rollback guarantee**. The client does not kill a thread, add retries, or claim
+that an uncertain commit succeeded or failed. Applications needing a durable
+outcome must reconcile through their domain's identities and stored state.
+
+## Existing Agent, Workflow and coordination operations
+
+Internal `Storage::AsyncClient.submit(pool:)` accepts an existing synchronous
+storage unit. This is private framework API, not an application extension API.
+It submits exactly once and adds no transaction, token, or timeout. This lets
+domain operations preserve their own transaction and reconciliation boundaries.
+See the [operation inventory](../architecture/storage-execution-boundaries.md).
+
+In particular, a Workflow runner may have only an injected repository rather
+than access to its raw backend. Internal submit therefore accepts a callable
+and the owner's pool; it does not require a dummy backend or a Persistence
+facade. Public transaction_async requires a real SPI 2 backend.
+
+Durable commit/readback policy, admission release, callback delivery and the
+application of results to live state remain with Agent/Workflow/MultiAgent.
+No cancellation condition is added to existing terminal saves. Tool execution,
+authorization, tracing and application approval listeners retain their own
+execution boundaries.
+
+## ContentStore path and diagram
+
+P4 originally moved `ContentStore::StoredContents` into
+`content_store/backends/stored_contents.rb`. [ADR-062](../decisions/062-content-store-service.md)
+supersedes that split: the implementation now lives at
+`content_store/stored_contents.rb`, beside its shared API and owned schema.
+The obsolete backend directory and collapse entry are deleted without a shim.
+Its constant, synchronous operations, digest rules and exceptions are unchanged.
+Use normal `require "phronomy"`; internal file paths are not a public load API.
+Zeitwerk still collapses `storage/async/`. `Storage::Backends` remains a namespace.
+ContentStore receives no artificial async API.
+
+M10 is G57 Content Service in B3, outside Backend Contracts/Implementations;
+M73 is retired. M69 Storage AsyncClient stays in B4. Text panels are transparent.
+Arrows targeting M33/M41/M44 are hidden by display settings; all measured
+dependencies, source evidence and matrix cells remain available.