igniter 0.4.5 → 0.5.1

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/extensions/introspection/graph_formatter.rb

@@ -36,8 +36,26 @@ module Igniter
             if node.kind == :composition
               line += " contract=#{node.contract_class.name || 'AnonymousContract'}"
             end
+            if node.kind == :agent
+              interaction = node.interaction_contract
+              line += " via=#{node.agent_name.inspect}"
+              line += " message=#{node.message_name.inspect}"
+              line += " timeout=#{node.timeout}"
+              line += " mode=#{interaction.mode}"
+              line += " routing=#{interaction.routing_mode}"
+              line += " node=#{interaction.node_url.inspect}" if interaction.routing_mode == :static
+              line += " capability=#{interaction.capability.inspect}" if interaction.capability
+              line += " query=#{interaction.capability_query.inspect}" if interaction.capability_query
+              line += " pinned_to=#{interaction.pinned_to.inspect}" if interaction.pinned_to
+              line += " reply=#{interaction.reply_mode}"
+              line += " finalizer=#{interaction.finalizer.inspect}" if interaction.finalizer
+              line += " tool_loop_policy=#{interaction.tool_loop_policy.inspect}" if interaction.tool_loop_policy
+              line += " session_policy=#{interaction.session_policy.inspect}" if interaction.session_policy
+            end
             if node.kind == :branch
-              cases = node.cases.map { |entry| "#{entry[:match].inspect}:#{entry[:contract].name || 'AnonymousContract'}" }
+              cases = node.cases.map do |entry|
+                "#{format_branch_case(entry)}:#{entry[:contract].name || 'AnonymousContract'}"
+              end
               line += " selector=#{node.selector_dependency}"
               line += " depends_on=#{node.context_dependencies.join(',')}" if node.context_dependencies.any?
               line += " cases=#{cases.join('|')}"
@@ -97,6 +115,19 @@ module Igniter
 
           "#{node.kind}: #{node.path}\\n#{node.callable_name}"
         end
+
+        def format_branch_case(entry)
+          case entry[:matcher]
+          when :eq
+            entry[:value].inspect
+          when :in
+            "in=#{entry[:value].inspect}"
+          when :matches
+            "matches=#{entry[:value].inspect}"
+          else
+            "#{entry[:matcher]}=#{entry[:value].inspect}"
+          end
+        end
       end
     end
   end

