phronomy 0.32.0 → 0.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8eeef6dddca310da11fcdcaf7ffc2490191151cfa070384be8d04f84366efb08
-  data.tar.gz: 2b43c66ff8c5484360b2a953bcdd4aa754ef99c3b7bc944285993d866ee34007
+  metadata.gz: 4c67e91b9abb65c5ab2ddc5b657afa6843b916a5ba84aefcd8f808ae297c3236
+  data.tar.gz: b5894936fa47d493da81c650edbf3c330eaeec7101c68ec91acf96bec00d1a79
 SHA512:
-  metadata.gz: 9ebee2313bc7d60b27c6e42e0909fbb1102cca3c220f25575d1c755b18f3d1c00b7ea0dfec36646155a7aff325ba47c99af202c9b7fbf226d45c4fbb07b8bff9
-  data.tar.gz: 3b089fdc8447a0a56c66d10d64c809eb26ddc31be6800a55c095409e87e649047afbc42fa1872eab8fd68b7939bd6845edc194b5ec4ab03beca602408f320596
+  metadata.gz: ebec13bc657697922f3f487eefe809a35570b36a574e8a3ea95d5124459035ca263ad39b89419e8042621e4971f550cbb7d21ab206d2961f8a7f01bec6b9514e
+  data.tar.gz: b1d930edb100e7782522a9d666d555756fcc50e5be46881c58c035f2e021631093132b4bde4cec8134f296f068ddb9cb0fd17548ea356afad32652d484b7da91

data/CHANGELOG.md

@@ -12,6 +12,145 @@ Release history for 0.14.0 and earlier is archived in
 
 ## [Unreleased]
 
