smart_brain 0.1.2 → 0.2.0

data/exe/smart_brain

@@ -0,0 +1,168 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# SmartBrain CLI — drive the memory runtime from the shell or as an agent tool.
+#
+#   smart_brain status
+#   smart_brain migrate                         (postgres backend only)
+#   smart_brain commit   --data '{"session_id":..,"turn_events":{..}}'
+#   smart_brain compose  --data '{"session_id":..,"user_message":..}'
+#   smart_brain search   --data '{"session_id":..,"query":..}'
+#   smart_brain serve    [--host 0.0.0.0] [--port 9292] [--config PATH]
+#   smart_brain mcp      [--config PATH]        (stdio JSON-RPC, for Claude Code / Cursor)
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+
+require 'optparse'
+require 'json'
+require 'smart_brain'
+require 'smart_brain/server/service'
+require 'smart_brain/server/http_app'
+require 'smart_brain/server/mcp_server'
+
+module SmartBrain
+  module CLI
+    module_function
+
+    def run(argv)
+      config_path = ENV['SMARTBRAIN_CONFIG']
+      global = OptionParser.new do |opts|
+        opts.banner = 'Usage: smart_brain <command> [options]'
+        opts.on('--config PATH', 'Path to brain.yml') { |p| config_path = p }
+        opts.on('--version', 'Print version and exit') { puts SmartBrain::VERSION; exit 0 }
+        opts.on('-h', '--help', 'Show this help') { puts opts; exit 0 }
+      end
+      global.order!(argv)
+
+      command = argv.shift
+      abort(global.to_s) unless command
+
+      case command
+      when 'status'  then print_json(Server::Service.build(config_path: config_path).status)
+      when 'migrate' then print_json(ok: Server::Service.build(config_path: config_path).migrate)
+      when 'commit', 'compose', 'search', 'fact-check', 'brief', 'wake-up'
+        data_cmd(command, argv, config_path)
+      when 'knowledge' then knowledge_cmd(argv, config_path)
+      when 'kg' then kg_cmd(argv, config_path)
+      when 'serve'   then serve(argv, config_path)
+      when 'mcp'     then mcp(config_path)
+      else
+        warn "unknown command: #{command}"
+        warn global.to_s
+        exit 1
+      end
+    end
+
+    def data_cmd(command, argv, config_path)
+      options = {}
+      parser = OptionParser.new do |opts|
+        opts.on('--data JSON', 'JSON payload (or read from stdin)') { |j| options[:data] = j }
+        opts.on('-h', '--help') { puts opts; exit 0 }
+      end
+      parser.parse!(argv)
+
+      payload = read_payload(options[:data])
+      service = Server::Service.build(config_path: config_path)
+      result =
+        case command
+        when 'commit' then service.commit(**payload.slice(:domain_id, :session_id, :scope_context, :turn_events).merge(turn_events: payload[:turn_events] || {}))
+        when 'compose' then service.compose(**payload.slice(:domain_id, :session_id, :scope_context, :user_message, :agent_state).merge(agent_state: payload[:agent_state] || {}))
+        when 'search' then service.search(**payload.slice(:domain_id, :session_id, :scope_context, :query, :limit))
+        when 'fact-check' then service.fact_check(**payload.slice(:domain_id, :session_id, :scope_context, :text))
+        when 'brief' then service.brief(**payload.slice(:domain_id, :session_id, :scope_context, :query))
+        when 'wake-up' then service.wake_up(**payload.slice(:domain_id, :session_id, :scope_context))
+        end
+      print_json(result)
+    end
+
+    def knowledge_cmd(argv, config_path)
+      options = {}
+      OptionParser.new do |opts|
+        opts.banner = 'usage: smart_brain knowledge <distill|gate|promote|demote|retract|promote-to-scope|lineage|events> --data JSON'
+        opts.on('--data JSON', 'JSON payload (or read from stdin)') { |j| options[:data] = j }
+        opts.on('-h', '--help') { puts opts; exit 0 }
+      end.parse!(argv)
+
+      action = argv.shift
+      abort 'usage: smart_brain knowledge <distill|gate|promote|demote|retract|promote-to-scope|lineage|events> --data JSON' unless action
+
+      payload = read_payload(options[:data])
+      service = Server::Service.build(config_path: config_path)
+      result =
+        case action
+        when 'distill' then service.distill(**payload.slice(:domain_id, :session_id, :scope_context, :statement, :content, :tier, :supporting_refs, :domain, :field, :reviewer, :key))
+        when 'gate' then service.gate(**payload.slice(:memory_item_id, :domain_id, :session_id, :scope_context))
+        when 'promote' then service.promote(**payload.slice(:memory_item_id, :domain_id, :session_id, :scope_context, :verification_refs, :reason, :reviewer, :force))
+        when 'demote' then service.demote(**payload.slice(:memory_item_id, :domain_id, :session_id, :scope_context, :evidence_refs, :reason, :reason_type, :reviewer))
+        when 'retract' then service.retract(**payload.slice(:memory_item_id, :domain_id, :session_id, :scope_context, :evidence_refs, :reason, :reviewer))
+        when 'promote-to-scope' then service.promote_to_scope(**payload.slice(:memory_item_id, :target_scope, :domain_id, :session_id, :scope_context, :verification_refs, :reason, :reviewer))
+        when 'lineage' then service.promotion_lineage(**payload.slice(:memory_item_id, :domain_id, :session_id, :scope_context))
+        when 'events' then service.knowledge_events(**payload.slice(:memory_item_id, :domain_id, :session_id, :scope_context))
+        else abort "unknown knowledge action: #{action}"
+        end
+      print_json(result)
+    rescue SmartBrain::Governance::LifecycleGateError, ArgumentError => e
+      warn "#{e.class}: #{e.message}"
+      exit 1
+    end
+
+    def kg_cmd(argv, config_path)
+      options = {}
+      OptionParser.new do |opts|
+        opts.banner = 'usage: smart_brain kg <add|query|timeline|invalidate|stats> --data JSON'
+        opts.on('--data JSON', 'JSON payload (or read from stdin)') { |j| options[:data] = j }
+        opts.on('-h', '--help') { puts opts; exit 0 }
+      end.parse!(argv)
+      action = argv.shift
+      abort 'usage: smart_brain kg <add|query|timeline|invalidate|stats> --data JSON' unless action
+
+      payload = read_payload(options[:data])
+      service = Server::Service.build(config_path: config_path)
+      result =
+        case action
+        when 'add' then service.kg_add(**payload.slice(:domain_id, :session_id, :scope_context, :scope_ref, :subject, :predicate, :object, :confidence, :source_turn_id))
+        when 'query' then service.kg_query(**payload.slice(:domain_id, :session_id, :scope_context, :subject, :predicate, :object, :include_invalid))
+        when 'timeline' then service.kg_timeline(**payload.slice(:domain_id, :session_id, :scope_context, :subject))
+        when 'invalidate' then service.kg_invalidate(**payload.slice(:edge_id, :reason, :domain_id, :session_id, :scope_context))
+        when 'stats' then service.kg_stats(**payload.slice(:domain_id, :session_id, :scope_context))
+        else abort "unknown kg action: #{action}"
+        end
+      print_json(result)
+    end
+
+    def serve(argv, config_path)
+      options = { host: '127.0.0.1', port: 9292 }
+      OptionParser.new do |opts|
+        opts.on('--host HOST') { |h| options[:host] = h }
+        opts.on('--port PORT', Integer) { |p| options[:port] = p }
+        opts.on('-h', '--help') { puts opts; exit 0 }
+      end.parse!(argv)
+
+      service = Server::Service.build(config_path: config_path)
+      Server::HttpApp.service = service
+      warn "[smart_brain] HTTP on http://#{options[:host]}:#{options[:port]} (backend: #{service.backend})"
+      Server::HttpApp.run!(host: options[:host], port: options[:port], server: :puma) do |server|
+        # Puma-specific tuning can go here.
+      end
+    end
+
+    def mcp(config_path)
+      service = Server::Service.build(config_path: config_path)
+      Server::McpServer.new(service: service).run
+    end
+
+    def read_payload(raw)
+      return {} if raw.nil? && $stdin.tty?
+      raw ||= $stdin.read
+      raw.to_s.strip.empty? ? {} : JSON.parse(raw, symbolize_names: true)
+    rescue JSON::ParserError => e
+      abort "invalid JSON payload: #{e.message}"
+    end
+
+    def print_json(payload)
+      puts JSON.generate(payload)
+    end
+  end
+end
+
+SmartBrain::CLI.run(ARGV)

