hecks 3.5.0 → 3.6.0

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)"

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

@@ -0,0 +1,62 @@
+require "json"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      # The write path under the domain's lock: one journal row, then the head snapshot and every
+      # field cache brought to the same ordinal inside the same transaction.
+      module HeadWrites
+        private
+
+        def lock_writes!
+          @db.exec_params(
+            "SELECT pg_advisory_xact_lock(hashtext('hecks_ordinal:' || $1))",
+            [@lineage.domain]
+          )
+        end
+
+        def append_and_project!(entry)
+          state_json = entry.state && JSON.generate(Ports::Persistence::StateCodec.encode(@aggregate, entry.state))
+          ordinal = insert_journal_row(entry, state_json)
+          entry.save? ? snapshot_save!(entry, ordinal, state_json) : snapshot_delete!(entry, ordinal)
+          ordinal
+        end
+
+        def insert_journal_row(entry, state_json)
+          @db.exec_params(
+            "INSERT INTO #{@lineage.quoted_journal} (era, aggregate, aggregate_id, operation, state, mirrors) " \
+            "VALUES ($1, $2, $3, $4, $5, $6) RETURNING ordinal",
+            [@era, table, entry.id, entry.operation, state_json,
+             entry.mirrors && JSON.generate(entry.mirrors)]
+          )[0]["ordinal"]
+        end
+
+        def snapshot_save!(entry, ordinal, state_json)
+          @db.exec_params(
+            "INSERT INTO #{quoted_head_snapshot} (id, ordinal, operation, state) VALUES ($1, $2, 'save', $3) " \
+            "ON CONFLICT (id) DO UPDATE SET ordinal = EXCLUDED.ordinal, operation = EXCLUDED.operation, " \
+            "state = EXCLUDED.state WHERE #{quoted_head_snapshot}.ordinal < EXCLUDED.ordinal",
+            [entry.id, ordinal, state_json]
+          )
+          # Same transaction and ordinal, so every cache is exactly as current as the snapshot.
+          @field_caches.each do |field, cache_table|
+            @lineage.upsert_field_cache_row!(cache_table, entry.id, ordinal, state_json, query_expression(field))
+          end
+        end
+
+        # A tombstone row, not a bare DELETE: without one, an ancestor era's saved row would win
+        # the head's DISTINCT ON and the deleted record would read back. The ordinal guard keeps
+        # a stale replayed delete from clobbering a newer save.
+        def snapshot_delete!(entry, ordinal)
+          @db.exec_params(
+            "INSERT INTO #{quoted_head_snapshot} (id, ordinal, operation, state) VALUES ($1, $2, 'delete', NULL) " \
+            "ON CONFLICT (id) DO UPDATE SET ordinal = EXCLUDED.ordinal, operation = EXCLUDED.operation, " \
+            "state = EXCLUDED.state WHERE #{quoted_head_snapshot}.ordinal < EXCLUDED.ordinal",
+            [entry.id, ordinal]
+          )
+          @field_caches.each_value { |cache_table| @lineage.delete_field_cache_row!(cache_table, entry.id) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,128 @@
+require "json"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      # Writing and reading the journal: every append, with the head snapshot and field caches
+      # it keeps current in the same transaction, and the reads of the whole journal.
+      module Journal
+        # Appends one entry to the journal and updates the head snapshot and every field cache,
+        # all in one transaction under the domain's write lock.
+        #
+        # The lock precedes the INSERT because the ordinal comes from `nextval()` inside it. It is
+        # a different key from `mint_era!`'s, so it serializes writes, never a write against a mint.
+        # `project` stays out of it: AppendOnly#recover! already replays it on every boot.
+        #
+        # @param entry [Ports::Persistence::Entry] the save or delete to journal
+        # @return [Ports::Persistence::Entry] the same entry, unchanged
+        # @raise [Runtime::WiringError] if this boot's era has been superseded by a mint
+        # @raise [PG::Error] if Postgres refuses a statement, such as the era fence's RLS
+        def append(entry)
+          refuse_superseded_write!
+          transaction do
+            lock_writes!
+            append_and_project!(entry)
+          end
+          entry
+        end
+
+        # Refuses a write from a checkout whose era a later mint has superseded.
+        # Runs before the transaction so a stale checkout takes no lock; reads stay allowed.
+        #
+        # @return [nil] when this boot's era is current
+        # @raise [Runtime::WiringError] if the boot gate marked this era superseded
+        def refuse_superseded_write!
+          return unless @superseded_by
+
+          raise Runtime::WiringError,
+                "cannot write #{table} for #{@domain}: this checkout booted era #{@era}, which era " \
+                "#{@superseded_by} has superseded — its shape was replaced by a mint, and a write here would " \
+                "land in a partition no newer head reads. Reads still work; pull the current bluebook and " \
+                "reboot to write again."
+        end
+
+        # Saves an entry and reports whether it inserted or replaced, decided under the same lock
+        # that guards the write.
+        #
+        # @param entry [Ports::Persistence::Entry] the save to journal
+        # @param insert_only [Boolean] when true, an id already in the head is left untouched
+        # @return [Symbol] `:inserted`, `:replaced`, or `:conflicted` when `insert_only` hit a
+        #   record
+        # @raise [Runtime::WiringError] if this boot's era has been superseded by a mint
+        # @raise [PG::Error] if Postgres refuses a statement
+        def atomic_put(entry, insert_only: false)
+          refuse_superseded_write!
+          status = nil
+          transaction do
+            lock_writes!
+            status = put_status(head_row?(entry.id), insert_only)
+            append_and_project!(entry) unless status == :conflicted
+          end
+          status
+        end
+
+        # Reads this aggregate's whole journal, every era, in write order. States are decoded but
+        # not translated: an ancestor era's row keeps the shape it was written in.
+        #
+        # @return [Array<Ports::Persistence::Entry>] entries by ascending ordinal
+        def entries
+          @db.exec_params(
+            "SELECT aggregate_id, operation, state, mirrors FROM #{@lineage.quoted_journal} " \
+            "WHERE aggregate = $1 ORDER BY ordinal",
+            [table]
+          ).map { |row| entry_from_row(row) }
+        end
+
+        # Deletes this aggregate's journal rows, refusing when row-level security turns the DELETE
+        # into a silent no-op.
+        #
+        # The journal forces RLS with no DELETE policy, so an ordinary connection matches zero rows
+        # without error; comparing the count before with the DELETE's own count exposes that.
+        # Head snapshots, field caches, `events` and saga rows are left as they are.
+        #
+        # @return [Adapters::PostgresEra] this adapter
+        # @raise [Runtime::WiringError] if the journal held rows and the DELETE removed none
+        def reset!
+          before = @db.exec_params(
+            "SELECT count(*) FROM #{@lineage.quoted_journal} WHERE aggregate = $1", [table]
+          )[0]["count"].to_i
+          result = @db.exec_params("DELETE FROM #{@lineage.quoted_journal} WHERE aggregate = $1", [table])
+          refuse_silent_delete!(before, result)
+          self
+        end
+
+        private
+
+        def head_row?(id)
+          !@db.exec_params("SELECT 1 FROM #{quoted_head} WHERE id = $1 LIMIT 1", [id.to_s]).ntuples.zero?
+        end
+
+        def put_status(exists, insert_only)
+          return :conflicted if insert_only && exists
+
+          exists ? :replaced : :inserted
+        end
+
+        def entry_from_row(row)
+          state = row["state"] && JSON.parse(row["state"])
+          Ports::Persistence::Entry.new(
+            operation: row["operation"] || "save",
+            id:        row["aggregate_id"],
+            state:     Ports::Persistence::StateCodec.decode(@aggregate, state),
+            mirrors:   row["mirrors"] && JSON.parse(row["mirrors"])
+          )
+        end
+
+        def refuse_silent_delete!(before, result)
+          return unless before.positive? && result.cmd_tuples.zero?
+
+          raise Runtime::WiringError,
+                "reset! deleted 0 of #{before} row(s) for #{table} in #{@lineage.quoted_journal} — " \
+                "FORCE ROW LEVEL SECURITY admits no DELETE policy on the journal, so this connection's " \
+                "DELETE silently matched nothing. reset! only works connected as an actual Postgres " \
+                "superuser or a role granted BYPASSRLS, not as the provisioner or an app role."
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+module Hecks
+  module Adapters
+    class PostgresEra
+      class Lineage
+        # The DDL of the lineage tables and the journal, run once per boot, owner only.
+        module BaseSql
+          # The held eras of every domain.
+          ERAS_SQL = <<~SQL.freeze
+            CREATE TABLE IF NOT EXISTS hecks_eras (
+              domain    text NOT NULL,
+              ordinal   int  NOT NULL,
+              hash      text,
+              label     text,
+              held_text text NOT NULL,
+              watermark bigint,
+              PRIMARY KEY (domain, ordinal)
+            )
+          SQL
+
+          # Every frozen text version, archived where an edit cannot reach it.
+          ERA_TEXTS_SQL = <<~SQL.freeze
+            CREATE TABLE IF NOT EXISTS hecks_era_texts (
+              domain      text NOT NULL,
+              ordinal     int  NOT NULL,
+              digest      text NOT NULL,
+              held_text   text NOT NULL,
+              archived_at timestamptz NOT NULL DEFAULT now(),
+              PRIMARY KEY (domain, ordinal, digest)
+            )
+          SQL
+
+          # The Layer-3 approvals of translation edges.
+          APPROVALS_SQL = <<~SQL.freeze
+            CREATE TABLE IF NOT EXISTS hecks_approvals (
+              domain           text NOT NULL,
+              from_label       text NOT NULL,
+              to_label         text NOT NULL,
+              edge_digest      text NOT NULL,
+              reviewed_ordinal bigint NOT NULL,
+              approved_at      timestamptz NOT NULL DEFAULT now()
+            )
+          SQL
+
+          # An owned sequence default, not generated always as identity, which
+          # partitioned tables only support from Postgres 17.
+          JOURNAL_SQL = <<~SQL.freeze
+            CREATE TABLE IF NOT EXISTS %<journal>s (
+              ordinal      bigint NOT NULL DEFAULT nextval('%<sequence>s'),
+              era          int    NOT NULL,
+              aggregate    text   NOT NULL,
+              aggregate_id text   NOT NULL,
+              operation    text   NOT NULL DEFAULT 'save',
+              state        jsonb,
+              mirrors      jsonb
+            ) PARTITION BY LIST (era)
+          SQL
+
+          # One era's partition, built apart from the journal before it is attached.
+          PARTITION_SQL = <<~SQL.freeze
+            CREATE TABLE IF NOT EXISTS %<partition>s (
+              LIKE %<journal>s INCLUDING DEFAULTS
+            )
+          SQL
+
+          # Attaches a built partition to the journal.
+          ATTACH_PARTITION_SQL = <<~SQL.freeze
+            ALTER TABLE %<journal>s
+              ATTACH PARTITION %<partition>s FOR VALUES IN (%<era>s)
+          SQL
+        end
+      end
+    end
+  end
+end