hecks 3.5.0 → 3.7.0

data/lib/hecks/ports/persistence/plugins/era/lineage.rb

@@ -1,6 +1,9 @@
 require_relative "../../../../naming"
 require_relative "../../append_only"
 require_relative "../../../../runtime/registry"
+require_relative "lineage/rules"
+require_relative "lineage/coverage"
+require_relative "lineage/rewrite"
 
 module Hecks
   module Ports
@@ -8,11 +11,17 @@ module Hecks
       # Translates a journal entry written under an old shape into the one
       # the current bluebook declares; replay derives the head from unrewritten history.
       class Lineage
+        include Coverage
+        include Rewrite
+
         # `ancestor_name` is the declared name a rename came from (matches
         # the held bluebook's own aggregate names); `ancestor_storage_name`
         # is its derived, snake_case file/table name. Both are nil unless
         # the edge declares a `was:` name that differs from the aggregate's own.
-        attr_reader :ancestor_name, :ancestor_storage_name
+        def ancestor_name = @rules.ancestor_name
+
+        # @return [String, nil] the snake_case storage name of `ancestor_name`
+        def ancestor_storage_name = @rules.ancestor_storage_name
 
         # Builds the rules of the first declared translation that mentions an aggregate.
         #
@@ -59,24 +68,15 @@ module Hecks
         # @param moves [Array<Bluebook::TranslationMove>] from/to paths across a value object
         # @param converts [Array<Bluebook::TranslationConvert>] moves mapped through a values table
         # @param drops [Array<Symbol>] bare or dotted paths whose data is discarded
-        # @param retypes [Array<Bluebook::TranslationRetype>] type names meaning the same shape
-        # @param computes [Array<Bluebook::TranslationCompute>] SQL-only rules, never applied here
-        # @param rekeys [Array<Bluebook::TranslationRekey>] SQL rewrites; only the first is read
-        # @param backfills [Array<Bluebook::TranslationBackfill>] defaults for a new attribute
-        # @param ancestor_name [String, nil] the aggregate's name before the edge, if renamed
-        # @param ancestor_storage_name [String, nil] snake_case storage name of ancestor_name
-        def initialize(renames, moves = [], converts = [], drops = [], retypes: [], computes: [], rekeys: [],
-                       backfills: [], ancestor_name: nil, ancestor_storage_name: nil)
+        # @param rules [Hash] the optional rule lists, as `Rules` names them: `retypes:`,
+        #   `computes:`, `rekeys:`, `backfills:`, `ancestor_name:` and `ancestor_storage_name:`
+        # @raise [ArgumentError] on a keyword `Rules` does not name
+        def initialize(renames, moves = [], converts = [], drops = [], **rules)
           @renames = renames
           @moves = moves
           @converts = converts
           @drops = drops
-          @retypes = retypes
-          @computes = computes
-          @rekeys = rekeys
-          @backfills = backfills
-          @ancestor_name = ancestor_name
-          @ancestor_storage_name = ancestor_storage_name
+          @rules = Rules.build(**rules)
         end
 
         # Reports whether any rule in this edge is a compute.
@@ -85,7 +85,7 @@ module Hecks
         # one refuses to boot anywhere but Postgres.
         #
         # @return [Boolean] true when the edge declares at least one compute rule
-        def computes? = !@computes.empty?
+        def computes? = !@rules.computes.empty?
 
         # Reports whether this edge rewrites the aggregate's identity.
         #
@@ -93,7 +93,7 @@ module Hecks
         # rather than re-deriving it from `declared` themselves.
         #
         # @return [Boolean] true when the edge declares at least one rekey rule
-        def rekey? = !@rekeys.empty?
+        def rekey? = !@rules.rekeys.empty?
 
         # Returns the SQL expression the edge's first rekey rule declares.
         #
@@ -101,7 +101,7 @@ module Hecks
         # `compute` makes; more than one is a DSL-level decision to arbitrate elsewhere.
         #
         # @return [String, nil] the first rekey rule's SQL; nil when the edge declares no rekey
-        def rekey_sql = @rekeys.first&.sql
+        def rekey_sql = @rules.rekeys.first&.sql
 
         # Rewrites one journal entry's state from the held shape into the current one.
         #
@@ -120,58 +120,10 @@ module Hecks
           # Deep, not shallow: a move or convert reaches into a nested
           # value-object hash, and a shallow dup would quietly mutate
           # the caller's copy of the original entry.
