phronomy 0.27.0 → 0.28.0

data/sig/phronomy/agent/execution_environment.rbs

@@ -0,0 +1,20 @@
+module Phronomy
+  module Agent
+    # Private composition port; serial ownership and routing are process-local.
+    class ExecutionEnvironment
+      def self.install_provider: (^() -> ExecutionEnvironment provider) -> untyped
+      def self.current: () -> ExecutionEnvironment
+      def registry: () -> untyped
+      def existing_registry: () -> untyped
+      def ownership: () -> untyped
+      def existing_ownership: () -> untyped
+      def executing?: () -> bool
+      def session_phase: (String id) -> Symbol?
+      def submit: [V] (**untyped options) { () -> V } -> TaskResult[V]
+      def submit_authorization: [V] (timeout: Numeric?, cancellation_token: Concurrency::CancellationToken?) { () -> V } -> TaskResult[V]
+      def build_agent_session: (invocation: untyped, ?resume_event: Symbol?, ?resume_phase: Symbol?) -> untyped
+      def build_tool_session: (invocation: untyped, parent_sink: untyped, ?resume_event: Symbol?, ?resume_phase: Symbol?) -> untyped
+      def register_session: (untyped session, completion: TaskResult[untyped]) -> untyped
+    end
+  end
+end

data/sig/phronomy/agent/store.rbs

@@ -0,0 +1,73 @@
+module Phronomy
+  interface _AgentRepository
+    def create: (untyped root) -> untyped
+    def load: (String agent_id) -> untyped
+    def save: (String agent_id, expected_revision: Integer, root: untyped) -> untyped
+    def delete: (String agent_id) -> untyped
+  end
+
+  interface _JournalRepository
+    def append: (String agent_id, expected_position: Integer, records: Array[untyped]) -> Array[untyped]
+    def read: (String agent_id, ?after: Integer?, ?limit: Integer?) -> Array[untyped]
+    def head: (String agent_id) -> Integer
+    def delete: (String agent_id) -> untyped
+  end
+
+  interface _ExecutionRepository
+    def create_active: (untyped execution) -> untyped
+    def load: (String execution_id) -> untyped
+    def save: (String execution_id, expected_revision: Integer, execution: untyped) -> untyped
+    def list_active: (String agent_id) -> Array[untyped]
+    def list: (String agent_id, ?after: String?, ?limit: Integer) -> Array[untyped]
+    def delete: (String execution_id) -> untyped
+    def delete_for_agent: (String agent_id) -> untyped
+    def assert_idle!: (String agent_id) -> untyped
+  end
+
+  module Agent
+    interface _Records
+      def contents: () -> _ContentRepository
+      def agents: () -> _AgentRepository
+      def journals: () -> _JournalRepository
+      def executions: () -> _ExecutionRepository
+      def guard_agent!: (String agent_id) -> untyped
+      def assert_agent_watermark!: (agent_id: String, agent_revision: Integer, journal_position: Integer) -> true
+    end
+
+    class Store
+      class AuthorizedOperation < Data
+        attr_reader invocation_id: String
+        attr_reader name: String
+        attr_reader arguments: Hash[String, json_value]
+        def self.new: (invocation_id: String, name: String, arguments: Hash[String, json_value]) -> instance
+      end
+
+      attr_reader coordinator: ::Phronomy::Persistence
+      attr_reader contents: _ContentRepository
+      attr_reader agents: _AgentRepository
+      attr_reader journals: _JournalRepository
+      attr_reader executions: _ExecutionRepository
+      def initialize: (coordinator: ::Phronomy::Persistence, records: ::Phronomy::Persistence::_Participant[_Records]) -> void
+      def transaction: [R] () { (_Records, ::Phronomy::Persistence::Transaction) -> R } -> R
+      def participate: [R] (::Phronomy::Persistence::Transaction scope) { (_Records) -> R } -> R
+      def exist?: (String agent_id) -> bool
+      def authorized_operations: (::Phronomy::Persistence::Transaction scope, agent_id: String, execution_id: String, invocation_id: String, name: String, arguments: Hash[String, untyped], names: Array[String]) -> Array[AuthorizedOperation]
+      def result: (String execution_id) -> Hash[Symbol, untyped]
+      def runs: (String owner_id, ?after: String?, ?limit: Integer) -> Array[untyped]
+      def observe_execution: (agent_id: String, execution_id: String, ?scope: ::Phronomy::Persistence::Transaction?) -> ExecutionObservation
+      def active_executions: (agent_id: String, ?scope: ::Phronomy::Persistence::Transaction?) -> Array[ExecutionObservation]
+      def definition: (agent_id: String, ?scope: ::Phronomy::Persistence::Transaction?) -> { id: String, version: Integer }
+      def knowledge_snapshot: (agent_id: String, ?scope: ::Phronomy::Persistence::Transaction?) -> Array[KnowledgeItem]
+      def execution_extension: (agent_id: String, execution_id: String, binding_key: String, ?scope: ::Phronomy::Persistence::Transaction?) -> ExecutionExtensionState?
+      def guard_agents: (::Phronomy::Persistence::Transaction scope, agent_ids: Array[String]) -> nil
+      def remove_execution_extension: (agent_id: String, execution_id: String, binding_key: String, scope: ::Phronomy::Persistence::Transaction) -> nil
+      def execution_identity: (String execution_id, ?scope: ::Phronomy::Persistence::Transaction?) -> ReservedExecution
+      def retained_references: (agent_id: String, ?scope: ::Phronomy::Persistence::Transaction?) -> Array[Retention]
+      def retain: (Retention retention, ?scope: ::Phronomy::Persistence::Transaction?) -> Retention
+      def release_retention: (agent_id: String, owner_key: String, scope: ::Phronomy::Persistence::Transaction) -> nil
+      def request_cancellation: (agent_id: String, execution_id: String, ?scope: ::Phronomy::Persistence::Transaction?) -> bool
+      def cancellation_requested?: (agent_id: String, execution_id: String, ?scope: ::Phronomy::Persistence::Transaction?) -> bool
+      def assert_agent_watermark!: (agent_id: String, agent_revision: Integer, journal_position: Integer) -> true
+    end
+  end
+end

