hecks 0.2.0 → 1.0.0

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

@@ -0,0 +1,304 @@
+require_relative "../../../../naming"
+require_relative "../../append_only"
+require_relative "../../../../runtime/registry"
+
+module Hecks
+  module Ports
+    module Persistence
+      # Translates a journal entry written under an old shape into the one
+      # the current bluebook declares — a renamed attribute, a renamed
+      # aggregate, or a field crossing a value-object boundary. Applied
+      # wherever entries are read, so replay derives the current head from
+      # history that was never rewritten — the port owns the meaning,
+      # adapters stay oblivious.
+      class Lineage
+        # `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 aggregate itself was renamed.
+        attr_reader :ancestor_name, :ancestor_storage_name
+
+        def self.for(registry, domain, aggregate)
+          translation = registry.translations.find do |candidate|
+            candidate.domain == domain.to_s && candidate.for_aggregate(aggregate.name)
+          end
+          return nil unless translation
+
+          from_declared(translation.for_aggregate(aggregate.name), aggregate.name)
+        end
+
+        # One SPECIFIC edge's rules for one aggregate — what the mint
+        # path uses, where `for` would happily answer with whichever
+        # edge in the registry mentioned the aggregate first.
+        def self.from_declared(declared, aggregate_name)
+          return nil unless declared
+
+          renamed_aggregate = declared.was && declared.was != aggregate_name.to_s
+          ancestor_name = renamed_aggregate ? declared.was : nil
+          ancestor_storage_name = renamed_aggregate ? Naming.snake(declared.was) : nil
+
+          new(declared.renames, declared.moves, declared.converts, declared.drops,
+              retypes: declared.retypes, computes: declared.computes, rekeys: declared.rekeys,
+              backfills: declared.backfills,
+              ancestor_name: ancestor_name, ancestor_storage_name: ancestor_storage_name)
+        end
+
+        def initialize(renames, moves = [], converts = [], drops = [], retypes: [], computes: [], rekeys: [],
+                       backfills: [], ancestor_name: nil, ancestor_storage_name: nil)
+          @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
+        end
+
+        # Whether any rule in this edge is a compute — the one rule kind
+        # with no in-process implementation at all. An aggregate carrying
+        # one refuses to boot anywhere but Postgres, per-rule and by name,
+        # before the general drift machinery says anything vaguer.
+        def computes? = !@computes.empty?
+
+        # THE SINGLE SOURCE OF TRUTH for "does this edge rekey this
+        # aggregate" — every consumer (coverage_check.rb's identity gate,
+        # minter.rb's approval gate, layer_two.rb's audit, head_compiler.rb's
+        # SQL compilation) asks THIS, never re-derives it from `declared`
+        # independently. One accessor to change if what a rekey rule means
+        # ever needs to change, not four call sites in four files.
+        def rekey? = !@rekeys.empty?
+
+        # The rekey's own SQL — first-and-only rule, same one-per-aggregate
+        # assumption `compute` makes about its own list where it matters
+        # (an edge with more than one is a DSL-level decision, not
+        # something this reader arbitrates).
+        def rekey_sql = @rekeys.first&.sql
+
+        # The reference semantics for the five PORTABLE rule kinds —
+        # rename, move, convert, drop, and the aggregate-level `was:`.
+        # `retype` moves nothing (stored state never carries a type name)
+        # and `compute` is deliberately not applied here: its SQL is its
+        # only implementation, so this transform neither imitates nor
+        # checks it — the source field passes through untouched, and the
+        # audit verifies compute output against the matview alone.
+        def translate(entry)
+          return entry unless entry.save? && entry.state
+
+          # 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) }
+          # LAST, and only where nothing already answered — a backfill
+          # fills the gap a rename/move/convert left untouched, never
+          # overwrites a value that already made it across.
+          @backfills.each { |backfill| state[backfill.name] = backfill.default unless state.key?(backfill.name) }
+          Entry.new(operation: entry.operation, id: entry.id, state: state, mirrors: entry.mirrors)
+        end
+
+        # Whether this translation names `path` as an old key it accounts
+        # for — the rename, move, or convert it came from, or an explicit
+        # drop. `path` is a bare name ("cost") or a dotted value-object
+        # member ("price.currency"); a rule covering the WHOLE top-level
+        # attribute (a rename, a top-level move/convert/drop) also covers
+        # anything nested under it, since the whole value travels or goes
+        # away together. Used to catch a field — or a value object's own
+        # member — that vanished (or silently changed type) without
+        # anything explaining it, even when some OTHER field is covered.
+        #
+        # `backfills` matches on the WHOLE name only, never a dotted
+        # prefix — a backfill names a top-level attribute that is new
+        # outright (nothing to be a prefix of on the held side), unlike
+        # every rule above it, which explains a path that existed and
+        # moved, converted, or vanished.
+        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
+
+        # THE DESTINATION-SIDE TWIN of `explains?` above, which only ever
+        # asks about a rule's SOURCE. `unsafe_additions` asks a different
+        # question — not "was this vanished path accounted for" but "does
+        # an existing record end up with a value here" — and a move or
+        # convert whose `to:` lands a old field inside a BRAND-NEW
+        # top-level attribute (`weight` becoming `contents.weight` when
+        # `Contents` did not exist before) fills that attribute for an
+        # existing record exactly as a `backfill` would, even though
+        # nothing named `contents` explains any vanished path. `compute`
+        # counts on the same terms `explains?` already grants it
+        # elsewhere in this file — Postgres-only and audited, not
+        # actually applied by THIS method, the same gap the vanish side
+        # already lives with.
+        #
+        # `@renames.value?` belongs here too, and used to be missing: a
+        # bare `rename :cost, to: :amount` is the plainest possible
+        # covering rule there is (`translate` above applies it
+        # unconditionally, no lookup table, no per-record ambiguity —
+        # simpler than a move or convert, which both got their `fills?`
+        # entry from the start), and its absence meant `unsafe_additions`
+        # reported the new name as an unexplained required addition on
+        # EVERY rename-only edge, the single most common translation
+        # shape there is. `explains?` already checked the source side
+        # (`@renames.key?`); `fills?` is the symmetric destination-side
+        # check that was never added alongside 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
+
+        # Whether a declared retype says the pair of TYPE names means the
+        # same shape — a value object or entity whose own name changed
+        # with its members intact. Nothing in the stored data carries the
+        # type name, so this never moves a value; it only satisfies the
+        # era diff's literal type-name comparison.
+        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
+
+        # M27 (docs/audits/2026-08-10-main-bug-audit.md,
+        # docs/audits/2026-08-11-bug-triage.md) — SIMULTANEOUS, not
+        # sequential: `state[new] = state.delete(old)` per rename, run
+        # one rule at a time against the SAME hash it was reading from,
+        # loses data the instant one rule's destination is another
+        # rule's source. A swap (`rename :a, to: :b` alongside
+        # `rename :b, to: :a`) on `{a: 1, b: 2}` used to produce
+        # `{a: 1}` — the first rule wrote `b: 1` over the real `b: 2`
+        # before the second rule ever got a chance to read it, and the
+        # value the whole edge was supposed to preserve (2, moved to
+        # `:a`) was gone. The standard fix: snapshot every rule's OLD
+        # key and value from `state` FIRST, then remove every old key
+        # and only THEN write every new key — a rename never reads a
+        # key this same pass has already written to, so a swap or a
+        # longer chain applies as one permutation, not a sequence of
+        # edits each stepping on the last.
+        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) }
+          # rubocop:disable Style/CombinableLoops -- NOT combinable: a swap
+          # (:a<->:b) needs every delete done before any write, or the first
+          # rename's write becomes the second rename's delete target — see
+          # this method's own comment above.
+          snapshot.each { |_old_name, new_name, value| state[new_name] = value }
+          # rubocop:enable Style/CombinableLoops
+        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
+
+        # A dotted path's first segment is a top-level (symbol) key; a
+        # second segment reaches into a value-object member, stored with a
+        # string key exactly as the adapter's own journal reader loaded it.
+        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 — the same path machinery, plus a lookup. A value
+        # with no entry in the 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
+
+        # ADVERSARIAL FINDING, not a hypothetical: a destination whose
+        # top segment ALREADY holds a value — most commonly a reference,
+        # stored as a bare scalar id — used to be silently clobbered with
+        # an empty hash the moment a dotted destination needed to nest
+        # under it (`state[top] ||= {}` only guards nil/false, so a
+        # truthy non-Hash sailed straight through to `state[top][member] =`,
+        # i.e. `"team-1"["detail"] =`, which is String#[]=  and raised an
+        # unrelated-looking IndexError). Whether it crashed or silently
+        # replaced the value, this is a `drop` that never declared
+        # itself — the one thing this language exists to make explicit
+        # (see apply_convert's own refusal above, the same shape). Refuse
+        # by name instead, on both sides: the SQL half (hecks_tr_insert)
+        # raises the 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
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,171 @@
+require_relative "../../era_tamper"
+require_relative "../../../../../../runtime/registry"
+require_relative "../../storage_shape"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      class Lineage
+        module EraStore
+          # Every held text is verified against its raw-byte digest on the
+          # way out — an edited storage fact refuses rather than silently
+          # reporting "no drift". This is NOT the era name (which hashes
+          # the canonical projection, minted once, never recomputed): it
+          # is a plain integrity check over bytes, and a row from before
+          # the check existed is backfilled, not refused.
+          def eras
+            @db.exec_params(
+              "SELECT ordinal, hash, label, held_text, watermark, held_digest, held_projection::text " \
+              "FROM hecks_eras WHERE domain = $1 ORDER BY ordinal",
+              [@domain]
+            ).map do |row|
+              verify_integrity!(row["ordinal"].to_i, row["held_text"], row["held_digest"], row["held_projection"])
+              { ordinal: row["ordinal"].to_i, hash: row["hash"], label: row["label"],
+                held_text: row["held_text"], watermark: row["watermark"]&.to_i }
+            end
+          end
+
+          # The unverified row — what bin/reattest_era shows an operator
+          # after the integrity check fires.
+          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
+
+          # The recovery path: tamper-EVIDENCE (against accident and
+          # drift, not adversaries) gets resolved by a human acknowledging
+          # the text as it now stands — recorded in an append-only
+          # attestation table, never by a bare psql UPDATE.
+          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
+
+          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
+
+          # A verified-authentic text backfills what older rows lack: its
+          # projection and its archive copy. Never run on a text that
+          # failed verification — that would bless the 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]
+          end
+
+          def hold_first!(text, projection: nil)
+            @db.exec_params(
+              "INSERT INTO hecks_eras (domain, ordinal, held_text, held_digest, held_projection) " \
+              "VALUES ($1, 1, $2, $3, $4) ON CONFLICT DO NOTHING",
+              [@domain, text, Digest::SHA256.hexdigest(text), projection && JSON.generate(projection)]
+            )
+            archive_text!(1, text)
+            # Era 1 is the current era from its first moment — established
+            # here, not left to whichever role happens to boot first.
+            advance_era!(1)
+          end
+
+          def archive_text!(ordinal, text)
+            @db.exec_params(
+              "INSERT INTO hecks_era_texts (domain, ordinal, digest, held_text) VALUES ($1, $2, $3, $4) " \
+              "ON CONFLICT DO NOTHING",
+              [@domain, ordinal, Digest::SHA256.hexdigest(text), text]
+            )
+          end
+
+          # A Layer-3 approval, recorded IN the database it was reviewed
+          # against — bound to the edge's parsed content and the journal's
+          # high-water ordinal at review time. The latest row for a shape
+          # pair wins (re-approval supersedes).
+          def record_approval!(from:, to:, edge_digest:)
+            @db.exec_params(
+              "INSERT INTO hecks_approvals (domain, from_label, to_label, edge_digest, reviewed_ordinal) " \
+              "VALUES ($1, $2, $3, $4, $5)",
+              [@domain, from, to, edge_digest, last_ordinal]
+            )
+          end
+
+          def approval_for(from:, to:)
+            rows = @db.exec_params(
+              "SELECT edge_digest, reviewed_ordinal FROM hecks_approvals " \
+              "WHERE domain = $1 AND from_label = $2 AND to_label = $3 ORDER BY approved_at DESC, reviewed_ordinal DESC LIMIT 1",
+              [@domain, from, to]
+            )
+            return nil if rows.ntuples.zero?
+
+            { edge_digest: rows[0]["edge_digest"], reviewed_ordinal: rows[0]["reviewed_ordinal"].to_i }
+          end
+
+          # Era identity is minted ONCE and stored; nothing ever recomputes
+          # a stored name to verify it.
+          def mint_name!(ordinal, hash, label)
+            @db.exec_params(
+              "UPDATE hecks_eras SET hash = $3, label = $4, canon_form = $5 " \
+              "WHERE domain = $1 AND ordinal = $2 AND hash IS NULL",
+              [@domain, ordinal, hash, label, Runtime::StorageShape::FORM_VERSION]
+            )
+          end
+
+          def last_ordinal
+            @db.exec("SELECT COALESCE(max(ordinal), 0) AS o FROM #{quoted_journal}")[0]["o"].to_i
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,190 @@
+require "digest"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      class Lineage
+        # THE READ-SIDE OF THE ERA WORKAROUND. Once a domain mints a
+        # second era, `head_view` is a `DISTINCT ON`/`UNION ALL`
+        # reduction — and a `where` clause on anything but `id` (its own
+        # partition key) cannot be pushed through that reduction, so every
+        # declared query pays the cost of reducing the WHOLE aggregate
+        # before it can filter anything (see docs/implemented/postgres-era-adapter-
+        # split-plan.md's own trigger section — this is a real
+        # SQL-semantics wall, not a missing index; adding one to
+        # `head_view` itself changes nothing, because the planner cannot
+        # prove a predicate on a non-partition column commutes with
+        # `DISTINCT ON` without risking a stale row winning).
+        #
+        # THE WORKAROUND: one narrow table per declared `where`-field
+        # (never `order_by`-only fields — sorting the reduced output was
+        # never blocked by the reduction; only filtering was), holding
+        # exactly (id, ordinal, value) — the CURRENT extracted value for
+        # every live id, maintained transactionally by `append` alongside
+        # the head snapshot it already upserts (same ordinal-guard idiom:
+        # `WHERE ordinal < EXCLUDED.ordinal`). A query whose sole `where`
+        # is on a cached field never runs the reduction at all: `SELECT id
+        # FROM <field>_cache WHERE value <op> $1`, then `SELECT id, state
+        # FROM head_view WHERE id = ANY($ids)` — safe THROUGH the
+        # reduction because `id` is its own partition key, unlike the
+        # original field.
+        #
+        # SCOPED TO NON-LIST FIELDS ONLY, same reasoning Track A (plain
+        # Postgres) and Track B (Sqlite/D1) both landed on independently
+        # for their own automatic indexing: this codebase's `contains`
+        # compiles to element-membership (`jsonb_array_elements`/
+        # `json_each` + `EXISTS`), which a (id, ordinal, value) cache table
+        # keyed on ONE scalar value per id has no way to represent — a
+        # list field would need one row per (id, element), a different
+        # shape this plan does not build. `PostgresEra#eligible_for_cache?`
+        # is where that boundary lives.
+        module FieldCache
+          # Deterministic and collision-free regardless of field-path
+          # length or storage-name length — Postgres identifiers cap at 63
+          # bytes, and a value-object member path (`compliance.review.
+          # deadline_at`) combined with a long storage name could exceed
+          # that if built any less defensively. Not meant to be
+          # human-readable; `hecks_backfill_progress`/catalog lookups are
+          # always driven by this same computed name, never typed by hand.
+          def field_cache(storage_name, era, field)
+            "hecks_fc_#{Digest::SHA256.hexdigest("#{storage_name}\0#{era}\0#{field}")[0, 20]}"
+          end
+
+          # Self-healing, same idiom as `ensure_head_snapshot!`: cheap,
+          # unconditional, safe to call on every boot. CREATION is a
+          # short-held lock (table doesn't exist yet — nothing to block);
+          # BACKFILL runs outside it, chunk by chunk, each chunk its own
+          # short lock — never one transaction spanning the scan, per
+          # principle 1. `value_expression` is the exact SQL
+          # `PostgresEra#query_expression(field)` already compiles for
+          # this field, applied against a `state` column this module's own
+          # SQL always makes available in scope (see `field_cache_source_sql`)
+          # — ONE source of truth for "what does this field mean", not a
+          # second hand-rolled copy that could silently drift from what a
+          # live query actually filters on.
+          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
+            backfill_field_cache!(name, storage_name, era, value_expression)
+            name
+          end
+
+          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
+                  #{cursor ? "WHERE id > #{text_literal(cursor)}" : ''}
+                  ORDER BY id LIMIT #{ResumableBackfill::CHUNK_SIZE}
+                SQL
+              end,
+              upsert:     lambda do |rows|
+                upsert_field_cache_rows!(name, rows)
+              end
+            )
+          end
+
+          # THE LIVE-WRITE SIDE — called from `append`, inside the SAME
+          # transaction as the journal insert and the head-snapshot
+          # upsert, for every field this aggregate has a cache table for.
+          # `state_json` is the entry's OWN new state (already the thing
+          # `append` is about to write) — bound as a literal jsonb value
+          # and aliased `state`, so `value_expression` (built to read a
+          # column literally named `state`) evaluates identically here and
+          # in every backfill/query-time use, with no separate Ruby-side
+          # re-implementation of "how to pick a value-object's member" to
+          # keep in sync.
+          def upsert_field_cache_row!(name, id, ordinal, state_json, value_expression)
+            @db.exec_params(<<~SQL, [id, ordinal, state_json])
+              INSERT INTO #{quote(name)} (id, ordinal, value)
+              SELECT $1, $2, #{value_expression}
+              FROM (SELECT $3::jsonb AS state) src
+              ON CONFLICT (id) DO UPDATE SET ordinal = EXCLUDED.ordinal, value = EXCLUDED.value
+              WHERE #{quote(name)}.ordinal < EXCLUDED.ordinal
+            SQL
+          end
+
+          def delete_field_cache_row!(name, id)
+            @db.exec_params("DELETE FROM #{quote(name)} WHERE id = $1", [id])
+          end
+
+          private
+
+          # The reduced (id, ordinal, state) source a field cache backfills
+          # from — NOT the raw journal (unlike `backfill_head_snapshot!`'s
+          # own source): a field cache reflects the CURRENT HEAD value,
+          # which for era > 1 can come from either this era's own live
+          # writes OR an untouched-this-era id whose value still comes
+          # from the translated ancestor tail. Era 1 has no ancestor tail
+          # (the snapshot table IS the head, verbatim); era N reduces the
+          # SAME two sources `compile_head!`'s own final view definition
+          # unions (head_compiler.rb) — this is deliberately the identical
+          # shape, ordinal kept in the SELECT list instead of dropped,
+          # because a backfilled cache row needs a REAL ordinal to guard
+          # against a concurrent live write the same way every other
+          # upsert in this adapter already does. Ordinals are safe to
+          # compare across that union because they come from ONE spanning
+          # sequence per domain (see lineage.rb's own header comment) —
+          # an ancestor-era ordinal is always numerically smaller than any
+          # current-era one, so the ordinary `ordinal <` guard already
+          # means the right thing with no era-aware special case.
+          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
+
+            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 (e.g. this era was just
+                # minted and compile_head! hasn't run for THIS aggregate) —
+                # the live snapshot side alone is the whole truth so far.
+                "SELECT NULL::bigint AS ordinal, NULL::text AS id, NULL::jsonb AS state WHERE FALSE"
+              end
+
+            <<~SQL
+              SELECT id, ordinal, #{value_expression} AS value FROM (
+                SELECT DISTINCT ON (id) id, ordinal, state FROM (
+                  #{ancestor_side}
+                  UNION ALL
+                  SELECT ordinal, id, state FROM #{quote(head_snapshot(storage_name, era))}
+                ) merged ORDER BY id, ordinal DESC
+              ) reduced
+            SQL
+          end
+
+          def upsert_field_cache_rows!(name, rows)
+            rows.each do |row|
+              @db.exec_params(
+                "INSERT INTO #{quote(name)} (id, ordinal, value) VALUES ($1, $2, $3) " \
+                "ON CONFLICT (id) DO UPDATE SET ordinal = EXCLUDED.ordinal, value = EXCLUDED.value " \
+                "WHERE #{quote(name)}.ordinal < EXCLUDED.ordinal",
+                [row["id"], row["ordinal"], row["value"]]
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end