data/lib/smart_brain/adapters/smart_rag/direct_client.rb

@@ -1,16 +1,26 @@
 # frozen_string_literal: true
 
+require_relative 'scope_filter'
+
 module SmartBrain
   module Adapters
     module SmartRag
       class DirectClient
-        def initialize(rag:)
+        include ScopeFilter
+
+        def initialize(rag:, scope_mapper: nil, fail_closed: true)
           @rag = rag
+          @scope_mapper = scope_mapper
+          @fail_closed = fail_closed
         end
 
         def retrieve(plan)
-          response = rag.retrieve(plan: plan)
-          normalize_pack(response, request_id: plan[:request_id])
+          scoped_plan, required, ignored, warnings = prepare_scoped_plan(plan)
+          return scope_failure_pack(plan, ignored, warnings, prefix: 'scope-blocked') unless scoped_plan
+
+          response = rag.retrieve(plan: scoped_plan)
+          pack = normalize_pack(response, request_id: plan[:request_id])
+          enforce_scope_confirmation(pack, required: required, ignored: ignored, warnings: warnings)
         rescue StandardError => e
           {
             version: '0.1',
@@ -26,7 +36,7 @@ module SmartBrain
 
         private
 
-        attr_reader :rag
+        attr_reader :rag, :scope_mapper, :fail_closed
 
         def normalize_pack(response, request_id:)
           pack = response.is_a?(Hash) ? response : {}
@@ -38,7 +48,8 @@ module SmartBrain
             evidences: Array(pack[:evidences]),
             stats: pack[:stats] || { candidates: Array(pack[:evidences]).size, returned: Array(pack[:evidences]).size, took_ms: 0 },
             explain: pack[:explain] || { ignored_fields: [] },
-            warnings: Array(pack[:warnings])
+            warnings: Array(pack[:warnings]),
+            scope_filter_applied: pack[:scope_filter_applied] == true
           }
         end
       end