data/sig/phronomy/agent.rbs

@@ -1,25 +1,7 @@
 module Phronomy
   module Agent
     interface _BeforeLLMInputHook
-      def call: (LLMInputBuildContext context) -> LLMInputPatch?
-    end
-
-    class LLMInputPatch
-      attr_reader model_config_patch: Hash[untyped, untyped]?
-      attr_reader segment_candidates: Array[untyped]?
-
-      def initialize: (?model_config_patch: Hash[untyped, untyped]?, ?segment_candidates: Array[untyped]?) -> void
-      def self.empty: () -> LLMInputPatch
-    end
-
-    class LLMInputBuildContext
-      attr_reader agent_id: String
-      attr_reader agent_definition_id: String
-      attr_reader agent_definition_version: Integer
-      attr_reader config: Hash[untyped, untyped]
-      attr_reader call_sequence: Integer
-
-      def initialize: (agent_id: String, agent_definition_id: String, agent_definition_version: Integer, ?config: Hash[untyped, untyped], call_sequence: Integer) -> void
+      def call: (Phronomy::Context::LLMInputBuildContext context) -> Phronomy::Context::LLMInputPatch?
     end
 
     class ToolApprovalRequest
@@ -67,118 +49,6 @@ module Phronomy
       def initialize: (agent_id: String, agent_definition_id: String, agent_definition_version: Integer, execution_id: String, tool_name: String, tool_schema: Hash[untyped, untyped], tool_invocation_id: String, tool_call_id: String?, arguments: Hash[untyped, untyped], ?facts: Hash[untyped, untyped], ?invocation_context: Hash[untyped, untyped], ?origin: Symbol, ?metadata: Hash[untyped, untyped], ?default_decision: Symbol?) -> void
     end
 
