hecks 0.3.0 → 1.0.1

data/lib/hecks/{runtime → ports/persistence/plugins/era}/era_guard.rb

@@ -1,67 +1,34 @@
-require "fileutils"
 require_relative "era_guard/shape_diff"
-require_relative "../bluebook/dsl/malformed"
-require_relative "../bluebook/meta_validator"
-require_relative "../naming"
-require_relative "../ports/loading"
-require_relative "../ports/persistence/lineage"
-require_relative "era_check"
-require_relative "registry"
+require_relative "../../../../bluebook/dsl/malformed"
+require_relative "../../../../bluebook/meta_validator"
+require_relative "../../../../ports/loading"
+require_relative "../../../../runtime/registry"
 
 module Hecks
   module Runtime
-    # Detects when a bluebook's storage shape has drifted from what its data
-    # was written under — a rename or restructure with nothing to explain
-    # it. Refuses at boot, before a command can run into the gap and raise
-    # something that only makes sense once you already suspect a rename.
+    # The shape-drift coverage primitives — ADR 0032. Not a driver: nothing
+    # here walks a registry or reads/writes a held snapshot on its own.
+    # `PostgresEra::LineageManager::CoverageCheck` calls `uncovered_
+    # attributes`/`unsafe_additions`/`refuse_uncovered!`/`refuse_unsafe_
+    # addition!`/`check_vanished_aggregates!` directly, per translation
+    # edge, over its own DB-held shapes; `Translation::Reattest` and
+    # `PostgresEra::LineageManager` call `shadow_parse` directly, to read
+    # historical bluebook text under old grammar defaults. Both are real,
+    # independent, currently-shipped consumers.
     #
-    # The held source is a snapshot of the bluebook text as it stood the
-    # last time its shape was accepted. It updates only when a drift is
-    # seen AND covered by a translation — never on every boot, and never
-    # silently when a rename has nothing to explain it.
+    # A prior version of this module ALSO drove its own top-level check —
+    # `check!`/`check_bluebook!`, walking a registry and reading/writing a
+    # held snapshot under `data/eras/*.bluebook` — duplicating, on its own,
+    # the same per-aggregate walk `CoverageCheck` already performs against
+    # `PostgresEra`'s own DB-held shapes. Nothing in production ever called
+    # it (only a direct unit spec did); deleted rather than kept unwired,
+    # per ADR 0032. Wanted again, it's rebuilt informed by `CoverageCheck`'s
+    # real orchestration, not resurrected from here.
     module EraGuard
       extend ShapeDiff
 
       module_function
 
-      def check!(registry, directory)
-        registry.bluebooks.each_value { |bluebook| check_bluebook!(registry, bluebook, directory) }
-      end
-
-      def check_bluebook!(registry, bluebook, directory)
-        current_text = EraCheck.source_text_for(bluebook, directory)
-        return unless current_text
-
-        era_dir   = File.join(registry.root, "data", "eras")
-        held_path = File.join(era_dir, "#{Naming.snake(bluebook.name)}.bluebook")
-
-        FileUtils.mkdir_p(era_dir)
-        unless File.exist?(held_path)
-          File.write(held_path, current_text)
-          return
-        end
-
-        held_bluebook = shadow_parse(File.read(held_path, encoding: "UTF-8"), held_path)
-        drifted = false
-
-        bluebook.aggregates.each do |aggregate|
-          lineage = Ports::Persistence::Lineage.for(registry, bluebook.name, aggregate)
-          held_aggregate = held_bluebook.aggregate(lineage&.ancestor_name || aggregate.name)
-          next unless held_aggregate
-          next if shape(aggregate) == shape(held_aggregate)
-
-          drifted = true
-          uncovered = uncovered_attributes(aggregate, held_aggregate, lineage)
-          refuse_uncovered!(bluebook, aggregate, uncovered) unless uncovered.empty?
-
-          unsafe = unsafe_additions(aggregate, held_aggregate, lineage)
-          refuse_unsafe_addition!(bluebook, aggregate, unsafe) unless unsafe.empty?
-        end
-
-        check_vanished_aggregates!(registry, bluebook, held_bluebook)
-        File.write(held_path, current_text) if drifted
-      end
-
       # An aggregate that existed in the held text and answers to no
       # current name — renamed silently, with nothing declaring `was:` to
       # explain where its data went — is exactly the disease this guards
