engram 0.5.0 → 0.6.0

data/lib/engram/persistence.rb

@@ -3,6 +3,8 @@
 module Engram
   # Applies persistence hooks and policy consistently before writing records.
   class Persistence
+    RECORD_METADATA_READER = Engram::Record.instance_method(:metadata)
+
     def initialize(store:, embedder:, before_persist: Engram.config.before_persist,
       persistence_policy: Engram.config.persistence_policy)
       @store = store
@@ -12,28 +14,96 @@ module Engram
     end
 
     def add(record, scope: record.scope)
-      record = prepare(record)
-      if record && record.scope != scope
-        raise Engram::Error, "cannot move memory across scopes"
-      end
-      @store.add(record) if record
+      add_prepared(prepare(record), scope: scope)
     end
 
     def update(scope:, id:, record:)
-      record = prepare(record)
-      @store.update(scope: scope, id: id, record: record) if record
+      update_prepared(scope: scope, id: id, record: prepare(record))
     end
 
-    private
+    # Persists a record already returned by #prepare. These split-phase methods let
+    # orchestrators prepare a complete batch before beginning store mutations.
+    def add_prepared(record, scope: record&.scope)
+      return unless record
+
+      record = canonicalize_provenance!(record)
+      unless Engram::Internal::Scope.record_matches?(record, scope)
+        raise Engram::Error, "cannot move memory across scopes"
+      end
+
+      @store.add(record)
+    end
+
+    def update_prepared(scope:, id:, record:)
+      return unless record
+
+      record = canonicalize_provenance!(record)
+      unless Engram::Internal::Scope.record_matches?(record, scope)
+        raise Engram::Error, "cannot move memory across scopes"
+      end
+
+      @store.update(scope: scope, id: id, record: record)
+    end
 
+    # Applies all write transformations without mutating the store. Input is validated
+    # before callbacks can remove or replace provenance, and final output is validated too.
     def prepare(record)
+      original_provenance = validate_provenance!(record)
       original_content = record.content
       record = @before_persist.call(record) if @before_persist
+      if record
+        transformed_provenance = validate_provenance!(record)
+        validate_provenance_trust!(original_provenance, transformed_provenance) if @before_persist
+      end
       record = @persistence_policy.call(record) if record && @persistence_policy
+      validate_provenance!(record) if record
       if record && record.content != original_content
         record = record.with(embedding: @embedder.embed(record.content))
       end
-      record ? Engram::EmbeddingMetadata.attach(record, embedder: @embedder) : nil
+      record = Engram::EmbeddingMetadata.attach(record, embedder: @embedder) if record
+      validate_provenance!(record) if record
+      record
+    end
+
+    # Authorizes a destructive decision without applying write transformations or content
+    # filtering. Policies may opt into this separate contract with #allow_destructive?.
+    # Malformed provenance always fails closed.
+    def allowed?(record)
+      validate_provenance!(record)
+      return true unless @persistence_policy&.respond_to?(:allow_destructive?)
+
+      authorization = @persistence_policy.allow_destructive?(record)
+      unless authorization.equal?(true) || authorization.equal?(false)
+        raise Engram::Error, "persistence policy allow_destructive? must return true or false"
+      end
+      validate_provenance!(record)
+
+      authorization
+    end
+
+    private
+
+    def canonicalize_provenance!(record)
+      metadata = RECORD_METADATA_READER.bind_call(record)
+      canonical_metadata = Engram::Provenance.canonical_metadata_for_persistence(metadata)
+      return record if canonical_metadata.equal?(metadata)
+
+      record.with(metadata: canonical_metadata)
+    rescue TypeError
+      raise Engram::Error, "persistence requires an Engram::Record"
+    end
+
+    def validate_provenance!(record)
+      metadata = RECORD_METADATA_READER.bind_call(record)
+      Engram::Provenance.canonical_integrity_representation_for_persistence(metadata)
+    rescue TypeError
+      raise Engram::Error, "persistence requires an Engram::Record"
+    end
+
+    def validate_provenance_trust!(original, transformed)
+      return if original == transformed
+
+      raise Engram::Error, "before_persist cannot change provenance trust"
     end
   end
 end

data/lib/engram/persistence_policy.rb

@@ -16,16 +16,26 @@ module Engram
       /\b(?:today|now|this session)\b.*\b(?:fixed|resolved|done|completed|finished)\b/i
     ].freeze
 