-    class LLMInputManifest
-      VERSION: String
-      CALL_MODES: Array[Symbol]
-      SEGMENT_DELIVERIES: Array[String]
-
-      def self.from_h: (Hash[String, untyped] hash) -> LLMInputManifest
-      def version: () -> String
-      def to_h: () -> Hash[String, untyped]
-    end
-
-    class ContextPolicyInput
-      class Provenance
-        attr_reader origin: Symbol
-        attr_reader content_ref: String?
-        attr_reader record_id: String?
-        attr_reader agent_id: String?
-        attr_reader execution_id: String?
-        attr_reader llm_call_id: String?
-        def initialize: (origin: Symbol, ?content_ref: String?, ?record_id: String?, ?agent_id: String?, ?execution_id: String?, ?llm_call_id: String?) -> void
-      end
-
-      class InstructionItem
-        attr_reader id: String
-        attr_reader kind: Symbol
-        attr_reader role: Symbol?
-        attr_reader content: untyped
-        attr_reader content_format: Symbol
-        attr_reader estimated_tokens: Integer
-        attr_reader required: bool
-        attr_reader provenance: Provenance
-        attr_reader metadata: Hash[untyped, untyped]
-        def initialize: (id: String, kind: Symbol, ?role: Symbol?, content: untyped, ?content_format: Symbol?, ?estimated_tokens: Integer?, ?required: bool?, ?provenance: Provenance?, ?metadata: Hash[untyped, untyped]) -> void
-        def required?: () -> bool
-      end
-
-      class KnowledgeItem
-        attr_reader id: String
-        attr_reader kind: Symbol
-        attr_reader role: Symbol?
-        attr_reader content: untyped
-        attr_reader content_format: Symbol
-        attr_reader estimated_tokens: Integer
-        attr_reader required: bool
-        attr_reader provenance: Provenance
-        attr_reader metadata: Hash[untyped, untyped]
-        def initialize: (id: String, kind: Symbol, ?role: Symbol?, content: untyped, ?content_format: Symbol?, ?estimated_tokens: Integer?, ?required: bool?, ?provenance: Provenance?, ?metadata: Hash[untyped, untyped]) -> void
-        def required?: () -> bool
-      end
-
-      class ToolItem
-        attr_reader id: String
-        attr_reader definition: Hash[untyped, untyped]
-        attr_reader estimated_tokens: Integer
-        attr_reader required: bool
-        attr_reader provenance: Provenance
-        attr_reader metadata: Hash[untyped, untyped]
-        def initialize: (id: String, definition: Hash[untyped, untyped], ?estimated_tokens: Integer?, ?required: bool?, ?provenance: Provenance?, ?metadata: Hash[untyped, untyped]) -> void
-        def required?: () -> bool
-      end
-
-      class ConversationItem
-        attr_reader id: String
-        attr_reader kind: Symbol
-        attr_reader role: Symbol?
-        attr_reader content: untyped
-        attr_reader content_format: Symbol
-        attr_reader sequence: Integer?
-        attr_reader estimated_tokens: Integer
-        attr_reader required: bool
-        attr_reader provenance: Provenance
-        attr_reader tool_call_id: String?
-        attr_reader tool_call_ids: Array[String]
-        attr_reader delivery: Symbol
-        attr_reader metadata: Hash[untyped, untyped]
-        def initialize: (id: String, kind: Symbol, ?role: Symbol?, content: untyped, ?content_format: Symbol?, ?sequence: Integer?, ?estimated_tokens: Integer?, ?required: bool?, ?provenance: Provenance?, ?tool_call_id: String?, ?tool_call_ids: Array[String], ?delivery: Symbol, ?metadata: Hash[untyped, untyped]) -> void
-        def required?: () -> bool
-        def with_required: (bool required) -> ConversationItem
-      end
-
-      attr_reader agent_id: String
-      attr_reader execution_id: String?
-      attr_reader call_sequence: Integer
-      attr_reader call_mode: Symbol
-      attr_reader instruction: Array[InstructionItem]
-      attr_reader knowledge: Array[KnowledgeItem]
-      attr_reader tools: Array[ToolItem]
-      attr_reader conversation: Array[Array[ConversationItem]]
-      attr_reader token_budget: untyped
-      attr_reader model_config: Hash[untyped, untyped]
-      attr_reader previous_manifest: LLMInputManifest?
-      attr_reader metadata: Hash[untyped, untyped]
-      def initialize: (agent_id: String, ?execution_id: String?, call_sequence: Integer, call_mode: Symbol, ?instruction: Array[InstructionItem], ?knowledge: Array[KnowledgeItem], ?tools: Array[ToolItem], ?conversation: Array[Array[ConversationItem]], token_budget: untyped, ?model_config: Hash[untyped, untyped], previous_manifest: LLMInputManifest?, ?metadata: Hash[untyped, untyped]) -> void
-    end
-
-    class ContextPlan
-      attr_reader instruction: Array[ContextPolicyInput::InstructionItem]
-      attr_reader knowledge: Array[ContextPolicyInput::KnowledgeItem]
-      attr_reader tools: Array[ContextPolicyInput::ToolItem]
-      attr_reader conversation: Array[Array[ContextPolicyInput::ConversationItem]]
-      attr_reader metadata: Hash[untyped, untyped]
-      def initialize: (?instruction: Array[ContextPolicyInput::InstructionItem], ?knowledge: Array[ContextPolicyInput::KnowledgeItem], ?tools: Array[ContextPolicyInput::ToolItem], ?conversation: Array[Array[ContextPolicyInput::ConversationItem]], ?metadata: Hash[untyped, untyped]) -> void
-    end
-
-    class ContextPolicy
-      def call: (ContextPolicyInput input) -> ContextPlan
-
-      def instruction_item: (content: untyped, ?role: Symbol, ?kind: Symbol, ?content_format: Symbol?, ?required: bool, ?metadata: Hash[untyped, untyped]) -> ContextPolicyInput::InstructionItem
-      def knowledge_item: (content: untyped, ?role: Symbol, ?kind: Symbol, ?content_format: Symbol?, ?required: bool, ?metadata: Hash[untyped, untyped]) -> ContextPolicyInput::KnowledgeItem
-      def conversation_item: (content: untyped, role: Symbol, ?kind: Symbol, ?content_format: Symbol?, ?sequence: Integer?, ?required: bool, ?tool_call_id: String?, ?tool_call_ids: Array[String], ?delivery: Symbol, ?metadata: Hash[untyped, untyped]) -> ContextPolicyInput::ConversationItem
-      def plan: (?instruction: Array[ContextPolicyInput::InstructionItem], ?knowledge: Array[ContextPolicyInput::KnowledgeItem], ?tools: Array[ContextPolicyInput::ToolItem], ?conversation: Array[Array[ContextPolicyInput::ConversationItem]], ?metadata: Hash[untyped, untyped]) -> ContextPlan
-    end
-
     class Base
       def self.model: (?String name) -> String?
       def self.instructions: (?untyped text) { (untyped) -> untyped } -> untyped
