smart_brain 0.1.2 → 0.3.0

data/lib/smart_brain/runtime.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 require 'securerandom'
+require_relative 'model_provider/stub'
+require_relative 'governance/lifecycle'
+require_relative 'governance/knowledge_graph'
+require_relative 'governance/fact_check'
+require_relative 'governance/briefing'
 require_relative 'contracts/retrieval_plan'
 require_relative 'contracts/evidence_pack'
 require_relative 'contracts/context_package'
@@ -14,33 +19,60 @@ require_relative 'retrievers/memory_retriever'
 require_relative 'adapters/smart_rag/null_client'
 require_relative 'fusion/merger'
 require_relative 'context_composer/composer'
+require_relative 'scopes/registry'
+require_relative 'scopes/resolver'
+require_relative 'scopes/conflict_resolver'
 
 module SmartBrain
   class Runtime
     def self.build(config:, smart_rag_client: nil, clock:)
-      event_store = EventStore::InMemory.new
-      memory_store = MemoryStore::InMemory.new
+      require_relative 'model_provider'
+      event_store, memory_store, scope_registry = build_stores(config: config, clock: clock)
+      model_provider = ModelProvider.build(config)
       new(
         config: config,
         clock: clock,
         event_store: event_store,
         memory_store: memory_store,
+        scope_registry: scope_registry,
+        scope_resolver: Scopes::Resolver.new,
+        conflict_resolver: Scopes::ConflictResolver.new(config: config),
         extractor: MemoryExtractor::Extractor.new(config: config),
-        consolidator: Consolidator::WorkingSummary.new(config: config, clock: clock),
+        consolidator: Consolidator::WorkingSummary.new(config: config, clock: clock, memory_store: memory_store, model_provider: model_provider),
         planner: RetrievalPlanner::Planner.new(config: config),
         memory_retriever: Retrievers::MemoryRetriever.new(config: config),
         smart_rag_client: smart_rag_client || Adapters::SmartRag::NullClient.new,
-        merger: Fusion::Merger.new(config: config),
+        merger: Fusion::Merger.new(config: config, model_provider: model_provider),
         composer: ContextComposer::Composer.new(config: config, clock: clock),
-        tracker: Observability::Tracker.new
+        tracker: Observability::Tracker.new,
+        model_provider: model_provider
       )
     end
 
-    def initialize(config:, clock:, event_store:, memory_store:, extractor:, consolidator:, planner:, memory_retriever:, smart_rag_client:, merger:, composer:, tracker:)
+    def self.build_stores(config:, clock:)
+      if config.storage_backend == 'postgres'
+        require_relative 'db'
+        require_relative 'event_store/postgres'
+        require_relative 'memory_store/postgres'
+        db = SmartBrain::DB.connect(config)
+        SmartBrain::DB.migrate(db) # idempotent; self-provisions the schema
+        [EventStore::Postgres.new(db: db, clock: clock),
+         MemoryStore::Postgres.new(db: db, config: config),
+         Scopes::Registry.new(db: db, clock: clock)]
+      else
+        [EventStore::InMemory.new, MemoryStore::InMemory.new, Scopes::Registry.new(clock: clock)]
+      end
+    end
+
+    def initialize(config:, clock:, event_store:, memory_store:, scope_registry:, scope_resolver:, conflict_resolver:, extractor:, consolidator:, planner:, memory_retriever:, smart_rag_client:, merger:, composer:, tracker:, model_provider: SmartBrain::ModelProvider::Stub.new)
       @config = config
       @clock = clock
+      @model_provider = model_provider
       @event_store = event_store
       @memory_store = memory_store
+      @scope_registry = scope_registry
+      @scope_resolver = scope_resolver
+      @conflict_resolver = conflict_resolver
       @extractor = extractor
       @consolidator = consolidator
       @planner = planner
@@ -49,19 +81,142 @@ module SmartBrain
       @merger = merger
       @composer = composer
       @tracker = tracker
