phronomy 0.33.0 → 0.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e696f701b22d91c4ccb8f566e28274b73e9fd69704a673e18a687a1d377b4583
-  data.tar.gz: 7a63749fb58c70fb6c74a843a601bb48401ffe35fa02de03a63fa9f8d6320552
+  metadata.gz: 4c67e91b9abb65c5ab2ddc5b657afa6843b916a5ba84aefcd8f808ae297c3236
+  data.tar.gz: b5894936fa47d493da81c650edbf3c330eaeec7101c68ec91acf96bec00d1a79
 SHA512:
-  metadata.gz: af029ecc2491d2912c48fef847f8501ce255040759bb5d8edba3949d2bea0352b2a6a89e731d70493570c5b72d26e094ed03d80aff412f6805af21a0da588219
-  data.tar.gz: 529ece7bc74b4096d332e9f39a3097933f1441797f5dc22b5bb9ec9d5b39fde2c42709d2b53e83b99a3e42ec6e2e9a227920f10371e6ac65772241cb54d0abc7
+  metadata.gz: ebec13bc657697922f3f487eefe809a35570b36a574e8a3ea95d5124459035ca263ad39b89419e8042621e4971f550cbb7d21ab206d2961f8a7f01bec6b9514e
+  data.tar.gz: b1d930edb100e7782522a9d666d555756fcc50e5be46881c58c035f2e021631093132b4bde4cec8134f296f068ddb9cb0fd17548ea356afad32652d484b7da91

data/CHANGELOG.md

@@ -12,6 +12,68 @@ 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

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,19 +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.33.0.
-The new sharing, Tool composition and Context budgeting operations remain
+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) |
@@ -206,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)

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

@@ -173,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/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/features.md

@@ -90,7 +90,7 @@ Backend authors continue to implement the synchronous SPI only.
 | **OffloadPool sizing** — `offload_pool_size` / `offload_queue_size`; named pools available for application-owned isolation | Beta |
 | **InvocationContext** — Explicit cancellation/deadline/policy plus observability-correlation context for Agent and Workflow invocations | Beta |
 | **Metrics** — OffloadPool active/queue/abandoned metrics plus EventLoop queue/lag metrics | Beta |
-| **Runtime lifecycle** — Runtime-owned EventLoop and terminal `Runtime#shutdown` | Beta |
+| **Runtime lifecycle** — Runtime-owned EventLoop and terminal `Runtime#shutdown`; use the result's `cleanup_complete?` for resource release and `clean?` for a graceful shutdown; [cleanup migration](migrations/cleanup-audit.md) | Beta |
 
 ## Agent and workflow patterns
 
