phronomy 0.6.0 → 0.7.1

data/lib/phronomy/workflow_context.rb

@@ -11,7 +11,7 @@ module Phronomy
   # Field update policies:
   #   :replace (default) -- overwrites with the new value
   #   :append            -- appends to an Array
-  #   :merge             -- deep-merges into a Hash
+  #   :merge             -- shallow-merges into a Hash (top-level keys are merged; nested objects are replaced)
   #
   # @example
   #   class ScanContext
@@ -31,9 +31,27 @@ module Phronomy
       # @param name [Symbol]
       # @param type [Symbol] :replace / :append / :merge
       # @param default [Object, Proc, nil]
+      # @raise [ArgumentError] if +default+ is a plain Array or Hash (use a Proc instead)
+      # @api public
       def field(name, type: :replace, default: nil)
+        if default.is_a?(Array) || default.is_a?(Hash)
+          raise ArgumentError,
+            "Mutable default for field #{name.inspect} must be wrapped in a Proc " \
+            "to avoid shared state across instances. " \
+            "Use `default: -> { #{default.inspect} }` instead."
+        end
+
         @fields[name] = {type: type, default: default}
-        attr_accessor name
+
+        # Define getter.
+        attr_reader name
+
+        # Define write-guarded setter.  Mutation from outside the EventLoop
+        # dispatch thread raises WorkflowContextOwnershipError in EventLoop mode.
+        define_method(:"#{name}=") do |value|
+          _assert_write_permitted!
+          instance_variable_set(:"@#{name}", value)
+        end
       end
 
       def fields
@@ -51,12 +69,14 @@ module Phronomy
     #   :awaiting_<name>   — halted at a wait_state(:awaiting_<name>) declaration
     #   :<state>           — resuming at <state> (workflow paused before its execution)
     # @return [Symbol]
+    # @api public
     def phase
       @phase || :__end__
     end
 
     # Returns true if the workflow is paused mid-execution (not yet completed).
     # @return [Boolean]
+    # @api public
     def halted?
       phase != :__end__
     end
@@ -64,6 +84,7 @@ module Phronomy
     # Sets internal workflow metadata. Returns self.
     # @param thread_id [String, nil]
     # @param phase [Symbol, nil]
+    # @api public
     def set_graph_metadata(thread_id: nil, phase: nil)
       @thread_id = thread_id unless thread_id.nil?
       @phase = phase unless phase.nil?
@@ -71,19 +92,32 @@ module Phronomy
     end
 
     def initialize(**attrs)
+      unknown = attrs.keys - self.class.fields.keys
+      raise ArgumentError, "Unknown WorkflowContext field(s): #{unknown.inspect}" unless unknown.empty?
+
       self.class.fields.each do |name, config|
         default = config[:default].is_a?(Proc) ? config[:default].call : config[:default]
-        send(:"#{name}=", attrs.fetch(name, default))
+        # Bypass the write guard in initialize — ownership enforcement begins
+        # after construction is complete.
+        instance_variable_set(:"@#{name}", attrs.fetch(name, default))
       end
       @thread_id = nil
       @phase = :__end__
     end
 
-    # Immutably updates context fields. Returns a new instance with the applied changes.
-    # Internal workflow metadata (thread_id, phase) is preserved.
+    # Returns a new context instance with the specified field updates applied.
+    # Updated fields follow the field's declared +:type+ semantics (:replace, :append,
+    # or :merge). Unchanged fields are deep-copied on a best-effort basis — objects
+    # that do not support +#dup+ (e.g. integers, frozen objects) are carried over
+    # by reference. Internal workflow metadata (thread_id, phase) is preserved.
     # @param updates [Hash] { field_name => new_value }
     # @return [self.class] new context instance
+    # @raise [ArgumentError] if updates contains keys that are not declared fields
+    # @api public
     def merge(updates)
+      unknown = updates.keys - self.class.fields.keys
+      raise ArgumentError, "Unknown WorkflowContext field(s): #{unknown.inspect}" unless unknown.empty?
+
       new_attrs = {}
       self.class.fields.each_key do |name|
         field_config = self.class.fields[name]
