activerecord-materialized 0.1.1 → 0.2.0

data/lib/activerecord/materialized/module_api.rb

@@ -1,4 +1,3 @@
-# typed: strict
 # frozen_string_literal: true
 
 module ActiveRecord
@@ -13,19 +12,16 @@ module ActiveRecord
   # @see Materialized::Configuration the configurable settings
   module Materialized
     class << self
-      extend T::Sig
-
-      @configuration = T.let(nil, T.nilable(Configuration))
+      @configuration = nil
 
       # The global configuration object. Prefer {configure} for setting values.
       #
       # @return [Configuration] the current configuration (created on first use)
-      sig { returns(Configuration) }
       def configuration
         config = @configuration
         if config.nil?
           config = Configuration.new
-          @configuration = T.let(config, T.nilable(Configuration))
+          @configuration = config
         end
         config
       end
@@ -41,20 +37,13 @@ module ActiveRecord
       #
       # @yieldparam config [Configuration]
       # @return [void]
-      sig { params(block: T.proc.params(config: Configuration).void).void }
       def configure(&block)
         yield(configuration)
       end
 
-      sig { returns(String) }
-      def metadata_table_name
-        configuration.metadata_table_name
-      end
+      def metadata_table_name = configuration.metadata_table_name
 
-      sig { returns(String) }
-      def partition_table_name
-        configuration.partition_table_name
-      end
+      def partition_table_name = configuration.partition_table_name
 
       # Verifies every registered view's cache table still matches the columns its
       # source relation projects — run it at boot or in CI to catch a view whose
@@ -62,21 +51,229 @@ module ActiveRecord
       #
       # @raise [SchemaVerifier::SchemaDriftError] on the first drifted view
       # @return [void]
-      sig { void }
       def verify_schema!
         registered = Registry.all
         registered.each { |view_class| SchemaVerifier.new(view_class).verify! }
       end
 
-      sig { returns(T::Boolean) }
-      def atomic_swap_refresh?
-        configuration.atomic_swap_refresh
+      # Checks every registered view's materialized *contents* against its source
+      # relation and returns a {DataVerificationResult} per view (never raises on
+      # drift), so callers can alert on or repair the divergent partition keys.
+      #
+      # @param mode [Symbol] +:row_count+, +:checksum+, or +:full+
+      # @param sample [Numeric, nil] verify a random subset (Integer count / Float fraction)
+      # @return [Array<DataVerificationResult>]
+      def verify_data(mode: :checksum, sample: nil)
+        Registry.all.map { |view_class| DataVerifier.new(view_class, mode: mode, sample: sample).verify }
+      end
+
+      # Like {verify_data} but raises {DataVerifier::DataDriftError} if any view has
+      # drifted — for a boot/CI/cron gate. Returns the results when all are clean.
+      #
+      # @raise [DataVerifier::DataDriftError] listing the drifted views
+      # @return [Array<DataVerificationResult>]
+      def verify_data!(mode: :checksum, sample: nil)
+        results = verify_data(mode: mode, sample: sample)
+        drifted = results.select(&:drifted?)
+        return results if drifted.empty?
+
+        raise DataVerifier::DataDriftError, data_drift_message(drifted)
+      end
+
+      # Reconciles every registered view — verifies its contents against the source and
+      # repairs any drift with scoped maintenance (never a full rebuild), returning a
+      # {ReconcileResult} per view. See {Reconciler}.
+      #
+      # @param mode [Symbol] drift-check depth: +:row_count+, +:checksum+, or +:full+
+      # @param sample [Numeric, nil] verify a random subset (Integer count / Float fraction)
+      # @return [Array<ReconcileResult>]
+      def reconcile!(mode: :checksum, sample: nil)
+        Registry.reconcile_all!(mode: mode, sample: sample)
+      end
+
+      # Like {reconcile!} but only for stale views — dirty, never refreshed, or past
+      # +max_staleness+ — the scheduled bounded-staleness backstop (fresh views are
+      # skipped). Drive it from cron or ActiveJob.
+      #
+      # @param mode [Symbol] drift-check depth: +:row_count+, +:checksum+, or +:full+
+      # @param sample [Numeric, nil] verify a random subset (Integer count / Float fraction)
+      # @return [Array<ReconcileResult>] one per reconciled (stale) view
+      def reconcile_stale!(mode: :checksum, sample: nil)
+        Registry.reconcile_stale!(mode: mode, sample: sample)
       end
 
