phronomy 0.33.0 → 0.35.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +104 -0
  3. data/CONTRIBUTING.md +5 -5
  4. data/README.md +17 -2
  5. data/RELEASE_CHECKLIST.md +3 -1
  6. data/SECURITY.md +1 -1
  7. data/VERIFY.sh +1 -9
  8. data/docs/architecture/backend-groups.md +69 -19
  9. data/docs/architecture/error-api-review.md +6 -2
  10. data/docs/architecture/storage-execution-boundaries.md +49 -29
  11. data/docs/architecture/structured-output-and-scope.md +3 -4
  12. data/docs/decisions/016-semantic-multi-agent-handoff.md +6 -5
  13. data/docs/decisions/027-llm-adapter-provider-boundary.md +7 -1
  14. data/docs/decisions/059-backend-contracts-and-async-clients.md +16 -4
  15. data/docs/features.md +4 -3
  16. data/docs/migrations/cleanup-audit.md +89 -0
  17. data/docs/migrations/legacy-format-removal.md +55 -0
  18. data/docs/migrations/r8-unit6.md +4 -2
  19. data/docs/migrations/storage-async-client.md +47 -17
  20. data/docs/migrations/vector-async-clients.md +24 -10
  21. data/docs/persistence-backends.md +50 -5
  22. data/docs/shared-state-sharing.md +14 -4
  23. data/lib/phronomy/agent/execution/agent_invocation.rb +0 -4
  24. data/lib/phronomy/agent/handoff/transfer_projection.rb +0 -9
  25. data/lib/phronomy/agent/journal/journal_record.rb +2 -2
  26. data/lib/phronomy/agent/recovery/recovery_rules.rb +0 -12
  27. data/lib/phronomy/agent/store.rb +3 -8
  28. data/lib/phronomy/agent/tool_execution/tool_invocation.rb +0 -3
  29. data/lib/phronomy/context/context_policy.rb +3 -7
  30. data/lib/phronomy/context/llm_input_manifest.rb +3 -3
  31. data/lib/phronomy/engine/runtime/shutdown_result.rb +0 -5
  32. data/lib/phronomy/execution/execution.rb +0 -11
  33. data/lib/phronomy/multi_agent/shared_state.rb +5 -8
  34. data/lib/phronomy/persistence/content_repository.rb +2 -1
  35. data/lib/phronomy/persistence_composition/stores.rb +14 -2
  36. data/lib/phronomy/storage/async/async_client.rb +0 -12
  37. data/lib/phronomy/vector_store/async/async_client.rb +3 -3
  38. data/lib/phronomy/version.rb +1 -1
  39. data/scripts/api_snapshot.rb +2 -2
  40. data/sig/phronomy/persistence_composition.rbs +2 -0
  41. data/sig/phronomy/vector_store/async/async_client.rbs +2 -2
  42. metadata +4 -11
  43. data/lib/phronomy/execution/scheduler_reentrancy_error.rb +0 -9
  44. data/lib/phronomy/persistence/migration/initial_format_migration.rb +0 -226
  45. data/scripts/add_to_h_to_token_doubles.rb +0 -33
  46. data/scripts/add_to_h_unnamed_doubles.rb +0 -27
  47. data/scripts/migrate_generator_verifier_result.rb +0 -18
  48. data/scripts/migrate_spec_agent_definition.rb +0 -108
  49. data/scripts/migrate_spec_agent_definition_pass2.rb +0 -53
  50. data/scripts/migrate_spec_inline_pass3.rb +0 -24
  51. data/sig/phronomy/persistence/migration.rbs +0 -13
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: e696f701b22d91c4ccb8f566e28274b73e9fd69704a673e18a687a1d377b4583
4
- data.tar.gz: 7a63749fb58c70fb6c74a843a601bb48401ffe35fa02de03a63fa9f8d6320552
3
+ metadata.gz: 6d22c5161612ef11e4a4facc21f6f0de5a92cd7c79c5c4b810dc048675a3ae9a
4
+ data.tar.gz: 04cb167dc080f27262634e9e33fe5668ddd9b125bbb6e3345d8ec6e5c2cd7f11
5
5
  SHA512:
6
- metadata.gz: af029ecc2491d2912c48fef847f8501ce255040759bb5d8edba3949d2bea0352b2a6a89e731d70493570c5b72d26e094ed03d80aff412f6805af21a0da588219
7
- data.tar.gz: 529ece7bc74b4096d332e9f39a3097933f1441797f5dc22b5bb9ec9d5b39fde2c42709d2b53e83b99a3e42ec6e2e9a227920f10371e6ac65772241cb54d0abc7
6
+ metadata.gz: 64fff83cad837875f1c8682e917377723bedec10ea1bcafcb3aed14f78617e3e29c80ff8327b1242ae47da8e9c0628bb42549aeb1d4021c09af75aab53ed3b64
7
+ data.tar.gz: 169a3f9bb47b4fdf5004ff5731c8fd95d3c0f949d46f99fdff6a67aa8de80b4efe07ba523c132b0f0bcf5831c255b722afff28777a74a93be457db10d8ba6980
data/CHANGELOG.md CHANGED
@@ -12,6 +12,110 @@ Release history for 0.14.0 and earlier is archived in
12
12
 
13
13
  ## [Unreleased]
14
14
 