@@ -97,7 +131,7 @@ module Phronomy
             updates[name]
           end
         else
-          send(name)
+          deep_dup_value(send(name))
         end
       end
       new_context = self.class.new(**new_attrs)
@@ -110,10 +144,53 @@ module Phronomy
 
     # Converts user-defined fields to a Hash (excludes internal workflow metadata).
     # @return [Hash]
+    # @api public
     def to_h
       self.class.fields.keys.each_with_object({}) do |name, h|
         h[name] = send(name)
       end
     end
+
+    private
+
+    # Asserts that the calling thread is allowed to mutate this context.
+    # No-op when EventLoop mode is disabled.
+    # @raise [Phronomy::WorkflowContextOwnershipError] when called from a
+    #   non-EventLoop thread in EventLoop mode.
+    # @api private
+    def _assert_write_permitted!
+      return unless defined?(Phronomy::EventLoop) &&
+        Phronomy.configuration.event_loop
+      return if Phronomy::EventLoop.current?
+
+      raise Phronomy::WorkflowContextOwnershipError,
+        "WorkflowContext fields may only be mutated from the EventLoop dispatch " \
+        "thread. Use context.merge(...) to produce a new context, or deliver " \
+        "updates as event payloads."
+    end
+
+    # Performs a deep copy of a value for immutable context propagation.
+    # Arrays and Hashes are deep-duplicated recursively.
+    # Immutable values (nil, Symbol, Integer, Float, true/false, frozen String) are returned as-is.
+    # Other objects are dup'd (best-effort shallow copy for custom types).
+    # Objects that cannot be dup'd (e.g. Proc, Method) are returned as-is.
+    def deep_dup_value(val)
+      case val
+      when Array
+        val.map { |v| deep_dup_value(v) }
+      when Hash
+        val.each_with_object({}) { |(k, v), h| h[k] = deep_dup_value(v) }
+      when NilClass, Symbol, Integer, Float, TrueClass, FalseClass
+        val
+      else
+        return val if val.frozen?
+
+        begin
+          val.dup
+        rescue TypeError
+          val
+        end
+      end
+    end
   end
 end

data/lib/phronomy/workflow_runner.rb

@@ -17,8 +17,11 @@ module Phronomy
   # determined by the declared state machine topology, never by Phronomy internals.
   #
   # Entry and exit actions are registered as state_machines +after_transition to:+
-  # and +before_transition from:+ callbacks respectively. The WorkflowContext is
-  # mutable; actions receive it and modify fields in place.
+  # and +before_transition from:+ callbacks respectively. Entry actions may either
+  # mutate the context in place or return a new context (e.g. via +s.merge(...)+).
+  # When an entry action returns a Phronomy::WorkflowContext, that value replaces
+  # the current context; otherwise the return value is ignored.
+  # Exit actions are always mutation-in-place; their return value is ignored.
   #
   # The sole exception is the initial state: state_machines does not fire transition
   # callbacks on initialization, so the entry action for the entry point is invoked
@@ -35,13 +38,14 @@ module Phronomy
   #   2. <event_name>    — external events triggered by human input, originating
   #                        from wait states
   #                        (declared with +transition from: :awaiting, on: :approve, to: :run+)
+  # @api private
   class WorkflowRunner
     include Phronomy::Runnable
 
     # Sentinel value for the terminal state of a workflow.
     FINISH = :__end__
 
-    def initialize(state_class:, entry_actions:, declared_states:, auto_transitions:, external_events:, entry_point:, exit_actions: {}, wait_state_names: [])
+    def initialize(state_class:, entry_actions:, declared_states:, auto_transitions:, external_events:, entry_point:, exit_actions: {}, wait_state_names: [], state_store: nil, action_timeouts: {})
       @state_class = state_class
       @entry_actions = entry_actions   # { state_name => [callable, ...] }
       @declared_states = declared_states
@@ -50,13 +54,16 @@ module Phronomy
       @external_events = external_events    # { name => [{from:, to:, guard:}, ...] }
       @entry_point = entry_point
       @wait_state_names = wait_state_names
