hecks 1.3.0 → 1.4.0

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

@@ -2,56 +2,67 @@ module Hecks
   module Adapters
     class PostgresEra
       class Lineage
-        # THE ONE CHUNKED, LOCK-FREE, RESUMABLE BACKFILL LOOP — shared by
-        # `backfill_head_snapshot!` (era 1's existing one-shot blocking
-        # backfill, retrofit) and every field-cache table's own initial
-        # backfill (new). Governing principle 1 (docs/implemented/postgres-era-adapter-
-        # split-plan.md): no operation this plan touches may hold a lock
-        # across a scan whose duration scales with table size — a single
-        # `INSERT ... SELECT` over the whole journal (what
-        # `backfill_head_snapshot!` used to be) is exactly that, and so is
-        # a naive "populate every cache row in one statement" field-cache
-        # backfill.
+        # The one chunked, lock-free, resumable backfill loop — shared by
+        # `backfill_head_snapshot!` (era 1's head-snapshot backfill) and
+        # every field-cache table's own initial backfill. Governing
+        # principle 1
+        # (docs/implemented/postgres-era-adapter-split-plan.md): no
+        # operation this plan touches may hold a lock across a scan whose
+        # duration scales with table size — a single `INSERT ... SELECT`
+        # over the whole journal (the one-shot form of
+        # `backfill_head_snapshot!`) is exactly that, and so is a naive
+        # "populate every cache row in one statement" field-cache backfill.
         #
-        # THE SHAPE: read one bounded chunk (real rows, real ordinals) with
+        # ## The shape
+        #
+        # Read one bounded chunk (real rows, real ordinals) with
         # a plain SELECT — no lock held across it, so an ordinary reader or
         # writer is never blocked by a backfill in progress — then upsert
-        # that chunk under the SAME transactionally-scoped advisory lock +
+        # that chunk under the same transactionally-scoped advisory lock +
         # ordinal-guard idiom `append`'s own snapshot upsert already uses
         # (`WHERE ordinal < EXCLUDED.ordinal`), then persist a cursor
         # before moving to the next chunk. Repeat until a chunk reads back
         # short of a full page — that page was the last one.
         #
-        # RESUMABLE, not merely restartable. A crash (or a second
+        # ## Resumable, not merely restartable
+        #
+        # A crash (or a second
         # concurrent boot) mid-backfill leaves the cursor exactly where the
-        # last COMMITTED chunk left it — `hecks_backfill_progress` is
-        # updated in the SAME transaction as the chunk's own upsert, so
+        # last committed chunk left it — `hecks_backfill_progress` is
+        # updated in the same transaction as the chunk's own upsert, so
         # cursor and data can never observably disagree (see
         # `run_chunk!`). The next attempt reads that cursor and continues;
         # it does not rescan what a prior attempt already committed.
-        # RESTARTABLE would also be CORRECT here (every upsert is
+        # Restartable would also be correct here (every upsert is
         # idempotent and ordinal-guarded — rerunning an already-done chunk
         # from id 1 changes nothing) but wastes real work on a large
-        # table; resumability is what keeps a crash near the END of a
+        # table; resumability is what keeps a crash near the end of a
         # large backfill cheap to recover from instead of starting over.
         #
-        # THE LOCK KEY PREFIX is `hecks_field_cache:` — deliberately
+        # ## The lock key
+        #
+        # The lock key prefix is `hecks_field_cache:` — deliberately
         # disjoint from the three families already in use elsewhere in
         # this adapter (`hecks_ordinal:`, `hecks_eras:`,
         # `hecks_head_snapshot:` — see lineage.rb/head_compiler.rb/
-        # mint_transaction.rb/tail_merge.rb) so a backfill chunk NEVER
+        # mint_transaction.rb/tail_merge.rb) so a backfill chunk never
         # contends with a plain write, a mint, or a snapshot-table's own
-        # first-creation lock. It is held for exactly ONE CHUNK's own
+        # first-creation lock. It is held for exactly one chunk's own
         # transaction, never across the whole backfill — two concurrent
-        # backfillers of the SAME target simply take turns one chunk at a
+        # backfillers of the same target simply take turns one chunk at a
         # time rather than racing to duplicate work; neither blocks an
         # unrelated reader or writer for even an instant.
         module ResumableBackfill
           CHUNK_SIZE = 5_000
 