@@ -190,23 +60,29 @@ module Phronomy
       def self.max_iterations: (?Integer value) -> Integer
       def self.cache_instructions: (?bool enabled) -> bool?
       def self.max_output_tokens: (?Integer value) -> Integer?
-      def self.context_policy: () -> ContextPolicy
-                             | (ContextPolicy policy) -> ContextPolicy
+      def self.context_policy: () -> Phronomy::Context::ContextPolicy
+                             | (Phronomy::Context::ContextPolicy policy) -> Phronomy::Context::ContextPolicy
       def self.agent_definition: () -> Hash[Symbol, untyped]
                                | (version: Integer, ?id: String?) -> Hash[Symbol, untyped]
-      def self.before_llm_input: (?_BeforeLLMInputHook callable) ?{ (LLMInputBuildContext context) -> LLMInputPatch? } -> _BeforeLLMInputHook?
+      def self.before_llm_input: (?_BeforeLLMInputHook callable) ?{ (Phronomy::Context::LLMInputBuildContext context) -> Phronomy::Context::LLMInputPatch? } -> _BeforeLLMInputHook?
 
       # on_event is bound once to the live Agent Runtime incarnation. The block
       # is an alternative spelling of on_event; supplying both is an error.
-      def self.create: (?agent_id: String, ?context: untyped, ?knowledge: Array[untyped], ?persistence: Persistence?, ?metadata: Hash[untyped, untyped], ?on_event: ^(untyped) -> void) ?{ (untyped event) -> void } -> instance
-      def self.load: (String agent_id, persistence: Persistence, ?on_event: ^(untyped) -> void) ?{ (untyped event) -> void } -> instance
+      def self.create: (?agent_id: String, ?context: untyped, ?knowledge: Array[KnowledgeItem], ?retention: Retention?, ?persistence: Store?, ?metadata: Hash[untyped, untyped], ?on_event: ^(untyped) -> void) ?{ (untyped event) -> void } -> instance
+      def self.load: (String agent_id, persistence: Store, ?execution_wiring: execution_wiring, ?on_event: ^(untyped) -> void) ?{ (untyped event) -> void } -> instance
       def self.get: (String agent_id) -> instance?
       def self.live_for_execution: (String execution_id) -> instance
 
-      def initialize: (?agent_id: String?, ?context: untyped, ?knowledge: Array[untyped], ?persistence: Persistence?, ?metadata: Hash[untyped, untyped], ?on_event: ^(untyped) -> void) ?{ (untyped event) -> void } -> void
+      def initialize: (?agent_id: String?, ?context: untyped, ?knowledge: Array[KnowledgeItem], ?retention: Retention?, ?persistence: Store?, ?metadata: Hash[untyped, untyped], ?on_event: ^(untyped) -> void) ?{ (untyped event) -> void } -> void
 
       attr_reader agent_id: String
-      attr_reader persistence: Persistence
+      attr_reader persistence: Store
+      def knowledge_snapshot: () -> Array[KnowledgeItem]
+      def event_listener: () -> (^(Object) -> void)?
+      def start_reserved_async: (reservation: ReservedExecution, input: String, ?config: Hash[Symbol, Object]) -> TaskResult[execution_result]
+      def resume_async: (String execution_id, ?config: Hash[Symbol, Object]) -> TaskResult[execution_result]
+      def resume: (String execution_id, ?config: Hash[Symbol, Object]) -> execution_result
+      def cancel_async: (String execution_id) -> TaskResult[ExecutionObservation]
       attr_accessor before_llm_input: _BeforeLLMInputHook?
 
       # Public operation methods no longer accept per-invocation event listeners