@@ -109,7 +109,7 @@ See the [migration guide](migrations/parallel-tool-chat-removal.md).
 | **Hosted child approvals** — An Orchestrator can release a single direct child and its parent at successive Tool approvals within the same child execution. The host transfers exclusive ownership between workers. [Contract](runtime-and-concurrency.md#hosting-an-orchestrator-through-a-child-approval) | Beta |
 | **Completed native child release** — A host can unload the local Orchestrator and its finished direct child while preserving their saved results, conversation and coordination history. [Contract](runtime-and-concurrency.md#releasing-a-completed-orchestrator-and-child) | Beta |
 | **`Phronomy::MultiAgent::TeamCoordinator`** — LLM coordinator with stateful worker Agents | Beta |
-| **`Phronomy::MultiAgent::SharedState`** — Sequential peer-agent coordination through an invocation-local findings store; see the [namespace migration](migrations/shared-state-multi-agent.md) | Experimental |
+| **`Phronomy::MultiAgent::SharedState`** — Sequential peer-agent coordination through an invocation-local findings store; default member derivation preserves Phronomy authoring settings through `Agent::Base.with_tools`; see the [sharing contract](shared-state-sharing.md#deriving-an-agent-with-a-complete-tool-set) and [namespace migration](migrations/shared-state-multi-agent.md) | Experimental |
 | **Agent Tool composition** — `Agent::Base.with_tools(definitions, id:, version:)` derives a class with a complete replacement Tool map while preserving Phronomy authoring settings and filters; [contract](shared-state-sharing.md#deriving-an-agent-with-a-complete-tool-set) | Experimental (Unreleased) |
 | **Custom shared data and Tools** — `SharedState.sharing(provider, id:, version:)` and `SharedState::Binding` connect application-owned stores and Tool definitions without private overrides; [contract and executable example](shared-state-sharing.md) | Experimental (Unreleased) |
 | **Human-in-the-loop approval** — durable suspension publishes `:approval_required` through the Agent listener; `approve` / `approve_async` resumes the same logical `execution_id` with a fresh FSMSession incarnation | Beta |

data/docs/migrations/cleanup-audit.md

@@ -0,0 +1,89 @@
+# Cleanup audit migration
+
+Phronomy 0.34.0 removes redundant internal operations and old public entry points
+whose behavior is already provided by a current operation. Applications must
+use the current names; the removed names have no compatibility aliases. Current
+record writers are unchanged. The subsequent [legacy-format cleanup](legacy-format-removal.md)
+also removes old read fallbacks and explicitly retires two data-conversion
+entry points. It does not rewrite existing stores.
+
+For example, an application checking whether Runtime resources were released
+uses `cleanup_complete?` on the result returned by `Runtime#shutdown`. The
+removed `success?` method delegated to that same predicate.
+
+## Runtime cleanup completion
+
+Use `cleanup_complete?` to determine whether Runtime-owned resources have stopped.
+Use `clean?` only when the application also needs a graceful, error-free shutdown;
+that stricter predicate is retained and is not a replacement for `success?`.
+
+Before:
+
+```ruby
+result = runtime.shutdown
+resources_released = result.success?
+```
+
+After:
+
+```ruby
+result = runtime.shutdown
+resources_released = result.cleanup_complete?
+```
+
+The same replacement applies to a shutdown result returned by
+`Runtime.reset_default!`. Existing reset guards still reject incomplete cleanup.
+
+## EventLoop reentrancy errors
+
+Rescue `Phronomy::EventLoopReentrancyError` when a synchronous operation would
+block the EventLoop control thread. Framework operations already raise this
+class. The removed `SchedulerReentrancyError` was an empty subclass and did not
+add a distinct failure or recovery behavior.
+
+Before:
+
+```ruby
+begin
+  Phronomy::Diagnostics.assert_not_in_event_loop!
+rescue Phronomy::SchedulerReentrancyError => error
+  warn error.message
+end
+```
+
+After:
+
+```ruby
+begin
+  Phronomy::Diagnostics.assert_not_in_event_loop!
+rescue Phronomy::EventLoopReentrancyError => error
+  warn error.message
+end
+```
+
+Ruby rescue matches a class and its subclasses, not its parent. The old rescue
+above therefore did not catch a directly raised `EventLoopReentrancyError` even
+before this cleanup. The current error name describes the actual failure.
+
+## Internal operations
+
+Internal cleanup keeps behavior at its owning boundary. Context item factories
+call the protected `ContextPolicy#estimate_tokens` extension operation directly.
+Tool approval requests obtain one display projection and snapshot its arguments
+and facts in the public approval Item.
+
+For example, an application that renders approval details continues to use
+`ToolApprovalRequest::Item#arguments` and `#facts`; it does not need the removed
+internal `ToolInvocation#display_arguments` and `#display_facts` getters. The
+public `Tool::Base#approval_display` extension operation remains available.
+
+The cleanup also removes the unused internal `AgentInvocation#streaming?`,
+`RecoveryRules.subject_key`, and `Execution#__while_open` and
+`Execution#__cancellation_token` methods. Scope-owned operations used by result
+composition remain in `ExecutionScopeState`. Five completed scripts for migrating
+the repository's own test sources are removed. The subsequent legacy-format
+cleanup separately retires the pre-S3 migration API and old Result JSON converter.
+
+`JournalProjection#llm_call_records` and
+`LLMInputManifest#referenced_content_refs` remain available. Lack of calls from
+the repository does not make an application-facing operation removable.

data/docs/migrations/legacy-format-removal.md

@@ -0,0 +1,55 @@
+# Legacy-format cleanup
+
+Phronomy 0.34.0 keeps current saved facts and removes specific historical read
+fallbacks and conversion facilities. It does not rewrite stores or introduce a
+new record version. Retiring the conversion facilities is an intentional removal
+of migration support, not a claim that another public API replaces them.
+
+For example, a newly authorized Tool operation continues to store its validated
+arguments, including type coercion and meaningful null values. Its reader no
+longer reconstructs those arguments from an older raw-input field.
+
+## Handoff conversation groups
+
+Handoff uses the conversation group recorded by the current Context assembly.
+The historical selection-unit ID and kind no longer supply grouping or category
+information. Segments without a current group still use the ordinary per-segment
+fallback; reserved internal metadata is still removed from transferred content.
+
+For example, current Tool-call and Tool-result segments share
+`context_policy_conversation_group_id` and remain together when a Handoff policy
+selects that exchange. A saved `selection_unit_id` is no longer an alternative
+source for that relationship. The Manifest codec remains strict about its
+supported version and required fields.
+
+## Authorized Tool arguments
+
+Agent Store reads the exact validated argument snapshot for an authorized
+operation. The raw request remains a separate fact and is not a substitute when
+the validated snapshot is absent.
+
+For example, raw `{"count":"2","optional":null}` may validate as
+`{"count":2,"optional":null}`. Authorization matching must use the integer and
+retain the explicit null. An authorized record missing `validated_arguments`
+fails instead of falling back to `arguments` and dropping null values.
+
+Provider-response recovery can temporarily record an `authorized` placeholder
+without that snapshot. The normal `framework_calls` continuation validates its
+Tool invocation and saves the prepared snapshot before an operation consumer
+reads it. Directly projecting the intermediate placeholder is rejected; its
+status alone is not proof that its arguments have been validated. A resumed
+`framework_tools` continuation instead uses its previously saved dispatch
+snapshot.
+
+## Retired conversion support
+
+The pre-S3 `Persistence::Migration::InitialFormatMigration` API and the
+GeneratorVerifier Result JSON converter are removed, along with the former
+command's usage instructions. There is no compatibility alias or replacement
+conversion command. Ordinary Agent and Workflow persistence, current Manifest
+decoding and GeneratorVerifier Result validation remain in their owning domains.
+
+For example, `GeneratorVerifier::Result.from_h` still requires `failure` even
+when its value is null. It does not add missing fields to historical JSON.
+The separate `PersistenceComposition::Unit4Migration` snapshot conversion is
+retained and was not an implementation of either removed conversion facility.

data/docs/migrations/r8-unit6.md

@@ -91,8 +91,10 @@ an explicit items schema to restrict them.
 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,
+null in explicit schemas). Authorization projection requires this validated
+dispatch evidence; it does not infer approved values from raw request fields.
+Provider-recovery placeholders are revalidated and replaced by the normal Tool
+dispatch barrier before framework operations run. 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.

data/docs/migrations/vector-async-clients.md

@@ -107,4 +107,9 @@ The public class names below are unchanged. Their implementation files move:
 Use `require "phronomy"` and the public constants. Direct partial-load paths are
 not the public loading contract; no require shim is kept in the contract
 directories. Backend Contracts have no execution or implementation dependency.
-P4 Storage/ContentStore work remains pending.
+P4 Storage/ContentStore work is implemented; see the
+[Storage asynchronous execution guide](storage-async-client.md).
+[ADR-062](../decisions/062-content-store-service.md) subsequently classified
+ContentStore as a content service over Storage, rather than a physical backend.
+The final P5 cross-repository/API/documentation review remains pending, as
+recorded in [Backend responsibilities](../architecture/backend-groups.md).

data/docs/shared-state-sharing.md

@@ -102,8 +102,9 @@ argument to the default `read_store` Tool or a search method to that store.
 The public `Agent::Base.with_tools(definitions, id:, version:)` factory creates
 an Agent subclass with a replacement Tool map and an explicit definition
 identity. Agent owns preservation of its authoring settings; SharedState uses
-this public operation after composing the member and application Tools. It does
-not need to read Agent private settings.
+this public operation after composing the member Tools with either its built-in
+sharing Tools or the application's Tools. It does not need to read Agent private
+settings.
 
 For example, inside the complete example's module, a provider can supply the
 entire Tool map for a derived researcher class:
@@ -131,6 +132,13 @@ The original class is unchanged. This explicit factory does not change general
 Agent subclass inheritance or define copying rules for application-specific
 class state.
 
+The default findings-store mode now preserves these settings through the same
+factory. For example, a member configured with `max_iterations 3` and
+`temperature 0.25` keeps those settings when SharedState adds `read_store` and
+`write_finding`. Member Tool aliases, the generated definition identity and the
+default store/prompt behavior remain unchanged. This fixes the earlier default
+derivation, which explicitly copied only the model setting.
+
 ## Application search and LLM input
 
 Application Tools own record fields and search conditions. ContextPolicy and the
@@ -151,8 +159,10 @@ explicitly through the existing appropriate contracts.
 SharedState continues to use the member's configured ContextPolicy. The binding
 does not automatically populate `before_llm_input` candidates, inspect Context
 internals or manage a provider message buffer. Example 22's adaptive reader is a
-separate application implementation; this extension alone does not migrate it
-or remove its existing private-API dependency.
+separate application implementation. Its current version uses the public sharing
+contract and Context budgeting APIs introduced in v0.33.0; its previous private
+overrides have been removed. The application still owns adaptive retrieval and
+budget allocation rather than delegating those policies to the sharing binding.
 
 ## Lifetime and verification
 

data/lib/phronomy/agent/execution/agent_invocation.rb

@@ -114,10 +114,6 @@ module Phronomy
         @callback_failure = nil
       end
 
-      def streaming?
-        @mode == :stream
-      end
-
       def set_graph_metadata(phase: nil)
         @phase = phase
       end

data/lib/phronomy/agent/handoff/transfer_projection.rb

@@ -83,9 +83,6 @@ module Phronomy
         return :current_request if segment.delivery.to_sym == :ask_argument
         return nil if CONTROL_CATEGORIES.include?(segment.category.to_sym)
         return :knowledge if segment.category.to_sym == :knowledge
-        unit_kind = segment.metadata["selection_unit_kind"] ||
-          segment.metadata[:selection_unit_kind]
-        return :tool_exchanges if unit_kind.to_s == "tool_exchange"
 
         case segment.category.to_sym
         when :external_message, :assistant_message, :tool_message,
@@ -102,12 +99,6 @@ module Phronomy
           return "context-policy-conversation:#{conversation_group_id}"
         end
 
-        # Compatibility for finalized pre-ACS-04 manifests. New manifests use
-        # context_policy_conversation_group_id and do not recreate Phronomy::Context::Unit.
-        unit_id = segment.metadata["selection_unit_id"] ||
-          segment.metadata[:selection_unit_id]
-        return "unit:#{unit_id}" if unit_id
-
         "segment:#{policy_category}:#{segment.position}"
       end
 

data/lib/phronomy/agent/journal/journal_record.rb

@@ -57,8 +57,8 @@ module Phronomy
         ATTRIBUTES.to_h { |name| [name.to_s, public_send(name)] }
       end
 
-      # Historical durable fields are not accepted here. Explicit migration must
-      # convert them to the current semantic payload first.
+      # Reads the current semantic payload only. Historical durable fields are
+      # rejected rather than converted.
       def self.from_h(hash)
         source = hash.to_h { |key, value| [key.to_s, value] }
         expected = ATTRIBUTES.map(&:to_s).sort

data/lib/phronomy/agent/recovery/recovery_rules.rb

@@ -88,18 +88,6 @@ module Phronomy
         normalized.freeze
       end
 
-      def subject_key(subject)
-        normalized = normalize_subject(subject)
-        case normalized.fetch(:type)
-        when :llm_call
-          "llm_call:#{normalized.fetch(:llm_call_id)}"
-        when :tool_invocation
-          "tool_invocation:#{normalized.fetch(:tool_invocation_id)}"
-        when :persistence_operation
-          "persistence_operation:#{normalized.fetch(:entity)}"
-        end
-      end
-
       def subject_equal?(left, right)
         normalize_subject(left) == normalize_subject(right)
       rescue ArgumentError, KeyError

data/lib/phronomy/agent/store.rb

@@ -48,6 +48,7 @@ module Phronomy
 
       # Validate the exact requested call and project its authorized batch in
       # Provider order from one execution snapshot in the caller's transaction.
+      # Only the validated dispatch snapshot is authorization evidence.
       # The receiving domain owns application and replay of these operations.
       def authorized_operations(scope, agent_id:, execution_id:, invocation_id:, name:, arguments:, names:)
         participate(scope) do |records|
@@ -58,7 +59,7 @@ module Phronomy
           batch = Array(execution.metadata[ExecutionMetadata::TOOL_BATCH_METADATA_KEY])
           requested = batch.find { |entry| entry.fetch("tool_invocation_id") == invocation_id }
           unless names.include?(name) && requested && requested.fetch("status") == "authorized" &&
-              requested.fetch("tool_name") == name && authorized_argument_values(requested) == arguments
+              requested.fetch("tool_name") == name && requested.fetch("validated_arguments") == arguments
             raise Phronomy::Persistence::StateConflictError, "Operation #{invocation_id} is not the authorized call"
           end
           batch.filter_map do |entry|
@@ -66,7 +67,7 @@ module Phronomy
             AuthorizedOperation.new(
               invocation_id: Phronomy::Values::Immutable.copy(entry.fetch("tool_invocation_id")),
               name: Phronomy::Values::Immutable.copy(entry.fetch("tool_name")),
-              arguments: Phronomy::Values::Immutable.copy(authorized_argument_values(entry))
+              arguments: Phronomy::Values::Immutable.copy(entry.fetch("validated_arguments"))
             )
           end.freeze
         end
@@ -286,12 +287,6 @@ module Phronomy
           Phronomy::Values::Immutable.json(contents.fetch_json(execution.result_ref)) : contents.fetch_text(execution.result_ref)
       end
 
-      def authorized_argument_values(entry)
-        # Unit 6 persists the exact validated snapshot. Older records encoded
-        # legacy raw params, whose explicit optional nil meant omission.
-        entry.key?("validated_arguments") ? entry.fetch("validated_arguments") : entry.fetch("arguments").compact
-      end
-
       def with_scope(scope, &block)
         assert_observation_thread!
         scope ? participate(scope, &block) : transaction(&block)

data/lib/phronomy/agent/tool_execution/tool_invocation.rb

@@ -345,9 +345,6 @@ module Phronomy
         display
       end
 
-      def display_arguments = immutable_copy(approval_display.fetch(:arguments))
-      def display_facts = immutable_copy(approval_display.fetch(:facts))
-
       private
 
       def restore_saved_state!(status, result)