+      @state_store = state_store
+      @action_timeouts = action_timeouts   # { state_name => seconds }
       @phase_machine_class = build_phase_machine_class(auto_transitions, exit_actions)
     end
 
     # Executes the workflow from the initial state.
     # @param input [Hash] initial context field values
-    # @param config [Hash] { thread_id:, recursion_limit:, user_id:, session_id: }
+    # @param config [Hash] { thread_id:, recursion_limit:, user_id:, session_id:, state_store: }
     # @return [Object] final context (includes Phronomy::WorkflowContext)
+    # @api private
     def invoke(input, config: {})
       caller_meta = {}
       caller_meta[:user_id] = config[:user_id] if config[:user_id]
@@ -65,13 +72,23 @@ module Phronomy
       trace("workflow.invoke", input: input.inspect, **caller_meta) do |_span|
         thread_id = config[:thread_id] || SecureRandom.uuid
         recursion_limit = config.fetch(:recursion_limit, Phronomy.configuration.recursion_limit)
-        state = @state_class.new(**input)
+
+        store = config.fetch(:state_store, @state_store) || Phronomy.configuration.state_store
+        snapshot = (store && config[:thread_id]) ? store.load(thread_id) : nil
+        initial_fields = if snapshot && snapshot[:fields]
+          snapshot[:fields].transform_keys(&:to_sym).merge(input.transform_keys(&:to_sym))
+        else
+          input
+        end
+
+        state = @state_class.new(**initial_fields)
         state.set_graph_metadata(thread_id: thread_id)
         result = if Phronomy.configuration.event_loop
           run_via_event_loop(state, recursion_limit: recursion_limit)
         else
           run_workflow(state, recursion_limit: recursion_limit)
         end
+        store&.save(thread_id, {fields: result.to_h, phase: result.phase.to_s}) if config[:thread_id]
         [result, nil]
       end
     end
@@ -80,6 +97,7 @@ module Phronomy
     # @param state [Object] halted context
     # @param input [Hash, nil] optional field updates to merge before resuming
     # @return [Object] final context
+    # @api private
     def resume(state:, input: nil)
       send_event(state: state, event: :resume, input: input)
     end
@@ -93,6 +111,7 @@ module Phronomy
     # @param event [Symbol] named event or +:resume+ for generic resumption
     # @param input [Hash, nil] optional field updates to merge before resuming
     # @return [Object] final context
+    # @api private
     def send_event(state:, event:, input: nil)
       state = state.merge(input) if input
       event = event.to_sym
@@ -128,6 +147,7 @@ module Phronomy
     # @param config [Hash]
     # @yield [Hash]
     # @return [Object] final context
+    # @api private
     def stream(input, config: {}, &block)
       thread_id = config[:thread_id] || SecureRandom.uuid
       recursion_limit = config.fetch(:recursion_limit, Phronomy.configuration.recursion_limit)
@@ -151,6 +171,7 @@ module Phronomy
         external_events: @external_events,
         phase_machine_class: @phase_machine_class,
         recursion_limit: recursion_limit,
+        action_timeouts: @action_timeouts,
         resume_event: resume_event,
         resume_phase: resume_phase
       )
@@ -180,6 +201,7 @@ module Phronomy
         tracker = new_phase_machine(current_state)
         tracker.context = ctx
         fire_event!(tracker, resume_event, current_state)
+        ctx = tracker.context
         next_phase = tracker.phase.to_sym
         current_state = (next_phase == current_state) ? FINISH : next_phase
       else
@@ -189,7 +211,24 @@ module Phronomy
         tracker.context = ctx
         # state_machines only fires after_transition callbacks on transitions.
         # The entry point has no prior transition, so we invoke its entry actions directly.