data/lib/smart_brain/adapters/smart_rag/http_client.rb

@@ -1,18 +1,28 @@
 # frozen_string_literal: true
 
+require_relative 'scope_filter'
+
 module SmartBrain
   module Adapters
     module SmartRag
       class HttpClient
-        def initialize(transport:, timeout_seconds: 2)
+        include ScopeFilter
+
+        def initialize(transport:, timeout_seconds: 2, scope_mapper: nil, fail_closed: true)
           @transport = transport
           @timeout_seconds = timeout_seconds
+          @scope_mapper = scope_mapper
+          @fail_closed = fail_closed
         end
 
         def retrieve(plan)
           started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-          raw = transport.call(plan, timeout_seconds: timeout_seconds)
-          build_pack(raw: raw, request_id: plan[:request_id], took_ms: elapsed_ms(started_at))
+          scoped_plan, required, ignored, warnings = prepare_scoped_plan(plan)
+          return scope_failure_pack(plan, ignored, warnings, prefix: 'scope-blocked') unless scoped_plan
+
+          raw = transport.call(scoped_plan, timeout_seconds: timeout_seconds)
+          pack = build_pack(raw: raw, request_id: plan[:request_id], took_ms: elapsed_ms(started_at))
+          enforce_scope_confirmation(pack, required: required, ignored: ignored, warnings: warnings)
         rescue Timeout::Error
           {
             version: '0.1',
@@ -28,7 +38,7 @@ module SmartBrain
 
         private
 
-        attr_reader :transport, :timeout_seconds
+        attr_reader :transport, :timeout_seconds, :scope_mapper, :fail_closed
 
         def build_pack(raw:, request_id:, took_ms:)
           ignored = []
@@ -48,7 +58,8 @@ module SmartBrain
             explain: {
               ignored_fields: ignored + Array(raw.dig(:explain, :ignored_fields))
             },
-            warnings: Array(raw[:warnings])
+            warnings: Array(raw[:warnings]),
+            scope_filter_applied: raw[:scope_filter_applied] == true
           }
         end
 