-      sig { params(value: Configuration).void }
-      def configuration=(value)
-        @configuration = T.let(value, T.nilable(Configuration))
+      # Fans the periodic reconcile backstop across an ActiveJob fleet: enqueues one
+      # {ReconcileJob} per stale, materialized view so many workers share the (expensive) drift
+      # verification instead of one process running it serially. Run it from a SINGLE owner —
+      # a leader, a dedicated instance, or one recurring job — never as cron on every server (see
+      # the distributed-deployment guide). Requires ActiveJob; without it, use {reconcile_stale!}.
+      #
+      # @param mode [Symbol] drift-check depth passed to each job (+:row_count+/+:checksum+/+:full+)
+      # @param sample [Numeric, nil] verify a random subset (Integer count / Float fraction)
+      # @return [Array<String>] the view keys enqueued
+      def enqueue_stale_reconciles!(mode: :checksum, sample: nil)
+        enqueue_for_each_stale_view(:enqueue_stale_reconciles!) do |view_class|
+          ReconcileJob.perform_later(view_class.view_key, mode: mode, sample: sample)
+        end
+      end
+
+      # The fan-out form of the serial {Registry.refresh_stale!}: enqueues one {RefreshJob} per
+      # stale, materialized view. Same single-owner rule as {enqueue_stale_reconciles!}. Requires ActiveJob.
+      #
+      # @return [Array<String>] the view keys enqueued
+      def enqueue_stale_refreshes!
+        enqueue_for_each_stale_view(:enqueue_stale_refreshes!) do |view_class|
+          RefreshJob.perform_later(view_class.view_key)
+        end
+      end
+
+      # Logged once at boot (see {Railtie}) when ActiveJob is available but the effective dispatcher
+      # is still the in-process refresher — it does not coordinate across processes, so it is a
+      # correctness/efficiency hazard in a multi-process deployment. Silent when dispatching via
+      # ActiveJob, and silent when ActiveJob isn't loaded at all (a genuinely single-process app,
+      # for which the in-process refresher is the right and only choice).
+      #
+      # @param logger [#warn, nil] destination (defaults to the Rails logger)
+      # @return [void]
+      def warn_if_in_process_dispatcher!(logger: default_logger)
+        return unless configuration.active_job_available?
+        return if configuration.refresh_dispatcher == :active_job
+
+        logger&.warn(IN_PROCESS_DISPATCHER_WARNING)
+      end
+
+      # Publishes a committed dependency write from a custom change source (a
+      # CDC/replication stream, a bulk loader, another service). It drives the
+      # externally-fed views (`change_source :none`) that depend on the table;
+      # callback-driven views are left to their own commit callbacks so no view is
+      # maintained twice. To recover a callback-driven view after a callback-skipping
+      # bulk load, use {mark_dirty_for_tables!} instead.
+      #
+      # @param change [WriteChange] the committed write to publish
+      # @return [void]
+      def publish_write_change!(change)
+        DependencyRegistry.publish_write_change!(change)
+      end
+
+      # Coarse ingestion signal for callers that cannot describe the individual
+      # write: enqueues a full recompute for every view depending on any of
+      # +tables+ and schedules it per each view's refresh strategy (inline for
+      # +:immediate+, in the background for +:async+). Idempotent, so it is safe to
+      # call repeatedly and to recover a view after a callback-skipping bulk load.
+      #
+      # @param tables [Array<String>] dependency table names
+      # @return [void]
+      def mark_dirty_for_tables!(tables)
+        DependencyRegistry.mark_dirty_for_tables!(tables)
+      end
+
+      # Ingests a change described as a normalized descriptor — the CDC-friendly
+      # entry point for a consumer that has the table, operation, and (optionally)
+      # the changed key columns or full before/after images as plain data rather
+      # than an ActiveRecord object. Builds a {WriteChange} and publishes it via
+      # {publish_write_change!}, so it drives the externally-fed
+      # (+change_source :none+) views on the table; a callback-driven view is left
+      # to its own callbacks — recover one after a bulk load with
+      # {mark_dirty_for_tables!}.
+      #
+      # Supply +before+/+after+ images when the stream carries them; otherwise
+      # +key_attributes+ scopes maintenance to the affected partition(s). With
+      # neither — or a partial +:update+ image that cannot identify both the old
+      # and new partition — maintenance widens to a full recompute (always correct).
+      # See {WriteChange.from_descriptor}.
+      #
+      # @param table [String] the changed table
+      # @param operation [Symbol] +:create+, +:update+, or +:destroy+
+      # @param key_attributes [Hash, nil] the GROUP BY key columns of the changed row
+      # @param before [Hash, nil] pre-image, for +:update+/+:destroy+
+      # @param after [Hash, nil] post-image, for +:create+/+:update+
+      # @param source_ts [Integer, nil] optional monotonic source watermark (e.g. a Debezium +source.ts_ms+
+      #   or a per-key Kafka offset). When given, an affected partition that already applied a strictly-newer
+      #   value is skipped as provably-stale — an equal value still applies, so a coarse (second-granular)
+      #   timestamp is safe (best-effort, reconcile-backed) — and the view's freshness/lag becomes
+      #   observable via {SourceWatermark}. Ignored for callback-driven and full-recompute writes.
+      # @param images [Hash] the change images/keys — +key_attributes:+, +before:+, +after:+ (forwarded
+      #   to {WriteChange.from_descriptor}, which rejects any unrecognized keyword)
+      # @return [void]
+      def ingest_change(table:, operation:, source_ts: nil, **images)
+        unless source_ts.nil? || source_ts.is_a?(Integer)
+          raise ArgumentError,
+                "source_ts must be an Integer (e.g. a Debezium ts_ms or a Kafka offset); got #{source_ts.class}"
+        end
+
+        change = WriteChange.from_descriptor(table_name: table, operation: operation, **images)
+        change = change.with_source_ts(source_ts) if source_ts
+        publish_write_change!(change)
+      end
+
+      # Relay one Debezium CDC change envelope through {#ingest_change} — mapping +op+ (c/r → create,
+      # u → update, d → destroy), the +before+/+after+ row images, +source.table+, and the envelope's
+      # +source.ts_ms+ as the +source_ts+ watermark for you (a nested
+      # +payload+ is unwrapped). A +nil+ envelope (a Kafka tombstone) is a no-op; a non-tombstone with
+      # no +op+, or an unsupported +op+, raises. Pass +table+ to override the target when it differs
+      # from +source.table+. +table+ is positional (not a keyword) so an inline envelope literal is not
+      # misparsed as keyword arguments. See {DebeziumEnvelope} and the CDC section of the README.
+      #
+      # @param envelope [Hash, nil] a decoded Debezium change event value (string or symbol keys)
+      # @param table [String, Symbol, nil] target-table override; defaults to +source.table+
+      # @return [void]
+      # @raise [ArgumentError] on a mis-shaped envelope, an unsupported +op+, or an undeterminable table
+      def ingest_debezium_change(envelope, table = nil)
+        descriptor = DebeziumEnvelope.to_change_descriptor(envelope, table)
+        ingest_change(**descriptor) if descriptor
+      end
+
+      # Relay pending {WriteOutbox} rows (captured by database triggers for out-of-band writes)
+      # through {#ingest_change}, then delete them. The operational entry point run from a poller,
+      # cron, or background job when a table has trigger/outbox capture installed. Returns the number
+      # of rows relayed so a caller can loop until drained. See +docs/out-of-band-writes.md+.
+      #
+      # @param limit [Integer, nil] max rows to relay this pass (nil = all pending)
+      # @return [Integer]
+      def drain_write_outbox!(limit: nil) = WriteOutbox.drain!(limit: limit)
+
+      def atomic_swap_refresh? = configuration.atomic_swap_refresh
+
+      attr_writer :configuration
+
+      private
+
+      # Enqueues one job per stale, *materialized* view and returns their keys. Cold views read
+      # through and aren't maintained, so a job for one would only no-op every tick — skip them.
+      def enqueue_for_each_stale_view(method_name)
+        require_active_job!(method_name)
+        Registry.stale_views.select(&:materialized?).map do |view_class|
+          yield view_class
+          view_class.view_key
+        end
+      end
+
+      def require_active_job!(method_name)
+        return if configuration.active_job_available?
+
+        raise NotImplementedError,
+              "#{method_name} requires ActiveJob — load it and set config.refresh_dispatcher = " \
+              ":active_job, or run the in-process reconcile_stale! / Registry.refresh_stale! instead."
+      end
+
+      def default_logger
+        Rails.logger if defined?(Rails) && Rails.respond_to?(:logger)
+      end
+
+      def data_drift_message(results)
+        summary = results.map do |result|
+          "#{result.view_name} (#{result.missing_keys.size} missing, " \
+            "#{result.extra_keys.size} extra, #{result.mismatched_keys.size} mismatched)"
+        end
+        "materialized view data drift detected: #{summary.join('; ')}"
       end
     end
