hecks 0.3.0 → 1.0.0

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

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

@@ -1,14 +1,14 @@
 require "json"
 
-require_relative "sql_query_builder"
+require_relative "../../../../adapters/driven/sql_query_builder"
 require_relative "postgres_era/lineage"
 require_relative "postgres_era/lineage_manager"
-require_relative "../../ports/persistence/append_only"
-require_relative "../../query_specification/common/order_by"
-require_relative "../../runtime/errors"
-require_relative "../../runtime/event"
-require_relative "../../runtime/instance"
-require_relative "../../runtime/registry"
+require_relative "../../../../ports/persistence/append_only"
+require_relative "../../../../query_specification/common/order_by"
+require_relative "../../../../runtime/errors"
+require_relative "../../../../runtime/event"
+require_relative "../../../../runtime/instance"
+require_relative "../../../../runtime/registry"
 
 module Hecks
   module Adapters
@@ -67,12 +67,30 @@ module Hecks
         )
       end
 
+      # BOTH SPELLINGS OF A SETTING ARE HONORED — a world's settings hash
+      # may arrive symbol-keyed (built straight in Ruby) or string-keyed
+      # (round-tripped through JSON), and a domain that names one is not
+      # obligated to also skip the other. `key?` decides which spelling
+      # actually exists, never `||` — `||` cannot tell a genuinely stored
+      # `false` apart from an absent key, and would silently prefer the
+      # OTHER spelling (or `default`) instead of returning the real, held
+      # answer. See Hecks::QuerySpecification::FieldPath#read for the same
+      # discipline applied to stored state instead of settings.
+      def self.setting(settings, key, default: nil)
+        return settings[key] if settings.key?(key)
+
+        str_key = key.to_s
+        return settings[str_key] if settings.key?(str_key)
+
+        default
+      end
+
       def self.connect_for(name, settings)
         # LAZY, ON PURPOSE — same reasoning as Sqlite's own initialize:
         # a domain that never wires PostgresEra should never need the gem.
         require "pg"
 
-        declared = settings[:database] || settings["database"]
+        declared = setting(settings, :database)
         if declared.to_s.empty?
           raise Runtime::WiringError,
                 "#{name} binds PostgresEra, which needs a database connection, " \
@@ -94,7 +112,7 @@ module Hecks
         # TABLE ... SET SCHEMA migrations transparent to the rest of the
         # adapter. A domain with no `schema` setting keeps Postgres's
         # own default search_path (public), same as before this existed.
-        schema = settings[:schema] || settings["schema"]
+        schema = setting(settings, :schema)
         if schema.to_s != ""
           # THE SCHEMA ITSELF, IDEMPOTENTLY — a domain naming a `schema:`
           # nobody has created yet used to fail on its FIRST table-
@@ -132,14 +150,29 @@ module Hecks
         # The domain names the journal (one journal per lineage). The
         # factory injects it; a directly-instantiated adapter (specs,
         # consoles) journals under the aggregate's own name.
-        @domain = (settings[:domain] || settings["domain"] || aggregate.storage_name).to_s
+        @domain = self.class.setting(settings, :domain, default: aggregate.storage_name).to_s
         @lineage = Lineage.new(@db, @domain)
         @lineage.ensure_base!
         # The era gate resolves which era this boot IS (an old checkout
         # boots a held-but-superseded era and keeps writing its own
         # partition); a directly-instantiated adapter defaults to the
         # newest.
-        @era = settings[:era] || settings["era"] || @lineage.current_era
+        #
+        # NOT `self.class.setting(...)` here — RepositoryFactory#build
+        # always merges `era: registry.resolved_eras[domain]` into
+        # settings, so the key is genuinely PRESENT (not absent) for
+        # any domain the era boot gate hasn't resolved yet (or that
+        # doesn't have one at all), just holding `nil`. `setting`'s own
+        # presence-over-truthiness discipline (correct for a field like
+        # `:role`, where a stored `false` is a real, distinct answer
+        # from "unset") does the wrong thing for `:era` specifically:
+        # `nil` can never be a meaningful era override — only a real
+        # ordinal or "not resolved, self-resolve" ever apply — so
+        # coalescing here, not `setting`'s presence check, is what
+        # actually honors this comment's own "defaults to the newest"
+        # promise.
+        @era = settings.key?(:era) ? settings[:era] : settings["era"]
+        @era ||= @lineage.current_era
         # Unconditional and idempotent, regardless of era — belt-and-
         # suspenders self-healing (compile_head! already ensures this for
         # a freshly-minted era's own name; ensure_first_head! for era 1's)