data/lib/smart_brain/adapters/smart_rag/null_client.rb

@@ -5,6 +5,9 @@ module SmartBrain
     module SmartRag
       class NullClient
         def retrieve(plan)
+          business_scoped = Array(plan.dig(:scope_context, :read)).any? do |ref|
+            (ref[:type] || ref['type']).to_s != 'session'
+          end
           {
             version: '0.1',
             plan_id: "local-#{plan[:request_id]}",
@@ -12,8 +15,10 @@ module SmartBrain
             generated_at: Time.now.utc.iso8601,
             evidences: [],
             stats: { candidates: 0, returned: 0, took_ms: 0 },
-            explain: { ignored_fields: [] },
-            warnings: ['smart_rag client not configured; returned empty evidences']
+            explain: { ignored_fields: business_scoped ? ['scope_context.read'] : [] },
+            warnings: [business_scoped ? 'smart_rag scope filter unavailable: client not configured; failed closed' :
+              'smart_rag client not configured; returned empty evidences'],
+            scope_filter_applied: !business_scoped
           }
         end
       end

data/lib/smart_brain/adapters/smart_rag/scope_filter.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module SmartBrain
+  module Adapters
+    module SmartRag
+      module ScopeFilter
+        private
+
+        def prepare_scoped_plan(plan)
+          refs = Array(plan.dig(:scope_context, :read)).reject { |ref| (ref[:type] || ref['type']).to_s == 'session' }
+          return [plan, false, [], []] if refs.empty?
+
+          unless scope_mapper
+            warning = 'smart_rag scope filter unavailable: no scope mapper configured'
+            return [nil, true, ['scope_context.read'], [warning]] if fail_closed
+            return [plan, true, ['scope_context.read'], [warning]]
+          end
+
+          mapped = scope_mapper.call(
+            domain_id: plan.dig(:debug, :caller, :domain_id),
+            scopes: refs
+          )
+          applied = mapped.fetch(:applied, true)
+          filters = mapped[:filters] || mapped.reject { |key, _value| %i[applied warnings ignored_fields].include?(key) }
+          warnings = Array(mapped[:warnings])
+          ignored = Array(mapped[:ignored_fields])
+          return [nil, true, ignored + ['scope_context.read'], warnings + ['smart_rag scope mapper did not apply filters']] if !applied && fail_closed
+
+          [plan.merge(scope_filters: filters), true, ignored, warnings]
+        rescue StandardError => e
+          warning = "smart_rag scope mapping failed: #{e.message}"
+          fail_closed ? [nil, true, ['scope_context.read'], [warning]] : [plan, true, ['scope_context.read'], [warning]]
+        end
+
+        def scope_failure_pack(plan, ignored, warnings, prefix:)
+          {
+            version: '0.2', request_id: plan[:request_id], plan_id: "#{prefix}-#{plan[:request_id]}",
+            generated_at: Time.now.utc.iso8601, evidences: [],
+            stats: { candidates: 0, returned: 0, took_ms: 0 },
+            explain: { ignored_fields: ignored }, warnings: warnings,
+            scope_filter_applied: false
+          }
+        end
+
+        def enforce_scope_confirmation(pack, required:, ignored:, warnings:)
+          confirmed = pack[:scope_filter_applied] == true
+          pack[:explain] ||= { ignored_fields: [] }
+          pack[:explain][:ignored_fields] = Array(pack.dig(:explain, :ignored_fields)) + ignored
+          pack[:warnings] = Array(pack[:warnings]) + warnings
+          return pack unless required && !confirmed
+
+          pack[:explain][:ignored_fields] << 'scope_context.read'
+          pack[:warnings] << 'smart_rag did not confirm scope filter application'
+          pack[:evidences] = [] if fail_closed
+          pack
+        end
+      end
+    end
+  end
+end