-    def initialize(denylist_patterns: [])
+    def initialize(denylist_patterns: [], allow_ungrounded: false)
       @denylist_patterns = denylist_patterns
+      @allow_ungrounded = BasicObject.instance_method(:equal?).bind_call(allow_ungrounded, true)
     end
 
     def call(record)
+      provenance = Engram::Provenance.extract_for_persistence(record.metadata)
+      return nil if provenance&.ungrounded? && !@allow_ungrounded
       return nil if reject?(record.content)
 
       redact(record)
     end
 
+    # Destructive authorization is deliberately independent from write-content filtering and
+    # redaction. Provenance trust still applies, but secret/transient content can always be removed.
+    def allow_destructive?(record)
+      provenance = Engram::Provenance.extract_for_persistence(record.metadata)
+      !provenance&.ungrounded? || @allow_ungrounded
+    end
+
     private
 
     def reject?(content)

data/lib/engram/ports/consolidator.rb

@@ -7,8 +7,13 @@ module Engram
     # dumb pile of embeddings.
     # Implementations: Consolidators::HeuristicConsolidator, Consolidators::LLMConsolidator.
     module Consolidator
-      # Given Array<Record> candidates and a scope, return Array<Decision> (one per
-      # candidate that should result in an action).
+      # Given Array<Record> candidates and a scope, return Array<Decision> (at most one
+      # per candidate occurrence, including NOOP decisions). Each decision must reference
+      # the actual candidate instance from this array, not a copy or replacement. When the
+      # same instance occurs multiple times, it may have no more decisions than occurrences.
+      # Candidates are read-only reconciliation inputs: implementations must not mutate
+      # their state, including nested metadata or embedding values. Decision target IDs
+      # must be plain String or Integer values without singleton behavior or custom state.
       def reconcile_all(candidates:, scope:)
         raise NotImplementedError, "#{self.class} must implement #reconcile_all"
       end

data/lib/engram/ports/extractor.rb

@@ -6,7 +6,7 @@ module Engram
     # Declared now so the differentiator (extract -> consolidate) slots in without
     # reworking the core. Not implemented in v0.1.
     module Extractor
-      # Given conversation messages, return Array<Record> of candidate memories.
+      # Given conversation messages, return an Array whose members are Record or Extraction values.
       def extract(messages:, scope:)
         raise NotImplementedError, "Extractor arrives in v0.2"
       end

data/lib/engram/ports/memory_store.rb

@@ -25,6 +25,17 @@ module Engram
         raise NotImplementedError, "#{self.class} must implement #all"
       end
 
+      # Optional performance capability: return the subset of requested ids that
+      # exists in `scope`, preserving each requested value's representation rather
+      # than returning a store-native cast of it. Return at most one requested
+      # representation for each persisted record when the store accepts aliases.
+      # Callers must fall back
+      # to #all for legacy stores that do not expose this method or leave it
+      # unimplemented, so adding it does not break custom MemoryStore adapters.
+      def existing_ids(scope:, ids:)
+        raise NotImplementedError, "#{self.class} does not implement #existing_ids"
+      end
+
       # Replace the content/embedding of an existing memory. Used by consolidation
       # (UPDATE). Returns the updated Record. Raises Engram::Error when the scoped
       # record does not exist or the replacement would move it to another scope.

data/lib/engram/provenance.rb

@@ -11,6 +11,10 @@ module Engram
     METADATA_KEY = "provenance"
     SCHEMA_VERSION = 1
     ALIGNMENTS = %i[exact normalized inferred ungrounded].freeze
+    # Includes arbitrary extension fields. Keeping this conservative leaves ample
+    # Ruby stack headroom while covering the schema's ordinary nesting.
+    MAX_PROVENANCE_NESTING = 100
+    private_constant :MAX_PROVENANCE_NESTING
 
     class Span
       OFFSET_UNIT = "unicode_codepoint"
@@ -44,6 +48,30 @@ module Engram
       end
     end
 