-        @entry_actions[current_state]&.each { |c| c.call(ctx) }
+        @entry_actions[current_state]&.each do |c|
+          result = c.call(ctx)
+          if result.is_a?(Phronomy::Task)
+            timeout_secs = @action_timeouts[current_state]
+            if timeout_secs
+              if result.join(timeout_secs).nil?
+                result.cancel!
+                raise Phronomy::ActionTimeoutError,
+                  "Action in state #{current_state.inspect} timed out after #{timeout_secs}s"
+              end
+            end
+            task_result = result.await
+            ctx = task_result if task_result.is_a?(Phronomy::WorkflowContext)
+          elsif result.is_a?(Phronomy::WorkflowContext)
+            ctx = result
+          end
+        end
+        tracker.context = ctx
       end
 
       # Event queue: decouple action execution from transition firing.
@@ -211,6 +250,7 @@ module Phronomy
           end
 
           fire_event!(tracker, event, current_state)
+          ctx = tracker.context
           next_phase = tracker.phase.to_sym
           # When next_phase == current_state no transition matched → terminal state.
           current_state = (next_phase == current_state) ? FINISH : next_phase
@@ -277,11 +317,17 @@ module Phronomy
       ext_events = @external_events
       entry_acts = @entry_actions
       exit_acts = exit_actions
+      act_timeouts = @action_timeouts  # { state_name => seconds }
 
       Class.new do
         # Holds the current WorkflowContext so guards and callbacks can read it.
         attr_accessor :context
 
+        # Set to true by an entry action that returned an awaitable Task.
+        # When true, FSMSession skips the automatic advance_or_halt step and
+        # waits for the async worker thread to post a state_completed event back.
+        attr_accessor :async_pending
+
         state_machine :phase, initial: entry do
           all_states.each { |s| state s }
 
@@ -316,10 +362,63 @@ module Phronomy
           # Entry callbacks: fire after_transition into each state.
           #    Each callable is registered as a separate callback; state_machines
           #    accumulates them and fires in declaration order.
+          #    If the callable returns a WorkflowContext (e.g. via s.merge(...)),
+          #    the returned context replaces the current one on the tracker.
           entry_acts.each do |state_name, callables|
             callables.each do |callable|
+              timeout_secs = act_timeouts[state_name]
               after_transition to: state_name do |machine|
-                callable.call(machine.context)
+                result = callable.call(machine.context)
+                if result.is_a?(Phronomy::Task)
+                  if Phronomy.configuration.event_loop
+                    # EventLoop mode: await in a background task so the EventLoop
+                    # thread is not blocked. Signal async_pending so FSMSession
+                    # skips the automatic advance_or_halt step.
+                    machine.async_pending = true
+                    ctx_ref = machine.context
+                    thread_id = ctx_ref.thread_id
+                    Phronomy::Runtime.instance.spawn(name: "wf-await-#{thread_id}") do
+                      if timeout_secs
+                        if result.join(timeout_secs).nil?
+                          result.cancel!
+                          raise Phronomy::ActionTimeoutError,
+                            "Action in state #{state_name.inspect} timed out after #{timeout_secs}s"
+                        end
+                      end
+                      task_result = result.await
+                      if task_result.is_a?(Phronomy::WorkflowContext)
+                        Phronomy::EventLoop.instance.post(
+                          Phronomy::Event.new(
+                            type: :action_completed,
+                            target_id: thread_id,
+                            payload: task_result
+                          )
+                        )
+                      else
+                        Phronomy::EventLoop.instance.post(
+                          Phronomy::Event.new(type: :state_completed, target_id: thread_id, payload: nil)
+                        )
+                      end
+                    rescue => e
+                      Phronomy::EventLoop.instance.post(
+                        Phronomy::Event.new(type: :error, target_id: thread_id, payload: e)
+                      )
+                    end
+                  else
+                    # Non-EventLoop mode: block synchronously on the task result.
+                    if timeout_secs
+                      if result.join(timeout_secs).nil?
+                        result.cancel!
+                        raise Phronomy::ActionTimeoutError,
+                          "Action in state #{state_name.inspect} timed out after #{timeout_secs}s"
+                      end
+                    end
+                    task_result = result.await
+                    machine.context = task_result if task_result.is_a?(Phronomy::WorkflowContext)
+                  end
+                elsif result.is_a?(Phronomy::WorkflowContext)
+                  machine.context = result
+                end
               end
             end
           end

data/lib/phronomy.rb

