phronomy 0.30.0 → 0.30.1
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 +11 -0
- data/docs/architecture/r8-unit1.md +68 -68
- data/docs/architecture/r8-unit2.md +34 -34
- data/docs/decisions/029-semantic-completion-and-application-effect-boundary.md +1 -1
- data/docs/design/durable-semantic-coordination/CHANGELOG_V2_REVISION_2.md +23 -23
- data/docs/design/durable-semantic-coordination/IMPLEMENTATION_REPORT.md +99 -99
- data/docs/design/durable-semantic-coordination/RECOVERY_CONTRACT_CLARIFICATIONS.md +135 -136
- data/lib/phronomy/version.rb +1 -1
- metadata +2 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 077db55116aa3b2b1deeeabef69b46b5481c72f1636aa4c623ad8b843d20ef38
|
|
4
|
+
data.tar.gz: 07bbf1214b2aaaf6df1403c69ff8e9f7a7bc4bc8dac63ec4a7a1b11955c0a014
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: a28ae543ff3826e964cd235580a01175446187546f5f2c94ed34bf12cfd967337df9673654b3029d9173f99479cc32ef966f5bac71db2918cd0265402860e124
|
|
7
|
+
data.tar.gz: ca6dbea79bc432cb1802dbec83cae8b427011b6782f11cfce02fa30ec5b5003439e6b4e6fedd48b6a589ba6b9374075491ae796549dabe41746f20c43f2ee143
|
data/CHANGELOG.md
CHANGED
|
@@ -12,6 +12,17 @@ Release history for 0.14.0 and earlier is archived in
|
|
|
12
12
|
|
|
13
13
|
## [Unreleased]
|
|
14
14
|
|
|
15
|
+
## [0.30.1] - 2026-10-24
|
|
16
|
+
|
|
17
|
+
### Documentation
|
|
18
|
+
|
|
19
|
+
- Translate historical r8 unit 1/2 architecture notes and durable semantic
|
|
20
|
+
coordination records into English, preserving API names, executable commands,
|
|
21
|
+
requirement IDs, dates and the original validation limits.
|
|
22
|
+
- Repair ADR-029's link to the recovery-contract document and its English heading.
|
|
23
|
+
|
|
24
|
+
Runtime behavior, public APIs and dependency requirements match 0.30.0.
|
|
25
|
+
|
|
15
26
|
## [0.30.0] - 2026-10-24
|
|
16
27
|
|
|
17
28
|
### Added
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# r8
|
|
1
|
+
# r8 unit 1: Shared Context, Tool, and Execution foundations
|
|
2
2
|
|
|
3
3
|
> Current boundary: r8 unit 6 supersedes the historical Chat/SDK ownership and
|
|
4
4
|
> adapter extension SPI below. Agent uses LLMAdapter values; the backend owns SDK
|
|
@@ -6,99 +6,99 @@
|
|
|
6
6
|
> `docs/architecture/r8-unit6.md` and `docs/migrations/r8-unit6.md`.
|
|
7
7
|
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
The baseline is main `653e255a34fe4062d4beca47530e084fdd3a6ba9`, checked on 2026-09-30. The design references are the revised r8 specification and directory layout documents updated that day. This change is the first implementation unit; it does not mean that all of r8, every S1 item, or every S2/S3 acceptance condition is complete. Compatibility aliases and old APIs that only forward calls are not retained.
|
|
10
10
|
|
|
11
|
-
##
|
|
11
|
+
## Implemented responsibilities and operations
|
|
12
12
|
|
|
13
|
-
|
|
|
13
|
+
| Owner | What the shared foundation does | What remains with the caller |
|
|
14
14
|
|---|---|---|
|
|
15
|
-
| `Context::Assembly` | Policy
|
|
16
|
-
| `Tool::DefinitionSet` | Tool
|
|
17
|
-
| `Tool::Authorization` |
|
|
18
|
-
| `Tool::ToolExecutor` | cooperative/offloaded
|
|
19
|
-
| `LLMAdapter::Base` / `RubyLLM` |
|
|
20
|
-
| `Execution` | submit
|
|
21
|
-
| `Tracing::Observation` |
|
|
15
|
+
| `Context::Assembly` | Calls the Policy once and validates the Plan; normalizes content, checks the final budget, and stores the Manifest | Agent obtains the snapshot, rechecks the watermark immediately before persistence, and updates the Agent execution record |
|
|
16
|
+
| `Tool::DefinitionSet` | Normalizes Tool definitions and validates name uniqueness and consistency with persisted definitions | Agent prepares its own Tool aliases, decorators, and runtime instances |
|
|
17
|
+
| `Tool::Authorization` | Evaluates facts -> requirement -> policy -> decision using immutable arguments and authorization context | Agent manages execution matching, approval state, admission results, and supervision |
|
|
18
|
+
| `Tool::ToolExecutor` | Handles cooperative/offloaded execution rules and results | Pool selection in Engine is delegated to the Execution mechanism binding |
|
|
19
|
+
| `LLMAdapter::Base` / `RubyLLM` | Handles synchronous generation and chat construction/configuration, message construction, and tool-call construction; the RubyLLM implementation translates SDK failures | Agent validates its persisted data and Tool definitions before passing them to the adapter |
|
|
20
|
+
| `Execution` | Owns the submit entry point, fan-out/fan-in, result composition, and cancellation/deadline/waiting rules | Engine implements pools, timers, Runtime, and FSM mechanisms |
|
|
21
|
+
| `Tracing::Observation` | Provides explicit observation and PII redaction without changing the actual return value | Runnable owns the invoke/stream/batch execution contract |
|
|
22
22
|
|
|
23
|
-
Context
|
|
23
|
+
Context and Tool own real shared procedures, rather than merely housing thin Agent type definitions. However, current Context inputs still contain Agent-derived identifiers and provenance. This is not a redesign into a fully generic domain model. The Tool DSL base continues to use RubyLLM::Tool.
|
|
24
24
|
|
|
25
|
-
`Context::Assembly#prepare(input:, policy:, adapter_identity:)`
|
|
25
|
+
`Context::Assembly#prepare(input:, policy:, adapter_identity:)` calls the Policy outside the persistence transaction. `#store(prepared, contents:)` uses only the contents repository supplied by the caller from the same transaction; it does not start an independent transaction. Initial and follow-up Agent commits store the Manifest and the AgentExecution reference within the existing transaction. If a later write fails, the Manifest is rolled back too, and the Policy is not executed again. The existing ordering, which applies the live projection after commit, is preserved. This validates the Agent/Context part of P02; it does not complete participation in outer transactions for arbitrary domains.
|
|
26
26
|
|
|
27
|
-
Execution
|
|
27
|
+
Execution depends on the operations of `_ExecutionBackend`. Composition configures a deferred provider, and Engine's `ExecutionBinding` implements submit/after. Creating settled TaskResults, using map/flat_map/all_settled, and checking waiting constraints do not load Engine. Runtime is obtained only when work is actually submitted or a timer is registered. Mechanism references are consolidated here, rather than merely being renamed or nominally reassigned.
|
|
28
28
|
|
|
29
|
-
Workflow
|
|
29
|
+
`Workflow::Completion` owns Workflow FINISH and completion values, and WorkflowRunner translates them into the FSM representation. Event/FSMProtocol/TerminalDecision, which are specific to FSMSession, live in Engine. Full separation of Agent and MultiAgent FSM-specific bindings remains outstanding.
|
|
30
30
|
|
|
31
|
-
##
|
|
31
|
+
## Public names and layout changes
|
|
32
32
|
|
|
33
|
-
|
|
|
33
|
+
| Previous location/API | New location/API | Rationale |
|
|
34
34
|
|---|---|---|
|
|
35
|
-
| `agent/context_contract/`
|
|
36
|
-
| `agent/context_policies/default.rb` | `context/default_policy.rb
|
|
37
|
-
| `Agent::Context::Instruction::PromptTemplate` | `Context::PromptTemplate` | Agent
|
|
38
|
-
| `Agent::Selection::{Candidate,Constraint}` | `Context::{Candidate,Constraint}` |
|
|
39
|
-
| `Agent::LLMInputPatch` / `LLMInputBuildContext` | `Context::LLMInputPatch` / `LLMInputBuildContext` | hook
|
|
40
|
-
| `ContextBudgetExceededError` | `Context::BudgetExceededError` | LLM
|
|
41
|
-
| `agent/context_assembly/` | `context/assembly.rb`
|
|
42
|
-
| `Agent::Context::Capability::Base` |
|
|
43
|
-
| `agent/tool_execution/tool_definition_set.rb` | `tool/definition_set.rb` |
|
|
44
|
-
| `execution_contract/`
|
|
45
|
-
| `WorkerSubmission` | `Execution.submit` |
|
|
46
|
-
| `Runnable#trace` | `Tracing::Observation.trace` |
|
|
47
|
-
| `tool/contract
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
## r8
|
|
54
|
-
|
|
55
|
-
|
|
|
35
|
+
| `agent/context_contract/` and APIs such as `Agent::ContextPolicy` | `context/` and APIs such as `Context::ContextPolicy` | Consolidate Policy, Plan, Manifest, and validation under the owner of the shared operations |
|
|
36
|
+
| `agent/context_policies/default.rb` | `context/default_policy.rb`, `Context::DefaultPolicy` | Keep the concrete Policy in the same domain |
|
|
37
|
+
| `Agent::Context::Instruction::PromptTemplate` | `Context::PromptTemplate` | Remove the old public name under Agent |
|
|
38
|
+
| `Agent::Selection::{Candidate,Constraint}` | `Context::{Candidate,Constraint}` | Remove the thin Selection subdivision |
|
|
39
|
+
| `Agent::LLMInputPatch` / `LLMInputBuildContext` | `Context::LLMInputPatch` / `LLMInputBuildContext` | Unify ownership of hook inputs and return values |
|
|
40
|
+
| `ContextBudgetExceededError` | `Context::BudgetExceededError` | Represent a Context budget failure, not an LLM provider failure |
|
|
41
|
+
| `agent/context_assembly/` | `context/assembly.rb` plus preparation, state, and input handling directly under Agent | Separate shared Context procedures, Agent snapshot/state handling, and LLM SDK handling |
|
|
42
|
+
| `Agent::Context::Capability::Base` | The actual implementation, `Tool::Base` | Remove the old name and alias |
|
|
43
|
+
| `agent/tool_execution/tool_definition_set.rb` | `tool/definition_set.rb` | Transfer shared definition handling; keep Agent-specific construction in Agent |
|
|
44
|
+
| `execution_contract/` and `execution_services/` | `execution/` and the necessary `execution/concurrency/` | Consolidate operations, values, and shared rules; do not add thin subdivisions such as `execution_result` |
|
|
45
|
+
| `WorkerSubmission` | `Execution.submit` | Remove the forwarding-only module |
|
|
46
|
+
| `Runnable#trace` | `Tracing::Observation.trace` | Remove the execution foundation's dependency on observation |
|
|
47
|
+
| `tool/contract`, `filter/contract`, `output_parser/contract`, `agent/lifecycle_contract` | Exception files under their owning domains | Remove exception-only directories; retain existing meaningful exception constant names as actual definitions |
|
|
48
|
+
|
|
49
|
+
Custom LLM adapters implement `build_chat`, `configure_chat`, `message`, and `tool_call` in addition to complete/stream. The base class supplies a default `identity` and a nil default for `input_budget`. See `sig/phronomy/llm_adapter/base.rbs` for exact keywords and return contracts. Translate SDK-specific exceptions into LLM failures at adapter operation boundaries, preserving the original cause. Do not translate application exceptions or cancellation into unrelated provider failures.
|
|
50
|
+
|
|
51
|
+
The existing `tool_result_max_size` configuration API and logger are supplied by application composition to neutral RuntimeSettings. Remove references from Tool to the composition factory while preserving default, nil, and scoped-copy semantics. Place RBS in `sig/` and `sig/_private/`, and analyze dependencies based on implementation constants and declaration ownership.
|
|
52
|
+
|
|
53
|
+
## Progress by r8 item
|
|
54
|
+
|
|
55
|
+
| Item | This implementation unit | Outstanding work |
|
|
56
56
|
|---|---|---|
|
|
57
|
-
| DP01 Context
|
|
58
|
-
| DP02 Tool
|
|
59
|
-
| DP03 Execution
|
|
60
|
-
| DP04 Persistence |
|
|
61
|
-
| DP05
|
|
62
|
-
| DP06 LLM
|
|
63
|
-
| DP07
|
|
64
|
-
| DP08
|
|
65
|
-
| DP09 Embeddings
|
|
66
|
-
| DP10 Documents |
|
|
67
|
-
| DP11 assembly/concerns
|
|
68
|
-
| DP12
|
|
69
|
-
| DP13 Recovery/Handoff |
|
|
70
|
-
| P02
|
|
71
|
-
| P01/P03
|
|
72
|
-
| 155
|
|
57
|
+
| DP01 Context consolidation | Main scope implemented | Broader domain inputs and public operations still require review |
|
|
58
|
+
| DP02 Shared Tool foundation | Shared definition, authorization evaluation, and invocation implemented | Agent FSM bindings and all parent/child authorization rules remain under DP12/P04 |
|
|
59
|
+
| DP03 Execution consolidation | Implemented | This does not complete the review of FSM use across all domains |
|
|
60
|
+
| DP04 Persistence | Not started | Facade removal and shared transaction/participation/outcome-reconciliation APIs |
|
|
61
|
+
| DP05 Domain persistence schemas | Not started | Consolidation of MultiAgent/Workflow storage_contract |
|
|
62
|
+
| DP06 LLM consolidation | Prerequisites only | Full consolidation of llm_contract and llm_adapter |
|
|
63
|
+
| DP07 Consolidation of thin failure directories | Implemented | This is not a redesign of every domain's failure vocabulary |
|
|
64
|
+
| DP08 Composition consolidation | Bindings added only | Physical consolidation of runtime/persistence/agent composition |
|
|
65
|
+
| DP09 Independent Embeddings domain | Not started | Placement independent of vector_store |
|
|
66
|
+
| DP10 Documents | Not started | Loader/splitter relocation |
|
|
67
|
+
| DP11 Decomposition of assembly/concerns | Main scope implemented | Agent-specific processing remains directly under Agent |
|
|
68
|
+
| DP12 Domain execution bindings | Partial, including the Workflow completion boundary | Full separation of Agent/ToolInvocation/Team domain decisions from FSM bindings |
|
|
69
|
+
| DP13 Recovery/Handoff | Not started | Ownership of domain recovery, Persistence outcome reconciliation, and parent/child operations |
|
|
70
|
+
| P02 Persistence participation | Validated in the existing Agent/Context transaction | Outer scopes, savepoints, and public participation APIs across multiple domains |
|
|
71
|
+
| P01/P03-P06 Persistence and parent/child coordination | Not started | The atomicity conditions below must be established |
|
|
72
|
+
| Triangle review: 155 pairs, 393 cases | Reassessment incomplete | Regenerating the diagrams does not substitute for completing the assessment |
|
|
73
73
|
|
|
74
|
-
NC/F/RM
|
|
74
|
+
No document claims that every NC/F/RM item has been addressed. Acceptance claims are limited to the implementation units in this table and the accompanying test evidence.
|
|
75
75
|
|
|
76
|
-
## Persistence
|
|
76
|
+
## Why Persistence is outside this implementation unit
|
|
77
77
|
|
|
78
|
-
|
|
78
|
+
Initial Agent admission currently reads the Team reservation inside the persistence transaction. The final design should eliminate Agent's reference to Team internals, but simply moving validation to an earlier call creates this race:
|
|
79
79
|
|
|
80
|
-
1.
|
|
81
|
-
2.
|
|
82
|
-
3. Agent
|
|
80
|
+
1. The parent checks that the reservation is valid.
|
|
81
|
+
2. Another operation cancels the reservation.
|
|
82
|
+
3. Agent saves its admission record in a new transaction and starts the cancelled child.
|
|
83
83
|
|
|
84
|
-
|
|
84
|
+
The next implementation unit needs a participation API that performs the parent-owned reservation check and records Agent admission within the same scope. The parent owns reservation rules, Agent owns admission rules, and Persistence owns participation and commit boundaries. Merely hiding the current reverse dependency, where Agent switches on parent kind to select Team, behind a new callback would not resolve it.
|
|
85
85
|
|
|
86
|
-
|
|
86
|
+
The unresolved details are public participation keywords/return values, races with cancellation, post-commit Runtime admission, and querying/resuming with the same child ID after interruption. Workflow halt/finish snapshots alone do not make child execution inside arbitrary actions durable. P05 must define the concrete Workflow-to-Agent/Team paths, checkpoints, and one-time result incorporation. Unknown outcomes must not be treated as success based on a single matching record; P06 must define evidence across multiple domains.
|
|
87
87
|
|
|
88
|
-
|
|
88
|
+
Therefore this change does not alter the existing Persistence facade, Team admission validation, or transaction boundaries for reservations and child records. These remain for the next specification and implementation unit, rather than introducing provisional code with weaker guarantees.
|
|
89
89
|
|
|
90
|
-
##
|
|
90
|
+
## Reading the analysis diagrams
|
|
91
91
|
|
|
92
|
-
|
|
92
|
+
Regenerate the diagrams from actual source and RBS. Preserve the existing horizontal bands, group colors, individual module boxes, and transparent text backgrounds. Arrows to M33/M41/M44 are omitted only from the display; retain them in JSON, matrices, and boundary assessments. Retire old IDs instead of reusing them.
|
|
93
93
|
|
|
94
|
-
|
|
94
|
+
These are measured diagrams of the revised candidate, not conceptual diagrams of a completed r8. Include remaining cycles and reverse dependencies. RBS alone cannot fully prove injected targets or dynamic dispatch that static analysis cannot observe. Combine it with execution tests for Engine mechanism bindings and domain persistence.
|
|
95
95
|
|
|
96
96
|
```bash
|
|
97
97
|
bundle exec rbs -I sig validate
|
|
98
98
|
python -m pip install -r tools/architecture/tools/requirements.txt
|
|
99
99
|
python -m unittest discover -s tools/architecture/tests -v
|
|
100
|
-
# lib/sig
|
|
100
|
+
# After committing lib/sig, use this option for an unpublished candidate.
|
|
101
101
|
python tools/architecture/refresh_diagram.py . tmp/architecture-r8-unit1 --candidate
|
|
102
102
|
```
|
|
103
103
|
|
|
104
|
-
|
|
104
|
+
The SHA in the supplied SVG identifies the local candidate used to generate it. It differs from the SHA created when the user applies and commits the changes, so regenerate the post-application diagrams from that checkout. See the distribution package's verification report for the Ruby environment, test counts, skip reasons, unverified environments, and application procedure.
|
|
@@ -1,55 +1,55 @@
|
|
|
1
|
-
# r8 unit 2
|
|
1
|
+
# r8 unit 2: Parent reservation checks and Agent admission
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
This unit implements the P02/P03 admission boundary. The core baseline is `16e6fcb2dd49836735598525114abfc256d0773e`. It does not complete all of r8 or the entire Persistence reorganization.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Responsibilities and operations
|
|
6
6
|
|
|
7
|
-
|
|
|
7
|
+
| Owner | Public operations and shared rules | Dependencies and internal implementation |
|
|
8
8
|
|---|---|---|
|
|
9
|
-
|
|
|
10
|
-
| Agent | `Admission#accept_in
|
|
11
|
-
| MultiAgent | `ReservedChildAdmission#admit
|
|
12
|
-
|
|
|
9
|
+
| Shared Persistence | `atomic`, `Transaction#participate`, and `committed?`; validates the same Persistence instance, synchronous thread, active scope, savepoints, and commit acknowledgements | Uses Storage's public transaction/scope rules; does not select Agent, Team, Workflow, or composition components |
|
|
10
|
+
| Agent | `Admission#accept_in`; persists input records, execution identity, Agent admission, and revision updates in the same scope | Uses Agent's persistence component; does not interpret parent kind, Team assignments, subagent snapshots, or Handoff reservations |
|
|
11
|
+
| MultiAgent | `ReservedChildAdmission#admit`; validates parent cancellation, slot, and child ID, and has Agent admission participate in the same scope | Its own persistence component reads the reservation evidence and acquires the required guards |
|
|
12
|
+
| Persistence components | `Agent::Persistence::Admission`, `MultiAgent::Persistence::Reservation` | Uses raw Storage views at this boundary; does not pass raw views to domain operations |
|
|
13
13
|
|
|
14
|
-
Agent
|
|
14
|
+
The existing ExecutionCoordinator continues to own acquiring Agent Runtime admission, starting the FSM, and applying live state. The new Admission covers only the short persistence phase; it does not place the entire Agent execution inside the parent's database transaction. Ordinary applications do not need to implement or instantiate the new participation classes.
|
|
15
15
|
|
|
16
|
-
`phronomy_admission`
|
|
16
|
+
`phronomy_admission` is current internal wiring; no Proc or object is persisted. Only the existing correlation information and parent/child IDs are stored. The Team/subagent/Handoff start and resume components supply the current participant. Reconnecting to a persisted execution preserves ExactExecution's same-ID matching and recovery rules.
|
|
17
17
|
|
|
18
|
-
##
|
|
18
|
+
## Persistence ordering and failures
|
|
19
19
|
|
|
20
|
-
1. Agent
|
|
21
|
-
2. MultiAgent
|
|
22
|
-
3.
|
|
23
|
-
4. commit
|
|
20
|
+
1. Agent acquires the existing Runtime admission and begins the persistence operation on a synchronous worker.
|
|
21
|
+
2. MultiAgent opens a short `atomic` scope, acquires the parent guard, and then rereads the reservation.
|
|
22
|
+
3. It validates parent cancellation, assignment, and child identity. Agent stores the input content, AgentExecution, and AgentRoot in the same scope.
|
|
23
|
+
4. Only after a successful commit acknowledgement does the Agent execution component obtain the admission result and continue preparation, FSM execution, and live-state updates.
|
|
24
24
|
|
|
25
|
-
|
|
25
|
+
A participation operation's return value does not mean that commit succeeded. `accept_in` returns nil, and the Agent-internal `result` is unavailable until the outer commit. Duplicate participation, a different Persistence instance, a different thread, or an expired scope is rejected. Separate Persistence instances wrapping the same backend are not treated as the same scope. Code inside a raw backend transaction cannot claim to be a new commit owner.
|
|
26
26
|
|
|
27
|
-
|
|
27
|
+
Explicit nesting uses savepoints. Inner success is not committed if the outer transaction rolls back. Even if an exception during participation is caught inside the scope, earlier changes in that failed scope cannot be committed. Do not perform LLM calls, Tool calls, scheduling, external callbacks, or asynchronous waits inside participation operations.
|
|
28
28
|
|
|
29
|
-
Storage
|
|
29
|
+
Storage scope violations are translated into `Persistence::TransactionError`, preserving cause and backtrace. This naming change does not assert that the persistence outcome is known. Persistence failures with unknown outcomes, such as IOError, are neither translated nor automatically retried; they pass to existing Agent recovery rules. This unit does not add a generalized persistence-outcome reconciliation API.
|
|
30
30
|
|
|
31
|
-
##
|
|
31
|
+
## Races with cancellation
|
|
32
32
|
|
|
33
|
-
Team
|
|
33
|
+
Team uses TeamRoot as its guard, subagents use the parent AgentRoot, and Handoff uses the routing record. On PostgreSQL, row locks on the guard and existing conditional updates order cancellation/changes against child admission. Ordinary reads on the child admission path alone did not provide this guarantee.
|
|
34
34
|
|
|
35
|
-
Handoff
|
|
35
|
+
The Handoff cancellation path first observes the child state. If the child is incomplete or absent, it locks routing and **reads the child state again**. If child admission committed while it was waiting, it discards the stale absence observation and sends public cancellation to the admitted child. Cancellation of an already terminal execution continues to act as result access.
|
|
36
36
|
|
|
37
|
-
InMemory
|
|
37
|
+
InMemory uses a shared Monitor, SQLite uses transactions and write-conflict detection, and PostgreSQL uses row locks. A conflicting SQLite transaction is not considered successful; its backend failure is handled. No distributed lease or exactly-once guarantee for external effects is added. Actual PostgreSQL waiting order is to be checked by the three new concurrency tests in examples; it must not be inferred from successful InMemory/SQLite tests.
|
|
38
38
|
|
|
39
|
-
## API
|
|
39
|
+
## API and file changes
|
|
40
40
|
|
|
41
|
-
- Agent::InitialPreparation
|
|
42
|
-
-
|
|
43
|
-
-
|
|
44
|
-
- Persistence
|
|
45
|
-
- RBS
|
|
46
|
-
-
|
|
47
|
-
-
|
|
41
|
+
- Remove Agent::InitialPreparation's `build_admitted_execution`, its three kinds of parent validation, and its parent-kind branches. Separate shared Agent admission handling from MultiAgent reservation decisions.
|
|
42
|
+
- Place the shared participation framework in `persistence/transaction.rb`, Agent admission in `agent/admission.rb`, and persistence bindings in each domain's existing `persistence/`. No new directory or independent Contract is added.
|
|
43
|
+
- Add synchronous-context `transaction_open?` to the Storage SPI. Implementations inheriting Storage::Backend receive a shared implementation. Custom SPI implementations that do not inherit it must also provide this operation. Update RBS, the SPI snapshot, and duck-typed backend validation.
|
|
44
|
+
- Unify the public type for known Persistence scope failures as `Persistence::TransactionError`; do not add an alias for the old Storage exception. Code using Storage directly continues to use the existing Storage exception.
|
|
45
|
+
- Place RBS in sig and declare participant factories, Agent admission, and MultiAgent dependencies. Track dynamic `phronomy_admission` injection in this document and at its use sites.
|
|
46
|
+
- Separate dependency analysis rules for the Execution boundary from the diagram's revision display name. Add a regression test ensuring that changing the unit name does not disable the prohibition on synchronous-backend dependencies on Execution.
|
|
47
|
+
- Preserve persisted record formats, IDs, and revision rules. No data migration is required.
|
|
48
48
|
|
|
49
|
-
##
|
|
49
|
+
## Outstanding work
|
|
50
50
|
|
|
51
|
-
`Persistence#transaction
|
|
51
|
+
`Persistence#transaction` and the combined domain-repository facade still have callers and are not fully removed in this unit. This does not add new aliases for old names to preserve compatibility, but the P01/DP04 completion conditions remain unmet. Next, move domain queries and persistence composition, then remove unnecessary entry points together with their callers.
|
|
52
52
|
|
|
53
|
-
MultiAgent
|
|
53
|
+
MultiAgent's persistence component still references Agent execution/Handoff repositories. Ownership of reservation validation has been clarified, but this does not mean that public parent/child projections, authorization queries, and result incorporation have all been encapsulated. Under the remaining P04/F02/F03 work, establish the operations Agent should expose and the persistence formats MultiAgent should own. Adding a generic metadata getter alone is not a solution.
|
|
54
54
|
|
|
55
|
-
Agent
|
|
55
|
+
Agent/Team FSM bindings, durable Workflow child coordination (P05), reconciliation of persistence outcomes across multiple records (P06), the remaining layout reorganization, and semantic reassessment of 155 pairs/393 cases also remain outstanding. The SVG for this unit depicts the implementation candidate, not a conceptual graph claiming that all cycles have been eliminated.
|
|
@@ -153,7 +153,7 @@ request deduplication or unambiguous correlation. Existing retention applies.
|
|
|
153
153
|
|
|
154
154
|
Reuse existing APIs where they meet this contract; map missing capabilities only
|
|
155
155
|
after baseline inspection. Do not invent a framework outbox or request registry.
|
|
156
|
-
See [RC-01](RECOVERY_CONTRACT_CLARIFICATIONS.md#1-rc-01
|
|
156
|
+
See [RC-01](../design/durable-semantic-coordination/RECOVERY_CONTRACT_CLARIFICATIONS.md#1-rc-01-accessing-final-results-and-discovering-executions).
|
|
157
157
|
|
|
158
158
|
### 9. Unknown commit outcome and cancellation
|
|
159
159
|
|
|
@@ -1,33 +1,33 @@
|
|
|
1
|
-
# V2 revision 2
|
|
1
|
+
# V2 revision 2 - Changes
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Updated: 2026-09-06 / Status: Accepted
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Accepted decisions reflected in this revision
|
|
6
6
|
|
|
7
|
-
|
|
|
7
|
+
| Item | Change in this revision |
|
|
8
8
|
|---|---|
|
|
9
|
-
| RC-01
|
|
10
|
-
| RC-02
|
|
11
|
-
| RC-03
|
|
12
|
-
| RC-04
|
|
13
|
-
| RC-05
|
|
9
|
+
| RC-01 Result access | Add contracts for reading status/results by exact execution ID and discovering candidates from the owner if execution is interrupted before the caller receives the ID |
|
|
10
|
+
| RC-02 Unknown persistence outcomes | Distinguish confirmed absence, read failure, CAS conflict, and unknown commit outcome; reconcile using the same reserved identity |
|
|
11
|
+
| RC-03 Wiring compatibility | Specify minimum checks for definition id/version, slot, graph, and Persistence boundary, and give precedence to committed facts |
|
|
12
|
+
| RC-04 Cancellation | Distinguish ending observation/shutdown from semantic cancellation; specify handling by child state, races, and rediscovery after restart |
|
|
13
|
+
| RC-05 Guarantee wording | Use consistent wording: reuse committed outcomes, recover with the same identity, and resolve uncertain external outcomes through existing Recovery |
|
|
14
14
|
|
|
15
|
-
ADR-029/030/031
|
|
16
|
-
|
|
17
|
-
|
|
15
|
+
The corresponding normative statements have been incorporated into ADR-029/030/031, the implementation design, the responsibility boundary review, and the README.
|
|
16
|
+
Detailed contracts and validation conditions are collected in RECOVERY_CONTRACT_CLARIFICATIONS.md and referenced across the documents.
|
|
17
|
+
The pre-approval Proposed status has been changed to Accepted. This does not request renewed approval of the new functionality.
|
|
18
18
|
|
|
19
|
-
##
|
|
19
|
+
## Correction of implementation status
|
|
20
20
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
21
|
+
Earlier implementation counts and successful static checks in the handoff document remain reports from the previous session.
|
|
22
|
+
They are not evidence that implementation was revalidated in this continuation. Only the design documents and handoff document are currently available;
|
|
23
|
+
the old overlay/apply.py/APPLY.sh/VERIFY.sh have not been recovered. The resumption procedure has also been updated to begin by recovering the actual files.
|
|
24
24
|
|
|
25
|
-
##
|
|
25
|
+
## Checks performed for this revision
|
|
26
26
|
|
|
27
|
-
-
|
|
28
|
-
-
|
|
29
|
-
- RC-01
|
|
30
|
-
- ZIP
|
|
27
|
+
- Check consistency of approval status, baseline, and cross-references in the affected documents.
|
|
28
|
+
- Correct obsolete statements that implementation was stopped pending approval and guarantee wording that could imply exactly-once external effects.
|
|
29
|
+
- Check the mapping of RC-01 through RC-05 to ADRs, implementation design, and validation conditions.
|
|
30
|
+
- Verify the ZIP layout, SHA256SUMS for all documents, and external SHA256 values for the ZIP and handoff document.
|
|
31
31
|
|
|
32
|
-
|
|
33
|
-
API
|
|
32
|
+
No code changes or RSpec runs were performed in the target repository.
|
|
33
|
+
Unverified API or exception names were not invented; mapping the requirements to the baseline was made mandatory before implementation.
|
|
@@ -6,107 +6,107 @@
|
|
|
6
6
|
> [ADR-034](../../decisions/034-handoff-runner-coordination-ownership.md).
|
|
7
7
|
> Handoff and HandoffPolicy remain in Agent at this stage.
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
9
|
+
Created: 2026-09-07. Design approved: 2026-09-06.
|
|
10
|
+
Baseline: `5472116cd99a63ec27875024c955ea82be612d6b`.
|
|
11
|
+
This is a new implementation of the approved ADR-029/030/031 and RC-01 through RC-05.
|
|
12
|
+
It does not use the old Complete Durability overlay, existing work ZIPs, or synthetic fan-out executions.
|
|
13
13
|
|
|
14
|
-
##
|
|
14
|
+
## Implementation scope
|
|
15
15
|
|
|
16
|
-
|
|
|
16
|
+
| Area | Implemented behavior |
|
|
17
17
|
|---|---|
|
|
18
|
-
| Persistence | root
|
|
19
|
-
| Handoff | Agent-domain API
|
|
20
|
-
| Orchestrator |
|
|
21
|
-
| Team | TeamRoot/TeamExecution
|
|
22
|
-
| Team
|
|
23
|
-
| Aggregate |
|
|
24
|
-
| Runtime |
|
|
25
|
-
| Recovery | framework-owned
|
|
26
|
-
|
|
|
27
|
-
|
|
28
|
-
Handoff graph
|
|
29
|
-
|
|
30
|
-
Runtime
|
|
31
|
-
|
|
32
|
-
##
|
|
33
|
-
|
|
34
|
-
|
|
|
18
|
+
| Persistence | Eight repositories in both root and transaction views; the three new records use current format `0.1`. Backend handles opaque DurableRecords and explicit identity/revision/index metadata |
|
|
19
|
+
| Handoff | Moved to the Agent-domain API. Source terminal state, Context, exact Target reservation, and responsibility transfer are persisted in one transaction. Target terminal state and routing stabilization also share one transaction |
|
|
20
|
+
| Orchestrator | Stores child ID/input/knowledge/config/outcome for static subagent Tools in the existing parent AgentExecution. Direct `dispatch_parallel`/`fan_out` calls do not create synthetic parents |
|
|
21
|
+
| Team | Persists TeamRoot/TeamExecution, tasks, worker slots, and exact assignments/outcomes using CAS. Coordinators/workers use the existing Agent engine. Scheduling retains the existing sequential approach |
|
|
22
|
+
| Internal Team operations | Applies persisted authorized Tool batches in Provider order. Retains the result of each `tool_invocation_id` and automatically reconciles `enqueue_task`/`finalize` |
|
|
23
|
+
| Aggregate | Pure/replay-safe computation. Commits canonical JSON results or errors as terminal outcomes. Recalculation is possible after a crash before persistence, but not for a persisted terminal outcome |
|
|
24
|
+
| Runtime | Adds process-local Team ownership, admission, and draining. Does not add a new Team FSM/Workflow engine |
|
|
25
|
+
| Recovery | Resumes framework-owned operations from exact facts. In batches mixed with external Tools, only external facts are resolved through the existing Recovery API |
|
|
26
|
+
| Termination and deletion | Retains cancellation/reconciliation information for exact children. `purge!` on an idle main Agent also deletes the Handoff anchor; deleting an anchor for an incomplete turn is rejected |
|
|
27
|
+
|
|
28
|
+
A Handoff graph uses the same Persistence **instance**. The original main Agent ID is the routing anchor.
|
|
29
|
+
Persisted Context is not reprojected using a new policy, and persisted worker assignments are not reselected using the current scheduler.
|
|
30
|
+
Runtime Classes/Procs, listeners, Tasks, and CancellationTokens are not persisted.
|
|
31
|
+
|
|
32
|
+
## Public entry points
|
|
33
|
+
|
|
34
|
+
| Purpose | API / return value |
|
|
35
35
|
|---|---|
|
|
36
|
-
| Agent
|
|
37
|
-
| Handoff
|
|
38
|
-
| Agent
|
|
39
|
-
| Team
|
|
40
|
-
| Team
|
|
41
|
-
| Handoff
|
|
42
|
-
|
|
|
43
|
-
| Team
|
|
44
|
-
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
Agent
|
|
50
|
-
|
|
51
|
-
`class`/`message
|
|
52
|
-
|
|
53
|
-
Handoff
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
`Team.load
|
|
59
|
-
Agent
|
|
60
|
-
Team
|
|
61
|
-
`Team.stream
|
|
62
|
-
|
|
63
|
-
## RC
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
`spec/phronomy/multi_agent/durable_coordination_spec.rb
|
|
67
|
-
|
|
68
|
-
|
|
|
36
|
+
| Agent result access | `store.execution_result(execution_id)`; a frozen Hash containing owner, status, phase, result/error, and reference IDs |
|
|
37
|
+
| Handoff result access | `store.handoff_result(source_execution_id)`; follows the exact Target of that turn. No graph/Agent hydration is required |
|
|
38
|
+
| Agent execution discovery | `store.list_executions(agent_id, after: nil, limit: 100)`; immutable execution records, both active and terminal |
|
|
39
|
+
| Team result access | `store.team_execution_result(run_id)` or `team.result(run_id)` |
|
|
40
|
+
| Team execution discovery | `store.list_team_executions(team_id, after: nil, limit: 100)` or `team.executions(...)` |
|
|
41
|
+
| Handoff execution/recovery | `Agent::HandoffRunner.new(main_agent:, handoffs:).invoke(input, config: {})`; uses the persisted reservation and input if an incomplete turn exists |
|
|
42
|
+
| Static child recovery | `Orchestrator#resume(execution_id, config: {})` |
|
|
43
|
+
| Team creation/recovery | `team_definition id:, version:`, `create(team_id:, persistence:)`, `load(team_id, persistence:, on_event:)`, `resume(run_id)` |
|
|
44
|
+
| Explicit cancellation | `team.cancel(run_id)` / `handoff_runner.cancel(execution_id)`; existing Agent operations, including Orchestrator, use `config[:cancellation_token]` |
|
|
45
|
+
|
|
46
|
+
Lists are ordered lexicographically by semantic ID; `after` is an exclusive ID cursor, and `limit` is a positive integer.
|
|
47
|
+
This does not imply chronological ordering or unique correspondence to a request. Applications match candidates against their own correlation information.
|
|
48
|
+
|
|
49
|
+
Agent result status uses existing Symbols; Team result status uses canonical Strings.
|
|
50
|
+
The default Team aggregate result is also canonical JSON: Hash keys are Strings, and errors are data such as
|
|
51
|
+
`class`/`message`, not exception objects. Top-level assignment keys and task keys passed to aggregate are Symbols.
|
|
52
|
+
|
|
53
|
+
An unstarted Handoff Target reservation is identified by `status: :active, phase: :target_pending, reserved: true`.
|
|
54
|
+
Explicit cancellation of an unstarted Target preserves its reserved ID; a later turn never substitutes for the result of an earlier turn.
|
|
55
|
+
Absence produces `Persistence::NotFoundError`; read/decode failures produce their actual errors.
|
|
56
|
+
No facility to restore deleted results or retain them indefinitely has been added.
|
|
57
|
+
|
|
58
|
+
`Team.load` hydrates Team facts only. Child execution/recovery starts through `resume`.
|
|
59
|
+
Agent `load` retains its existing Recovery contract. Use the Persistence access APIs above when only results are needed.
|
|
60
|
+
Team's `on_event` is passed to hidden Agents to receive required Recovery/approval events.
|
|
61
|
+
`Team.stream` provides Runtime notifications of committed assignments; it adds no notification-delivery guarantee.
|
|
62
|
+
|
|
63
|
+
## RC mapping
|
|
64
|
+
|
|
65
|
+
Paths are relative to the repository root. The shared additional fault specs are in
|
|
66
|
+
`spec/phronomy/multi_agent/durable_coordination_spec.rb`.
|
|
67
|
+
|
|
68
|
+
| Requirement | Main implementation | Validation evidence |
|
|
69
69
|
|---|---|---|
|
|
70
|
-
| RC-01-A/B | `Persistence#execution_result` / `list_executions
|
|
71
|
-
| RC-01-C | `Persistence#handoff_result
|
|
72
|
-
| RC-02-A |
|
|
73
|
-
| RC-02-B/C |
|
|
74
|
-
| RC-03-A | Team definition
|
|
75
|
-
| RC-03-B |
|
|
76
|
-
| RC-04-A |
|
|
77
|
-
| RC-04-B/C/D | Team
|
|
78
|
-
| RC-04-E | Source terminal link
|
|
79
|
-
| RC-05 |
|
|
80
|
-
|
|
81
|
-
`lib/phronomy/testing/persistence_contract/coordination_repositories.rb
|
|
82
|
-
|
|
83
|
-
raw SPI/API
|
|
84
|
-
logical-operation tracing
|
|
85
|
-
|
|
86
|
-
##
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
-
|
|
92
|
-
-
|
|
93
|
-
-
|
|
94
|
-
|
|
95
|
-
-
|
|
96
|
-
|
|
97
|
-
-
|
|
98
|
-
InMemory
|
|
99
|
-
-
|
|
100
|
-
durable
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
callback outbox/ACK
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
##
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
70
|
+
| RC-01-A/B | `Persistence#execution_result` / `list_executions`, and corresponding Team APIs | Reads active/terminal candidates, pagination, and results in a reconstructed environment without loading the owner; does not invoke Providers or add ownership registrations |
|
|
71
|
+
| RC-01-C | `Persistence#handoff_result`, read-only materialization | Reservation access without graph/owner, read failures, and NotFound for purged results. Callback policy is also covered by the existing `stream_callback_error_policy_spec.rb` |
|
|
72
|
+
| RC-02-A | Existing F1 readback during Agent preparation, `reconcile_terminal_error`, Team `admit`/`update` | Lost acknowledgements immediately after each Team revision commit and Source transfer; reuse of committed worker/child outcomes |
|
|
73
|
+
| RC-02-B/C | Exact reservation reconciliation, atomic admission/CAS, bounded readback | Distinguishes read failure from absence. No dispatch after a failed readback following Team admission. Backend contracts check stale CAS, duplicate active records, and rollback across eight repositories |
|
|
74
|
+
| RC-03-A | Team definition snapshots, static child slot definitions, Handoff graph/Target matching | Fails closed on worker-version mismatch or missing Target/graph. Existing Handoff integration specs reject a different Persistence instance |
|
|
75
|
+
| RC-03-B | Immutable Context/input/knowledge/assignment/outcome | Uses persisted HandoffContext even when the current policy changes. Preserves worker results, static child results, and knowledge metadata |
|
|
76
|
+
| RC-04-A | Existing Task waiting/Runtime shutdown contracts | `task_spec.rb`, `agent/acs16_task_quiescence_spec.rb`, and Runtime/admission specs. Runtime reconstruction tests introduce no implicit cancellation |
|
|
77
|
+
| RC-04-B/C/D | Team cancellation flags, exact Handoff cancellation, Agent child-admission conditions, existing terminal barriers | Preserves reserved worker/Target IDs without starting them. A parent with an active child awaiting external facts remains active, persists cancellation information, and retains it after restart. Checked together with existing admission/physical-quiescence specs |
|
|
78
|
+
| RC-04-E | Source terminal link and Target cancellation; responsibility remains with Target | Cancellation after transfer, restart, and a later turn do not return responsibility to Source; historical reserved IDs and cancellation results are preserved |
|
|
79
|
+
| RC-05 | Separation of callbacks/external effects from semantic records | Mixed external/framework Tool batches resolve only external facts and do not rerun completed children. Application is not asked to determine facts about internal `finalize` |
|
|
80
|
+
|
|
81
|
+
The new shared examples in `lib/phronomy/testing/persistence_contract/coordination_repositories.rb`
|
|
82
|
+
run through `phronomy/testing/persistence_contract`, which is also exposed to external backends.
|
|
83
|
+
Existing guards for raw SPI/API snapshots/RBS, removal of old Handoff constants, the EventLoop single writer/causal barrier,
|
|
84
|
+
and logical-operation tracing are preserved.
|
|
85
|
+
|
|
86
|
+
## Validation scope and limitations
|
|
87
|
+
|
|
88
|
+
The measured environment is Ruby 3.3.6. Gem versions are recorded in the distribution ZIP's `verification/gems.txt`.
|
|
89
|
+
See the accompanying verification records for commands, results, and logs measured against the distributed files.
|
|
90
|
+
|
|
91
|
+
- Ordinary RSpec runs exclude integration tags requiring connections to external LLMs.
|
|
92
|
+
- Selected Handoff/Orchestrator/Team integration tests run with WebMock.
|
|
93
|
+
- Added F4 tests model recovery by copying committed DurableRecords and using a new Backend and Runtime.
|
|
94
|
+
They do not demonstrate forced termination of a real OS process or fsync to physical storage.
|
|
95
|
+
- Separate suites using live LLMs, Redis, PostgreSQL, OpenTelemetry, and similar dependencies are outside this measurement.
|
|
96
|
+
There are 61 pending cases: 59 with optional dependencies/services unconfigured and two existing obsolete cases.
|
|
97
|
+
- F4 durability and exclusion across multiple processes for external backends depend on the backend and deployment contracts.
|
|
98
|
+
InMemory itself does not guarantee persistence after process termination.
|
|
99
|
+
- Semantic cancellation does not roll back external effects. Token objects are Runtime-only.
|
|
100
|
+
Committed durable cancellation flags/facts are retained, and uncertain external operations are reconciled through existing Recovery.
|
|
101
|
+
Waiting for facts/approval is not converted into failure that forgets a child; control returns through `ExecutionRehydrationRequiredError`.
|
|
102
|
+
|
|
103
|
+
The framework reuses committed outcomes and recovers incomplete executions with the same semantic identity.
|
|
104
|
+
It adds no callback outbox/ACK, global generic class registry, Proc/Class persistence, distributed transaction,
|
|
105
|
+
or second execution engine dedicated to Team.
|
|
106
|
+
|
|
107
|
+
## Package
|
|
108
|
+
|
|
109
|
+
The package includes complete files and a deletion manifest. Application checks the baseline and pre/post-application hashes.
|
|
110
|
+
New Class locations follow Zeitwerk naming conventions; the old overlay's decorator ignore is unnecessary.
|
|
111
|
+
The old `MultiAgent::Handoff*`, `Runner`, `Coordinator`, and `CoordinationState` implementations are removed.
|
|
112
|
+
See `README_APPLY_JA.md` at the distribution root for application, dependencies, and VERIFY procedures.
|
|
@@ -1,179 +1,178 @@
|
|
|
1
|
-
# V2
|
|
1
|
+
# V2 Recovery Contract Clarifications - Approved Addendum
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Updated: 2026-09-06 / Document revision: V2 revision 2
|
|
4
4
|
|
|
5
|
-
## 0.
|
|
5
|
+
## 0. Purpose and authority
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
ADR-029/030/031
|
|
9
|
-
|
|
10
|
-
|
|
7
|
+
This addendum is a normative implementation contract reflecting the user's approval of five additions to V2.
|
|
8
|
+
Apply it together with ADR-029/030/031 and Implementation Design V2.
|
|
9
|
+
It preserves the original V2 responsibility boundaries while clarifying result access, unknown persistence outcomes, wiring compatibility, cancellation, and guarantee wording.
|
|
10
|
+
Where an earlier statement on the same issue differs, these clarifications take precedence. They do not otherwise replace existing ADR contracts.
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
12
|
+
The baseline remains `5472116cd99a63ec27875024c955ea82be612d6b`.
|
|
13
|
+
This is specification approval, not evidence of implementation completion or successful tests.
|
|
14
|
+
Public method names, exception names, and mappings to the existing cancellation implementation will be finalized after inspecting the baseline.
|
|
15
|
+
Requirement IDs in this document are for traceability; they are not new Runtime IDs, persistent IDs, or APIs.
|
|
16
16
|
|
|
17
|
-
## 1. RC-01
|
|
17
|
+
## 1. RC-01: Accessing final results and discovering executions
|
|
18
18
|
|
|
19
|
-
###
|
|
19
|
+
### Required contract
|
|
20
20
|
|
|
21
|
-
- Application
|
|
22
|
-
-
|
|
23
|
-
- Handoff
|
|
24
|
-
- admission
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
-
|
|
21
|
+
- Application can obtain the owner identity, execution state, and committed result or error by semantic execution ID through read-only access.
|
|
22
|
+
- This covers AgentExecution and TeamExecution. Handoff/Orchestrator use existing routing anchors, parent executions, and reserved child/Target IDs; they do not create a new execution entity just for result access.
|
|
23
|
+
- Handoff identifies the Target outcome associated with the specified execution. The latest active Agent result from a later turn must not substitute for an earlier invocation's result.
|
|
24
|
+
- Provide a public path to discover execution candidates from a known agent_id/team_id, covering an interruption after admission commits but before Application receives the execution ID. Include terminal as well as active executions.
|
|
25
|
+
- Result access and candidate enumeration must not invoke Providers/Tools, continue Agent execution, redeliver callbacks, or acquire ownership. Distinguish these operations from operations that initiate recovery.
|
|
26
|
+
- Distinguish an unresolved result, absence, and inability to read. Do not translate Persistence failures or result-materialization failures into no execution, in progress, or successful completion without a result.
|
|
27
|
+
- Read basic state and committed results from persisted records. Do not require the graph/Procs needed for continuation merely to access results. Preserve existing codec/schema compatibility requirements.
|
|
28
28
|
|
|
29
|
-
###
|
|
29
|
+
### Scope limitations
|
|
30
30
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
Application
|
|
31
|
+
Candidate discovery does not guarantee automatic unique correspondence to an Application request or exactly-once submission.
|
|
32
|
+
When multiple candidates exist, do not select one merely because it has the latest timestamp; Application must match its own correlation information.
|
|
33
|
+
Application-specific request IDs, outboxes, and deduplication remain Application responsibilities. Do not add generic idempotency infrastructure solely to meet result-access requirements.
|
|
34
34
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
35
|
+
Preserve existing retention/deletion contracts. Restoring deleted results, indefinite retention, and a new history-management service are not required.
|
|
36
|
+
Inspect existing API/SPI behavior and map list scope, ordering, pagination, and similar concerns to the smallest necessary public path.
|
|
37
|
+
Add only capabilities that existing APIs cannot provide; do not expose internal repositories directly as the public contract.
|
|
38
38
|
|
|
39
|
-
## 2. RC-02
|
|
39
|
+
## 2. RC-02: Distinguishing absence, conflicts, and unknown persistence outcomes
|
|
40
40
|
|
|
41
|
-
###
|
|
41
|
+
### Shared decision rules
|
|
42
42
|
|
|
43
|
-
|
|
|
43
|
+
| Observation | Permitted decision or action |
|
|
44
44
|
|---|---|
|
|
45
|
-
|
|
|
46
|
-
| exact ID
|
|
47
|
-
| exact ID
|
|
48
|
-
|
|
|
49
|
-
| write
|
|
50
|
-
|
|
|
45
|
+
| A successful authoritative read confirms that the reserved ID is absent | Check the parent's latest state, reservation, and cancellation conditions, then attempt admission with the same reserved ID |
|
|
46
|
+
| The exact ID is confirmed nonterminal | Follow the existing Recovery contract for the same execution |
|
|
47
|
+
| The exact ID is confirmed terminal | Use the persisted outcome; do not create a replacement execution |
|
|
48
|
+
| Read timeout / I/O failure / record decode failure | Preserve state and follow existing error/retry contracts; do not treat the failure as absence |
|
|
49
|
+
| Commit outcome is unknown, for example after a lost write acknowledgement | Retain the same operation identity and reserved ID for readback; do not create another ID or assignment before confirmation |
|
|
50
|
+
| A definite revision/admission conflict | Reread the latest authoritative facts and validate consistency with the reservation, owner, and input; do not treat the conflict as success by itself |
|
|
51
51
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
52
|
+
Readback consistency must satisfy the existing Persistence contract that protects admission/CAS.
|
|
53
|
+
Cache/index discrepancies and read failures must not justify new admission.
|
|
54
|
+
Use existing atomic admission/CAS to prevent races between confirming absence and admission.
|
|
55
|
+
Start external semantic work only after admission success is confirmed.
|
|
56
56
|
|
|
57
|
-
|
|
58
|
-
Team admission/enqueue/finalize/assignment/worker outcome/terminal
|
|
59
|
-
Team-owned enqueue/finalize
|
|
57
|
+
Scope: Source Handoff transfer, Target admission/stabilization, parent child reservation/outcome,
|
|
58
|
+
and Team admission/enqueue/finalize/assignment/worker outcome/terminal state.
|
|
59
|
+
Team-owned enqueue/finalize retain the existing policy of fact reconciliation using a stable tool_invocation_id.
|
|
60
60
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
61
|
+
While an unknown outcome remains unresolved, do not advance to the next semantic operation based on unconfirmed local assumptions.
|
|
62
|
+
Return control through existing Persistence error/retry paths instead of waiting synchronously without a bound.
|
|
63
|
+
Do not add manual resolution that requires Application to invent storage facts.
|
|
64
|
+
Reuse existing Agent/Persistence handling of unknown outcomes; do not create a second transaction engine dedicated to coordination.
|
|
65
65
|
|
|
66
|
-
## 3. RC-03
|
|
66
|
+
## 3. RC-03: Minimum wiring compatibility for recovery
|
|
67
67
|
|
|
68
|
-
###
|
|
68
|
+
### Required checks
|
|
69
69
|
|
|
70
|
-
|
|
|
70
|
+
| Subject | Checks required before continuation |
|
|
71
71
|
|---|---|
|
|
72
|
-
| Agent/Team
|
|
73
|
-
| Orchestrator child |
|
|
74
|
-
| Handoff | original main anchor
|
|
75
|
-
| Team worker/coordinator | Team lineage
|
|
72
|
+
| Agent/Team definition | Compare the persisted definition id/version with the current definition; require equality unless an existing explicit compatibility/migration contract permits otherwise |
|
|
73
|
+
| Orchestrator child | Match the persisted slot, the definition resolved from static subagent registration, reserved agent_id/execution_id, and owner |
|
|
74
|
+
| Handoff | Match the original main anchor, persisted active/Target IDs, required graph connections, and the same Persistence instance/domain |
|
|
75
|
+
| Team worker/coordinator | Match Team lineage, the persisted worker slot and definition, reserved Agent/execution IDs, and the persisted assignment |
|
|
76
76
|
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
77
|
+
If a required registration or Target is missing, a definition is incompatible, or the Persistence boundary differs, fail closed without starting semantic work.
|
|
78
|
+
Use existing configuration/rehydration error contracts and make the affected identity and type of missing/inconsistent information clear from the error.
|
|
79
|
+
Do not require execution wiring unnecessary for read-only result access (RC-01).
|
|
80
80
|
|
|
81
|
-
###
|
|
81
|
+
### Committed facts take precedence
|
|
82
82
|
|
|
83
|
-
-
|
|
84
|
-
-
|
|
85
|
-
-
|
|
86
|
-
-
|
|
87
|
-
-
|
|
83
|
+
- Do not reproject committed HandoffContext using the current HandoffPolicy.
|
|
84
|
+
- Do not replace committed child input/config with current defaults.
|
|
85
|
+
- Do not reselect committed assignments using the current scheduler.
|
|
86
|
+
- Do not recompute committed child/worker/final aggregate outcomes.
|
|
87
|
+
- Uncommitted scheduler/aggregate computations may rerun under the existing V2 replay-safe contract. Application must preserve semantic compatibility with the persisted inputs.
|
|
88
88
|
|
|
89
|
-
Phronomy
|
|
90
|
-
|
|
91
|
-
version
|
|
92
|
-
Proc/Class
|
|
89
|
+
Phronomy can check declared identity/version and structure, not semantic equivalence of Ruby code.
|
|
90
|
+
Application is responsible for not introducing incompatible implementations under an unchanged version.
|
|
91
|
+
Increasing a version alone does not automatically enable recovery of old executions; the corresponding definition or an existing explicit migration contract is required.
|
|
92
|
+
Do not add Proc/Class persistence, source hashes, policy descriptors, or a global generic class registry.
|
|
93
93
|
|
|
94
|
-
## 4. RC-04
|
|
94
|
+
## 4. RC-04: Ending observation and semantic cancellation
|
|
95
95
|
|
|
96
|
-
###
|
|
96
|
+
### Distinguish operations
|
|
97
97
|
|
|
98
|
-
|
|
|
98
|
+
| Operation or state | Contract |
|
|
99
99
|
|---|---|
|
|
100
|
-
| Application
|
|
101
|
-
| Runtime shutdown / process loss |
|
|
102
|
-
|
|
|
103
|
-
| recovery resolution / approval
|
|
100
|
+
| Application stops waiting, a connection is lost, or observation times out | This alone is not semantic cancellation of the durable execution |
|
|
101
|
+
| Runtime shutdown / process loss | This alone does not establish semantic cancellation; preserve execution and recoverability under existing shutdown/draining contracts |
|
|
102
|
+
| Explicit semantic cancellation request | Map it to the target owner/run and reserved executions under the existing Agent cancellation contract |
|
|
103
|
+
| Waiting for recovery resolution / approval | Preserve existing V2 rehydration paths; do not convert waiting into failure or automatic cancellation |
|
|
104
104
|
|
|
105
|
-
|
|
106
|
-
|
|
105
|
+
APIs that already request semantic cancellation, such as explicit cancellation of an existing Task, retain that contract.
|
|
106
|
+
Do not treat them as equivalent to merely ending observation. Record concrete public API mappings when inspecting the baseline.
|
|
107
107
|
|
|
108
|
-
###
|
|
108
|
+
### Applying cancellation to child executions
|
|
109
109
|
|
|
110
|
-
|
|
|
110
|
+
| Child state | Behavior after semantic cancellation of the parent run is accepted |
|
|
111
111
|
|---|---|
|
|
112
|
-
|
|
|
113
|
-
|
|
|
114
|
-
|
|
|
112
|
+
| Reserved, not started | Stop new dispatch owned by the current parent run; retain reservation information and do not start a child just to cancel it |
|
|
113
|
+
| Running, or racing with admission | Check the exact reserved ID's state and apply existing Agent cancellation; discarding a local Task alone does not complete cancellation handling |
|
|
114
|
+
| Terminal | Preserve the durable outcome; do not rewrite historical success/failure as cancellation or rerun it for compensation |
|
|
115
115
|
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
restart
|
|
121
|
-
|
|
116
|
+
Handle races between parent cancellation and child admission using the latest parent-run state and existing admission contracts.
|
|
117
|
+
Reconcile an already admitted child under the running-child rules; do not create a child with a different ID.
|
|
118
|
+
Map the ordering of parent terminalization and child settlement to existing Agent cancellation/terminal-barrier contracts.
|
|
119
|
+
If a child is incomplete, retain its exact ID and required cancellation/reconciliation state.
|
|
120
|
+
Require rediscovery through existing recovery paths after restart; do not claim that all parent work is complete while forgetting an unhandled child.
|
|
121
|
+
Do not add a new public terminal status or a separate cancellation scheduler solely for this addendum.
|
|
122
122
|
|
|
123
|
-
|
|
124
|
-
Handoff
|
|
125
|
-
|
|
126
|
-
|
|
123
|
+
Limit cancellation to children owned by the affected parent run; it must not affect other executions of a shared Agent or later Team runs.
|
|
124
|
+
A Handoff Source is handed_off after transfer commits. Cancelling Source later must not be treated as reversing the transfer.
|
|
125
|
+
Map explicit cancellation of the current Handoff turn to the relevant Target execution using persisted routing/reservations.
|
|
126
|
+
Do not return active responsibility to the original main Agent because observation ends or cancellation occurs.
|
|
127
127
|
|
|
128
|
-
|
|
129
|
-
|
|
128
|
+
Cancellation of external Providers/Tools does not guarantee reversal of side effects. Resolve uncertain outcomes through the existing Agent Recovery contract.
|
|
129
|
+
If existing mechanisms cannot satisfy the required ordering and rediscovery without a second execution engine or similar addition, report a Stop Condition.
|
|
130
130
|
|
|
131
|
-
## 5. RC-05
|
|
131
|
+
## 5. RC-05: Consistent durability guarantee wording
|
|
132
132
|
|
|
133
|
-
>
|
|
134
|
-
>
|
|
133
|
+
> Reuse committed durable outcomes. Recover incomplete executions with the same semantic identity.
|
|
134
|
+
> Resolve uncertain outcomes of external Provider/Tool operations under the existing Agent Recovery contract.
|
|
135
135
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
callback
|
|
136
|
+
Starting only when execution is confirmed not to have started refers to framework-owned execution admission.
|
|
137
|
+
It does not mean that no request ever reached an external system, nor does it guarantee exactly-once external side effects.
|
|
138
|
+
Recovering an incomplete execution with the same ID also does not mean unconditionally resending every internal Provider/Tool call.
|
|
139
|
+
Loss of a callback or local Task, or an observation timeout, must not justify rerunning semantic work.
|
|
140
140
|
|
|
141
|
-
## 6.
|
|
141
|
+
## 6. Validation conditions and implementation mapping
|
|
142
142
|
|
|
143
|
-
|
|
144
|
-
|
|
143
|
+
The following are behavioral validation conditions, not a required count of new spec files.
|
|
144
|
+
Where existing specs verify a contract, record that evidence and add only missing cases.
|
|
145
145
|
|
|
146
|
-
| ID |
|
|
146
|
+
| ID | Validation scenario | Required outcome |
|
|
147
147
|
|---|---|---|
|
|
148
|
-
| RC-01-A | terminal commit
|
|
149
|
-
| RC-01-B | admission
|
|
150
|
-
| RC-01-C | graph/listener
|
|
151
|
-
| RC-02-A |
|
|
152
|
-
| RC-02-B | read
|
|
153
|
-
| RC-02-C |
|
|
154
|
-
| RC-03-A | subagent
|
|
155
|
-
| RC-03-B |
|
|
156
|
-
| RC-04-A |
|
|
157
|
-
| RC-04-B |
|
|
158
|
-
| RC-04-C |
|
|
159
|
-
| RC-04-D |
|
|
160
|
-
| RC-04-E | Handoff transfer
|
|
161
|
-
| RC-05-A |
|
|
162
|
-
|
|
163
|
-
baseline
|
|
164
|
-
|
|
165
|
-
focused
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
## 7.
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
Proc/Class serialization
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
## 8.
|
|
176
|
-
|
|
177
|
-
2026-09-07
|
|
178
|
-
|
|
179
|
-
本追補の責務境界と必須契約は変更しない。
|
|
148
|
+
| RC-01-A | Process loss after terminal commit and before callback | Read the same result by exact ID without rerunning semantic work or callbacks |
|
|
149
|
+
| RC-01-B | Caller is lost before the admission acknowledgement; execution later becomes terminal | Discover candidates from owner identity; do not arbitrarily choose one when multiple candidates exist |
|
|
150
|
+
| RC-01-C | Access results without a graph/listener, or inject result read/decode failure | Require no unnecessary wiring; do not disguise an access failure as success or absence |
|
|
151
|
+
| RC-02-A | Lose the acknowledgement immediately after each successful semantic commit | Adopt the existing fact through readback; create neither another ID nor duplicate assignments |
|
|
152
|
+
| RC-02-B | Independently inject read failure, authoritative absence, and CAS conflict | Keep the states distinct; execute only after admission success is confirmed |
|
|
153
|
+
| RC-02-C | Readback also fails after an unknown outcome | Preserve state and return control; do not wait synchronously without a bound or create a new execution |
|
|
154
|
+
| RC-03-A | Remove subagent registration, mismatch definition version, or omit Target | Fail closed before continuation; do not substitute another definition or Target |
|
|
155
|
+
| RC-03-B | Recover with compatible current wiring | Do not recompute committed Context/input/assignment/outcome |
|
|
156
|
+
| RC-04-A | End waiting, shut down Runtime, or lose the process | Do not establish implicit semantic cancellation |
|
|
157
|
+
| RC-04-B | Parent cancellation with an unstarted/active/terminal child | Follow state-specific rules and preserve exact IDs and committed outcomes |
|
|
158
|
+
| RC-04-C | Race parent cancellation against child admission/terminal state | Do not lose the child; remain consistent with existing cancellation/terminal barriers |
|
|
159
|
+
| RC-04-D | Lose the process at each commit boundary after a cancellation request | Rediscover and reconcile incomplete children of the same run through recovery paths |
|
|
160
|
+
| RC-04-E | End observation or explicitly cancel after Handoff transfer | Do not roll responsibility back to Source; apply cancellation only to the relevant Target execution |
|
|
161
|
+
| RC-05-A | Independently inject an uncertain external Tool effect and a lost callback | Use existing Recovery for the former and committed-result access for the latter; never rerun blindly |
|
|
162
|
+
|
|
163
|
+
When integrating with the baseline, record the public API/SPI, implementation locations, and existing/additional specs for each RC ID in a mapping table.
|
|
164
|
+
In particular, do not mark result-discovery APIs, compatible-version handling, or cancellation/terminal barriers complete using unverified method names.
|
|
165
|
+
Successful focused, backend, fault, and full-suite runs require actual measurement on the target checkout.
|
|
166
|
+
They have not been run at the time of this document revision.
|
|
167
|
+
|
|
168
|
+
## 7. Responsibilities that remain out of scope
|
|
169
|
+
|
|
170
|
+
Callback outbox/ACK, a terminal-delivery index, synthetic executions for standalone fan-out,
|
|
171
|
+
Proc/Class serialization, a global generic registry, distributed transactions across independent Persistence instances,
|
|
172
|
+
and a second execution engine dedicated to Team remain out of scope.
|
|
173
|
+
Public result access does not replace Application notification delivery or deduplication of external effects.
|
|
174
|
+
|
|
175
|
+
## 8. Implementation mapping
|
|
176
|
+
|
|
177
|
+
See [IMPLEMENTATION_REPORT.md](IMPLEMENTATION_REPORT.md) for the implementation, public API/SPI, and validation scope as of 2026-09-07.
|
|
178
|
+
The responsibility boundaries and required contracts in this addendum remain unchanged.
|
data/lib/phronomy/version.rb
CHANGED
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.30.
|
|
4
|
+
version: 0.30.1
|
|
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-10-
|
|
11
|
+
date: 2026-10-24 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: ruby_llm
|