+    class SourceText
+      attr_reader :source_id, :source_type, :message_index, :role, :text
+
+      def initialize(source_id:, source_type:, message_index:, role:, text:)
+        raise ArgumentError, "source_id is required" if source_id.to_s.strip.empty?
+        raise ArgumentError, "source_type is required" if source_type.to_s.strip.empty?
+        unless message_index.is_a?(Integer) && !message_index.negative?
+          raise ArgumentError, "message_index must be a non-negative integer"
+        end
+        raise ArgumentError, "role is required" if role.to_s.strip.empty?
+        raise ArgumentError, "source text must be a String" unless text.is_a?(String)
+        raise ArgumentError, "source text must be valid UTF-8" unless text.valid_encoding?
+
+        @source_id = source_id.to_s.dup.freeze
+        @source_type = source_type.to_s.dup.freeze
+        @message_index = message_index
+        @role = role.to_s.dup.freeze
+        @text = text.encode(Encoding::UTF_8).freeze
+        freeze
+      rescue EncodingError
+        raise ArgumentError, "source text must be valid UTF-8"
+      end
+    end
+
     class Source
       attr_reader :source_id, :source_type, :message_index, :role, :spans, :alignment
 
@@ -75,6 +103,42 @@ module Engram
         freeze
       end
 
+      def validate_source_text!(source_text)
+        unless source_text.is_a?(SourceText)
+          raise ArgumentError, "source_text must be a Provenance::SourceText"
+        end
+
+        {
+          source_id: source_id,
+          source_type: source_type,
+          message_index: message_index,
+          role: role
+        }.each do |attribute, expected|
+          actual = source_text.public_send(attribute)
+          next if actual == expected
+
+          raise Engram::Error, "provenance #{attribute} does not match source text"
+        end
+
+        source_length = source_text.text.length
+        spans.each_with_index do |span, index|
+          next if span.end_offset <= source_length
+
+          raise Engram::Error,
+            "provenance span #{index} ends at #{span.end_offset} beyond source length #{source_length}"
+        end
+
+        true
+      end
+
+      def supporting_text(source_text)
+        validate_source_text!(source_text)
+
+        spans.map do |span|
+          source_text.text[span.start_offset...span.end_offset].freeze
+        end.freeze
+      end
+
       def ==(other)
         other.is_a?(self.class) && to_h == other.to_h
       end
@@ -158,6 +222,10 @@ module Engram
       }
     end
 
+    def ungrounded?
+      sources.any? { |source| source.alignment == :ungrounded }
+    end
+
     class << self
       def attach(metadata, provenance)
         raise ArgumentError, "provenance must be a Provenance value" unless provenance.is_a?(self)
@@ -166,20 +234,294 @@ module Engram
       end
 
       def extract(metadata)
-        metadata = deep_stringify(metadata || {})
-        return nil unless metadata.is_a?(Hash)
+        extract_for_persistence(metadata)
+      rescue Engram::Error
+        nil
+      end
 
-        reserved = metadata[RESERVED_KEY]
-        return nil unless reserved.is_a?(Hash)
+      # Strict parser used by writers. Ordinary reads intentionally use #extract and
+      # tolerate malformed or future schemas, but an older writer must not silently
+      # persist provenance it cannot validate.
+      def extract_for_persistence(metadata)
+        data = canonical_payload_for_persistence(metadata)
+        data && from_h(data)
+      end
 
-        data = reserved[METADATA_KEY]
-        return nil unless data.is_a?(Hash) && data["version"] == SCHEMA_VERSION
+      # Returns a behavior-free canonical copy of the complete validated payload,
+      # including extension fields which the value object intentionally does not expose.
+      def canonical_payload_for_persistence(metadata)
+        metadata ||= {}
+        return nil unless core_kind_of?(metadata, Hash)
+
+        reserved_values = core_hash_values(metadata, RESERVED_KEY, :_engram)
+        reserved_hashes = reserved_values.select { |value| core_kind_of?(value, Hash) }
+        provenance_values = reserved_hashes
+          .flat_map { |reserved| core_hash_values(reserved, METADATA_KEY, :provenance) }
+        if provenance_values.empty?
+          reject_non_hash_reserved_values!(reserved_values)
+          return nil
+        end
 
+        reserved = provenance_values.reduce({}) do |merged, value|
+          detached = detach_provenance_container(value)
+          Engram::ReservedMetadata.merge(merged, METADATA_KEY => detached)
+        end
+        data = reserved.fetch(METADATA_KEY)
+        unless data.is_a?(Hash)
+          raise Engram::Error, "malformed provenance at _engram.provenance: expected an object"
+        end
+        unless data.key?("version")
+          raise Engram::Error, "malformed provenance at _engram.provenance.version: version is required"
+        end
+        unless data["version"] == SCHEMA_VERSION
+          raise Engram::Error, "unsupported provenance version #{data["version"].inspect}"
+        end
+
+        # Validate the known schema while retaining the already detached extension data.
         from_h(data)