+
+    # Guidance logged when the in-process dispatcher is active in a possibly multi-process
+    # deployment. Private — internal wording, not a public contract.
+    IN_PROCESS_DISPATCHER_WARNING =
+      "[activerecord-materialized] refresh_dispatcher is :async: the in-process refresher is " \
+      "single-process-only (queue lost on restart). Use config.refresh_dispatcher = :active_job for multiple servers."
+    private_constant :IN_PROCESS_DISPATCHER_WARNING
   end
 end

data/lib/activerecord/materialized/partition_filter.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Materialized
+    # Restricts a relation to a set of partition key tuples, given the Arel key
+    # attributes already resolved to their tables. Handles single- and multi-column
+    # keys, and matches a NULL key with IS NULL (SQL's `IN (...)` never matches NULL).
+    #
+    # @api private
+    class PartitionFilter
+      def initialize(attributes, key_tuples)
+        @attributes = attributes
+        @key_tuples = key_tuples
+      end
+
+      def apply(scope)
+        @attributes.size > 1 ? multi_column(scope) : scope.where(single_column_predicate)
+      end
+
+      private
+
+      # OR in an `IS NULL` when a NULL partition key is requested (a nullable GROUP
+      # BY column's NULL group), which `IN (...)` would otherwise skip.
+      def single_column_predicate
+        attribute = @attributes.fetch(0)
+        values = @key_tuples.map(&:first)
+        present = values.compact
+        in_predicate = attribute.in(present) unless present.empty?
+        return in_predicate unless values.size > present.size
+
+        null_predicate = attribute.eq(nil)
+        in_predicate ? in_predicate.or(null_predicate) : null_predicate
+      end
+
+      def multi_column(scope)
+        @key_tuples.reduce(nil) do |merged_scope, tuple|
+          branch = @attributes.each_with_index.reduce(scope) do |relation, (attribute, index)|
+            relation.where(attribute.eq(tuple[index]))
+          end
+          merged_scope.nil? ? branch : merged_scope.or(branch)
+        end
+      end
+    end
+  end
+end

