phronomy 0.20.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a9f9f2ab4acdb4e17edeb4e0b7f0b33660b7102e5b345c2bd8d411e6b0760de
-  data.tar.gz: 331265c52dfadbe4be8f85b9a48b35de384042664538f4fa74db0d34829e3b62
+  metadata.gz: 1da8f29678594e3b2c0b8db70e6485f3576ffe72bc19db0dd340abefbdc3118b
+  data.tar.gz: 8dbf2cacbca536c99b7552f3494edf208986b9e45c3817fac700da445d27d2c3
 SHA512:
-  metadata.gz: f3c7e0b15ede3129a2ac426ed86ebde36e353c664b5c64fc559878996ab6331b86f88c289e2f47179f0d1c58e91ec23c0c3d23060f066168c1a441e349dd534f
-  data.tar.gz: 527e858a300d3e8fb305782cdab29d6195b3836686df5b4d41a7abf8a40b584de8a8f0dcdab8ccd5b7b5dcfbcbf0c0dad45a7be2f092eae69c2c643ff69e9734
+  metadata.gz: b513420381c3eb137470d834baca90938daded756b6d3e480eed295c592b9ada062f565eaf0a77c175075378fc747080aa7c8b6bf3ccd72da22dd0c4037e2608
+  data.tar.gz: 6cea982e98ef21605ff8b55de55a6693fd2b3c3002c0212c8c9c4912f68c5bbd74204669cea3658ec7c174f506e19bda5b5f1084cccee78fa49615b181863941

data/.mutant.yml

@@ -9,7 +9,9 @@ matcher:
   subjects:
     - Phronomy::WorkflowContext
     - Phronomy::WorkflowRunner
-    - Phronomy::Tool::Base
+    # Phronomy::Tool::Base is a public constant alias to this same Class object.
+    # Use the implementation canonical name returned by Class#name for Mutant.
+    - Phronomy::Agent::Context::Capability::Base
     - Phronomy::LlmContextWindow::TokenBudget
     - Phronomy::Agent::ContextAssembler
     - Phronomy::Agent::ContextPolicies::Default

data/CHANGELOG.md

@@ -37,6 +37,31 @@ Release history for 0.14.0 and earlier is archived in
 - `Persistence#activations`; ActivationRegistry is transient Runtime state.
 - Class-level `Agent::Base.approve` / `Agent::Base.approve_async` routing APIs and their caller-supplied `persistence:` argument; approval execution now goes through the resolved live Agent instance.
 
+### Public API façade and typed contracts
+
+#### Added
+
+- `Phronomy::Tool::Base` as the application-facing Tool authoring façade. It is
+  an exact alias of `Phronomy::Agent::Context::Capability::Base`, so existing
+  Tool definitions remain compatible and share the same class identity/DSL state.
+- Initial hand-written RBS signatures for the primary application API and
+  explicit extension SPIs, with a dedicated RBS validation CI job.
+- ADR-015 defining Tool façade ownership, the LLMAdapter SPI, RBS scope, and
+  extension dependency direction.
+
+#### Changed
+
+- `Phronomy::LLMAdapter::Base#complete` and `#stream` are explicit Beta extension
+  SPI methods. Phronomy continues to own `complete_async` / `stream_async` and
+  OffloadPool integration.
+- VectorStore and Embeddings backends expose synchronous implementation contracts;
+  their framework-provided async convenience methods offload through Phronomy and
+  return `Task`.
+- `InvocationContext` construction is classified consistently with its documented
+  Beta application API.
+- OutputParser `parse` is classified as the public subclass extension point that
+  concrete parsers implement.
+
 ### OffloadPool execution model
 
 #### Changed
@@ -52,20 +77,22 @@ Release history for 0.14.0 and earlier is archived in
 - Framework-owned EventLoop-origin offload submissions use non-blocking queue
   admission so a full worker queue raises backpressure instead of blocking
   the EventLoop control thread.
