maglev-rb 0.1.1 → 0.2.1

data/lib/maglev/retriever.rb

@@ -1,49 +1,248 @@
 # frozen_string_literal: true
 
-require_relative "adapters/ruby_llm_embedding"
+require_relative "adapters/faraday_embedding"
 require_relative "authorization"
 require_relative "chunk"
+require_relative "index_identity"
 require_relative "provider_call"
+require_relative "retrieval_outcome"
+require_relative "retrieval_result"
+require_relative "context_assembler"
+require "securerandom"
 require_relative "search_result"
 require_relative "vector_stores/pgvector"
 
 module Maglev
   class Retriever
-    def initialize(model_class, chunk_model: Chunk, embedding_adapter: Maglev.configuration.embedding_adapter, authorization: Authorization.new, vector_store: Maglev.configuration.vector_store)
+    OWNER_DIVERSE_OVERFETCH = 4
+    AUTHORIZED_OWNER_LIMIT = 1_000
+    IdentityConfiguration = Struct.new(
+      :embedding_model,
+      :embedding_dimensions,
+      :embedding_adapter_id,
+      :embedding_adapter_version,
+      :application_index_version
+    )
+    private_constant :IdentityConfiguration
+
+    def initialize(model_class, chunk_model: Chunk, embedding_adapter: Maglev.configuration.embedding_adapter, embedding_dimensions: Maglev.configuration.embedding_dimensions, chunk_size: Maglev.configuration.chunk_size, authorization: Authorization.new, vector_store: Maglev.configuration.vector_store)
       @model_class = model_class
       @chunk_model = chunk_model
-      @embedding_adapter = embedding_adapter || Adapters::RubyLLMEmbedding.new
+      @embedding_adapter = embedding_adapter || Adapters::FaradayEmbedding.new
+      @embedding_dimensions = embedding_dimensions
+      @chunk_size = chunk_size
       @authorization = authorization
       @vector_store = vector_store
     end
 
-    def search(query, limit:, owner: nil, user: nil)
+    def search(query, limit:, owner: nil, user: nil, minimum_similarity: nil)
+      @candidate_ids = nil
+      retrieval_outcome(
+        query,
+        limit: limit,
+        owner: owner,
+        user: user,
+        minimum_similarity: minimum_similarity,
+        chunks_per_owner: 1
+      ).results
+    end
+
+    def retrieve(query, limit:, owner: nil, user: nil, minimum_similarity: nil, chunks_per_owner: 1, trace_id: SecureRandom.uuid, candidates: nil)
+      started = monotonic
+      validate_candidates!(candidates)
+      @candidate_ids = candidates&.ids
+      outcome = retrieval_outcome(query, limit: limit, owner: owner, user: user,
+        minimum_similarity: minimum_similarity, chunks_per_owner: chunks_per_owner)
+      context_started = monotonic
+      context = ContextAssembler.new.assemble(outcome.results)
+      context_ms = elapsed_ms(context_started)
+      selected_ids = context.sources.map { |source| [source[:owner_type], source[:owner_id], source[:source], source[:chunk_index]] }
+      selected = outcome.results.select do |result|
+        selected_ids.include?([result.owner.class.name, result.owner.respond_to?(:id) ? result.owner.id : result.owner, result.source, result.chunk_index])
+      end
+      budget_rejected = outcome.results - selected
+      rejected = outcome.rejected_results.map { |result| {source: result, reason: :relevance_threshold} } +
+        budget_rejected.map { |result| {source: result, reason: :context_budget} }
+      timings = @last_timings.merge(context_assembly_ms: context_ms, total_ms: elapsed_ms(started)).freeze
+      reasons = rejected.map { |item| item[:reason] }
+      if outcome.considered.empty?
+        reasons << ((outcome.authorization_rejected_count.positive? || @authorization_filter_applied) ? :authorization_filtered : :no_documents)
+      end
+      reasons = reasons.uniq.freeze
+      payload = {trace_id: trace_id, model: @model_class.name, considered_count: outcome.considered.size,
+                 selected_count: selected.size, rejected_count: rejected.size, timings: timings}.freeze
+      ActiveSupport::Notifications.instrument("maglev.retrieval.complete", payload)
+      RetrievalResult.new(query: query, considered: outcome.considered, selected: selected, rejected: rejected,
+        context: context.text, budgets: context.metadata, reasons: reasons, timings: timings, trace_id: trace_id)
+    end
+
+    def retrieval_outcome(query, limit:, owner: nil, user: nil, minimum_similarity: nil, chunks_per_owner: 1)
+      @authorization_scope_empty = false
+      @authorization_filter_applied = false
+      @request_tenant_id = user ? Maglev.configuration.tenant_id(user: user) : nil
+      threshold = resolve_threshold(minimum_similarity)
+      validate_limit!(limit)
+      validate_chunks_per_owner!(chunks_per_owner)
+      @current_index_version = current_index_version
+      embedding_started = monotonic
       embedding = ProviderCall.new.call(operation: "embed") { @embedding_adapter.embed(query) }
