hecks 1.0.2 → 1.1.0

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

@@ -2,6 +2,12 @@ module Hecks
   module Adapters
     class PostgresEra
       class Lineage
+        # Owner-only schema bootstrap: creates the lineage tables
+        # (`hecks_eras`, `hecks_era_texts`, `hecks_approvals`, the
+        # partitioned journal), sets up its RLS fence, bridges a renamed
+        # domain's history (`rename_domain!`), and attaches each era's
+        # journal partition (`ensure_partition!`) — the build-then-ATTACH
+        # dance that keeps a mint from stopping every writer.
         module Provisioning
           # Provisioning is the OWNER's job, and a deployment's app role is
           # deliberately not the owner — it may append and read, and it
@@ -13,6 +19,15 @@ module Hecks
           # grant_era! exists to constrain could never finish booting
           # ("must be owner of table hecks_eras"). A fence nothing can
           # reach is not a fence.
+          # One bootstrap sequence of DDL, order-dependent throughout —
+          # every guarded ALTER (RLS, REVOKE) is guarded and placed
+          # exactly where it is for measured, documented reasons (see the
+          # inline comments on each: catalog-lock avoidance, RLS timing,
+          # FORCE semantics). Splitting this into smaller methods would
+          # only hide that single ordered sequence behind several call
+          # sites, with nothing gained — each statement already reads as
+          # one step, and the length here is DDL, not branching logic.
+          # rubocop:disable-next Metrics/MethodLength
           def ensure_base!
             rename_domain! if @formerly_known_as
             return unless provisioner?
@@ -183,6 +198,16 @@ module Hecks
           # Anything else (no rows under either name) falls through
           # harmlessly — `formerly_known_as` pointing at a name with no
           # held history is not an error, just inert.