data/sig/phronomy/common.rbs

@@ -0,0 +1,7 @@
+module Phronomy
+  type json_value = nil | bool | String | Integer | Float | Array[json_value] | Hash[String, json_value]
+  # Synchronous backends need only cooperative cancellation, not Runtime services.
+  interface _CancellationSignal
+    def raise_if_cancelled!: (?String message) -> nil
+  end
+end

data/sig/phronomy/content_store/contracts.rbs

@@ -0,0 +1,13 @@
+module Phronomy
+  interface _ContentRepository
+    def put: (String bytes, canonicalization_version: untyped) -> String
+    def fetch: (String content_id) -> String
+    def exist?: (String content_id) -> bool
+    def put_text: (String text) -> String
+    def put_json: (untyped value) -> String
+    def fetch_text: (String content_id) -> String
+    def fetch_json: (String content_id) -> untyped
+    def fetch_many: (Array[String] content_ids) -> Hash[String, String]
+  end
+
+end

data/sig/phronomy/context.rbs

@@ -0,0 +1,152 @@
+module Phronomy
+  module Context
+    class LLMInputPatch
+      attr_reader model_config_patch: Hash[untyped, untyped]?
+      attr_reader segment_candidates: Array[untyped]?
+
+      def initialize: (?model_config_patch: Hash[untyped, untyped]?, ?segment_candidates: Array[untyped]?) -> void
+      def self.empty: () -> LLMInputPatch
+    end
+
+    class LLMInputBuildContext
+      attr_reader agent_id: String
+      attr_reader agent_definition_id: String
+      attr_reader agent_definition_version: Integer
+      attr_reader config: Hash[untyped, untyped]
+      attr_reader call_sequence: Integer
+
+      def initialize: (agent_id: String, agent_definition_id: String, agent_definition_version: Integer, ?config: Hash[untyped, untyped], call_sequence: Integer) -> void
+    end
+
+    class LLMInputManifest
+      VERSION: String
+      CALL_MODES: Array[Symbol]
+      SEGMENT_DELIVERIES: Array[String]
+
+      def self.from_h: (Hash[String, untyped] hash) -> LLMInputManifest
+      def version: () -> String
+      def to_h: () -> Hash[String, untyped]
+    end
+
+    class ContextPolicyInput
+      class Provenance
+        attr_reader origin: Symbol
+        attr_reader content_ref: String?
+        attr_reader record_id: String?
+        attr_reader agent_id: String?
+        attr_reader execution_id: String?
+        attr_reader llm_call_id: String?
+        def initialize: (origin: Symbol, ?content_ref: String?, ?record_id: String?, ?agent_id: String?, ?execution_id: String?, ?llm_call_id: String?) -> void
+      end
+
+      class InstructionItem
+        attr_reader id: String
+        attr_reader kind: Symbol
+        attr_reader role: Symbol?
+        attr_reader content: untyped
+        attr_reader content_format: Symbol
+        attr_reader estimated_tokens: Integer
+        attr_reader required: bool
+        attr_reader provenance: Provenance
+        attr_reader metadata: Hash[untyped, untyped]
+        def initialize: (id: String, kind: Symbol, ?role: Symbol?, content: untyped, ?content_format: Symbol?, ?estimated_tokens: Integer?, ?required: bool?, ?provenance: Provenance?, ?metadata: Hash[untyped, untyped]) -> void
+        def required?: () -> bool
+      end
+
+      class KnowledgeItem
+        attr_reader id: String
+        attr_reader kind: Symbol
+        attr_reader role: Symbol?
+        attr_reader content: untyped
+        attr_reader content_format: Symbol
+        attr_reader estimated_tokens: Integer
+        attr_reader required: bool
+        attr_reader provenance: Provenance
+        attr_reader metadata: Hash[untyped, untyped]
+        def initialize: (id: String, kind: Symbol, ?role: Symbol?, content: untyped, ?content_format: Symbol?, ?estimated_tokens: Integer?, ?required: bool?, ?provenance: Provenance?, ?metadata: Hash[untyped, untyped]) -> void
+        def required?: () -> bool
+      end
+
+      class ToolItem
+        attr_reader id: String
+        attr_reader definition: Hash[untyped, untyped]
+        attr_reader estimated_tokens: Integer
+        attr_reader required: bool
+        attr_reader provenance: Provenance
+        attr_reader metadata: Hash[untyped, untyped]
+        def initialize: (id: String, definition: Hash[untyped, untyped], ?estimated_tokens: Integer?, ?required: bool?, ?provenance: Provenance?, ?metadata: Hash[untyped, untyped]) -> void
+        def required?: () -> bool
+      end
+
+      class ConversationItem
+        attr_reader id: String
+        attr_reader kind: Symbol
+        attr_reader role: Symbol?
+        attr_reader content: untyped
+        attr_reader content_format: Symbol
+        attr_reader sequence: Integer?
+        attr_reader estimated_tokens: Integer
+        attr_reader required: bool
+        attr_reader provenance: Provenance
+        attr_reader tool_call_id: String?
+        attr_reader tool_call_ids: Array[String]
+        attr_reader delivery: Symbol
+        attr_reader metadata: Hash[untyped, untyped]
+        def initialize: (id: String, kind: Symbol, ?role: Symbol?, content: untyped, ?content_format: Symbol?, ?sequence: Integer?, ?estimated_tokens: Integer?, ?required: bool?, ?provenance: Provenance?, ?tool_call_id: String?, ?tool_call_ids: Array[String], ?delivery: Symbol, ?metadata: Hash[untyped, untyped]) -> void
+        def required?: () -> bool
+        def with_required: (bool required) -> ConversationItem
+      end
+
+      attr_reader agent_id: String
+      attr_reader execution_id: String?
+      attr_reader call_sequence: Integer
+      attr_reader call_mode: Symbol
+      attr_reader instruction: Array[InstructionItem]
+      attr_reader knowledge: Array[KnowledgeItem]
+      attr_reader tools: Array[ToolItem]
+      attr_reader conversation: Array[Array[ConversationItem]]
+      attr_reader token_budget: untyped
+      attr_reader model_config: Hash[untyped, untyped]
+      attr_reader previous_manifest: LLMInputManifest?
+      attr_reader metadata: Hash[untyped, untyped]
+      def initialize: (agent_id: String, ?execution_id: String?, call_sequence: Integer, call_mode: Symbol, ?instruction: Array[InstructionItem], ?knowledge: Array[KnowledgeItem], ?tools: Array[ToolItem], ?conversation: Array[Array[ConversationItem]], token_budget: untyped, ?model_config: Hash[untyped, untyped], previous_manifest: LLMInputManifest?, ?metadata: Hash[untyped, untyped]) -> void
+    end
+
+    class ContextPlan
+      attr_reader instruction: Array[ContextPolicyInput::InstructionItem]
+      attr_reader knowledge: Array[ContextPolicyInput::KnowledgeItem]
+      attr_reader tools: Array[ContextPolicyInput::ToolItem]
+      attr_reader conversation: Array[Array[ContextPolicyInput::ConversationItem]]
+      attr_reader metadata: Hash[untyped, untyped]
+      def initialize: (?instruction: Array[ContextPolicyInput::InstructionItem], ?knowledge: Array[ContextPolicyInput::KnowledgeItem], ?tools: Array[ContextPolicyInput::ToolItem], ?conversation: Array[Array[ContextPolicyInput::ConversationItem]], ?metadata: Hash[untyped, untyped]) -> void
+    end
+
+    class ContextPolicy
+      def call: (ContextPolicyInput input) -> ContextPlan
+
+      def instruction_item: (content: untyped, ?role: Symbol, ?kind: Symbol, ?content_format: Symbol?, ?required: bool, ?metadata: Hash[untyped, untyped]) -> ContextPolicyInput::InstructionItem
+      def knowledge_item: (content: untyped, ?role: Symbol, ?kind: Symbol, ?content_format: Symbol?, ?required: bool, ?metadata: Hash[untyped, untyped]) -> ContextPolicyInput::KnowledgeItem
+      def conversation_item: (content: untyped, role: Symbol, ?kind: Symbol, ?content_format: Symbol?, ?sequence: Integer?, ?required: bool, ?tool_call_id: String?, ?tool_call_ids: Array[String], ?delivery: Symbol, ?metadata: Hash[untyped, untyped]) -> ContextPolicyInput::ConversationItem
+      def plan: (?instruction: Array[ContextPolicyInput::InstructionItem], ?knowledge: Array[ContextPolicyInput::KnowledgeItem], ?tools: Array[ContextPolicyInput::ToolItem], ?conversation: Array[Array[ContextPolicyInput::ConversationItem]], ?metadata: Hash[untyped, untyped]) -> ContextPlan
+    end
+
+    class BudgetExceededError < Phronomy::Error
+    end
+    class ManifestError < Phronomy::Error
+    end
+    class Assembly
+      @tracer: Phronomy::Tracing::Base
+      def initialize: (?tracer: Phronomy::Tracing::Base) -> void
+      class Prepared
+        attr_reader input: ContextPolicyInput
+        attr_reader plan: ContextPlan
+        attr_reader adapter_identity: Hash[String, String?]
+      end
+      def prepare: (input: ContextPolicyInput, policy: ContextPolicy, adapter_identity: Hash[String, String?]) -> Prepared
+      def store: (Prepared prepared, contents: Phronomy::_ContentRepository) -> [LLMInputManifest, String]
+    end
+    class DefaultPolicy < ContextPolicy
+      def self.instance: () -> DefaultPolicy
+    end
+  end
+end