+      @lifecycle = Governance::Lifecycle.new(memory_store: memory_store, config: config, model_provider: model_provider)
+      @knowledge_graph = Governance::KnowledgeGraph.new(memory_store: memory_store, config: config)
+      @fact_check = Governance::FactCheck.new(memory_store: memory_store, config: config)
+      @briefing = Governance::Briefing.new(memory_store: memory_store, event_store: event_store, config: config)
+    end
+
+    def distill(session_id:, domain_id: nil, scope_context: nil, **options)
+      resolved = resolve_scopes(domain_id: domain_id, session_id: session_id, scope_context: scope_context)
+      target = resolved[:default_write_scope]
+      lifecycle.distill(
+        session_id: session_id, scope_id: target[:scope_id], scope: target.slice(:type, :id), **options
+      )
+    end
+
+    def gate(memory_item_id:, domain_id: nil, session_id: nil, scope_context: nil)
+      authorize_item!(memory_item_id, domain_id:, session_id:, scope_context:)
+      lifecycle.gate(memory_item_id: memory_item_id)
+    end
+
+    def promote(memory_item_id:, domain_id: nil, session_id: nil, scope_context: nil, **options)
+      authorize_item!(memory_item_id, domain_id:, session_id:, scope_context:)
+      lifecycle.promote(memory_item_id: memory_item_id, **options)
+    end
+
+    def demote(memory_item_id:, domain_id: nil, session_id: nil, scope_context: nil, **options)
+      authorize_item!(memory_item_id, domain_id:, session_id:, scope_context:)
+      lifecycle.demote(memory_item_id: memory_item_id, **options)
+    end
+
+    def retract(memory_item_id:, domain_id: nil, session_id: nil, scope_context: nil, **options)
+      authorize_item!(memory_item_id, domain_id:, session_id:, scope_context:)
+      lifecycle.retract(memory_item_id: memory_item_id, **options)
+    end
+
+    def promote_to_scope(memory_item_id:, target_scope:, domain_id:, session_id:, scope_context:,
+                         verification_refs:, reason:, reviewer: nil)
+      source = authorize_item!(memory_item_id, domain_id:, session_id:, scope_context:)
+      resolved = resolve_scopes(domain_id: domain_id, session_id: session_id, scope_context: scope_context)
+      normalized_target = normalize_scope_ref(target_scope)
+      target = resolved[:scopes].find do |scope|
+        scope[:type] == normalized_target[:type] && scope[:id] == normalized_target[:id]
+      end
+      writable = resolved[:write].any? { |scope| scope == normalized_target }
+      scope_validation_failure!("target scope is not writable: #{normalized_target[:type]}:#{normalized_target[:id]}") unless target && writable
+
+      result = lifecycle.promote_to_scope(
+        source_item: source, target_scope: target, session_id: session_id,
+        verification_refs: verification_refs, reason: reason, reviewer: reviewer
+      )
+      tracker.log_scope_promotion(result)
+      result
+    end
+
+    def demote_from_scope(...) = demote(...)
+
+    def promotion_lineage(memory_item_id:, domain_id: nil, session_id: nil, scope_context: nil)
+      authorize_item!(memory_item_id, domain_id:, session_id:, scope_context:)
+      lifecycle.lineage(memory_item_id: memory_item_id)
+    end
+
+    def knowledge_events(memory_item_id:, domain_id: nil, session_id: nil, scope_context: nil)
+      authorize_item!(memory_item_id, domain_id:, session_id:, scope_context:)
+      lifecycle.events(memory_item_id: memory_item_id)
+    end
+
+    def kg_add(session_id:, domain_id: nil, scope_context: nil, scope_ref: nil, **options)
+      resolved = resolve_scopes(domain_id: domain_id, session_id: session_id, scope_context: scope_context)
+      target_ref = normalize_scope_ref(scope_ref || resolved[:default_write])
+      target = resolved[:scopes].find { |scope| scope[:type] == target_ref[:type] && scope[:id] == target_ref[:id] }
+      writable = resolved[:write].include?(target_ref)
+      scope_validation_failure!("target scope is not writable: #{target_ref[:type]}:#{target_ref[:id]}") unless target && writable
+
+      knowledge_graph.add(
+        session_id: session_id, scope_id: target[:scope_id], scope: target_ref,
+        source_session_id: session_id, **options
+      )
+    end
+
+    def kg_query(session_id:, domain_id: nil, scope_context: nil, **options)
+      resolved = resolve_scopes(domain_id: domain_id, session_id: session_id, scope_context: scope_context)
+      knowledge_graph.query(scope_ids: resolved[:scope_ids], **options)
+    end
+
+    def kg_timeline(session_id:, domain_id: nil, scope_context: nil, **options)
+      resolved = resolve_scopes(domain_id: domain_id, session_id: session_id, scope_context: scope_context)
+      knowledge_graph.timeline(scope_ids: resolved[:scope_ids], **options)
+    end
+
+    def kg_invalidate(edge_id:, reason: nil, domain_id: nil, session_id: nil, scope_context: nil)
+      authorize_edge!(edge_id, domain_id:, session_id:, scope_context:)
+      knowledge_graph.invalidate(edge_id: edge_id, reason: reason)
+    end
+
+    def kg_stats(session_id:, domain_id: nil, scope_context: nil)
+      resolved = resolve_scopes(domain_id: domain_id, session_id: session_id, scope_context: scope_context)
+      knowledge_graph.stats(scope_ids: resolved[:scope_ids])
+    end
+
+    def fact_check(session_id:, text:, domain_id: nil, scope_context: nil, **options)
+      resolved = resolve_scopes(domain_id: domain_id, session_id: session_id, scope_context: scope_context)
+      @fact_check.check(session_id: session_id, text: text, scope_ids: resolved[:scope_ids], **options)
+    end
+
+    def brief(session_id:, query: nil, domain_id: nil, scope_context: nil)
+      resolved = resolve_scopes(domain_id: domain_id, session_id: session_id, scope_context: scope_context)
+      @briefing.brief(
+        session_id: session_id, query: query, scope_ids: resolved[:scope_ids], domain_id: resolved[:domain_id],
+        scope_context: public_scope_context(resolved)
+      )
     end
 
