phronomy 0.28.0 → 0.29.0

data/lib/phronomy/workflow/runtime_binding/workflow_engine_environment.rb

@@ -9,7 +9,13 @@ module Phronomy
       @runtime = runtime
     end
 
-    def registry = WorkflowExecutionRegistry.for(@runtime.event_loop)
+    def registry
+      receiver = WorkflowExecutionRegistry.for(@runtime.event_loop)
+      @runtime.__shutdown_participant(key: WorkflowExecutionRegistry) ||
+        @runtime.__register_shutdown_participant(key: WorkflowExecutionRegistry, participant: receiver)
+      receiver
+    end
+
     def existing_registry = WorkflowExecutionRegistry.existing_for(@runtime)
     def executing? = @runtime.event_loop.current?
 
@@ -21,18 +27,35 @@ module Phronomy
       WorkflowPhaseMachineBuilder.new(**definition).build
     end
 
-    def build_session(entry_actions:, persist: nil, **options)
+    def build_session(entry_actions:, persist: nil, task_execution: nil, **options)
       # Preserve nil/scalar results: initial entry must not re-adopt metadata
       # unless the application actually returns a context.
       initial_actions = entry_actions.to_h do |state_name, callbacks|
         [state_name, callbacks.map { |callback| ->(context) { WorkflowActionRules.entry(callback, context, state_name) } }]
       end
-      Phronomy::FSMSession.new(**options, entry_actions: initial_actions, event_loop: @runtime.event_loop,
+      klass = task_execution ? Phronomy::WorkflowTaskSession : Phronomy::FSMSession
+      options = options.merge(task_execution: task_execution) if task_execution
+      klass.new(**options, entry_actions: initial_actions, event_loop: @runtime.event_loop,
         terminal_policy: persist && WorkflowTerminalPolicy.new(persist: persist))
     end
 
     def register_session(session, completion:)
       @runtime.event_loop.register(session, completion: completion, receiver: registry)
     end
+
+    def subscribe_cancellation(token, &callback)
+      subscriptions = Phronomy::Concurrency::ResultSubscriptions.new
+      subscriptions.cancellation(token, &callback)
+      remaining = token.remaining_monotonic_seconds
+      if remaining && !token.cancelled?
+        timer = @runtime.timer_queue
+        timer.schedule(seconds: remaining, &callback)
+        subscriptions.add { timer.cancel(callback) }
+      end
+      subscriptions
+    rescue
+      subscriptions&.close
+      raise
+    end
   end
 end

data/lib/phronomy/workflow/runtime_binding/workflow_phase_machine_builder.rb

@@ -47,7 +47,8 @@ module Phronomy
           :context,
           :current_event,
           :selected_transition_action,
-          :selected_transition_metadata
+          :selected_transition_metadata,
+          :workflow_task_execution
         )
 
         state_machine :phase, initial: entry do
@@ -85,6 +86,7 @@ module Phronomy
           # Both source exit callbacks and the transition action are
           # before_transition callbacks. Register exits first to preserve the
           # required exit -> transition action -> entry ordering.
