phronomy 0.34.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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 4c67e91b9abb65c5ab2ddc5b657afa6843b916a5ba84aefcd8f808ae297c3236
4
- data.tar.gz: b5894936fa47d493da81c650edbf3c330eaeec7101c68ec91acf96bec00d1a79
3
+ metadata.gz: 6d22c5161612ef11e4a4facc21f6f0de5a92cd7c79c5c4b810dc048675a3ae9a
4
+ data.tar.gz: 04cb167dc080f27262634e9e33fe5668ddd9b125bbb6e3345d8ec6e5c2cd7f11
5
5
  SHA512:
6
- metadata.gz: ebec13bc657697922f3f487eefe809a35570b36a574e8a3ea95d5124459035ca263ad39b89419e8042621e4971f550cbb7d21ab206d2961f8a7f01bec6b9514e
7
- data.tar.gz: b1d930edb100e7782522a9d666d555756fcc50e5be46881c58c035f2e021631093132b4bde4cec8134f296f068ddb9cb0fd17548ea356afad32652d484b7da91
6
+ metadata.gz: 64fff83cad837875f1c8682e917377723bedec10ea1bcafcb3aed14f78617e3e29c80ff8327b1242ae47da8e9c0628bb42549aeb1d4021c09af75aab53ed3b64
7
+ data.tar.gz: 169a3f9bb47b4fdf5004ff5731c8fd95d3c0f949d46f99fdff6a67aa8de80b4efe07ba523c132b0f0bcf5831c255b722afff28777a74a93be457db10d8ba6980
data/CHANGELOG.md CHANGED
@@ -12,6 +12,48 @@ 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
+
15
57
  ## [0.34.0] - 2026-11-16
16
58
 
17
59
  ### Changed
data/README.md CHANGED
@@ -37,7 +37,8 @@ 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.34.0.
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.
41
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.
@@ -55,6 +56,7 @@ the current saved representation.
55
56
 
56
57
  | API | Stability | Contract |
57
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) |
58
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) |
59
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) |
60
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) |
data/SECURITY.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  | Version | Supported |
6
6
  |---------|-----------|
7
- | 0.34.0 (latest release) | ✅ |
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
@@ -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
 
@@ -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.
@@ -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
data/docs/features.md CHANGED
@@ -55,8 +55,9 @@ rather than implicitly inheriting the parent revision. The Stable
55
55
  | **Knowledge** — Journal-backed persistent Agent context registered with `knowledge:` / `add_knowledge`, selected per LLM call by Context Policy | Beta |
56
56
  | **`VectorStore#size`** — Document count for InMemory, RedisSearch, and Pgvector backends | Beta |
57
57
  | **Storage::AsyncClient** — `transaction_async` runs a raw backend transaction on one worker and returns TaskResult; [usage and lifetime rules](migrations/storage-async-client.md) | Beta |