-    def commit_turn(session_id:, turn_events:)
+    def wake_up(session_id:, domain_id: nil, scope_context: nil)
+      resolved = resolve_scopes(domain_id: domain_id, session_id: session_id, scope_context: scope_context)
+      @briefing.wake_up(
+        session_id: session_id, scope_ids: resolved[:scope_ids], domain_id: resolved[:domain_id],
+        scope_context: public_scope_context(resolved)
+      )
+    end
+    def resume(...) = @briefing.resume(...)
+
+    def commit_turn(session_id:, turn_events:, domain_id: nil, scope_context: nil)
       started_at = monotonic_time
       now = clock.call
-      turn = event_store.append_turn(session_id: session_id, turn_events: turn_events, created_at: now)
+      resolved = resolve_scopes(domain_id: domain_id, session_id: session_id, scope_context: scope_context)
+      turn = event_store.append_turn(
+        session_id: session_id, turn_events: turn_events, created_at: now, domain_id: resolved[:domain_id]
+      )
       entity_frequencies = event_store.entity_frequencies(
         session_id: session_id,
         window_turns: config.retention.dig(:entity_gate, :window_turns) || 20
       )
 
       extracted = extractor.extract(session_id: session_id, turn: turn, entity_frequencies: entity_frequencies)
+      extracted = route_scoped_records(extracted, resolved, session_id)
       write_result = memory_store.upsert(extracted)