+## [0.34.0] - 2026-11-16
+
+### Changed
+
+- Route ContextPolicy item estimates directly through the protected
+  `estimate_tokens` extension operation, removing the redundant private wrapper.
+- Exercise Tool approval redaction through the display/snapshot path used by
+  production approval requests instead of internal convenience getters.
+- Replace references to an absent repository language-check script with an
+  external maintainer check and recorded evidence. Correct the Storage phase
+  status: P4 is implemented; the separate final P5 review remains pending.
+
+### Fixed
+
+- Derive default SharedState members through `Agent::Base.with_tools`, retaining
+  Phronomy authoring settings and filters as custom sharing already does. A
+  member's iteration limit, temperature and other configuration no longer reset
+  when built-in sharing Tools are added. Preserve Tool aliases, the generated
+  definition identity and default findings-store behavior.
+
+### Removed
+
+- Remove Handoff's old selection-unit metadata fallback and Agent Store's raw
+  argument fallback. Current conversation groups and exact validated arguments
+  remain the authoritative saved facts; current record writers are unchanged.
+- Retire `Persistence::Migration::InitialFormatMigration` and the old
+  GeneratorVerifier Result JSON conversion command, including their dedicated
+  migration tests and active usage instructions. No replacement converter or
+  compatibility entry point is supplied. Current codecs, Result validation and
+  the separate Unit4 snapshot migration remain. See the
+  [legacy-format cleanup](docs/migrations/legacy-format-removal.md).
+- Remove `Runtime::ShutdownResult#success?`; use the equivalent
+  `cleanup_complete?`. Keep `clean?`, which additionally requires a graceful
+  shutdown.
+- Remove the obsolete `SchedulerReentrancyError` subclass; use
+  `EventLoopReentrancyError`, which is already raised by current execution paths.
+  No compatibility aliases are retained. See the
+  [cleanup migration](docs/migrations/cleanup-audit.md).
+- Remove unused internal Invocation, RecoveryRules and Execution helpers, along
+  with five completed development-only spec migration scripts. Keep the public
+  `JournalProjection#llm_call_records` and
+  `LLMInputManifest#referenced_content_refs` operations and the Scope hooks still
+  used for result composition.
+
+### Compatibility and verification
+
+- Replace `Runtime::ShutdownResult#success?` with `cleanup_complete?` and rescue
+  `EventLoopReentrancyError` instead of the removed `SchedulerReentrancyError`.
+  No compatibility aliases are retained. See the
+  [cleanup migration](docs/migrations/cleanup-audit.md).
+- Historical pre-S3 and GeneratorVerifier Result conversion support is retired
+  without a replacement command. Current record writers and saved representation
+  are unchanged; this release does not rewrite existing stores. Handoff no longer
+  derives groups from old selection-unit metadata, and authorization requires
+  validated argument evidence. Review the
+  [legacy-format migration](docs/migrations/legacy-format-removal.md) before
+  upgrading applications that still consume those historical records.
+- Previously observed LM Studio/gpt-oss PEG-format failures are not resolved by
+  this cleanup. This release does not claim to fix their root cause or prevent
+  recurrence; offline persistence/recovery checks do not establish full real-LLM
+  acceptance.
+
+## [0.33.0] - 2026-11-14
+
+### Added
+
+- Add public `ContextPolicyInput#input_token_limit` and
+  `#with_input_token_limit(limit)` for immutable, non-expanding selection limits,
+  plus protected `ContextPolicy#estimate_tokens(content)` using the same
+  canonical estimator as generated Policy items. Applications can reserve input
+  capacity while retaining DefaultPolicy selection without constructing private
+  budget objects or calling private token-estimation helpers. These operations
+  do not change model capabilities, generation settings or final validation.
+- Add `Agent::Base.with_tools(definitions, id:, version:)` to derive an Agent
+  class with a complete replacement Tool map and explicit definition identity.
+  The factory preserves Phronomy authoring settings and independently copies
+  filter lists; configured callable instances remain shared. Custom SharedState
+  uses this public operation after merging member and application Tools. General
+  Agent subclass inheritance remains unchanged.
+- Add `MultiAgent::SharedState.sharing(provider, id:, version:)` and the public
+  `SharedState::Binding` value. A synchronous provider opens one application-owned
+  store for an invocation and supplies Tool definitions for each member/cycle.
+  Applications define their own records, search arguments and cleanup without
+  overriding SharedState private methods. Custom sharing requires an explicit
+  aggregation block and does not inject the default findings Tools or append
+  stored records to member prompts.
+- Include the sharing provider's stable ID and semantic version in custom
+  generated Agent definition identity. Default SharedState retains its existing
+  built-in Tools, prompts and instrumentation revision 1. The extension adds no
+  database adapter, ContextPolicy implementation or durable sharing lifecycle.
+- Release terminal custom-sharing members through the public Agent lifecycle
+  operation. Normal Agent approval waits keep the invocation and provider open.
+  `SharedState::MemberLifecycleError` reports failed release or a custom
+  `invoke` override returning a suspended result prematurely, with the Agent and
+  available result/error details. It does not automatically answer approvals or
+  release a pending execution; application providers retain responsibility for
+  resource cleanup and recovery policy.
+
+### Changed
+
+- Reuse the immutable argument schema prepared by an explicit `parameters`
+  declaration. Each Tool instance compiles its own validator on first use.
+
+### Fixed
+
+- Build each human-facing Tool approval item from the Tool's public
+  `approval_display(arguments:, facts:)` result. A Tool without this operation
+  contributes empty argument and fact maps to new approval requests. Tool
+  execution and policy evaluation still receive their original inputs.
+- Apply the default approval display's sensitive-value check to values inside
+  a Tool's redacted hash or array arguments, including copies used as fact keys.
+
+### Security
+
+- Use patched ActiveRecord 8.0 development dependencies, including ActiveSupport
+  8.0.5.2 or later in the 8.0 series. Remove unused ActiveJob and SQLite3
+  development dependencies; the examples retain the dependencies they use.
+  The published gem's runtime dependencies are unchanged.
+- Provide Bundler Audit in the development bundle and check the complete
+  dependency set in pull-request CI and immediately before release publication.
+
+### Compatibility and verification
+
+- The new SharedState sharing, Agent Tool composition and Context budgeting APIs
+  require 0.33.0 or later and remain Experimental. Default sharing and ordinary
+  Agent subclass inheritance retain their existing behavior. Custom sharing is
+  synchronous and invocation-scoped; it does not add durable sharing recovery.
+- Approval display is selected by each Tool. Custom Tool implementations without
+  `approval_display` expose empty display maps; execution and policy evaluation
+  still use the original arguments. Review custom display overrides for safe
+  human-facing fields when upgrading.
+- Observed LM Studio/gpt-oss PEG-format failures remain unresolved.
+  The existing adapter identifies known errors and bounds retries; this release
+  does not claim to fix their root cause or establish full real-LLM acceptance.
+  The latest full examples verification recorded 102 passed, 1 failed and no
+  skips (Example 22: HTTP 400). A separate Qwen Example 22 run completed all three
+  cycles, but took 2,220 seconds and does not replace the full verifier result
+  or satisfy its 240-second per-example limit.
+
 ## [0.32.0] - 2026-11-03
 
 ### Added