-      return search_vector_store(embedding, limit: limit, owner: owner, user: user) if @vector_store
+      embedding_ms = elapsed_ms(embedding_started)
+      validate_embedding!(embedding)
+
+      bounded_limit = candidate_limit(limit, owner: owner, chunks_per_owner: chunks_per_owner)
+      retrieval_started = monotonic
+      candidates = search_results(fetch_candidates(embedding, owner: owner, user: user, limit: bounded_limit))
+      candidate_count = candidates.size
+      candidates = authorize_results(candidates, user)
+      authorization_rejected_count = candidate_count - candidates.size
+      examined = sorted_results(candidates)
+      accepted, rejected = apply_threshold(examined, threshold)
+      projected = project_results(accepted, limit: limit, owner: owner, chunks_per_owner: chunks_per_owner)
+      @last_timings = {embedding_ms: embedding_ms, retrieval_ms: elapsed_ms(retrieval_started)}.freeze
+
+      RetrievalOutcome.new(
+        results: projected,
+        minimum_similarity: threshold,
+        examined_count: examined.size,
+        accepted_count: accepted.size,
+        rejected_count: rejected.size,
+        best_similarity: examined.filter_map(&:similarity).max,
+        considered: examined,
+        rejected_results: rejected,
+        authorization_rejected_count: authorization_rejected_count
+      )
+    end
+
+    private
+
+    def validate_candidates!(candidates)
+      return unless candidates
+      unless candidates.is_a?(HybridCandidateSet) && candidates.model_class == @model_class
+        raise ConfigurationError, "hybrid candidates do not match the retrieval model"
+      end
+    end
+
+    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    def elapsed_ms(started) = ((monotonic - started) * 1000).round(3)
+
+    def resolve_threshold(request_threshold)
+      threshold = request_threshold || Maglev.configuration.minimum_similarity
+      validate_threshold!(threshold)
+      threshold
+    end
+
+    def validate_threshold!(threshold)
+      return if threshold.nil?
+
+      unless threshold.is_a?(Numeric) && threshold.finite?
+        raise ArgumentError, "minimum_similarity must be a finite Numeric in 0.0..1.0, got: #{threshold.inspect}"
+      end
+      return if (0.0..1.0).cover?(threshold)
+
+      raise ArgumentError, "minimum_similarity must be in 0.0..1.0, got: #{threshold}"
+    end
+
+    def apply_threshold(results, threshold)
+      return [results, []] if threshold.nil?
+
+      accepted = []
+      rejected = []
+      results.each do |result|
+        similarity = result.similarity
+        if similarity && similarity >= threshold
+          accepted << result
+        else
+          rejected << result
+        end
+      end
+      [accepted, rejected]
+    end
+
+    def validate_chunks_per_owner!(value)
+      return if value.is_a?(Integer) && value.positive?
+
+      raise ArgumentError, "chunks_per_owner must be a positive Integer, got: #{value.inspect}"
+    end
+
+    def validate_limit!(value)
+      return if value.is_a?(Integer) && value.positive?
+
+      raise ArgumentError, "limit must be a positive Integer, got: #{value.inspect}"
+    end
+
+    def fetch_candidates(embedding, owner:, user:, limit:)
+      if @vector_store
+        filters = filters_for(owner, user: user)
+        return [] if @authorization_scope_empty
 