data/lib/activerecord/materialized/partition_keyed_store.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Materialized
+    # Shared base for the per-partition stores keyed by (view_name, partition_key): {PartitionState}
+    # (the cold-view fresh set) and {SourceWatermark} (the CDC watermark). Centralizes the primitives
+    # they must share — most importantly {#serialize}, which has to be identical across every store, or
+    # a mark and a watermark would key the same partition differently and lookups would silently miss.
+    #
+    # A subclass supplies the three things that differ — its {#record_class}, {#table_name}, and the
+    # table-specific columns via {#define_columns} — and may override {#ensure_columns!} to lazily add
+    # a column introduced after the table was first provisioned.
+    #
+    # @api private
+    class PartitionKeyedStore
+      def initialize(view_class)
+        @view_class = view_class
+      end
+
+      private
+
+      attr_reader :view_class
+
+      # The ActiveRecord model backing this store (e.g. PartitionRecord). Subclasses must override.
+      def record_class
+        raise NotImplementedError, "#{self.class} must define #record_class"
+      end
+
+      # The store's table name. Subclasses must override.
+      def table_name
+        raise NotImplementedError, "#{self.class} must define #table_name"
+      end
+
+      # Add the store's own columns (beyond view_name/partition_key) to the create_table definition.
+      # Subclasses must override.
+      def define_columns(_table)
+        raise NotImplementedError, "#{self.class} must define #define_columns"
+      end
+
+      # Lazily add columns introduced after the table was first provisioned, so an app migrated from an
+      # earlier version picks them up without a new migration. Default: nothing extra to add.
+      def ensure_columns!(_connection); end
+
+      # Serialize a partition-key tuple to its stored form. MUST stay identical across every store, or
+      # two stores would key the same partition differently and their lookups would silently miss.
+      def serialize(key_tuple)
+        key_tuple.map(&:to_s).to_json
+      end
+
+      def view_key
+        view_class.view_key
+      end
+
+      def scope
+        record_class.where(view_name: view_key)
+      end
+
+      def ensure_table!
+        connection = view_class.connection
+        return ensure_columns!(connection) if record_class.table_exists?
+
+        connection.create_table(table_name) do |t|
+          t.string :view_name, null: false
+          t.string :partition_key, null: false
+          define_columns(t)
+        end
+        connection.add_index(table_name, %i[view_name partition_key], unique: true)
+        record_class.reset_column_information
+      end
+    end
+  end
+end

