phronomy 0.24.1 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb31ae2fdc7b102461fd91480ea2e2aaeda618fb65cc3eb885a9525ca1e985e2
-  data.tar.gz: 2ede56b656b789ff195561ac72cac5df2f51dba410dbee8e3025437985509e61
+  metadata.gz: 636ce578204172927316a89f0f65a2bdfda49140822da98cd1eec9230d821105
+  data.tar.gz: 8d776e0ab9bf2775af4e23f77b0b29968a3d4962f8fbd877d3fe9574a3efb306
 SHA512:
-  metadata.gz: fe717ea7a31272ad7d7247f214c59ca8c5370a80ce80e67d69d8bb14f5e285d779004545e56f3298e85d63ca7352ba430f2912e967453b899c1181e8d00fb77e
-  data.tar.gz: e3a45c05b4b8f129e61fa09ae7e23be8916aeae762642f5333fb3876c6d142091d836c8c33d3dcb0a3908d1d1d6d99261bffde3e07d8ad505aa136a0df9f9097
+  metadata.gz: 81a2b295d5fb03d4cd03c6f3ceabca7b62f4e635fc5dd6ed3db31b1c5f59c6031fc38958895a1fc7b8e9fc75394a81181d51529ebb86f310e85cd2300a9395af
+  data.tar.gz: f701f8fd0be60d655e9676c8cbdfec93606cca20769da90b7c67617c9d876cbde51bf18a42531b7cf70079aa12863af022acd21500fe40cff64c04d5a70df6ab

data/CHANGELOG.md

@@ -12,8 +12,18 @@ Release history for 0.14.0 and earlier is archived in
 
 ## [Unreleased]
 
+---
+
+## [0.25.0] - 2026-09-12
+
+### Added
+
+- Public `Task.completed` / `Task.failed` factories for application-owned settled results.
+- `Blocking.call_async` for non-waiting submission of synchronous application work.
+
 ### Fixed
 
+- Reject waiting OffloadPool admission from EventLoop before creating an operation.
 - Add runtime dependency constraint `json < 3` to prevent Faraday/RubyLLM JSON
   parser incompatibilities from resolving in consumer environments.
 

data/README.md

@@ -23,6 +23,8 @@ tracking `main` directly.
 - **EventLoop + FSMSession** — the framework control plane for logical lifecycle coordination.
 - **OffloadPool** — bounded operating-system-thread execution boundary for synchronous work that must not run on EventLoop.
 - **Task** — the common thread-free completion handle returned by Phronomy asynchronous APIs, including OffloadPool-backed work.
+- **Task.completed / Task.failed** — already-settled application results without starting execution.
+- **Blocking.call_async** — submits synchronous application work to the existing bounded OffloadPool without waiting for queue space.
 - **Journal / Context Policy / Manifest** — canonical history plus per-LLM-call context selection.
 
 See [Features and Application Programming Interface (API) stability](docs/features.md) for the full feature matrix.

data/docs/features.md

@@ -66,6 +66,8 @@ rather than implicitly inheriting the parent revision. The Stable
 | **`stream_callback_error_policy`** — Terminal event callback error policy (`:report` / `:fail_task`) | Beta |
 | **Task completion contract** — `Task` is the common caller-facing completion handle for EventLoop/FSMSession lifecycles and OffloadPool work | Beta |
 | **`Task#map`** — Application-level Task result transformation and error propagation | Stable |
+| **Settled Task factories** — Public `Task.completed` / `Task.failed` represent already available application results without starting execution | Beta |
+| **Blocking.call_async** — Public non-waiting admission of synchronous application work to the existing OffloadPool, returning a Task | Beta |
 | **CancellationToken** — Cooperative cancellation with explicit `cancel!`, lazy monotonic deadlines, and callback registration | Experimental |
 | **Tool `execution_mode`** — `:cooperative` for short EventLoop-safe work; `:offloaded` for synchronous work that must stay off EventLoop | Experimental |
 | **OffloadPool sizing** — `offload_pool_size` / `offload_queue_size`; named pools available for application-owned isolation | Beta |

data/lib/phronomy/blocking.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Public adapter for synchronous application I/O or computation.
+  # This uses the existing bounded OffloadPool. It does not execute logical
+  # waits, persist work, force-stop a running block, or create a scheduler.
+  module Blocking
+    # Submits synchronous application work to the default Runtime OffloadPool.
+    # Admission never waits for queue space. Admission StandardError failures
+    # become failed Tasks; accepted work retains the pool's Task unchanged.
+    # A timeout/cancellation can settle that Task before a running worker exits.
+    # The block must not wait for another Agent, Workflow, or Task.
+    # @param timeout [Numeric, nil] operation deadline, including queue time
+    # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
+    # @yield synchronous application work
+    # @return [Phronomy::Task] original accepted Task or failed admission Task
+    # @raise [ArgumentError] if no block is supplied
+    # @api public
+    def self.call_async(timeout: nil, cancellation_token: nil, &block)
+      raise ArgumentError, "Blocking.call_async requires a block" unless block
+
+      begin
+        Phronomy::Runtime.instance.offload.submit(
+          on_full: :raise,
+          timeout: timeout,
+          cancellation_token: cancellation_token,
+          &block
+        )
+      rescue => error
+        Phronomy::Task.failed(error, name: "blocking-admission-failed")
+      end
+    end
+  end
+end