data/packages/igniter-core/lib/igniter/core/extensions/introspection/plan_formatter.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Introspection
+      class PlanFormatter
+        def self.to_text(execution, output_names = nil)
+          new(execution, output_names).to_text
+        end
+
+        def initialize(execution, output_names = nil)
+          @execution = execution
+          @plan = execution.plan(output_names)
+        end
+
+        def to_text
+          lines = []
+          lines << "Plan #{@execution.compiled_graph.name}"
+          lines << "Targets: #{format_list(@plan[:targets])}"
+          lines << "Ready: #{format_list(@plan[:ready])}"
+          lines << "Blocked: #{format_list(@plan[:blocked])}"
+          if @plan[:agent_profiles] && @plan[:agent_profiles][:total].positive?
+            lines << "Agents: total=#{@plan[:agent_profiles][:total]}, interactive=#{@plan[:agent_profiles][:interactive]}, manual=#{@plan[:agent_profiles][:manual]}, single_turn=#{@plan[:agent_profiles][:single_turn]}, streaming=#{@plan[:agent_profiles][:streaming]}, deferred=#{@plan[:agent_profiles][:deferred]}"
+          end
+          if @plan[:orchestration] && @plan[:orchestration][:total].positive?
+            lines << "Orchestration: attention_required=#{@plan[:orchestration][:attention_required]}, resumable=#{@plan[:orchestration][:resumable]}, interactive_sessions=#{@plan[:orchestration][:interactive_sessions]}, manual_sessions=#{@plan[:orchestration][:manual_sessions]}, single_turn_sessions=#{@plan[:orchestration][:single_turn_sessions]}, deferred_calls=#{@plan[:orchestration][:deferred_calls]}, single_reply_calls=#{@plan[:orchestration][:single_reply_calls]}, delivery_only=#{@plan[:orchestration][:delivery_only]}"
+            if @plan[:orchestration][:attention_nodes].any?
+              lines << "Attention Nodes: #{format_list(@plan[:orchestration][:attention_nodes])}"
+            end
+            if @plan[:orchestration][:actions].any?
+              lines << "Orchestration Actions: #{@plan[:orchestration][:actions].map { |action| "#{action[:node]}(#{action[:action]})" }.join(', ')}"
+            end
+          end
+          lines << "Nodes:"
+
+          @plan[:nodes].each_value do |entry|
+            lines << format_node(entry)
+          end
+
+          lines.join("\n")
+        end
+
+        private
+
+        def format_node(entry)
+          line = "- #{entry[:kind]} #{entry[:path]} status=#{entry[:status]}"
+          line += " ready=true" if entry[:ready]
+          line += " blocked=true" if entry[:blocked]
+          line += " waiting_on=#{format_list(entry[:waiting_on])}" if entry[:waiting_on].any?
+          if entry[:kind] == :agent
+            line += " via=#{entry[:via].inspect}"
+            line += " message=#{entry[:message].inspect}"
+            line += " mode=#{entry[:mode]}"
+            line += " reply=#{entry[:reply_mode]}"
+            line += " session_policy=#{entry[:session_policy]}" if entry[:session_policy]
+            line += " tool_loop_policy=#{entry[:tool_loop_policy]}" if entry[:tool_loop_policy]
+            line += " finalizer=#{entry[:finalizer].inspect}" if entry[:finalizer]
+            if entry[:orchestration]
+              line += " orchestration=#{entry[:orchestration][:interaction]}"
+              line += " guidance=#{entry[:orchestration][:guidance].inspect}"
+              line += " attention_required=true" if entry[:orchestration][:attention_required]
+              line += " resumable=true" if entry[:orchestration][:resumable]
+              line += " allows_continuation=true" if entry[:orchestration][:allows_continuation]
+              line += " requires_explicit_completion=true" if entry[:orchestration][:requires_explicit_completion]
+              line += " auto_finalization=#{entry[:orchestration][:auto_finalization]}"
+            end
+          end
+
+          dependency_summary = entry[:dependencies].map do |dependency|
+            "#{dependency[:name]}(#{dependency[:status]})"
+          end
+          line += " deps=#{dependency_summary.join(',')}" if dependency_summary.any?
+          line
+        end
+
+        def format_list(values)
+          array = Array(values)
+          return "none" if array.empty?
+
+          array.join(",")
+        end
+      end
+    end
+  end
+end

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/extensions/introspection/runtime_formatter.rb

@@ -73,6 +73,7 @@ module Igniter
             status: state.status,
             version: state.version,
             invalidated_by: invalidation_details(state),
+            details: state.details,
             value: serialize_value(state.value),
             error: state.error&.message
           }
@@ -91,6 +92,31 @@ module Igniter
 
         def serialize_value(value)
           case value