data/CONTRIBUTING.md

@@ -25,11 +25,11 @@ Run the linter:
 bundle exec standardrb
 ```
 
-Check that no Japanese characters appear in source files:
-
-```bash
-ruby scripts/check_japanese.rb
-```
+Check that source, comments, documentation and release notes are in English.
+Use the maintainer's external language checker and record its command, checked
+files and result with the review evidence. Check complete final files, including
+new files; a diff-only check can miss retained non-English content. This
+repository does not bundle a language-check script.
 
 ---
 

data/README.md

@@ -37,13 +37,31 @@ tracking `main` directly.
 
 See [Features and Application Programming Interface (API) stability](docs/features.md) for the full feature matrix.
 
-The following table describes the application APIs available in v0.32.0.
+The following table describes the application APIs available in v0.34.0.
+The sharing, Tool composition and Context budgeting operations remain
+Experimental; their introduction version is shown below.
 Worker hosting and completed parent/child release require v0.32.0 or later.
 Review the [0.31 migration notes](docs/migrations/0.31.md) before upgrading
 persistent applications or custom Agent Tool subclasses.
 
+The v0.34.0 cleanup removes obsolete entry points. Use
+`EventLoopReentrancyError` for EventLoop reentrancy failures and
+`Runtime#shutdown`'s `cleanup_complete?` result predicate for resource release;
+`clean?` additionally requires a graceful shutdown. See the
+[cleanup migration](docs/migrations/cleanup-audit.md) before upgrading to v0.34.0.
+The [legacy-format cleanup](docs/migrations/legacy-format-removal.md) separately
+retires old data-conversion entry points and read fallbacks without changing
+the current saved representation.
+
 | API | Stability | Contract |
 |---|---|---|