-          state = deep_dup(entry.state)
-          apply_renames(state, @renames)
-          @moves.each { |move| apply_move(state, move) }
-          @converts.each { |convert| apply_convert(state, convert) }
-          @drops.each { |name| apply_drop(state, name) }
-          # Only fills a gap nothing else already filled; dotted-path aware, like apply_drop.
-          @backfills.each { |backfill| apply_backfill(state, backfill) }
+          state = rewrite(deep_dup(entry.state))
           Entry.new(operation: entry.operation, id: entry.id, state: state, mirrors: entry.mirrors)
         end
 
-        # Reports whether some rule accounts for a held path that vanished or changed type.
-        #
-        # A rule covering a whole top-level attribute also covers anything nested
-        # under it; `backfills` only matches a whole name, since a backfill adds an
-        # attribute that is new outright, never a path that existed and moved.
-        #
-        # @param path [String, Symbol] a bare attribute name or a dotted value-object member path
-        # @return [Boolean] true when a rename, move, convert, drop or compute names the path or
-        #   its top-level attribute as its source, or a backfill names the top-level attribute
-        # rubocop:disable-next Metrics/CyclomaticComplexity
-        # rubocop:disable-next Metrics/PerceivedComplexity
-        def explains?(path)
-          path = path.to_s
-          top = path.split(".").first
-
-          @renames.key?(top.to_sym) ||
-            @moves.any? { |move| move.from == path || move.from.split(".").first == top } ||
-            @converts.any? { |convert| convert.from == path || convert.from.split(".").first == top } ||
-            @drops.any? { |drop| drop.to_s == path || drop.to_s.split(".").first == top } ||
-            @computes.any? { |compute| compute.from == path || compute.from.split(".").first == top } ||
-            @backfills.any? { |backfill| backfill.name.to_s == top }
-        end
-
-        # Reports whether some rule gives an existing record a value at a new attribute.
-        #
-        # The destination-side twin of `explains?`, which checks a rule's source; this checks
-        # `@renames.value?` too, since a bare rename fills the destination unconditionally,
-        # the same way a backfill would.
-        #
-        # @param path [String, Symbol] the name of a top-level attribute new in the current shape
-        # @return [Boolean] true when a rename, move, convert or compute lands a value in that
-        #   attribute, or a backfill names it
-        def fills?(path)
-          path = path.to_s
-
-          @renames.value?(path.to_sym) ||
-            @moves.any? { |move| move.to.split(".").first == path } ||
-            @converts.any? { |convert| convert.to.split(".").first == path } ||
-            @computes.any? { |compute| compute.to.split(".").first == path } ||
-            @backfills.any? { |backfill| backfill.name.to_s == path }
-        end
-
         # Reports whether a declared retype pairs two type names as the same shape.
         #
         # Nothing in the stored data carries a type name, so this never moves a value;
@@ -181,119 +133,7 @@ module Hecks
         # @param current_type [String, Bluebook::Reference] the type declared now
         # @return [Boolean] true when some retype rule runs from `held_type` to `current_type`
         def retype?(held_type, current_type)