+          # One transactional migration, whose own comment above spells
+          # out a three-way precheck and a FIXED lock-acquisition order
+          # (old before new, eras before ordinal) chosen specifically to
+          # avoid a deadlock against a concurrent rename/mint/write.
+          # Splitting this would separate the precheck from the locking
+          # from the renames from the commit/rollback handling — each a
+          # piece of ONE transaction that must stay in this exact order
+          # or the deadlock-avoidance guarantee stops holding.
+          # rubocop:disable-next Metrics/AbcSize
+          # rubocop:disable-next Metrics/MethodLength
           def rename_domain!
             return unless @db.exec_params("SELECT to_regclass($1)", ["hecks_eras"])[0]["to_regclass"]
             return if @db.exec_params(
@@ -236,17 +261,30 @@ module Hecks
             # ensure_base! at all — only lazily, on first reattest! — so a
             # domain that never needed one must not be forced through an
             # UPDATE against a table that doesn't exist.
-            @db.exec_params("UPDATE hecks_attestations SET domain = $1 WHERE domain = $2", [@domain, @formerly_known_as]) if @db.exec_params("SELECT to_regclass($1)", ["hecks_attestations"])[0]["to_regclass"]
+            if @db.exec_params(
+              "SELECT to_regclass($1)", ["hecks_attestations"]
+            )[0]["to_regclass"]
+              @db.exec_params("UPDATE hecks_attestations SET domain = $1 WHERE domain = $2",
+                              [@domain, @formerly_known_as])
+            end
 
             @db.exec("COMMIT")
           rescue PG::LockNotAvailable
-            @db.exec("ROLLBACK") rescue nil
+            begin
+              @db.exec("ROLLBACK")
+            rescue StandardError
+              nil
+            end
             raise Runtime::WiringError,
                   "cannot rename #{@formerly_known_as} to #{@domain}: another rename, mint, or write holds " \
                   "one of the domain locks — waited 10s; try again shortly"
-          rescue PG::Error => error
-            @db.exec("ROLLBACK") rescue nil
-            raise Runtime::WiringError, "cannot rename #{@formerly_known_as} to #{@domain}: #{error.message.strip}"
+          rescue PG::Error => e
+            begin
+              @db.exec("ROLLBACK")
+            rescue StandardError
+              nil
+            end
+            raise Runtime::WiringError, "cannot rename #{@formerly_known_as} to #{@domain}: #{e.message.strip}"
           end
 
           # Nothing provisioned yet — build it. Provisioned and owned —

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

@@ -4,6 +4,10 @@ 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.
         module TailMerge
           # ── fork observability ─────────────────────────────────────────
 
@@ -29,6 +33,14 @@ module Hecks
           # winner; resolution itself is append-only (the winner's state
           # 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
+          # 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.
           def merge_tail!(aggregates:, edges:, winners: {}, audit: nil)
             @db.exec("BEGIN")
             @db.exec("SET LOCAL lock_timeout = '10s'")
@@ -129,14 +141,23 @@ module Hecks
             @db.exec("COMMIT")
             true
           rescue PG::LockNotAvailable
-            @db.exec("ROLLBACK") rescue nil
+            begin
+              @db.exec("ROLLBACK")
+            rescue StandardError
+              nil
+            end
             raise Runtime::WiringError,
                   "cannot merge the tail of #{@domain}: another mint or merge holds the domain lock — " \
                   "waited 10s; try again shortly"
-          rescue PG::Error => error
-            @db.exec("ROLLBACK") rescue nil
-            raise Runtime::WiringError, "cannot merge the tail of #{@domain}: #{error.message.strip}"
+          rescue PG::Error => e
+            begin
+              @db.exec("ROLLBACK")
+            rescue StandardError
+              nil
+            end
+            raise Runtime::WiringError, "cannot merge the tail of #{@domain}: #{e.message.strip}"
           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.

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

@@ -2,6 +2,12 @@ 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.
         module TransformInstaller
           # The jsonb rule transforms — installed once, idempotently. Kept
           # equal to the port's reference entry-JSON transform by the
@@ -27,7 +33,26 @@ module Hecks
             end
           end
 
+          # 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.
           def install_transform_functions!
+            install_hecks_tr_extract!
+            install_hecks_tr_insert!
+            install_hecks_tr_rename!
+            install_hecks_tr_move!
+            install_hecks_tr_convert!
+            install_hecks_tr_drop!
+          end
+
+          private
+
+          def install_hecks_tr_extract!
             @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$
@@ -57,15 +82,18 @@ module Hecks
                 END IF;
               END $fn$
             SQL
-            # 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.
+          end
+
+          # 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.
+          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
               LANGUAGE plpgsql IMMUTABLE AS $fn$
@@ -83,6 +111,9 @@ module Hecks
                 RETURN jsonb_set(state, path, value);
               END $fn$
             SQL
+          end
+
+          def install_hecks_tr_rename!
             @db.exec(<<~SQL)
               CREATE OR REPLACE FUNCTION hecks_tr_rename(state jsonb, old_name text, new_name text) RETURNS jsonb
               LANGUAGE sql IMMUTABLE AS $fn$
@@ -91,6 +122,9 @@ module Hecks
                   ELSE state END
               $fn$
             SQL
+          end
+
+          def install_hecks_tr_move!
             @db.exec(<<~SQL)
               CREATE OR REPLACE FUNCTION hecks_tr_move(state jsonb, from_path text[], to_path text[], rule_label text) RETURNS jsonb
               LANGUAGE plpgsql IMMUTABLE AS $fn$
@@ -101,6 +135,9 @@ module Hecks
                 RETURN hecks_tr_insert(extracted.remaining, to_path, extracted.value, rule_label);
               END $fn$
             SQL
+          end
+
+          def install_hecks_tr_convert!
             @db.exec(<<~SQL)
               CREATE OR REPLACE FUNCTION hecks_tr_convert(state jsonb, from_path text[], to_path text[], pairs jsonb, from_label text, rule_label text) RETURNS jsonb
               LANGUAGE plpgsql IMMUTABLE AS $fn$
@@ -117,6 +154,9 @@ module Hecks
                   from_label, extracted.value, extracted.value;
               END $fn$
             SQL
+          end
+
+          def install_hecks_tr_drop!
             @db.exec(<<~SQL)
               CREATE OR REPLACE FUNCTION hecks_tr_drop(state jsonb, path text[]) RETURNS jsonb
               LANGUAGE plpgsql IMMUTABLE AS $fn$

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

@@ -66,8 +66,8 @@ module Hecks
               declared = edge.for_aggregate(aggregate.name)
               after = begin
                 lineage.translated_latest(aggregate, ordinal, chain)
-              rescue PG::Error => error
-                raise Runtime::WiringError, "cannot mint era #{ordinal} of #{bluebook.name}: #{error.message.strip}"
+              rescue PG::Error => e
+                raise Runtime::WiringError, "cannot mint era #{ordinal} of #{bluebook.name}: #{e.message.strip}"
               end
               before = if chain.size > 1
                          lineage.translated_latest(aggregate, ordinal, chain[0..-2])

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

@@ -10,6 +10,15 @@ module Hecks
         # held-but-superseded shape boots read-only-toward-the-fence; an
         # unheld shape goes to the minter.
         module EraResolver
+          # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+          # A single order-dependent dispatch over a closed set of four
+          # boot scenarios (first boot / quiet reboot / held-but-superseded
+          # / unheld-shape-goes-to-minter), each already explained by its
+          # own comment above, all sharing one `db` connection closed in
+          # `ensure`. Splitting the branches into separate methods would
+          # turn each `return` (which exits `check!`, closing `db`) into a
+          # sentinel value threaded back up, obscuring the mutual
+          # exclusivity that IS the method's whole point.
           def check!(registry:, bluebook:, current_text:, settings:, directory: nil)
             db = PostgresEra.connect_for(bluebook.name, settings)
             lineage = Lineage.new(db, bluebook.name, formerly_known_as: bluebook.formerly_known_as)
@@ -78,6 +87,7 @@ module Hecks
           ensure
             db&.close
           end
+          # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         end
       end
     end

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

@@ -20,10 +20,29 @@ module Hecks
             label = hash[0, Runtime::StorageShape::LABEL_LENGTH]
             ordinal = latest[:ordinal] + 1
 
+            edge = resolve_edge!(registry, bluebook, lineage, latest, label, ordinal, directory)
+            ensure_compute_rekey_approved!(bluebook, lineage, edge, ordinal)
+            check_coverage!(registry, bluebook, shadow(latest[:held_text]), edge)
+
+            chain = edge_chain(registry, bluebook, lineage.eras, label)
+            audit!(bluebook, lineage, chain, ordinal, edge)
+            lineage.mint_era!(
+              ordinal: ordinal, hash: hash, label: label, held_text: current_text,
+              aggregates: bluebook.aggregates, edges: chain, role: role,
+              projection: Runtime::StorageShape.project(bluebook)
+            )
+            ordinal
+          end
+
+          # Find the one translation edge that leaves the held era, and
+          # validate it: exactly one edge must leave (eras fork
+          # mechanically — a second edge from the same source is a wiring
+          # mistake, not a merge to resolve automatically), and it must
+          # target the current shape's label (otherwise the edge is stale
+          # and boot must not silently mint past it).
+          def resolve_edge!(registry, bluebook, lineage, latest, label, ordinal, directory)
             edges = registry.translations.select { |t| t.domain == bluebook.name && t.from == latest[:label] }
-            if edges.empty?
-              refuse_toward_the_scaffold!(registry, bluebook, lineage, latest, ordinal, directory)
-            end
+            refuse_toward_the_scaffold!(registry, bluebook, lineage, latest, ordinal, directory) if edges.empty?
             if edges.size > 1
               raise Runtime::WiringError,
                     "cannot boot #{bluebook.name}: #{edges.size} translation edges leave era #{latest[:ordinal]} " \
@@ -36,43 +55,35 @@ module Hecks
                     "cannot boot #{bluebook.name}: the translation edge from #{latest[:label]} targets " \
                     "#{edge.to}, but the current shape is #{label} — the edge is stale; re-run bin/scaffold_translation"
             end
+            edge
+          end
 
-            # A compute's (and, the same way, a rekey's) only verification
-            # is the audit's human-approved sample — mint stays
-            # non-interactive by requiring the approval to already exist,
-            # recorded IN THIS DATABASE by `bin/translation_audit …
-            # --approve` and bound to what was actually reviewed: this
-            # edge's parsed content, and the journal as it stood when the
-            # samples were read. A journal that has advanced past the
-            # review invalidates it — the approved samples no longer cover
-            # the data.
-            if edge.aggregates.any? { |declared| !declared.computes.empty? || !declared.rekeys.empty? }
-              approval = lineage.approval_for(from: edge.from, to: edge.to)
-              unless approval && approval[:edge_digest] == Translation::Audit.edge_digest(edge)
-                raise Runtime::WiringError,
-                      "cannot mint era #{ordinal} of #{bluebook.name}: this edge carries a compute or rekey " \
-                      "rule, and the audit's human-approved sample is its only verification — run " \
-                      "bin/translation_audit with --approve, then boot again"
-              end
-              tip = lineage.last_ordinal
-              if approval[:reviewed_ordinal] != tip
-                raise Runtime::WiringError,
-                      "cannot mint era #{ordinal} of #{bluebook.name}: the journal advanced past the approved " \
-                      "review (ordinal #{approval[:reviewed_ordinal]} reviewed, #{tip} now) — the samples a " \
-                      "human approved no longer cover the data; re-run bin/translation_audit with --approve"
-              end
-            end
+          # A compute's (and, the same way, a rekey's) only verification
+          # is the audit's human-approved sample — mint stays
+          # non-interactive by requiring the approval to already exist,
+          # recorded IN THIS DATABASE by `bin/translation_audit …
+          # --approve` and bound to what was actually reviewed: this
+          # edge's parsed content, and the journal as it stood when the
+          # samples were read. A journal that has advanced past the
+          # review invalidates it — the approved samples no longer cover
+          # the data.
+          def ensure_compute_rekey_approved!(bluebook, lineage, edge, ordinal)
+            return unless edge.aggregates.any? { |declared| !declared.computes.empty? || !declared.rekeys.empty? }
 
-            check_coverage!(registry, bluebook, shadow(latest[:held_text]), edge)
+            approval = lineage.approval_for(from: edge.from, to: edge.to)
+            unless approval && approval[:edge_digest] == Translation::Audit.edge_digest(edge)
+              raise Runtime::WiringError,
+                    "cannot mint era #{ordinal} of #{bluebook.name}: this edge carries a compute or rekey " \
+                    "rule, and the audit's human-approved sample is its only verification — run " \
+                    "bin/translation_audit with --approve, then boot again"
+            end
+            tip = lineage.last_ordinal
+            return unless approval[:reviewed_ordinal] != tip
 
-            chain = edge_chain(registry, bluebook, lineage.eras, label)
-            audit!(bluebook, lineage, chain, ordinal, edge)
-            lineage.mint_era!(
-              ordinal: ordinal, hash: hash, label: label, held_text: current_text,
-              aggregates: bluebook.aggregates, edges: chain, role: role,
-              projection: Runtime::StorageShape.project(bluebook)
-            )
-            ordinal
+            raise Runtime::WiringError,
+                  "cannot mint era #{ordinal} of #{bluebook.name}: the journal advanced past the approved " \
+                  "review (ordinal #{approval[:reviewed_ordinal]} reviewed, #{tip} now) — the samples a " \
+                  "human approved no longer cover the data; re-run bin/translation_audit with --approve"
           end
 
           # No edge yet: the boot refuses toward the authoring loop —
@@ -96,7 +107,7 @@ module Hecks
           # Diff the held era against the current shape and write the edge
           # file — confident rules inline, ambiguities as parse-refusing
           # `unresolved` lines. Returns the file path.
-          def scaffold!(registry, bluebook, lineage, latest, directory)
+          def scaffold!(_registry, bluebook, lineage, latest, directory)
             ensure_named!(lineage, latest)
             latest = lineage.eras.last
 

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

@@ -1,6 +1,7 @@
 require "json"
 
 require_relative "../../../../adapters/driven/sql_query_builder"
+require_relative "../../../../adapters/driven/postgres/outbox"
 require_relative "postgres_era/lineage"
 require_relative "postgres_era/lineage_manager"
 require_relative "../../../../ports/persistence/append_only"
@@ -40,6 +41,7 @@ module Hecks
     #   operator compiles fully into SQL, or the query refuses loudly.
     class PostgresEra
       include SqlQueryBuilder
+      include Adapters::PostgresOutbox
 
       attr_reader :aggregate
 
@@ -139,9 +141,9 @@ module Hecks
         # problems) still surface.
         connection.exec("SET client_min_messages = warning")
         connection
-      rescue PG::Error => error
+      rescue PG::Error => e
         raise Runtime::WiringError,
-              "cannot bind PostgresEra at #{declared} for #{name}: #{error.message.strip}"
+              "cannot bind PostgresEra at #{declared} for #{name}: #{e.message.strip}"
       end
 
       def initialize(aggregate:, settings: {}, root: nil)
@@ -192,6 +194,7 @@ module Hecks
         @field_caches = ensure_field_caches!
         create_event_table!
         create_saga_table!
+        create_outbox_table!
       end
 
       def table = @aggregate.storage_name
@@ -216,7 +219,10 @@ module Hecks
         return @db.exec(%(SELECT id, state FROM #{quoted_head} ORDER BY id)).map { |row| instance(row) } unless order_by
 
         name = order_by.to_s.split(".").first
-        raise Runtime::WiringError, "#{@aggregate.name} has no attribute #{order_by.inspect} to order by" unless @aggregate.lifecycle&.field.to_s == name || @aggregate.attribute(name)
+        unless @aggregate.lifecycle&.field.to_s == name || @aggregate.attribute(name)
+          raise Runtime::WiringError,
+                "#{@aggregate.name} has no attribute #{order_by.inspect} to order by"
+        end
 
         spec = QuerySpecification::Common::OrderBy.new(field: order_by, direction: direction)
         @db.exec(%(SELECT id, state FROM #{quoted_head} ORDER BY #{order_clause(spec, nil)})).map { |row| instance(row) }
@@ -286,7 +292,7 @@ module Hecks
       # make that replay pay real DB cost for a snapshot that's already
       # correct.
       def append(entry)
-        @db.transaction do
+        transaction do
           lock_writes!
           append_and_project!(entry)
         end
@@ -299,7 +305,7 @@ module Hecks
       # occurs before entering this adapter-native operation.
       def atomic_put(entry, insert_only: false)
         status = nil
-        @db.transaction do
+        transaction do
           lock_writes!
           exists = !@db.exec_params(
             "SELECT 1 FROM #{quoted_head} WHERE id = $1 LIMIT 1",
@@ -418,7 +424,8 @@ module Hecks
           "ON CONFLICT (domain, process_manager, correlation) DO UPDATE " \
           "SET state = EXCLUDED.state, memory = EXCLUDED.memory, " \
           "completed_compensations = EXCLUDED.completed_compensations, updated_at = now()",
-          [@domain, process_manager.to_s, correlation.to_s, state.to_s, JSON.generate(memory), JSON.generate(completed_compensations)]
+          [@domain, process_manager.to_s, correlation.to_s, state.to_s, JSON.generate(memory),
+           JSON.generate(completed_compensations)]
         )
       end
 
@@ -433,7 +440,8 @@ module Hecks
         return enum_for(:each_saga) unless block_given?
 
         @db.exec_params(
-          "SELECT process_manager, correlation, state, memory, completed_compensations FROM hecks_saga_instances WHERE domain = $1",
+          "SELECT process_manager, correlation, state, memory, completed_compensations " \
+          "FROM hecks_saga_instances WHERE domain = $1",
           [@domain]
         ).each do |row|
           yield row["process_manager"], row["correlation"], row["state"],
@@ -624,11 +632,12 @@ module Hecks
       end
 
       def cached_where_fields
-        declared_queries.flat_map { |q|
-          q.wheres.map { |clause|
+        fields = declared_queries.flat_map do |q|
+          q.wheres.map do |clause|
             clause.field.to_s
-          }
-        }.uniq.select { |field| cacheable_field?(field) }
+          end
+        end
+        fields.uniq.select { |field| cacheable_field?(field) }
       end
 
       def declared_queries
@@ -709,7 +718,7 @@ module Hecks
           clauses << where_clause(clause.op.to_s, expression, value, binds, field: clause.field)
         end
 
-        sql = +"SELECT #{select_list} FROM #{from_relation} WHERE #{clauses.join(' AND ')}"
+        sql = "SELECT #{select_list} FROM #{from_relation} WHERE #{clauses.join(' AND ')}"
         sql << if declared.order_by
                  " ORDER BY #{order_clause(declared.order_by, declared.null_semantics)}"
                else
@@ -751,7 +760,8 @@ module Hecks
         # this same domain already created before this column existed —
         # the same idiom `rust/host/src/journal.rs`'s own
         # `sagas_backfilled` column addition already uses.
-        @db.exec("ALTER TABLE hecks_saga_instances ADD COLUMN IF NOT EXISTS completed_compensations jsonb NOT NULL DEFAULT '[]'::jsonb")
+        @db.exec("ALTER TABLE hecks_saga_instances ADD COLUMN IF NOT EXISTS completed_compensations jsonb " \
+                 "NOT NULL DEFAULT '[]'::jsonb")
       end
     end
   end

data/lib/hecks/ports/persistence/plugins/era/translation/audit/layer_one.rb

@@ -15,29 +15,27 @@ module Hecks
       module LayerOne
         def layer_one!(violations, aggregate, after)
           after.each do |id, state|
-            begin
-              symbolized = JSON.parse(JSON.generate(state), symbolize_names: true)
-              instance = Runtime::Instance.new(aggregate: aggregate, id: id, state: symbolized)
-              lifecycle = aggregate.lifecycle
-              next unless lifecycle
+            symbolized = JSON.parse(JSON.generate(state), symbolize_names: true)
+            instance = Runtime::Instance.new(aggregate: aggregate, id: id, state: symbolized)
+            lifecycle = aggregate.lifecycle
+            next unless lifecycle
 
-              held = instance[lifecycle.field]
-              # `Lifecycle#states` answers default+targets only — a state
-              # legitimately declared just as a `from:` (a terminal
-              # transition's source, never anyone's target) is real and
-              # reachable but invisible to it. `ModelCheck.full_states`
-              # is the full declared set (default, every target, AND
-              # every from) that `fuzzing/properties.rb`'s own replay
-              # check already uses for this identical question — see its
-              # comment on this same hole.
-              allowed = Bluebook::ModelCheck.full_states(lifecycle)
-              unless held.nil? || allowed.include?(held.to_s)
-                violations << "#{aggregate.name}##{id}: #{lifecycle.field} is #{held.inspect}, " \
-                              "a state this era's lifecycle never reaches"
-              end
-            rescue Runtime::InvariantViolation, Runtime::TypeMismatch => error
-              violations << "#{aggregate.name}##{id}: #{error.message}"
+            held = instance[lifecycle.field]
+            # `Lifecycle#states` answers default+targets only — a state
+            # legitimately declared just as a `from:` (a terminal
+            # transition's source, never anyone's target) is real and
+            # reachable but invisible to it. `ModelCheck.full_states`
+            # is the full declared set (default, every target, AND
+            # every from) that `fuzzing/properties.rb`'s own replay
+            # check already uses for this identical question — see its
+            # comment on this same hole.
+            allowed = Bluebook::ModelCheck.full_states(lifecycle)
+            unless held.nil? || allowed.include?(held.to_s)
+              violations << "#{aggregate.name}##{id}: #{lifecycle.field} is #{held.inspect}, " \
+                            "a state this era's lifecycle never reaches"
             end
+          rescue Runtime::InvariantViolation, Runtime::TypeMismatch => e
+            violations << "#{aggregate.name}##{id}: #{e.message}"
           end
         end
       end

data/lib/hecks/ports/persistence/plugins/era/translation/audit/layer_two.rb

@@ -24,6 +24,26 @@ module Hecks
         def layer_two!(violations, aggregate, declared, before, after)
           rekeyed = declared && !declared.rekeys.empty?
 
+          check_id_conservation!(violations, aggregate, before, after, rekeyed: rekeyed)
+
+          return unless declared
+          # No correspondence between an old id and its rekeyed row exists
+          # in Ruby (the rekey's SQL is its only implementation, same as
+          # compute's) — exempt from the per-record equivalence gate for
+          # the same reason compute paths already are, extended to the
+          # whole record since an old-id lookup into `after` can never
+          # succeed once the id itself has changed.
+          return if rekeyed
+
+          check_value_preservation!(violations, aggregate, declared, before, after)
+        end
+
+        # Record-count / id-set conservation — one of the two properties
+        # this module's own header names, and independent of the other
+        # (per-rule value preservation, below): it needs only `before`,
+        # `after`, and whether the edge rekeyed, never the declared rules
+        # themselves.
+        def check_id_conservation!(violations, aggregate, before, after, rekeyed:)
           # A rekey legitimately changes the id SET (that's the entire
           # point) — set-equality would flag every honest rekey as data
           # loss. What must still hold is RECORD COUNT: a botched rekey
@@ -43,15 +63,13 @@ module Hecks
             violations << "#{aggregate.name}: the id set changed across the edge " \
                           "(lost #{lost.sort.inspect}, gained #{gained.sort.inspect})"
           end
-          return unless declared
-          # No correspondence between an old id and its rekeyed row exists
-          # in Ruby (the rekey's SQL is its only implementation, same as
-          # compute's) — exempt from the per-record equivalence gate for
-          # the same reason compute paths already are, extended to the
-          # whole record since an old-id lookup into `after` can never
-          # succeed once the id itself has changed.
-          return if rekeyed
+        end
 
+        # Per-rule value preservation — the other property this module's
+        # header names. Only reached once `layer_two!` has already ruled
+        # out "no declared edge" and "rekeyed" (see its own comment on
+        # that second guard); this method assumes both are false.
+        def check_value_preservation!(violations, aggregate, declared, before, after)
           rules = Ports::Persistence::Lineage.from_declared(declared, aggregate.name)
           compute_paths = declared.computes.flat_map { |compute| [compute.from, compute.to] }.map(&:to_s)
 
@@ -63,7 +81,7 @@ module Hecks
             actual = strip_compute_paths(normalize(after[id]), compute_paths)
             next if expected == actual
 
-            diverged = (expected.keys | actual.keys).select { |key| expected[key] != actual[key] }
+            diverged = (expected.keys | actual.keys).reject { |key| expected[key] == actual[key] }
             violations << "#{aggregate.name}##{id}: the translated state diverges from the reference " \
                           "transform at #{diverged.sort.join(', ')}"
           end

data/lib/hecks/ports/persistence/plugins/era/translation/audit/unfed_report.rb

@@ -7,6 +7,15 @@ module Hecks
       # attribute, and the loud refusal for a REQUIRED one comes from
       # Layer 1 the moment an invariant reads it.
       module UnfedReport
+        # `fed` build-up plus one ordered guard chain per attribute
+        # (already fed, has a default, actually present in some record, no
+        # records to check at all) answering a single question — "is
+        # anything, ever, going to feed this field" — where each `next`
+        # rules out one way the answer is "not unfed after all" before the
+        # next is even worth asking. Splitting the guards out would just
+        # turn each into a same-shaped one-line predicate call.
+        # rubocop:disable-next Metrics/CyclomaticComplexity
+        # rubocop:disable-next Metrics/PerceivedComplexity
         def unfed(aggregate, declared, after)
           fed = if declared
                   (declared.renames.values.map(&:to_s) +