+          when Igniter::Runtime::StreamResult
+            {
+              type: :stream,
+              token: value.token,
+              payload: value.payload,
+              source_node: value.source_node,
+              waiting_on: value.waiting_on,
+              phase: value.phase,
+              events: value.events,
+              event_count: value.events.size,
+              status_count: value.status_events.size,
+              tool_call_count: value.tool_calls.size,
+              tool_result_count: value.tool_results.size,
+              tool_interaction_count: value.tool_interactions.size,
+              pending_tool_interaction_count: value.pending_tool_interactions.size,
+              completed_tool_interaction_count: value.completed_tool_interactions.size,
+              orphan_tool_interaction_count: value.orphan_tool_interactions.size,
+              tool_loop_status: value.tool_loop_status,
+              tool_loop_complete: value.tool_loop_complete?,
+              tool_loop_summary: value.tool_loop_summary,
+              tool_runtime: value.tool_runtime,
+              artifact_count: value.artifacts.size,
+              chunks: value.chunks,
+              chunk_count: value.chunks.size
+            }
           when Igniter::Runtime::DeferredResult
             {
               type: :deferred,

data/packages/igniter-core/lib/igniter/core/extensions/invariants.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "../contract"
+require_relative "../errors"
+require_relative "../invariant"
+
+module Igniter
+  module Extensions
+    # Patches Igniter::Contract with:
+    #   - Class method: invariant(name) { |output:, **| condition }
+    #   - Instance method: check_invariants -> Array<InvariantViolation>
+    #   - Automatic post-execution check in resolve_all (raises InvariantError)
+    module Invariants
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.prepend(InstanceMethods)
+      end
+
+      module ClassMethods
+        def invariant(name, &block)
+          @_invariants ||= {}
+          @_invariants[name.to_sym] = Igniter::Invariant.new(name, &block)
+        end
+
+        def invariants
+          @_invariants || {}
+        end
+      end
+
+      module InstanceMethods
+        def resolve_all(...)
+          result = super
+          validate_invariants! unless Thread.current[:igniter_skip_invariants]
+          result
+        end
+
+        def check_invariants
+          return [] if self.class.invariants.empty?
+
+          resolved = collect_output_values
+          self.class.invariants.values.filter_map { |inv| inv.check(resolved) }
+        end
+
+        private
+
+        def validate_invariants!
+          violations = check_invariants
+          return if violations.empty?
+
+          names = violations.map { |v| ":#{v.name}" }.join(", ")
+          raise Igniter::InvariantError.new(
+            "#{violations.size} invariant(s) violated: #{names}",
+            violations: violations,
+            context: { contract: self.class.name }
+          )
+        end
+
+        def collect_output_values
+          cache = execution.cache
+          execution.compiled_graph.outputs.each_with_object({}) do |output_node, acc|
+            state = cache.fetch(output_node.source_root)
+            acc[output_node.name] = state.value if state&.succeeded?
+          end
+        end
+      end
+    end
+  end
+end
+
+Igniter::Contract.include(Igniter::Extensions::Invariants)

data/packages/igniter-core/lib/igniter/core/fingerprint.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Igniter
+  # Mixin that enables stable cross-execution cache keys for objects used as
+  # compute node dependencies (e.g. ActiveRecord models).
+  #
+  # Include this module in any class whose instances are passed as node deps:
+  #
+  #   class Trade < ApplicationRecord
+  #     include Igniter::Fingerprint
+  #   end
+  #
+  # The Rails Railtie includes this automatically in ApplicationRecord when
+  # the igniter-rails integration is loaded.
+  #
+  # == Custom fingerprints
+  #
+  # Override #igniter_fingerprint for non-AR objects or custom invalidation logic:
+  #
+  #   class PricingConfig
+  #     include Igniter::Fingerprint
+  #
+  #     def igniter_fingerprint
+  #       "PricingConfig:#{version}:#{market}"
+  #     end
+  #   end
+  module Fingerprint
+    # Returns a stable string that uniquely identifies this object's state.
+    # Changing the returned value invalidates any NodeCache entry that depends on it.
+    #
+    # Default: "{ClassName}:{id}:{updated_at_unix}" — works for any AR record.
+    # Returns "{ClassName}:{id}" for objects without updated_at.
+    def igniter_fingerprint
+      if respond_to?(:updated_at) && updated_at
+        "#{self.class.name}:#{id}:#{updated_at.to_i}"
+      elsif respond_to?(:id)
+        "#{self.class.name}:#{id}"
+      else
+        "#{self.class.name}:#{object_id}"
+      end
+    end
+  end
+end

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/incremental.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-require "igniter"
-require "igniter/incremental/result"
-require "igniter/incremental/tracker"
-require "igniter/incremental/formatter"
+require_relative "errors"
+require_relative "incremental/result"
+require_relative "incremental/tracker"
+require_relative "incremental/formatter"
 
 module Igniter
   # Incremental computation for Igniter contracts.

data/packages/igniter-core/lib/igniter/core/memory/agent_memory.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Memory
+    # Facade that pre-fills +agent_id+ on all Store operations.
+    #
+    # Callers interact with AgentMemory instead of the raw Store so they never
+    # have to pass +agent_id:+ explicitly. An optional +session_id+ groups
+    # episodes within a single interaction session.
+    #
+    # @example
+    #   store  = Igniter::Memory::Stores::InMemory.new
+    #   memory = Igniter::Memory::AgentMemory.new(store: store, agent_id: "MyAgent:1")
+    #
+    #   memory.record(type: :tool_call, content: "searched web for Ruby docs")
+    #   memory.recall(query: "Ruby")      # => [Episode, ...]
+    #   memory.remember(:user_tz, "UTC")
+    #   memory.facts                      # => { "user_tz" => Fact }
+    class AgentMemory
+      # @param store      [Store]         backing store implementation
+      # @param agent_id   [String]        identifier for this agent
+      # @param session_id [String, nil]   optional session grouping key
+      def initialize(store:, agent_id:, session_id: nil)
+        @store      = store
+        @agent_id   = agent_id
+        @session_id = session_id
+      end
+
+      # Record a new episode.
+      #
+      # @param type       [String, Symbol] category tag
+      # @param content    [String]         textual description of the event
+      # @param outcome    [String, nil]    result label, e.g. "success"/"failure"
+      # @param importance [Float]          relevance weight 0.0–1.0
+      # @return [Episode]
+      def record(type:, content:, outcome: nil, importance: 0.5)
+        @store.record(
+          agent_id: @agent_id,
+          type: type,
+          content: content,
+          session_id: @session_id,
+          outcome: outcome,
+          importance: importance
+        )
+      end
+
+      # Keyword-search episodes for this agent.
+      #
+      # @param query [String, nil] search term; nil returns most recent
+      # @param limit [Integer]     maximum results (default 10)
+      # @param type  [String, Symbol, nil] optional type filter
+      # @return [Array<Episode>]
+      def recall(query: nil, limit: 10, type: nil)
+        @store.retrieve(agent_id: @agent_id, query: query, limit: limit, type: type)
+      end
+
+      # Store or update a named fact.
+      #
+      # @param key        [String, Symbol]  fact name
+      # @param value      [Object]          fact value
+      # @param confidence [Float]           confidence score 0.0–1.0
+      # @return [Fact]
+      def remember(key, value, confidence: 1.0)
+        @store.store_fact(agent_id: @agent_id, key: key, value: value, confidence: confidence)
+      end
+
+      # Returns all stored facts for this agent.
+      #
+      # @return [Hash{String => Fact}]
+      def facts
+        @store.facts(agent_id: @agent_id)
+      end
+
+      # Returns recent episodes.
+      #
+      # @param last [Integer]              maximum episodes to return
+      # @param type [String, Symbol, nil]  optional type filter
+      # @return [Array<Episode>]
+      def recent(last: 20, type: nil)
+        @store.episodes(agent_id: @agent_id, last: last, type: type)
+      end
+
+      # Run a reflection cycle and record the result.
+      #
+      # @param current_system_prompt [String, nil] current prompt to compare against
+      # @return [ReflectionRecord]
+      def reflect(current_system_prompt: nil)
+        ReflectionCycle.new(store: @store).reflect(
+          agent_id: @agent_id,
+          current_system_prompt: current_system_prompt
+        )
+      end
+
+      # Check whether the agent should run a reflection cycle.
+      #
+      # Returns true when the recent failure rate exceeds the threshold.
+      #
+      # @return [Boolean]
+      def should_reflect?
+        ReflectionCycle.new(store: @store).should_reflect?(agent_id: @agent_id)
+      end
+    end
+  end
+end

data/packages/igniter-core/lib/igniter/core/memory/episode.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Memory
+    # Immutable value object representing a single recorded event in agent history.
+    #
+    # @!attribute [r] id
+    #   @return [Integer] unique identifier within the store
+    # @!attribute [r] agent_id
+    #   @return [String] identifier of the agent that recorded this episode
+    # @!attribute [r] session_id
+    #   @return [String, nil] optional session grouping identifier
+    # @!attribute [r] ts
+    #   @return [Integer] Unix timestamp of when the episode was recorded
+    # @!attribute [r] type
+    #   @return [String, Symbol] category of the episode (e.g. :tool_call, :response)
+    # @!attribute [r] content
+    #   @return [String] textual description of what happened
+    # @!attribute [r] outcome
+    #   @return [String, nil] result descriptor, e.g. "success" or "failure"
+    # @!attribute [r] importance
+    #   @return [Float] relevance weight in [0.0, 1.0], default 0.5
+    Episode = Struct.new(
+      :id, :agent_id, :session_id, :ts,
+      :type, :content, :outcome, :importance,
+      keyword_init: true
+    )
+  end
+end

data/packages/igniter-core/lib/igniter/core/memory/fact.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Memory
+    # Immutable value object representing a persisted learned fact for an agent.
+    #
+    # Facts represent stable knowledge extracted from experience, keyed by a
+    # string name and associated with a confidence score.
+    #
+    # @!attribute [r] id
+    #   @return [Integer] unique identifier within the store
+    # @!attribute [r] agent_id
+    #   @return [String] identifier of the agent that owns this fact
+    # @!attribute [r] key
+    #   @return [String] fact name (e.g. "user_timezone", "preferred_format")
+    # @!attribute [r] value
+    #   @return [Object] the fact's value
+    # @!attribute [r] confidence
+    #   @return [Float] confidence score in [0.0, 1.0], default 1.0
+    # @!attribute [r] updated_at
+    #   @return [Integer] Unix timestamp of last upsert
+    Fact = Struct.new(
+      :id, :agent_id, :key, :value, :confidence, :updated_at,
+      keyword_init: true
+    )
+  end
+end

data/packages/igniter-core/lib/igniter/core/memory/memorable.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Memory
+    # Mixin that adds episodic memory capabilities to Igniter::Agent and
+    # Igniter::AI::Executor subclasses (or any class that includes it).
+    #
+    # Including +Memorable+ adds:
+    # * A class-level +enable_memory+ DSL method for opt-in activation
+    # * A +memory+ instance accessor returning a bound AgentMemory facade
+    # * Automatic agent_id derived from the class name and object_id
+    #
+    # Memory is NOT enabled by default — call +enable_memory+ in the class body.
+    #
+    # == Example
+    #
+    #   class MyAgent < Igniter::Agent
+    #     include Igniter::Memory::Memorable
+    #
+    #     enable_memory store: Igniter::Memory::Stores::InMemory.new
+    #
+    #     on :task do |state:, payload:, **|
+    #       memory.record(type: :task, content: payload[:description])
+    #       # ... handle task
+    #       state
+    #     end
+    #   end
+    #
+    # == Inheritance
+    #
+    # Subclasses inherit +memory_enabled?+ and +memory_store+ from their parent.
+    # Each subclass can override them independently.
+    module Memorable
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.instance_variable_set(:@memory_store, nil)
+        base.instance_variable_set(:@memory_enabled, false)
+      end
+
+      module ClassMethods
+        # Enable episodic memory for this class.
+        #
+        # @param store [Store, nil] backing store; falls back to Igniter::Memory.default_store
+        # @return [void]
+        def enable_memory(store: nil)
+          @memory_enabled = true
+          @memory_store   = store || Igniter::Memory.default_store
+        end
+
+        # Returns the configured memory store, walking up the inheritance chain
+        # if none is set on this class.
+        #
+        # @return [Store]
+        def memory_store
+          @memory_store ||
+            (superclass.respond_to?(:memory_store) ? superclass.memory_store : Igniter::Memory.default_store)
+        end
+
+        # Returns whether memory has been enabled for this class or any ancestor.
+        #
+        # @return [Boolean]
+        def memory_enabled?
+          @memory_enabled ||
+            (superclass.respond_to?(:memory_enabled?) && superclass.memory_enabled?)
+        end
+      end
+
+      # Returns the AgentMemory facade bound to this instance.
+      #
+      # Lazily initialised on first access. The agent_id incorporates the class
+      # name and object_id to keep instances isolated.
+      #
+      # @return [AgentMemory]
+      def memory
+        @memory ||= AgentMemory.new(
+          store: self.class.memory_store,
+          agent_id: memory_agent_id,
+          session_id: respond_to?(:session_id, true) ? session_id : nil
+        )
+      end
+
+      private
+
+      def memory_agent_id
+        cls_name = self.class.name || "anonymous"
+        "#{cls_name}:#{object_id}"
+      end
+    end
+  end
+end

data/packages/igniter-core/lib/igniter/core/memory/reflection_cycle.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Memory
+    # Evaluates recent episodes and produces a ReflectionRecord.
+    #
+    # ReflectionCycle can operate in two modes:
+    #
+    # * **Rule-based** (default) — analyses failure rates using simple heuristics,
+    #   requiring no LLM. Always available.
+    # * **LLM-assisted** — delegates to an LLM executor for a richer summary and
+    #   an optional system-prompt patch. Enabled by passing an +llm:+ object.
+    #
+    # @example Rule-based reflection
+    #   cycle = Igniter::Memory::ReflectionCycle.new(store: store)
+    #   rec   = cycle.reflect(agent_id: "MyAgent:1")
+    #   # => ReflectionRecord (summary describes failure breakdown)
+    #
+    # @example With failure threshold check
+    #   cycle.should_reflect?(agent_id: "MyAgent:1")
+    #   # => true when recent failures >= DEFAULT_FAILURE_THRESHOLD
+    class ReflectionCycle
+      DEFAULT_FAILURE_THRESHOLD = 5
+      DEFAULT_WINDOW            = 50
+
+      # @param store             [Store]    backing episode store
+      # @param failure_threshold [Integer]  minimum failures to trigger reflection
+      # @param window            [Integer]  how many recent episodes to inspect
+      # @param llm               [#call, nil] optional LLM executor for smart reflection
+      def initialize(store:, failure_threshold: DEFAULT_FAILURE_THRESHOLD,
+                     window: DEFAULT_WINDOW, llm: nil)
+        @store             = store
+        @failure_threshold = failure_threshold
+        @window            = window
+        @llm               = llm
+      end
+
+      # Check whether a reflection cycle should be triggered.
+      #
+      # Returns true when the number of recent "failure" outcomes meets or
+      # exceeds the configured +failure_threshold+.
+      #
+      # @param agent_id [String]
+      # @return [Boolean]
+      def should_reflect?(agent_id:)
+        recent   = @store.episodes(agent_id: agent_id, last: @window)
+        failures = recent.count { |e| e.outcome == "failure" }
+        failures >= @failure_threshold
+      end
+
+      # Run a reflection cycle and persist the result.
+      #
+      # Analyses the most recent +window+ episodes and produces a
+      # ReflectionRecord with a summary (and optional system-prompt patch when
+      # an LLM is configured).
+      #
+      # @param agent_id              [String]
+      # @param current_system_prompt [String, nil] passed to the LLM if available
+      # @return [ReflectionRecord]
+      def reflect(agent_id:, current_system_prompt: nil) # rubocop:disable Metrics/MethodLength
+        recent = @store.episodes(agent_id: agent_id, last: @window)
+        summary, patch = if @llm
+                           smart_reflect(recent, current_system_prompt)
+                         else
+                           rule_based_reflect(recent)
+                         end
+
+        @store.record_reflection(
+          agent_id: agent_id,
+          summary: summary,
+          system_patch: patch
+        )
+      end
+
+      private
+
+      def rule_based_reflect(episodes) # rubocop:disable Metrics/CyclomaticComplexity
+        failures      = episodes.select { |e| e.outcome == "failure" }
+        failure_types = failures.group_by(&:type).transform_values(&:count)
+        top           = failure_types.max_by { |_, v| v }
+
+        summary = "#{failures.size}/#{episodes.size} failures. " \
+                  "Top failure type: #{top&.first || "none"} (#{top&.last || 0}\xc3\x97)"
+        [summary, nil]
+      end
+
+      def smart_reflect(episodes, current_system_prompt)
+        result = @llm.call(
+          episodes: episodes.map { |e| { type: e.type, content: e.content, outcome: e.outcome } },
+          current_system_prompt: current_system_prompt
+        )
+        [result[:summary], result[:system_patch]]
+      end
+    end
+  end
+end

data/packages/igniter-core/lib/igniter/core/memory/reflection_record.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Memory
+    # Immutable value object representing the output of a reflection cycle.
+    #
+    # A ReflectionRecord captures the summary and optional system-prompt patch
+    # produced by a ReflectionCycle run. It can be applied to update an agent's
+    # system prompt or used as an audit trail.
+    #
+    # @!attribute [r] id
+    #   @return [Integer] unique identifier within the store
+    # @!attribute [r] agent_id
+    #   @return [String] identifier of the agent this reflection belongs to
+    # @!attribute [r] ts
+    #   @return [Integer] Unix timestamp when the reflection was recorded
+    # @!attribute [r] summary
+    #   @return [String] human-readable summary of findings
+    # @!attribute [r] system_patch
+    #   @return [String, nil] optional suggested replacement/patch for system prompt
+    # @!attribute [r] applied
+    #   @return [Boolean] whether this reflection has been applied to the agent
+    ReflectionRecord = Struct.new(
+      :id, :agent_id, :ts, :summary, :system_patch, :applied,
+      keyword_init: true
+    )
+  end
+end