-          @retypes.any? { |retype| retype.from == held_type.to_s && retype.to == current_type.to_s }
-        end
-
-        private
-
-        def deep_dup(node)
-          case node
-          when Hash then node.transform_values { |value| deep_dup(value) }
-          when Array then node.map { |item| deep_dup(item) }
-          else node
-          end
-        end
-
-        # Snapshots every rename's old key/value before writing any new key, so a
-        # swap (:a<->:b) applies as one permutation instead of losing data when one
-        # rule's destination is another's source.
-        def apply_renames(state, renames)
-          snapshot = renames.filter_map { |old_name, new_name| [old_name, new_name, state[old_name]] if state.key?(old_name) }
-          snapshot.each { |old_name, _new_name, _value| state.delete(old_name) }
-          # Not combinable: every delete must finish before any write, or a swap's
-          # first write becomes its second delete target.
-          snapshot.each { |_old_name, new_name, value| state[new_name] = value }
-        end
-
-        def apply_drop(state, name)
-          name = name.to_s
-          top, member = name.split(".", 2)
-          top = top.to_sym
-
-          if member
-            nested = state[top]
-            if nested.is_a?(Hash)
-              nested.delete(member)
-              state.delete(top) if nested.empty?
-            end
-          else
-            state.delete(top)
-          end
-        end
-
-        # Dotted-path aware; must stay in step with `hecks_tr_insert` in rule_compiler.rb.
-        def apply_backfill(state, backfill)
-          name = backfill.name.to_s
-          top, member = name.split(".", 2)
-          top = top.to_sym
-
-          if member
-            nested = (state[top] ||= {})
-            nested[member] = backfill.default unless nested.key?(member)
-          else
-            state[top] = backfill.default unless state.key?(top)
-          end
-        end
-
-        # Runs on raw rows, before the state codec decodes anything — decode is
-        # always the last step, so this never sees an adapter's deep-symbolized entry.
-        def apply_move(state, move)
-          old_top, old_member = move.from.split(".", 2)
-          new_top, new_member = move.to.split(".", 2)
-          old_top = old_top.to_sym
-
-          value, present = extract(state, old_top, old_member)
-          return unless present
-
-          insert(state, new_top.to_sym, new_member, value, rule: "move #{move.from} to: #{move.to}")
-        end
-
-        # A convert is a move whose value has nothing in common with its replacement.
-        # A value missing from the lookup table refuses loudly rather than carry an
-        # unrecognized value silently into the new era.
-        def apply_convert(state, convert)
-          old_top, old_member = convert.from.split(".", 2)
-          new_top, new_member = convert.to.split(".", 2)
-          old_top = old_top.to_sym
-
-          raw, present = extract(state, old_top, old_member)
-          return unless present
-
-          unless convert.values.key?(raw)
-            raise Runtime::WiringError,
-                  "cannot translate #{convert.from}: #{raw.inspect} has no mapping in its " \
-                  "convert's values: table. Add #{raw.inspect} => ... to cover it."
-          end
-
-          insert(state, new_top.to_sym, new_member, convert.values[raw], rule: "convert #{convert.from} to: #{convert.to}")
-        end
-
-        def extract(state, top, member)
-          return [nil, false] unless state.key?(top)
-          return [state.delete(top), true] unless member
-
-          nested = state[top]
-          return [nil, false] unless nested.is_a?(Hash) && nested.key?(member)
-
-          value = nested.delete(member)
-          state.delete(top) if nested.empty?
-          [value, true]
-        end
-
-        # A destination already holding a non-Hash value (e.g. a bare reference id)
-        # must not be silently nested under — that would be an undeclared drop. The
-        # SQL half (`hecks_tr_insert`) refuses with identical wording.
-        def insert(state, top, member, value, rule:)
-          return state[top] = value unless member
-
-          if state.key?(top) && !state[top].is_a?(Hash)
-            raise Runtime::WiringError,
-                  "cannot #{rule}: #{top} already holds #{state[top].inspect}, not a value this can nest " \
-                  "under — moving into it would discard that value silently. Rename or drop #{top} first."
-          end
-
-          state[top] ||= {}
-          state[top][member] = value
+          @rules.retypes.any? { |retype| retype.from == held_type.to_s && retype.to == current_type.to_s }
         end
       end
     end

data/lib/hecks/ports/persistence/plugins/era/postgres_era/boot.rb

@@ -0,0 +1,41 @@
+module Hecks
+  module Adapters
+    class PostgresEra
+      # The steps `PostgresEra#initialize` runs after joining the shared connection: naming the
+      # journal, resolving the era, and provisioning every table the adapter reads or writes.
+      module Boot
+        private
+
+        # Journal name: the owning bluebook's declared name, matching the key rust/host derives its
+        # advisory lock from (ADR 0036). A bare aggregate with no owner falls back to its own name.
+        def journal_domain(aggregate, settings)
+          self.class.setting(
+            settings, :domain, default: aggregate.hecks_owner&.name || aggregate.storage_name
+          ).to_s
+        end
+
+        # Coalesce instead of `setting` for the era: the factory always passes `era:`, nil until
+        # the boot gate resolves it, and nil can never be a real override.
+        def resolve_era!(settings)
+          @era = settings.key?(:era) ? settings[:era] : settings["era"]
+          @era ||= @lineage.current_era
+          # Non-nil only for a held-but-superseded boot. `append` and `atomic_put` refuse on it
+          # because a superuser walks through the RLS fence.
+          @superseded_by = settings.key?(:superseded_by) ? settings[:superseded_by] : settings["superseded_by"]
+        end
+
+        def provision!
+          # Idempotent self-healing against any boot-ordering surprise.
+          @lineage.ensure_head_snapshot!(table, @era)
+          @lineage.ensure_first_head!(table) if @era == 1
+          # One row-cache table per where-field the aggregate's queries use; `query` consults it
+          # to skip the head reduction.
+          @field_caches = ensure_field_caches!
+          create_event_table!
+          create_saga_table!
+          create_outbox_table!
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/plugins/era/postgres_era/class_methods.rb