58
+ | **PersistenceComposition resource catalogs** — Unreleased `resources` / `agent_resources` expose canonical frozen declarations for full or Agent-only backend construction; [ownership and example](persistence-backends.md#supplying-a-backend-catalog) | Beta |
58
59
  | **VectorStore::AsyncClient** — `add_async` / `search_async` / `remove_async` / `clear_async` offload the synchronous Backend SPI through Phronomy and return `TaskResult`; native async override is not part of the current Backend SPI | Beta |
59
- | **VectorStore::Embeddings::AsyncClient** — `embed_async` offloads synchronous `embed` through Phronomy and returns `TaskResult` | Beta |
60
+ | **Embeddings::AsyncClient** — `embed_async` offloads synchronous `embed` through Phronomy and returns `TaskResult` | Beta |
60
61
  | **Model Context Protocol (MCP) Tool** — `Phronomy::Tools::Mcp` integration through the official `mcp` gem | Beta |
61
62
  | **Agent Tool** — `Phronomy::Tools::Agent.from_agent` exposes a child Agent as a Tool without occupying a worker while waiting | Beta |
62
63
  | **Ordered event delivery** — Explicitly require `Phronomy::Integrations::OrderedEventDelivery` for bounded ordered delivery outside lifecycle callbacks; [lifetime and failure rules](ordered-event-delivery.md) | Beta |
@@ -1,15 +1,29 @@
1
1
  # Storage asynchronous execution and ContentStore ownership
2
2
 
3
- P4 adds the public Beta `Phronomy::Storage::AsyncClient`. Synchronous storage
4
- backends and `Persistence#transaction` keep their existing interfaces. Backend
5
- authors implement no scheduler or async methods.
3
+ Storage execution schedules raw transactions without taking ownership of domain
4
+ persistence rules. The public Beta `Phronomy::Storage::AsyncClient` introduced
5
+ in P4 wraps a synchronous backend; domain stores retain their own operations.
6
+
7
+ For example, an application can write a raw notes resource with this client.
8
+ An Agent instead uses its domain store, whose transaction participates through
9
+ the neutral `Persistence#atomic` coordinator. Backend authors implement no
10
+ scheduler or asynchronous methods.
6
11
 
7
12
  ## Public transaction API
8
13
 
14
+ The client schedules one backend transaction and returns its completion handle.
15
+ The transaction block receives a raw Storage view valid only for that scope.
16
+
17
+ For example, with `stores = PersistenceComposition.in_memory`, construct the
18
+ client around `stores.coordinator.backend`. Pass `stores.agent` to Agent,
19
+ `stores.multi_agent` to MultiAgent, and `stores.workflow` to Workflow. These
20
+ domain components are distinct from the raw backend and coordinator.
21
+
9
22
  Construct `Storage::AsyncClient.new(backend: raw_backend, pool: nil)` around a
10
- Storage SPI 2 backend. For an existing Persistence facade, use
11
- `persistence.backend`. The transaction block receives a **raw Storage::View**,
12
- not the domain repositories yielded by `Persistence#transaction`.
23
+ Storage SPI 2 backend. The block receives a **raw Storage::View**.
24
+ `stores.coordinator.atomic` instead yields a shared participation scope;
25
+ `stores.agent.transaction` and `stores.multi_agent.transaction` yield their
26
+ domain-owned records and scope. There is no coordinator `transaction` facade.
13
27
 
14
28
  `transaction_async(cancellation_token: nil, timeout: nil) { |view| ... }`
15
29
  returns the pool's original TaskResult. The complete transaction runs on one
@@ -20,8 +34,9 @@ savepoint behavior.
20
34
 
21
35
  ### Complete offline example
22
36
 
23
- This requires a checkout containing P4; the previously released 0.27.0 gem does
24
- not contain the new client. It uses only the public raw storage contract.
37
+ An application owns its resource declarations and chooses its backend. This
38
+ example saves a note in a custom resource and receives its payload after commit,
39
+ using only the public raw storage contract.
25
40
 
26
41
  ```ruby runnable
27
42
  require "phronomy"
@@ -54,6 +69,13 @@ backend rules; no new transaction implementation is introduced.
54
69
 
55
70
  ## Admission, cancellation and ownership
56
71
 
72
+ Admission and completion govern the submitted operation, while the backend owns
73
+ the physical transaction. A settled timeout or cancellation does not establish
74
+ whether a transaction that already started eventually committed.
75
+
76
+ For example, a notes write may outlive its TaskResult timeout and still commit.
77
+ The application must inspect durable state before retrying an uncertain write.
78
+
57
79
  Construction starts no Runtime. Each call resolves the current default pool,
58
80
  unless an explicit caller-owned `pool:` was supplied. Runtime reset does not
59
81
  transfer ownership of an injected pool.
@@ -68,16 +90,16 @@ outcome must reconcile through their domain's identities and stored state.
68
90
 
69
91
  ## Existing Agent, Workflow and coordination operations
70
92
 
71
- Internal `Storage::AsyncClient.submit(pool:)` accepts an existing synchronous
72
- storage unit. This is private framework API, not an application extension API.
73
- It submits exactly once and adds no transaction, token, or timeout. This lets
74
- domain operations preserve their own transaction and reconciliation boundaries.
75
- See the [operation inventory](../architecture/storage-execution-boundaries.md).
93
+ Domain execution schedules complete persistence operations while each operation
94
+ retains its transaction and reconciliation policy. Agent, Workflow and MultiAgent
95
+ use their execution environments or `Execution.submit`, not a Storage forwarding
96
+ helper. Submission adds no transaction, token or timeout.
76
97
 
77
- In particular, a Workflow runner may have only an injected repository rather
78
- than access to its raw backend. Internal submit therefore accepts a callable
79
- and the owner's pool; it does not require a dummy backend or a Persistence
80
- facade. Public transaction_async requires a real SPI 2 backend.
98
+ For example, Workflow terminal persistence saves its snapshot and reads back an
99
+ uncertain response within its own operation. A Workflow runner needs its injected
100
+ repository and execution environment; it does not need a dummy raw backend to
101
+ submit that operation. See the 14-site
102
+ [operation inventory](../architecture/storage-execution-boundaries.md).
81
103
 
82
104
  Durable commit/readback policy, admission release, callback delivery and the
83
105
  application of results to live state remain with Agent/Workflow/MultiAgent.
@@ -87,6 +109,14 @@ execution boundaries.
87
109
 
88
110
  ## ContentStore path and diagram
89
111
 
112
+ Content management owns canonical bytes, content identity and integrity over
113
+ neutral Storage. The service does not select a physical backend or introduce
114
+ another execution client.
115
+
116
+ For example, StoredContents writes canonical JSON through a supplied blob view;
117
+ the Persistence content adapter translates known storage failures for its domain
118
+ caller. Neither operation creates a new worker or chooses a database.
119
+
90
120
  P4 originally moved `ContentStore::StoredContents` into
91
121
  `content_store/backends/stored_contents.rb`. [ADR-062](../decisions/062-content-store-service.md)
92
122
  supersedes that split: the implementation now lives at
@@ -1,8 +1,12 @@
1
1
  # VectorStore and Embeddings: asynchronous client migration
2
2
 
3
- This unreleased P3 change moves the Beta asynchronous API to explicit clients.
4
- It changes the receiver used by callers. Backend authors continue to implement
5
- only synchronous methods; method arguments and results remain unchanged.
3
+ The P3 migration separated asynchronous submission from synchronous backend
4
+ operations. Current applications call explicit Beta clients, while backend
5
+ authors implement protected synchronous hooks behind the common templates.
6
+
7
+ For example, an application calls `async_store.search_async` to schedule the same
8
+ public search operation that `store.search` performs synchronously. The current
9
+ namespace and hook SPI also include the later [unit 5 migration](r8-unit5.md).
6
10
 
7
11
  | Previous receiver | New receiver |
8
12
  |---|---|
@@ -13,7 +17,7 @@ only synchronous methods; method arguments and results remain unchanged.
13
17
  | `embeddings.embed_async(text, token, timeout: seconds)` | `async_embeddings.embed_async(text, token, timeout: seconds)` |
14
18
 
15
19
  Construct the clients with `VectorStore::AsyncClient.new(backend: store)` and
16
- `VectorStore::Embeddings::AsyncClient.new(adapter: embeddings)`. The embedding
20
+ `Embeddings::AsyncClient.new(adapter: embeddings)`. The embedding
17
21
  cancellation token stays positional. Synchronous `add`, `search`, `remove`,
18
22
  `clear`, `size` and `embed` stay on the existing backend objects.
19
23
 
@@ -27,8 +31,10 @@ The clients are public Beta API; their `async/` directories do not introduce
27
31
 
28
32
  This example uses an intentionally simple local embedding adapter to demonstrate
29
33
  the API. It needs no provider key, network request, or database server. The
30
- implementation supplies only `embed`; Phronomy supplies asynchronous execution.
31
- Run it against a checkout containing P3, not the previously released 0.27.0 gem.
34
+ implementation supplies protected `perform_embed`; the inherited public `embed`
35
+ validates input and result, and Phronomy supplies asynchronous execution. The
36
+ example uses the current unit 5 namespace and extension SPI, which supersede
37
+ the original P3 adapter names.
32
38
 
33
39
  ```ruby runnable
34
40
  require "phronomy"
@@ -95,14 +101,17 @@ minimal synchronous signal for an async operation's full token.
95
101
 
96
102
  ## Source ownership
97
103
 
98
- The public class names below are unchanged. Their implementation files move:
104
+ Concrete implementations remain separate from their common operation contracts.
105
+ For example, a vector store keeps its algorithm in `vector_store/backends/`,
106
+ while an embedding provider lives in the independent `embeddings/backends/`
107
+ directory introduced by the [unit 5 migration](r8-unit5.md).
99
108
 
100
- | Public class | New path under `lib/phronomy/` |
109
+ | Current public class | Path under `lib/phronomy/` |
101
110
  |---|---|
102
111
  | `VectorStore::InMemory` | `vector_store/backends/in_memory.rb` |
103
112
  | `VectorStore::Pgvector` | `vector_store/backends/pgvector.rb` |
104
113
  | `VectorStore::RedisSearch` | `vector_store/backends/redis_search.rb` |
105
- | `VectorStore::Embeddings::RubyLLMEmbeddings` | `embeddings/backends/ruby_llm_embeddings.rb` |
114
+ | `Embeddings::RubyLLMEmbeddings` | `embeddings/backends/ruby_llm_embeddings.rb` |
106
115
 
107
116
  Use `require "phronomy"` and the public constants. Direct partial-load paths are
108
117
  not the public loading contract; no require shim is kept in the contract
@@ -3,7 +3,7 @@
3
3
  [ADR-058](decisions/058-neutral-storage-primitives.md) defines the current
4
4
  extension contract. This is an intentional breaking replacement of the old
5
5
  fixed-repository Backend SPI. Application construction now uses
6
- `PersistenceComposition.build(backend:)` or `.in_memory`; pass its `agent`, `team`,
6
+ `PersistenceComposition.build(backend:)` or `.in_memory`; pass its `agent`, `multi_agent`,
7
7
  or `workflow` component to that domain. `Persistence.new(backend:)` provides only
8
8
  the neutral coordinator. The old eight-repository facade and its queries were
9
9
  removed; see [r8 unit 3](architecture/r8-unit3.md).
@@ -15,8 +15,13 @@ Storage owns `Resource`, `Backend`, `View`, `Records`, `Streams`, `Blobs`, immut
15
15
  record types, active-execution policy, content digest algorithm or watermark API.
16
16
 
17
17
  Agent, Team, Workflow and ContentStore declare their own resource schemas.
18
- `PersistenceComposition::StorageSchema` gathers those declarations and
19
- `PersistenceComposition` binds domain record adapters to one coordinator.
18
+ Composition supplies those canonical declarations to a backend and binds domain
19
+ record adapters to one coordinator. Applications select the physical driver;
20
+ the driver does not recreate domain schemas.
21
+
22
+ For example, a custom SQL driver receives the composition catalog before
23
+ `PersistenceComposition.build(backend:)` constructs `stores.agent`,
24
+ `stores.multi_agent` and `stores.workflow` over its shared coordinator.
20
25
  Team and Workflow schemas live in their existing `persistence/` implementation
21
26
  directories. An isolated Agent uses `PersistenceComposition.agent` and does not
22
27
  construct Team or Workflow stores.
@@ -25,13 +30,53 @@ The Agent-owned `Watermark` composes guarded revision and stream-head conditions
25
30
 
26
31
  InMemory receives `resources:` and supplies one Monitor/snapshot transaction
27
32
  across the catalog. SQL reference composition supplies the same catalog and a
28
- separate physical table/column mapping to the neutral driver in examples
29
- `shared/storage`. Table names, columns, indexes, DurableRecord envelopes, payloads,
33
+ separate physical table/column mapping to the optional examples package at
34
+ `packages/phronomy-active_record/lib/phronomy/active_record/storage/`.
35
+ Table names, columns, indexes, DurableRecord envelopes, payloads,
30
36
  format versions and content identities remain unchanged.
31
37
 
32
38
  The [S3 closure review](architecture/refactoring-closure.md) records why these
33
39
  names and placements remain and separates applied evidence from the candidate.
34
40
 
41
+ ### Supplying a backend catalog
42
+
43
+ The composition catalog lets an external backend use domain-owned resource
44
+ declarations through a public operation. Each accessor returns a frozen Array
45
+ containing the canonical immutable Resource objects; it does not construct a
46
+ backend, open a database, create domain stores or start Runtime. These Beta
47
+ accessors are Unreleased and are not present in the published 0.34.0 gem.
48
+
49
+ For example, an application selecting a full InMemory backend passes the public
50
+ catalog to that backend, then composes its domain stores. An Agent-only
51
+ application requests only Agent and content declarations, avoiding Team and
52
+ Workflow schema loading.
53
+
54
+ ```ruby runnable
55
+ require "phronomy"
56
+
57
+ resources = Phronomy::PersistenceComposition.resources
58
+ backend = Phronomy::Storage::Backends::InMemory.new(resources: resources)
59
+ stores = Phronomy::PersistenceComposition.build(backend: backend)
60
+ raise "backend changed" unless stores.coordinator.backend.equal?(backend)
61
+
62
+ agent_resources = Phronomy::PersistenceComposition.agent_resources
63
+ agent_backend = Phronomy::Storage::Backends::InMemory.new(resources: agent_resources)
64
+ agent_store = Phronomy::PersistenceComposition.agent(backend: agent_backend)
65
+ raise "agent backend changed" unless agent_store.coordinator.backend.equal?(agent_backend)
66
+ raise "mutable catalog" unless resources.frozen? && agent_resources.frozen?
67
+ ```
68
+
69
+ | Construction scope | Public catalog | Composition operation |
70
+ |---|---|---|
71
+ | Agent, MultiAgent, Workflow and content | `PersistenceComposition.resources` | `.build(backend:)` |
72
+ | Agent and content only | `PersistenceComposition.agent_resources` | `.agent(backend:)` |
73
+
74
+ Use the returned Resource objects rather than rebuilding equivalent declarations:
75
+ Storage validates resource identity as well as registration. The internal
76
+ `PersistenceComposition::StorageSchema` remains private. Database/table mappings,
77
+ connection configuration and schema installation stay with the external package
78
+ and application deployment.
79
+
35
80
  ## Backend and View
36
81
 
37
82
  ```ruby
@@ -3,7 +3,8 @@
3
3
  module Phronomy
4
4
  class Persistence
5
5
  # Domain-facing content access uses the Persistence failure vocabulary.
6
- # ContentStore implementations retain their independent backend contract.
6
+ # ContentStore remains a content service over neutral Storage; this facade
7
+ # translates known Storage failures without selecting a physical backend.
7
8
  # @api private
8
9
  class ContentRepository < Phronomy::ContentStore::Base
9
10
  def initialize(store)
@@ -6,10 +6,22 @@ module Phronomy
6
6
  # Pass only the corresponding domain store to each domain's API.
7
7
  Stores = Data.define(:coordinator, :agent, :multi_agent, :workflow)
8
8
 
9
+ # Canonical declarations for a backend supplied to .build. This frozen list
10
+ # preserves Resource identity without constructing stores, a backend or Runtime.
11
+ # @return [Array<Storage::Resource>] the complete domain and content catalog
12
+ # @api public
13
+ def self.resources = StorageSchema.resources
14
+
15
+ # Canonical declarations for a backend supplied to .agent. This frozen list
16
+ # includes Agent and content resources without loading Team or Workflow schemas.
17
+ # @return [Array<Storage::Resource>] the Agent and content catalog
18
+ # @api public
19
+ def self.agent_resources = StorageSchema.agent_resources
20
+
9
21
  # An ordinary Agent needs only its own records and content. Do not load or
10
22
  # instantiate Team/Workflow implementations merely to construct an Agent.
11
23
  def self.agent(backend: nil)
12
- resources = StorageSchema.agent_resources
24
+ resources = agent_resources
13
25
  backend ||= Phronomy::Storage::Backends::InMemory.new(resources: resources)
14
26
  coordinator = Phronomy::Persistence.new(backend: backend)
15
27
  Phronomy::Persistence::StorageBoundary.call do
@@ -28,7 +40,7 @@ module Phronomy
28
40
  end
29
41
 
30
42
  def self.in_memory
31
- build(backend: Phronomy::Storage::Backends::InMemory.new(resources: StorageSchema.resources))
43
+ build(backend: Phronomy::Storage::Backends::InMemory.new(resources: resources))
32
44
  end
33
45
  end
34
46
  end
@@ -38,18 +38,6 @@ module Phronomy
38
38
  end
39
39
  end
40
40
 
41
- # Submit an existing domain-owned synchronous storage unit unchanged.
42
- # It may already open transactions or perform reads/reconciliation. Do not
43
- # add a transaction, timeout or cancellation condition around that unit.
44
- # The owner supplies its current runtime's pool and applies the result.
45
- #
46
- # @api private
47
- def self.submit(pool:, &operation)
48
- raise ArgumentError, "storage submit requires a block" unless operation
49
-
50
- Phronomy::Execution.submit(pool: pool, on_full: :raise, &operation)
51
- end
52
-
53
41
  private
54
42
 
55
43
  def default_pool
@@ -24,7 +24,7 @@ module Phronomy
24
24
  # Async variant of {VectorStore::Base#add}.
25
25
  #
26
26
  # @param id [String]
27
- # @param embedding [Array<Float>]
27
+ # @param embedding [Array<Numeric>]
28
28
  # @param metadata [Hash]
29
29
  # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
30
30
  # @param timeout [Numeric, nil]
@@ -41,8 +41,8 @@ module Phronomy
41
41
 
42
42
  # Async variant of {VectorStore::Base#search}.
43
43
  #
44
- # @param query_embedding [Array<Float>]
45
- # @param k [Integer]
44
+ # @param query_embedding [Array<Numeric>]
45
+ # @param k [Integer, String] positive integer or its decimal string
46
46
  # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
47
47
  # @param timeout [Numeric, nil]
48
48
  # @return [Phronomy::TaskResult]
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Phronomy
4
- VERSION = "0.34.0"
4
+ VERSION = "0.35.0"
5
5
  end
@@ -55,6 +55,7 @@ PUBLIC_API_ENTRIES = [
55
55
  Phronomy::Runnable,
56
56
  Phronomy::Context::PromptTemplate,
57
57
  # Beta
58
+ Phronomy::PersistenceComposition,
58
59
  Phronomy::Tool::Schema,
59
60
  Phronomy::Tool::CallRequest,
60
61
  Phronomy::Tool::Operation,
@@ -112,8 +113,7 @@ def snapshot_entry(klass)
112
113
  else []
113
114
  end
114
115
  instance_methods = (klass.public_instance_methods - BASELINE_INSTANCE_METHODS - internal_methods).sort
115
- internal_class_methods = (klass == Phronomy::Storage::AsyncClient) ? %i[submit] : []
116
- class_methods = (klass.public_methods(false) - BASELINE_CLASS_METHODS - internal_class_methods).sort
116
+ class_methods = (klass.public_methods(false) - BASELINE_CLASS_METHODS).sort
117
117
  {
118
118
  "name" => klass.name,
119
119
  "type" => "class",
@@ -12,6 +12,8 @@ module Phronomy
12
12
  def self.convert: (Hash[String, json_value] snapshot, quiescent: bool) -> Hash[String, json_value]
13
13
  end
14
14
 
15
+ def self.resources: () -> Array[Storage::Resource]
16
+ def self.agent_resources: () -> Array[Storage::Resource]
15
17
  def self.agent: (?backend: _StorageBackend?) -> Agent::Store
16
18
  def self.build: (backend: _StorageBackend) -> Stores
17
19
  def self.in_memory: () -> Stores
@@ -3,8 +3,8 @@ module Phronomy
3
3
  class AsyncClient
4
4
  # pool is an optional internal execution-pool injection; ordinary callers omit it.
5
5
  def initialize: (backend: Base, ?pool: untyped) -> void
6
- def add_async: (id: String, embedding: Array[Float], ?metadata: Hash[untyped, untyped], ?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> TaskResult[untyped]
7
- def search_async: (query_embedding: Array[Float], ?k: Integer, ?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> TaskResult[Array[Hash[Symbol, untyped]]]
6
+ def add_async: (id: String, embedding: Array[Numeric], ?metadata: Hash[untyped, untyped], ?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> TaskResult[untyped]
7
+ def search_async: (query_embedding: Array[Numeric], ?k: Integer | String, ?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> TaskResult[Array[Hash[Symbol, untyped]]]
8
8
  def remove_async: (id: String, ?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> TaskResult[untyped]
9
9
  def clear_async: (?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> TaskResult[untyped]
10
10
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: phronomy
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.34.0
4
+ version: 0.35.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Raizo T.C.S
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2026-11-15 00:00:00.000000000 Z
11
+ date: 2026-11-16 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: ruby_llm