+      edges_written = persist_edges(session_id: session_id, turn_id: turn[:id], edges: extracted[:edges])
       turn_count = event_store.turns_count(session_id: session_id)
       recent_turns = event_store.recent_turns(session_id: session_id, limit: config.composition.fetch(:recent_turns_max, 8))
       stage_event = extracted[:items].any? { |item| item[:type] == 'decisions' || (item[:type] == 'tasks' && item.dig(:value_json, :status) == 'done') }
@@ -69,7 +224,7 @@ module SmartBrain
         session_id: session_id,
         turn_count: turn_count,
         recent_turns: recent_turns,
-        memory_items: memory_store.active_items(session_id: session_id),
+        memory_items: memory_store.active_items(scope_ids: [resolved[:default_write_scope][:scope_id]]),
         stage_event: stage_event
       )
 
@@ -77,12 +232,18 @@ module SmartBrain
         ok: true,
         commit_id: SecureRandom.uuid,
         session_id: session_id,
+        domain_id: resolved[:domain_id],
+        scope_context: public_scope_context(resolved),
         turn_id: turn[:id],
         memory_written: write_result,
         summary: summary,
         explain: {
           retention: extracted.fetch(:explain, []),
           conflicts: write_result.fetch(:conflicts, []),
+          scope_routing: write_result.fetch(:items, []).map do |item|
+            item.slice(:id, :type, :key, :scope, :source_session_id)
+          end,
+          edges: edges_written,
           summary: {
             triggered: summary[:triggered],
             reason: summary[:trigger_reason]
@@ -103,8 +264,10 @@ module SmartBrain
       result
     end
 
-    def compose_context(session_id:, user_message:, agent_state: {})
+    def compose_context(session_id:, user_message:, agent_state: {}, domain_id: nil, scope_context: nil,
+                        resource_filters: {})
       started_at = monotonic_time
+      resolved = resolve_scopes(domain_id: domain_id, session_id: session_id, scope_context: scope_context)
       recent_turns = event_store.recent_turns(session_id: session_id, limit: config.composition.fetch(:recent_turns_max, 8))
       refs = event_store.recent_refs(session_id: session_id, limit: config.composition.fetch(:recent_turns_max, 8))
       request_id = SecureRandom.uuid
@@ -116,15 +279,24 @@ module SmartBrain
         recent_turns: recent_turns,
         refs: refs
       )
+      plan[:scope_context] = public_scope_context(resolved)
+      plan[:global_filters] = plan.fetch(:global_filters, {}).merge(symbolize_keys(resource_filters))
+      plan[:debug] = (plan[:debug] || {}).merge(
+        caller: { app: 'smart_brain', domain_id: resolved[:domain_id], session_id: session_id }
+      )
       Contracts::RetrievalPlan.validate!(plan)
 
       memory_evidence = memory_retriever.retrieve(
         query: user_message,
-        memory_items: memory_store.active_items(session_id: session_id),
+        memory_store: memory_store,
+        session_id: session_id,
+        scope_ids: resolved[:scope_ids],
         recent_turns: recent_turns,
-        entities: memory_store.entities(session_id: session_id),
+        entities: memory_store.entities(scope_ids: resolved[:scope_ids]),
         refs: refs
       )
+      conflict_result = conflict_resolver.resolve(memory_evidence)
+      memory_evidence = conflict_result[:selected]
 
       resource_pack = if plan.dig(:resource_retrieval, :enabled)
                         smart_rag_client.retrieve(plan)
@@ -147,15 +319,23 @@ module SmartBrain
         resource_evidence: resource_pack.fetch(:evidences, [])
       )
       merged_bundle[:ignored_fields] = Array(merged_bundle[:ignored_fields]) + Array(resource_pack.dig(:explain, :ignored_fields))