@@ -87,8 +54,9 @@ module Hecks
         end
       end
 
-      # The Layer-1 coverage refusal — one wording, whoever detects the
-      # gap (the file-store boot check here, or Postgres's mint path).
+      # The Layer-1 coverage refusal — one wording, shared with whoever
+      # calls it (today, `PostgresEra::LineageManager::CoverageCheck`'s
+      # own mint-time coverage check).
       def refuse_uncovered!(bluebook, aggregate, uncovered)
         raise WiringError,
               "cannot boot #{bluebook.name}::#{aggregate.name}: its shape changed and " \

data/lib/hecks/ports/persistence/{lineage.rb → plugins/era/lineage.rb}

@@ -1,6 +1,6 @@
-require_relative "../../naming"
-require_relative "append_only"
-require_relative "../../runtime/registry"
+require_relative "../../../../naming"
+require_relative "../../append_only"
+require_relative "../../../../runtime/registry"
 
 module Hecks
   module Ports
@@ -91,7 +91,7 @@ module Hecks
           # value-object hash, and a shallow dup would quietly mutate
           # the caller's copy of the original entry.
           state = deep_dup(entry.state)
-          @renames.each { |old_name, new_name| state[new_name] = state.delete(old_name) if state.key?(old_name) }
+          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) }
@@ -183,6 +183,33 @@ module Hecks
           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)

data/lib/hecks/{adapters/driven → ports/persistence/plugins/era}/postgres_era/lineage/era_store.rb

@@ -1,6 +1,6 @@
-require_relative "../../../../runtime/era_tamper"
-require_relative "../../../../runtime/registry"
-require_relative "../../../../runtime/storage_shape"
+require_relative "../../era_tamper"
+require_relative "../../../../../../runtime/registry"
+require_relative "../../storage_shape"
 
 module Hecks
   module Adapters

data/lib/hecks/{adapters/driven → ports/persistence/plugins/era}/postgres_era/lineage/head_compiler.rb

@@ -1,5 +1,5 @@
-require_relative "../../../../naming"
-require_relative "../../../../translation/rule_compiler"
+require_relative "../../../../../../naming"
+require_relative "../../translation/rule_compiler"
 
 module Hecks
   module Adapters
@@ -67,15 +67,41 @@ module Hecks
                 @db.exec_params("SELECT pg_advisory_xact_lock(hashtext('hecks_head_snapshot:' || $1))", [name])
                 next if table_exists?(name)
 
+                # `operation` + a NULLABLE `state` — H3, docs/audits/2026-08-
+                # 10-main-bug-audit.md: a delete used to just `DELETE FROM`
+                # this table, leaving NO row at all for an id carried in
+                # from an ancestor era. `compile_head!`'s union below then
+                # had nothing current-era to outrank the ancestor
+                # matview's own (still-live-looking) `save` row with, so a
+                # deleted ancestor-carried record kept winning `DISTINCT
+                # ON` forever. A delete now upserts a TOMBSTONE row here
+                # instead (`operation = 'delete'`, `state` NULL) — the
+                # exact same ordinal-guarded upsert every write already
+                # uses, so it participates in the union/`DISTINCT ON`
+                # exactly like a save does, and out-ranks the ancestor row
+                # by ordinal the same way a real re-save already did
+                # ("re-saves are masked correctly" — the audit's own
+                # phrasing for why this half of the read path was never
+                # broken).
                 @db.exec(<<~SQL)
                   CREATE TABLE #{quote(name)} (
-                    id      text PRIMARY KEY,
-                    ordinal bigint NOT NULL,
-                    state   jsonb NOT NULL
+                    id        text PRIMARY KEY,
+                    ordinal   bigint NOT NULL,
+                    operation text NOT NULL DEFAULT 'save',
+                    state     jsonb
                   )
                 SQL
               end
             end
+            # SELF-HEALING for a table this ADR predates — same idiom as
+            # `postgres/schema_builder.rb`'s own `hecks_version` backfill:
+            # unconditional, runs on every boot, a no-op once the column
+            # is there. A table created before H3's fix has no
+            # `operation` column and a `state NOT NULL` constraint a
+            # tombstone's NULL state would violate; both are corrected
+            # here regardless of which branch above just ran.
+            @db.exec("ALTER TABLE #{quote(name)} ADD COLUMN IF NOT EXISTS operation text NOT NULL DEFAULT 'save'")
+            @db.exec("ALTER TABLE #{quote(name)} ALTER COLUMN state DROP NOT NULL")
             backfill_head_snapshot!(name, storage_name, era)
           end
 