+        reject_non_hash_reserved_values!(reserved_values)
+        data
+      end
+
+      # Replaces validated provenance aliases with the detached payload in a plain
+      # reserved namespace. Unrelated application metadata values remain untouched.
+      def canonical_metadata_for_persistence(metadata)
+        payload = canonical_payload_for_persistence(metadata)
+        return metadata unless payload
+
+        # Copy the core table without rehashing arbitrary application keys, then
+        # remove only the reserved aliases through bound Hash traversal.
+        application_metadata = Hash.instance_method(:transform_values).bind_call(metadata) { |value| value }
+        Hash.instance_method(:delete_if).bind_call(application_metadata) do |key, _value|
+          reserved_key_style(key)
+        end
+        string_reserved = []
+        symbol_reserved = []
+        Engram::Internal::CoreHash.each_pair(metadata) do |key, value|
+          case reserved_key_style(key)
+          when :string then string_reserved << value
+          when :symbol then symbol_reserved << value
+          end
+        end
+
+        reserved = (string_reserved + symbol_reserved).reduce({}) do |merged, value|
+          siblings = {}
+          Engram::Internal::CoreHash.each_pair(value) do |key, nested|
+            siblings[key] = nested unless provenance_key_alias?(key)
+          end
+          Engram::ReservedMetadata.merge(merged, Engram::ReservedMetadata.normalize(siblings))
+        end
+        application_metadata[RESERVED_KEY] = reserved.merge(METADATA_KEY => payload)
+        application_metadata
+      end
+
+      # Represents the complete canonical payload without relying on value #==, #eql?,
+      # or #hash implementations. Explicit structural and scalar tags preserve key,
+      # value, and container roles. Integers remain distinct from Floats, whose packed
+      # IEEE 754 bits preserve distinctions such as negative zero.
+      def canonical_integrity_representation_for_persistence(metadata)
+        data = canonical_payload_for_persistence(metadata)
+        data && provenance_integrity_representation(data)
       end
 
       private
 