@@ -12,6 +12,10 @@ loader.inflector.inflect("ruby_llm_embeddings" => "RubyLLMEmbeddings")
 loader.inflector.inflect("fsm_session" => "FSMSession")
 # AgentFSM: Zeitwerk would infer "Fsm" — override to "FSM".
 loader.inflector.inflect("fsm" => "FSM")
+# LLMAdapter: Zeitwerk would infer "LlmAdapter" — override to "LLMAdapter".
+loader.inflector.inflect("llm_adapter" => "LLMAdapter")
+# LLMAdapter::RubyLLM: "ruby_llm" maps to "RubyLLM" (not "RubyLlm").
+loader.inflector.inflect("ruby_llm" => "RubyLLM")
 loader.setup
 
 require_relative "phronomy/version"
@@ -23,11 +27,49 @@ module Phronomy
   class ParseError < Error; end
   class RecursionLimitError < Error; end
   class ToolError < Error; end
+  # Raised when an agent invocation exceeds the timeout set via +invoke_timeout+.
+  class TimeoutError < Error; end
 
   class ConfigurationError < Error; end
 
   class HandoffError < Error; end
 
+  # Raised when a network or transport layer call fails (e.g. LLM API unreachable,
+  # MCP server connection refused). Distinguishable from application-level errors
+  # so callers can apply network-specific retry logic.
+  class TransportError < Error; end
+
+  # Raised when the LLM API returns a rate-limit response (HTTP 429 or equivalent).
+  # Callers should back off and retry after the indicated delay.
+  class RateLimitError < TransportError; end
+
+  # Raised when the LLM API rejects the request due to an invalid or revoked API key.
+  # Callers should not retry without fixing the credentials.
+  class AuthenticationError < TransportError; end
+
+  # Raised when the prompt exceeds the model's context window limit.
+  class ContextLengthError < Error; end
+
+  # Raised when a workflow or agent execution is explicitly cancelled.
+  # Separate from TimeoutError (deadline exceeded) — this is an intentional stop.
+  class CancellationError < Error; end
+
+  # Raised when {Agent#invoke} (a synchronous, blocking call) is attempted from
+  # inside an active scheduler task and +strict_runtime_guards+ is enabled.
+  #
+  # Calling a blocking invocation from within a scheduler task stalls the
+  # scheduler until the inner invocation completes, preventing other tasks from
+  # making progress (hidden deadlock risk).  Use {Agent#invoke_async} followed by
+  # +#await+ inside scheduler tasks instead.
+  #
+  # This error is only raised when:
+  #   Phronomy.configure { |c| c.strict_runtime_guards = true }
+  #
+  # By default a warning is logged and execution continues.
+  #
+  # @see Phronomy::Runtime.in_scheduler_context?
+  class SchedulerReentrancyError < Error; end
+
   # Raised by {Phronomy::GeneratorVerifier#invoke} when +raise_if_untrusted: true+
   # and the pipeline's combined confidence score falls below the configured threshold.
   #
@@ -54,6 +96,28 @@ module Phronomy
     end
   end
 
+  # Raised when an operation is submitted to a {BlockingAdapterPool} that has
+  # already been shut down via {BlockingAdapterPool#shutdown}.
+  class PoolShutdownError < Error; end
+
+  # Raised when a concurrency limit is exceeded and the configured backpressure
+  # strategy is +:raise+. The caller should back off and retry.
+  class BackpressureError < Error; end
+
+  # Raised by {CancellationScope#pop_queue} when the deadline expires before a
+  # result is available. Extends {TimeoutError} for backwards compatibility.
+  class ScopeTimeoutError < TimeoutError; end
+
+  # Raised when a Workflow entry/exit action task exceeds the +action_timeout:+
+  # configured for its state.  Extends {TimeoutError}.
+  class ActionTimeoutError < TimeoutError; end
+
+  # Raised when a {Phronomy::WorkflowContext} field is mutated from a thread
+  # that does not own the context (i.e. not the EventLoop dispatch thread).
+  # Only raised in EventLoop mode.  Use +context.merge(...)+ to produce a new
+  # context, or deliver updates as +:child_completed+ event payloads.
+  class WorkflowContextOwnershipError < Error; end
+
   class << self
     def configuration
       @configuration ||= Configuration.new