-- Submit cancellation now settles the caller-facing `PendingOperation`
-  immediately. Cancellation before worker start prevents execution;
-  cancellation after worker start marks the operation abandoned while allowing
-  the synchronous worker to finish without asynchronous `Thread#raise`.
+- `OffloadPool#submit` now returns the common caller-facing `Phronomy::Task`.
+  OffloadPool queue/worker/timeout/abandonment state is held by a private
+  Operation record rather than by a second completion-handle class.
+- Submit cancellation now settles the caller-facing `Task` immediately.
+  Cancellation before worker start prevents execution; cancellation after worker
+  start marks the private Operation abandoned while allowing the synchronous
+  worker to finish without asynchronous `Thread#raise`.
 - Monotonic deadlines carried by an OffloadPool submit cancellation token are
   promoted by the Runtime timer queue, so cancellation completion does not
   require a polling Thread.
 - Independent notification callbacks now isolate subscriber failures. An
-  `StandardError` from one `CancellationToken#on_cancel`, `Task#on_complete`, or
-  `PendingOperation#on_complete` callback is logged and does not suppress later
-  subscribers.
-- `PendingOperation#blocking_wait(timeout:)` remains a waiter-local synchronous
-  timeout only. It does not settle or cancel the operation; operation-wide
-  cancellation is represented only by `OffloadPool#submit(cancellation_token:)`.
+  `StandardError` from one `CancellationToken#on_cancel` or `Task#on_complete`
+  callback is logged and does not suppress later subscribers.
+- `Task#wait_result(timeout:)` is the waiter-local synchronous timeout bridge.
+  It does not settle or cancel the Task; operation-wide cancellation is
+  represented by the CancellationToken supplied to the creating API.
 - `offload_pool_abandoned_total` is the cumulative number of operations whose
   caller-facing submit timeout or cancellation settled after worker execution
   started. `offload_pool_abandoned_active` is the current number of those
@@ -78,8 +105,11 @@ Release history for 0.14.0 and earlier is archived in
 - Tool execution modes `:blocking_io`, `:cpu_bound`, and `:external_process`.
 - `Runtime#blocking_io`, `blocking_io_pool_size`, and
   `blocking_io_queue_size`.
+- Caller-facing `OffloadPool::PendingOperation` and
+  `PendingOperation#blocking_wait`; asynchronous Phronomy APIs use `Task` as the
+  completion contract.
 - Waiter-local `cancellation_token:` from `PendingOperation#blocking_wait`.
-  The low-level synchronous bridge continues to support waiter-local `timeout:`.
+  Operation-wide cancellation remains on `OffloadPool#submit(cancellation_token:)`.
 
 
 ### EventLoop-first runtime cleanup

data/CONTRIBUTING.md

@@ -43,14 +43,28 @@ ruby scripts/check_japanese.rb
 
 ## Public API Changes
 
-When adding, removing, or renaming a public method or class:
+When adding, removing, renaming, or changing the contract of a public API or
+extension SPI:
 
-1. Update the stability table in `README.md`.
-2. Add or update `@api private` YARD annotations for internal APIs.
-3. Regenerate the API compatibility snapshot:
+1. Update `docs/features.md` when the public feature/stability description changes.
+2. Add or update YARD `@api public` / `@api private` classification.
+3. Regenerate the API compatibility snapshot when the reflected compatibility
+   surface changes:
    ```bash
    bundle exec ruby scripts/api_snapshot.rb --write
    ```
+4. Update the corresponding hand-written `sig/**/*.rbs` signature when the
+   public type shape changes.
+5. Validate the RBS environment:
+   ```bash
+   bundle exec rbs -I sig validate
+   ```
+6. Add or update a focused spec for the public API or extension contract.
+
+RBS is a typed representation of an API contract that has already been defined
+by source behavior, YARD classification, documentation, and focused tests. Do
+not make an internal method public, change runtime semantics, or invent a new
+extension guarantee merely to make an RBS signature easier to write.
 
 ### `@api` classification vs Ruby visibility
 
@@ -82,6 +96,22 @@ contract rather than by a repository-wide visibility inference rule.
 
 Do not change Ruby visibility merely to make it match an `@api` annotation.
 