+      def reject_non_hash_reserved_values!(reserved_values)
+        return if reserved_values.all? { |value| core_kind_of?(value, Hash) }
+
+        raise Engram::Error, "metadata key #{RESERVED_KEY.inspect} is reserved for Engram embedding metadata"
+      end
+
+      def reserved_key_style(key)
+        key_class = Object.instance_method(:class).bind_call(key)
+        return :symbol if key.equal?(:_engram) && key_class.equal?(Symbol)
+        :string if core_kind_of?(key, String) && String.instance_method(:==).bind_call(key, RESERVED_KEY)
+      rescue TypeError
+        nil
+      end
+
+      def provenance_key_alias?(key)
+        core_key_equal?(key, METADATA_KEY, :provenance)
+      end
+
+      # Finds trusted namespace keys through Hash's implementation rather than any
+      # behavior supplied by a Hash subclass or singleton class.
+      def core_hash_values(hash, string_key, symbol_key)
+        values = []
+        Engram::Internal::CoreHash.each_pair(hash) do |key, value|
+          values << value if core_key_equal?(key, string_key, symbol_key)
+        end
+        values
+      end
+
+      def core_key_equal?(key, string_key, symbol_key)
+        key_class = Object.instance_method(:class).bind_call(key)
+        return key.equal?(symbol_key) if key_class.equal?(Symbol)
+        return false unless core_kind_of?(key, String)
+
+        # Compare the stored String bytes without dispatching subclass #==/#eql?.
+        String.instance_method(:==).bind_call(key, string_key)
+      rescue TypeError
+        false
+      end
+
+      # Detaches the provenance subtree into plain containers and trusted primitive
+      # leaves. Container subclasses retain their stored contents, while Strings are
+      # exposed without subclass behavior and canonicalized to UTF-8. Other metadata
+      # is deliberately left untouched.
+      def detach_provenance_container(value, active = {}.compare_by_identity, depth = 0)
+        if core_kind_of?(value, Hash)
+          with_acyclic_container(value, active) do
+            copy = {}
+            Engram::Internal::CoreHash.each_pair(value) do |key, nested|
+              normalized_key = provenance_key(key)
+              normalized_value = detach_nested_provenance(nested, active, depth)
+              if copy.key?(normalized_key)
+                # Both collision inputs have already passed the same depth bound;
+                # merging them cannot introduce a deeper path than either input.
+                copy.replace(Engram::ReservedMetadata.merge(copy, normalized_key => normalized_value))
+              else
+                copy[normalized_key] = normalized_value
+              end
+            end
+            copy
+          end
+        elsif core_kind_of?(value, Array)
+          with_acyclic_container(value, active) do
+            copy = []
+            Array.instance_method(:each).bind_call(value) do |nested|
+              copy << detach_nested_provenance(nested, active, depth)
+            end
+            copy
+          end
+        else
+          canonical_provenance_scalar(value)
+        end
+      end
+
+      def detach_nested_provenance(value, active, parent_depth)
+        if parent_depth >= MAX_PROVENANCE_NESTING && provenance_container?(value)
+          raise Engram::Error,
+            "malformed provenance at _engram.provenance: nesting exceeds maximum depth of #{MAX_PROVENANCE_NESTING}"
+        end
+
+        detach_provenance_container(value, active, parent_depth + 1)
+      end
+
+      def provenance_container?(value)
+        core_kind_of?(value, Hash) || core_kind_of?(value, Array)
+      end
+
+      def canonical_provenance_scalar(value)
+        value_class = Object.instance_method(:class).bind_call(value)
+        return nil if value_class.equal?(NilClass)
+        return true if value_class.equal?(TrueClass)
+        return false if value_class.equal?(FalseClass)
+        return value if value_class.equal?(Symbol) || value_class.equal?(Integer)
+        if value_class.equal?(Float)
+          unless Float.instance_method(:finite?).bind_call(value)
+            raise Engram::Error, "malformed provenance: scalar values must be JSON-native primitives"
+          end
+
+          return value
+        end
+
+        if core_kind_of?(value, String)
+          # Bound String#to_s exposes a subclass's underlying string as an exact String;
+          # bound #dup then removes any singleton methods from an exact String value.
+          string = String.instance_method(:to_s).bind_call(value)
+          string = canonical_utf8_string(string)
+          unless string
+            raise Engram::Error, "malformed provenance: String values must have valid encoding"
+          end
+
+          return String.instance_method(:dup).bind_call(string)
+        end
+
+        raise Engram::Error, "malformed provenance: scalar values must be JSON-native primitives"
+      rescue TypeError
+        raise Engram::Error, "malformed provenance: scalar values must be JSON-native primitives"
+      end
+
+      def provenance_integrity_representation(value)
+        value_class = Object.instance_method(:class).bind_call(value)
+        if value_class.equal?(Hash)
+          fields = {}
+          Engram::Internal::CoreHash.each_pair(value) do |key, nested|
+            fields[key] = provenance_integrity_representation(nested)
+          end
+          return [:object, fields]
+        end
+        if value_class.equal?(Array)
+          entries = []
+          Array.instance_method(:each).bind_call(value) do |nested|
+            entries << provenance_integrity_representation(nested)
+          end
+          return [:array, entries]
+        end
+        return [:null] if value_class.equal?(NilClass)
+        return [:boolean, true] if value_class.equal?(TrueClass)
+        return [:boolean, false] if value_class.equal?(FalseClass)
+        if value_class.equal?(Integer)
+          return [:integer, Integer.instance_method(:to_s).bind_call(value)]
+        end
+        if value_class.equal?(Float)
+          bits = Array.instance_method(:pack).bind_call([value], "G")
+          return [:float, bits]
+        end
+        return [:symbol, Symbol.instance_method(:to_s).bind_call(value)] if value_class.equal?(Symbol)
+        return [:string, value] if value_class.equal?(String)
+
+        # canonical_payload_for_persistence has already rejected every other type.
+        raise Engram::Error, "malformed provenance: scalar values must be JSON-native primitives"
+      rescue TypeError
+        raise Engram::Error, "malformed provenance: scalar values must be JSON-native primitives"
+      end
+
+      def provenance_key(key)
+        key_class = Object.instance_method(:class).bind_call(key)
+        string = if key_class.equal?(Symbol)
+          Symbol.instance_method(:to_s).bind_call(key)
+        elsif core_kind_of?(key, String)
+          # Bound String#to_s returns the underlying bytes as an exact String without
+          # dispatching subclass behavior; #dup strips exact-String singleton methods.
+          String.instance_method(:to_s).bind_call(key)
+        else
+          raise Engram::Error, "malformed provenance: object keys must be String or Symbol values"
+        end
+        string = canonical_utf8_string(string)
+        unless string
+          raise Engram::Error, "malformed provenance: object keys must have valid encoding"
+        end
+
+        String.instance_method(:dup).bind_call(string)
+      rescue TypeError
+        raise Engram::Error, "malformed provenance: object keys must be String or Symbol values"
+      end
+
+      def canonical_utf8_string(string)
+        return unless String.instance_method(:valid_encoding?).bind_call(string)
+
+        String.instance_method(:encode).bind_call(string, Encoding::UTF_8)
+      rescue EncodingError
+        nil
+      end
+
+      def with_acyclic_container(value, active)
+        raise Engram::Error, "malformed provenance: cyclic containers are unsupported" if active.key?(value)
+
+        active[value] = true
+        yield
+      ensure
+        active.delete(value)
+      end
+
+      def core_kind_of?(value, klass)
+        Object.instance_method(:is_a?).bind_call(value, klass)
+      rescue TypeError
+        false
+      end
+
       def from_h(data)
         sources = provenance_array(data["sources"], "_engram.provenance.sources")
         extractor_data = provenance_hash(data["extractor"], "_engram.provenance.extractor")