data/lib/activerecord/materialized/partition_record.rb

@@ -1,4 +1,3 @@
-# typed: strict
 # frozen_string_literal: true
 
 module ActiveRecord
@@ -6,22 +5,9 @@ module ActiveRecord
     # One row per fresh partition of a cold view; presence means the partition is
     # materialized and current, absence means it is not.
     class PartitionRecord < ::ActiveRecord::Base
-      extend T::Sig
+      include ConfigurableTableName
 
-      @table_name_override = T.let(nil, T.nilable(String))
-
-      self.table_name = ::ActiveRecord::Materialized.partition_table_name
-
-      sig { params(name: String).void }
-      def self.table_name=(name)
-        @table_name_override = name
-      end
-
-      sig { returns(String) }
-      def self.table_name
-        override = @table_name_override
-        override.nil? ? ::ActiveRecord::Materialized.partition_table_name : override
-      end
+      configurable_table_name { ::ActiveRecord::Materialized.partition_table_name }
     end
   end
 end

data/lib/activerecord/materialized/partition_snapshot.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module ActiveRecord
+  module Materialized
+    # Reads a relation (via ActiveRecord, not raw SQL) into
+    # { group-key tuple => value-signature tally } for {DataVerifier}.
+    #
+    # Both keys and values are cast through the *cache model's* own attribute types,
+    # so the cache and the recomputed source are compared in a single type system —
+    # an integer, string, date, or scaled-decimal column can't masquerade as drift
+    # just because the two sides read it through different type casts. A float
+    # aggregate is additionally canonicalized to a fixed significance, since an
+    # order-dependent SUM/AVG can differ from a re-aggregation in the last bit without
+    # any real drift (see {FLOAT_SIGNIFICANT_DIGITS}).
+    #
+    # Rows are tallied per key, so two cache rows for one partition are detected as a
+    # count difference rather than silently collapsed.
+    #
+    # @api private
+    class PartitionSnapshot
+      SEPARATOR = "\x1f" # ASCII unit separator between digested values
+
+      # Significant digits a float aggregate is rounded to before comparison. A SUM/AVG over a float
+      # column is order-dependent — the DB may re-aggregate base rows in a different order than the
+      # maintained value accumulated, so the two differ in the last bit (0.1+0.2+0.3 => 0.6000000000000001
+      # but 0.3+0.2+0.1 => 0.6). Rounding to a fixed significance absorbs that float noise so it does not
+      # read as data drift, while any real divergence (a missed write moves the value by far more than a
+      # ULP) is still caught. Integer/COUNT and fixed-scale decimal columns already compare exactly after
+      # the type cast, so this only touches floats. ~12 of a double's ~15-16 significant digits leaves a
+      # safe margin for accumulated rounding without masking a meaningful difference.
+      FLOAT_SIGNIFICANT_DIGITS = 12
+
+      def initialize(model, key_columns, value_columns, mode)
+        @model = model
+        @key_columns = key_columns
+        @value_columns = value_columns
+        @mode = mode
+      end
+
+      def of(relation)
+        relation.to_a
+                .group_by { |record| key_tuple(record) }
+                .transform_values { |records| records.map { |record| value_signature(record) }.tally }
+      end
+
+      private
+
+      def key_tuple(record)
+        @key_columns.map { |column| cast(column, record[column]) }
+      end
+
+      def value_signature(record)
+        return nil if @mode == :row_count
+
+        values = @value_columns.map { |column| cast(column, record[column]) }
+        @mode == :checksum ? Digest::MD5.hexdigest(values.map(&:inspect).join(SEPARATOR)) : values
+      end
+
+      # Cast through the cache model's declared type so the cache value and the source recompute (read
+      # through a different type system) normalize identically, then canonicalize a float to a fixed
+      # significance so order-dependent SUM/AVG rounding does not read as drift (see FLOAT_SIGNIFICANT_DIGITS).
+      def cast(column, value)
+        canonicalize_float(@model.type_for_attribute(column).cast(value))
+      end
+
+      # Round a float to FLOAT_SIGNIFICANT_DIGITS significant digits (relative, so it works at any
+      # magnitude); non-floats — integers, fixed-scale decimals, strings — pass through untouched.
+      def canonicalize_float(value)
+        return value unless value.is_a?(Float)
+        return value unless value.finite? && !value.zero?
+
+        magnitude = Math.log10(value.abs).floor
+        value.round(FLOAT_SIGNIFICANT_DIGITS - 1 - magnitude)
+      end
+    end
+  end
+end