+      merged_bundle[:scope_filter_warnings] = Array(resource_pack[:warnings]).select do |warning|
+        warning.to_s.include?('scope')
+      end
 
       context = composer.compose(
         session_id: session_id,
+        domain_id: resolved[:domain_id],
+        scope_context: public_scope_context(resolved),
         user_message: user_message,
         plan: plan,
         plan_id: resource_pack[:plan_id],
         summary: consolidator.latest_summary(session_id),
         recent_turns: recent_turns,
-        evidence_bundle: merged_bundle
+        evidence_bundle: merged_bundle.merge(
+          shadowed: conflict_result[:shadowed], scope_stats: conflict_result[:scope_stats],
+          scope_budget: conflict_result[:scope_budget], scope_filter_warnings: merged_bundle[:scope_filter_warnings]
+        )
       )
       Contracts::ContextPackage.validate!(context)
 
@@ -170,24 +350,134 @@ module SmartBrain
         ignored_fields: context.dig(:debug, :ignored),
         token_used: token_budget[:used_estimate] || 0,
         token_limit: token_budget[:limit] || config.composition.fetch(:token_limit, 8192),
-        took_ms: took_ms
+        took_ms: took_ms,
+        scope_stats: conflict_result[:scope_stats],
+        shadowed_count: conflict_result[:shadowed].size,
+        scope_filter_warnings: merged_bundle[:scope_filter_warnings]
       )
       context
     end
 
+    def search_memory(session_id:, query:, limit: nil, domain_id: nil, scope_context: nil)
+      limit ||= config.retrieval.fetch(:top_k, 30)
+      resolved = resolve_scopes(domain_id: domain_id, session_id: session_id, scope_context: scope_context)
+      result = memory_store.search_memory(query: query, scope_ids: resolved[:scope_ids], limit: limit * resolved[:scope_ids].size)
+      conflict_resolver.resolve(result)[:selected].first(limit)
+    end
+
+    def add_document(source:, options: {}) = smart_rag_client.add_document(source, options)
+    def add_media(source:, options: {}) = smart_rag_client.add_media(source, options)
+    def add_image(source:, options: {}) = smart_rag_client.add_image(source, options)
+    def add_audio(source:, options: {}) = smart_rag_client.add_audio(source, options)
+    def add_video(source:, options: {}) = smart_rag_client.add_video(source, options)
+    def enqueue_media(source:, options: {}) = smart_rag_client.enqueue_media(source, options)
+    def media_job(job_id:) = smart_rag_client.media_job(job_id)
+    def media_jobs(status: nil, limit: 20, offset: 0) = smart_rag_client.media_jobs(status: status, limit: limit, offset: offset)
+    def cancel_media_job(job_id:) = smart_rag_client.cancel_media_job(job_id)
+    def retry_media_job(job_id:) = smart_rag_client.retry_media_job(job_id)
+    def media_job_statistics = smart_rag_client.media_job_statistics
+
+    def memory_item(id:)
+      memory_store.find_item(id: id)
+    end
+
+    def storage_backend
+      config.storage_backend
+    end
+
     def diagnostics
-      tracker.snapshot.merge(turns: event_store.all_turns(session_id: nil))
+      tracker.snapshot.merge(
+        backend: storage_backend,
+        turns: event_store.all_turns(session_id: nil),
+        summaries: memory_store.all_summaries
+      )
     end
 
     private
 
     attr_reader :config, :clock, :event_store, :memory_store, :extractor, :consolidator,
