hecks 2.7.0 → 2.9.0

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

@@ -2,67 +2,12 @@ module Hecks
   module Adapters
     class PostgresEra
       class Lineage
-        # 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
-        # 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 +
-        # 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
-        # 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
-        # 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
-        # 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
-        # large backfill cheap to recover from instead of starting over.
-        #
-        # ## 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
-        # 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
-        # transaction, never across the whole backfill — two concurrent
-        # 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.
+        # Chunked, lock-free, resumable backfill loop shared by the head-snapshot backfill and each
+        # field-cache table's initial backfill.
         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
+          # Creates `hecks_backfill_progress`, the per-target cursor table, if absent.
           def ensure_backfill_progress_table!
             @db.exec(<<~SQL)
               CREATE TABLE IF NOT EXISTS hecks_backfill_progress (
@@ -76,40 +21,11 @@ module Hecks
 
           # 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.
-          #
-          #   source_sql.call(cursor) — given the last-processed id (nil
-          #     before the first chunk), returns a SQL SELECT whose result
-          #     has an `id` column (text, ordered ascending) plus whatever
-          #     other columns `upsert` below needs. Must read `id >
-          #     cursor` (or unconditional when cursor is nil), `ORDER BY
-          #     id`, `LIMIT CHUNK_SIZE` — the caller owns the actual
-          #     column list/source tables; this method only owns the loop,
-          #     the lock, and the cursor.
-          #
-          #   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
-          #     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.
+          # `source_sql` takes the last id (nil before the first chunk) and returns a SELECT
+          # with an ascending text `id` column, `id > cursor`, `LIMIT CHUNK_SIZE`. `upsert`
+          # takes the chunk's PG::Result and runs in the cursor update's transaction.
           #
-          # @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
+          # @raise [PG::Error] on a failed read or cursor update; `upsert` errors roll back
           def chunked_backfill!(target, source_sql:, upsert:)
             ensure_backfill_progress_table!
             loop do
@@ -120,21 +36,16 @@ module Hecks
 
           private
 
-          # 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
-          # chunk another process just committed. Harmless either way
-          # (idempotent, ordinal-guarded) but the re-read is what keeps
-          # two concurrent boots from both doing the full scan instead of
-          # splitting it.
+          # One chunk, one transaction. Progress is re-read under the lock: a concurrent booter may
+          # have committed this chunk while we waited.
           def run_chunk!(target, source_sql:, upsert:)
             progress = backfill_progress(target)
             return true if progress[:completed]
 
             completed = false
             nested_transaction("hecks_backfill_chunk") do
+              # Prefix is disjoint from the ordinal/era/head-snapshot lock keys, so a chunk
+              # never blocks a write or a mint.
               @db.exec_params("SELECT pg_advisory_xact_lock(hashtext('hecks_field_cache:' || $1))", [target])
               progress = backfill_progress(target)
               if progress[:completed]
@@ -151,20 +62,14 @@ module Hecks
 
               upsert.call(rows)
               completed = rows.ntuples < CHUNK_SIZE
-              # `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.
+              # `PG::Result#[]` rejects negative indexes, so index the last row explicitly.
               last_cursor = rows[rows.ntuples - 1]["id"]
               upsert_backfill_progress!(target, cursor: last_cursor, completed: completed)
             end
             completed
           end
 
-          # `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
-          # target's very first check) cannot be read via a bare `[0]`.
-          # `ntuples.zero?` first, always.
+          # `PG::Result#[]` raises IndexError out of range, so check `ntuples.zero?` before `[0]`.
           def backfill_progress(target)
             result = @db.exec_params(
               "SELECT cursor, completed FROM hecks_backfill_progress WHERE target = $1", [target]

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

@@ -4,21 +4,12 @@ module Hecks
   module Adapters
     class PostgresEra
       class Lineage
-        # The one deliberate, human-driven command that closes a fork:
-        # `merge_tail!` re-enters an old era's post-cut writes into the
-        # current era under named winners, and `diverged_count` observes how
-        # far the two worlds have drifted at any time before that.
+        # `merge_tail!` closes a fork: an old era's post-cut writes re-enter under named winners;
+        # `diverged_count` measures the drift before that.
         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
+          # @return [Integer] 0 when the domain holds no 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)
@@ -29,41 +20,18 @@ module Hecks
             )[0]["count"].to_i
           end
 
-          # ── tail-merge ─────────────────────────────────────────────────
-          #
-          # Folds every old era's post-cut writes into the current era's heads, under named winners.
+          # Folds every old era's post-cut writes into the current era's heads, under 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
-          # recorded global ordinal, append the declared winners, audit —
-          # and roll the whole thing back on any refusal. Records touched
-          # by both worlds since the cut refuse until each has an explicit
-          # winner; resolution itself is append-only (the winner's state
-          # re-enters as the newest row and wins structurally — originals
-          # stay immutable).
+          # One transaction; any refusal rolls back. Records both worlds touched need a winner.
           # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
-          # 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.
+          # One transaction with a manual `ROLLBACK` at each refusal, and `new_states` must be
+          # captured before the head rebuild; splitting the steps would scatter both.
           #
-          # @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
+          # @param aggregates [Array<Bluebook::Aggregate>] the current bluebook's aggregates
+          # @param edges [Array<Hash>] the mint-order edge chain, from `LineageManager.edge_chain`
+          # @param winners [Hash{String => String}] aggregate id to `"old"` or `"new"`
+          # @param audit [#call, nil] returns violations (Array<String>); run before `COMMIT`
+          # @raise [Runtime::WiringError] at era 1, an unresolved conflict, audit or lock failure
           def merge_tail!(aggregates:, edges:, winners: {}, audit: nil)
             @db.exec("BEGIN")
             @db.exec("SET LOCAL lock_timeout = '10s'")
@@ -125,23 +93,14 @@ module Hecks
                   end
                 next unless state
 
-                # Same two-step append does for a live write — journal
-                # first, snapshot second — because this INSERT bypasses
-                # PostgresEra#append entirely (it writes through Lineage
-                # directly). Skipping the snapshot half here would mean a
-                # merge winner lands in the journal but head_view — which
-                # reads this era's live rows from the snapshot table, not
-                # by re-scanning the journal — never shows it.
+                # Journal first, snapshot second, as a live write does: this INSERT bypasses
+                # PostgresEra#append, and head_view reads live rows from the snapshot table.
                 ordinal = @db.exec_params(
                   "INSERT INTO #{quoted_journal} (era, aggregate, aggregate_id, operation, state) " \
                   "VALUES ($1, $2, $3, 'save', $4) RETURNING ordinal",
                   [era, aggregate.storage_name, id, state]
                 )[0]["ordinal"]
-                # Always `'save'` — a merge winner is read from either
-                # the matview's own `operation = 'save'` rows or the new
-                # world's live head (`new_states`, captured from
-                # `head_view`, which is save-only by construction), so
-                # nothing reaching this INSERT is ever a delete.
+                # Always 'save': winners come from save-only sources, never a delete.
                 @db.exec_params(
                   "INSERT INTO #{quote(head_snapshot(aggregate.storage_name, era))} (id, ordinal, operation, state) " \
                   "VALUES ($1, $2, 'save', $3) " \
@@ -182,26 +141,10 @@ 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
-          # post-cut tail INTERSECTed with the new world's own writes.
+          # Ids written by both worlds since the cut, as `[storage_name, aggregate_id]` pairs.
           #
-          # 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
-          # 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
-          # about a rekey mapping is real, separate work, deliberately
-          # out of scope for rekey's first pass.
-          # @param aggregate [Bluebook::Aggregate] the aggregate to check for conflicting ids
-          # @param edges [Hash] the fork's own era edges, as `names_by_era` reads them
-          # @param era [Integer] the new world's own era
-          # @param cut [Integer] the ordinal the fork happened at
-          # @return [Array<Array(String, String)>] `[storage_name, aggregate_id]` pairs touched
-          #   by both worlds since the cut
+          # 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)
             olds = (1...era).map { |ancestor| text_literal(names[:storage][ancestor - 1]) }.join(", ")

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

@@ -2,32 +2,14 @@ module Hecks
   module Adapters
     class PostgresEra
       class Lineage
-        # Installs the shared, domain-independent `hecks_tr_*` Postgres
-        # functions (extract/insert/rename/move/convert/drop over jsonb)
-        # that a compiled translation rule set's SQL calls into — the SQL
-        # compilation target kept equal to the Ruby reference transform by
-        # the cross-execution equivalence spec, never a second source of
-        # truth.
+        # Installs the shared `hecks_tr_*` jsonb functions that compiled translation SQL calls;
+        # kept equal to the Ruby reference transform by the equivalence spec.
         module TransformInstaller
-          # Installs or replaces the six `hecks_tr_*` functions under a database-wide advisory lock.
+          # Installs or replaces the six `hecks_tr_*` functions under a database-wide 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
-          # 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
-          # 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
-          # graceful no-op. `nested_transaction` is the same
-          # 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.
+          # Locked because `CREATE OR REPLACE FUNCTION` rewrites the `pg_proc` row, so concurrent
+          # boots of any two domains (the functions are global) can hit
+          # `tuple concurrently updated`.
           #
           # @return [void]
           # @raise [PG::Error] if Postgres refuses the lock or a function definition
@@ -38,21 +20,7 @@ module Hecks
             end
           end
 
-          # 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
-          # 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
+          # Runs the six definitions without a lock; `install_transforms!` is the locked entry.
           def install_transform_functions!
             install_hecks_tr_extract!
             install_hecks_tr_insert!
@@ -96,16 +64,8 @@ module Hecks
             SQL
           end
 
-          # **Adversarial finding**: a destination whose top segment already
-          # holds a value — most commonly a reference, a bare scalar id
-          # — 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.
+          # Refuses to nest under a non-object value (such as a reference id): overwriting it would
+          # be an undeclared drop. The Ruby reference transform's `insert` raises the same 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

@@ -14,86 +14,8 @@ require_relative "../../../../../naming"
 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
-      # 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
-      # 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`.
-      # 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
-      # 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
-      # 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
-      # 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
-      # 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
-      # 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.
-      #
-      # ## 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**. 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` — plain writes serialize against
-      # each other only, never against a mint, and ordinal order equals
-      # commit order for them.
-      #
-      # **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
-      # `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),
-      # mint_transaction (the one transaction that makes an era real),
-      # tail_merge (the one deliberate merge command), resumable_backfill
-      # (the one chunked/lock-free/resumable scan loop, shared by
-      # head_compiler's own backfill and field_cache's), head_compiler
-      # (the chained-edge SQL a head derives through), field_cache (the
-      # per-where-field read cache that lets a query skip the reduction
-      # entirely), transform_installer (the hecks_tr_* jsonb helpers).
+      # The lineage topology inside one Postgres database: a journal per domain, partitioned by
+      # era, with each aggregate's head derived from it rather than stored.
       class Lineage
         include Provisioning
         include EraStore
@@ -106,16 +28,7 @@ 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.
+        # Longer identifiers are silently truncated by Postgres, so `qualified_name` hashes them.
         POSTGRES_IDENTIFIER_LIMIT = 63
 
         attr_reader :db, :domain, :formerly_known_as
@@ -154,17 +67,7 @@ module Hecks
 
         # 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).
+        # Domain-qualified so two domains sharing an aggregate name do not clobber each other.
         #
         # @param storage_name [String] the aggregate's snake-cased storage name
         # @return [String] unquoted view name, at most `POSTGRES_IDENTIFIER_LIMIT` bytes
@@ -172,15 +75,7 @@ module Hecks
 
         # 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
-        # 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.
+        # Era-scoped so a new era starts empty, not with the previous era's rows.
         #
         # @param storage_name [String] the aggregate's snake-cased storage name
         # @param era [Integer] ordinal of the era the snapshot belongs to
@@ -197,19 +92,7 @@ module Hecks
 
         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.
+        # Snake-cased domain folded onto `suffix`; hashed and truncated only past the length limit.
         def qualified_name(suffix)
           full = "#{Naming.snake(@domain)}_#{suffix}"
           return full if full.bytesize <= POSTGRES_IDENTIFIER_LIMIT