phronomy 0.33.0 → 0.35.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +104 -0
  3. data/CONTRIBUTING.md +5 -5
  4. data/README.md +17 -2
  5. data/RELEASE_CHECKLIST.md +3 -1
  6. data/SECURITY.md +1 -1
  7. data/VERIFY.sh +1 -9
  8. data/docs/architecture/backend-groups.md +69 -19
  9. data/docs/architecture/error-api-review.md +6 -2
  10. data/docs/architecture/storage-execution-boundaries.md +49 -29
  11. data/docs/architecture/structured-output-and-scope.md +3 -4
  12. data/docs/decisions/016-semantic-multi-agent-handoff.md +6 -5
  13. data/docs/decisions/027-llm-adapter-provider-boundary.md +7 -1
  14. data/docs/decisions/059-backend-contracts-and-async-clients.md +16 -4
  15. data/docs/features.md +4 -3
  16. data/docs/migrations/cleanup-audit.md +89 -0
  17. data/docs/migrations/legacy-format-removal.md +55 -0
  18. data/docs/migrations/r8-unit6.md +4 -2
  19. data/docs/migrations/storage-async-client.md +47 -17
  20. data/docs/migrations/vector-async-clients.md +24 -10
  21. data/docs/persistence-backends.md +50 -5
  22. data/docs/shared-state-sharing.md +14 -4
  23. data/lib/phronomy/agent/execution/agent_invocation.rb +0 -4
  24. data/lib/phronomy/agent/handoff/transfer_projection.rb +0 -9
  25. data/lib/phronomy/agent/journal/journal_record.rb +2 -2
  26. data/lib/phronomy/agent/recovery/recovery_rules.rb +0 -12
  27. data/lib/phronomy/agent/store.rb +3 -8
  28. data/lib/phronomy/agent/tool_execution/tool_invocation.rb +0 -3
  29. data/lib/phronomy/context/context_policy.rb +3 -7
  30. data/lib/phronomy/context/llm_input_manifest.rb +3 -3
  31. data/lib/phronomy/engine/runtime/shutdown_result.rb +0 -5
  32. data/lib/phronomy/execution/execution.rb +0 -11
  33. data/lib/phronomy/multi_agent/shared_state.rb +5 -8
  34. data/lib/phronomy/persistence/content_repository.rb +2 -1
  35. data/lib/phronomy/persistence_composition/stores.rb +14 -2
  36. data/lib/phronomy/storage/async/async_client.rb +0 -12
  37. data/lib/phronomy/vector_store/async/async_client.rb +3 -3
  38. data/lib/phronomy/version.rb +1 -1
  39. data/scripts/api_snapshot.rb +2 -2
  40. data/sig/phronomy/persistence_composition.rbs +2 -0
  41. data/sig/phronomy/vector_store/async/async_client.rbs +2 -2
  42. metadata +4 -11
  43. data/lib/phronomy/execution/scheduler_reentrancy_error.rb +0 -9
  44. data/lib/phronomy/persistence/migration/initial_format_migration.rb +0 -226
  45. data/scripts/add_to_h_to_token_doubles.rb +0 -33
  46. data/scripts/add_to_h_unnamed_doubles.rb +0 -27
  47. data/scripts/migrate_generator_verifier_result.rb +0 -18
  48. data/scripts/migrate_spec_agent_definition.rb +0 -108
  49. data/scripts/migrate_spec_agent_definition_pass2.rb +0 -53
  50. data/scripts/migrate_spec_inline_pass3.rb +0 -24
  51. data/sig/phronomy/persistence/migration.rbs +0 -13
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 |
@@ -90,7 +91,7 @@ Backend authors continue to implement the synchronous SPI only.
90
91
  | **OffloadPool sizing** — `offload_pool_size` / `offload_queue_size`; named pools available for application-owned isolation | Beta |
91
92
  | **InvocationContext** — Explicit cancellation/deadline/policy plus observability-correlation context for Agent and Workflow invocations | Beta |
92
93
  | **Metrics** — OffloadPool active/queue/abandoned metrics plus EventLoop queue/lag metrics | Beta |