@@ -0,0 +1,105 @@
+require_relative "../../../../../runtime/errors"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      # The class-level surface of the adapter: the boot gate's entry point, setting lookup,
+      # and the connection the shared-connection pool opens on its behalf.
+      module ClassMethods
+        # Resolves this boot's era, minting the next one when the shape drifted and a translation
+        # edge covers it. Delegates to `LineageManager.check!`.
+        #
+        # @param settings [Hash{Symbol, String => Object}] persistence settings; needs `database`
+        # @param directory [String, nil] where `HECKS_SCAFFOLD=1` writes a translation edge
+        # @return [Integer, nil] the ordinal of the era this boot minted, or nil when none
+        # @raise [Runtime::WiringError] if the database is unreachable or the mint refuses
+        # @raise [Bluebook::DSL::Malformed] if a held era's text parses under no grammar
+        def era_check!(registry:, bluebook:, current_text:, settings:, directory: nil)
+          LineageManager.check!(
+            registry: registry, bluebook: bluebook, current_text: current_text,
+            settings: settings, directory: directory
+          )
+        end
+
+        # Reads one setting under either its Symbol or String spelling.
+        #
+        # Uses `key?` rather than `||` so a stored `false` is not mistaken for an absent key.
+        #
+        # @return [Object, nil] the stored value, or `default` when neither spelling is present
+        def setting(settings, key, default: nil)
+          return settings[key] if settings.key?(key)
+
+          str_key = key.to_s
+          return settings[str_key] if settings.key?(str_key)
+
+          default
+        end
+
+        # Opens a connection to the declared database, selecting the declared `schema` if any.
+        # The caller owns the connection and closes it.
+        #
+        # @param name [String] the domain or aggregate name, used only in refusal messages
+        # @param settings [Hash{Symbol, String => Object}] `database` is a name or `postgres://` URL
+        # @return [PG::Connection] an open connection
+        # @raise [Runtime::WiringError] if `database` is missing or Postgres refuses a statement
+        def connect_for(name, settings)
+          require_pg!(name)
+          declared = declared_database(name, settings)
+          connection = open_connection(declared)
+          prepare_session!(connection, setting(settings, :schema))
+          connection
+        rescue StandardError => e
+          # PG is only defined once the gem loads, so the clause cannot name it.
+          raise unless defined?(PG::Error) && e.is_a?(PG::Error)
+
+          raise bind_failure(name, declared, e)
+        end
+
+        private
+
+        # Lazy so a domain that never wires PostgresEra does not need the pg gem.
+        def require_pg!(name)
+          require "pg"
+        rescue LoadError
+          raise LoadError, "#{name} binds PostgresEra, which needs the pg gem: add `gem \"pg\"` to the Gemfile"
+        end
+
+        def declared_database(name, settings)
+          declared = setting(settings, :database)
+          return declared unless declared.to_s.empty?
+
+          raise Runtime::WiringError,
+                "#{name} binds PostgresEra, which needs a database connection, " \
+                "but its world declares no \"database\"."
+        end
+
+        def open_connection(declared)
+          return PG.connect(declared) if declared.start_with?("postgres://", "postgresql://")
+
+          PG.connect(dbname: declared)
+        end
+
+        # A declared `schema` means the instance is shared; search_path makes every unqualified
+        # name this adapter and its lineage classes build resolve inside that schema.
+        def prepare_session!(connection, schema)
+          if schema.to_s != ""
+            # Idempotent: the schema may not exist yet on the first boot.
+            connection.exec("CREATE SCHEMA IF NOT EXISTS #{connection.quote_ident(schema)}")
+            connection.exec("SET search_path TO #{connection.quote_ident(schema)}")
+          end
+
+          # Provisioning re-runs CREATE ... IF NOT EXISTS on every boot; silence the notices.
+          # Warnings and above still surface.
+          connection.exec("SET client_min_messages = warning")
+        end
+
+        def bind_failure(name, declared, error)
+          Runtime::WiringError.new(
+            "cannot bind PostgresEra at #{declared} for #{name}: #{error.message.strip} " \
+            "-- to run without a database, set HECKS_ENVIRONMENT=memory (a domain needs an environments/memory overlay)"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/plugins/era/postgres_era/dialect.rb

@@ -0,0 +1,137 @@
+require "json"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      # The SQL dialect `SqlQueryBuilder` compiles declared queries in, plus the two-phase
+      # query path that narrows candidates through the field caches before reading the head view.
+      module Dialect
+        private
+
+        def select_list = "id, state"
+        def from_relation = quoted_head
+        def dialect_name = "PostgresEra"
+        def empty_in_clause = "FALSE"
+
+        def placeholder(binds, value)
+          binds << value
+          "$#{binds.size}"
+        end
+
+        def contains_clause(expression, placeholder)
+          "position(#{placeholder} in #{expression}) > 0"
+        end
+
+        def list_contains_clause(column, member, placeholder)
+          target = member.empty? ? "elem #>> '{}'" : "elem ->> #{text_literal(member)}"
+          elements = "jsonb_array_elements(state #> ARRAY[#{text_literal(column)}]::text[]) AS elem"
+          "EXISTS (SELECT 1 FROM #{elements} WHERE #{target} = #{placeholder})"
+        end
+
+        def plain_column(name) = jsonb_path([name])
+
+        def nested_expression(name, path, member)
+          segments = path.empty? ? [name, (member || "value").to_s] : [name, *path]
+          jsonb_path(segments)
+        end
+
+        def comparable_expression(expression, value)
+          value.is_a?(Numeric) ? "(#{expression})::numeric" : expression
+        end
+
+        def execute_query(sql, binds)
+          @db.exec_params(sql, binds).map { |row| instance(row) }
+        end
+
+        def instance(row)
+          Runtime::Instance.new(aggregate: @aggregate, id: row["id"], state: decode(row["state"]))
+        end
+
+        # Reads every head row after `suffix`, as instances.
+        def head_instances(suffix)
+          @db.exec(%(SELECT id, state FROM #{quoted_head} #{suffix})).map { |row| instance(row) }
+        end
+
+        # Runs after SQL-side era translation, as the last step of every read.
+        def decode(state_json)
+          Ports::Persistence::StateCodec.decode(@aggregate, JSON.parse(state_json))
+        end
+
+        def quote_ident(name) = PG::Connection.quote_ident(name.to_s)
+        def quoted_head = quote_ident(@lineage.head_view(table))
+        def quoted_head_snapshot = quote_ident(@lineage.head_snapshot(table, @era))
+
+        def order_expression(field)
+          expression = query_expression(field)
+          numeric_field?(field) ? "(#{expression})::numeric" : expression
+        end
+
+        # Postgres defaults to NULLS LAST on ASC; place nulls explicitly (first ascending, last
+        # descending) so a declared query answers the same on every adapter.
+        def order_clause(order_by, policy)
+          direction = order_by.direction.to_s.downcase == "desc" ? "DESC" : "ASC"
+          nulls = case policy&.mode.to_s
+                  when "first" then " NULLS FIRST"
+                  when "last" then " NULLS LAST"
+                  else direction == "DESC" ? " NULLS LAST" : " NULLS FIRST"
+                  end
+          "#{order_expression(order_by.field)} #{direction}#{nulls}, id #{direction}"
+        end
+
+        # One shared walk decides numericness at any depth, so a nested path is not ordered as text.
+        def numeric_field?(field)
+          name, *path = field.to_s.split(".")
+          QuerySpecification::FieldPath.numeric?(@aggregate.attribute(name), path) do |type|
+            Runtime::Value.value_object_for(@aggregate, type)
+          end
+        end
+
+        # `ARRAY[...]` of escaped literals, never the '{a,b}' syntax: that form has no escaping, so
+        # a quote in a segment would become live SQL.
+        def jsonb_path(segments)
+          "state #>> ARRAY[#{segments.map { |segment| text_literal(segment) }.join(", ")}]::text[]"
+        end
+
+        def text_literal(text) = "'#{text.to_s.gsub("'", "''")}'"
+
+        # Where-fields of the aggregate's and its entities' queries that a cache table can
+        # represent; order_by-only fields never needed a cache.
+        def ensure_field_caches!
+          cached_where_fields.to_h do |field|
+            [field, @lineage.ensure_field_cache!(table, @era, field, query_expression(field))]
+          end
+        end
+
+        def cached_where_fields
+          fields = declared_queries.flat_map do |q|
+            q.wheres.map do |clause|
+              clause.field.to_s
+            end
+          end
+          fields.uniq.select { |field| cacheable_field?(field) }
+        end
+
+        def declared_queries
+          @aggregate.queries + @aggregate.entities.flat_map(&:queries)
+        end
+
+        # List fields are excluded: a one-value cache row cannot hold `contains` membership.
+        def cacheable_field?(field)
+          name = field.to_s.split(".").first
+          return true if @aggregate.lifecycle&.field.to_s == name
+
+          attribute = @aggregate.attribute(name)
+          !attribute.nil? && !attribute.list?
+        end
+
+        # A clause is cache-served when its field has a cache table and it is not a null comparison,
+        # which `NullPolicy` intercepts before `where_clause`.
+        def cache_eligible?(clause, value)
+          @field_caches.key?(clause.field.to_s) &&
+            QuerySpecification::Common::NullPolicy.sql_predicate(query_expression(clause.field, value: value), clause.op,
+                                                                 value).nil?
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/plugins/era/postgres_era/events.rb

@@ -4,6 +4,18 @@ module Hecks
       # The shared `events` table: every domain's aggregates journal their emitted events
       # into it, keyed by `aggregate` ("domain::AggregateName") and `aggregate_id`.
       module Events
+        # The DDL for the shared `events` table.
+        CREATE_EVENTS_SQL = <<~SQL.freeze
+          CREATE TABLE IF NOT EXISTS events (
+            id           bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+            name         text NOT NULL,
+            aggregate    text NOT NULL,
+            aggregate_id text NOT NULL,
+            payload      jsonb,
+            occurred_at  text
+          )
+        SQL
+
         # Stores one emitted event in the `events` table, shared by every aggregate on this
         # database and schema.
         #
@@ -20,15 +32,7 @@ module Hecks
         #
         # @return [Array<Runtime::Event>] events with symbol-keyed `payload` and `correlation` nil
         def events
-          @db.exec("SELECT * FROM events ORDER BY id").map do |row|
-            Runtime::Event.new(
-              name:        row["name"],
-              aggregate:   row["aggregate"],
-              id:          row["aggregate_id"],
-              payload:     JSON.parse(row["payload"], symbolize_names: true),
-              occurred_at: row["occurred_at"]
-            )
-          end
+          @db.exec("SELECT * FROM events ORDER BY id").map { |row| event_from_row(row) }
         end
 
         # Reads back one record's recorded events, oldest first — pushed down as a `WHERE`
@@ -42,30 +46,23 @@ module Hecks
           @db.exec_params(
             "SELECT * FROM events WHERE aggregate = $1 AND aggregate_id = $2 ORDER BY id",
             [aggregate, id.to_s]
-          ).map do |row|
-            Runtime::Event.new(
-              name:        row["name"],
-              aggregate:   row["aggregate"],
-              id:          row["aggregate_id"],
-              payload:     JSON.parse(row["payload"], symbolize_names: true),
-              occurred_at: row["occurred_at"]
-            )
-          end
+          ).map { |row| event_from_row(row) }
         end
 
         private
 
+        def event_from_row(row)
+          Runtime::Event.new(
+            name:        row["name"],
+            aggregate:   row["aggregate"],
+            id:          row["aggregate_id"],
+            payload:     JSON.parse(row["payload"], symbolize_names: true),
+            occurred_at: row["occurred_at"]
+          )
+        end
+
         def create_event_table!
-          @db.exec(<<~SQL)
-            CREATE TABLE IF NOT EXISTS events (
-              id           bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
-              name         text NOT NULL,
-              aggregate    text NOT NULL,
-              aggregate_id text NOT NULL,
-              payload      jsonb,
-              occurred_at  text
-            )
-          SQL
+          @db.exec(CREATE_EVENTS_SQL)
           # Backs #events_for's per-record lookup (a `corrects` command's history read).
           @db.exec(
             "CREATE INDEX IF NOT EXISTS hecks_events_aggregate_id_idx ON events (aggregate, aggregate_id)"