@@ -234,24 +576,13 @@ module Engram
 
       def build_provenance_value(path)
         yield
-      rescue ArgumentError, TypeError, KeyError, NoMethodError => error
+      rescue ArgumentError, TypeError, KeyError, NoMethodError, EncodingError => error
         raise Engram::Error, "malformed provenance at #{path}: #{error.message}"
       end
 
       def symbolize_extractor(data)
         {name: data["name"], provider: data["provider"], model: data["model"]}
       end
-
-      def deep_stringify(value)
-        case value
-        when Hash
-          value.each_with_object({}) { |(key, nested), out| out[key.to_s] = deep_stringify(nested) }
-        when Array
-          value.map { |nested| deep_stringify(nested) }
-        else
-          value
-        end
-      end
     end
   end
 end

data/lib/engram/record.rb

@@ -8,6 +8,10 @@ module Engram
   # `kind` is a memory type (fact / preference / instruction / episodic). The legacy
   # `semantic` kind is normalized to `fact` for compatibility with pre-1.0 records.
   class Record
+    STATE_READERS = %i[
+      id content scope embedding kind importance metadata created_at last_accessed_at
+    ].freeze
+
     attr_accessor :id, :last_accessed_at
     attr_reader :content, :embedding, :scope, :kind, :importance, :metadata,
       :created_at
@@ -29,12 +33,15 @@ module Engram
       self.class.new(**to_h.merge(attributes))
     end
 
+    # Return structured supporting-source metadata when this record carries a
+    # provenance schema understood by the installed Engram version.
+    # Legacy, malformed, and future-schema records remain readable and return nil.
+    def provenance
+      Engram::Provenance.extract(metadata)
+    end
+
     def to_h
-      {
-        id: id, content: content, scope: scope, embedding: embedding, kind: kind,
-        importance: importance, metadata: metadata,
-        created_at: created_at, last_accessed_at: last_accessed_at
-      }
+      STATE_READERS.to_h { |reader| [reader, public_send(reader)] }
     end
   end
 end

data/lib/engram/use_cases/grounding_report.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Engram
+  module UseCases
+    # Count records in a scope by their weakest understood source alignment.
+    class GroundingReport
+      ALIGNMENT_RANK = Engram::Provenance::ALIGNMENTS.each_with_index.to_h.freeze
+      private_constant :ALIGNMENT_RANK
+
+      def initialize(store:)
+        @store = store
+      end
+
+      def call(scope:)
+        counts = {
+          exact: 0,
+          normalized: 0,
+          inferred: 0,
+          ungrounded: 0,
+          unattributed: 0,
+          total: 0
+        }
+
+        @store.all(scope: scope).each do |record|
+          provenance = record.provenance
+          alignment = provenance && weakest_alignment(provenance)
+          counts[alignment || :unattributed] += 1
+          counts[:total] += 1
+        end
+
+        counts.freeze
+      end
+
+      private
+
+      def weakest_alignment(provenance)
+        alignments = provenance.sources.map(&:alignment)
+        return unless alignments.all? { |alignment| ALIGNMENT_RANK.key?(alignment) }
+
+        alignments.max_by { |alignment| ALIGNMENT_RANK.fetch(alignment) }
+      end
+    end
+  end
+end