+| `Persistence::Migration::InitialFormatMigration` | Removed (v0.34.0) | The pre-S3 conversion API is retired without a replacement. Current domain codecs and the separate Unit4 snapshot migration remain. [Legacy-format cleanup](docs/migrations/legacy-format-removal.md) |
+| `Context::ContextPolicyInput#input_token_limit / #with_input_token_limit` and protected `ContextPolicy#estimate_tokens` | Experimental (since v0.33.0) | Inspect and constrain selection budgets and estimate candidate content through Context-owned operations. [Policy budgeting](docs/context-policy-budgeting.md) |
+| `Agent::Base.with_tools(definitions, id:, version:)` | Experimental (since v0.33.0) | Derive an Agent class with a complete replacement Tool map and explicit definition identity while preserving Phronomy authoring settings and filters. [Tool composition](docs/shared-state-sharing.md#deriving-an-agent-with-a-complete-tool-set) |
+| `MultiAgent::SharedState.sharing(provider, id:, version:)`, `SharedState::Binding` and `SharedState::MemberLifecycleError` | Experimental (since v0.33.0) | Connect application-owned shared data and Tools to sequential coordination through a synchronous invocation-scoped provider. [Custom sharing contract and example](docs/shared-state-sharing.md) |
+| `Tool::Base#approval_display(arguments:, facts:)` | Beta (since v0.33.0) | The Tool selects the arguments and derived facts a person can see in an approval request. [Approval display](docs/runtime-and-concurrency.md#tool-approval-display) |
+| `Runtime#shutdown` result predicates `cleanup_complete?` and `clean?` | Beta | Check resource release with `cleanup_complete?`; `clean?` additionally requires a graceful shutdown. The obsolete `success?` alias is removed in v0.34.0. [Cleanup migration](docs/migrations/cleanup-audit.md#runtime-cleanup-completion) |
+| `Phronomy::EventLoopReentrancyError` | Beta | Raised when a synchronous operation would block the EventLoop control thread. The obsolete `SchedulerReentrancyError` subclass is removed in v0.34.0. [Cleanup migration](docs/migrations/cleanup-audit.md#eventloop-reentrancy-errors) |
 | `Phronomy::LLMAdapter::LMStudio` | Beta | Explicit known-output-error identification and bounded opt-in retry; [policy and evidence limits](docs/architecture/lm-studio-output-failures.md) |
 | Agent `output_schema:`, `schema_delivery:`, `Agent::OutputError` and `OutputParser::JsonSchemaParser` | Beta | Agent returns validated immutable JSON or an explicit output failure; [contract and migration](docs/architecture/structured-output-and-scope.md) |
 | Agent `transcript_messages` / `transcript_messages_async` | Beta | Read immutable conversation Message values with the same restoration rules as execution results; [reading conversation state](docs/getting-started.md) |
@@ -200,6 +218,7 @@ contracts, timeout/cancellation semantics, metrics, and callback rules.
 - [0.19 unified Persistence migration](docs/migrations/0.19.md).
 - [0.22 semantic Multi-Agent Handoff migration](docs/migrations/0.22.md).
 - [0.31 persistence and Agent lifetime migration](docs/migrations/0.31.md).
+- [0.34 cleanup migration](docs/migrations/cleanup-audit.md) — replacement entry points and retained public operations.
 - [Architecture Decision Records](docs/decisions/) — design rationale and superseding decisions.
 - [CHANGELOG](CHANGELOG.md) — current development and recent release history.
 - [Changelog archive: 0.14.0 and earlier](docs/changelog/0.14-and-earlier.md).

data/RELEASE_CHECKLIST.md

@@ -24,7 +24,9 @@ Copy it into the GitHub Release draft and check off each item.
 
 - [ ] `bundle exec rspec --format documentation` — 0 failures
 - [ ] `bundle exec rspec --tag integration` — 0 failures, all expected pending
-- [ ] `ruby scripts/check_japanese.rb` — exit 0 (no Japanese in source)
+- [ ] External language check passes on the complete release files; source,
+  comments, documentation and release notes are in English. Record the checker
+  command, file scope and result; no language-check script is bundled here.
 - [ ] `bundle exec standardrb` — 0 offenses
 - [ ] `COVERAGE=1 bundle exec rspec` — coverage above configured threshold (Issue #207)
 - [ ] CI green on all Ruby matrix versions (3.2 / 3.3 / 3.4 / head)
@@ -38,6 +40,10 @@ Copy it into the GitHub Release draft and check off each item.
 - [ ] No new `requires_approval` tools missing the approval gate
 - [ ] No secrets, credentials, or PII in tool descriptions, schema strings, or spec fixtures
 - [ ] Dependency audit passes: `bundle exec bundler-audit check --update`
+  Run `bundle install` first; the development Gemfile provides the audit tool.
+  Audit the complete resolved bundle, including development and test dependencies,
+  without advisory exclusions. A runtime-only audit does not satisfy this gate.
+  The dependency-audit CI job and the release workflow enforce the same command.
 
 ---
 

data/SECURITY.md

@@ -4,7 +4,7 @@
 
 | Version | Supported |
 |---------|-----------|
-| Latest release (main branch) | ✅ |
+| 0.34.0 (latest release) | ✅ |
 | Older versions | ❌ — please upgrade |
 
 Only the latest released version of `phronomy` receives security patches. If you

data/VERIFY.sh

@@ -30,12 +30,10 @@ required_files=(
   lib/phronomy/persistence/durable_record.rb
   lib/phronomy/persistence/durable_codec.rb
   lib/phronomy/persistence/repository_facades.rb
-  lib/phronomy/persistence/migration/initial_format_migration.rb
   sig/phronomy/persistence.rbs
   spec/phronomy/persistence/backend_spi_api_spec.rb
   spec/phronomy/persistence/durable_codec_spec.rb
   spec/phronomy/persistence/in_memory_spec.rb
-  spec/phronomy/persistence/initial_format_migration_spec.rb
   lib/phronomy/testing/persistence_contract/a_workflow_state_repository.rb
   spec/phronomy/workflow_identity_contract_spec.rb
   lib/phronomy/engine/invocation_context.rb
@@ -128,11 +126,9 @@ syntax_files=(
   lib/phronomy/persistence/durable_record.rb
   lib/phronomy/persistence/durable_codec.rb
   lib/phronomy/persistence/repository_facades.rb
-  lib/phronomy/persistence/migration/initial_format_migration.rb
   spec/phronomy/persistence/backend_spi_api_spec.rb
   spec/phronomy/persistence/durable_codec_spec.rb
   spec/phronomy/persistence/in_memory_spec.rb
-  spec/phronomy/persistence/initial_format_migration_spec.rb
   lib/phronomy/testing/persistence_contract/a_workflow_state_repository.rb
   spec/phronomy/workflow_identity_contract_spec.rb
   lib/phronomy/engine/invocation_context.rb
@@ -327,17 +323,14 @@ ruby -c lib/phronomy/persistence/durable_record.rb >/dev/null
 ruby -c lib/phronomy/persistence/durable_codec.rb >/dev/null
 ruby -c lib/phronomy/persistence/repository_facades.rb >/dev/null
 ruby -c lib/phronomy/persistence/in_memory.rb >/dev/null
-ruby -c lib/phronomy/persistence/migration/initial_format_migration.rb >/dev/null
 ruby -c spec/phronomy/persistence/backend_spi_api_spec.rb >/dev/null
 ruby -c spec/phronomy/persistence/durable_codec_spec.rb >/dev/null
 ruby -c spec/phronomy/persistence/in_memory_spec.rb >/dev/null
-ruby -c spec/phronomy/persistence/initial_format_migration_spec.rb >/dev/null
 bundle exec rbs -I sig validate
 bundle exec rspec \
   spec/phronomy/persistence/backend_spi_api_spec.rb \
   spec/phronomy/persistence/durable_codec_spec.rb \
   spec/phronomy/persistence/in_memory_spec.rb \
-  spec/phronomy/persistence/initial_format_migration_spec.rb \
   spec/phronomy/persistence/backend_contract_spec.rb \
   spec/phronomy/agent/agent_execution_codec_spec.rb \
   spec/phronomy/agent/llm_input_manifest_spec.rb \
@@ -530,8 +523,7 @@ legacy_agent_invocation_identity="$(
 legacy_agent_invocation_identity="$(
   printf '%s\n' "$legacy_agent_invocation_identity" |
     grep -v 'lib/phronomy/agent/base.rb' |
-    grep -v 'lib/phronomy/agent/agent_execution.rb' |
-    grep -v 'lib/phronomy/persistence/migration/initial_format_migration.rb' || true
+    grep -v 'lib/phronomy/agent/agent_execution.rb' || true
 )"
 if [[ -n "$legacy_agent_invocation_identity" ]]; then
   echo "FAIL: active source/RBS reintroduced agent_invocation_id domain identity:" >&2

data/docs/architecture/error-api-review.md

@@ -175,7 +175,12 @@ unchanged and acyclic; Ruby+RBS architecture validation passes.
 
 ## Static exception inventory
 
-Ripper inspected 339 Ruby files. The following 63 definitions include base, private and optional-integration types; this is not a count of public APIs. Ruby declarations establish ownership. Existing RBS definitions and new owning-domain signatures are checked together.
+The original inventory used Ripper to inspect 339 Ruby files and listed 63
+definitions, including base, private and optional-integration types. The table
+below removes the superseded `SchedulerReentrancyError` entry as part of the
+[cleanup migration](../migrations/cleanup-audit.md). These historical scan totals
+are not a current count of source files or public APIs. Ruby declarations
+establish ownership; RBS declarations are checked at their owning boundaries.
 
 | Class | Parent | Declaration |
 |---|---|---|
@@ -208,7 +213,6 @@ Ripper inspected 339 Ruby files. The following 63 definitions include base, priv
 | `Phronomy::RecursionLimitError` | `Phronomy::Error` | `lib/phronomy/execution/recursion_limit_error.rb` |
 | `Phronomy::RuntimeShutdownError` | `Phronomy::Error` | `lib/phronomy/execution/runtime_shutdown_error.rb` |
 | `Phronomy::RuntimeShutdownReentrancyError` | `Phronomy::RuntimeShutdownError` | `lib/phronomy/execution/runtime_shutdown_reentrancy_error.rb` |
-| `Phronomy::SchedulerReentrancyError` | `Phronomy::EventLoopReentrancyError` | `lib/phronomy/execution/scheduler_reentrancy_error.rb` |
 | `Phronomy::TimeoutError` | `Phronomy::Error` | `lib/phronomy/execution/timeout_error.rb` |
 | `Phronomy::FilterBlockError` | `Phronomy::Error` | `lib/phronomy/filter/filter_block_error.rb` |
 | `Phronomy::GeneratorVerifier::UnacceptedResultError` | `Phronomy::Error` | `lib/phronomy/generation/generator_verifier/unaccepted_result_error.rb` |

data/docs/architecture/structured-output-and-scope.md

@@ -83,10 +83,11 @@ with lazy grammar` is a known native schema/Tool rejection. It is classified as
 stream operations. Unrelated string errors and requests without a schema retain
 their ordinary transport-error behavior. The adapter neither downgrades schemas
 nor replays requests. RubyLLM's configured transport retry policy is independent.
-The minimum Faraday streaming callback omits the HTTP status, so RubyLLM may
-surface this same exact rejection as `ServerError`; its cause is preserved too.
-That synthetic server status can trigger SDK retries before the adapter receives
-the error. Adapter replay tests disable SDK retries to verify their own boundary.
+On the supported HTTP stack, the known schema rejection retains its
+`RubyLLM::BadRequestError` cause even when streaming. An HTTP 500 with the same
+body retains its `RubyLLM::ServerError` cause. The
+[HTTP dependency rationale](trust-acceptance-followup.md#http-dependency-correction)
+documents the tested versions and request counts.
 
 `Response` records finish_reason (stop, tool_calls, length, content_filter, refusal,
 unknown), refusal and raw_finish_reason metadata. Only normal final completion can
@@ -172,10 +173,9 @@ Normal low-quality output follows the configured evaluation loop as before.
 
 `Result#failure` is nil except for output_failed, where it carries the owned error
 diagnostic (without raw_output). Hash/JSON round trips, equality, hashing and freeze
-include it. `Result.from_h` requires every new field; migrate old saved Result JSON
-explicitly with `scripts/migrate_generator_verifier_result.rb OLD.json NEW.json`.
-The script adds failure=nil, validates the result and creates a new file. It does
-not overwrite the source or silently alter invalid data. `raise_if_unaccepted`
+include it. `Result.from_h` requires every field, including `failure: nil` for
+results without an output failure. It rejects incomplete serialized results.
+`raise_if_unaccepted`
 retains the Result and the original OutputError cause in the same process.
 
 ## Symmetric lifetime rules

data/docs/architecture/trust-acceptance-followup.md

@@ -37,6 +37,21 @@ retain the SDK server-error cause. Configured SDK retries for 429/500 remain;
 a 400 rejection is one HTTP attempt even with three retries configured.
 Partial-stream replay and callback identity regressions remain in place.
 
+RubyLLM owns HTTP transport selection for model calls. Phronomy's LLM and
+Embeddings adapters recognize Faraday exception classes at the SDK boundary.
+The two gemspec declarations are a temporary workaround for the streaming
+status bug. Remove both when all supported RubyLLM versions preserve the
+status or exclude the affected HTTP stack through their own dependencies.
+
+Verify removal with the two Phronomy declarations omitted. Resolve the minimum
+supported RubyLLM and its permitted HTTP dependencies without the existing CI
+pins. If the old pair still resolves, test it explicitly. If RubyLLM excludes
+it, confirm resolution rejects it and test the new minimum. In both cases run
+`spec/integration/transport_error_spec.rb` against the minimum and the normal
+bundle. With three retries configured, a streaming HTTP 400 with a string
+error body must retain its 400 cause and send one POST. An HTTP 500 with the
+same body must retain its 500 cause and send four POSTs.
+
 Before and after, application handling uses the same public API:
 
 ```ruby

data/docs/context-policy-budgeting.md

@@ -0,0 +1,108 @@
+# Context Policy budgeting
+
+Applications choose how much model input capacity to use for one selection.
+Context exposes that capacity and candidate estimates, while the framework keeps
+its internal budget representation and final input validation.
+
+For example, a review Policy can reserve part of the available input for its own
+safety margin, then let DefaultPolicy choose history within the smaller limit.
+No application needs to construct a private budget object for that operation.
+
+## Reading and constraining input limits
+
+A Policy input reports its current selection limit and can derive another input
+with a smaller limit. Derivation preserves the original input and all its
+material; it does not change model capabilities or generation settings.
+
+For example, an input with a limit of 8192 can produce a selection input capped
+at 5632. The original input still reports 8192. The derived input cannot later
+increase its limit above 5632.
+
+```ruby
+require "phronomy"
+
+class ReservedInputPolicy < Phronomy::Context::ContextPolicy
+  def call(input)
+    limit = input.input_token_limit
+    unless limit
+      raise Phronomy::ConfigurationError, "Review requires known model input capacity"
+    end
+
+    selection_limit = limit - limit / 4 - limit / 16
+    selected_input = input.with_input_token_limit(selection_limit)
+    Phronomy::Context::DefaultPolicy.instance.call(selected_input)
+  end
+end
+```
+
+`input_token_limit` returns an Integer or `nil` for an unknown limit.
+`with_input_token_limit(limit)` requires a positive Integer without coercion;
+zero, negative values, strings and floating-point values raise `ArgumentError`.
+Increasing a known limit also raises `ArgumentError`. The returned
+`ContextPolicyInput` is immutable, and its other field values are unchanged.
+
+When the original limit is unknown, an explicit positive selection cap is
+allowed. That cap expresses application policy and does not establish that the
+model can accept that input. Applications that require known capability must
+reject `nil`, as the example above does.
+
+The cap controls selection performed with the derived input. The framework's
+final validation still uses the actual model budget; returning a different Plan
+does not make the derived cap a new global validator. It does not set an output
+token limit, alter a saved Manifest, or affect another Agent call.
+
+## Estimating candidate content
+
+A Policy can estimate proposed content through the same canonical encoding and
+estimator used by its generated items. The Policy remains responsible for
+choosing complete items and preserving required conversation groups.
+
+For example, a retrieval Policy can fit a JSON page before adding it as
+knowledge. JSON escaping contributes to the estimate because the complete
+serialized page is measured.
+
+```ruby
+require "phronomy"
+require "json"
+
+class PageKnowledgePolicy < Phronomy::Context::ContextPolicy
+  def initialize(page:, allowance:)
+    @page = page
+    @allowance = allowance
+  end
+
+  def call(input)
+    content = JSON.generate(@page)
+    if estimate_tokens(content) > @allowance
+      raise Phronomy::Context::BudgetExceededError, "Retrieved page exceeds its allowance"
+    end
+
+    page = knowledge_item(content: content, required: true)
+    Phronomy::Context::DefaultPolicy.instance.call(
+      input.with(knowledge: input.knowledge + [page])
+    )
+  end
+end
+```
+
+`estimate_tokens(content)` is a protected subclass helper. Strings are estimated
+as text; other values use the framework's canonical JSON encoding. The helper
+uses the existing estimator and does not introduce a second token-counting
+algorithm. Estimates are approximate unless the configured estimator provides
+model-specific counts. A successful estimate does not guarantee provider
+acceptance or replace final input validation.
+
+## Compatibility and ownership
+
+These operations belong to the Context contract and reuse its existing budget
+and estimation mechanisms. Applications own allocation ratios and retrieval
+policy; DefaultPolicy retains its current selection algorithm.
+
+For example, Example 22 can budget retrieved findings through these operations
+while SharedState continues to coordinate Agents and application Tools continue
+to own the finding store. No SharedState-to-Context dependency is introduced.
+
+The operations are Experimental and available since v0.33.0. Existing private
+budget and estimation classes remain implementation details. Existing ContextPolicy
+factories and DefaultPolicy behavior are unchanged, and the protected helper
+applies equally to normal Agent calls and SharedState member calls.

data/docs/decisions/016-semantic-multi-agent-handoff.md

@@ -61,11 +61,12 @@ Tool-role messages are one indivisible conversation group. When the selected
 Plan is realized, the Manifest records the Framework conversation-group identity
 and classifies canonical Tool exchanges as `tool_exchanges` for Handoff.
 
-`HandoffProjection` groups current-format Manifest segments by that conversation
-group identity. It may still read legacy `selection_unit_id` metadata from a
-finalized pre-ACS-04 Manifest, but new Context assembly does not recreate
-`Selection::Unit`. `Selection::Candidate` and `Selection::Constraint` remain
-internal Context-input normalization details only.
+The current `Agent::TransferProjection` groups Manifest segments by that
+conversation-group identity. Segments without a group identity are projected
+independently. Historical selection-unit identifiers and kinds are no longer
+interpreted, and Context assembly does not recreate `Selection::Unit`.
+`Selection::Candidate` and `Selection::Constraint` remain internal Context-input
+normalization details only.
 
 Handoff Policy answers what may cross the Agent boundary. Target Context Policy
 remains the final authority for what enters each Target LLM call. Transferred

data/docs/examples/shared_state_custom_sharing.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "json"
+require "phronomy"
+
+module SharedStateCustomSharingExample
+  class IssueBoard
+    attr_reader :closed
+
+    def initialize
+      @records = []
+      @closed = false
+    end
+
+    def record(content:, category:, status:, author:, cycle:)
+      raise "Issue board is closed" if closed
+
+      row = {id: @records.length + 1, content: content.dup.freeze,
+             category: category.dup.freeze, status: status.dup.freeze,
+             author: author.dup.freeze, cycle: cycle}.freeze
+      @records << row
+      row
+    end
+
+    def search(category: nil, status: nil)
+      snapshot.select do |row|
+        (category.nil? || row.fetch(:category) == category) &&
+          (status.nil? || row.fetch(:status) == status)
+      end
+    end
+
+    def snapshot
+      raise "Issue board is closed" if closed
+
+      @records.dup.freeze
+    end
+
+    def close
+      @records.clear
+      @closed = true
+    end
+  end
+
+  class IssueSharing
+    def open(input:, config:)
+      board = IssueBoard.new
+      yield Phronomy::MultiAgent::SharedState::Binding.new(
+        store: board,
+        tools: ->(member:, cycle:) { tool_definitions(board, member, cycle) }
+      )
+    ensure
+      board&.close
+    end
+
+    private
+
+    def tool_definitions(board, member, cycle)
+      {
+        record_tool(board, member.agent_definition.fetch(:id), cycle) => nil,
+        search_tool(board) => nil
+      }
+    end
+
+    def record_tool(board, author, cycle)
+      Class.new(Phronomy::Tool::Base) do
+        tool_name "record_issue"
+        description "Record one issue with an explicit category and status."
+        execution_mode :cooperative
+        param :content, type: :string, desc: "The issue description."
+        param :category, type: :string, enum: %w[security performance],
+          desc: "The issue category."
+        param :status, type: :string, enum: %w[open closed],
+          desc: "The issue status."
+
+        define_method(:execute) do |content:, category:, status:|
+          board.record(content: content, category: category, status: status,
+            author: author, cycle: cycle).to_json
+        end
+      end
+    end
+
+    def search_tool(board)
+      Class.new(Phronomy::Tool::Base) do
+        tool_name "search_issues"
+        description "Read issues matching all supplied category and status filters."
+        execution_mode :cooperative
+        param :category, type: :string, required: false, enum: %w[security performance],
+          desc: "Optional exact category filter."
+        param :status, type: :string, required: false, enum: %w[open closed],
+          desc: "Optional exact status filter."
+
+        define_method(:execute) do |category: nil, status: nil|
+          board.search(category: category, status: status).to_json
+        end
+      end
+    end
+  end
+
+  class Researcher < Phronomy::Agent::Base
+    agent_definition id: "shared-issue-researcher", version: 1
+    model ENV.fetch("PHRONOMY_EXAMPLE_MODEL", "configured-model")
+  end
+
+  class ReviewTeam < Phronomy::MultiAgent::SharedState
+    sharing IssueSharing.new, id: "shared-issues", version: 1
+    member Researcher
+    max_cycles 2
+    coordination "Use search_issues to inspect relevant issues. " \
+                 "Use record_issue to record each new issue with its category and status."
+    aggregate { |board| board.snapshot }
+  end
+
+  module OfflineDemo
+    def self.run
+      opened_board = nil
+      output = IssueSharing.new.open(input: "Review authentication", config: {}) do |binding|
+        opened_board = binding.store
+        definitions = binding.tool_definitions(member: Researcher, cycle: 1)
+        tools = definitions.keys.to_h { |tool| [tool.tool_name, tool.new] }
+        recorder = tools.fetch("record_issue")
+        recorder.call({"content" => "Missing token validation", "category" => "security", "status" => "open"})
+        recorder.call({"content" => "Slow cache lookup", "category" => "performance", "status" => "open"})
+        recorder.call({"content" => "Session expiry corrected", "category" => "security", "status" => "closed"})
+
+        matches = JSON.parse(tools.fetch("search_issues").call({"category" => "security", "status" => "open"}))
+        unless matches.map { |row| row.fetch("content") } == ["Missing token validation"]
+          raise "Search did not apply both filters"
+        end
+        all_records = binding.store.snapshot
+        raise "Search changed the board" unless all_records.length == 3
+
+        {matches: matches, total_records: all_records.length}
+      end
+      raise "Provider did not close the board" unless opened_board.closed
+
+      puts JSON.pretty_generate(output.merge(provider_closed: true))
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  abort "Run with --offline, or require this file from a configured Phronomy application." unless ARGV == ["--offline"]
+
+  SharedStateCustomSharingExample::OfflineDemo.run
+end