+### Async completion boundary
+
+`Phronomy::Task` is the caller-facing completion handle. EventLoop/FSMSession and
+OffloadPool are execution/continuation mechanisms, not competing completion
+abstractions.
+
+Synchronous work that requires execution away from EventLoop must use an
+OffloadPool. Do not create production worker Threads in adapters, backends, or
+Tools to emulate asynchronous behavior. Logical waits between Phronomy
+lifecycles stay on EventLoop/FSMSession and settle a Task later.
+
+The framework owns Task settlement (`complete`, `fail`, and framework-driven
+cancellation). Application code should observe Tasks through `wait_result`,
+`on_complete`, `map`, and settlement state. Operation-wide cancellation of
+OffloadPool work is supplied through `CancellationToken`.
+
 ---
 
 ## Architecture Decision Records
@@ -91,7 +121,9 @@ Key design decisions are documented as ADRs in
 to the threading model, persistence/context authority, or public API shape.
 
 For Agent Context work, ADR-012 and ADR-013 define the current Journal,
-Manifest, Context Policy and persistent Knowledge model.
+Manifest, Context Policy and persistent Knowledge model. ADR-010 defines the
+EventLoop/FSMSession, Task, and OffloadPool execution boundary. ADR-015 defines
+the Tool public façade, extension-SPI boundary, and RBS ownership rules.
 
 ---
 
@@ -119,7 +151,7 @@ The authoritative subject list is `.mutant.yml`. It currently includes:
 
 - `Phronomy::WorkflowContext`
 - `Phronomy::WorkflowRunner`
-- `Phronomy::Tool::Base`
+- `Phronomy::Agent::Context::Capability::Base`
 - `Phronomy::LlmContextWindow::TokenBudget`
 - `Phronomy::Agent::ContextAssembler`
 - `Phronomy::Agent::ContextPolicies::Default`
@@ -130,6 +162,12 @@ The authoritative subject list is `.mutant.yml`. It currently includes:
 - `Phronomy::Agent::ContextPlanValidator`
 - `Phronomy::VectorStore::InMemory`
 
+The Tool mutation subject intentionally uses
+`Phronomy::Agent::Context::Capability::Base`, which is the implementation
+canonical name returned by the single Class object's runtime `Class#name`.
+`Phronomy::Tool::Base` is the public facade constant alias to that same Class
+object; it is not a second Tool base class.
+
 When you add or modify tests for a covered subject, run mutation tests locally
 when practical and investigate meaningful score regressions.
 

data/README.md

@@ -18,10 +18,10 @@ tracking `main` directly.
 - **Agent** — stateful, persistence-backed LLM agent with canonical execution history.
 - **Persistence** — unified durable backend for Agent state and Workflow `workflow_states`.
 - **Workflow** — state-machine-driven application workflow with explicit events and wait states.
-- **Tool / Capability** — callable application capability exposed to an Agent.
+- **Tool / Capability** — callable application capability exposed to an Agent; application-defined Tools subclass `Phronomy::Tool::Base`.
 - **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** — thread-free completion handle for asynchronous Phronomy lifecycles.
+- **Task** — the common thread-free completion handle returned by Phronomy asynchronous APIs, including OffloadPool-backed work.
 - **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.
@@ -57,7 +57,7 @@ dependencies, stateful Agent setup, streaming, and Workflow examples.
 ## Quick start
 
 ```ruby runnable
-class WebSearch < Phronomy::Agent::Context::Capability::Base
+class WebSearch < Phronomy::Tool::Base
   description "Search the web"
   param :query, type: :string, desc: "Search query"
 
@@ -78,6 +78,10 @@ result = ResearchAgent.new.invoke("What happened in AI research this week?")
 puts result[:output]
 ```
 
+`Phronomy::Tool::Base` is the public authoring name for the existing Tool base
+class. The legacy `Phronomy::Agent::Context::Capability::Base` constant remains
+valid for compatibility.
+
 For non-blocking top-level use, call `invoke_async` and keep the returned
 `Phronomy::Task`. Inside Phronomy lifecycle callbacks, do not block waiting for
 another Task; continue through explicit events instead.