data/lib/activerecord/materialized/partition_state.rb

@@ -1,4 +1,3 @@
-# typed: strict
 # frozen_string_literal: true
 
 module ActiveRecord
@@ -6,36 +5,33 @@ module ActiveRecord
     # Tracks which partitions of a cold view have been materialized ("fresh") so
     # a read can decide whether a partition is served from the cache or read
     # through to the source. Warm views are fully materialized and ignore this.
-    class PartitionState
-      extend T::Sig
-
-      KeyTuple = T.type_alias { T::Array[T.untyped] }
-
-      sig { params(view_class: ViewClass).void }
-      def initialize(view_class)
-        @view_class = view_class
-      end
-
-      sig { params(key_tuples: T::Array[KeyTuple]).returns(T::Boolean) }
+    class PartitionState < PartitionKeyedStore
       def all_fresh?(key_tuples)
         return false if key_tuples.empty?
 
         ensure_table!
+        view_class.metadata.ensure_schema! # the epoch subquery reads the metadata table
         serialized = key_tuples.map { |tuple| serialize(tuple) }.uniq
-        scope.where(partition_key: serialized).count == serialized.size
+        # Only marks stamped with the current epoch count as fresh — a mark left behind by a populate
+        # that raced a reset! (a widen invalidation) carries a superseded generation and is ignored.
+        # The epoch is a correlated subquery so this stays ONE round-trip on the keyed cold-read fast path.
+        fresh = scope.where(partition_key: serialized, generation: current_generation_scope)
+        fresh.count == serialized.size
       end
 
-      sig { params(key_tuples: T::Array[KeyTuple]).void }
-      def mark_fresh!(key_tuples)
+      # Stamp each partition fresh with +generation+ (the epoch the caller captured before its source
+      # read). Overwrites any existing mark's generation, so a re-populate after a reset! re-establishes
+      # freshness rather than leaving a stale-epoch row that all_fresh? would forever ignore.
+      def mark_fresh!(key_tuples, generation:)
         return if key_tuples.empty?
 
         ensure_table!
         key_tuples.uniq.each do |tuple|
-          PartitionRecord.create_or_find_by(view_name: view_key, partition_key: serialize(tuple))
+          record = record_class.create_or_find_by(view_name: view_key, partition_key: serialize(tuple))
+          record.update!(generation: generation) unless record.generation == generation
         end
       end
 
-      sig { params(key_tuples: T::Array[KeyTuple]).void }
       def mark_stale!(key_tuples)
         return if key_tuples.empty?
 
@@ -43,15 +39,27 @@ module ActiveRecord
         scope.where(partition_key: key_tuples.map { |tuple| serialize(tuple) }).delete_all
       end
 
-      sig { void }
+      # Invalidate the whole fresh set (a widen recompute whose scope is unknown). Advance the epoch
+      # FIRST, then delete the marks: the epoch bump alone invalidates everything (all_fresh? honours
+      # only current-epoch marks), so the delete is pure cleanup. Ordering it this way makes reset!
+      # crash-safe without a transaction — a crash after the bump but before the delete still leaves the
+      # fresh set invalidated (stale-epoch marks are ignored, and a racing populate that captured the
+      # pre-bump epoch is ignored too); the leftover rows are reclaimed by the next reset!.
       def reset!
         ensure_table!