15
+ ## [0.35.0] - 2026-11-17
16
+
17
+ ### Added
18
+
19
+ - Add public Beta `PersistenceComposition.resources` and `.agent_resources` for
20
+ constructing external backends with the canonical full or Agent-only resource
21
+ catalog. Both return frozen Arrays of existing Resource objects without
22
+ creating backends, stores or Runtime. The internal StorageSchema stays private.
23
+
24
+ ### Fixed
25
+
26
+ - Correct dependency-generated state-machine success assertions for both boolean
27
+ and Transition return values. Refusal remains exactly false, and destination,
28
+ guard order, exception and approval/resume checks remain intact. The existing
29
+ execution boundary already normalizes successful values; product behavior and
30
+ dependency requirements are unchanged.
31
+ - Align VectorStore AsyncClient RBS input types with the synchronous public
32
+ operations: Numeric vectors and Integer or decimal String search limits.
33
+ - Correct current Embeddings names, LLM extension ownership, Execution client
34
+ boundaries and the 14-site domain persistence submission inventory. Distinguish
35
+ neutral coordinator scopes from domain transactions and retain superseded ADR
36
+ rationale as explicitly historical.
37
+
38
+ ### Removed
39
+
40
+ - Remove the unused private `Storage::AsyncClient.submit` forwarding helper.
41
+ Domain operations already submit through their execution environments or
42
+ Execution; public `transaction_async` and its transaction behavior are retained.
43
+
44
+ ### Compatibility and verification
45
+
46
+ - External persistence backend integrations can use the public resource catalogs
47
+ starting with v0.35.0 instead of reading private StorageSchema declarations.
48
+ Composition owns the canonical catalog; integrations retain backend mapping
49
+ and connection ownership. Resource identity, current saved formats, public
50
+ transaction behavior and domain recovery policies are unchanged.
51
+ - VectorStore input type declarations now describe inputs already accepted by
52
+ synchronous operations; this does not add coercion or change search behavior.
53
+ - This release does not resolve the root cause of previously observed
54
+ LM Studio/gpt-oss PEG-format failures or claim to prevent recurrence.
55
+ Published-gem examples acceptance remains separate from core verification.
56
+
57
+ ## [0.34.0] - 2026-11-16
58
+
59
+ ### Changed
60
+
61
+ - Route ContextPolicy item estimates directly through the protected
62
+ `estimate_tokens` extension operation, removing the redundant private wrapper.
63
+ - Exercise Tool approval redaction through the display/snapshot path used by
64
+ production approval requests instead of internal convenience getters.
65
+ - Replace references to an absent repository language-check script with an
66
+ external maintainer check and recorded evidence. Correct the Storage phase
67
+ status: P4 is implemented; the separate final P5 review remains pending.
68
+
69
+ ### Fixed
70
+
71
+ - Derive default SharedState members through `Agent::Base.with_tools`, retaining
72
+ Phronomy authoring settings and filters as custom sharing already does. A
73
+ member's iteration limit, temperature and other configuration no longer reset
74
+ when built-in sharing Tools are added. Preserve Tool aliases, the generated
75
+ definition identity and default findings-store behavior.
76
+
77
+ ### Removed
78
+
79
+ - Remove Handoff's old selection-unit metadata fallback and Agent Store's raw
80
+ argument fallback. Current conversation groups and exact validated arguments
81
+ remain the authoritative saved facts; current record writers are unchanged.
82
+ - Retire `Persistence::Migration::InitialFormatMigration` and the old
83
+ GeneratorVerifier Result JSON conversion command, including their dedicated
84
+ migration tests and active usage instructions. No replacement converter or
85
+ compatibility entry point is supplied. Current codecs, Result validation and
86
+ the separate Unit4 snapshot migration remain. See the
87
+ [legacy-format cleanup](docs/migrations/legacy-format-removal.md).
88
+ - Remove `Runtime::ShutdownResult#success?`; use the equivalent
89
+ `cleanup_complete?`. Keep `clean?`, which additionally requires a graceful
90
+ shutdown.
91
+ - Remove the obsolete `SchedulerReentrancyError` subclass; use
92
+ `EventLoopReentrancyError`, which is already raised by current execution paths.
93
+ No compatibility aliases are retained. See the
94
+ [cleanup migration](docs/migrations/cleanup-audit.md).
95
+ - Remove unused internal Invocation, RecoveryRules and Execution helpers, along
96
+ with five completed development-only spec migration scripts. Keep the public
97
+ `JournalProjection#llm_call_records` and
98
+ `LLMInputManifest#referenced_content_refs` operations and the Scope hooks still
99
+ used for result composition.
100
+
101
+ ### Compatibility and verification
102
+
103
+ - Replace `Runtime::ShutdownResult#success?` with `cleanup_complete?` and rescue
104
+ `EventLoopReentrancyError` instead of the removed `SchedulerReentrancyError`.
105
+ No compatibility aliases are retained. See the
106
+ [cleanup migration](docs/migrations/cleanup-audit.md).
107
+ - Historical pre-S3 and GeneratorVerifier Result conversion support is retired
108
+ without a replacement command. Current record writers and saved representation
109
+ are unchanged; this release does not rewrite existing stores. Handoff no longer
110
+ derives groups from old selection-unit metadata, and authorization requires
111
+ validated argument evidence. Review the
112
+ [legacy-format migration](docs/migrations/legacy-format-removal.md) before
113
+ upgrading applications that still consume those historical records.
114
+ - Previously observed LM Studio/gpt-oss PEG-format failures are not resolved by
115
+ this cleanup. This release does not claim to fix their root cause or prevent
116
+ recurrence; offline persistence/recovery checks do not establish full real-LLM
117
+ acceptance.
118
+
15
119
  ## [0.33.0] - 2026-11-14
