phronomy 0.27.0 → 0.29.0

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.

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.