data/lib/smart_brain/configuration.rb

@@ -37,5 +37,62 @@ module SmartBrain
     def observability
       policies.fetch(:observability, {})
     end
+
+    def scopes
+      policies.fetch(:scopes, {})
+    end
+
+    def allowed_scope_types
+      scopes.fetch(:allowed_types, %w[global project expert task session]).map(&:to_s)
+    end
+
+    def storage
+      raw.fetch(:storage, {})
+    end
+
+    def llm
+      raw.fetch(:model_provider, {})
+    end
+
+    def llm_provider
+      (ENV['SMARTBRAIN_LLM_PROVIDER'] || llm.fetch(:provider, 'stub')).to_s
+    end
+
+    def tiers
+      raw.fetch(:tiers, {})
+    end
+
+    def lifecycle
+      raw.fetch(:lifecycle, {})
+    end
+
+    def kg
+      raw.fetch(:kg, {})
+    end
+
+    def fact_check
+      raw.fetch(:fact_check, {})
+    end
+
+    def briefing
+      raw.fetch(:briefing, {})
+    end
+
+    def storage_backend
+      (ENV['SMARTBRAIN_BACKEND'] || storage.fetch(:backend, 'memory')).to_s
+    end
+
+    def database_config
+      cfg = (storage.fetch(:database, {}) || {}).dup
+      %i[host port database user password].each do |key|
+        env_key = "SMARTBRAIN_DB_#{key.to_s.upcase}"
+        cfg[key] = ENV[env_key] if ENV.key?(env_key)
+      end
+      cfg
+    end
+
+    def fts_config
+      storage.fetch(:fts_config, nil) || database_config.fetch(:fts_config, 'simple')
+    end
   end
 end

data/lib/smart_brain/consolidator/working_summary.rb

@@ -1,42 +1,103 @@
 # frozen_string_literal: true
 
+require_relative '../model_provider/stub'
+
 module SmartBrain
   module Consolidator
+    # WorkingSummary is store-backed: summaries persist via the MemoryStore
+    # (in-memory hash for MemoryStore::InMemory, the summaries table for
+    # MemoryStore::Postgres), so they survive runtime restarts on the PG path.
+    # The last-summary turn is derived from the persisted summary's source range.
+    #
+    # When a real LLM ModelProvider is wired, the summary text is generated by
+    # the model (qwen3 etc.); otherwise it falls back to the deterministic
+    # template (Stub default), so behavior is stable and offline-friendly.
     class WorkingSummary
-      def initialize(config:, clock:)
+      SUMMARY_SYSTEM = 'You are a memory consolidator. Produce a concise rolling ' \
+                       'summary in the exact section structure given. Skip empty ' \
+                       'sections. No preamble, no markdown fences.'
+
+      def initialize(config:, clock:, memory_store:, model_provider: SmartBrain::ModelProvider::Stub.new)
         @config = config
         @clock = clock
-        @summaries = {}
-        @last_summary_turn = Hash.new(0)
+        @memory_store = memory_store
+        @model_provider = model_provider
       end
 
       def update(session_id:, turn_count:, recent_turns:, memory_items:, stage_event: false)
         reason = trigger_reason(session_id: session_id, turn_count: turn_count, recent_turns: recent_turns, stage_event: stage_event)