data/sig/phronomy/embeddings/async/async_client.rbs

@@ -0,0 +1,9 @@
+module Phronomy
+  module Embeddings
+    class AsyncClient
+      def initialize: (adapter: Base, ?pool: untyped) -> void
+      def embed_async: (String text, ?Concurrency::CancellationToken? cancellation_token, ?timeout: Numeric?) -> TaskResult[Array[Float]]
+    end
+  end
+
+end

data/sig/phronomy/embeddings/base.rbs

@@ -0,0 +1,17 @@
+module Phronomy
+  module Embeddings
+    class InvalidResultError < Phronomy::Error
+    end
+
+    class TransportError < Phronomy::Error
+    end
+
+    class Base
+      def embed: (String text, ?_CancellationSignal? cancellation_token) -> Array[Float]
+
+      # Protected extension SPI at runtime; RBS has no protected visibility.
+      private
+      def perform_embed: (String text, ?_CancellationSignal? cancellation_token) -> Array[Numeric]
+    end
+  end
+end

data/sig/phronomy/engine/concurrency/timer_bindings.rbs

@@ -0,0 +1,22 @@
+module Phronomy
+  interface _TimerQueue
+    def schedule: (seconds: Numeric) { () -> void } -> self
+    def cancel: (^() -> void callback) -> bool
+  end
+
+  module Concurrency
+    class OffloadPool
+      @timer_queue_provider: (^() -> _TimerQueue)?
+      def initialize: (?pool_size: Integer, ?queue_size: Integer, ?name: (String | Symbol)?, ?logger: untyped, ?timer_queue_provider: (^() -> _TimerQueue)?) -> void
+      def begin_shutdown: () -> self
+      def terminated?: () -> bool
+      def shutdown: (?drain_timeout: Numeric, ?deadline: Numeric?) -> self
+    end
+
+    class PoolRegistry
+      @timer_queue_provider: (^() -> _TimerQueue)?
+      def initialize: (?timer_queue_provider: (^() -> _TimerQueue)?) -> void
+      def shutdown: (?deadline: Numeric) -> bool
+    end
+  end
+end