@@ -89,7 +93,7 @@ result = task.wait_result   # top-level/external caller only
 
 ## Runtime model
 
-Phronomy uses one explicit lifecycle model:
+Phronomy uses one completion model with two execution mechanisms:
 
 ```text
 Runtime
@@ -100,13 +104,18 @@ Runtime
 │     ├─ ToolInvocation
 │     └─ MultiAgent fan-out
 ├─ OffloadPool
+│  └─ synchronous off-EventLoop work
 └─ EventLoop-driven timers
 
-Task = completion handle
+EventLoop / FSMSession ─┐
+                       ├─> Task = completion handle
+OffloadPool ────────────┘
 ```
 
 Logical waiting remains in EventLoop/FSMSession state. Synchronous work that
-would block EventLoop uses the bounded OffloadPool. See
+would block EventLoop uses the bounded OffloadPool. OffloadPool-specific queue,
+worker, timeout, and abandonment state remains private runtime machinery; callers
+observe completion through `Phronomy::Task`. See
 [Runtime and concurrency](docs/runtime-and-concurrency.md) for the detailed
 contracts, timeout/cancellation semantics, metrics, and callback rules.
 

data/docs/decisions/010-cooperative-first-concurrency.md

@@ -2,7 +2,8 @@
 
 ## Status
 
-Accepted — revised for the OffloadPool execution boundary.
+Accepted — revised for a single Task completion contract and the OffloadPool
+execution boundary.
 
 ## Context
 
@@ -11,28 +12,31 @@ and MultiAgent lifecycles without allocating one OS Thread per logical task.
 At the same time, application and third-party code may contain synchronous work
 that must not execute on the single Runtime EventLoop thread.
 
-Classifying arbitrary application work as I/O-bound, CPU-bound, or external
-process work is not a responsibility the framework can reliably infer. The
-architecturally relevant distinction for Phronomy is whether a unit of work can
-safely run to completion on EventLoop or must be moved off the control thread.
+The architecturally relevant distinction is whether a unit of work can safely run
+to completion on EventLoop or must be moved off the control thread. The way work
+executes is separate from the object used by callers to observe completion.
 
 ## Decision
 
 Framework lifecycle coordination uses one Runtime-owned EventLoop and explicit
-FSMSession state/events. **Task is a completion handle**, not an execution
-backend.
+FSMSession state/events. **`Phronomy::Task` is the single caller-facing completion
+handle**, not an execution backend.
+
+There are two framework execution mechanisms:
+
+- **EventLoop / FSMSession** for logical lifecycle progression and waits;
+- **OffloadPool** for synchronous work that must execute on bounded worker OS
+  Threads away from EventLoop.
+
+Both mechanisms surface asynchronous completion as `Phronomy::Task`.
 
 Phronomy defines two Tool execution modes:
 
 - `:cooperative` — short, EventLoop-safe work, or a specialized asynchronous
   implementation that starts another Phronomy lifecycle and immediately returns
-  a completion handle.
+  a Task;
 - `:offloaded` — synchronous work that must not run on EventLoop. It executes in
-  the bounded `OffloadPool`.
-
-`OffloadPool` is the thread execution boundary for synchronous work that must be
-kept off EventLoop. It may contain blocking I/O, CPU-bound Ruby work, or other
-application-defined long-running synchronous calls.
+  the bounded OffloadPool and returns a Task.
 
 Workload classification such as I/O-bound versus CPU-bound is application-owned.
 Phronomy does not provide separate `:blocking_io`, `:cpu_bound`, or
@@ -53,23 +57,29 @@ Runtime
 │     ├─ ToolInvocation
 │     └─ MultiAgent fan-out
 ├─ OffloadPool (bounded OS Threads)
+│  ├─ private Operation records
 │  ├─ blocking I/O
 │  ├─ CPU-bound synchronous work
 │  └─ other long synchronous work
 ├─ named OffloadPools
 └─ EventLoop-driven timers
 