-      scope = @chunk_model.where(owner_model_name: @model_class.name)
+        return @vector_store.search(vector: embedding, filters: filters, limit: limit)
+      end
+
+      scope = @chunk_model.where(owner_model_name: @model_class.name, index_version: @current_index_version)
+      scope = scope.where(owner_id: @candidate_ids) if @candidate_ids
       scope = scope.where(owner: owner) if owner
+      tenant_id = @request_tenant_id
+      scope = scope.where(tenant_id: tenant_id) if tenant_id && @chunk_model.columns_hash.key?("tenant_id")
       scope = apply_authorization_scope(scope, user) unless owner
-      rows = scope
-        .nearest_neighbors(:embedding, embedding, distance: "cosine")
+      scope.nearest_neighbors(:embedding, embedding, distance: "cosine").limit(limit)
+    end
 
-      unique_owner_results(rows).first(limit)
+    def project_results(results, limit:, owner:, chunks_per_owner:)
+      return results.first(limit) if owner
+
+      groups = results.group_by { |result| owner_key(result.owner) }
+      selected_owners = groups.values.sort_by { |chunks| result_sort_key(chunks.first) }.first(limit)
+      selected_owners.flat_map { |chunks| chunks.first(chunks_per_owner) }.sort_by { |result| result_sort_key(result) }
     end
 
-    private
+    def candidate_limit(limit, owner:, chunks_per_owner: 1)
+      [limit * chunks_per_owner * OWNER_DIVERSE_OVERFETCH,
+        Maglev.configuration.retrieval_max_candidates].min
+    end
+
+    def sorted_results(results)
+      results.sort_by { |result| result_sort_key(result) }
+    end
 
-    def search_vector_store(embedding, limit:, owner:, user:)
-      documents = @vector_store.search(vector: embedding, filters: filters_for(owner), limit: limit)
-      unique_owner_results(documents).first(limit)
+    def result_sort_key(result)
+      [result.distance || Float::INFINITY, source_priority(result.source_type), *owner_key(result.owner).map(&:to_s), result.chunk_index || Float::INFINITY]
     end
 
-    def filters_for(owner)
-      filters = {owner_model_name: @model_class.name}
+    def owner_key(owner)
+      [owner.class.name, owner.respond_to?(:id) ? owner.id : owner]
+    end
+
+    def source_priority(type) = (type.to_sym == :attribute) ? 1 : 0
+
+    def filters_for(owner, user:)
+      filters = {owner_model_name: @model_class.name, index_version: @current_index_version}
       if owner
         filters[:owner_type] = owner.class.name
         filters[:owner_id] = owner.id
       end
-      filters
+      filters[:tenant_id] = @request_tenant_id
+      authorized_ids = authorized_owner_ids(user) if !owner && @authorization.configured? && user
+      owner_ids = if @candidate_ids && authorized_ids
+        @candidate_ids & authorized_ids
+      else
+        @candidate_ids || authorized_ids
+      end
+      @authorization_scope_empty = true if owner_ids && owner_ids.empty?
+      filters[:owner_ids] = owner_ids if owner_ids&.any?
+      VectorStores::MetadataFilter.new(**filters.compact)
+    end
+
+    def authorized_owner_ids(user)
+      scope = @authorization.scope(model: @model_class, user: user)
+      @authorization_filter_applied = true
+      return unless scope.respond_to?(:limit) && scope.respond_to?(:pluck)
+
+      primary_key = @model_class.respond_to?(:primary_key) ? @model_class.primary_key : :id
+      ids = scope.limit(AUTHORIZED_OWNER_LIMIT + 1).pluck(primary_key.to_sym)
+      raise ConfigurationError, "authorization scope exceeds #{AUTHORIZED_OWNER_LIMIT} owner ids for vector retrieval" if ids.size > AUTHORIZED_OWNER_LIMIT
+
+      @authorization_scope_empty = ids.empty?
+      ids unless ids.empty?
     end
 
     def apply_authorization_scope(scope, user)
@@ -57,33 +256,89 @@ module Maglev
       end
     end
 
-    def unique_owner_results(rows)
-      seen_owners = {}
-      results = []
+    def authorize_results(results, user)
+      return results unless @authorization.configured? && user
 