data/sig/phronomy/engine/control_bindings.rbs

@@ -0,0 +1,11 @@
+module Phronomy
+  class FSMSession
+    @terminal_policy: _TerminalPolicy?
+    @event_sink: _FSMEventSink
+  end
+
+  class EventLoop
+    @execution_receivers: Hash[untyped, _ExecutionReceiver]
+    @session_receivers: Hash[String, _ExecutionReceiver]
+  end
+end

data/sig/phronomy/engine/control_protocols.rbs

@@ -0,0 +1,23 @@
+module Phronomy
+  interface _FSMEventSink
+    def post: (Symbol type, ?untyped payload) -> untyped
+  end
+
+  interface _TerminalPolicy
+    def start: (terminal_type: Symbol, context: untyped, event_sink: _FSMEventSink) -> untyped
+    def handles?: (Event event) -> bool
+    def decision_for: (Event event) -> TerminalDecision
+  end
+
+  class Event
+    attr_reader type: Symbol
+    attr_reader payload: untyped
+  end
+
+  class TerminalDecision < Data
+    attr_reader action: (:complete | :fail | :retire)
+    attr_reader error: Exception?
+    def self.new: (action: (:complete | :fail | :retire), error: Exception?) -> instance
+  end
+
+end

data/sig/phronomy/engine/execution_binding.rbs

@@ -0,0 +1,6 @@
+module Phronomy
+  module ExecutionBinding
+    def self.submit: [V] (?pool: _ExecutionPool?, ?runtime: _ExecutionRuntime?, ?pool_name: Symbol?, ?size: Integer, ?queue_size: Integer, ?timeout: Numeric?, ?cancellation_token: Concurrency::CancellationToken?, ?on_full: Symbol) { () -> V } -> TaskResult[V]
+    def self.after: (Numeric seconds) { () -> void } -> ^() -> untyped
+  end
+end