@@ -105,10 +131,13 @@ module Hecks
               end,
               upsert:     lambda do |rows|
                 rows.each do |row|
+                  # Always `'save'` — `source_sql` above already filtered
+                  # to `operation = 'save'`, so nothing this backfill ever
+                  # sees is a delete tombstone.
                   @db.exec_params(
-                    "INSERT INTO #{quote(name)} (id, ordinal, state) VALUES ($1, $2, $3) " \
-                    "ON CONFLICT (id) DO UPDATE SET ordinal = EXCLUDED.ordinal, state = EXCLUDED.state " \
-                    "WHERE #{quote(name)}.ordinal < EXCLUDED.ordinal",
+                    "INSERT INTO #{quote(name)} (id, ordinal, operation, state) VALUES ($1, $2, 'save', $3) " \
+                    "ON CONFLICT (id) DO UPDATE SET ordinal = EXCLUDED.ordinal, operation = EXCLUDED.operation, " \
+                    "state = EXCLUDED.state WHERE #{quote(name)}.ordinal < EXCLUDED.ordinal",
                     [row["id"], row["ordinal"], row["state"]]
                   )
                 end
@@ -149,9 +178,15 @@ module Hecks
           # already keeps the snapshot current as of every write.
           def ensure_first_head!(storage_name)
             ensure_head_snapshot!(storage_name, 1)
+            # `WHERE operation = 'save'` — era 1 has no ancestor tail to
+            # worry about, but the snapshot table can now hold delete
+            # tombstones too (H3, see `ensure_head_snapshot!`'s own
+            # comment), and a tombstone's `state` is NULL: without this
+            # filter a deleted id would still resolve here, just to a nil
+            # state, instead of correctly falling out of the head at all.
             @db.exec(<<~SQL)
               CREATE OR REPLACE VIEW #{quote(head_view(storage_name))} AS
-              SELECT id, state FROM #{quote(head_snapshot(storage_name, 1))}
+              SELECT id, state FROM #{quote(head_snapshot(storage_name, 1))} WHERE operation = 'save'
             SQL
           end
 
@@ -359,13 +394,27 @@ module Hecks
             # under this era specifically.
             ensure_head_snapshot!(storage_name, era)
             @db.exec("DROP VIEW IF EXISTS #{quote(head_view(storage_name))}")
+            # THE CURRENT-ERA SIDE READS ITS OWN `operation` COLUMN NOW —
+            # H3 (docs/audits/2026-08-10-main-bug-audit.md). This used to
+            # hardcode `'save' AS operation` here, on the reasoning that a
+            # delete simply removed its row from the snapshot table. But
+            # for an id carried in from an ancestor era, that left the
+            # ancestor matview's own `save` row as the ONLY row on either
+            # side of this union — which then won `DISTINCT ON` and
+            # `WHERE operation = 'save'` let it straight through, so a
+            # deleted ancestor-carried record kept resurrecting forever.
+            # The snapshot side now upserts a real tombstone row on
+            # delete (`ensure_head_snapshot!`'s own comment) instead of
+            # deleting the row, so reading its actual `operation` here
+            # lets that tombstone outrank the stale ancestor `save` row
+            # by ordinal, exactly the way a genuine re-save already did.
             @db.exec(<<~SQL)
               CREATE VIEW #{quote(head_view(storage_name))} AS
               SELECT id, state FROM (
                 SELECT DISTINCT ON (aggregate_id) aggregate_id AS id, operation, state FROM (
                   SELECT ordinal, aggregate_id, operation, state FROM #{quote(view)}
                   UNION ALL
-                  SELECT ordinal, id AS aggregate_id, 'save' AS operation, state
+                  SELECT ordinal, id AS aggregate_id, operation, state
                   FROM #{quote(head_snapshot(storage_name, era))}
                 ) merged ORDER BY aggregate_id, ordinal DESC
               ) latest WHERE operation = 'save'

data/lib/hecks/{adapters/driven → ports/persistence/plugins/era}/postgres_era/lineage/mint_transaction.rb