data/lib/phronomy/engine/concurrency/offload_pool.rb

@@ -347,6 +347,9 @@ module Phronomy
       # Synchronous queue admission may delay return from this method when
       # +on_full: :wait+ is used. EventLoop-owned framework paths therefore submit
       # with +on_full: :raise+ and handle backpressure asynchronously.
+      # EventLoop callers requesting a waiting policy are rejected before any
+      # operation, timer, or cancellation subscription is created. Application
+      # code should use Phronomy::Blocking.call_async.
       #
       # @param timeout [Numeric, nil] operation-wide deadline in seconds
       # @param cancellation_token [CancellationToken, nil] operation-wide token
@@ -359,6 +362,7 @@ module Phronomy
       # @raise [Phronomy::PoolShutdownError] when the pool has been shut down
       # @raise [Phronomy::BackpressureError] when +on_full: :raise+ and queue is full
       # @raise [Phronomy::TimeoutError] when +on_full: :timeout+ exceeds +full_timeout+
+      # @raise [Phronomy::EventLoopReentrancyError] for waiting admission on EventLoop
       # @api private
       def submit(
         timeout: nil,
@@ -367,6 +371,10 @@ module Phronomy
         full_timeout: nil,
         &block
       )
+        if Phronomy::Runtime.in_event_loop_context? && on_full != :raise
+          raise Phronomy::EventLoopReentrancyError,
+            "OffloadPool admission cannot wait on EventLoop; use on_full: :raise"
+        end
         raise Phronomy::PoolShutdownError, "pool has been shut down" if @shutdown
 
         submitted_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)

data/lib/phronomy/engine/task.rb

@@ -23,6 +23,29 @@ module Phronomy
       new(name: name, parent: parent)
     end
 
+    # Public factories for already-settled values. No execution is started.
+    # Always create a base Task: there is no physical worker to supervise.
+    # @param value [Object] already available result
+    # @param name [String, nil] optional diagnostic name
+    # @return [Phronomy::Task] a completed base Task
+    # @api public
+    def self.completed(value = nil, name: nil)
+      Phronomy::Task.deferred(name: name).tap { |task| task.complete(value) }
+    end
+
+    # Represents an already known failure without raising the stored error.
+    # Observation through wait_result raises it; on_complete receives it.
+    # @param error [Exception] original failure object
+    # @param name [String, nil] optional diagnostic name
+    # @return [Phronomy::Task] a failed base Task
+    # @raise [ArgumentError] if error is not an Exception
+    # @api public
+    def self.failed(error, name: nil)
+      raise ArgumentError, "error must be an Exception" unless error.is_a?(Exception)
+
+      Phronomy::Task.deferred(name: name).tap { |task| task.fail(error) }
+    end
+
     attr_reader :name, :parent
 
     # @api private

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.24.1"
+  VERSION = "0.25.0"
 end

data/sig/phronomy/runtime.rbs

@@ -1,5 +1,8 @@
 module Phronomy
   class Task[A]
+    def self.completed: [V] (V value, ?name: String?) -> Task[V]
+                      | (?name: String?) -> Task[nil]
+    def self.failed: (Exception error, ?name: String?) -> Task[untyped]
     attr_reader name: String?
     attr_reader parent: Task[untyped]?
 
@@ -38,3 +41,9 @@ module Phronomy
     def initialize: (?user_id: String?, ?cancellation_token: Concurrency::CancellationToken?, ?deadline: untyped, ?token_budget: Integer?, ?approval_policy: untyped, ?redaction_policy: untyped, ?task_id: String?, ?parent_task_id: String?) -> void
   end
 end
+
+module Phronomy
+  module Blocking
+    def self.call_async: [V] (?timeout: Numeric?, ?cancellation_token: Concurrency::CancellationToken?) { () -> V } -> Task[V]
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.24.1
+  version: 0.25.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-07 00:00:00.000000000 Z
+date: 2026-09-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -252,6 +252,7 @@ files:
 - lib/phronomy/agent_already_exists_error.rb
 - lib/phronomy/agent_busy_error.rb
 - lib/phronomy/agent_purged_error.rb
+- lib/phronomy/blocking.rb
 - lib/phronomy/canonical_json.rb
 - lib/phronomy/configuration.rb
 - lib/phronomy/content_store/base.rb