data/sig/phronomy/engine/execution_receiver.rbs

@@ -0,0 +1,15 @@
+module Phronomy
+  class EventLoop
+    def __execution_receiver: (key: untyped) -> ExecutionReceiver?
+    def __register_execution_receiver: (key: untyped, receiver: ExecutionReceiver) -> ExecutionReceiver
+    def __synchronize_execution_state: [V] () { () -> V } -> V
+    def __admit_execution: [V] (ExecutionReceiver receiver) { () -> V } -> V
+    def __post_execution: (ExecutionReceiver receiver, untyped message, ?admission: bool, ?completion: TaskResult[untyped]?) -> bool
+    def __route_execution_event: (ExecutionReceiver receiver) { () -> untyped } -> bool
+    def __receiver_cleanup_complete?: () -> bool
+  end
+
+  class Runtime
+    def __event_loop_if_initialized: () -> EventLoop?
+  end
+end

data/sig/phronomy/engine/observability.rbs

@@ -0,0 +1,13 @@
+# Internal lookup operations. None of these methods initializes a resource.
+module Phronomy
+  class Runtime
+    def self.__default_if_initialized: () -> Runtime?
+    def __offload_if_initialized: () -> Concurrency::OffloadPool?
+  end
+
+  module Concurrency
+    class PoolRegistry
+      def default_pool_if_initialized: () -> OffloadPool?
+    end
+  end
+end

data/sig/phronomy/execution/async_operation.rbs

@@ -0,0 +1,7 @@
+module Phronomy
+  module AsyncOperation
+    def self.map: [A, B] (_CompletionHandle[A] source, name: String, ?on_error: (^(Exception) -> B)?) { (A) -> B } -> TaskResult[B]
+    def self.call: [A, B] (name: String, ?on_error: (^(Exception) -> B)?, ?transform: ^(A) -> B) { () -> _CompletionHandle[A] } -> TaskResult[B]
+    def self.capture: [V] (name: String, ?on_error: (^(Exception) -> V)?) { () -> V } -> TaskResult[V]
+  end
+end

data/sig/phronomy/execution/blocking.rbs

@@ -0,0 +1,5 @@
+module Phronomy
+  module Blocking
+    def self.call_async: [V] (?timeout: Numeric?, ?cancellation_token: Concurrency::CancellationToken?, ?invocation_context: InvocationContext?) { () -> V } -> TaskResult[V]
+  end
+end

data/sig/phronomy/execution/concurrency/cancellation_token.rbs

@@ -0,0 +1,13 @@
+module Phronomy
+  module Concurrency
+    class CancellationToken
+      def self.timeout_after: (Numeric seconds) -> CancellationToken
+      def initialize: (?monotonic_deadline: Float?) -> void
+      def remaining_monotonic_seconds: () -> Float?
+      def on_cancel: () { () -> void } -> self
+      def cancel!: () -> self
+      def cancelled?: () -> bool
+      def raise_if_cancelled!: (?String message) -> nil
+    end
+  end
+end

data/sig/phronomy/execution/concurrency/deadline.rbs

@@ -0,0 +1,10 @@
+module Phronomy
+  module Concurrency
+    class Deadline
+      def self.in: (Numeric seconds) -> instance
+      def initialize: (Numeric monotonic_at) -> void
+      def expired?: () -> bool
+      def remaining_seconds: () -> Float
+    end
+  end
+end

data/sig/phronomy/execution/concurrency/result_composition.rbs

@@ -0,0 +1,7 @@
+module Phronomy
+  module Concurrency
+    class ResultComposition
+      @scope: _ExecutionScope?
+    end
+  end
+end

data/sig/phronomy/execution/control_protocols.rbs

@@ -0,0 +1,18 @@
+module Phronomy
+  # Only the operations used across the execution boundary; no concrete runtime.
+  interface _CompletionHandle[A]
+    def on_complete: () { (A?, Exception?) -> void } -> untyped
+  end
+
+  interface _ExecutionScope
+    def __while_open: [V] () { () -> V } -> V?
+    def __open?: () -> bool
+    def __cancellation_token: () -> Concurrency::CancellationToken
+    def __cancellation_error: () -> Exception
+  end
+
+  module WaitPolicy
+    def self.blocking_forbidden?: () -> bool
+    def self.without_blocking: [V] () { () -> V } -> V
+  end
+end