hecks 0.3.0 → 1.0.1

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

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

@@ -1,5 +1,5 @@
-require_relative "../../ports/persistence/append_only"
-require_relative "../../ports/persistence/lineage"
+require_relative "../../../../../../ports/persistence/append_only"
+require_relative "../../lineage"
 
 module Hecks
   module Translation
@@ -53,15 +53,14 @@ module Hecks
           return if rekeyed
 
           rules = Ports::Persistence::Lineage.from_declared(declared, aggregate.name)
-          compute_tops = declared.computes.flat_map { |compute| [compute.from, compute.to] }
-                                 .map { |path| path.to_s.split(".").first }
+          compute_paths = declared.computes.flat_map { |compute| [compute.from, compute.to] }.map(&:to_s)
 
           before.each do |id, state|
             next unless after.key?(id)
 
             entry = Ports::Persistence::Entry.new(operation: "save", id: id, state: state.transform_keys(&:to_sym))
-            expected = normalize(rules.translate(entry).state).reject { |key, _| compute_tops.include?(key) }
-            actual = normalize(after[id]).reject { |key, _| compute_tops.include?(key) }
+            expected = strip_compute_paths(normalize(rules.translate(entry).state), compute_paths)
+            actual = strip_compute_paths(normalize(after[id]), compute_paths)
             next if expected == actual
 
             diverged = (expected.keys | actual.keys).select { |key| expected[key] != actual[key] }
@@ -71,6 +70,32 @@ module Hecks
         end
 
         def normalize(state) = JSON.parse(JSON.generate(state))
+
+        # Exempts exactly the paths a compute owns, not the whole
+        # top-level attribute it happens to live under. A bare path
+        # ("price_cents") is itself the compute's entire value — dropping
+        # the whole top-level key is correct, there's nothing else there
+        # to check. A DOTTED path ("price.cents") only owns that one
+        # member of the value object it reaches into; every sibling
+        # member (e.g. "price.currency") is untouched by the compute and
+        # must stay subject to the equivalence check below. Blanket-
+        # dropping the whole top-level key for a dotted compute used to
+        # exempt the entire attribute — silent data loss elsewhere in the
+        # same value object (a migration that nulls or drops a sibling
+        # field) produced zero violations, defeating the one gate whose
+        # entire purpose is to catch exactly that.
+        def strip_compute_paths(state, paths)
+          paths.each do |path|
+            segments = path.split(".")
+            if segments.length == 1
+              state.delete(segments.first)
+            else
+              parent = segments[0..-2].reduce(state) { |node, segment| node.is_a?(Hash) ? node[segment] : nil }
+              parent.delete(segments.last) if parent.is_a?(Hash)
+            end
+          end
+          state
+        end
       end
     end
   end

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

@@ -33,7 +33,11 @@ module Hecks
           path.to_s.split(".").reduce(state) do |node, segment|
             break nil unless node.is_a?(Hash)
 
-            node[segment] || node[segment.to_sym]
+            # `key?` decides which spelling answers, never `||` — a
+            # `false` genuinely held at this path must not fall through
+            # to the other spelling (usually absent) and read as `nil`,
+            # which would wrongly mark a `false`-valued attribute "unfed".
+            node.key?(segment) ? node[segment] : node[segment.to_sym]
           end
         end
       end

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

@@ -1,7 +1,7 @@
 require "tempfile"
-require_relative "../runtime/era_guard"
-require_relative "../runtime/registry"
-require_relative "../runtime/storage_shape"
+require_relative "../era_guard"
+require_relative "../../../../../runtime/registry"
+require_relative "../storage_shape"
 
 module Hecks
   module Translation

data/lib/hecks/{translation → ports/persistence/plugins/era/translation}/scaffold/differ.rb

@@ -1,4 +1,4 @@
-require_relative "../../runtime/storage_shape"
+require_relative "../../storage_shape"
 
 module Hecks
   module Translation

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