93
- | **Runtime lifecycle** — Runtime-owned EventLoop and terminal `Runtime#shutdown` | Beta |
94
+ | **Runtime lifecycle** — Runtime-owned EventLoop and terminal `Runtime#shutdown`; use the result's `cleanup_complete?` for resource release and `clean?` for a graceful shutdown; [cleanup migration](migrations/cleanup-audit.md) | Beta |
94
95
 
95
96
  ## Agent and workflow patterns
96
97
 
@@ -109,7 +110,7 @@ See the [migration guide](migrations/parallel-tool-chat-removal.md).
109
110
  | **Hosted child approvals** — An Orchestrator can release a single direct child and its parent at successive Tool approvals within the same child execution. The host transfers exclusive ownership between workers. [Contract](runtime-and-concurrency.md#hosting-an-orchestrator-through-a-child-approval) | Beta |
110
111
  | **Completed native child release** — A host can unload the local Orchestrator and its finished direct child while preserving their saved results, conversation and coordination history. [Contract](runtime-and-concurrency.md#releasing-a-completed-orchestrator-and-child) | Beta |
111
112
  | **`Phronomy::MultiAgent::TeamCoordinator`** — LLM coordinator with stateful worker Agents | Beta |
112
- | **`Phronomy::MultiAgent::SharedState`** — Sequential peer-agent coordination through an invocation-local findings store; see the [namespace migration](migrations/shared-state-multi-agent.md) | Experimental |
113
+ | **`Phronomy::MultiAgent::SharedState`** — Sequential peer-agent coordination through an invocation-local findings store; default member derivation preserves Phronomy authoring settings through `Agent::Base.with_tools`; see the [sharing contract](shared-state-sharing.md#deriving-an-agent-with-a-complete-tool-set) and [namespace migration](migrations/shared-state-multi-agent.md) | Experimental |
113
114
  | **Agent Tool composition** — `Agent::Base.with_tools(definitions, id:, version:)` derives a class with a complete replacement Tool map while preserving Phronomy authoring settings and filters; [contract](shared-state-sharing.md#deriving-an-agent-with-a-complete-tool-set) | Experimental (Unreleased) |
114
115
  | **Custom shared data and Tools** — `SharedState.sharing(provider, id:, version:)` and `SharedState::Binding` connect application-owned stores and Tool definitions without private overrides; [contract and executable example](shared-state-sharing.md) | Experimental (Unreleased) |
115
116
  | **Human-in-the-loop approval** — durable suspension publishes `:approval_required` through the Agent listener; `approve` / `approve_async` resumes the same logical `execution_id` with a fresh FSMSession incarnation | Beta |
@@ -0,0 +1,89 @@
1
+ # Cleanup audit migration
2
+
3
+ Phronomy 0.34.0 removes redundant internal operations and old public entry points
4
+ whose behavior is already provided by a current operation. Applications must
5
+ use the current names; the removed names have no compatibility aliases. Current
6
+ record writers are unchanged. The subsequent [legacy-format cleanup](legacy-format-removal.md)
7
+ also removes old read fallbacks and explicitly retires two data-conversion
8
+ entry points. It does not rewrite existing stores.
9
+
10
+ For example, an application checking whether Runtime resources were released
11
+ uses `cleanup_complete?` on the result returned by `Runtime#shutdown`. The
12
+ removed `success?` method delegated to that same predicate.
13
+
14
+ ## Runtime cleanup completion
15
+
16
+ Use `cleanup_complete?` to determine whether Runtime-owned resources have stopped.
17
+ Use `clean?` only when the application also needs a graceful, error-free shutdown;
18
+ that stricter predicate is retained and is not a replacement for `success?`.
19
+
20
+ Before:
21
+
22
+ ```ruby
23
+ result = runtime.shutdown
24
+ resources_released = result.success?
25
+ ```
26
+
27
+ After:
28
+
29
+ ```ruby
30
+ result = runtime.shutdown
31
+ resources_released = result.cleanup_complete?
32
+ ```
33
+
34
+ The same replacement applies to a shutdown result returned by
35
+ `Runtime.reset_default!`. Existing reset guards still reject incomplete cleanup.
36
+
37
+ ## EventLoop reentrancy errors
38
+
39
+ Rescue `Phronomy::EventLoopReentrancyError` when a synchronous operation would
40
+ block the EventLoop control thread. Framework operations already raise this
41
+ class. The removed `SchedulerReentrancyError` was an empty subclass and did not
42
+ add a distinct failure or recovery behavior.
43
+
44
+ Before:
45
+
46
+ ```ruby
47
+ begin
48
+ Phronomy::Diagnostics.assert_not_in_event_loop!
49
+ rescue Phronomy::SchedulerReentrancyError => error
50
+ warn error.message
51
+ end
52
+ ```
53
+
54
+ After:
55
+
56
+ ```ruby
57
+ begin
58
+ Phronomy::Diagnostics.assert_not_in_event_loop!
59
+ rescue Phronomy::EventLoopReentrancyError => error
60
+ warn error.message
61
+ end
62
+ ```
63
+
64
+ Ruby rescue matches a class and its subclasses, not its parent. The old rescue
65
+ above therefore did not catch a directly raised `EventLoopReentrancyError` even
66
+ before this cleanup. The current error name describes the actual failure.
67
+
68
+ ## Internal operations
69
+
70
+ Internal cleanup keeps behavior at its owning boundary. Context item factories
71
+ call the protected `ContextPolicy#estimate_tokens` extension operation directly.
72
+ Tool approval requests obtain one display projection and snapshot its arguments
73
+ and facts in the public approval Item.
74
+
75
+ For example, an application that renders approval details continues to use
76
+ `ToolApprovalRequest::Item#arguments` and `#facts`; it does not need the removed
77
+ internal `ToolInvocation#display_arguments` and `#display_facts` getters. The
78
+ public `Tool::Base#approval_display` extension operation remains available.
79
+
80
+ The cleanup also removes the unused internal `AgentInvocation#streaming?`,
81
+ `RecoveryRules.subject_key`, and `Execution#__while_open` and
82
+ `Execution#__cancellation_token` methods. Scope-owned operations used by result
83
+ composition remain in `ExecutionScopeState`. Five completed scripts for migrating
84
+ the repository's own test sources are removed. The subsequent legacy-format
85
+ cleanup separately retires the pre-S3 migration API and old Result JSON converter.
86
+
87
+ `JournalProjection#llm_call_records` and
88
+ `LLMInputManifest#referenced_content_refs` remain available. Lack of calls from
89
+ the repository does not make an application-facing operation removable.
@@ -0,0 +1,55 @@
1
+ # Legacy-format cleanup
2
+
3
+ Phronomy 0.34.0 keeps current saved facts and removes specific historical read
4
+ fallbacks and conversion facilities. It does not rewrite stores or introduce a
5
+ new record version. Retiring the conversion facilities is an intentional removal
6
+ of migration support, not a claim that another public API replaces them.
7
+
8
+ For example, a newly authorized Tool operation continues to store its validated
9
+ arguments, including type coercion and meaningful null values. Its reader no
10
+ longer reconstructs those arguments from an older raw-input field.
11
+
12
+ ## Handoff conversation groups
13
+
14
+ Handoff uses the conversation group recorded by the current Context assembly.
15
+ The historical selection-unit ID and kind no longer supply grouping or category
16
+ information. Segments without a current group still use the ordinary per-segment
17
+ fallback; reserved internal metadata is still removed from transferred content.
18
+
19
+ For example, current Tool-call and Tool-result segments share
20
+ `context_policy_conversation_group_id` and remain together when a Handoff policy
21
+ selects that exchange. A saved `selection_unit_id` is no longer an alternative
22
+ source for that relationship. The Manifest codec remains strict about its
23
+ supported version and required fields.
24
+
25
+ ## Authorized Tool arguments
26
+
27
+ Agent Store reads the exact validated argument snapshot for an authorized
28
+ operation. The raw request remains a separate fact and is not a substitute when
29
+ the validated snapshot is absent.
30
+
31
+ For example, raw `{"count":"2","optional":null}` may validate as
32
+ `{"count":2,"optional":null}`. Authorization matching must use the integer and
33
+ retain the explicit null. An authorized record missing `validated_arguments`
34
+ fails instead of falling back to `arguments` and dropping null values.
35
+
36
+ Provider-response recovery can temporarily record an `authorized` placeholder
37
+ without that snapshot. The normal `framework_calls` continuation validates its
38
+ Tool invocation and saves the prepared snapshot before an operation consumer
39
+ reads it. Directly projecting the intermediate placeholder is rejected; its
40
+ status alone is not proof that its arguments have been validated. A resumed
41
+ `framework_tools` continuation instead uses its previously saved dispatch
42
+ snapshot.
43
+
44
+ ## Retired conversion support
45
+
46
+ The pre-S3 `Persistence::Migration::InitialFormatMigration` API and the
47
+ GeneratorVerifier Result JSON converter are removed, along with the former
48
+ command's usage instructions. There is no compatibility alias or replacement
49
+ conversion command. Ordinary Agent and Workflow persistence, current Manifest
50
+ decoding and GeneratorVerifier Result validation remain in their owning domains.
51
+
52
+ For example, `GeneratorVerifier::Result.from_h` still requires `failure` even
53
+ when its value is null. It does not add missing fields to historical JSON.
54
+ The separate `PersistenceComposition::Unit4Migration` snapshot conversion is
55
+ retained and was not an implementation of either removed conversion facility.
@@ -91,8 +91,10 @@ an explicit items schema to restrict them.
91
91
  Storage SPI and SQL schemas are unchanged. New Tool batch metadata additionally
92
92
  records `validated_arguments`, separately from the unchanged raw request fields.
93
93
  Agent authorization projects and compares that exact snapshot (including explicit
94
- null in explicit schemas). Older snapshots without this field use the historical
95
- raw-argument/optional-nil-omission rule. Existing journal message boundaries,
94
+ null in explicit schemas). Authorization projection requires this validated
95
+ dispatch evidence; it does not infer approved values from raw request fields.
96
+ Provider-recovery placeholders are revalidated and replaced by the normal Tool
97
+ dispatch barrier before framework operations run. Existing journal message boundaries,
96
98
  Tool call identities and recorded usage remain readable. Legacy top-level
97
99
  thought_signature is decoded into opaque CallRequest metadata and rendered by
98
100
  the backend. Old SDK usage field spellings remain accepted by SavedContextReader.
@@ -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,16 +101,24 @@ 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
109
118
  directories. Backend Contracts have no execution or implementation dependency.
110
- P4 Storage/ContentStore work remains pending.
119
+ P4 Storage/ContentStore work is implemented; see the
120
+ [Storage asynchronous execution guide](storage-async-client.md).
121
+ [ADR-062](../decisions/062-content-store-service.md) subsequently classified
122
+ ContentStore as a content service over Storage, rather than a physical backend.
123
+ The final P5 cross-repository/API/documentation review remains pending, as
124
+ recorded in [Backend responsibilities](../architecture/backend-groups.md).
@@ -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
@@ -102,8 +102,9 @@ argument to the default `read_store` Tool or a search method to that store.
102
102
  The public `Agent::Base.with_tools(definitions, id:, version:)` factory creates
103
103
  an Agent subclass with a replacement Tool map and an explicit definition
104
104
  identity. Agent owns preservation of its authoring settings; SharedState uses
105
- this public operation after composing the member and application Tools. It does
106
- not need to read Agent private settings.
105
+ this public operation after composing the member Tools with either its built-in
106
+ sharing Tools or the application's Tools. It does not need to read Agent private
107
+ settings.
107
108
 
108
109
  For example, inside the complete example's module, a provider can supply the
109
110
  entire Tool map for a derived researcher class:
@@ -131,6 +132,13 @@ The original class is unchanged. This explicit factory does not change general
131
132
  Agent subclass inheritance or define copying rules for application-specific
132
133
  class state.
133
134
 
135
+ The default findings-store mode now preserves these settings through the same
136
+ factory. For example, a member configured with `max_iterations 3` and
137
+ `temperature 0.25` keeps those settings when SharedState adds `read_store` and
138
+ `write_finding`. Member Tool aliases, the generated definition identity and the
139
+ default store/prompt behavior remain unchanged. This fixes the earlier default
140
+ derivation, which explicitly copied only the model setting.
141
+
134
142
  ## Application search and LLM input
135
143
 
136
144
  Application Tools own record fields and search conditions. ContextPolicy and the
@@ -151,8 +159,10 @@ explicitly through the existing appropriate contracts.
151
159
  SharedState continues to use the member's configured ContextPolicy. The binding
152
160
  does not automatically populate `before_llm_input` candidates, inspect Context
153
161
  internals or manage a provider message buffer. Example 22's adaptive reader is a
154
- separate application implementation; this extension alone does not migrate it
155
- or remove its existing private-API dependency.
162
+ separate application implementation. Its current version uses the public sharing
163
+ contract and Context budgeting APIs introduced in v0.33.0; its previous private
164
+ overrides have been removed. The application still owns adaptive retrieval and
165
+ budget allocation rather than delegating those policies to the sharing binding.
156
166
 
157
167
  ## Lifetime and verification
158
168
 
@@ -114,10 +114,6 @@ module Phronomy
114
114
  @callback_failure = nil
115
115
  end
116
116
 
117
- def streaming?
118
- @mode == :stream
119
- end
120
-
121
117
  def set_graph_metadata(phase: nil)
122
118
  @phase = phase
123
119
  end
@@ -83,9 +83,6 @@ module Phronomy
83
83
  return :current_request if segment.delivery.to_sym == :ask_argument
84
84
  return nil if CONTROL_CATEGORIES.include?(segment.category.to_sym)
85
85
  return :knowledge if segment.category.to_sym == :knowledge
86
- unit_kind = segment.metadata["selection_unit_kind"] ||
87
- segment.metadata[:selection_unit_kind]
88
- return :tool_exchanges if unit_kind.to_s == "tool_exchange"
89
86
 
90
87
  case segment.category.to_sym
91
88
  when :external_message, :assistant_message, :tool_message,
@@ -102,12 +99,6 @@ module Phronomy
102
99
  return "context-policy-conversation:#{conversation_group_id}"
103
100
  end
104
101
 
105
- # Compatibility for finalized pre-ACS-04 manifests. New manifests use
106
- # context_policy_conversation_group_id and do not recreate Phronomy::Context::Unit.
107
- unit_id = segment.metadata["selection_unit_id"] ||
108
- segment.metadata[:selection_unit_id]
109
- return "unit:#{unit_id}" if unit_id
110
-
111
102
  "segment:#{policy_category}:#{segment.position}"
112
103
  end
113
104
 
@@ -57,8 +57,8 @@ module Phronomy
57
57
  ATTRIBUTES.to_h { |name| [name.to_s, public_send(name)] }
58
58
  end
59
59
 
60
- # Historical durable fields are not accepted here. Explicit migration must
61
- # convert them to the current semantic payload first.
60
+ # Reads the current semantic payload only. Historical durable fields are
61
+ # rejected rather than converted.
62
62
  def self.from_h(hash)
63
63
  source = hash.to_h { |key, value| [key.to_s, value] }
64
64
  expected = ATTRIBUTES.map(&:to_s).sort
@@ -88,18 +88,6 @@ module Phronomy
88
88
  normalized.freeze
89
89
  end
90
90
 
91
- def subject_key(subject)
92
- normalized = normalize_subject(subject)
93
- case normalized.fetch(:type)
94
- when :llm_call
95
- "llm_call:#{normalized.fetch(:llm_call_id)}"
96
- when :tool_invocation
97
- "tool_invocation:#{normalized.fetch(:tool_invocation_id)}"
98
- when :persistence_operation
99
- "persistence_operation:#{normalized.fetch(:entity)}"
100
- end
101
- end
102
-
103
91
  def subject_equal?(left, right)
104
92
  normalize_subject(left) == normalize_subject(right)
105
93
  rescue ArgumentError, KeyError
@@ -48,6 +48,7 @@ module Phronomy
48
48
 
49
49
  # Validate the exact requested call and project its authorized batch in
50
50
  # Provider order from one execution snapshot in the caller's transaction.
51
+ # Only the validated dispatch snapshot is authorization evidence.
51
52
  # The receiving domain owns application and replay of these operations.
52
53
  def authorized_operations(scope, agent_id:, execution_id:, invocation_id:, name:, arguments:, names:)
53
54
  participate(scope) do |records|
@@ -58,7 +59,7 @@ module Phronomy
58
59
  batch = Array(execution.metadata[ExecutionMetadata::TOOL_BATCH_METADATA_KEY])
59
60
  requested = batch.find { |entry| entry.fetch("tool_invocation_id") == invocation_id }
60
61
  unless names.include?(name) && requested && requested.fetch("status") == "authorized" &&
61
- requested.fetch("tool_name") == name && authorized_argument_values(requested) == arguments
62
+ requested.fetch("tool_name") == name && requested.fetch("validated_arguments") == arguments
62
63
  raise Phronomy::Persistence::StateConflictError, "Operation #{invocation_id} is not the authorized call"
63
64
  end
64
65
  batch.filter_map do |entry|
@@ -66,7 +67,7 @@ module Phronomy
66
67
  AuthorizedOperation.new(
67
68
  invocation_id: Phronomy::Values::Immutable.copy(entry.fetch("tool_invocation_id")),
68
69
  name: Phronomy::Values::Immutable.copy(entry.fetch("tool_name")),
69
- arguments: Phronomy::Values::Immutable.copy(authorized_argument_values(entry))
70
+ arguments: Phronomy::Values::Immutable.copy(entry.fetch("validated_arguments"))
70
71
  )
71
72
  end.freeze
72
73
  end
@@ -286,12 +287,6 @@ module Phronomy
286
287
  Phronomy::Values::Immutable.json(contents.fetch_json(execution.result_ref)) : contents.fetch_text(execution.result_ref)
287
288
  end
288
289
 
289
- def authorized_argument_values(entry)
290
- # Unit 6 persists the exact validated snapshot. Older records encoded
291
- # legacy raw params, whose explicit optional nil meant omission.
292
- entry.key?("validated_arguments") ? entry.fetch("validated_arguments") : entry.fetch("arguments").compact
293
- end
294
-
295
290
  def with_scope(scope, &block)
296
291
  assert_observation_thread!
297
292
  scope ? participate(scope, &block) : transaction(&block)
@@ -345,9 +345,6 @@ module Phronomy
345
345
  display
346
346
  end
347
347
 
348
- def display_arguments = immutable_copy(approval_display.fetch(:arguments))
349
- def display_facts = immutable_copy(approval_display.fetch(:facts))
350
-
351
348
  private
352
349
 
353
350
  def restore_saved_state!(status, result)
@@ -35,7 +35,7 @@ module Phronomy
35
35
  role: role,
36
36
  content: content,
37
37
  content_format: content_format || inferred_content_format(content),
38
- estimated_tokens: estimate_content(content),
38
+ estimated_tokens: estimate_tokens(content),
39
39
  required: required,
40
40
  provenance: generated_provenance,
41
41
  metadata: metadata
@@ -56,7 +56,7 @@ module Phronomy
56
56
  role: role,
57
57
  content: content,
58
58
  content_format: content_format || inferred_content_format(content),
59
- estimated_tokens: estimate_content(content),
59
+ estimated_tokens: estimate_tokens(content),
60
60
  required: required,
61
61
  provenance: generated_provenance,
62
62
  metadata: metadata
@@ -82,7 +82,7 @@ module Phronomy
82
82
  content: content,
83
83
  content_format: content_format || inferred_content_format(content),
84
84
  sequence: sequence,
85
- estimated_tokens: estimate_content(content),
85
+ estimated_tokens: estimate_tokens(content),
86
86
  required: required,
87
87
  provenance: generated_provenance,
88
88
  tool_call_id: tool_call_id,
@@ -121,10 +121,6 @@ module Phronomy
121
121
  def inferred_content_format(content)
122
122
  content.is_a?(String) ? :text : :json
123
123
  end
124
-
125
- def estimate_content(content)
126
- estimate_tokens(content)
127
- end
128
124
  end
129
125
  end
130
126
  end