@@ -309,8 +342,31 @@ module Hecks
         end
       end
 
+      # The journal carries FORCE ROW LEVEL SECURITY with exactly two
+      # policies — hecks_current_era's INSERT and hecks_read_all's
+      # SELECT (advance_era! above) — and no DELETE policy at all, for
+      # anyone. FORCE means even the table's own owner is fenced by
+      # that (only an actual Postgres superuser or a role granted
+      # BYPASSRLS sits above it — see lineage.rb's own header), so a
+      # plain `DELETE ... WHERE aggregate = $1` from an ordinary
+      # connection silently matches zero rows: no privilege error, no
+      # exception, just a no-op that looks like success. Counting
+      # before and comparing to what the DELETE itself reports is what
+      # tells "nothing to delete" apart from "RLS silently ate the
+      # delete" — the same row count, from the same statement, either
+      # way, with no separate query racing the DELETE for an answer.
       def reset!
-        @db.exec_params("DELETE FROM #{@lineage.quoted_journal} WHERE aggregate = $1", [table])
+        before = @db.exec_params(
+          "SELECT count(*) FROM #{@lineage.quoted_journal} WHERE aggregate = $1", [table]
+        )[0]["count"].to_i
+        result = @db.exec_params("DELETE FROM #{@lineage.quoted_journal} WHERE aggregate = $1", [table])
+        if before.positive? && result.cmd_tuples.zero?
+          raise Runtime::WiringError,
+                "reset! deleted 0 of #{before} row(s) for #{table} in #{@lineage.quoted_journal} — " \
+                "FORCE ROW LEVEL SECURITY admits no DELETE policy on the journal, so this connection's " \
+                "DELETE silently matched nothing. reset! only works connected as an actual Postgres " \
+                "superuser or a role granted BYPASSRLS, not as the provisioner or an app role."
+        end
         self
       end
 
@@ -355,13 +411,14 @@ module Hecks
       # `SagaInterpreter`'s own mutex (§7) serializing IN-PROCESS writers,
       # and gets the SAME cross-process safety an aggregate's own writes
       # get from this adapter — no better, no worse.
-      def save_saga(process_manager:, correlation:, state:, memory:)
+      def save_saga(process_manager:, correlation:, state:, memory:, completed_compensations: [])
         @db.exec_params(
-          "INSERT INTO hecks_saga_instances (domain, process_manager, correlation, state, memory) " \
-          "VALUES ($1, $2, $3, $4, $5) " \
+          "INSERT INTO hecks_saga_instances (domain, process_manager, correlation, state, memory, completed_compensations) " \
+          "VALUES ($1, $2, $3, $4, $5, $6) " \
           "ON CONFLICT (domain, process_manager, correlation) DO UPDATE " \
-          "SET state = EXCLUDED.state, memory = EXCLUDED.memory, updated_at = now()",
-          [@domain, process_manager.to_s, correlation.to_s, state.to_s, JSON.generate(memory)]
+          "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)]
         )
       end
 
@@ -376,11 +433,12 @@ module Hecks
         return enum_for(:each_saga) unless block_given?
 
         @db.exec_params(
-          "SELECT process_manager, correlation, state, memory 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"],
-                JSON.parse(row["memory"], symbolize_names: true)
+                JSON.parse(row["memory"], symbolize_names: true),
+                JSON.parse(row["completed_compensations"] || "[]", symbolize_names: true)
         end
       end
 
@@ -404,9 +462,9 @@ module Hecks
 
         if entry.save?
           @db.exec_params(
-            "INSERT INTO #{quoted_head_snapshot} (id, ordinal, state) VALUES ($1, $2, $3) " \
-            "ON CONFLICT (id) DO UPDATE SET ordinal = EXCLUDED.ordinal, state = EXCLUDED.state " \
-            "WHERE #{quoted_head_snapshot}.ordinal < EXCLUDED.ordinal",
+            "INSERT INTO #{quoted_head_snapshot} (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 #{quoted_head_snapshot}.ordinal < EXCLUDED.ordinal",
             [entry.id, ordinal, state_json]
           )
           # SAME TRANSACTION, SAME ORDINAL — every field cache stays