@@ -0,0 +1,48 @@
+require_relative "../plugin"
+require_relative "era/era_check"
+require_relative "era/era_guard"
+require_relative "era/era_tamper"
+require_relative "era/storage_shape"
+require_relative "era/lineage"
+require_relative "era/postgres_era"
+require_relative "era/translation"
+
+module Hecks
+  module Ports
+    module Persistence
+      module Plugins
+        # ADR 0033 — requiring THIS FILE is installing the plugin. Nothing in
+        # Hecks core requires it; an app that binds `PostgresEra`, or wants
+        # schema-translation support at all, requires it explicitly — the
+        # same shape every adapter-specific spec fixture already uses to
+        # load one particular `.adapter` file rather than all of them.
+        module Era
+          module_function
+
+          # `Runtime::Loader.run_boot_gates!` asks every loaded persistence
+          # plugin to contribute here, generically — it never mentions
+          # `EraCheck` or "era" by name. Two gates, both `:pre_verify`:
+          #
+          # `:era_compute_rules` — unconditional, whenever this plugin is
+          # loaded at all. A `compute`/`rekey` rule requires Postgres
+          # whatever adapter is actually bound (ADR 0031's own reasoning,
+          # unchanged) — this is the rich, adapter-aware version of that
+          # check; `Runtime::Loader`'s own structural backstop (plain
+          # `Bluebook::Translation` data, no plugin-specific class) only
+          # ever fires when NO persistence plugin is loaded at all.
+          #
+          # `:era_check` — conditional, exactly ADR 0031's own gate,
+          # unchanged: registered only when this registry has an aggregate
+          # actually bound to a lineage-capable adapter.
+          def contribute_boot_gates(registry, gates)
+            gates.register(:era_compute_rules, ->(reg, _dir) { Runtime::EraCheck.check_compute_rules_for_registry!(reg) }, phase: :pre_verify)
+            gates.register(:era_check, Runtime::EraCheck.method(:check_lineage!), phase: :pre_verify) if
+              Runtime::EraCheck.lineage_capable_registry?(registry)
+          end
+        end
+      end
+    end
+  end
+end
+
+Hecks::Ports::Persistence.register_plugin(:era, Hecks::Ports::Persistence::Plugins::Era)

data/lib/hecks/ports/persistence.rb

@@ -9,7 +9,7 @@ module Hecks
 end
 
 require_relative "persistence/binding_policy"
-require_relative "persistence/lineage"
+require_relative "persistence/plugin"
 require_relative "persistence/repository_factory"
 require_relative "persistence/append_only"
 require_relative "persistence/execution"

data/lib/hecks/ports/projection.rb

@@ -29,10 +29,30 @@ module Hecks
       class Worker
         attr_reader :projection
 
+        # The only two policies anything in this codebase ever passes
+        # (`bin/project`, every spec) — there is no third, legitimate
+        # "lenient append" policy on record anywhere. Before this, any
+        # value OTHER than the exact symbol `:strict` silently fell
+        # through the `consistent?` check below and appended onto
+        # divergent history without a word — not just a real typo like
+        # `:strikt`, but a caller-supplied String `"strict"` too (this
+        # duck-typed fine via `policy.to_sym`, but that was luck, not a
+        # contract: nothing here declared what a valid policy even was).
+        # Refusing loudly at construction, once, for anything outside
+        # this list turns a silent no-op into an immediate, named error
+        # — the "refuse rather than silently skip" reading of L1, since
+        # `:strict` really is meant to be the only enforcing contract.
+        VALID_POLICIES = %i[refresh strict].freeze
+
         def initialize(authoritative, projection, policy: :refresh)
           @authoritative = authoritative
           @projection = projection
           @policy = policy.to_sym
+          unless VALID_POLICIES.include?(@policy)
+            raise ArgumentError,
+                  "unknown projection catch_up! policy #{@policy.inspect} — expected one of " \
+                  "#{VALID_POLICIES.map(&:inspect).join(' or ')}"
+          end
         end
 
         # Invoke from a separate process or scheduler. The command-side write