-        return latest_summary(session_id).merge(triggered: false, trigger_reason: 'not_triggered') unless reason
+        unless reason
+          return latest_summary(session_id).merge(triggered: false, trigger_reason: 'not_triggered')
+        end
 
+        text, method = build_summary_text(memory_items: memory_items, recent_turns: recent_turns)
         summary = {
           summary_version: next_version(session_id),
           summary_source_turn_range: source_turn_range(turn_count),
           summary_generated_at: clock.call.iso8601,
-          text: build_text(memory_items),
+          text: text,
+          summary_method: method,
           triggered: true,
           trigger_reason: reason
         }
-        summaries[session_id] = summary
-        last_summary_turn[session_id] = turn_count
+        memory_store.save_summary(session_id: session_id, summary: summary)
         summary
       end
 
       def latest_summary(session_id)
-        summaries[session_id] || default_summary
+        memory_store.latest_summary(session_id: session_id) || default_summary
       end
 
       private
 
-      attr_reader :config, :clock, :summaries, :last_summary_turn
+      attr_reader :config, :clock, :memory_store, :model_provider
+
+      def build_summary_text(memory_items:, recent_turns:)
+        if model_provider&.llm?
+          text = llm_summary(memory_items: memory_items, recent_turns: recent_turns)
+          return [text, 'llm'] unless text.nil? || text.strip.empty?
+        end
+
+        [build_text(memory_items), 'template']
+      end
+
+      def llm_summary(memory_items:, recent_turns:)
+        result = model_provider.complete(
+          prompt: summary_prompt(memory_items: memory_items, recent_turns: recent_turns),
+          system: SUMMARY_SYSTEM,
+          temperature: config.llm.fetch(:temperature, 0.2),
+          max_tokens: config.llm.fetch(:summary_max_tokens, 900)
+        )
+        result[:error] ? nil : result[:text]
+      rescue StandardError
+        nil
+      end
+
+      def summary_prompt(memory_items:, recent_turns:)
+        convo = Array(recent_turns).map { |t| "#{t[:role]}: #{t[:content]}" }.join("\n")
+        mem = memory_items.group_by { |i| i[:type] }
+                          .map { |type, items| "#{type}: #{items.first(8).map { |i| i[:key] }.join(', ')}" }
+                          .join("\n")
+        <<~PROMPT
+          <conversation>
+          #{convo}
+          </conversation>
+
+          <memory>
+          #{mem}
+          </memory>
+
+          Write a concise rolling summary of the conversation above using ONLY these sections (omit a section if empty, terse bullets, cite memory keys). Do not echo the input or add preamble:
+          Goals:
+          Decisions:
+          Tasks:
+          Key References:
+          Open Questions:
+        PROMPT
+      end
 
       def trigger_reason(session_id:, turn_count:, recent_turns:, stage_event:)
-        turns_since_last = turn_count - last_summary_turn[session_id]
+        turns_since_last = turn_count - last_summary_turn(session_id)
         threshold = config.retention.fetch(:summarize_after_turns, 12)
         return 'turn_threshold' if turns_since_last >= threshold
 
@@ -48,13 +109,20 @@ module SmartBrain
         nil
       end
 
+      def last_summary_turn(session_id)
+        summary = memory_store.latest_summary(session_id: session_id)
+        return 0 unless summary
+
+        (summary[:summary_source_turn_range] || {})[:to].to_i
+      end
+
       def estimate_tokens(recent_turns)
         recent_turns.sum { |t| t[:content].to_s.length / 4 }
       end
 
       def next_version(session_id)
-        previous = summaries[session_id]
-        previous ? previous[:summary_version] + 1 : 1
+        previous = memory_store.latest_summary(session_id: session_id)
+        previous ? previous[:summary_version].to_i + 1 : 1
       end
 
       def source_turn_range(turn_count)

data/lib/smart_brain/context_composer/composer.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'securerandom'
+require_relative '../governance/tiers'
 
 module SmartBrain
   module ContextComposer