-                :planner, :memory_retriever, :smart_rag_client, :merger, :composer, :tracker
+                :scope_registry, :scope_resolver, :conflict_resolver, :planner, :memory_retriever,
+                :smart_rag_client, :merger, :composer, :tracker, :model_provider, :lifecycle, :knowledge_graph
+
+    def resolve_scopes(domain_id:, session_id:, scope_context:)
+      scope_registry.resolve(
+        domain_id: domain_id, session_id: session_id, scope_context: scope_context,
+        allowed_types: config.allowed_scope_types
+      )
+    rescue ArgumentError => e
+      tracker.log_scope_validation_failure(e)
+      raise
+    end
+
+    def public_scope_context(resolved)
+      { read: resolved[:read], write: resolved[:write], default_write: resolved[:default_write] }
+    end
+
+    def route_scoped_records(extracted, resolved, session_id)
+      scope_resolver.route(extracted: extracted, resolved_context: resolved, source_session_id: session_id)
+    rescue ArgumentError => e
+      tracker.log_scope_validation_failure(e)
+      raise
+    end
+
+    def normalize_scope_ref(ref)
+      Contracts::ScopeRef.normalize(ref, allowed_types: config.allowed_scope_types)
+    rescue ArgumentError => e
+      tracker.log_scope_validation_failure(e)
+      raise
+    end
+
+    def symbolize_keys(hash)
+      hash.each_with_object({}) { |(key, value), result| result[key.to_sym] = value }
+    end
+
+    def scope_validation_failure!(message)
+      error = ArgumentError.new(message)
+      tracker.log_scope_validation_failure(error)
+      raise error
+    end
+
+    def authorize_item!(memory_item_id, domain_id:, session_id:, scope_context:)
+      item = memory_store.find_item(id: memory_item_id)
+      raise ArgumentError, "memory item not found: #{memory_item_id}" unless item
+      return item unless domain_id || session_id || scope_context
+      scope_validation_failure!('session_id is required to validate memory item access') if session_id.to_s.empty?
+
+      resolved = resolve_scopes(domain_id: domain_id, session_id: session_id, scope_context: scope_context)
+      scope_validation_failure!("memory item is outside the requested domain/scopes: #{memory_item_id}") unless resolved[:scope_ids].include?(item[:scope_id])
+
+      item
+    end
+
+    def authorize_edge!(edge_id, domain_id:, session_id:, scope_context:)
+      edge = memory_store.find_edge(id: edge_id)
+      raise ArgumentError, "edge not found: #{edge_id}" unless edge
+      return edge unless domain_id || session_id || scope_context
+      scope_validation_failure!('session_id is required to validate edge access') if session_id.to_s.empty?
+
+      resolved = resolve_scopes(domain_id: domain_id, session_id: session_id, scope_context: scope_context)
+      scope_validation_failure!("edge is outside the requested domain/scopes: #{edge_id}") unless resolved[:scope_ids].include?(edge[:scope_id])
+
+      edge
+    end
 
     def monotonic_time
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
 
+    def persist_edges(session_id:, turn_id:, edges:)
+      return [] unless edges&.any?
+
+      edges.map do |edge|
+        knowledge_graph.add(
+          session_id: session_id,
+          subject: edge[:subject], predicate: edge[:predicate], object: edge[:object],
+          source_turn_id: turn_id, confidence: edge[:confidence], scope_id: edge[:scope_id],
+          scope: edge[:scope], source_session_id: edge[:source_session_id]
+        )
+      end
+    end
+
     def elapsed_ms(start)
       ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(2)
     end