16
120
 
17
121
  ### Added
data/CONTRIBUTING.md CHANGED
@@ -25,11 +25,11 @@ Run the linter:
25
25
  bundle exec standardrb
26
26
  ```
27
27
 
28
- Check that no Japanese characters appear in source files:
29
-
30
- ```bash
31
- ruby scripts/check_japanese.rb
32
- ```
28
+ Check that source, comments, documentation and release notes are in English.
29
+ Use the maintainer's external language checker and record its command, checked
30
+ files and result with the review evidence. Check complete final files, including
31
+ new files; a diff-only check can miss retained non-English content. This
32
+ repository does not bundle a language-check script.
33
33
 
34
34
  ---
35
35
 
data/README.md CHANGED
@@ -37,19 +37,33 @@ tracking `main` directly.
37
37
 
38
38
  See [Features and Application Programming Interface (API) stability](docs/features.md) for the full feature matrix.
39
39
 
40
- The following table describes the application APIs available in v0.33.0.
41
- The new sharing, Tool composition and Context budgeting operations remain
40
+ The following table describes the application APIs available in v0.35.0.
41
+ The public persistence resource catalogs are available starting with v0.35.0.
42
+ The sharing, Tool composition and Context budgeting operations remain
42
43
  Experimental; their introduction version is shown below.
43
44
  Worker hosting and completed parent/child release require v0.32.0 or later.
44
45
  Review the [0.31 migration notes](docs/migrations/0.31.md) before upgrading
45
46
  persistent applications or custom Agent Tool subclasses.
46
47
 
48
+ The v0.34.0 cleanup removes obsolete entry points. Use
49
+ `EventLoopReentrancyError` for EventLoop reentrancy failures and
50
+ `Runtime#shutdown`'s `cleanup_complete?` result predicate for resource release;
51
+ `clean?` additionally requires a graceful shutdown. See the
52
+ [cleanup migration](docs/migrations/cleanup-audit.md) before upgrading to v0.34.0.
53
+ The [legacy-format cleanup](docs/migrations/legacy-format-removal.md) separately
54
+ retires old data-conversion entry points and read fallbacks without changing
55
+ the current saved representation.
56
+
47
57
  | API | Stability | Contract |
48
58
  |---|---|---|
59
+ | `PersistenceComposition.resources` and `.agent_resources` | Beta (since v0.35.0) | Supply canonical frozen resource catalogs to an application-selected backend for `.build(backend:)` or `.agent(backend:)`, without creating a backend, stores or Runtime. [Backend catalog](docs/persistence-backends.md#supplying-a-backend-catalog) |
60
+ | `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) |
49
61
  | `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) |
50
62
  | `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) |
51
63
  | `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) |
52
64
  | `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) |
65
+ | `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) |
66
+ | `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) |
53
67
  | `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) |
54
68
  | 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) |
55
69
  | 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 +220,7 @@ contracts, timeout/cancellation semantics, metrics, and callback rules.
206
220
  - [0.19 unified Persistence migration](docs/migrations/0.19.md).
207
221
  - [0.22 semantic Multi-Agent Handoff migration](docs/migrations/0.22.md).
208
222
  - [0.31 persistence and Agent lifetime migration](docs/migrations/0.31.md).
223
+ - [0.34 cleanup migration](docs/migrations/cleanup-audit.md) — replacement entry points and retained public operations.
209
224
  - [Architecture Decision Records](docs/decisions/) — design rationale and superseding decisions.
210
225
  - [CHANGELOG](CHANGELOG.md) — current development and recent release history.
211
226
  - [Changelog archive: 0.14.0 and earlier](docs/changelog/0.14-and-earlier.md).
data/RELEASE_CHECKLIST.md CHANGED
@@ -24,7 +24,9 @@ Copy it into the GitHub Release draft and check off each item.
24
24
 
25
25
  - [ ] `bundle exec rspec --format documentation` — 0 failures
26
26
  - [ ] `bundle exec rspec --tag integration` — 0 failures, all expected pending
27
- - [ ] `ruby scripts/check_japanese.rb` — exit 0 (no Japanese in source)
27
+ - [ ] External language check passes on the complete release files; source,
28
+ comments, documentation and release notes are in English. Record the checker
29
+ command, file scope and result; no language-check script is bundled here.
28
30
  - [ ] `bundle exec standardrb` — 0 offenses