@@ -10,9 +11,10 @@ module SmartBrain
         @clock = clock
       end
 
-      def compose(session_id:, user_message:, plan:, plan_id:, summary:, recent_turns:, evidence_bundle:)
+      def compose(session_id:, user_message:, plan:, plan_id:, summary:, recent_turns:, evidence_bundle:,
+                  domain_id: 'legacy', scope_context: nil)
         context_id = SecureRandom.uuid
-        evidence = evidence_bundle.fetch(:selected, [])
+        evidence = apply_tier_order(evidence_bundle.fetch(:selected, []))
         used_estimate = estimate_tokens(summary: summary[:text], recent_turns: recent_turns, evidence: evidence, user_message: user_message)
         token_limit = config.composition.fetch(:token_limit, 8192)
 
@@ -20,6 +22,8 @@ module SmartBrain
           version: '0.1',
           context_id: context_id,
           session_id: session_id,
+          domain_id: domain_id,
+          scope_context: scope_context,
           created_at: clock.call.iso8601,
           system_blocks: [],
           developer_blocks: [],
@@ -54,7 +58,14 @@ module SmartBrain
             },
             why_selected: evidence.map { |e| "#{e[:id]} score=#{e[:score]} source=#{e[:source]}" },
             ignored: evidence_bundle[:ignored_fields] || [],
-            dropped: (evidence_bundle[:dropped] || []).map { |e| { id: e[:id], reason: e[:drop_reason] } }
+            dropped: (evidence_bundle[:dropped] || []).map { |e| { id: e[:id], reason: e[:drop_reason] } },
+            scopes_read: Array(scope_context && scope_context[:read]),
+            scope_stats: evidence_bundle[:scope_stats] || {},
+            shadowed: (evidence_bundle[:shadowed] || []).map do |e|
+              e.slice(:id, :memory_type, :memory_key, :scope, :shadow_reason, :shadowed_by)
+            end,
+            scope_budget: evidence_bundle[:scope_budget] || {},
+            scope_filter_warnings: evidence_bundle[:scope_filter_warnings] || []
           }
         }
       end
@@ -70,6 +81,32 @@ module SmartBrain
         text_size += user_message.to_s.length
         (text_size / 4.0).ceil
       end
+
+      # Order evidence by mind-model tier (dao_tian → dao_ren → shu → qi →
+      # evidence), preserving score order within a tier, and cap immutable
+      # dao_tian principles at dao_tian_limit.
+      def apply_tier_order(evidence)
+        dao_tian_limit = begin
+                           Governance::Tiers.dao_tian_limit(config)
+                         rescue StandardError
+                           1
+                         end
+        stable = evidence.each_with_index
+        sorted = stable.sort_by do |e, idx|
+          [Governance::Tiers.priority(e[:tier] || 'evidence'), -(e[:score] || 0.0), idx]
+        end
+        result = []
+        dao_tian_count = 0
+        sorted.each do |e, _idx|
+          if (e[:tier] || 'evidence') == 'dao_tian'
+            next if dao_tian_count >= dao_tian_limit
+
+            dao_tian_count += 1
+          end
+          result << e
+        end
+        result
+      end
     end
   end
 end

data/lib/smart_brain/contracts/retrieval_plan.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'scope_context'
+
 module SmartBrain
   module Contracts
     class RetrievalPlan
@@ -10,6 +12,14 @@ module SmartBrain
         raise ArgumentError, "invalid retrieval plan: missing #{missing.join(', ')}" unless missing.empty?
         raise ArgumentError, 'invalid retrieval plan: queries must not be empty' if Array(plan[:queries]).empty?
 
+        if plan[:scope_context]
+          ScopeContext.normalize(
+            domain_id: plan.dig(:debug, :caller, :domain_id),
+            session_id: plan.dig(:debug, :caller, :session_id) || plan[:session_id],
+            scope_context: plan[:scope_context]
+          )
+        end
+
         true
       end
     end