data/lib/smart_brain/scopes/conflict_resolver.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module SmartBrain
+  module Scopes
+    class ConflictResolver
+      DEFAULT_PRIORITY = %w[task project expert global session].freeze
+
+      def initialize(config:)
+        @priority = Array(config.scopes[:conflict_priority] || DEFAULT_PRIORITY).map(&:to_s)
+        @max_items_per_scope = Integer(config.scopes.fetch(:max_items_per_scope, 10))
+      end
+
+      def resolve(evidence)
+        selected = []
+        shadowed = []
+        keyed, unkeyed = evidence.partition { |item| item[:source] == 'memory' && item[:memory_type] && item[:memory_key] }
+
+        keyed.group_by { |item| [item[:memory_type], item[:memory_key]] }.each_value do |candidates|
+          winner = candidates.min_by { |item| winner_rank(item) }
+          selected << winner
+          candidates.each do |candidate|
+            next if candidate.equal?(winner)
+
+            shadowed << candidate.merge(
+              shadow_reason: shadow_reason(winner, candidate),
+              shadowed_by: winner[:id]
+            )
+          end
+        end
+        selected.concat(unkeyed)
+
+        budgeted = []
+        counts = Hash.new(0)
+        selected.sort_by { |item| -item.fetch(:score, 0.0) }.each do |item|
+          scope_key = item[:scope] && "#{item.dig(:scope, :type)}:#{item.dig(:scope, :id)}"
+          if scope_key && counts[scope_key] >= @max_items_per_scope
+            shadowed << item.merge(shadow_reason: 'scope_budget')
+          else
+            counts[scope_key] += 1 if scope_key
+            budgeted << item
+          end
+        end
+
+        {
+          selected: budgeted,
+          shadowed: shadowed,
+          scope_stats: counts,
+          scope_budget: { max_items_per_scope: @max_items_per_scope }
+        }
+      end
+
+      private
+
+      def winner_rank(item)
+        pinned = item[:tier].to_s == 'dao_tian' ? 0 : 1
+        scope_priority = @priority.index(item.dig(:scope, :type).to_s) || @priority.length
+        [pinned, scope_priority, -item.fetch(:score, 0.0)]
+      end
+
+      def shadow_reason(winner, candidate)
+        return 'dao_tian_pinned' if winner[:tier].to_s == 'dao_tian' && candidate[:tier].to_s != 'dao_tian'
+
+        "more_specific_scope:#{winner.dig(:scope, :type)}"
+      end
+    end
+  end
+end