+          before_transition { |machine| machine.workflow_task_execution&.leave }
           exit_actions.each do |state_name, callables|
             callables.each do |callable|
               before_transition(

data/lib/phronomy/workflow/runtime_binding/workflow_task_session.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # I07 translates C02 task-state decisions to generic FSM progression. Engine
+  # does not learn TaskResult ownership, cancellation or stale-result policy.
+  # @api private
+  class WorkflowTaskSession < FSMSession
+    def initialize(task_execution:, **options)
+      super(**options)
+      @task_execution = task_execution
+      @task_execution.bind(self)
+    end
+
+    def start
+      @task_execution.activate
+      super unless @done
+    rescue => error
+      finish_with_error(error)
+    end
+
+    def apply_task_context(context)
+      return unless @terminal_lifecycle_state == :running
+
+      @ctx = @context = context
+      apply_context_metadata!
+      @tracker.context = context
+      advance_or_halt
+    rescue => error
+      finish_with_error(error)
+    end
+
+    def fail_task_execution(error)
+      finish_with_error(error) if @terminal_lifecycle_state == :running
+    end
+
+    def handle(event)
+      return if event.type == :state_completed && !@task_execution.permits_completion?(event.payload)
+
+      super
+    end
+
+    private
+
+    def post_session_event(type, payload = nil)
+      payload = @task_execution.completion_key if type == :state_completed
+      super
+    end
+
+    def advance_or_halt
+      if @task_execution.enter(@current_state, @ctx)
+        notify_stable_state!
+      else
+        super
+      end
+    end
+
+    def build_tracker(from_state)
+      super.tap { |tracker| tracker.workflow_task_execution = @task_execution }
+    end
+
+    def request_terminal!(...)
+      @task_execution.close
+      super
+    end
+
+    def finish_with_error(error)
+      @task_execution.close
+      super
+    end
+
+    def retire_without_result!(error)
+      @task_execution.retire(error)
+      super
+    end
+  end
+end

data/lib/phronomy.rb

@@ -68,6 +68,8 @@ loader.ignore(
   "#{__dir__}/phronomy/runtime_composition/global_runtime.rb",
   "#{__dir__}/phronomy/runtime_composition/execution_defaults.rb"
 )
+# Optional application integrations are loaded explicitly by their consumers.
+loader.ignore("#{__dir__}/phronomy/integrations")
 # Persistence conformance support must never make production loading require RSpec.
 loader.ignore(
   "#{__dir__}/phronomy/testing/persistence_contract.rb",
@@ -85,6 +87,8 @@ loader.ignore("#{__dir__}/phronomy/agent/agent_purged_error.rb")
 loader.ignore("#{__dir__}/phronomy/agent/stream_callback_error.rb")
 loader.ignore("#{__dir__}/phronomy/agent/handoff_error.rb")
 loader.ignore("#{__dir__}/phronomy/agent/agent_already_exists_error.rb")
+loader.ignore("#{__dir__}/phronomy/agent/agent_not_found_error.rb")
+loader.ignore("#{__dir__}/phronomy/agent/agent_unloaded_error.rb")
 loader.setup
 require_relative "phronomy/persistence/transaction"
 require_relative "phronomy/persistence_composition/stores"
@@ -96,6 +100,8 @@ require_relative "phronomy/agent/agent_purged_error"
 require_relative "phronomy/agent/stream_callback_error"
 require_relative "phronomy/agent/handoff_error"
 require_relative "phronomy/agent/agent_already_exists_error"
+require_relative "phronomy/agent/agent_not_found_error"
+require_relative "phronomy/agent/agent_unloaded_error"
 
 require_relative "phronomy/runtime_composition/configuration_defaults"
 require_relative "phronomy/llm_adapter/token_usage"

data/scripts/api_snapshot.rb

@@ -18,6 +18,16 @@ require_relative "../lib/phronomy"
 
 PUBLIC_API_ENTRIES = [
   # Stable
+  Phronomy::Error,
+  Phronomy::AgentNotFoundError,
+  Phronomy::AgentUnloadedError,
+  Phronomy::Agent,
+  Phronomy::Agent::Scope,
+  Phronomy::Agent::ScopeCleanupError,
+  Phronomy::MultiAgent::TeamNotFoundError,
+  Phronomy::MultiAgent::TeamBusyError,
+  Phronomy::Embeddings::AuthenticationError,
+  Phronomy::Embeddings::RateLimitError,
   Phronomy::Agent::Base,
   Phronomy::Agent::ReservedExecution,
   Phronomy::Agent::ExecutionObservation,
@@ -36,6 +46,8 @@ PUBLIC_API_ENTRIES = [
   Phronomy::InvocationContext,
   Phronomy::Tool::Base,
   Phronomy::Workflow,
+  Phronomy::Workflow::Builder,
+  Phronomy::WorkflowTaskResumeError,
   Phronomy::WorkflowContext,
   Phronomy::Runnable,
   Phronomy::Context::PromptTemplate,

data/scripts/check_readme_ruby.rb

@@ -1,38 +1,33 @@
 # frozen_string_literal: true
 
-# Extracts every ```ruby ... ``` block from README.md and runs `ruby -c` on each.
-# Exits non-zero if any block has a syntax error.
-
+# Check all Ruby fences, including executable examples, in the entry documents.
 require "tempfile"
 require "open3"
-
-readme_path = File.expand_path("../README.md", __dir__)
-readme = File.read(readme_path)
-blocks = readme.scan(/^```ruby\n(.*?)^```/m).map.with_index(1) { |(code), i| [i, code] }
-
-puts "Checking #{blocks.size} Ruby code blocks in README.md..."
+require_relative "check_readme_runnable"
 
 failures = []
-
-blocks.each do |index, code|
-  Tempfile.create(["readme_block_#{index}", ".rb"]) do |f|
-    f.write(code)
-    f.flush
-    stdout, status = Open3.capture2e("ruby", "-c", f.path)
-    if status.success?
-      puts "  OK   block ##{index}"
-    else
-      failures << index
-      puts "  FAIL block ##{index}"
-      puts stdout.gsub(f.path, "block ##{index}")
+count = 0
+paths = ARGV.empty? ? RunnableDocumentation::PATHS : ARGV
+paths.each do |relative|
+  text = File.read(File.expand_path(relative, RunnableDocumentation::ROOT))
+  text.to_enum(:scan, /^```ruby(?: runnable)?\n(.*?)^```/m).each do
+    match = Regexp.last_match
+    line = text[0...match.begin(1)].count("\n") + 1
+    label = "#{relative}:#{line}"
+    count += 1
+    Tempfile.create(["documentation_block", ".rb"]) do |file|
+      file.write(match[1])
+      file.flush
+      out, status = Open3.capture2e(RbConfig.ruby, "-c", file.path)
+      if status.success?
+        puts "OK   #{label}"
+      else
+        failures << label
+        puts "FAIL #{label}"
+        puts out.gsub(file.path, label)
+      end
     end
   end
 end
-
-if failures.empty?
-  puts "All #{blocks.size} Ruby code blocks passed syntax check."
-  exit 0
-else
-  puts "\n#{failures.size} block(s) failed syntax check: #{failures.join(", ")}"
-  exit 1
-end
+puts "#{count} Ruby blocks; #{failures.size} syntax failures"
+exit(failures.empty? ? 0 : 1)

data/scripts/check_readme_runnable.rb

@@ -1,101 +1,112 @@
 # frozen_string_literal: true
 
-# scripts/check_readme_runnable.rb
-#
-# Extracts ```ruby runnable blocks from README.md and executes each in an
-# isolated subprocess with a fake LLM stub to catch API drift.
-#
-# Any block that raises NoMethodError / ArgumentError / NameError causes a
-# non-zero exit, failing the CI step.
-#
-# Usage (from the phronomy/ root):
-#   bundle exec ruby scripts/check_readme_runnable.rb
-
+# Runs annotated, self-contained examples through the real public API.
+# Only the external LLM adapter is replaced. Each block has its own process,
+# configuration and Runtime; an accidental network request fails immediately.
+# Usage: bundle exec ruby scripts/check_readme_runnable.rb [markdown paths...]
 require "tempfile"
 require "open3"
 
-REPO_ROOT = File.expand_path("..", __dir__)
-README_PATH = File.join(REPO_ROOT, "README.md")
-
-# Injected before every runnable block.
-# Uses the Gemfile of this project so subprocesses can load phronomy.
-PREAMBLE = <<~RUBY
-  # frozen_string_literal: true
-  # --- CI preamble: stub LLM calls so no real network requests are made ---
-  ENV["BUNDLE_GEMFILE"] ||= "#{File.join(REPO_ROOT, "Gemfile")}"
-  require "bundler/setup"
-  require "phronomy"
+module RunnableDocumentation
+  ROOT = File.expand_path("..", __dir__)
+  PATHS = %w[README.md docs/getting-started.md docs/application-recipes.md docs/workflow-completion.md].freeze
+
+  PREAMBLE = <<~RUBY
+    require "bundler/setup"
+    require "phronomy"
+    require "webmock"
+    require "timeout"
+    WebMock.enable!
+    WebMock.disable_net_connect!
+
+    class DocumentationLLM < Phronomy::LLMAdapter::Base
+      protected
+
+      def perform_complete(request, cancellation_token:)
+        previous = request.messages.last
+        if previous&.role == :tool
+          return Phronomy::LLMAdapter::Response.new(content: previous.content)
+        end
 
-  # Patch invoke methods to return canned responses instead of calling the LLM.
-  module Phronomy
-    module Agent
-      # Prepend overrides AsyncEventApi (which is also prepended) so invoke
-      # returns a canned response without triggering the EventLoop.
-      module CiInvokeStub
-        def invoke(input = nil, **)
-          {output: "ci-stub-output", messages: []}
+        search = request.tools.find do |tool|
+          tool.fetch("parameters_schema").fetch("properties", {}).key?("query")
         end
+        if search
+          return Phronomy::LLMAdapter::Response.new(tool_calls: [
+            Phronomy::Tool::CallRequest.new(
+              id: SecureRandom.uuid, name: search.fetch("name"),
+              arguments: {"query" => "Ruby AI frameworks"}
+            )
+          ])
+        end
+
+        Phronomy::LLMAdapter::Response.new(content: "ci-stub-output")
       end
-      Base.prepend(CiInvokeStub)
 
-      class Runner
-        def invoke(input = nil, **)
-          {output: "ci-stub-output", agent: nil, messages: []}
-        end
+      def perform_stream(request, cancellation_token:)
+        response = perform_complete(request, cancellation_token: cancellation_token)
+        yield Phronomy::LLMAdapter::StreamChunk.new(content: response.content) if response.content
+        response
       end
     end
+  RUBY
 
-    module Chain
-      class LLMChain
-        def invoke(vars = {})
-          "ci-stub-chain"
-        end
-      end
+  def self.blocks(path)
+    text = File.read(path)
+    text.to_enum(:scan, /^```ruby runnable\n(.*?)^```/m).map do
+      match = Regexp.last_match
+      [text[0...match.begin(1)].count("\n") + 1, match[1]]
     end
   end
-  # --- end CI preamble ---
-
-RUBY
-
-readme = File.read(README_PATH)
 
-# Match opening fence with 'runnable' annotation: ```ruby runnable
-blocks = readme.scan(/^```ruby runnable\n(.*?)^```/m).map.with_index(1) { |(code), i| [i, code] }
-
-if blocks.empty?
-  puts "No 'ruby runnable' blocks found in README.md."
-  exit 0
-end
-
-puts "Checking #{blocks.size} runnable Ruby block(s) in README.md..."
-
-failures = []
-
-blocks.each do |index, code|
-  Tempfile.create(["readme_runnable_#{index}", ".rb"]) do |f|
-    f.write(PREAMBLE)
-    f.write(code)
-    f.flush
-
-    out, err, status = Open3.capture3(RbConfig.ruby, f.path)
-    combined = (out + err).gsub(f.path, "block ##{index}")
-
-    if status.success?
-      puts "  OK   block ##{index}"
-    else
-      failures << index
-      puts "  FAIL block ##{index}"
-      # Print at most 15 lines of output to keep CI logs readable.
-      puts combined.lines.first(15).join
+  def self.check(paths = PATHS, output: $stdout)
+    failures = []
+    count = 0
+    paths.each do |relative|
+      path = File.expand_path(relative, ROOT)
+      examples = blocks(path)
+      if examples.empty?
+        failures << relative
+        output.puts "FAIL #{relative}: no ruby runnable blocks"
+      end
+      examples.each do |line, code|
+        count += 1
+        label = "#{relative}:#{line}"
+        Tempfile.create(["phronomy_documentation", ".rb"]) do |file|
+          file.write(PREAMBLE)
+          file.write(<<~RUBY)
+            Phronomy.with_configuration do |configuration|
+              configuration.llm_adapter = DocumentationLLM.new
+              begin
+                Timeout.timeout(20) do
+                  eval(#{code.dump}, TOPLEVEL_BINDING, #{path.dump}, #{line})
+                end
+              ensure
+                Phronomy::Runtime.reset_default!(timeout: 5)
+              end
+            end
+          RUBY
+          file.flush
+          out, err, status = Open3.capture3(
+            {"BUNDLE_GEMFILE" => File.join(ROOT, "Gemfile")},
+            RbConfig.ruby, file.path, chdir: ROOT
+          )
+          if status.success?
+            output.puts "OK   #{label}"
+          else
+            failures << label
+            output.puts "FAIL #{label}"
+            output.puts (out + err).gsub(file.path, label).lines.first(15).join
+          end
+        end
+      end
     end
+    output.puts "#{count} runnable examples; #{failures.size} failures"
+    failures.empty?
   end
 end
 
-puts
-if failures.empty?
-  puts "All #{blocks.size} runnable block(s) passed."
-  exit 0
-else
-  puts "#{failures.size} block(s) failed: #{failures.join(", ")}"
-  exit 1
+if $PROGRAM_NAME == __FILE__
+  paths = ARGV.empty? ? RunnableDocumentation::PATHS : ARGV
+  exit(RunnableDocumentation.check(paths) ? 0 : 1)
 end

data/sig/phronomy/agent/agent_not_found_error.rbs

@@ -0,0 +1,6 @@
+module Phronomy
+  class AgentNotFoundError < Phronomy::Persistence::NotFoundError
+    attr_reader agent_id: String
+    def initialize: (agent_id: untyped) -> void
+  end
+end

data/sig/phronomy/agent/agent_unloaded_error.rbs

@@ -0,0 +1,6 @@
+module Phronomy
+  class AgentUnloadedError < Phronomy::Error
+    attr_reader agent_id: String
+    def initialize: (agent_id: String) -> void
+  end
+end

data/sig/phronomy/agent/stream_callback_error.rbs

@@ -0,0 +1,8 @@
+module Phronomy
+  class StreamCallbackError < Error
+    attr_reader event_type: Symbol
+    attr_reader original_error: Exception
+    attr_reader result: untyped
+    def initialize: (event_type: Symbol, original_error: Exception, ?result: untyped, ?code: String?) -> void
+  end
+end

data/sig/phronomy/agent.rbs

@@ -1,5 +1,21 @@
 module Phronomy
   module Agent
+    # The block's TaskResult is awaited and unwrapped; Scope itself is process-local.
+    def self.open_scope: [R] () { (Scope) -> (R | Phronomy::TaskResult[R]) } -> R
+
+    class Scope
+      def create: (singleton(Base) agent_class, **untyped options) ?{ (untyped event) -> void } -> Base
+      def create_async: (singleton(Base) agent_class, **untyped options) ?{ (untyped event) -> void } -> Phronomy::TaskResult[Base]
+      def load: (singleton(Base) agent_class, String agent_id, persistence: Store, **untyped options) ?{ (untyped event) -> void } -> Base
+      def load_async: (singleton(Base) agent_class, String agent_id, persistence: Store, **untyped options) ?{ (untyped event) -> void } -> Phronomy::TaskResult[Base]
+    end
+
+    class ScopeCleanupError < Phronomy::Error
+      attr_reader failures: Array[{ agent_id: String, error: Exception }]
+      attr_reader result: untyped
+      def initialize: (failures: Array[{ agent_id: String, error: Exception }], result: untyped) -> void
+    end
+
     interface _BeforeLLMInputHook
       def call: (Phronomy::Context::LLMInputBuildContext context) -> Phronomy::Context::LLMInputPatch?
     end
@@ -108,6 +124,8 @@ module Phronomy
       def reset_context!: () -> untyped
       def close!: () -> untyped
       def purge!: () -> bool
+      def unload_async: () -> Phronomy::TaskResult[bool]
+      def unload!: (?timeout: Numeric?) -> bool
     end
   end
 end

data/sig/phronomy/embeddings/base.rbs

@@ -6,6 +6,12 @@ module Phronomy
     class TransportError < Phronomy::Error
     end
 
+    class AuthenticationError < TransportError
+    end
+
+    class RateLimitError < TransportError
+    end
+
     class Base
       def embed: (String text, ?_CancellationSignal? cancellation_token) -> Array[Float]
 

data/sig/phronomy/execution/execution.rbs

@@ -30,12 +30,12 @@ module Phronomy
 
   class ExecutionTimeoutError < TimeoutError
     attr_reader outcomes: Array[TaskResult::Outcome[untyped]]
-    def initialize: (?String message, outcomes: Array[TaskResult::Outcome[untyped]]) -> void
+    def initialize: (?String message, outcomes: Array[TaskResult::Outcome[untyped]], ?code: String?) -> void
   end
 
   class ExecutionCancellationError < CancellationError
     attr_reader outcomes: Array[TaskResult::Outcome[untyped]]
-    def initialize: (?String message, outcomes: Array[TaskResult::Outcome[untyped]]) -> void
+    def initialize: (?String message, outcomes: Array[TaskResult::Outcome[untyped]], ?code: String?) -> void
   end
 
 end

data/sig/phronomy/extensions.rbs

@@ -14,6 +14,7 @@ module Phronomy
 
   module Tracing
     class Base
+      def self.trace_with: [A] (untyped tracer, String name, ?record_output: bool, ?attributes: Hash[Symbol, untyped]) { (untyped span) -> [A, untyped] } -> A
       def start_span: (String name, **untyped attributes) -> untyped
       def finish_span: (untyped span, ?output: untyped, ?usage: untyped, ?error: Exception?) -> untyped
       def trace: [A] (String name, ?input: untyped, **untyped meta) { (untyped span) -> [A, untyped] } -> A

data/sig/phronomy/filter/filter_block_error.rbs

@@ -0,0 +1,6 @@
+module Phronomy
+  class FilterBlockError < Error
+    attr_reader filter: untyped
+    def initialize: (String message, ?filter: untyped, ?code: String?) -> void
+  end
+end

data/sig/phronomy/generation/low_confidence_error.rbs

@@ -0,0 +1,6 @@
+module Phronomy
+  class LowConfidenceError < Error
+    attr_reader result: untyped
+    def initialize: (untyped result, ?code: String?) -> void
+  end
+end

data/sig/phronomy/integrations.rbs

@@ -0,0 +1,14 @@
+module Phronomy
+  module Integrations
+    class OrderedEventDelivery
+      class ClosedError < Phronomy::Error
+      end
+      class OverflowError < Phronomy::Error
+      end
+      def self.open: [T] (?capacity: Integer, ?batch_size: Integer, ?flush_timeout: Numeric?, deliver: ^(untyped) -> untyped, ?prepare_batch: (^(Array[untyped]) -> Array[untyped])?) { (OrderedEventDelivery) -> T } -> T
+      def initialize: (?capacity: Integer, ?batch_size: Integer, ?prepare_batch: (^(Array[untyped]) -> Array[untyped])?) { (untyped) -> untyped } -> void
+      def publish: (untyped) -> self
+      def close_and_wait: (?timeout: Numeric?) -> self
+    end
+  end
+end

data/sig/phronomy/multi_agent/team_busy_error.rbs

@@ -0,0 +1,8 @@
+module Phronomy
+  module MultiAgent
+    class TeamBusyError < Phronomy::Error
+      attr_reader team_id: String
+      def initialize: (?String? message, team_id: untyped) -> void
+    end
+  end
+end

data/sig/phronomy/multi_agent/team_not_found_error.rbs

@@ -0,0 +1,8 @@
+module Phronomy
+  module MultiAgent
+    class TeamNotFoundError < Phronomy::Persistence::NotFoundError
+      attr_reader team_id: String
+      def initialize: (?String? message, team_id: untyped) -> void
+    end
+  end
+end

data/sig/phronomy/storage/contracts.rbs

@@ -16,11 +16,11 @@ module Phronomy
     class UniqueConstraintError < ConflictError
       attr_reader resource: String
       attr_reader constraint: Symbol
-      def initialize: (resource: Resource, constraint: Symbol) -> void
+      def initialize: (resource: Resource, constraint: Symbol, ?code: String?) -> void
     end
     class ConditionFailedError < ConflictError
       attr_reader condition: condition
-      def initialize: (condition) -> void
+      def initialize: (condition, ?code: String?) -> void
     end
     class BlobConflictError < ConflictError
     end

data/sig/phronomy/workflow/execution/workflow_execution_environment.rbs

@@ -10,5 +10,6 @@ module Phronomy
     def compile_transitions: (**untyped definition) -> untyped
     def build_session: (**untyped options) -> untyped
     def register_session: (untyped session, completion: TaskResult[untyped]) -> untyped
+    def subscribe_cancellation: (Concurrency::CancellationToken token) { () -> void } -> untyped
   end
 end

data/sig/phronomy/workflow.rbs

@@ -1,4 +1,7 @@
 module Phronomy
+  class WorkflowTaskResumeError < Error
+    def initialize: (?String message, ?code: String?) -> void
+  end
   module WorkflowContext
     def phase: () -> Symbol
     def halted?: () -> bool
@@ -20,6 +23,7 @@ module Phronomy
     class Builder
       def initial: (Symbol state_name) -> untyped
       def state: (Symbol name, ?action: untyped) -> untyped
+      def task_state: (Symbol name, start: ^(untyped) -> TaskResult[untyped], apply: ^(untyped, untyped) -> untyped) -> void
       def entry: (Symbol name, untyped callable) -> untyped
       def exit: (Symbol name, untyped callable) -> untyped
       def wait_state: (Symbol name) -> untyped

data/sig/phronomy.rbs

@@ -2,6 +2,10 @@ module Phronomy
   VERSION: String
 
   class Error < StandardError
+    attr_reader code: String?
+    def initialize: (?untyped message, ?code: String?) -> void
+    def self.diagnostic: (Exception) -> Hash[String, untyped]
+    def self.from_diagnostic: (Hash[untyped, untyped], ?remaining: Integer) -> Error
   end
 
   class ParseError < Error