+        view_class.metadata.bump_fresh_set_generation!
         scope.delete_all
       end
 
+      # The current fresh-set epoch, read into Ruby. A populate captures this BEFORE its source read and
+      # stamps its marks with it, so a widen committing during the read advances the epoch and leaves the
+      # mark un-served. (all_fresh? compares against the epoch in-SQL via current_generation_scope.)
+      def current_generation
+        view_class.metadata.fresh_set_generation
+      end
+
       # The partition key tuples a query touches, or nil unless the conditions are
       # an exact match on the GROUP BY columns (the only case the fast path serves).
-      sig { params(view_class: ViewClass, args: T::Array[T.untyped]).returns(T.nilable(T::Array[KeyTuple])) }
       def self.keys_from(view_class, args)
         conditions = single_hash(args)
         return nil if conditions.nil?
@@ -63,7 +71,6 @@ module ActiveRecord
         value_lists.nil? ? nil : cartesian(value_lists)
       end
 
-      sig { params(args: T::Array[T.untyped]).returns(T.nilable(T::Hash[T.untyped, T.untyped])) }
       def self.single_hash(args)
         return nil unless args.length == 1
 
@@ -71,10 +78,6 @@ module ActiveRecord
         conditions.is_a?(Hash) ? conditions : nil
       end
 
-      sig do
-        params(conditions: T::Hash[T.untyped, T.untyped], group_keys: T::Array[String])
-          .returns(T.nilable(T::Array[T::Array[String]]))
-      end
       def self.key_value_lists(conditions, group_keys)
         normalized = conditions.transform_keys(&:to_s)
         return nil unless normalized.keys.sort == group_keys.sort
@@ -82,7 +85,6 @@ module ActiveRecord
         group_keys.map { |column| Array(normalized.fetch(column)).map(&:to_s) }
       end
 
-      sig { params(value_lists: T::Array[T::Array[String]]).returns(T.nilable(T::Array[KeyTuple])) }
       def self.cartesian(value_lists)
         return nil if value_lists.any?(&:empty?)
 
@@ -93,34 +95,33 @@ module ActiveRecord
 
       private
 
-      sig { returns(String) }
-      def view_key
-        @view_class.view_key
+      def record_class
+        PartitionRecord
       end
 
-      sig { params(key_tuple: KeyTuple).returns(String) }
-      def serialize(key_tuple)
-        key_tuple.map(&:to_s).to_json
+      def table_name
+        ::ActiveRecord::Materialized.partition_table_name
       end
 
-      sig { returns(::ActiveRecord::Relation) }
-      def scope
-        PartitionRecord.where(view_name: view_key)
+      def define_columns(table)
+        table.integer :generation, null: false, default: 0
+        table.datetime :created_at, null: false
       end
 
-      sig { void }
-      def ensure_table!
-        connection = @view_class.connection
-        return if PartitionRecord.table_exists?
+      # Lazily add the fresh-set epoch column (#120) to a partition table provisioned by an earlier
+      # version, so an app migrated from before this column picks it up without a new migration.
+      def ensure_columns!(connection)
+        return if record_class.column_names.include?("generation")
 
-        table = ::ActiveRecord::Materialized.partition_table_name
-        connection.create_table(table) do |t|
-          t.string :view_name, null: false
-          t.string :partition_key, null: false
-          t.datetime :created_at, null: false
-        end
-        connection.add_index(table, %i[view_name partition_key], unique: true)
-        PartitionRecord.reset_column_information
+        connection.add_column(table_name, :generation, :integer, null: false, default: 0)
+        record_class.reset_column_information
+      end
+
+      # The view's current epoch as a one-column relation, so all_fresh? can filter marks by it in a
+      # single query (generation IN (SELECT ...)). An absent metadata row yields no match — nothing is
+      # fresh — which is correct: partition marks only ever exist once maintenance has created the row.
+      def current_generation_scope
+        MetadataRecord.where(view_name: view_key).select(:fresh_set_generation)
       end
     end
   end