29
31
  - [ ] `COVERAGE=1 bundle exec rspec` — coverage above configured threshold (Issue #207)
30
32
  - [ ] CI green on all Ruby matrix versions (3.2 / 3.3 / 3.4 / head)
data/SECURITY.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  | Version | Supported |
6
6
  |---------|-----------|
7
- | Latest release (main branch) | ✅ |
7
+ | 0.35.0 (latest release) | ✅ |
8
8
  | Older versions | ❌ — please upgrade |
9
9
 
10
10
  Only the latest released version of `phronomy` receives security patches. If you
data/VERIFY.sh CHANGED
@@ -30,12 +30,10 @@ required_files=(
30
30
  lib/phronomy/persistence/durable_record.rb
31
31
  lib/phronomy/persistence/durable_codec.rb
32
32
  lib/phronomy/persistence/repository_facades.rb
33
- lib/phronomy/persistence/migration/initial_format_migration.rb
34
33
  sig/phronomy/persistence.rbs
35
34
  spec/phronomy/persistence/backend_spi_api_spec.rb
36
35
  spec/phronomy/persistence/durable_codec_spec.rb
37
36
  spec/phronomy/persistence/in_memory_spec.rb
38
- spec/phronomy/persistence/initial_format_migration_spec.rb
39
37
  lib/phronomy/testing/persistence_contract/a_workflow_state_repository.rb
40
38
  spec/phronomy/workflow_identity_contract_spec.rb
41
39
  lib/phronomy/engine/invocation_context.rb
@@ -128,11 +126,9 @@ syntax_files=(
128
126
  lib/phronomy/persistence/durable_record.rb
129
127
  lib/phronomy/persistence/durable_codec.rb
130
128
  lib/phronomy/persistence/repository_facades.rb
131
- lib/phronomy/persistence/migration/initial_format_migration.rb
132
129
  spec/phronomy/persistence/backend_spi_api_spec.rb
133
130
  spec/phronomy/persistence/durable_codec_spec.rb
134
131
  spec/phronomy/persistence/in_memory_spec.rb
135
- spec/phronomy/persistence/initial_format_migration_spec.rb
136
132
  lib/phronomy/testing/persistence_contract/a_workflow_state_repository.rb
137
133
  spec/phronomy/workflow_identity_contract_spec.rb
138
134
  lib/phronomy/engine/invocation_context.rb
@@ -327,17 +323,14 @@ ruby -c lib/phronomy/persistence/durable_record.rb >/dev/null
327
323
  ruby -c lib/phronomy/persistence/durable_codec.rb >/dev/null
328
324
  ruby -c lib/phronomy/persistence/repository_facades.rb >/dev/null
329
325
  ruby -c lib/phronomy/persistence/in_memory.rb >/dev/null
330
- ruby -c lib/phronomy/persistence/migration/initial_format_migration.rb >/dev/null
331
326
  ruby -c spec/phronomy/persistence/backend_spi_api_spec.rb >/dev/null
332
327
  ruby -c spec/phronomy/persistence/durable_codec_spec.rb >/dev/null
333
328
  ruby -c spec/phronomy/persistence/in_memory_spec.rb >/dev/null
334
- ruby -c spec/phronomy/persistence/initial_format_migration_spec.rb >/dev/null
335
329
  bundle exec rbs -I sig validate
336
330
  bundle exec rspec \
337
331
  spec/phronomy/persistence/backend_spi_api_spec.rb \
338
332
  spec/phronomy/persistence/durable_codec_spec.rb \
339
333
  spec/phronomy/persistence/in_memory_spec.rb \
340
- spec/phronomy/persistence/initial_format_migration_spec.rb \
341
334
  spec/phronomy/persistence/backend_contract_spec.rb \
342
335
  spec/phronomy/agent/agent_execution_codec_spec.rb \
343
336
  spec/phronomy/agent/llm_input_manifest_spec.rb \
@@ -530,8 +523,7 @@ legacy_agent_invocation_identity="$(
530
523
  legacy_agent_invocation_identity="$(
531
524
  printf '%s\n' "$legacy_agent_invocation_identity" |
532
525
  grep -v 'lib/phronomy/agent/base.rb' |
533
- grep -v 'lib/phronomy/agent/agent_execution.rb' |
534
- grep -v 'lib/phronomy/persistence/migration/initial_format_migration.rb' || true
526
+ grep -v 'lib/phronomy/agent/agent_execution.rb' || true
535
527
  )"
536
528
  if [[ -n "$legacy_agent_invocation_identity" ]]; then
537
529
  echo "FAIL: active source/RBS reintroduced agent_invocation_id domain identity:" >&2
@@ -35,17 +35,28 @@ contracts and implementations have no Engine dependencies. See the
35
35
 
36
36
  ### P2: LLM
37
37
 
38
+ The LLM contract owns a model turn's inputs, results and validation; its backend
39
+ owns provider construction and translation. The execution client schedules the
40
+ complete synchronous operation through Execution.
41
+
42
+ For example, Agent supplies an `LLMAdapter::Request` to the internal client.
43
+ The selected backend creates its SDK objects inside `perform_complete`, and
44
+ Base validates the returned `LLMAdapter::Response` before Agent consumes it.
45
+
38
46
  - Install the AST analyzer, group annotations, SVG formatter and boundary gate
39
47
  in `tools/architecture/`. The Architecture workflow checks the committed
40
48
  phase and generates evidence for its actual checkout SHA.
41
- - `LLMAdapter::Base` now defines synchronous generation plus chat construction,
42
- configuration, message/tool-call values, identity and optional input budget.
43
- RubyLLM-specific construction and error translation belong to its backend.
44
- Adapter extensions must implement the new operations; no legacy wrapper remains.
49
+ - `LLMAdapter::Base` defines synchronous `complete` and `stream` templates,
50
+ identity and optional input budget. Backend extensions implement protected
51
+ `perform_complete` and `perform_stream`; SDK chat construction, configuration
52
+ and value translation stay private to the backend. The original P2 SPI was
53
+ replaced by [ADR-066](../decisions/066-llm-and-tool-operation-contracts.md)
54
+ and the [unit 6 migration](../migrations/r8-unit6.md).
45
55
  - `LLMAdapter::AsyncClient` owns the internal `complete_async` and `stream_async`
46
56
  operations in `llm_adapter/async/`. It is not a public extension API.
47
- - `LLMAdapter::RubyLLM` lives in `llm_adapter/backends/` and still inherits Base.
48
- Its public name, synchronous signatures and default configuration are unchanged.
57
+ - `LLMAdapter::RubyLLM` lives in `llm_adapter/backends/` and inherits Base.
58
+ Its public constant and default-provider role remain; the current signatures
59
+ use the typed operation contract introduced after the original P2 move.
49
60
  - Zeitwerk collapses these two new directories. Neither `Phronomy::Async` nor
50
61
  `LLMAdapter::Async` / `LLMAdapter::Backends` is introduced.
51
62
  - Agent constructs the framework client around the configured synchronous
@@ -55,39 +66,61 @@ The client preserves `on_full: :raise`, the original pool TaskResult, token
55
66
  forwarding and per-chunk cancellation. Transport timeout/retry stays with the
56
67
  adapter/provider. Construction starts no Runtime, and the default pool is
57
68
  resolved again on each operation; an injected pool stays caller-owned. Only an
58
- internal lightweight sink runs on the worker; application event callbacks
69
+ internal lightweight sink runs on the worker; Agent application event callbacks
59
70
  continue to run on EventLoop.
60
71
 
61
72
  Use `require "phronomy"` and the public constants. The old implementation path
62
73
  `phronomy/llm_adapter/ruby_llm` moves to
63
74
  `phronomy/llm_adapter/backends/ruby_llm`; arbitrary partial-load paths are not the
64
75
  public loading contract. No shim in the contract directory reintroduces an
65
- implementation dependency. No public RBS or Stable/Beta API snapshot changes
66
- are needed in this phase; both are verified unchanged.
76
+ implementation dependency. The original P2 source move left public RBS and the
77
+ Stable/Beta snapshot unchanged. The subsequent unit 6 SPI replacement updates
78
+ both; that historical P2 result is not a promise about the current signatures.
67
79
 
68
80
  ### P3: VectorStore and Embeddings
69
81
 
82
+ Vector and embedding contracts own synchronous operation rules; their clients
83
+ add submission and completion without selecting a provider. Backends implement
84
+ protected hooks behind the inherited public validation templates.
85
+
86
+ For example, `Embeddings::AsyncClient#embed_async` submits `Base#embed`, which
87
+ validates text, calls `perform_embed`, and validates the returned vector. The
88
+ application can use that vector in a separate VectorStore operation.
89
+
70
90
  - `VectorStore::AsyncClient` owns public add/search/remove/clear async operations;
71
- `VectorStore::Embeddings::AsyncClient` owns public `embed_async`.
91
+ `Embeddings::AsyncClient` owns public `embed_async`.
72
92
  - Backends implement only synchronous methods. The old `AsyncBackend` mixin
73
93
  and inherited async methods are removed; application callers change receiver.
74
- - InMemory, Pgvector, RedisSearch and RubyLLMEmbeddings move into `backends/`
75
- directories. Their public constants, synchronous signatures and bodies stay
76
- unchanged. Zeitwerk explicitly collapses the new `async/` and `backends/` paths.
94
+ - InMemory, Pgvector, RedisSearch and RubyLLMEmbeddings use `backends/`
95
+ directories. The original P3 relocation preserved their bodies; subsequent
96
+ [ADR-065](../decisions/065-vector-and-embeddings-common-operations.md) added
97
+ common operation templates and the independent `Embeddings` namespace.
98
+ See the [unit 5 migration](../migrations/r8-unit5.md) for the current SPI.
99
+ Zeitwerk collapses `async/` and `backends/` paths within each feature.
77
100
  - Synchronous RBS uses structural `_CancellationSignal`; async signatures keep
78
101
  TaskResult and the execution token. The public API snapshot records the new
79
102
  receivers and the intentional removals from Base/InMemory.
80
- - All three original backend-to-Engine edges are removed. In the measured view,
81
- M28/M29 join G47 Contracts in B5. M67/M68 are clients in B4 and M71/M72 are
82
- separately grouped implementations. No pending Storage clients are drawn.
103
+ - All three original backend-to-Engine edges are removed. In the current
104
+ annotated view, M28/M83 belong to G47 Contracts in B5. M67/M86 are clients in
105
+ B4 and M71/M87 are separately grouped implementations. The old nested
106
+ Embeddings module IDs are retired; no pending Storage clients are drawn.
83
107
 
84
108
  ### P4: Storage execution
85
109
 
110
+ Raw transaction submission and domain persistence work have different owners.
111
+ The Storage client schedules a backend transaction; a domain execution
112
+ environment schedules the domain's existing operation through Execution.
113
+
114
+ For example, a raw notes write uses `Storage::AsyncClient#transaction_async`.
115
+ An Agent terminal commit instead uses its Agent execution environment and keeps
116
+ commit/readback reconciliation in the Agent operation.
117
+
86
118
  - Public `Storage::AsyncClient#transaction_async` opens the raw backend transaction
87
119
  on a worker and yields its scoped Storage::View. Backends stay synchronous.
88
- - Private `Storage::AsyncClient.submit(pool:)` executes existing domain units
89
- without adding a transaction, timeout or token. All 16 durable submission sites
90
- are recorded in the [execution inventory](storage-execution-boundaries.md).
120
+ - Domain units use their execution environments or `Execution.submit` directly,
121
+ without a Storage forwarding helper or an extra transaction, timeout or token.
122
+ The [execution inventory](storage-execution-boundaries.md) records 14 current
123
+ submission sites in its six source files; it is not a framework-wide count.
91
124
  - M69 is an Async Client and M35 a concrete Storage backend in B4.
92
125
  Existing `Storage::Backends` is not collapsed.
93
126
  - See the [public API and transaction rules](../migrations/storage-async-client.md).
@@ -123,9 +156,26 @@ The recorded graph is not an ideal final r8 diagram.
123
156
  ## Pending phase
124
157
 
125
158
  P5 completes the final cross-repository/API/docs review after application.
159
+ The current candidate aligns public composition, async input declarations and
160
+ active guidance with the implemented responsibilities. It removes the unused
161
+ private Storage submission helper and the obsolete callback-test placeholder.
162
+
163
+ For example, the optional SQL package now obtains its canonical declarations
164
+ through `PersistenceComposition.resources`, then supplies the existing table
165
+ mappings and backend to composition. Agent-only backends use `agent_resources`.
166
+ Neither catalog selects a backend or starts execution.
167
+
168
+ The published 0.34.0 gem does not contain these catalog operations. Matching
169
+ source checkouts can be tested together, but P5 remains pending until a core
170
+ release containing the operations is published, all examples dependencies are
171
+ resolved against that release, and the applied commits pass their CI checks.
172
+ Do not use a private fallback or claim published-gem acceptance from a path
173
+ bundle. `phase.json` records this candidate and its remaining acceptance gates.
174
+
126
175
  All retained P2-P4 responsibilities exist in source; the unnecessary M73 split
127
176
  is superseded by G57 service ownership. The measured SVG still comes from
128
177
  actual Ruby analysis; the target concept is a separate explanatory artifact.
178
+ Completing P5 does not close every r8 pending scope.
129
179
 
130
180
  ## Regenerate and review
131
181
 
@@ -175,7 +175,12 @@ unchanged and acyclic; Ruby+RBS architecture validation passes.
175
175
 
176
176
  ## Static exception inventory
177
177
 
178
- 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.
178
+ The original inventory used Ripper to inspect 339 Ruby files and listed 63
179
+ definitions, including base, private and optional-integration types. The table
180
+ below removes the superseded `SchedulerReentrancyError` entry as part of the
181
+ [cleanup migration](../migrations/cleanup-audit.md). These historical scan totals
182
+ are not a current count of source files or public APIs. Ruby declarations
183
+ establish ownership; RBS declarations are checked at their owning boundaries.
179
184
 
180
185
  | Class | Parent | Declaration |
181
186
  |---|---|---|
@@ -208,7 +213,6 @@ Ripper inspected 339 Ruby files. The following 63 definitions include base, priv
208
213
  | `Phronomy::RecursionLimitError` | `Phronomy::Error` | `lib/phronomy/execution/recursion_limit_error.rb` |
209
214
  | `Phronomy::RuntimeShutdownError` | `Phronomy::Error` | `lib/phronomy/execution/runtime_shutdown_error.rb` |
210
215
  | `Phronomy::RuntimeShutdownReentrancyError` | `Phronomy::RuntimeShutdownError` | `lib/phronomy/execution/runtime_shutdown_reentrancy_error.rb` |
211
- | `Phronomy::SchedulerReentrancyError` | `Phronomy::EventLoopReentrancyError` | `lib/phronomy/execution/scheduler_reentrancy_error.rb` |
212
216
  | `Phronomy::TimeoutError` | `Phronomy::Error` | `lib/phronomy/execution/timeout_error.rb` |
213
217
  | `Phronomy::FilterBlockError` | `Phronomy::Error` | `lib/phronomy/filter/filter_block_error.rb` |
214
218
  | `Phronomy::GeneratorVerifier::UnacceptedResultError` | `Phronomy::Error` | `lib/phronomy/generation/generator_verifier/unaccepted_result_error.rb` |
@@ -1,29 +1,41 @@
1
- # Storage execution units in P4
1
+ # Storage execution boundaries after P4
2
2
 
3
- The following 16 submission sites delegate to internal
4
- `Storage::AsyncClient.submit(pool:)`. Only submission ownership changes: their
5
- blocks, result callbacks, domain transactions and error/reconciliation policy
6
- remain in their original owners. Each submitted unit still uses the exact
7
- pool selected by the owner, with `on_full: :raise` and no new timeout/token.
3
+ Domain owners schedule their persistence work through Execution and retain the
4
+ transaction, result application and uncertain-outcome policy. The raw Storage
5
+ client separately schedules an application-supplied backend transaction.
8
6
 
9
- | Owner / source under `lib/phronomy/` | Unit | Result application |
7
+ For example, an Agent terminal outcome is submitted through its execution
8
+ environment and committed by the Agent operation. The operation decides whether
9
+ an uncertain response requires readback. Storage does not wrap that operation in
10
+ another transaction or decide that the commit succeeded.
11
+
12
+ The following inventory contains 14 submission calls in six source files. It
13
+ does not count every durable operation in the framework. The former separate
14
+ Provider/Tool dispatch reconciliation submissions are absent; Agent change
15
+ reconciliation belongs to `ExecutionChange#perform_once`.
16
+
17
+ | Owner / source under `lib/phronomy/` | Unit | Submission receiver / result application |
10
18
  |---|---|---|
11
- | `agent/execution/execution_coordinator.rb` | Provider dispatch preparation | ProviderDispatchPreparationReady on EventLoop |
12
- | same | Tool dispatch preparation | ToolDispatchPreparationReady on EventLoop |
13
- | same | Uncertain Provider dispatch reconciliation | ProviderDispatchPreparationReconciliationReady |
14
- | same | Uncertain Tool dispatch reconciliation | ToolDispatchPreparationReconciliationReady |
15
- | same | Initial invocation preparation | InitialPreparationReady |
16
- | same | Recovery of initial preparation | InitialPreparationRecoveryReady |
17
- | same | Approval resume commit | ResumeCommitReady; existing admission handling |
18
- | same | Terminal outcome commit | TerminalCommitReady; existing save/readback and live-state policy |
19
- | `agent/execution/exact_execution.rb` | Exact execution read, recovery and materialization | Original observer completion / owner installation |
20
- | same | Exact execution reconciliation and result materialization | Original observer completion |
21
- | `agent/recovery/recovery_coordinator/resolution.rb` | Resolution preparation, save/readback and materialization | ResolveReady; validate before applying live state |
22
- | `workflow/execution/workflow_runner.rb` | Durable snapshot load | Original load-ready command |
23
- | same | Terminal snapshot save and uncertain-result readback | Original terminal persistence delivery |
24
- | `multi_agent/durable_subagent_coordinator.rb` | Reserved child load/create/recovery and input materialization | Original exact child execution observer |
25
- | `multi_agent/team_coordinator.rb` | External cancellation's durable transition | Existing cancellation/readback policy |
26
- | same | Durable Team Tool operation and reconciliation | Original Tool completion/error policy |
19
+ | `agent/execution/execution_coordinator.rb` | Provider dispatch preparation | Agent environment; ProviderDispatchPreparationReady |
20
+ | same | Tool dispatch preparation | Agent environment; ToolDispatchPreparationReady |
21
+ | same | Initial invocation preparation | Agent environment; InitialPreparationReady |
22
+ | same | Recovery of initial preparation | Agent environment; InitialPreparationRecoveryReady |
23
+ | same | Approval resume commit | Agent environment; ResumeCommitReady and admission handling |
24
+ | same | Terminal outcome commit | Agent environment; TerminalCommitReady and commit/readback policy |
25
+ | `agent/execution/exact_execution.rb` | Exact execution read, recovery and materialization | Agent environment; observer completion / owner installation |
26
+ | same | Exact execution reconciliation and result materialization | Agent environment; observer completion |
27
+ | `agent/recovery/recovery_coordinator/resolution.rb` | Resolution preparation, save/readback and materialization | Agent environment; ResolveReady before live-state application |
28
+ | `workflow/execution/workflow_runner.rb` | Durable snapshot load | Workflow environment; load-ready command |
29
+ | same | Terminal snapshot save and uncertain-result readback | Workflow environment; terminal persistence delivery |
30
+ | `multi_agent/durable_subagent_coordinator.rb` | Reserved child load/create/recovery and input materialization | `Execution.submit`; exact child execution observer |
31
+ | `multi_agent/team_coordinator.rb` | External cancellation's durable transition | MultiAgent environment; cancellation/readback policy |
32
+ | same | Durable Team Tool operation and reconciliation | `Execution.submit`; Tool completion/error policy |
33
+
34
+ Every listed call uses `on_full: :raise` without adding a submission timeout or
35
+ cancellation token. An execution environment forwards its owning Runtime to
36
+ Execution; the Engine binding selects that Runtime's pool. Direct submissions
37
+ use the configured Execution binding. The unused private
38
+ `Storage::AsyncClient.submit` forwarding helper is removed.
27
39
 
28
40
  The three MultiAgent sites are included because they perform the same kind of
29
41
  durable work as Agent and Workflow. They do not introduce a new shared domain
@@ -31,6 +43,14 @@ transaction or move Team rules into Storage.
31
43
 
32
44
  ## Boundaries deliberately retained
33
45
 
46
+ An execution boundary follows the operation's owner, rather than whether the
47
+ operation happens to perform I/O. Domain-specific callbacks and failure policies
48
+ therefore remain outside the raw transaction client.
49
+
50
+ For example, Tool authorization and an Agent approval listener both run work
51
+ asynchronously, but neither becomes a Storage transaction merely because a
52
+ Tool or listener may consult a database.
53
+
34
54
  | Existing boundary | Reason |
35
55
  |---|---|
36
56
  | Agent approval listener dispatch | Application callback; not a storage operation |
@@ -40,12 +60,12 @@ transaction or move Team rules into Storage.
40
60
  | MCP cleanup pool | Transport cleanup, not storage |
41
61
  | Synchronous Agent load/create, domain repository methods and recovery helpers | Stay synchronous; their existing callers own the offload boundary |
42
62
 
43
- Internal submit does not call `backend.transaction`. Public
44
- `Storage::AsyncClient#transaction_async` opens exactly one outer raw transaction
45
- on the worker and yields its view. They are separate entry points because a
46
- durable domain unit may already have transactions, reconciliation reads and
47
- materialization in a defined order. Adding an outer transaction would change
48
- that order's commit visibility, connection lifetime and uncertain-result behavior.
63
+ Domain submission adds no `backend.transaction` call. Public
64
+ `Storage::AsyncClient#transaction_async` opens one raw transaction on the worker
65
+ and yields its view. A durable domain unit may already contain transactions,
66
+ reconciliation reads and materialization in a defined order. An extra outer
67
+ transaction would change commit visibility, connection lifetime and
68
+ uncertain-result behavior.
49
69
 
50
70
  Runtime tests cover original TaskResult identity, single submission, rollback,
51
71
  nested savepoints, scope lifetime, cancellation/timeout and preserved failures.
@@ -173,10 +173,9 @@ Normal low-quality output follows the configured evaluation loop as before.
173
173
 
174
174
  `Result#failure` is nil except for output_failed, where it carries the owned error
175
175
  diagnostic (without raw_output). Hash/JSON round trips, equality, hashing and freeze
176
- include it. `Result.from_h` requires every new field; migrate old saved Result JSON
177
- explicitly with `scripts/migrate_generator_verifier_result.rb OLD.json NEW.json`.
178
- The script adds failure=nil, validates the result and creates a new file. It does
179
- not overwrite the source or silently alter invalid data. `raise_if_unaccepted`
176
+ include it. `Result.from_h` requires every field, including `failure: nil` for
177
+ results without an output failure. It rejects incomplete serialized results.
178
+ `raise_if_unaccepted`
180
179
  retains the Result and the original OutputError cause in the same process.
181
180
 
182
181
  ## Symmetric lifetime rules
@@ -61,11 +61,12 @@ Tool-role messages are one indivisible conversation group. When the selected
61
61
  Plan is realized, the Manifest records the Framework conversation-group identity
62
62
  and classifies canonical Tool exchanges as `tool_exchanges` for Handoff.
63
63
 
64
- `HandoffProjection` groups current-format Manifest segments by that conversation
65
- group identity. It may still read legacy `selection_unit_id` metadata from a
66
- finalized pre-ACS-04 Manifest, but new Context assembly does not recreate
67
- `Selection::Unit`. `Selection::Candidate` and `Selection::Constraint` remain
68
- internal Context-input normalization details only.
64
+ The current `Agent::TransferProjection` groups Manifest segments by that
65
+ conversation-group identity. Segments without a group identity are projected
66
+ independently. Historical selection-unit identifiers and kinds are no longer
67
+ interpreted, and Context assembly does not recreate `Selection::Unit`.
68
+ `Selection::Candidate` and `Selection::Constraint` remain internal Context-input
69
+ normalization details only.
69
70
 
70
71
  Handoff Policy answers what may cross the Agent boundary. Target Context Policy
71
72
  remains the final authority for what enters each Target LLM call. Transferred
@@ -2,7 +2,13 @@
2
2
 
3
3
  ## Status
4
4
 
5
- Accepted
5
+ Accepted; the SDK-shaped input and materialization provisions below are
6
+ superseded by [ADR-066](066-llm-and-tool-operation-contracts.md). The synchronous
7
+ provider boundary, default RubyLLM integration and provider-owned transport
8
+ policy remain. For example, current adapters receive `LLMAdapter::Request`
9
+ values and implement protected operation hooks; they no longer receive an
10
+ Agent-constructed SDK chat. The materializer description below records the
11
+ earlier boundary rather than the current extension SPI.
6
12
 
7
13
  ## Context
8
14
 
@@ -11,6 +11,15 @@ ContentStore's classification and directory split are superseded by
11
11
  Storage, outside Backend Contracts and Backend Implementations. The other
12
12
  contract/client/backend separations remain in force.
13
13
 
14
+ Later contracts refine the client connection and LLM extension points without
15
+ merging their responsibilities. [r8 unit 1](../architecture/r8-unit1.md) places
16
+ submission behind Execution, and
17
+ [ADR-066](066-llm-and-tool-operation-contracts.md) replaces the SDK-shaped LLM
18
+ SPI with typed model-turn operations. For example, the LLM client submits a
19
+ Request through Execution; the backend constructs its SDK chat inside a protected
20
+ hook. Earlier claims about unchanged P2 signatures and RubyLLMMaterializer
21
+ below are historical and do not define the current SPI.
22
+
14
23
  ## Context
15
24
 
16
25
  The synchronous LLMAdapter SPI and its RubyLLM implementation shared a directory
@@ -35,8 +44,10 @@ Numbered diagram bands also implied an ordering between independent concerns.
35
44
  collapse to retain feature namespaces. Do not make a common Async namespace,
36
45
  add a Base-to-client factory, or install an include/prepend compatibility hook.
37
46
  4. Implementations depend on Contracts. Contracts and implementations do not
38
- reference Engine or clients; clients use Contracts and Engine through normal
39
- constant references or object injection, without selecting concrete providers.
47
+ reference Engine or clients. Under the current Execution amendment, clients
48
+ use Backend and Execution contracts without directly referencing Engine or
49
+ selecting concrete providers. Engine implements the execution mechanism
50
+ chosen by composition.
40
51
  5. Preserve original TaskResult, non-waiting admission failure, token semantics,
41
52
  no additional operation timeout, provider-owned retries and EventLoop callback
42
53
  delivery. Resolve the default pool at operation time; do not cache it across
@@ -51,8 +62,9 @@ The vector/embedding SPI and namespace clauses are amended by
51
62
  ## Consequences
52
63
 
53
64
  This supersedes the remaining LLM Base-to-Runtime coupling described in ADR-040.
54
- ADR-027's synchronous public provider-call boundary and materialization caveat
55
- still apply: this change does not make RubyLLMMaterializer provider-neutral.
65
+ The original P2 change retained ADR-027's synchronous provider-call boundary and
66
+ its then-SDK-shaped materialization caveat. ADR-066 later replaced that
67
+ materialization and extension SPI; the synchronous provider boundary remains.
56
68
  P2 keeps the LLM client internal. P3 introduces public VectorStore/Embeddings
57
69
  AsyncClients and moves async receivers off the synchronous backends. Their
58
70
  argument conventions and execution semantics are unchanged; the receiver