@@ -1,5 +1,5 @@
-require_relative "../../../../runtime/registry"
-require_relative "../../../../runtime/storage_shape"
+require_relative "../../../../../../runtime/registry"
+require_relative "../../storage_shape"
 
 module Hecks
   module Adapters

data/lib/hecks/{adapters/driven → ports/persistence/plugins/era}/postgres_era/lineage/provisioning.rb

@@ -78,7 +78,35 @@ module Hecks
             # to revoke them from the owner itself); a deployment's app
             # role connects as a NON-owner and gets exactly INSERT, per
             # era, at mint time.
-            @db.exec("REVOKE UPDATE, DELETE ON #{quoted_journal} FROM PUBLIC")
+            #
+            # GUARDED, same reasoning as the RLS ALTER TABLE calls just
+            # below: REVOKE still writes pg_class.relacl (and takes the
+            # matching lock) even when the resulting privileges are
+            # unchanged, so an unconditional reissue on every ordinary
+            # reboot raced two concurrent boots into
+            # `PG::InternalError: tuple concurrently updated` — read
+            # first, touch the catalog only on the boot that actually
+            # needs to.
+            #
+            # `relacl IS NULL`, not `has_table_privilege('public', ...,
+            # 'UPDATE')` — found live, not assumed: a brand-new table's
+            # PUBLIC privilege is already "no UPDATE" by Postgres's own
+            # default (nothing has ever been explicitly granted to
+            # PUBLIC), so `has_table_privilege` answers false BOTH before
+            # the REVOKE has ever run AND after it has — indistinguishable
+            # by that check alone, which meant the very first boot's own
+            # REVOKE never actually ran, `relacl` stayed NULL forever, and
+            # "journal rows accept no UPDATE/DELETE from PUBLIC" was true
+            # only by accident of Postgres's default, not by the explicit
+            # privilege revocation this method exists to record.
+            # `relacl IS NULL` means "default ACL, nothing explicit yet" —
+            # exactly the one-time signal needed, and (like the RLS flags
+            # below) `pg_table_is_visible(oid)`, not a bare relname match,
+            # for the same shared-instance/storehouse reason.
+            relacl_null = @db.exec_params(
+              "SELECT relacl IS NULL FROM pg_class WHERE relname = $1 AND pg_table_is_visible(oid)", [journal]
+            ).getvalue(0, 0)
+            @db.exec("REVOKE UPDATE, DELETE ON #{quoted_journal} FROM PUBLIC") if relacl_null == "t"
             # RLS goes on AT PROVISIONING, never mid-life — enabling it
             # later would deny every role that has no policy yet, on
             # whatever the shape of the schema happened to be at that

data/lib/hecks/{adapters/driven → ports/persistence/plugins/era}/postgres_era/lineage/tail_merge.rb

@@ -1,4 +1,4 @@
-require_relative "../../../../runtime/registry"
+require_relative "../../../../../../runtime/registry"
 
 module Hecks
   module Adapters
@@ -74,6 +74,7 @@ module Hecks
               compile_head!(aggregate, era, label, edges, full: true)
             end
 
+            # rubocop:disable-next Metrics/BlockLength
             winners.each do |id, side|
               aggregates.each do |aggregate|
                 state =
@@ -101,10 +102,16 @@ module Hecks
                   "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.
                 @db.exec_params(
-                  "INSERT INTO #{quote(head_snapshot(aggregate.storage_name, era))} (id, ordinal, state) VALUES ($1, $2, $3) " \
-                  "ON CONFLICT (id) DO UPDATE SET ordinal = EXCLUDED.ordinal, state = EXCLUDED.state " \
-                  "WHERE #{quote(head_snapshot(aggregate.storage_name, era))}.ordinal < EXCLUDED.ordinal",
+                  "INSERT INTO #{quote(head_snapshot(aggregate.storage_name, era))} (id, ordinal, operation, state) " \
+                  "VALUES ($1, $2, 'save', $3) " \
+                  "ON CONFLICT (id) DO UPDATE SET ordinal = EXCLUDED.ordinal, operation = EXCLUDED.operation, " \
+                  "state = EXCLUDED.state WHERE #{quote(head_snapshot(aggregate.storage_name, era))}.ordinal < EXCLUDED.ordinal",
                   [id, ordinal, state]
                 )
               end

