phronomy 0.35.1 → 0.35.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 2a4e1f6acc08dbb7935eda1e96414206533947e2f058f8bcf5c42edc09476785
4
- data.tar.gz: 6c12e888f0f332c4528a0f7e836549cf9fd0972ba9dbe8e504e6b013f53326e8
3
+ metadata.gz: fd730052ab22e489edccab8719c26d5f25e66f15d798a35e7f6dd35ce2864033
4
+ data.tar.gz: 31f924ae82bfc4206ffe151396c9c6ffed809a68ede9f968a5b6c4607c4d2629
5
5
  SHA512:
6
- metadata.gz: b2c5073c3c843cd35b13af8a6ab4261d3f06fe4a778a4d26515a8ee6e34e529e81098feacb7a73c4f2a9ad8bb5b7c88c825f93b8a8eb166a01638c78ea764b70
7
- data.tar.gz: c454670df102b097412e406422668b0a3055fb6bedb416fac9b1775d4db529973699e5911671afd29dd62862ae1fe2faf4ce8044c8813c0eada5287a47cba9be
6
+ metadata.gz: 8e91585690b00f9566db0143fb56dd34961658c4b3c8c86c0131379b5922dc96458aecadd56f5a6323e36cb5f0041ff2c44030449ca38b26dcdd7d048f2ecc0c
7
+ data.tar.gz: 01cf02a781f981c892c1e4d4b64e2d3b66c9aed0698a55f2546d2afd5aec9bf4107afc70f39a7a0b4a862662037b34bd1f086453e466b7a10d009bb7003dc65f
data/CHANGELOG.md CHANGED
@@ -12,6 +12,38 @@ Release history for 0.14.0 and earlier is archived in
12
12
 
13
13
  ## [Unreleased]
14
14
 
15
+ ## [0.35.2] - 2026-11-18
16
+
17
+ ### Fixed
18
+
19
+ - Release completed member Agents in default SharedState coordination through
20
+ the same lifecycle handling used by custom sharing. Normal approval waits stay
21
+ live; invocation and release failures retain their original causes and the
22
+ member handle when cleanup needs attention.
23
+ - Keep Runtime deadline notifications active while accepted work drains during
24
+ shutdown, including queued Blocking operations and standalone fan-out results.
25
+ A delayed worker result cannot win merely because its timer driver stopped
26
+ before the worker pool drained.
27
+
28
+ ### Changed
29
+
30
+ - Report incomplete Runtime cleanup if the finite shutdown budget expires with
31
+ accepted timer callbacks still pending. No callback fires early to simulate
32
+ cancellation, and no worker thread is forcibly interrupted. Default Runtime
33
+ replacement still requires complete cleanup.
34
+ - Reconcile P5 progress with the published v0.35.0 and examples acceptance, and
35
+ identify the old execution-boundary proposal as historical documentation.
36
+
37
+ ### Compatibility and verification
38
+
39
+ - Public signatures, dependency requirements and current saved formats are
40
+ unchanged. The existing `cleanup_complete?` predicate now remains false when
41
+ the shutdown budget leaves accepted timer callbacks unfinished, so a default
42
+ Runtime cannot be replaced after incomplete cleanup.
43
+ - This core release does not claim new published-gem examples, live LLM or SQL
44
+ acceptance, or resolution of the previously observed LM Studio/gpt-oss
45
+ PEG-format failure root cause. Those checks remain separate follow-up work.
46
+
15
47
  ## [0.35.1] - 2026-11-18
16
48
 
17
49
  ### Fixed
data/README.md CHANGED
@@ -37,7 +37,7 @@ tracking `main` directly.
37
37
 
38
38
  See [Features and Application Programming Interface (API) stability](docs/features.md) for the full feature matrix.
39
39
 
40
- The following table describes the application APIs available in v0.35.1.
40
+ The following table describes the application APIs available in v0.35.2.
41
41
  The public persistence resource catalogs are available starting with v0.35.0.