data/lib/smart_brain/scopes/registry.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative '../contracts/scope_context'
+
+module SmartBrain
+  module Scopes
+    class Registry
+      def initialize(db: nil, clock: -> { Time.now.utc })
+        @db = db
+        @clock = clock
+        @domains = {}
+        @sessions = {}
+        @scopes = {}
+        @links = {}
+      end
+
+      def resolve(domain_id:, session_id:, scope_context:, allowed_types: Contracts::ScopeRef::DEFAULT_ALLOWED_TYPES)
+        context = Contracts::ScopeContext.normalize(
+          domain_id: domain_id, session_id: session_id, scope_context: scope_context, allowed_types: allowed_types
+        )
+        records = db ? resolve_postgres(context, session_id.to_s) : resolve_memory(context, session_id.to_s)
+        default_key = scope_key(context[:default_write])
+
+        context.merge(
+          scopes: records,
+          scope_ids: records.map { |record| record[:scope_id] },
+          default_write_scope: records.find { |record| scope_key(record) == default_key }
+        )
+      end
+
+      private
+
+      attr_reader :db, :clock, :domains, :sessions, :scopes, :links
+
+      def resolve_memory(context, session_id)
+        domain_id = context[:domain_id]
+        domains[domain_id] ||= { id: domain_id, metadata: {}, created_at: clock.call.iso8601 }
+        existing_domain = sessions[session_id]
+        if existing_domain && existing_domain != domain_id
+          raise ArgumentError, "session #{session_id} belongs to domain #{existing_domain}"
+        end
+        sessions[session_id] = domain_id
+
+        context[:read].each_with_index.map do |ref, priority|
+          key = [domain_id, ref[:type], ref[:id]]
+          scope = scopes[key] ||= scope_record(domain_id, ref)
+          links[[session_id, scope[:scope_id]]] = {
+            access_mode: writable?(context, ref) ? 'read_write' : 'read',
+            priority: priority
+          }
+          scope
+        end
+      end
+
+      def resolve_postgres(context, session_id)
+        domain_id = context[:domain_id]
+        records = []
+        db.transaction do
+          ensure_domain(domain_id)
+          ensure_session(session_id, domain_id)
+          records = context[:read].each_with_index.map do |ref, priority|
+            scope = ensure_scope(domain_id, ref)
+            ensure_link(session_id, scope[:id], priority, writable?(context, ref) ? 'read_write' : 'read')
+            scope_record_from_row(scope)
+          end
+        end
+        records
+      end
+
+      def ensure_domain(domain_id)
+        return if db[:domains].where(id: domain_id).first
+
+        now = clock.call
+        db[:domains].insert(id: domain_id, metadata_json: Sequel.pg_jsonb({}), created_at: now, updated_at: now)
+      end
+
+      def ensure_session(session_id, domain_id)
+        row = db[:sessions].where(id: session_id).first
+        if row && row[:domain_id] != domain_id
+          raise ArgumentError, "session #{session_id} belongs to domain #{row[:domain_id]}"
+        end
+        return if row
+
+        db[:sessions].insert(id: session_id, domain_id: domain_id, created_at: clock.call, metadata_json: Sequel.pg_jsonb({}))
+      end
+
+      def ensure_scope(domain_id, ref)
+        dataset = db[:memory_scopes].where(domain_id: domain_id, scope_type: ref[:type], external_id: ref[:id])
+        dataset.first || begin
+          now = clock.call
+          id = SecureRandom.uuid
+          db[:memory_scopes].insert(
+            id: id, domain_id: domain_id, scope_type: ref[:type], external_id: ref[:id],
+            metadata_json: Sequel.pg_jsonb({}), created_at: now, updated_at: now
+          )
+          db[:memory_scopes].where(id: id).first
+        end
+      end
+
+      def ensure_link(session_id, scope_id, priority, access_mode)
+        db[:session_scope_links].insert_conflict(
+          target: %i[session_id scope_id], update: { access_mode: access_mode, priority: priority }
+        ).insert(session_id: session_id, scope_id: scope_id, access_mode: access_mode, priority: priority, created_at: clock.call)
+      end
+
+      def scope_record(domain_id, ref)
+        {
+          scope_id: legacy_scope?(domain_id, ref) ? "legacy:session:#{ref[:id]}" : SecureRandom.uuid,
+          domain_id: domain_id,
+          type: ref[:type],
+          id: ref[:id]
+        }
+      end
+
+      def scope_record_from_row(row)
+        { scope_id: row[:id], domain_id: row[:domain_id], type: row[:scope_type], id: row[:external_id] }
+      end
+
+      def scope_key(ref)
+        "#{ref[:type]}:#{ref[:id]}"
+      end
+
+      def writable?(context, ref)
+        context[:write].any? { |candidate| scope_key(candidate) == scope_key(ref) }
+      end
+
+      def legacy_scope?(domain_id, ref)
+        domain_id == Contracts::ScopeContext::LEGACY_DOMAIN_ID && ref[:type] == 'session'
+      end
+    end
+  end
+end

data/lib/smart_brain/scopes/resolver.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module SmartBrain
+  module Scopes
+    class Resolver
+      def route(extracted:, resolved_context:, source_session_id:)
+        extracted.merge(
+          domain_id: resolved_context[:domain_id],
+          items: Array(extracted[:items]).map { |item| route_record(item, resolved_context, source_session_id) },
+          edges: Array(extracted[:edges]).map { |edge| route_record(edge, resolved_context, source_session_id) }
+        )
+      end
+
+      private
+
+      def route_record(record, context, source_session_id)
+        requested = record[:scope_ref] || context[:default_write]
+        normalized = Contracts::ScopeRef.normalize(requested)
+        writable = context[:write].any? { |candidate| candidate[:type] == normalized[:type] && candidate[:id] == normalized[:id] }
+        raise ArgumentError, "scope is not authorized by scope_context.write: #{normalized[:type]}:#{normalized[:id]}" unless writable
+
+        scope = context[:scopes].find { |candidate| candidate[:type] == normalized[:type] && candidate[:id] == normalized[:id] }
+
+        record.merge(
+          scope_id: scope[:scope_id],
+          scope: { type: scope[:type], id: scope[:id] },
+          source_session_id: source_session_id
+        ).tap { |routed| routed.delete(:scope_ref) }
+      end
+    end
+  end
+end