hecks 3.4.2 → 3.6.0

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

@@ -22,79 +22,6 @@ module Hecks
             end
           end
 
-          # Skips the integrity check `eras` runs, so hecks reattest can show the raw row first.
-          def raw_era(ordinal)
-            rows = @db.exec_params(
-              "SELECT held_text, held_digest, hash, held_projection::text FROM hecks_eras WHERE domain = $1 AND ordinal = $2",
-              [@domain, ordinal]
-            )
-            return nil if rows.ntuples.zero?
-
-            { held_text: rows[0]["held_text"], held_digest: rows[0]["held_digest"], hash: rows[0]["hash"],
-              held_projection: rows[0]["held_projection"] }
-          end
-
-          # Resolves drift via an append-only attestation record — never patch the digest.
-          def reattest!(ordinal)
-            era = raw_era(ordinal)
-            raise Runtime::WiringError, "#{@domain} holds no era #{ordinal} to re-attest" unless era
-
-            fresh = Digest::SHA256.hexdigest(era[:held_text])
-            @db.exec(<<~SQL)
-              CREATE TABLE IF NOT EXISTS hecks_attestations (
-                domain      text NOT NULL,
-                ordinal     int  NOT NULL,
-                old_digest  text,
-                new_digest  text NOT NULL,
-                attested_at timestamptz NOT NULL DEFAULT now()
-              )
-            SQL
-            @db.exec_params(
-              "INSERT INTO hecks_attestations (domain, ordinal, old_digest, new_digest) VALUES ($1, $2, $3, $4)",
-              [@domain, ordinal, era[:held_digest], fresh]
-            )
-            @db.exec_params(
-              "UPDATE hecks_eras SET held_digest = $3 WHERE domain = $1 AND ordinal = $2",
-              [@domain, ordinal, fresh]
-            )
-            archive_text!(ordinal, era[:held_text])
-            fresh
-          end
-
-          # A row with no stored digest yet is backfilled, not refused; only a mismatch raises.
-          def verify_integrity!(ordinal, text, stored_digest, stored_projection_json)
-            digest = Digest::SHA256.hexdigest(text)
-            if stored_digest.nil?
-              @db.exec_params(
-                "UPDATE hecks_eras SET held_digest = $3 WHERE domain = $1 AND ordinal = $2 AND held_digest IS NULL",
-                [@domain, ordinal, digest]
-              )
-              backfill_frozen_facts!(ordinal, text, stored_projection_json)
-              return
-            end
-            if stored_digest == digest
-              backfill_frozen_facts!(ordinal, text, stored_projection_json)
-              return
-            end
-
-            raise Runtime::WiringError, Runtime::EraTamper.refusal(domain: @domain, ordinal: ordinal)
-          end
-
-          # Call only on already-verified text; this would bless an unverified edit.
-          def backfill_frozen_facts!(ordinal, text, stored_projection_json)
-            archive_text!(ordinal, text)
-            return if stored_projection_json
-
-            projection = Runtime::EraTamper.project(text)
-            return unless projection
-
-            @db.exec_params(
-              "UPDATE hecks_eras SET held_projection = $3::text::jsonb " \
-              "WHERE domain = $1 AND ordinal = $2 AND held_projection IS NULL",
-              [@domain, ordinal, JSON.generate(projection)]
-            )
-          end
-
           def current_era
             held = eras
             held.empty? ? 1 : held.last[:ordinal]

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

@@ -39,21 +39,7 @@ module Hecks
           # @raise [PG::Error] if Postgres refuses the DDL, a source read, or an upsert
           def ensure_field_cache!(storage_name, era, field, value_expression)
             name = field_cache(storage_name, era, field)
