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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +104 -0
- data/CONTRIBUTING.md +5 -5
- data/README.md +17 -2
- data/RELEASE_CHECKLIST.md +3 -1
- data/SECURITY.md +1 -1
- data/VERIFY.sh +1 -9
- data/docs/architecture/backend-groups.md +69 -19
- data/docs/architecture/error-api-review.md +6 -2
- data/docs/architecture/storage-execution-boundaries.md +49 -29
- data/docs/architecture/structured-output-and-scope.md +3 -4
- data/docs/decisions/016-semantic-multi-agent-handoff.md +6 -5
- data/docs/decisions/027-llm-adapter-provider-boundary.md +7 -1
- data/docs/decisions/059-backend-contracts-and-async-clients.md +16 -4
- data/docs/features.md +4 -3
- data/docs/migrations/cleanup-audit.md +89 -0
- data/docs/migrations/legacy-format-removal.md +55 -0
- data/docs/migrations/r8-unit6.md +4 -2
- data/docs/migrations/storage-async-client.md +47 -17
- data/docs/migrations/vector-async-clients.md +24 -10
- data/docs/persistence-backends.md +50 -5
- data/docs/shared-state-sharing.md +14 -4
- data/lib/phronomy/agent/execution/agent_invocation.rb +0 -4
- data/lib/phronomy/agent/handoff/transfer_projection.rb +0 -9
- data/lib/phronomy/agent/journal/journal_record.rb +2 -2
- data/lib/phronomy/agent/recovery/recovery_rules.rb +0 -12
- data/lib/phronomy/agent/store.rb +3 -8
- data/lib/phronomy/agent/tool_execution/tool_invocation.rb +0 -3
- data/lib/phronomy/context/context_policy.rb +3 -7
- data/lib/phronomy/context/llm_input_manifest.rb +3 -3
- data/lib/phronomy/engine/runtime/shutdown_result.rb +0 -5
- data/lib/phronomy/execution/execution.rb +0 -11
- data/lib/phronomy/multi_agent/shared_state.rb +5 -8
- data/lib/phronomy/persistence/content_repository.rb +2 -1
- data/lib/phronomy/persistence_composition/stores.rb +14 -2
- data/lib/phronomy/storage/async/async_client.rb +0 -12
- data/lib/phronomy/vector_store/async/async_client.rb +3 -3
- data/lib/phronomy/version.rb +1 -1
- data/scripts/api_snapshot.rb +2 -2
- data/sig/phronomy/persistence_composition.rbs +2 -0
- data/sig/phronomy/vector_store/async/async_client.rbs +2 -2
- metadata +4 -11
- data/lib/phronomy/execution/scheduler_reentrancy_error.rb +0 -9
- data/lib/phronomy/persistence/migration/initial_format_migration.rb +0 -226
- data/scripts/add_to_h_to_token_doubles.rb +0 -33
- data/scripts/add_to_h_unnamed_doubles.rb +0 -27
- data/scripts/migrate_generator_verifier_result.rb +0 -18
- data/scripts/migrate_spec_agent_definition.rb +0 -108
- data/scripts/migrate_spec_agent_definition_pass2.rb +0 -53
- data/scripts/migrate_spec_inline_pass3.rb +0 -24
- data/sig/phronomy/persistence/migration.rbs +0 -13
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 6d22c5161612ef11e4a4facc21f6f0de5a92cd7c79c5c4b810dc048675a3ae9a
|
|
4
|
+
data.tar.gz: 04cb167dc080f27262634e9e33fe5668ddd9b125bbb6e3345d8ec6e5c2cd7f11
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
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.
|
|
41
|
-
The
|
|
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
|
-
- [ ]
|
|
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
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`
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
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
|
|
48
|
-
Its public
|
|
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.
|
|
66
|
-
|
|
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
|
-
`
|
|
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
|
|
75
|
-
directories.
|
|
76
|
-
|
|
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
|
|
81
|
-
M28/
|
|
82
|
-
separately grouped implementations.
|
|
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
|
-
-
|
|
89
|
-
without
|
|
90
|
-
|
|
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
|
-
|
|
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
|
|
1
|
+
# Storage execution boundaries after P4
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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
|
-
|
|
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 |
|
|
12
|
-
| same | Tool dispatch preparation |
|
|
13
|
-
| same |
|
|
14
|
-
| same |
|
|
15
|
-
| same |
|
|
16
|
-
| same |
|
|
17
|
-
|
|
|
18
|
-
| same |
|
|
19
|
-
| `agent/
|
|
20
|
-
|
|
|
21
|
-
|
|
|
22
|
-
| `
|
|
23
|
-
|
|
|
24
|
-
|
|
|
25
|
-
|
|
26
|
-
|
|
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
|
-
|
|
44
|
-
`Storage::AsyncClient#transaction_async` opens
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
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
|
|
177
|
-
|
|
178
|
-
|
|
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
|
-
`
|
|
65
|
-
group identity.
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
internal Context-input
|
|
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
|
|
39
|
-
|
|
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
|
|
55
|
-
|
|
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
|