-Task = completion handle
+EventLoop / FSMSession ─┐
+                       ├─> Task = completion handle
+OffloadPool ────────────┘
 ```
 
+OffloadPool's private Operation record owns the submitted block, queue/worker
+state, submit-time timeout/cancellation linearization, wait-time accounting, and
+abandonment. It is not returned to application or extension code.
+
 ## Capacity and starvation
 
-The default OffloadPool is a shared bounded resource. CPU-heavy work can occupy
-slots that would otherwise be available to I/O, and slow I/O can do the same in
-reverse. Phronomy guarantees bounded worker count, bounded queue depth,
-backpressure, timeout/cancellation settlement, abandoned-worker accounting,
-metrics, and lifecycle shutdown. It does **not** guarantee work-class fairness,
-CPU isolation, core reservation, or CPU-bound speedup.
+The default OffloadPool is a shared bounded resource. Phronomy guarantees bounded
+worker count, bounded queue depth, backpressure, timeout/cancellation settlement,
+abandoned-worker accounting, metrics, and lifecycle shutdown. It does not
+guarantee work-class fairness, CPU isolation, core reservation, or CPU-bound
+speedup.
 
 Applications own capacity planning through `offload_pool_size` and
 `offload_queue_size`. Where isolation is required, applications may use
@@ -80,28 +90,23 @@ resource domains.
 
 An EventLoop action must not block while waiting for a free OffloadPool queue
 slot. Framework-owned EventLoop-origin submissions therefore use non-blocking
-admission (`on_full: :raise`) and propagate `BackpressureError` through the
-normal FSM/completion path.
-
-External management threads may deliberately choose other admission policies
-when blocking the caller is acceptable.
+admission (`on_full: :raise`) and propagate `BackpressureError` through the normal
+FSM/Task completion path.
 
 ## Timeout and cancellation
 
-An OffloadPool submit-time timeout settles the caller-facing PendingOperation.
-It does not asynchronously interrupt a running worker Thread. If execution has
-already started, the operation becomes abandoned, the worker may continue until
-the submitted synchronous call returns, and that eventual worker result is
-discarded.
+An OffloadPool submit-time timeout settles the caller-facing Task with
+`TimeoutError`. It does not asynchronously interrupt a running worker Thread. If
+execution has already started, the private Operation becomes abandoned, the
+worker may continue until the submitted synchronous call returns, and that
+eventual worker result is discarded.
 
-The cancellation token passed to `OffloadPool#submit` follows the same
-caller-facing settlement model:
+The cancellation token passed to `OffloadPool#submit` follows the same model:
 
 - cancellation before worker execution prevents the submitted block from
-  starting;
-- cancellation after worker execution starts settles the caller-facing
-  PendingOperation immediately, marks the operation abandoned, and allows the
-  worker to continue until the synchronous call returns;
+  starting and settles the Task as cancelled;
+- cancellation after worker execution starts settles the Task immediately, marks
+  the private Operation abandoned, and allows the worker to continue;
 - cancellation does not use `Thread#raise`;
 - application code may observe the same CancellationToken and terminate its own
   synchronous operation cooperatively.
@@ -109,39 +114,51 @@ caller-facing settlement model:
 A submit token with a monotonic deadline is connected to the Runtime timer queue,
 so deadline expiry becomes explicit cancellation without a polling Thread.
 