@@ -63,9 +127,56 @@ module Phronomy
       yield configuration
     end
 
-    # Resets configuration; primarily used in tests.
+    # Resets the global Phronomy configuration to defaults.
+    #
+    # **Intended for test suites only.** Calling this in a production process
+    # will drop all runtime configuration (tracer, model, tokenizer, etc.)
+    # globally and immediately affect all subsequent agent and workflow calls.
+    #
+    # **Parallel test suites warning:** When tests run in parallel (e.g.
+    # `parallel_tests` or `parallel_rspec`), +reset_configuration!+ in one
+    # worker will clear configuration shared with other workers in the same
+    # process. Prefer process-isolation strategies (forked workers) over
+    # thread-based parallelism when using this method.
+    #
+    # Typical usage in a sequential test suite:
+    #   after { Phronomy.reset_configuration! }
     def reset_configuration!
       @configuration = Configuration.new
     end
+
+    # Yields the current {Configuration} object, then restores the original
+    # configuration on exit (even if the block raises).
+    #
+    # Intended for test helpers that need to temporarily override settings
+    # without permanently mutating the global configuration.
+    #
+    # @yield [config] the current {Configuration} instance (mutable)
+    # @example
+    #   Phronomy.with_configuration do |c|
+    #     c.logger = Logger.new($stdout)
+    #   end
+    # @api public
+    def with_configuration
+      original = @configuration&.dup
+      yield configuration
+    ensure
+      @configuration = original
+    end
+
+    # Resets all Phronomy runtime state: configuration and the EventLoop
+    # singleton (if running).
+    #
+    # **Intended for test suites only.**  Stops any running EventLoop thread,
+    # clears the EventLoop singleton, and resets configuration to defaults.
+    # Call once before/after each example to ensure test isolation.
+    #
+    # @example
+    #   config.around { |ex| Phronomy.reset_runtime! ; ex.run ; Phronomy.reset_runtime! }
+    # @api public
+    def reset_runtime!
+      Phronomy::EventLoop.reset!
+      @configuration = Configuration.new
+    end
   end
 end

data/scripts/api_snapshot.rb

@@ -0,0 +1,91 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# scripts/api_snapshot.rb
+#
+# Dumps the public instance methods of all Stable/Beta public API classes to
+# JSON.  The snapshot is stored in spec/fixtures/api_snapshot.json and is used
+# by spec/phronomy/api_compatibility_spec.rb to detect unintended API removals.
+#
+# Usage:
+#   # Regenerate spec/fixtures/api_snapshot.json (run when intentionally adding
+#   # or removing public API methods after updating the stability table):
+#   ruby scripts/api_snapshot.rb --write
+#
+#   # Print snapshot to stdout (useful for manual inspection):
+#   ruby scripts/api_snapshot.rb
+
+require "json"
+require "fileutils"
+require_relative "../lib/phronomy"
+
+# Classes and modules whose public API is tracked.
+# Add an entry whenever a new class/module is promoted to Stable or Beta in README.md.
+PUBLIC_API_ENTRIES = [
+  # Stable
+  Phronomy::Agent::Base,
+  Phronomy::Tool::Base,
+  Phronomy::Workflow,
+  Phronomy::WorkflowContext,
+  Phronomy::Runnable,
+  Phronomy::PromptTemplate,
+  # Beta
+  Phronomy::Agent::ReactAgent,
+  Phronomy::Agent::Orchestrator,
+  Phronomy::Agent::TeamCoordinator,
+  Phronomy::Guardrail::InputGuardrail,
+  Phronomy::Guardrail::OutputGuardrail,
+  Phronomy::VectorStore::Base,
+  Phronomy::VectorStore::InMemory,
+  Phronomy::Embeddings::Base,
+  Phronomy::KnowledgeSource::Base,
+  Phronomy::KnowledgeSource::StaticKnowledge,
+  Phronomy::KnowledgeSource::RAGKnowledge,
+  Phronomy::Tracing::Base,
+  Phronomy::Tracing::NullTracer,
+  Phronomy::Eval::Runner
+].freeze
+
+# Baseline methods common to all Ruby objects — excluded from the snapshot.
+BASELINE_INSTANCE_METHODS = (
+  Object.public_instance_methods |
+  Kernel.public_instance_methods
+).uniq.freeze
+
+BASELINE_CLASS_METHODS = (
+  Class.public_methods |
+  Module.public_methods
+).uniq.freeze
+
+def snapshot_entry(klass)
+  if klass.instance_of?(Module)
+    # Module — capture instance methods defined in this module only
+    own_methods = klass.public_instance_methods(false).sort
+    {
+      "name" => klass.name,
+      "type" => "module",
+      "public_instance_methods" => own_methods
+    }
+  else
+    # Class — capture public instance methods minus universal baseline
+    instance_methods = (klass.public_instance_methods - BASELINE_INSTANCE_METHODS).sort
+    class_methods = (klass.public_methods(false) - BASELINE_CLASS_METHODS).sort
+    {
+      "name" => klass.name,
+      "type" => "class",
+      "public_instance_methods" => instance_methods,
+      "public_class_methods" => class_methods
+    }
+  end
+end
+
+snapshot = PUBLIC_API_ENTRIES.map { |entry| snapshot_entry(entry) }
+
+if ARGV.include?("--write")
+  path = File.expand_path("../spec/fixtures/api_snapshot.json", __dir__)
+  FileUtils.mkdir_p(File.dirname(path))
+  File.write(path, JSON.pretty_generate(snapshot) + "\n")
+  puts "Wrote #{path}"
+else
+  puts JSON.pretty_generate(snapshot)
+end