@@ -419,7 +477,30 @@ module Hecks
             @lineage.upsert_field_cache_row!(cache_table, entry.id, ordinal, state_json, query_expression(field))
           end
         else
-          @db.exec_params("DELETE FROM #{quoted_head_snapshot} WHERE id = $1", [entry.id])
+          # A TOMBSTONE ROW, NOT A BARE DELETE — H3 (docs/audits/2026-08-
+          # 10-main-bug-audit.md). `DELETE FROM head_snapshot` used to be
+          # the whole story here, which is correct in isolation but wrong
+          # once an ancestor era is in the picture: for a record carried
+          # into this era from an ancestor, removing this era's row left
+          # NOTHING on the current-era side of `compile_head!`'s union to
+          # outrank the ancestor matview's own (still-present, still
+          # `save`) row, so `DISTINCT ON` picked the ancestor's row and
+          # the "deleted" record kept reading back forever. Upserting a
+          # tombstone (`operation = 'delete'`, `state` NULL) instead
+          # means this era always has ITS OWN newest-ordinal row for the
+          # id, exactly like a real re-save already did ("re-saves are
+          # masked correctly" — the audit's own phrasing for why that
+          # half of this was never broken) — it just carries `operation
+          # = 'delete'` instead of `'save'`, so `head_view`'s own `WHERE
+          # operation = 'save'` still correctly hides it. Ordinal-guarded
+          # the same as every other upsert here, so an out-of-order
+          # replay can never let a stale delete clobber a newer save.
+          @db.exec_params(
+            "INSERT INTO #{quoted_head_snapshot} (id, ordinal, operation, state) VALUES ($1, $2, 'delete', NULL) " \
+            "ON CONFLICT (id) DO UPDATE SET ordinal = EXCLUDED.ordinal, operation = EXCLUDED.operation, " \
+            "state = EXCLUDED.state WHERE #{quoted_head_snapshot}.ordinal < EXCLUDED.ordinal",
+            [entry.id, ordinal]
+          )
           @field_caches.each_value { |cache_table| @lineage.delete_field_cache_row!(cache_table, entry.id) }
         end
 
@@ -656,15 +737,21 @@ module Hecks
       def create_saga_table!
         @db.exec(<<~SQL)
           CREATE TABLE IF NOT EXISTS hecks_saga_instances (
-            domain          text NOT NULL,
-            process_manager text NOT NULL,
-            correlation     text NOT NULL,
-            state           text NOT NULL,
-            memory          jsonb NOT NULL,
-            updated_at      timestamptz NOT NULL DEFAULT now(),
+            domain               text NOT NULL,
+            process_manager      text NOT NULL,
+            correlation          text NOT NULL,
+            state                text NOT NULL,
+            memory               jsonb NOT NULL,
+            completed_compensations  jsonb NOT NULL DEFAULT '[]'::jsonb,
+            updated_at           timestamptz NOT NULL DEFAULT now(),
             PRIMARY KEY (domain, process_manager, correlation)
           )
         SQL
+        # `CREATE TABLE IF NOT EXISTS` above is a no-op against a table
+        # 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")
       end
     end
   end

data/lib/hecks/{translation → ports/persistence/plugins/era/translation}/audit/approval_digest.rb

@@ -1,5 +1,5 @@
 require "digest"
-require_relative "../../projector/exporter"
+require_relative "../../../../../../projector/exporter"
 
 module Hecks
   module Translation

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

@@ -1,6 +1,7 @@
-require_relative "../../runtime/errors"
-require_relative "../../runtime/instance"
-require_relative "../../runtime/value/invariant_violation"
+require_relative "../../../../../../runtime/errors"
+require_relative "../../../../../../runtime/instance"
+require_relative "../../../../../../runtime/value/invariant_violation"
+require_relative "../../../../../../bluebook/model_check"
 
 module Hecks
   module Translation
@@ -21,8 +22,16 @@ module Hecks
               next unless lifecycle
 
               held = instance[lifecycle.field]
-              allowed = lifecycle.states | [lifecycle.default]
-              unless held.nil? || allowed.include?(held)
+              # `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