-`PendingOperation#blocking_wait(timeout:)` is a low-level synchronous bridge for
-non-EventLoop callers such as tests and diagnostics. Its timeout is waiter-local:
-it raises `TimeoutError` only to that caller and does not settle the
-PendingOperation, cancel the submitted operation, or mark it abandoned.
-PendingOperation does not define a waiter-local cancellation token;
-operation-wide cancellation is represented only by the token passed to
-`OffloadPool#submit`.
-
-Independent notification callbacks are fault-isolated. A `StandardError` from one
-`CancellationToken#on_cancel`, `Task#on_complete`, or
-`PendingOperation#on_complete` subscriber is logged and does not suppress later
-subscribers. This rule applies to notification fan-out; continuation or
-transformation callbacks still report their own failures through the operation
-they construct.
-
-`abandoned_count` and the exported `offload_pool_abandoned_total` metric are
-cumulative: they count operations whose caller-facing submit timeout or submit
-cancellation settled after worker execution had already started.
-`abandoned_active_count` and `offload_pool_abandoned_active` are current-state
-values: they count only abandoned operations whose synchronous worker is still
-occupying OffloadPool capacity.
+`Task#wait_result(timeout:)` is a synchronous bridge for non-EventLoop callers.
+Its timeout is waiter-local: it raises `TimeoutError` only to that caller and does
+not settle the Task, cancel the submitted operation, or mark an OffloadPool
+Operation abandoned.
+
+Framework components own Task settlement. Application code should request
+operation-wide cancellation through the CancellationToken accepted by the API
+that created the Task rather than calling Task settlement methods directly. A
+Task cancellation must not implicitly cancel a shared CancellationToken in the
+reverse direction.
+
+Independent `Task#on_complete` notification callbacks are fault-isolated. Their
+execution thread is not guaranteed, so callbacks must be thread-safe and should
+return quickly. Framework lifecycle code normally converts completion into an
+explicit EventLoop event.
+
+## Abandoned-worker metrics
+
+`offload_pool_abandoned_total` is cumulative: it counts operations whose
+caller-facing timeout or cancellation won after worker execution had already
+started. `offload_pool_abandoned_active` is current-state: it counts only those
+abandoned operations whose synchronous workers are still occupying OffloadPool
+capacity. Task does not expose abandonment as caller-facing completion state;
+that distinction remains private OffloadPool execution/observability state.
 
 ## CPU-bound work
 
 CPU-bound work is allowed through `:offloaded`. Thread offload protects the
 EventLoop from direct long synchronous execution but does not remove CRuby GVL
-contention or physical CPU contention. Those are explicitly outside the core
-OffloadPool guarantee.
+contention or physical CPU contention.
+
+A future subprocess capability may provide process isolation and hard process
+termination. That future implementation belongs to the offload subsystem and
+does not reintroduce a Tool-level workload class.
+
+## Genuine native async
+
+A component that truly uses a native asynchronous driver and does not create a
+Phronomy-owned OS Thread does not need an OffloadPool worker. If such an
+extension point is formally introduced, it must still adapt completion into a
+`Phronomy::Task`; it must not expose provider-specific futures or private Runtime
+operation records as Phronomy's completion contract.
 
-A future subprocess capability may provide process isolation, hard process
-termination, stdout/stderr capture, and CPU-worker separation. That future
-implementation belongs to the offload subsystem and does not reintroduce a
-Tool-level `:external_process` execution class.
+The current VectorStore and Embeddings extension contracts are synchronous; their
+framework-provided async convenience methods use OffloadPool.
 
 ## Prohibited pattern
 
@@ -153,13 +170,12 @@ OffloadPool worker
 
 and equivalently for Workflow/ToolInvocation/Task lifecycles.
 
-That pattern converts a logical wait into worker-slot occupancy and can create
-pool starvation. The correct model is:
+The correct model is:
 
 ```text
 parent FSMSession
   → start child lifecycle
-  → return completion handle immediately
+  → return Task immediately
   → child settles
   → post parent EventLoop event
 ```
@@ -167,9 +183,10 @@ parent FSMSession
 ## Consequences
 
 - There is one explicit framework continuation model: FSMSession + EventLoop.
-- `Task` stays thread-free and represents settlement only.
-- Tool execution classification becomes `:cooperative` / `:offloaded`.
+- There is one caller-facing completion abstraction: Task.
+- Task stays thread-free and represents settlement only.
+- OffloadPool owns bounded OS-thread execution and its private Operation state.
+- Tool execution classification remains `:cooperative` / `:offloaded`.
 - CPU/I/O classification and resource sizing are application responsibilities.
-- Named pools remain available for application-managed resource isolation.
 - Production Fiber execution is not part of the architecture.
 - Raw production Threads remain confined to EventLoop and OffloadPool.