-            unless table_exists?(name)
-              nested_transaction("hecks_field_cache_create") do
-                @db.exec_params("SELECT pg_advisory_xact_lock(hashtext('hecks_field_cache:' || $1))", [name])
-                next if table_exists?(name)
-
-                @db.exec(<<~SQL)
-                  CREATE TABLE #{quote(name)} (
-                    id      text PRIMARY KEY,
-                    ordinal bigint NOT NULL,
-                    value   text
-                  )
-                SQL
-                @db.exec("CREATE INDEX IF NOT EXISTS #{quote("#{name}_value_idx")} ON #{quote(name)} (value)")
-              end
-            end
+            create_field_cache_table!(name) unless table_exists?(name)
             backfill_field_cache!(name, storage_name, era, value_expression)
             name
           end
@@ -70,16 +56,8 @@ module Hecks
           def backfill_field_cache!(name, storage_name, era, value_expression)
             chunked_backfill!(
               name,
-              source_sql: lambda do |cursor|
-                <<~SQL
-                  SELECT id, ordinal, value FROM (#{field_cache_source_sql(storage_name, era, value_expression)}) reduced
-                  #{"WHERE id > #{text_literal(cursor)}" if cursor}
-                  ORDER BY id LIMIT #{ResumableBackfill::CHUNK_SIZE}
-                SQL
-              end,
-              upsert:     lambda do |rows|
-                upsert_field_cache_rows!(name, rows)
-              end
+              source_sql: ->(cursor) { cache_backfill_page_sql(cursor, storage_name, era, value_expression) },
+              upsert:     ->(rows) { upsert_field_cache_rows!(name, rows) }
             )
           end
 
@@ -117,30 +95,56 @@ module Hecks
 
           private
 
+          # Creates the cache table under a short advisory lock, unless a racing boot made it first.
+          def create_field_cache_table!(name)
+            nested_transaction("hecks_field_cache_create") do
+              @db.exec_params("SELECT pg_advisory_xact_lock(hashtext('hecks_field_cache:' || $1))", [name])
+              next if table_exists?(name)
+
+              @db.exec(field_cache_ddl(name))
+              @db.exec("CREATE INDEX IF NOT EXISTS #{quote("#{name}_value_idx")} ON #{quote(name)} (value)")
+            end
+          end
+
+          def field_cache_ddl(name)
+            <<~SQL
+              CREATE TABLE #{quote(name)} (
+                id      text PRIMARY KEY,
+                ordinal bigint NOT NULL,
+                value   text
+              )
+            SQL
+          end
+
+          # One chunk of the reduced head, after `cursor` when the backfill resumes.
+          def cache_backfill_page_sql(cursor, storage_name, era, value_expression)
+            <<~SQL
+              SELECT id, ordinal, value FROM (#{field_cache_source_sql(storage_name, era, value_expression)}) reduced
+              #{"WHERE id > #{text_literal(cursor)}" if cursor}
+              ORDER BY id LIMIT #{ResumableBackfill::CHUNK_SIZE}
+            SQL
+          end
+
           # The reduced (id, ordinal, state) source a cache backfills from. Unlike the head
           # snapshot's source it reduces the ancestor tail too (era N > 1 mirrors `compile_head!`)
           # with ordinal kept; ordinals share one sequence per domain, so `ordinal <` holds.
           def field_cache_source_sql(storage_name, era, value_expression)
             era = era.to_i
-            if era == 1
-              return "SELECT id, ordinal, #{value_expression} AS value " \
-                     "FROM #{quote(head_snapshot(storage_name, era))}"
-            end
+            return era_one_cache_source_sql(storage_name, era, value_expression) if era == 1
 
-            held = eras.find { |candidate| candidate[:ordinal] == era }
-            view = held && held[:label] && matview(storage_name, era, held[:label])
-            ancestor_side =
-              if view && view_exists?(view)
-                "SELECT ordinal, aggregate_id AS id, state FROM #{quote(view)} WHERE operation = 'save'"
-              else
-                # No compiled ancestor matview yet (era just minted): snapshot side only.
-                "SELECT NULL::bigint AS ordinal, NULL::text AS id, NULL::jsonb AS state WHERE FALSE"
-              end
+            merged_cache_source_sql(storage_name, era, value_expression)
+          end
+
+          def era_one_cache_source_sql(storage_name, era, value_expression)
+            "SELECT id, ordinal, #{value_expression} AS value " \
+              "FROM #{quote(head_snapshot(storage_name, era))}"
+          end
 
+          def merged_cache_source_sql(storage_name, era, value_expression)
             <<~SQL
               SELECT id, ordinal, #{value_expression} AS value FROM (
                 SELECT DISTINCT ON (id) id, ordinal, state FROM (
-                  #{ancestor_side}
+                  #{ancestor_side_sql(storage_name, era)}
                   UNION ALL
                   SELECT ordinal, id, state FROM #{quote(head_snapshot(storage_name, era))}
                 ) merged ORDER BY id, ordinal DESC
@@ -148,6 +152,18 @@ module Hecks
             SQL
           end
 
+          # The ancestor era's saved rows from its compiled matview, or an empty relation.
+          def ancestor_side_sql(storage_name, era)
+            held = eras.find { |candidate| candidate[:ordinal] == era }
+            view = held && held[:label] && matview(storage_name, era, held[:label])
+            if view && view_exists?(view)
+              return "SELECT ordinal, aggregate_id AS id, state FROM #{quote(view)} WHERE operation = 'save'"
+            end
+
+            # No compiled ancestor matview yet (era just minted): snapshot side only.
+            "SELECT NULL::bigint AS ordinal, NULL::text AS id, NULL::jsonb AS state WHERE FALSE"
+          end
+
           def upsert_field_cache_rows!(name, rows)
             rows.each do |row|
               @db.exec_params(

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

@@ -1,5 +1,5 @@
-require_relative "../../../../../../naming"
-require_relative "../../translation/rule_compiler"
+require_relative "chain_sql"
+require_relative "sql_templates"
 
 module Hecks
   module Adapters
@@ -8,31 +8,14 @@ module Hecks
         # The read side of lineage: builds and maintains the head-snapshot
         # table and the compiled view/matview a query actually reads.
         module HeadCompiler
+          include ChainSql
+          include SqlTemplates
+
           # Backfill runs unconditionally after create: an existing journal
           # must never look empty just because its snapshot table is new.
           def ensure_head_snapshot!(storage_name, era)
             name = head_snapshot(storage_name, era)
-            unless table_exists?(name)
-              # Locked, not a bare CREATE, so two first-time boots can't race;
-              # nested_transaction lets this run standalone or inside mint's
-              # own already-open transaction without ending it early.
-              nested_transaction("hecks_head_snapshot") do
-                @db.exec_params("SELECT pg_advisory_xact_lock(hashtext('hecks_head_snapshot:' || $1))", [name])
-                next if table_exists?(name)
-
-                # A delete upserts a tombstone (operation = 'delete', state
-                # NULL) instead of removing the row, so it still outranks a
-                # stale ancestor `save` row by ordinal under DISTINCT ON.
-                @db.exec(<<~SQL)
-                  CREATE TABLE #{quote(name)} (
-                    id        text PRIMARY KEY,
-                    ordinal   bigint NOT NULL,
-                    operation text NOT NULL DEFAULT 'save',
-                    state     jsonb
-                  )
-                SQL
-              end
-            end
+            create_head_snapshot_table!(name) unless table_exists?(name)
             # Self-healing for a table created before this column existed;
             # a no-op once it and the relaxed constraint are already there.
             @db.exec("ALTER TABLE #{quote(name)} ADD COLUMN IF NOT EXISTS operation text NOT NULL DEFAULT 'save'")
@@ -46,29 +29,8 @@ module Hecks
           def backfill_head_snapshot!(name, storage_name, era)
             chunked_backfill!(
               name,
-              source_sql: lambda do |cursor|
-                <<~SQL
-                  SELECT id, ordinal, state FROM (
-                    SELECT DISTINCT ON (aggregate_id) aggregate_id AS id, ordinal, operation, state
-                    FROM #{quoted_journal}
-                    WHERE era = #{era.to_i} AND aggregate = #{text_literal(storage_name)}
-                    #{"AND aggregate_id > #{text_literal(cursor)}" if cursor}
-                    ORDER BY aggregate_id, ordinal DESC
-                  ) latest WHERE operation = 'save' ORDER BY id LIMIT #{ResumableBackfill::CHUNK_SIZE}
-                SQL
-              end,
-              upsert:     lambda do |rows|
-                rows.each do |row|
-                  # Always 'save' — source_sql above already filtered to
-                  # operation = 'save' rows only.
-                  @db.exec_params(
-                    "INSERT INTO #{quote(name)} (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 #{quote(name)}.ordinal < EXCLUDED.ordinal",
-                    [row["id"], row["ordinal"], row["state"]]
-                  )
-                end
-              end
+              source_sql: ->(cursor) { head_backfill_page_sql(cursor, storage_name, era) },
+              upsert:     ->(rows) { upsert_head_snapshot_rows!(name, rows) }
             )
           end
 
@@ -100,136 +62,8 @@ module Hecks
           # tail to reduce.
           def ensure_first_head!(storage_name)
             ensure_head_snapshot!(storage_name, 1)
-            # WHERE operation = 'save' excludes delete tombstones, whose
-            # state is NULL, so a deleted id falls out of the head instead
-            # of resolving to a nil state.
-            @db.exec(<<~SQL)
-              CREATE OR REPLACE VIEW #{quote(head_view(storage_name))} AS
-              SELECT id, state FROM #{quote(head_snapshot(storage_name, 1))} WHERE operation = 'save'
-            SQL
-          end
-
-          # Reduces the tail before chaining edges over it, not after: every
-          # reader already reduces to latest-per-id, so translating a
-          # superseded entry would be wasted work. `era` survives the
-          # reduction because each edge's case still needs it.
-          def latest_per_id(tail)
-            return tail if tail.to_s.empty?
-
-            "SELECT DISTINCT ON (aggregate_id) ordinal, era, aggregate, aggregate_id, operation, state " \
-              "FROM (#{tail}) tail_entries ORDER BY aggregate_id, ordinal DESC"
-          end
-
-          # Builds era N by layering its own last edge onto era N-1's existing
-          # matview, instead of re-deriving from raw history; returns nil
-          # (falling back to chain_sql) whenever that shortcut can't honestly
-          # apply. `edges.size != era - 1` guards names_by_era's own
-          # assumption that `edges` is the full chain reaching `era` — a
-          # shorter chain here would index names[:storage] out of bounds
-          # rather than safely falling back.
-          # rubocop:disable-next Metrics/CyclomaticComplexity
-          # rubocop:disable-next Metrics/PerceivedComplexity
-          def layered_chain_sql(aggregate, era, edges)
-            return nil if era < 3 || edges.size < 2 || edges.size != era - 1
-
-            held = eras
-            prior = held.find { |candidate| candidate[:ordinal] == era - 1 }
-            return nil unless prior && prior[:label]
-
-            prior_view = matview(aggregate.storage_name, era - 1, prior[:label])
-            return nil unless view_exists?(prior_view)
-
-            names = names_by_era(aggregate, edges)
-            cut = held.find { |candidate| candidate[:ordinal] == era }&.dig(:watermark)
-            declared = edges.last[:translation].for_aggregate(names[:current][edges.size])
-            expression = declared ? Translation::RuleCompiler.compile_rules(declared) : "state"
-            id_column = if Translation::RuleCompiler.rekeyed?(declared)
-                          Translation::RuleCompiler.id_case("operation = 'save'",
-                                                            declared)
-                        else
-                          "aggregate_id"
-                        end
-
-            <<~SQL
-              WITH layered AS (
-                SELECT DISTINCT ON (aggregate_id) ordinal, aggregate_id, operation, state FROM (
-                  SELECT ordinal, aggregate_id, operation, state FROM #{quote(prior_view)}
-                  UNION ALL
-                  SELECT ordinal, aggregate_id, operation, state FROM #{quoted_journal}
-                  WHERE era = #{era - 1} AND aggregate = #{text_literal(names[:storage][era - 2])}#{" AND ordinal <= #{cut}" if cut}
-                ) layers ORDER BY aggregate_id, ordinal DESC
-              )
-              SELECT ordinal, #{id_column}, operation,
-                     CASE WHEN operation = 'save' THEN #{expression} ELSE state END AS state
-              FROM layered
-            SQL
-          end
-
-          # Chains the original edges in mint order rather than flattening them
-          # into one rule set: edge 1 renaming A→B then edge 2 renaming C→A
-          # has no single phase order that applies both correctly.
-          def chain_sql(aggregate, era, edges)
-            names = names_by_era(aggregate, edges)
-            tail = latest_per_id(ancestor_tail_sql(names, era))
-            chain = edges.each_with_index.map do |edge, index|
-              declared = edge[:translation].for_aggregate(names[:current][index + 1])
-              expression = declared ? Translation::RuleCompiler.compile_rules(declared) : "state"
-              guard = "era <= #{index + 1} AND operation = 'save'"
-              id_column = if Translation::RuleCompiler.rekeyed?(declared)
-                            Translation::RuleCompiler.id_case(guard,
-                                                              declared)
-                          else
-                            "aggregate_id"
-                          end
-              "edge_#{index + 1} AS (SELECT ordinal, era, #{id_column}, operation, " \
-                "CASE WHEN #{guard} THEN #{expression} ELSE state END AS state " \
-                "FROM #{index.zero? ? 'tail' : "edge_#{index}"})"
-            end
-
-            <<~SQL
-              WITH tail AS (#{tail}),
-              #{chain.join(",\n")}
-              SELECT ordinal, aggregate_id, operation, state FROM edge_#{edges.size}
-            SQL
-          end
-
-          # Reads through head_body_sql — the same layered-or-full choice
-          # compile_head! makes at mint time — so a preview can't silently
-          # drift from what a real mint will materialize.
-          def translated_latest(aggregate, era, edges)
-            latest_of(head_body_sql(aggregate, era, edges))
-          end
-
-          # The untranslated ancestor tail, latest entry per id — the "before"
-          # side of a per-rule preservation check.
-          def ancestor_latest(aggregate, era, edges)
-            names = names_by_era(aggregate, edges)
-            tail = ancestor_tail_sql(names, era)
-            return {} if tail.empty?
-
-            latest_of("SELECT ordinal, era, aggregate_id, operation, state FROM (#{tail}) tail_rows")
-          end
-
-          # Reduces to newest entry per aggregate id, dropping any id whose
-          # newest entry is a delete rather than returning it with a nil state.
-          def latest_of(sql)
-            rows = @db.exec(<<~SQL)
-              SELECT aggregate_id, state FROM (
-                SELECT DISTINCT ON (aggregate_id) aggregate_id, operation, state
-                FROM (#{sql}) chained ORDER BY aggregate_id, ordinal DESC
-              ) latest WHERE operation = 'save'
-            SQL
-            rows.to_h { |row| [row["aggregate_id"], JSON.parse(row["state"])] }
-          end
-
-          # The one place that picks layered vs full, so a preview
-          # (translated_latest) can never approve a branch the real mint
-          # doesn't take. `full:` mirrors compile_head!'s own default;
-          # tail_merge is the one caller that forces it true.
-          def head_body_sql(aggregate, era, edges, full: false)
-            return chain_sql(aggregate, era, edges) if full
-
-            layered_chain_sql(aggregate, era, edges) || chain_sql(aggregate, era, edges)
+            tokens = { head_view: quote(head_view(storage_name)), snapshot: quote(head_snapshot(storage_name, 1)) }
+            @db.exec(format(FIRST_HEAD_VIEW_SQL, tokens))
           end
 
           # The matview bakes each ancestor's watermark in as a literal;
@@ -240,55 +74,11 @@ module Hecks
             storage_name = aggregate.storage_name
             view = matview(storage_name, era, label)
             body = head_body_sql(aggregate, era, edges, full: full)
-            @db.exec(<<~SQL)
-              CREATE MATERIALIZED VIEW #{quote(view)} AS
-              #{body}
-            SQL
+            @db.exec("CREATE MATERIALIZED VIEW #{quote(view)} AS\n#{body}\n")
             @db.exec("CREATE INDEX IF NOT EXISTS #{quote("#{view}_reduce_idx")} ON #{quote(view)} (aggregate_id, ordinal DESC)")
 
             ensure_head_snapshot!(storage_name, era)
-            @db.exec("DROP VIEW IF EXISTS #{quote(head_view(storage_name))}")
-            # Reads the snapshot's own operation column rather than hardcoding
-            # 'save', so a tombstone here outranks a stale ancestor save row
-            # by ordinal instead of letting it resurrect a deleted record.
-            @db.exec(<<~SQL)
-              CREATE VIEW #{quote(head_view(storage_name))} AS
-              SELECT id, state FROM (
-                SELECT DISTINCT ON (aggregate_id) aggregate_id AS id, operation, state FROM (
-                  SELECT ordinal, aggregate_id, operation, state FROM #{quote(view)}
-                  UNION ALL
-                  SELECT ordinal, id AS aggregate_id, operation, state
-                  FROM #{quote(head_snapshot(storage_name, era))}
-                ) merged ORDER BY aggregate_id, ordinal DESC
-              ) latest WHERE operation = 'save'
-            SQL
-          end
-
-          # Walks `was:` chains backward from the current name, so each
-          # ancestor era's rows can be found under the name of their time.
-          # names[:storage][e - 1] is the storage name for era e (1-based).
-          def names_by_era(aggregate, edges)
-            current = Array.new(edges.size + 1)
-            current[edges.size] = aggregate.name
-            (edges.size - 1).downto(0) do |index|
-              declared = edges[index][:translation].for_aggregate(current[index + 1])
-              current[index] = declared&.was || current[index + 1]
-            end
-            storage = current.map { |name| Naming.snake(name) }
-            { current: current, storage: storage }
-          end
-
-          # Cuts each ancestor era's rows at the watermark recorded when its
-          # successor was minted, so later writes to the old world don't leak in.
-          def ancestor_tail_sql(names, era)
-            watermarks = eras.to_h { |held| [held[:ordinal], held[:watermark]] }
-            selects = (1...era).map do |ancestor|
-              cut = watermarks[ancestor + 1]
-              "SELECT ordinal, era, aggregate, aggregate_id, operation, state FROM #{quoted_journal} " \
-                "WHERE era = #{ancestor} AND aggregate = #{text_literal(names[:storage][ancestor - 1])}" \
-                "#{" AND ordinal <= #{cut}" if cut}"
-            end
-            selects.join(" UNION ALL ")
+            replace_head_view!(storage_name, era, view)
           end
 
           # The rule-compiling helpers live in Translation::RuleCompiler instead,
@@ -307,6 +97,45 @@ module Hecks
               [name]
             ).ntuples.positive?
           end
+
+          private
+
+          # Locked, not a bare CREATE, so two first-time boots can't race;
+          # nested_transaction lets this run standalone or inside mint's
+          # own already-open transaction without ending it early.
+          def create_head_snapshot_table!(name)
+            nested_transaction("hecks_head_snapshot") do
+              @db.exec_params("SELECT pg_advisory_xact_lock(hashtext('hecks_head_snapshot:' || $1))", [name])
+              next if table_exists?(name)
+
+              @db.exec(format(HEAD_SNAPSHOT_SQL, table: quote(name)))
+            end
+          end
+
+          def head_backfill_page_sql(cursor, storage_name, era)
+            after_cursor = ("AND aggregate_id > #{text_literal(cursor)}" if cursor)
+            format(HEAD_BACKFILL_SQL, journal: quoted_journal, era: era.to_i, aggregate: text_literal(storage_name),
+                                      after_cursor: after_cursor, chunk_size: ResumableBackfill::CHUNK_SIZE)
+          end
+
+          def upsert_head_snapshot_rows!(name, rows)
+            rows.each do |row|
+              # Always 'save' — the source SQL filtered to operation = 'save' rows only.
+              @db.exec_params(
+                "INSERT INTO #{quote(name)} (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 #{quote(name)}.ordinal < EXCLUDED.ordinal",
+                [row["id"], row["ordinal"], row["state"]]
+              )
+            end
+          end
+
+          def replace_head_view!(storage_name, era, view)
+            @db.exec("DROP VIEW IF EXISTS #{quote(head_view(storage_name))}")
+            tokens = { head_view: quote(head_view(storage_name)), view: quote(view),
+                       snapshot: quote(head_snapshot(storage_name, era)) }
+            @db.exec(format(HEAD_VIEW_SQL, tokens))
+          end
         end
       end
     end

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

@@ -0,0 +1,120 @@
+module Hecks
+  module Adapters
+    class PostgresEra
+      class Lineage
+        # The row-level steps of a tail merge: finding the ids both worlds touched, capturing the
+        # new world's head states, rebuilding the heads, and writing each winner back.
+        module MergeWrites
+          # The ids written by both worlds since the cut.
+          CONFLICT_SQL = <<~SQL.freeze
+            SELECT aggregate_id FROM %<journal>s
+            WHERE era < %<era>s AND aggregate IN (%<olds>s) AND ordinal > %<cut>s
+            INTERSECT
+            SELECT aggregate_id FROM %<journal>s
+            WHERE era = %<era>s AND aggregate = %<current>s
+          SQL
+
+          # Ids written by both worlds since the cut, as `[storage_name, aggregate_id]` pairs.
+          #
+          # Compares raw ids: a rekeyed record's pre- and post-rekey rows never intersect and
+          # survive as two separate heads (a duplicate, not corruption); resolve by hand.
+          def conflict_ids(aggregate, edges, era, cut)
+            names = names_by_era(aggregate, edges)
+            rows = @db.exec(conflict_sql(names, era, cut))
+            rows.map { |row| [aggregate.storage_name, row["aggregate_id"]] }
+          end
+
+          private
+
+          def conflict_sql(names, era, cut)
+            olds = (1...era).map { |ancestor| text_literal(names[:storage][ancestor - 1]) }.join(", ")
+            format(CONFLICT_SQL, journal: quoted_journal, era: era.to_i, olds: olds, cut: cut.to_i,
+                                 current: text_literal(names[:storage][era - 1]))
+          end
+
+          # The new world's pre-merge head states, captured before the
+          # rebuild lets the tail interleave.
+          def pre_merge_states(merge)
+            new_ids = merge.winners.select { |_, side| side == "new" }.keys
+            merge.aggregates.each_with_object({}) do |aggregate, states|
+              new_ids.each do |id|
+                state = head_state(aggregate, id)
+                states[id] = [aggregate.storage_name, state] if state
+              end
+            end
+          end
+
+          # The record's state in the aggregate's current head, or nil when it is not there.
+          def head_state(aggregate, id)
+            row = @db.exec_params("SELECT state FROM #{quote(head_view(aggregate.storage_name))} WHERE id = $1", [id])
+            row[0]["state"] if row.ntuples.positive?
+          end
+
+          def recompile_heads!(merge)
+            @db.exec_params("UPDATE hecks_eras SET watermark = $2 WHERE domain = $1 AND ordinal > 1", [@domain, merge.tip])
+            merge.aggregates.each do |aggregate|
+              drop_head!(aggregate, merge)
+              # full: the watermarks just moved — every ancestor matview's
+              # cut is stale, so there is nothing safe to layer on.
+              compile_head!(aggregate, merge.era, merge.label, merge.edges, full: true)
+            end
+          end
+
+          def drop_head!(aggregate, merge)
+            @db.exec("DROP VIEW IF EXISTS #{quote(head_view(aggregate.storage_name))}")
+            @db.exec("DROP MATERIALIZED VIEW IF EXISTS #{quote(matview(aggregate.storage_name, merge.era, merge.label))}")
+          end
+
+          def reinsert_winners!(merge, new_states)
+            merge.winners.each do |id, side|
+              merge.aggregates.each do |aggregate|
+                state = winner_state(merge, aggregate, id, side, new_states)
+                write_winner!(merge, aggregate, id, state) if state
+              end
+            end
+          end
+
+          # The winning state of one record: the old world's from the rebuilt matview, the new
+          # world's from the states captured before the rebuild; nil when this aggregate has none.
+          def winner_state(merge, aggregate, id, side, new_states)
+            return new_winner_state(aggregate, id, new_states) unless side == "old"
+
+            row = @db.exec_params(
+              "SELECT state FROM #{quote(matview(aggregate.storage_name, merge.era, merge.label))} " \
+              "WHERE aggregate_id = $1 AND operation = 'save' ORDER BY ordinal DESC LIMIT 1",
+              [id]
+            )
+            row.ntuples.positive? ? row[0]["state"] : nil
+          end
+
+          def new_winner_state(aggregate, id, new_states)
+            new_states[id]&.first == aggregate.storage_name ? new_states[id][1] : nil
+          end
+
+          # Journal first, snapshot second, as a live write does: this INSERT bypasses
+          # PostgresEra#append, and head_view reads live rows from the snapshot table.
+          def write_winner!(merge, aggregate, id, state)
+            ordinal = @db.exec_params(
+              "INSERT INTO #{quoted_journal} (era, aggregate, aggregate_id, operation, state) " \
+              "VALUES ($1, $2, $3, 'save', $4) RETURNING ordinal",
+              [merge.era, aggregate.storage_name, id, state]
+            )[0]["ordinal"]
+            upsert_winner_snapshot!(snapshot: quote(head_snapshot(aggregate.storage_name, merge.era)),
+                                    id: id, ordinal: ordinal, state: state)
+          end
+
+          # Always 'save': winners come from save-only sources, never a delete.
+          def upsert_winner_snapshot!(snapshot:, id:, ordinal:, state:)
+            @db.exec_params(
+              "INSERT INTO #{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 #{snapshot}.ordinal < EXCLUDED.ordinal",
+              [id, ordinal, state]
+            )
+          end
+        end
+      end
+    end
+  end
+end