data/lib/hecks/{adapters/driven → ports/persistence/plugins/era}/postgres_era/lineage/transform_installer.rb

@@ -7,7 +7,27 @@ module Hecks
           # 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.
           def install_transforms!
+            nested_transaction("hecks_tr_functions") do
+              @db.exec_params("SELECT pg_advisory_xact_lock(hashtext('hecks_tr_functions'))", [])
+              install_transform_functions!
+            end
+          end
+
+          def install_transform_functions!
             @db.exec(<<~SQL)
               CREATE OR REPLACE FUNCTION hecks_tr_extract(state jsonb, path text[], OUT remaining jsonb, OUT value jsonb, OUT present boolean)
               LANGUAGE plpgsql IMMUTABLE AS $fn$

data/lib/hecks/{adapters/driven → ports/persistence/plugins/era}/postgres_era/lineage.rb

@@ -9,7 +9,7 @@ require_relative "lineage/resumable_backfill"
 require_relative "lineage/head_compiler"
 require_relative "lineage/field_cache"
 require_relative "lineage/transform_installer"
-require_relative "../../../naming"
+require_relative "../../../../../naming"
 
 module Hecks
   module Adapters

data/lib/hecks/{adapters/driven → ports/persistence/plugins/era}/postgres_era/lineage_manager/coverage_check.rb

@@ -1,8 +1,8 @@
-require_relative "../../../../ports/persistence/lineage"
-require_relative "../../../../runtime/era_guard"
-require_relative "../../../../runtime/identity"
-require_relative "../../../../runtime/registry"
-require_relative "../../../../translation/audit"
+require_relative "../../lineage"
+require_relative "../../era_guard"
+require_relative "../../../../../../runtime/identity"
+require_relative "../../../../../../runtime/registry"
+require_relative "../../translation/audit"
 
 module Hecks
   module Adapters

data/lib/hecks/{adapters/driven → ports/persistence/plugins/era}/postgres_era/lineage_manager/era_resolver.rb

@@ -1,5 +1,5 @@
 require_relative "../lineage"
-require_relative "../../../../runtime/storage_shape"
+require_relative "../../storage_shape"
 
 module Hecks
   module Adapters
@@ -14,7 +14,10 @@ module Hecks
             db = PostgresEra.connect_for(bluebook.name, settings)
             lineage = Lineage.new(db, bluebook.name, formerly_known_as: bluebook.formerly_known_as)
             lineage.ensure_base!
-            role = settings[:role] || settings["role"]
+            # Both spellings honored, key? first — never `||`, which cannot
+            # tell a genuinely stored `false` apart from an absent key (see
+            # PostgresEra.setting's own comment for the full reasoning).
+            role = settings.key?(:role) ? settings[:role] : settings["role"]
 
             held = lineage.eras
             if held.empty?

data/lib/hecks/{adapters/driven → ports/persistence/plugins/era}/postgres_era/lineage_manager/merge_coordinator.rb

@@ -1,6 +1,6 @@
 require_relative "../lineage"
-require_relative "../../../../runtime/registry"
-require_relative "../../../../translation/audit"
+require_relative "../../../../../../runtime/registry"
+require_relative "../../translation/audit"
 
 module Hecks
   module Adapters

data/lib/hecks/{adapters/driven → ports/persistence/plugins/era}/postgres_era/lineage_manager/minter.rb

@@ -1,7 +1,7 @@
-require_relative "../../../../runtime/registry"
-require_relative "../../../../runtime/storage_shape"
-require_relative "../../../../translation/audit"
-require_relative "../../../../translation/scaffold"
+require_relative "../../../../../../runtime/registry"
+require_relative "../../storage_shape"
+require_relative "../../translation/audit"
+require_relative "../../translation/scaffold"
 
 module Hecks
   module Adapters

data/lib/hecks/{adapters/driven → ports/persistence/plugins/era}/postgres_era/lineage_manager.rb

@@ -4,8 +4,8 @@ require_relative "lineage_manager/era_resolver"
 require_relative "lineage_manager/minter"
 require_relative "lineage_manager/merge_coordinator"
 require_relative "lineage_manager/coverage_check"
-require_relative "../../../runtime/era_guard"
-require_relative "../../../runtime/registry"
+require_relative "../era_guard"
+require_relative "../../../../../runtime/registry"
 
 module Hecks
   module Adapters