data/scripts/check_api_annotations.rb

@@ -0,0 +1,68 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# check_api_annotations.rb
+#
+# Verifies that every YARD-documented public method in lib/ carries either
+# "@api public" or "@api private".
+#
+# A method is considered "YARD-documented" when its preceding comment block
+# contains at least one @param, @return, @raise, @yield, @example, or
+# @overload tag.  Methods with only a plain prose description (no @ tags)
+# are exempt.
+#
+# Usage (run from the phronomy/ repository root):
+#   ruby scripts/check_api_annotations.rb
+#
+# Exit codes:
+#   0 — all documented methods carry @api annotations
+#   1 — one or more documented methods are missing @api annotations
+
+lib_dir = File.expand_path("../lib", __dir__)
+
+unless File.directory?(lib_dir)
+  warn "ERROR: lib directory not found at #{lib_dir}"
+  exit 1
+end
+
+errors = []
+
+Dir.glob(File.join(lib_dir, "**", "*.rb")).sort.each do |file|
+  lines = File.readlines(file)
+
+  lines.each_with_index do |line, i|
+    next unless line.match?(/^\s*def\s+\w/)
+
+    # Collect the contiguous comment block immediately above this def.
+    comment_lines = []
+    j = i - 1
+    while j >= 0 && lines[j].match?(/^\s*#/)
+      comment_lines.unshift(lines[j])
+      j -= 1
+    end
+
+    next if comment_lines.empty?
+
+    comment = comment_lines.join
+
+    # Only lint methods that carry at least one YARD type tag.
+    next unless comment.match?(/#[ \t]+@(param|return|raise|yield|example|overload)/)
+
+    # Pass if an @api tag is already present.
+    next if comment.match?(/#[ \t]+@api[ \t]+(public|private)/)
+
+    rel_path = file.sub("#{lib_dir}/../", "")
+    m = line.match(/def\s+(\w+[!?=]?)/)
+    method_name = m ? m[1] : "unknown"
+    errors << "#{rel_path}:#{i + 1}  def #{method_name}  (missing @api public or @api private)"
+  end
+end
+
+if errors.empty?
+  puts "OK: all YARD-documented methods carry @api annotations"
+  exit 0
+else
+  puts "FAIL: #{errors.size} method(s) missing @api annotation:"
+  errors.each { |e| puts "  #{e}" }
+  exit 1
+end