42
42
  The sharing, Tool composition and Context budgeting operations remain
43
43
  Experimental; their introduction version is shown below.
@@ -60,7 +60,7 @@ the current saved representation.
60
60
  | `Persistence::Migration::InitialFormatMigration` | Removed (v0.34.0) | The pre-S3 conversion API is retired without a replacement. Current domain codecs and the separate Unit4 snapshot migration remain. [Legacy-format cleanup](docs/migrations/legacy-format-removal.md) |
61
61
  | `Context::ContextPolicyInput#input_token_limit / #with_input_token_limit` and protected `ContextPolicy#estimate_tokens` | Experimental (since v0.33.0) | Inspect and constrain selection budgets and estimate candidate content through Context-owned operations. [Policy budgeting](docs/context-policy-budgeting.md) |
62
62
  | `Agent::Base.with_tools(definitions, id:, version:)` | Experimental (since v0.33.0) | Derive an Agent class with a complete replacement Tool map and explicit definition identity while preserving Phronomy authoring settings and filters. [Tool composition](docs/shared-state-sharing.md#deriving-an-agent-with-a-complete-tool-set) |
63
- | `MultiAgent::SharedState.sharing(provider, id:, version:)`, `SharedState::Binding` and `SharedState::MemberLifecycleError` | Experimental (since v0.33.0) | Connect application-owned shared data and Tools to sequential coordination through a synchronous invocation-scoped provider. [Custom sharing contract and example](docs/shared-state-sharing.md) |
63
+ | `MultiAgent::SharedState.sharing(provider, id:, version:)`, `SharedState::Binding` and `SharedState::MemberLifecycleError` | Experimental (since v0.33.0) | Sequential coordination releases its terminal member Agents in both default and custom modes; an optional invocation-scoped provider supplies application-owned data and Tools. [Sharing and member lifetime contract](docs/shared-state-sharing.md) |
64
64
  | `Tool::Base#approval_display(arguments:, facts:)` | Beta (since v0.33.0) | The Tool selects the arguments and derived facts a person can see in an approval request. [Approval display](docs/runtime-and-concurrency.md#tool-approval-display) |
65
65
  | `Runtime#shutdown` result predicates `cleanup_complete?` and `clean?` | Beta | Check resource release with `cleanup_complete?`; `clean?` additionally requires a graceful shutdown. The obsolete `success?` alias is removed in v0.34.0. [Cleanup migration](docs/migrations/cleanup-audit.md#runtime-cleanup-completion) |
66
66
  | `Phronomy::EventLoopReentrancyError` | Beta | Raised when a synchronous operation would block the EventLoop control thread. The obsolete `SchedulerReentrancyError` subclass is removed in v0.34.0. [Cleanup migration](docs/migrations/cleanup-audit.md#eventloop-reentrancy-errors) |
data/SECURITY.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  | Version | Supported |
6
6
  |---------|-----------|
7
- | 0.35.1 (latest release) | ✅ |
7
+ | 0.35.2 (latest release) | ✅ |
8
8
  | Older versions | ❌ — please upgrade |
9
9
 
10
10
  Only the latest released version of `phronomy` receives security patches. If you
@@ -1,7 +1,22 @@
1
- # Execution boundary candidate (unapplied)
1
+ # Execution boundary prototype (historical)
2
2
 
3
- Base: main 653e255a34fe4062d4beca47530e084fdd3a6ba9.
4
- This is an unpublished prototype for source-derived architecture review.
3
+ This document preserves an earlier source-derived design proposal, including
4
+ its original group names and compatibility decisions. It is not a pending
5
+ implementation plan or the authority for the current source layout.
6
+
7
+ For example, the Workflow phase compiler and neutral execution values are
8
+ present in the current implementation, while later refinements changed the
9
+ prototype's grouping and placement. Use [Phronomy Architecture](architecture.md)
10
+ and the current source diagram for the reconciled responsibilities.
11
+
12
+ Original prototype base: main 653e255a34fe4062d4beca47530e084fdd3a6ba9.
13
+ The proposal below is retained as history, not a current public API guide.
14
+
15
+ ## Recorded proposal
16
+
17
+ The prototype separated result values from concrete execution connections.
18
+ For example, Engine and Services could share TaskResult without making those
19
+ values acquire Runtime or invoke operation-submission services.
5
20
 
6
21
  TaskResult, Outcome, result composition, physical completion and ScopeState
7
22
  belong to Execution Results. They depend on Contracts and Common, without
@@ -16,7 +31,11 @@ terminal state. FSMSession retains terminal detection and persistence gating.
16
31
  TerminalDecision is an execution contract, independent of Workflow and FSM
17
32
  state vocabulary.
18
33
 
19
- ## Intentional compatibility changes
34
+ ## Compatibility decisions recorded in the prototype
35
+
36
+ The prototype moved execution-control adaptation out of shared values and
37
+ removed obsolete internal entry points. For example, InvocationContext kept
38
+ the supplied deadline value while the invoking service attached its timer.
20
39
 
21
40
  * InvocationContext#effective_timeout_token and #effective_cancellation_token
22
41
  are removed. Although annotated private, both occurred in the Stable API
@@ -637,9 +637,31 @@ been cancelled or timed out. It does not forcefully interrupt worker threads.
637
637
  See [R8 unit19](architecture/r8-unit19.md) and its
638
638
  [migration notes](migrations/r8-unit19.md) for the shutdown budget and result rules.
639
639
 
640
- `Runtime#shutdown` is terminal for that Runtime. It drains/terminates the
641
- Runtime-owned EventLoop, then closes pools and timers according to the Runtime
642
- shutdown contract.
640
+ `Runtime#shutdown` is terminal for that Runtime. During the drain phase it waits
641
+ for registered owners and pending timer notifications. During the stop phase it
642
+ closes pool admission and waits for workers while EventLoop continues delivering
643
+ existing deadlines. It then stops EventLoop and closes the timer service. Timer
644
+ callbacks continue to run on EventLoop, not on the shutdown caller's thread.
645
+
646
+ For example, a Blocking operation with a 50 ms timeout that takes 200 ms still
647
+ reports `TimeoutError` when shutdown begins immediately after submission, if the
648
+ shutdown budget permits that deadline to be delivered. The worker is allowed to
649
+ finish physically. A queued operation whose timeout settles before it starts is
650
+ skipped, just as during ordinary operation. Standalone fan-out deadlines also
651
+ remain active even when their pending results do not occupy a pool worker.
652
+
653
+ Complete cleanup requires accepted timer notifications to finish or be removed
654
+ by their owners before the timer service closes. If the finite shutdown budget
655
+ expires while notifications remain, Runtime reports incomplete cleanup even
656
+ when no worker thread remains. It does not fire future callbacks early or create
657
+ a background timer service to preserve deadlines after shutdown returns.
658
+
659
+ For example, a notification scheduled far beyond both shutdown phases is not
660
+ executed early merely to empty the timer queue. Discarding that notification at
661
+ closure makes `cleanup_complete?` false and prevents default Runtime replacement.
662
+ Once shutdown returns incomplete, future deadline delivery is not guaranteed;
663
+ the application must not treat that result as completed work or a safe handoff.
664
+ Repeated shutdown retains the original result rather than silently upgrading it.
643
665
 
644
666
  Internal subsystems can register one shutdown participant per Runtime-local key
645
667
  through `Runtime#__register_shutdown_participant`. This is an internal lifecycle
@@ -185,12 +185,21 @@ and verifies provider cleanup. It uses the real Tool argument-validation path.
185
185
  It does not exercise the SharedState Agent loop or establish live-model,
186
186
  database or multi-process acceptance.
187
187
 
188
- In custom mode, SharedState releases terminal member instances through the
189
- Agent's public `unload!` operation. A normal Agent approval wait keeps the public
190
- `invoke` call pending. SharedState consequently stays inside the provider's
191
- `open` block and retains its resources; it does not return a suspended result or
192
- close the provider merely because an internal execution reaches an approval
193
- wait. The application remains responsible for answering or cancelling approvals.
188
+ In both default and custom sharing modes, SharedState releases terminal member
189
+ instances through the Agent's public `unload!` operation. It owns the lifetime of
190
+ the members it creates, including successful calls, early coordination stops and
191
+ invocation failures. Releasing a member does not delete its saved history.
192
+
193
+ For example, two members running two cycles create four temporary Agents. Each
194
+ Agent is released after its invocation finishes, while the shared findings stay
195
+ available to later members and the final aggregation. Repeated coordination does
196
+ not accumulate completed member owners in the Runtime.
197
+
198
+ A normal Agent approval wait keeps the public `invoke` call pending. In custom
199
+ mode, SharedState consequently stays inside the provider's `open` block and
200
+ retains its resources; it does not return a suspended result or close the
201
+ provider merely because an internal execution reaches an approval wait. The
202
+ application remains responsible for answering or cancelling approvals.
194
203
 
195
204
  For example, when a member waits for approval of `record_issue`, the board stays
196
205
  open while that invocation waits. An approval allows the Tool and member to
@@ -207,7 +216,8 @@ during the wait; after a public approval response, the Tool writes its record,
207
216
  aggregation runs, the provider closes and the member is released. Fixed
208
217
  responses verify the execution path, not a live model's Tool-selection behavior.
209
218
 
210
- The lifecycle guard also detects a custom `invoke` override that returns a Hash
219
+ In either sharing mode, the lifecycle guard also detects a custom `invoke`
220
+ override that returns a Hash
211
221
  with a suspended status before reaching completion. That exceptional early
212
222
  return raises `SharedState::MemberLifecycleError` with `reason: :suspended` and
213
223
  stops coordination before later members or aggregation. It is not the behavior
@@ -39,7 +39,8 @@ module Phronomy
39
39
  freeze
40
40
  end
41
41
 
42
- # Returns true when every Runtime-owned resource is known to have stopped.
42
+ # Returns true when owned resources stopped and pending timer notifications
43
+ # settled within the shutdown budget rather than being discarded.
43
44
  def cleanup_complete?
44
45
  @cleanup_status == :complete
45
46
  end
@@ -8,6 +8,8 @@ module Phronomy
8
8
  @clock = clock
9
9
  @heap = []
10
10
  @mutex = Mutex.new
11
+ @idle = ConditionVariable.new
12
+ @firing = 0
11
13
  @stopped = false
12
14
  @wake = nil
13
15
  end
@@ -51,10 +53,26 @@ module Phronomy
51
53
  @mutex.synchronize do
52
54
  before = @heap.length
53
55
  @heap.delete_if { |(_, registered)| registered == callback }
56
+ @idle.broadcast if idle_locked?
54
57
  before != @heap.length
55
58
  end
56
59
  end
57
60
 
61
+ # Wait without driving callbacks on the shutdown caller's thread. Both
62
+ # registrations and callbacks already removed from the heap must finish.
63
+ # @api private
64
+ def wait_until_idle(deadline)
65
+ @mutex.synchronize do
66
+ until idle_locked?
67
+ remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
68
+ return false if remaining <= 0
69
+
70
+ @idle.wait(@mutex, remaining)
71
+ end
72
+ true
73
+ end
74
+ end
75
+
58
76
  # Executes all callbacks whose deadline is due. Must be called by EventLoop.
59
77
  def fire_due
60
78
  callbacks = @mutex.synchronize do
@@ -62,7 +80,9 @@ module Phronomy
62
80
 
63
81
  now = @clock.call
64
82
  due_count = @heap.bsearch_index { |(fire_at, _)| fire_at > now } || @heap.length
65
- @heap.shift(due_count).map(&:last)
83
+ callbacks = @heap.shift(due_count).map(&:last)
84
+ @firing += callbacks.length
85
+ callbacks
66
86
  end
67
87
 
68
88
  callbacks.each do |callback|
@@ -71,6 +91,11 @@ module Phronomy
71
91
  Phronomy::RuntimeSettings.current.logger&.error do
72
92
  "[TimerQueue] callback raised #{error.class}: #{error.message}"
73
93
  end
94
+ ensure
95
+ @mutex.synchronize do
96
+ @firing -= 1
97
+ @idle.broadcast if idle_locked?
98
+ end
74
99
  end
75
100
  callbacks.length
76
101
  end
@@ -82,13 +107,28 @@ module Phronomy
82
107
  def shutdown
83
108
  wake = @mutex.synchronize do
84
109
  return self if @stopped
110
+ @drained_on_shutdown = idle_locked?
85
111
  @stopped = true
86
112
  @heap.clear
113
+ @idle.broadcast if idle_locked?
87
114
  @wake
88
115
  end
89
116
  wake&.call
90
117
  self
91
118
  end
119
+
120
+ # Capture the first closure rather than a preceding idle observation:
121
+ # a caller holding this queue may register after that observation.
122
+ # @api private
123
+ def drained_on_shutdown?
124
+ @mutex.synchronize { @stopped && @drained_on_shutdown }
125
+ end
126
+
127
+ private
128
+
129
+ def idle_locked?
130
+ @heap.empty? && @firing.zero?
131
+ end
92
132
  end
93
133
  end
94
134
  end
@@ -27,7 +27,20 @@ module Phronomy
27
27
  end
28
28
 
29
29
  def shutdown
30
- @mutex.synchronize { @timer&.shutdown }
30
+ @mutex.synchronize do
31
+ return true unless @timer
32
+
33
+ @timer.shutdown
34
+ @timer.drained_on_shutdown?
35
+ end
36
+ end
37
+
38
+ # Capture the timer without holding the service lock during callbacks:
39
+ # an admitted continuation may acquire this same service while draining.
40
+ # @api private
41
+ def wait_until_idle(deadline)
42
+ timer = @mutex.synchronize { @timer }
43
+ !timer || timer.wait_until_idle(deadline)
31
44
  end
32
45
  end
33
46
  end
@@ -210,6 +210,7 @@ module Phronomy
210
210
  loop_instance&.begin_draining
211
211
 
212
212
  participants_idle = wait_for_participants(participants, drain_deadline)
213
+ @timer_service.wait_until_idle(drain_deadline)
213
214
  loop_idle = !loop_instance || loop_instance.wait_until_idle(drain_deadline)
214
215
 
215
216
  @lifecycle_mutex.synchronize do
@@ -217,13 +218,8 @@ module Phronomy
217
218
  end
218
219
 
219
220
  stop_deadline = monotonic_now + [cancel_grace.to_f, 0.2].max
220
- event_loop_status = if loop_instance
221
- loop_instance.stop_and_join(deadline: stop_deadline)
222
- else
223
- :not_started
224
- end
225
-
226
- pools_stopped, subsystem_error = shutdown_pools_and_timer(deadline: stop_deadline)
221
+ event_loop_status, pools_stopped, timers_idle, subsystem_error =
222
+ shutdown_resources(loop_instance, deadline: stop_deadline)
227
223
  participant_error = @lifecycle_mutex.synchronize { @shutdown_participant_error }
228
224
  cleanup_complete = participants_idle && participant_error.nil? &&
229
225
  loop_idle &&
@@ -231,6 +227,7 @@ module Phronomy
231
227
  event_loop_status != :cancel_timeout &&
232
228
  (!loop_instance || loop_instance.__receiver_cleanup_complete?) &&
233
229
  pools_stopped &&
230
+ timers_idle &&
234
231
  subsystem_error.nil?
235
232
 
236
233
  cleanup_complete = finalize_participants(participants) if cleanup_complete
@@ -306,21 +303,38 @@ module Phronomy
306
303
  "Runtime is #{current_state}; new work is not accepted"
307
304
  end
308
305
 
309
- def shutdown_pools_and_timer(deadline:)
306
+ # EventLoop must keep delivering existing deadlines while accepted pool
307
+ # operations drain. Its thread remains the only timer callback executor.
308
+ # Future registrations beyond the shared budget make cleanup incomplete.
309
+ def shutdown_resources(loop_instance, deadline:)
310
310
  error = nil
311
311
  pools_stopped = false
312
+ timers_idle = false
313
+ event_loop_status = :not_started
312
314
  begin
313
315
  pools_stopped = @pool_registry.shutdown(deadline: deadline)
314
316
  rescue => caught
315
317
  error ||= caught
318
+ end
319
+ begin
320
+ timers_idle = @timer_service.wait_until_idle(deadline)
321
+ rescue => caught
322
+ error ||= caught
323
+ end
324
+ begin
325
+ event_loop_status = loop_instance.stop_and_join(deadline: deadline) if loop_instance
326
+ rescue => caught
327
+ event_loop_status = :failed
328
+ error ||= caught
316
329
  ensure
317
330
  begin
318
- @timer_service.shutdown
331
+ timers_drained_on_shutdown = @timer_service.shutdown
332
+ timers_idle &&= timers_drained_on_shutdown
319
333
  rescue => caught
320
334
  error ||= caught
321
335
  end
322
336
  end
323
- [pools_stopped, error]
337
+ [event_loop_status, pools_stopped, timers_idle, error]
324
338
  end
325
339
 
326
340
  def validate_timeout!(value, name)
@@ -221,11 +221,11 @@ module Phronomy
221
221
  definitions = shared_tool_definitions(member, binding, cycle)
222
222
  instrumented = build_shared_researcher(member, definitions, sharing)
223
223
  prompt = shared_prompt(input, member_config[:instruction])
224
- invoke_shared_researcher(instrumented, prompt)
224
+ invoke_member_agent(instrumented, prompt)
225
225
  end
226
226
  end
227
227
 
228
- def invoke_shared_researcher(instrumented, prompt)
228
+ def invoke_member_agent(instrumented, prompt)
229
229
  agent = instrumented.new
230
230
  suspended = false
231
231
  result = agent.invoke(prompt)
@@ -235,10 +235,10 @@ module Phronomy
235
235
  end
236
236
  result
237
237
  ensure
238
- release_shared_member(agent, result, $!) if agent && !suspended
238
+ release_member_agent(agent, result, $!) if agent && !suspended
239
239
  end
240
240
 
241
- def release_shared_member(agent, result, primary_error)
241
+ def release_member_agent(agent, result, primary_error)
242
242
  agent.unload!
243
243
  rescue => release_error
244
244
  error = MemberLifecycleError.new(agent: agent, result: result, reason: :release_failed,
@@ -298,7 +298,7 @@ module Phronomy
298
298
  extra_tools: extra_tools,
299
299
  per_agent_instruction: per_agent_instruction
300
300
  )
301
- instrumented.new.invoke(prompt)
301
+ invoke_member_agent(instrumented, prompt)
302
302
  end
303
303
 
304
304
  def build_instrumented_researcher(researcher_class, store, cycle)
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Phronomy
4
- VERSION = "0.35.1"
4
+ VERSION = "0.35.2"
5
5
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: phronomy
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.35.1
4
+ version: 0.35.2
5
5
  platform: ruby
6
6
  authors:
7
7
  - Raizo T.C.S
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2026-11-17 00:00:00.000000000 Z
11
+ date: 2026-11-18 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: ruby_llm