-      rows.each do |row|
+      results.select { |result| @authorization.authorized?(record: result.owner, user: user) }
+    end
+
+    def current_index_version
+      configuration = Maglev.configuration
+      identity_configuration = IdentityConfiguration.new(
+        embedding_model: configuration.embedding_model,
+        embedding_dimensions: @embedding_dimensions,
+        embedding_adapter_id: configuration.embedding_adapter_id,
+        embedding_adapter_version: configuration.embedding_adapter_version,
+        application_index_version: configuration.application_index_version
+      )
+      IndexIdentity.new(
+        configuration: identity_configuration,
+        adapter: @embedding_adapter,
+        chunk_size: @chunk_size
+      ).to_s
+    end
+
+    def validate_embedding!(embedding)
+      return if embedding.respond_to?(:length) && embedding.length == @embedding_dimensions
+
+      actual = embedding.respond_to?(:length) ? embedding.length : "unknown"
+      raise ConfigurationError, "Embedding adapter returned #{actual} dimensions; expected #{@embedding_dimensions} dimensions"
+    end
+
+    def search_results(rows)
+      rows.filter_map do |row|
+        next unless compatible_owner_metadata?(row)
         owner = owner_for(row)
-        next if seen_owners[owner]
+        next unless owner
 
-        seen_owners[owner] = true
-        results << SearchResult.new(
+        SearchResult.new(
           owner: owner,
           content: row.content,
           source: row.source,
           distance: row.respond_to?(:neighbor_distance) ? row.neighbor_distance : row.distance,
-          chunk_index: row.respond_to?(:chunk_index) ? row.chunk_index : nil
+          chunk_index: row.respond_to?(:chunk_index) ? row.chunk_index : nil,
+          source_identity: row.respond_to?(:source_identity) ? row.source_identity : row.source,
+          source_type: (row.respond_to?(:source_type) && row.source_type) ? row.source_type : inferred_source_type(row.source),
+          score: row.respond_to?(:score) ? row.score : nil
         )
       end
-
-      results
     end
 
     def owner_for(row)
       if row.owner
         row.owner
       elsif row.respond_to?(:owner_type) && row.respond_to?(:owner_id)
-        row.owner_type.constantize.find(row.owner_id)
+        @model_class.find_by(@model_class.primary_key => row.owner_id)
       end
     end
+
+    def compatible_owner_metadata?(row)
+      return true unless @vector_store
+      return false if row.respond_to?(:owner_type) && row.owner_type != @model_class.name
+      return false if row.respond_to?(:owner_model_name) && row.owner_model_name != @model_class.name
+      if @request_tenant_id
+        return false unless row.respond_to?(:tenant_id) && row.tenant_id == @request_tenant_id
+      end
+      if @vector_store.respond_to?(:contract_version) && @vector_store.contract_version >= 2
+        return false unless row.respond_to?(:owner_type) && row.respond_to?(:owner_id) && row.respond_to?(:owner_model_name)
+        if row.owner
+          return false unless row.owner.is_a?(@model_class)
+          return false unless row.owner.respond_to?(:id) && row.owner.id.to_s == row.owner_id.to_s
+        end
+      end
+
+      true
+    end
+
+    def inferred_source_type(source)
+      value = source.to_s
+      return :attachment if value.include?("[blob:")
+      return :rich_text if value.start_with?("rich_text.")
+      return :related_record if value.start_with?("related:")
+      return :related_record if value.include?("[") || value.include?(".")
+      return :snapshot if value == "snapshot"
+
+      :attribute
+    end
   end
 end

data/lib/maglev/router.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Maglev
+  class Router
+    ROUTES = %i[structured rag hybrid unsupported clarification_required].freeze
+    MAX_RESOURCES = 12
+    MAX_ITEMS = 40
+    MAX_DESCRIPTION_CHARACTERS = 500
+
+    Decision = Struct.new(:route, :confidence, :reasons, :resources) do
+      def initialize(**attributes)
+        attributes[:route] = attributes.fetch(:route).to_sym
+        attributes[:confidence] = Float(attributes.fetch(:confidence))
+        attributes[:reasons] = Array(attributes.fetch(:reasons)).map { |reason| reason.to_s.freeze }.freeze
+        attributes[:resources] = Array(attributes.fetch(:resources)).map { |resource| resource.to_s.freeze }.freeze
+        super
+        freeze
+      end
+    end
+
+    def initialize(classifier:)
+      @classifier = classifier
+    end
+
+    def route(request)
+      raise ArgumentError, "a Maglev::Request is required" unless request.is_a?(Request)
+
+      return decision(route: request.mode, confidence: 1.0, reasons: ["explicit_mode"], request: request) unless request.mode == :auto
+
+      unless @classifier&.respond_to?(:classify)
+        raise ConfigurationError, "routing adapter is not configured"
+      end
+
+      output = @classifier.classify(question: request.question, capabilities: capability_summaries(request))
+      raise PermanentProviderError, "Routing provider returned invalid output" unless output.is_a?(Hash)
+
+      route = output["route"]&.to_sym
+      confidence = output["confidence"]
+      reasons = output["reasons"]
+      unless ROUTES.include?(route) && confidence.is_a?(Numeric) && (0.0..1.0).cover?(confidence) &&
+          reasons.is_a?(Array) && reasons.all? { |reason| reason.is_a?(String) }
+        raise PermanentProviderError, "Routing provider returned invalid output"
+      end
+
+      decision(route: route, confidence: confidence, reasons: reasons, request: request)
+    end
+
+    private
+
+    def decision(route:, confidence:, reasons:, request:)
+      Decision.new(route: route, confidence: confidence, reasons: reasons, resources: request.resources)
+    end
+
+    def capability_summaries(request)
+      request.resources.first(MAX_RESOURCES).filter_map do |identifier|
+        entry = Registry.fetch(identifier)
+        next unless entry
+
+        queryable = entry.queryable
+        knowledge = entry.knowledge
+        sources = if knowledge
+          knowledge.exposed_attributes + knowledge.attached_sources.map(&:name) + knowledge.rich_text_sources.map(&:name)
+        else
+          []
+        end
+        {
+          identifier: entry.identifier,
+          description: entry.description.to_s.each_char.first(MAX_DESCRIPTION_CHARACTERS).join,
+          structured: !queryable.nil?,
+          rag: !knowledge.nil?,
+          fields: Array(queryable&.fields).map(&:name).first(MAX_ITEMS).freeze,
+          sources: sources.uniq.first(MAX_ITEMS).freeze
+        }.freeze
+      end.freeze
+    end
+  end
+end

data/lib/maglev/routing_adapter.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Maglev
+  class RoutingAdapter
+    def classify(question:, capabilities:)
+      raise NotImplementedError, "#{self.class.name} must implement #classify"
+    end
+  end
+
+  class FakeRoutingAdapter < RoutingAdapter
+    attr_reader :requests
+
+    def initialize(outputs)
+      @outputs = Array(outputs).dup
+      @requests = []
+    end
+
+    def classify(**request)
+      @requests << request.freeze
+      raise PermanentProviderError, "Fake router has no remaining output" if @outputs.empty?
+
+      @outputs.shift
+    end
+  end
+end

data/lib/maglev/schema_compiler.rb

@@ -2,13 +2,14 @@
 
 require_relative "configuration"
 require_relative "errors"
+require_relative "relation_order"
 
 module Maglev
   class SchemaCompiler
     SUPPORTED_MACROS = %i[belongs_to has_one has_many].freeze
 
     CompiledSchema = Struct.new(:model_class, :relations)
-    CompiledRelation = Struct.new(:name, :depth, :limit, :inverse, :macro, :related_class)
+    CompiledRelation = Struct.new(:name, :depth, :limit, :inverse, :macro, :related_class, :order)
 
     def initialize(config, max_depth: Maglev.configuration.max_relation_depth)
       @config = config
@@ -16,7 +17,7 @@ module Maglev
     end
 
     def compile
-      CompiledSchema.new(@config.model_class, @config.relations.map { |relation| compile_relation(relation) }.freeze)
+      CompiledSchema.new(@config.model_class, @config.relations.map { |relation| compile_relation(relation) }.freeze).freeze
     end
 
     private
@@ -37,7 +38,7 @@ module Maglev
 
       related_class = reflection.klass
       unless related_class.respond_to?(:maglev_config) && related_class.maglev_config
-        raise ConfigurationError, "Related Maglev model #{related_class.name} must declare has_knowledge"
+        raise ConfigurationError, "Related Maglev model #{related_class.name} must declare maglev_resource knowledge"
       end
 
       inverse = relation.inverse || reflection.inverse_of&.name&.to_s
@@ -45,7 +46,19 @@ module Maglev
         raise ConfigurationError, "Maglev association #{@config.model_class.name}.#{relation.name} requires an inverse for invalidation"
       end
 
-      CompiledRelation.new(relation.name, relation.depth, relation.limit, inverse, reflection.macro, related_class)
+      order = compiled_order(relation.order, related_class)
+      CompiledRelation.new(relation.name, relation.depth, relation.limit, inverse, reflection.macro, related_class, order).freeze
+    end
+
+    def compiled_order(order, related_class)
+      return nil unless order
+
+      unknown = order.keys.map(&:to_s) - related_class.attribute_names.map(&:to_s)
+      if unknown.any?
+        raise ConfigurationError, "Unknown Maglev relation order attributes for #{related_class.name}: #{unknown.join(", ")}"
+      end
+
+      RelationOrder.with_primary_key(order, related_class)
     end
   end
 end

data/lib/maglev/schema_snapshot.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "errors"
+
+module Maglev
+  class SchemaSnapshot
+    DEFAULT_LIMITS = {resources: 12, fields: 40, associations: 20, bytes: 32_768}.freeze
+
+    Field = Struct.new(:name, :type, :null, :enum_values, :description, :synonyms) do
+      def initialize(**attributes)
+        attributes[:enum_values] = Array(attributes[:enum_values]).freeze
+        attributes[:synonyms] = Array(attributes[:synonyms]).freeze
+        super
+        freeze
+      end
+
+      def to_h
+        {name: name, type: type, null: null, enum_values: enum_values, description: description, synonyms: synonyms}.freeze
+      end
+    end
+
+    Association = Struct.new(:name, :resource, :macro, :polymorphic, :description, :synonyms) do
+      def initialize(**attributes)
+        attributes[:synonyms] = Array(attributes[:synonyms]).freeze
+        super
+        freeze
+      end
+
+      def to_h
+        {name: name, resource: resource, macro: macro, polymorphic: polymorphic, description: description, synonyms: synonyms}.freeze
+      end
+    end
+
+    Resource = Struct.new(:identifier, :description, :synonyms, :table_name, :primary_key, :sti_base, :inheritance_column,
+      :fields, :associations, :scopes, :aggregates, :limits, :allow_unscoped_model_queries) do
+      def initialize(**attributes)
+        attributes[:synonyms] = Array(attributes[:synonyms]).freeze
+        attributes[:fields] = attributes.fetch(:fields).freeze
+        attributes[:associations] = attributes.fetch(:associations).freeze
+        attributes[:scopes] = attributes.fetch(:scopes).freeze
+        attributes[:aggregates] = attributes.fetch(:aggregates).freeze
+        attributes[:limits] = attributes.fetch(:limits).freeze
+        super
+        freeze
+      end
+
+      def to_h
+        {
+          identifier: identifier, description: description, synonyms: synonyms, table_name: table_name,
+          primary_key: primary_key, sti_base: sti_base, inheritance_column: inheritance_column,
+          fields: fields.map(&:to_h).freeze, associations: associations.map(&:to_h).freeze,
+          scopes: scopes, aggregates: aggregates, limits: limits,
+          allow_unscoped_model_queries: allow_unscoped_model_queries
+        }.freeze
+      end
+    end
+
+    attr_reader :resources, :paths
+
+    def initialize(resources:, paths:, model_classes: {})
+      @resources = resources.freeze
+      @paths = paths.freeze
+      @model_classes = model_classes.freeze
+      @hash = {version: 1, resources: @resources.map(&:to_h).freeze, paths: @paths}.freeze
+      freeze
+    end
+
+    def to_h
+      @hash
+    end
+
+    def to_json(*arguments)
+      @hash.to_json(*arguments)
+    end
+
+    def model_class_for(identifier)
+      @model_classes[identifier.to_s]
+    end
+
+    class Builder
+      def initialize(entries, limits: {})
+        requested = limits.transform_keys(&:to_sym)
+        unknown = requested.keys - DEFAULT_LIMITS.keys
+        valid = requested.all? do |key, value|
+          value.is_a?(Integer) && ((key == :bytes) ? value.positive? : value >= 0)
+        end
+        raise ConfigurationError, "invalid schema snapshot limits" if unknown.any? || !valid
+
+        @limits = DEFAULT_LIMITS.merge(requested) { |_key, global, request| [global, request].min }.freeze
+        @entries = entries.sort_by(&:identifier).first(@limits.fetch(:resources)).freeze
+        @entry_by_identifier = @entries.to_h { |entry| [entry.identifier, entry] }.freeze
+        @resource_identifiers = @entries.map(&:identifier).to_h { |identifier| [identifier, true] }.freeze
+        @resource_for_model = @entries.to_h { |entry| [entry.model_class.name, entry.identifier] }.freeze
+      end
+
+      def build
+        resources = @entries.map { |entry| resource_for(entry) }
+        snapshot = SchemaSnapshot.new(
+          resources: resources,
+          paths: paths_for(resources),
+          model_classes: @entries.to_h { |entry| [entry.identifier, entry.model_class] }
+        )
+        if snapshot.to_json.bytesize > @limits.fetch(:bytes)
+          raise ConfigurationError, "schema snapshot exceeds #{@limits.fetch(:bytes)} bytes"
+        end
+        snapshot
+      end
+
+      private
+
+      def resource_for(entry)
+        model = entry.model_class
+        queryable = entry.queryable
+        fields = queryable.fields.reject(&:sensitive).sort_by(&:name).first(@limits.fetch(:fields)).map do |declaration|
+          column = model.columns_hash.fetch(declaration.name)
+          enum_values = declaration.enum_values.empty? ? model.defined_enums.fetch(declaration.name, {}).keys.sort : declaration.enum_values
+          Field.new(name: declaration.name, type: column.type, null: column.null, enum_values: enum_values,
+            description: declaration.description, synonyms: declaration.synonyms)
+        end
+        associations = queryable.associations.select { |declaration| @resource_identifiers.key?(declaration.resource) }
+          .sort_by(&:name).first(@limits.fetch(:associations)).map do |declaration|
+          reflection = model.reflect_on_association(declaration.name.to_sym)
+          target = @entry_by_identifier.fetch(declaration.resource)
+          unless reflection.polymorphic? || reflection.klass.base_class == target.model_class.base_class
+            raise ConfigurationError,
+              "Association #{model.name}.#{declaration.name} does not match resource #{declaration.resource}"
+          end
+          Association.new(name: declaration.name, resource: declaration.resource, macro: reflection.macro,
+            polymorphic: !!reflection.polymorphic?, description: declaration.description, synonyms: declaration.synonyms)
+        end
+        Resource.new(identifier: entry.identifier, description: entry.description, synonyms: entry.synonyms,
+          table_name: model.table_name, primary_key: model.primary_key, sti_base: @resource_for_model[model.base_class.name],
+          inheritance_column: model.inheritance_column, fields: fields, associations: associations,
+          scopes: queryable.scopes.map { |scope| scope_to_h(scope) }.freeze, aggregates: queryable.aggregates,
+          limits: queryable.limits, allow_unscoped_model_queries: queryable.allow_unscoped_model_queries)
+      end
+
+      def scope_to_h(scope)
+        {name: scope.name, description: scope.description, parameters: scope.parameters.transform_values do |parameter|
+          {type: parameter.type, required: parameter.required, nullable: parameter.nullable,
+           enum_values: parameter.enum_values, minimum: parameter.minimum, maximum: parameter.maximum}.freeze
+        end.freeze}.freeze
+      end
+
+      def paths_for(resources)
+        by_identifier = resources.to_h { |resource| [resource.identifier, resource] }
+        resources.flat_map do |resource|
+          resource.associations.flat_map do |association|
+            first = "#{resource.identifier}.#{association.name}"
+            nested = by_identifier[association.resource]&.associations&.map { |child| "#{first}.#{child.name}" } || []
+            [first, *nested]
+          end
+        end.sort.freeze
+      end
+    end
+  end
+end