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
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
|
-
| **
|
|
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.
|
data/docs/migrations/r8-unit6.md
CHANGED
|
@@ -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).
|
|
95
|
-
|
|
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
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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.
|
|
11
|
-
`
|
|
12
|
-
|
|
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
|
-
|
|
24
|
-
|
|
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
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
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
|
-
|
|
78
|
-
|
|
79
|
-
and
|
|
80
|
-
|
|
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
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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
|
-
`
|
|
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
|
|
31
|
-
|
|
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
|
-
|
|
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
|
-
|
|
|
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
|
-
| `
|
|
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
|
|
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`, `
|
|
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
|
-
|
|
19
|
-
|
|
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
|
|
29
|
-
`
|
|
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
|
|
106
|
-
not need to read Agent private
|
|
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
|
|
155
|
-
|
|
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
|
|
|
@@ -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
|
-
#
|
|
61
|
-
#
|
|
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
|
data/lib/phronomy/agent/store.rb
CHANGED
|
@@ -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 &&
|
|
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(
|
|
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:
|
|
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:
|
|
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:
|
|
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
|