+          # Creates `hecks_backfill_progress`, the table of per-target backfill cursors, if absent.
+          #
           # Idempotent, unguarded — same idiom as every other DDL helper
           # in this file tree (`ensure_head_snapshot!` et al.): cheap,
           # runs on every boot, only ever does real work once.
+          #
+          # @return [void]
+          # @raise [PG::Error] if Postgres refuses the DDL
           def ensure_backfill_progress_table!
             @db.exec(<<~SQL)
               CREATE TABLE IF NOT EXISTS hecks_backfill_progress (
@@ -63,13 +74,15 @@ module Hecks
             SQL
           end
 
+          # Fills `target` one committed chunk at a time, resuming from its stored cursor.
+          #
           # Drives `target` (an already-created, currently-empty-or-
           # partially-filled table) through chunks until a source read
           # comes back short of `CHUNK_SIZE` rows. Two distinct callables,
           # not one — a head-snapshot row and a field-cache row carry
           # different columns (`state` jsonb vs. a single extracted
           # `value`), so there is no one generic "upsert this row" shape
-          # to share; only the LOOP, the lock, and the cursor are generic.
+          # to share; only the loop, the lock, and the cursor are generic.
           #
           #   source_sql.call(cursor) — given the last-processed id (nil
           #     before the first chunk), returns a SQL SELECT whose result
@@ -82,11 +95,21 @@ module Hecks
           #
           #   upsert.call(rows) — given the PG::Result of one chunk's
           #     read, performs the actual guarded upsert into `target` and
-          #     returns nothing meaningful; runs INSIDE the same
+          #     returns nothing meaningful; runs inside the same
           #     transaction/advisory-lock scope as the cursor update below,
           #     so a crash between "wrote the chunk" and "advanced the
           #     cursor" is impossible — they commit together or not at
           #     all.
+          #
+          # @param target [String] unquoted name of the table to fill; also the progress row's key
+          #   and the advisory-lock key
+          # @param source_sql [#call] callable given the cursor (`String` id of the last row
+          #   processed, nil before the first chunk) that returns the chunk's SELECT as a `String`
+          # @param upsert [#call] callable given one chunk's `PG::Result` that writes it into
+          #   `target`; its return value is ignored
+          # @return [void]
+          # @raise [PG::Error] if Postgres refuses the progress-table DDL, a source read, or a
+          #   cursor update; whatever `upsert` raises propagates too, rolling back that chunk
           def chunked_backfill!(target, source_sql:, upsert:)
             ensure_backfill_progress_table!
             loop do
@@ -97,8 +120,8 @@ module Hecks
 
           private
 
-          # ONE CHUNK, ONE TRANSACTION, ONE SHORT-HELD LOCK. Re-reads
-          # progress AFTER acquiring the lock (not just before) — a second
+          # One chunk, one transaction, one short-held lock. Re-reads
+          # progress after acquiring the lock (not just before) — a second
           # concurrent booter may have already finished this exact chunk
           # (or the whole backfill) while this process was waiting for the
           # lock; without the re-read, it would redundantly reprocess a
@@ -128,7 +151,7 @@ module Hecks
 
               upsert.call(rows)
               completed = rows.ntuples < CHUNK_SIZE
-              # `PG::Result#[]` supports neither an out-of-range index NOR
+              # `PG::Result#[]` supports neither an out-of-range index nor
               # a negative one (unlike a plain Ruby Array) — same trap as
               # `backfill_progress` above, the explicit last-index form.
               last_cursor = rows[rows.ntuples - 1]["id"]
@@ -137,9 +160,9 @@ module Hecks
             completed
           end
 
-          # `PG::Result#[]` RAISES IndexError on an out-of-range index —
+          # `PG::Result#[]` raises IndexError on an out-of-range index —
           # unlike a plain Ruby Array, it does not return nil — so the
-          # ENTIRELY ORDINARY case of "no progress row exists yet" (every
+          # entirely ordinary case of "no progress row exists yet" (every
           # target's very first check) cannot be read via a bare `[0]`.
           # `ntuples.zero?` first, always.
           def backfill_progress(target)

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

@@ -11,8 +11,15 @@ module Hecks
         module TailMerge
           # ── fork observability ─────────────────────────────────────────
 
+          # Counts the journal rows an old era wrote after the next era's cut.
+          #
           # Post-cut writes an old era made after the newer era was minted
           # — the divergence between the worlds, observable at any time.
+          #
+          # @param old_era [Integer] ordinal of the superseded era to measure
+          # @return [Integer] number of `old_era` rows past the watermark of era `old_era + 1`;
+          #   0 when the domain holds no such newer era
+          # @raise [Runtime::WiringError] if a held era's text fails its integrity check
           def diverged_count(old_era)
             cut = eras.find { |era| era[:ordinal] == old_era + 1 }&.dig(:watermark)
             return 0 unless cut
@@ -24,6 +31,8 @@ module Hecks
 
           # ── tail-merge ─────────────────────────────────────────────────
           #
+          # Folds every old era's post-cut writes into the current era's heads, under named winners.
+          #
           # The one deliberate command — it marks a business event (an app
           # retiring), never a shape change. One transaction: advance the
           # watermarks, rebuild the head so the tail interleaves by its
@@ -34,13 +43,27 @@ module Hecks
           # re-enters as the newest row and wins structurally — originals
           # stay immutable).
           # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
-          # One Postgres transaction (BEGIN…COMMIT) with a manual ROLLBACK
+          # One Postgres transaction (`BEGIN`…`COMMIT`) with a manual `ROLLBACK`
           # at every early refusal, and a snapshot-before-mutation
           # invariant (`new_states` captured before the head rebuild lets
           # the tail interleave). Splitting the steps into separate
           # methods would force each to independently know how to roll
           # back the same shared transaction, and would separate the
           # snapshot from the mutation it must precede.
+          #
+          # @param aggregates [Array<Bluebook::Aggregate>] the current bluebook's aggregates, each
+          #   of which gets its head rebuilt
+          # @param edges [Array<Hash{Symbol => Bluebook::Translation}>] the full edge chain in mint
+          #   order, one `{ translation: }` Hash per step, as `LineageManager.edge_chain` builds it
+          # @param winners [Hash{String => String}] aggregate id to winning side, `"old"` or
+          #   `"new"`; the winner's whole state is appended as the newest row
+          # @param audit [#call, nil] callable run just before `COMMIT` that returns an
+          #   `Array<String>` of violations, empty to pass; nil skips the audit
+          # @return [true] always, once the merge is committed; every refusal raises instead
+          # @raise [Runtime::WiringError] if the domain stands at era 1, if an id touched by both
+          #   worlds since the cut has no entry in `winners`, if `audit` reports a violation, if
+          #   another mint or merge holds the domain lock for over 10s, if Postgres refuses any
+          #   statement, or if a held era's text fails its integrity check
           def merge_tail!(aggregates:, edges:, winners: {}, audit: nil)
             @db.exec("BEGIN")
             @db.exec("SET LOCAL lock_timeout = '10s'")
@@ -159,18 +182,18 @@ module Hecks
           end
           # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
-          # Ids touched by BOTH worlds since the cut — the old world's
+          # Ids touched by both worlds since the cut — the old world's
           # post-cut tail INTERSECTed with the new world's own writes.
           #
-          # KNOWN GAP, not silently risked: this compares raw
+          # Known gap, not silently risked: this compares raw
           # `aggregate_id` values, with no notion of "these two different
           # ids are the same entity, rekeyed." If a domain's history
-          # includes a rekey (see TranslationRekey) and is LATER
+          # includes a rekey (see TranslationRekey) and is later
           # merged here, a record's pre-rekey and post-rekey rows will
           # never intersect — they just silently survive as two separate,
           # unrelated-looking heads (a duplicate, not corruption: nothing
           # here deletes or clobbers either side). Resolve any such
-          # duplicate manually after a merge; teaching this INTERSECT
+          # duplicate manually after a merge; teaching this intersect
           # about a rekey mapping is real, separate work, deliberately
           # out of scope for rekey's first pass.
           def conflict_ids(aggregate, edges, era, cut)

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

@@ -9,16 +9,18 @@ module Hecks
         # the cross-execution equivalence spec, never a second source of
         # truth.
         module TransformInstaller
+          # Installs or replaces the six `hecks_tr_*` functions under a database-wide advisory lock.
+          #
           # The jsonb rule transforms — installed once, idempotently. Kept
           # equal to the port's reference entry-JSON transform by the
           # cross-execution equivalence spec; the SQL here is a compilation
           # target, not a second source of truth.
           #
-          # LOCKED, unlike every other statement `ensure_base!` runs — those
+          # Locked, unlike every other statement `ensure_base!` runs — those
           # are all `CREATE ... IF NOT EXISTS`/`ADD COLUMN IF NOT EXISTS`,
           # which Postgres itself resolves safely under concurrent boots.
           # `CREATE OR REPLACE FUNCTION` is not: it always rewrites the
-          # `pg_proc` row, so two sessions racing to (re)install the SAME
+          # `pg_proc` row, so two sessions racing to (re)install the same
           # function — these six are shared/global, not per-domain, so any
           # two domains' concurrent first-boots can collide here — hit a
           # real `PG::InternalError: tuple concurrently updated`, not a
@@ -26,6 +28,9 @@ module Hecks
           # already-open-transaction-safe wrapper `ensure_field_cache!`
           # uses for its own advisory lock; a fixed, domain-independent key
           # is correct since these functions have no domain of their own.
+          #
+          # @return [void]
+          # @raise [PG::Error] if Postgres refuses the lock or a function definition
           def install_transforms!
             nested_transaction("hecks_tr_functions") do
               @db.exec_params("SELECT pg_advisory_xact_lock(hashtext('hecks_tr_functions'))", [])
@@ -33,14 +38,21 @@ module Hecks
             end
           end
 
-          # Six independent CREATE OR REPLACE FUNCTION statements — each
+          # Runs the six function definitions with no lock of its own; `install_transforms!` is
+          # the locked entry point.
+          #
+          # Six independent `CREATE OR REPLACE FUNCTION` statements — each
           # self-contained SQL, no shared Ruby state, and (per this
           # module's own header comment) safe in any install order since
           # plpgsql bodies aren't resolved against each other until
-          # called, not at CREATE time. Split one-per-function below
+          # called, not at create time. Split one-per-function below
           # purely so each has its own name and (where relevant) its own
           # comment to sit next to, not because the six have any
           # sequencing dependency on one another.
+          #
+          # @return [void]
+          # @raise [PG::Error] if Postgres refuses a definition, including
+          #   `tuple concurrently updated` when two unlocked sessions race
           def install_transform_functions!
             install_hecks_tr_extract!
             install_hecks_tr_insert!
@@ -84,15 +96,16 @@ module Hecks
             SQL
           end
 
-          # ADVERSARIAL FINDING: a destination whose top segment already
+          # **Adversarial finding**: a destination whose top segment already
           # holds a value — most commonly a reference, a bare scalar id
-          # — used to be silently overwritten with an empty object the
-          # moment a dotted destination needed to nest under it. That is
-          # a drop that never declared itself, the one thing this
-          # language exists to make explicit (see hecks_tr_convert's own
-          # refusal below, the same shape) — refused here instead, with
-          # the Ruby reference transform (ports/persistence/lineage.rb's
-          # `insert`) raising the identical wording.
+          # — is refused rather than silently overwritten with an empty
+          # object the moment a dotted destination needs to nest under it.
+          # Overwriting is a drop that never declared itself, the one
+          # thing this language exists to make explicit (see
+          # hecks_tr_convert's own refusal below, the same shape). The
+          # Ruby reference transform
+          # (ports/persistence/plugins/era/lineage.rb's `insert`) raises
+          # the identical wording.
           def install_hecks_tr_insert!
             @db.exec(<<~SQL)
               CREATE OR REPLACE FUNCTION hecks_tr_insert(state jsonb, path text[], value jsonb, rule_label text) RETURNS jsonb

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

@@ -15,65 +15,75 @@ module Hecks
   module Adapters
     class PostgresEra
       # The lineage topology inside one Postgres database: one journal
-      # per domain, LIST-partitioned by era, with a single ordinal
+      # per domain, list-partitioned by era, with a single ordinal
       # sequence spanning partitions (total order across eras is
       # structural); a `hecks_eras` table holding each era's frozen
       # source text, its once-minted hash/label, and the watermark cut
-      # into its ancestor; and, per aggregate, a HEAD derived from the
+      # into its ancestor; and, per aggregate, a head derived from the
       # journal — never a table anything rewrites.
       #
+      # ## How a head is derived
+      #
       # For era 1 the head is a plain view (latest save per id). From
       # era 2 on, the ancestor tail is a MATERIALIZED view whose
       # definition is the compiled, chained edge sequence — one CTE per
       # original edge, in mint order, never a flattened merged rule set
       # — with the watermark baked into the definition, so post-cut
-      # old-era writes cannot leak into the new head even on REFRESH.
+      # old-era writes cannot leak into the new head even on `REFRESH`.
       # Live current-era writes overlay it through the head view.
       #
+      # ## The current-era write fence
+      #
       # Writing to a superseded schema drops the instant the new one
-      # materializes: ONE shared row policy admits INSERTs to whichever
+      # materializes: one shared row policy admits INSERTs to whichever
       # era was just established (era 1 at first hold, era N at mint),
-      # and advancing it is part of the SAME transaction that builds the
+      # and advancing it is part of the same transaction that builds the
       # new era's matview. There is no persisted per-role fork — any
-      # granted role, app or the table's own OWNER (FORCE ROW LEVEL
-      # SECURITY applies this to the owner too, not only ordinary
-      # roles), writes the current era or nothing, from the moment that
+      # granted role, app or the table's own owner
+      # (`FORCE ROW LEVEL SECURITY` applies this to the owner too, not only
+      # ordinary roles), writes the current era or nothing, from the moment that
       # transaction commits. A stale-era write during the narrow window
       # before that commit — RLS is checked once, when the statement
-      # EXECUTES, never re-checked at commit, so a transaction that
+      # executes, never re-checked at commit, so a transaction that
       # inserted while the old era was still current can still land
       # after a concurrent mint has already moved the fence on — is
-      # exactly what diverged_count/merge_tail exist to reconcile; it is
-      # the residual of an unavoidable race (ordinals are
+      # exactly what `diverged_count`/`merge_tail!` exist to reconcile; it
+      # is the residual of an unavoidable race (ordinals are
       # sequence-assigned, not transactional — see below), not a
       # supported way to keep operating two schemas side by side. Only
       # an actual Postgres superuser (or a role granted BYPASSRLS)
-      # sits above FORCE and keeps writing at will, forever.
+      # sits above `FORCE` and keeps writing at will, forever.
+      #
+      # ## Ordinal order and commit order
       #
       # Lineage order is ordinal-assignment order: the ordinal comes from a
       # sequence, and a sequence's `nextval()` is never rolled back with its
       # transaction — accepted and documented rather than papered over.
       #
-      # ONE PART OF THAT IS CLOSED. Two concurrent PLAIN writes could call
-      # `nextval()` in one order and COMMIT in the other — nothing about a
-      # single autocommit INSERT statement stops a slower one from finishing
-      # after a faster one that started later — so "ordinal order" and
-      # "commit order" were formally two different total orders even with no
-      # mint anywhere near either write. `PostgresEra#append` now holds
+      # **One part of that is closed**. Left unserialized, two concurrent
+      # plain writes can call `nextval()` in one order and COMMIT in the
+      # other — nothing about a single autocommit INSERT statement stops a
+      # slower one from finishing after a faster one that started later —
+      # which makes "ordinal order" and "commit order" formally two different
+      # total orders even with no mint anywhere near either write. So
+      # `PostgresEra#append` holds
       # `pg_advisory_xact_lock(hashtext('hecks_ordinal:' || domain))` for the
-      # length of its own transaction, a DIFFERENT key from `mint_era!` and
-      # `merge_tail!`'s `hecks_eras:domain` — so plain writes serialize
-      # against EACH OTHER only, never against a mint, and ordinal order
-      # equals commit order for them now.
+      # length of its own transaction, a different key from `mint_era!` and
+      # `merge_tail!`'s `hecks_eras:domain` — plain writes serialize against
+      # each other only, never against a mint, and ordinal order equals
+      # commit order for them.
       #
-      # THE OTHER PART IS NOT, ON PURPOSE. A stale-era write during the
-      # narrow window before a mint's fence-move commits is the SAME race by
+      # **The other part is deliberately open**. A stale-era write during the
+      # narrow window before a mint's fence-move commits is the same race by
       # a different name — and closing it would mean a plain write
       # serializing against a mint, which is exactly the guarantee
-      # `postgres_lineage_spec.rb`'s "an old checkout keeps writing its own
-      # era THROUGH a mint" pins the ABSENCE of. That race stays the
-      # residual `diverged_count`/`merge_tail!` exist to reconcile, not
-      # something a plain write should ever block for.
+      # `spec/adapters/driven/postgres_era/lineage_spec.rb`'s "an old
+      # checkout keeps writing its own era through a mint" pins the absence
+      # of. That race stays the residual `diverged_count`/`merge_tail!`
+      # exist to reconcile, not something a plain write should ever block
+      # for.
+      #
+      # ## File layout
       #
       # One concern per file under lineage/: provisioning (DDL and the
       # RLS posture), era_store (the hecks_eras rows and their integrity),
@@ -96,33 +106,118 @@ module Hecks
 
         JOURNAL_COLUMNS = "ordinal, era, aggregate, aggregate_id, operation, state, mirrors".freeze
 
+        # Postgres's own NAMEDATALEN limit: an identifier over 63 bytes is
+        # silently truncated, never refused — so two different overlong
+        # names that happen to share their first 63 bytes would collide
+        # again, at a longer length, the exact same failure mode this
+        # whole file exists to close for `storage_name` alone. Domain-
+        # qualifying every name below (`qualified_name`, private) makes
+        # that readily reachable: a long domain name stacked onto a long
+        # aggregate name. A constant, not private — Ruby constants are
+        # never actually scoped by `private`
+        # (Lint/UselessConstantScoping), so this stays above it.
+        POSTGRES_IDENTIFIER_LIMIT = 63
+
         attr_reader :db, :domain, :formerly_known_as
 
+        # @param db [PG::Connection] open connection to the database holding the domain's journal
+        # @param domain [String, Symbol] the domain's declared name; every relation name and
+        #   advisory-lock key derives from it
+        # @param formerly_known_as [String, Symbol, nil] the domain's prior name, which makes
+        #   `ensure_base!` rename its relations and rows first; nil when there is no prior name
         def initialize(db, domain, formerly_known_as: nil)
           @db = db
           @domain = domain.to_s
           @formerly_known_as = formerly_known_as&.to_s
         end
 
+        # Names the domain's one journal table, the partitioned parent of every era's rows.
+        #
+        # @return [String] unquoted relation name, `hecks_journal_` plus the snake-cased domain
         def journal = "hecks_journal_#{Naming.snake(@domain)}"
+
+        # Quotes the journal's name for direct interpolation into SQL.
+        #
+        # @return [String] `journal` as a double-quoted Postgres identifier
         def quoted_journal = quote(journal)
+
+        # Names the sequence that assigns journal ordinals across every era's partition.
+        #
+        # @return [String] unquoted sequence name, `journal` plus `_ordinal`
         def sequence = "#{journal}_ordinal"
+
+        # Names the journal partition that holds one era's rows.
+        #
+        # @param era [Integer] the era's ordinal, 1-based
+        # @return [String] unquoted relation name, `journal` plus `_era_` and the ordinal
         def partition(era) = "#{journal}_era_#{era}"
-        def head_view(storage_name) = "#{storage_name}_head"
+
+        # Names the view an aggregate's current state is read through.
+        #
+        # Domain-qualified, the same way `journal` is — see
+        # `qualified_name`'s own comment and docs/decisions/0059. Unqualified,
+        # two different domains bound to PostgresEra against the same
+        # database, each declaring an aggregate whose own name snake_cases
+        # to the same storage_name (found live: two unrelated "Note"
+        # aggregates), derive the exact same
+        # `note_head`/`note_head_snapshot_1` physical relations — every
+        # boot of the second domain silently clobbers the first's
+        # already-compiled head view, `ensure_first_head!`'s own
+        # "belt-and-suspenders self-healing" being exactly the mechanism
+        # that does it (postgres_era.rb's own comment there).
+        #
+        # @param storage_name [String] the aggregate's snake-cased storage name
+        # @return [String] unquoted view name, at most `POSTGRES_IDENTIFIER_LIMIT` bytes
+        def head_view(storage_name) = qualified_name("#{storage_name}_head")
+
+        # Names the snapshot table that backs one aggregate's head within one era.
+        #
         # The transactionally-upserted read cache behind head_view — one row
-        # per LIVE id, keyed by id, carrying the ordinal it was last written
-        # at. Scoped by ERA, not just storage_name — an aggregate that
-        # ISN'T renamed across a mint keeps the SAME storage_name in both
+        # per live id, keyed by id, carrying the ordinal it was last written
+        # at. Scoped by era, not just storage_name — an aggregate that
+        # isn't renamed across a mint keeps the same storage_name in both
         # eras, so storage_name alone would have era N+1 sharing one
         # physical table with era N: a freshly-minted era would inherit
         # every pre-mint (and, worse, pre-rekey/pre-translation) row
         # instead of starting empty. era-qualified naming is what
         # `partition`/`matview` already do for exactly this reason.
-        def head_snapshot(storage_name, era) = "#{storage_name}_head_snapshot_#{era}"
-        def matview(storage_name, era, label) = "#{storage_name}_lineage_#{era}_#{label}"
+        #
+        # @param storage_name [String] the aggregate's snake-cased storage name
+        # @param era [Integer] ordinal of the era the snapshot belongs to
+        # @return [String] unquoted table name, at most `POSTGRES_IDENTIFIER_LIMIT` bytes
+        def head_snapshot(storage_name, era) = qualified_name("#{storage_name}_head_snapshot_#{era}")
+
+        # Names the materialized view holding an aggregate's translated ancestor tail for one era.
+        #
+        # @param storage_name [String] the aggregate's snake-cased storage name
+        # @param era [Integer] ordinal of the era the view was compiled for
+        # @param label [String] the era's minted label, a prefix of its shape hash
+        # @return [String] unquoted matview name, at most `POSTGRES_IDENTIFIER_LIMIT` bytes
+        def matview(storage_name, era, label) = qualified_name("#{storage_name}_lineage_#{era}_#{label}")
 
         private
 
+        # `@domain`, snake-cased and folded onto `suffix` — human-readable
+        # in the ordinary case (every one of these names gets read
+        # directly at a psql prompt during a live incident — see
+        # docs/decisions/0059's own verification section), degrading to a
+        # hashed, truncated form only once the readable form would
+        # actually risk exceeding `POSTGRES_IDENTIFIER_LIMIT`. The same
+        # trade `Runtime::StorageShape.mint_label` (a bare hash-prefix, no
+        # attempt at readability at all — a mint label is never meant to
+        # be legible on its own) and `FieldCache#field_cache` (fully
+        # hashed, for the same reason) already make elsewhere in this
+        # adapter — this one keeps more of the readable form than either,
+        # since unlike a mint label or a field-cache table, these names
+        # are the ones an operator reads and types by hand.
+        def qualified_name(suffix)
+          full = "#{Naming.snake(@domain)}_#{suffix}"
+          return full if full.bytesize <= POSTGRES_IDENTIFIER_LIMIT
+
+          digest = Digest::SHA256.hexdigest(full)[0, 8]
+          "#{full.byteslice(0, POSTGRES_IDENTIFIER_LIMIT - digest.bytesize - 1)}_#{digest}"
+        end
+
         def quote(name) = PG::Connection.quote_ident(name.to_s)
 
         def text_literal(text) = "'#{text.to_s.gsub("'", "''")}'"

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage_manager/coverage_check.rb

@@ -10,12 +10,26 @@ module Hecks
       module LineageManager
         # What a mint must prove before it may happen: the edge covers
         # the whole diff, no identity path was re-keyed, and the audit's
-        # first two layers pass over the LIVE compiled chain.
+        # first two layers pass over the live compiled chain.
         module CoverageCheck
-          # Layer 1 against THIS edge specifically: every vanished or
+          # Refuses a mint whose translation edge leaves any part of the shape change
+          # unexplained.
+          #
+          # Layer 1 against this edge specifically: every vanished or
           # retyped path in the held→current diff must be explained, and
           # every held aggregate must still be claimed. The refusal is
           # EraGuard's own, byte for byte.
+          #
+          # @param registry [Runtime::Registry] the registry whose loaded translations may
+          #   claim a held aggregate through `was:` or `retired`
+          # @param bluebook [Bluebook::Chapter] the domain as currently declared
+          # @param held_bluebook [Bluebook::Chapter] the domain as the latest held era's
+          #   text declares it (a shadow parse)
+          # @param edge [Bluebook::Translation] the one edge leaving the latest held era
+          # @return [void]
+          # @raise [Runtime::WiringError] if an identity path changed without a `rekey`
+          #   rule, a vanished or retyped path has no rule, a new required attribute has
+          #   nothing to fill it, or a held aggregate is neither renamed nor retired
           def check_coverage!(registry, bluebook, held_bluebook, edge)
             bluebook.aggregates.each do |aggregate|
               rules = Ports::Persistence::Lineage.from_declared(edge.for_aggregate(aggregate.name), aggregate.name)
@@ -32,15 +46,28 @@ module Hecks
             Runtime::EraGuard.check_vanished_aggregates!(registry, bluebook, held_bluebook)
           end
 
-          # An identity-path change is a RE-KEYING, not an ordinary
+          # Refuses a mint that changes an aggregate's identity paths without declaring
+          # a `rekey`.
+          #
+          # An identity-path change is a re-keying, not an ordinary
           # translation — stored ids were fixed at write time under the old
-          # key, so this refuses UNLESS the edge declares a `rekey` for
+          # key, so this refuses unless the edge declares a `rekey` for
           # this aggregate covering exactly that. `rules.rekey?` (see
           # `Ports::Persistence::Lineage`'s own comment) is the single
           # source of truth every consumer of this fact asks — this is not
           # a second, independent check of `declared.rekeys`.
+          #
+          # @param bluebook [Bluebook::Chapter] the domain, named in the refusal
+          # @param aggregate [Bluebook::Aggregate] the aggregate as currently declared
+          # @param held_aggregate [Bluebook::Aggregate] the same aggregate as the held
+          #   era's text declares it
+          # @param rules [Ports::Persistence::Lineage, nil] the edge's rules for this
+          #   aggregate; nil when the edge declares none, which cannot excuse a change
+          # @return [nil] when the identity paths are unchanged or a `rekey` covers them
+          # @raise [Runtime::WiringError] if the identity paths differ and no `rekey` rule
+          #   is declared
           def check_identity_unchanged!(bluebook, aggregate, held_aggregate, rules)
-            # The FULL declared path lists, in declaration order — never the
+            # The full declared path lists, in declaration order — never the
             # single-head shortcut, which is nil for every composite identity
             # and so would let two different composites compare as unchanged.
             return if held_aggregate.identity_paths == aggregate.identity_paths
@@ -56,10 +83,28 @@ module Hecks
                   "data explicitly"
           end
 
-          # Layers 1 and 2 of the audit, over the LIVE compiled chain —
+          # Previews every aggregate's translated head through the pending chain and
+          # refuses the mint if the audit finds a violation.
+          #
+          # Layers 1 and 2 of the audit, over the live compiled chain —
           # before anything is minted, so a refusal leaves no half-born
           # era. (A convert meeting an unmapped value raises inside the
           # preview query itself: same rollback-shaped outcome.)
+          #
+          # @param bluebook [Bluebook::Chapter] the domain as currently declared
+          # @param lineage [Adapters::PostgresEra::Lineage] the domain's lineage, on an open
+          #   connection
+          # @param chain [Array<Hash{Symbol => Bluebook::Translation}>] the full edge chain
+          #   ending in `edge`, as `edge_chain` returns it
+          # @param ordinal [Integer] the ordinal of the era about to be minted
+          # @param edge [Bluebook::Translation] the pending edge, whose per-aggregate rules
+          #   the audit checks
+          # @return [nil] when no aggregate reports a violation
+          # @raise [Runtime::WiringError] if Postgres refuses the translated preview query
+          #   (a `convert` meeting an unmapped value, for one), or the audit reports any
+          #   violation; the message lists them all
+          # @raise [PG::Error] if Postgres refuses the "before" query; only the translated
+          #   preview is rescued into a `Runtime::WiringError`
           def audit!(bluebook, lineage, chain, ordinal, edge)
             violations = []
             bluebook.aggregates.each do |aggregate|