hecks 1.2.0 → 1.4.0

data/lib/hecks/fuzzing/isolated_boot.rb

@@ -4,30 +4,30 @@ require "securerandom"
 
 module Hecks
   module Fuzzing
-    # A FRESH, IN-PROCESS ADAPTER FOR EVERY EPHEMERAL BOOT.
+    # A fresh, in-process adapter for every ephemeral boot.
     #
     # Fuzzing/replay copies a domain to a tmpdir and boots from there
     # specifically to get zero-history state — `rm_rf`ing the copy's own
     # `data/` achieves that for a file-based adapter (Memory,
-    # SqlitePersistence, Heki), because copying the DIRECTORY copies the
+    # SqlitePersistence, Heki), because copying the directory copies the
     # store. It achieves nothing for an adapter that lives outside the
     # copied directory entirely — Postgres, named by a fixed connection
     # string in `.world` (examples/pizzas/bluebook/pizzas.world, for
     # instance). Copying the directory does not copy or isolate the
-    # DATABASE, so a "fresh" boot against a Postgres-bound domain would
+    # database, so a "fresh" boot against a Postgres-bound domain would
     # still see every record any other run, ever, wrote to it.
     #
     # So every `.hecksagon` in the copy gets its persistence binding
     # rewritten to Memory before booting, and any `projected_by` bind
     # dropped outright (optional — `Registry#read_repository` already
     # falls back to the authoritative repository when none exists). The
-    # domain's own rules and shape are untouched ; only WHICH adapter this
+    # domain's own rules and shape are untouched ; only which adapter this
     # one ephemeral copy answers through changes. What the domain is
     # bound to for real deployment is never touched — only this tmp copy.
     #
     # `adapter:` (PRD 02) — Memory is the default and the only mode every
     # existing caller still gets with no change. `:sqlite` rebinds to the
-    # REAL SQLite adapter instead of the in-memory one, for exactly the
+    # real SQLite adapter instead of the in-memory one, for exactly the
     # same reason PRD 02 exists: 15 declared properties (properties.rb)
     # and every fuzz/replay run has only ever been checked against
     # Memory's own hand-written repository, never against a real,
@@ -44,15 +44,25 @@ module Hecks
     # `root:`, which `Hecks.boot(copy)` passes as this ephemeral copy's
     # own directory — a fresh, empty `data/` per run, exactly like
     # Memory's own zero-history guarantee, just backed by a real SQLite
-    # file instead of a Hash. Postgres/PostgresEra are deliberately NOT
-    # added here: a real Postgres run needs a live server and shared
-    # connection settings this in-process, no-adapter-config path has no
-    # place to source safely — that stays `io: true`-gated, direct-adapter
-    # coverage (`spec/adapters/driven/postgres_*_spec.rb`), not this.
+    # file instead of a Hash. Stale as of this paragraph's original
+    # writing — both `Postgres` (PRD 02, docs/prds/02-fuzzer-real-
+    # adapters.md) and `PostgresEra` (this mode's own header, below,
+    # `rebind_to_postgres_era!`) since gained real `adapter:` modes here.
+    # Each writes its own fresh `.world` per `.hecksagon` rather than
+    # relying on the zero-config default Sqlite/Memory get, and each
+    # needs a real, reachable Postgres server — but "no place to source a
+    # connection safely" turned out not to be true: `:postgres` sources
+    # one shared, permanent scratch database/schema this module itself
+    # owns (see `FUZZ_POSTGRES_DATABASE`'s own header); `:postgres_era`
+    # instead requires the caller to supply (and own the lifecycle of) its
+    # own throwaway `database:`/`schema:`, since its only caller
+    # (`bin/qa_sweep --persistence-parity`) already has to manage a
+    # disposable database of its own, never a shared one this module could
+    # safely default to.
     module IsolatedBoot
       module_function
 
-      # PRD 02 (docs/future-features.md) — `adapter:` picks WHICH real
+      # PRD 02 (docs/future-features.md) — `adapter:` picks which real
       # persistence this one ephemeral boot answers through, not just
       # Memory. `:memory` is the original, zero-config behavior (every
       # other caller in this codebase that doesn't pass `adapter:` gets
@@ -65,23 +75,33 @@ module Hecks
       # so `bin/fuzz --adapter postgres` is meant to run with smaller
       # seed/step counts than the Memory default, not as a like-for-like
       # swap; see that flag's own comment.
-      def call(domain_path, adapter: :memory)
+      # `database:`/`schema:` are only meaningful for `adapter: :postgres_era`
+      # — see `rebind_to_postgres_era!`'s own header for why that mode takes
+      # caller-supplied connection identity instead of a hardcoded shared
+      # constant the way `:postgres` does. Every other adapter ignores both;
+      # accepting them unconditionally here (rather than a separate method
+      # signature per adapter) keeps `SequenceGenerator`/`Replay`'s own
+      # single passthrough (`adapter:`, now joined by these two) uniform
+      # across all four modes.
+      def call(domain_path, adapter: :memory, database: nil, schema: nil)
         Dir.mktmpdir("hecks-fuzz") do |tmp|
           copy = File.join(tmp, File.basename(domain_path))
           copy_dereferencing(domain_path, copy)
           FileUtils.rm_rf(File.join(copy, "data"))
           case adapter
-          when :memory   then rebind_to_memory!(copy)
-          when :sqlite   then rebind_to_sqlite!(copy)
-          when :postgres then rebind_to_postgres!(copy)
-          else raise ArgumentError, "unknown fuzz adapter #{adapter.inspect} — :memory, :sqlite, or :postgres"
+          when :memory       then rebind_to_memory!(copy)
+          when :sqlite       then rebind_to_sqlite!(copy)
+          when :postgres     then rebind_to_postgres!(copy)
+          when :postgres_era then rebind_to_postgres_era!(copy, database: database, schema: schema)
+          else raise ArgumentError,
+                     "unknown fuzz adapter #{adapter.inspect} — :memory, :sqlite, :postgres, or :postgres_era"
           end
           yield copy
         end
       end
 
-      # SYMLINKS ARE FOLLOWED, NOT COPIED. `FileUtils.cp_r` reproduces a
-      # symlink AS a symlink, and a RELATIVE one then points at nothing
+      # Symlinks are followed, not copied. `FileUtils.cp_r` reproduces a
+      # symlink as a symlink, and a relative one then points at nothing
       # from a tmpdir — `lib/hecks/framework/bluebook/compliance
       # .bluebook` is exactly that, a link to
       # `examples/compliance/bluebook/compliance.bluebook`, so the whole
@@ -89,7 +109,7 @@ module Hecks
       # path under /var/folders that had never existed. Nothing about the
       # domain was wrong; the copy was.
       #
-      # `FileUtils.cp` follows a symlink and copies its CONTENT, which is
+      # `FileUtils.cp` follows a symlink and copies its content, which is
       # what an isolated boot wants: the copy has to stand alone, since
       # rebind! rewrites files in it and must not reach back through a
       # link into the real tree.
@@ -118,9 +138,10 @@ module Hecks
 
       def rebind_to_memory!(copy)
         rewrite_bindings!(copy, "Memory")
+        strip_translations!(copy)
 
-        # THE SETTINGS, NOT JUST THE BIND — `WorldBuilder#method_missing`
-        # stores a settings block under BOTH "verb:adapter" and the bare
+        # **The settings, not just the bind** — `WorldBuilder#method_missing`
+        # stores a settings block under both "verb:adapter" and the bare
         # "verb" (world_builder.rb:32-33), so a bind rewritten to Memory
         # still falls back to whatever adapter's settings were declared
         # bare — Postgres's `database:`, which Memory does not take and
@@ -133,7 +154,7 @@ module Hecks
         Dir.glob(File.join(copy, "**", "*.world")).each { |path| File.delete(path) }
       end
 
-      # SAME DANCE AS MEMORY, ONE ADAPTER OVER — `Adapters::Sqlite#
+      # Same dance as memory, one adapter over — `Adapters::Sqlite#
       # resolve_path` (adapters/driven/sqlite.rb) defaults to
       # `data/<table>.db` under the boot's own root when no `database`
       # setting is declared, which `data/` already being cleared makes a
@@ -143,27 +164,28 @@ module Hecks
       # nothing here creates it up front.
       def rebind_to_sqlite!(copy)
         rewrite_bindings!(copy, "SqlitePersistence")
+        strip_translations!(copy)
         Dir.glob(File.join(copy, "**", "*.world")).each { |path| File.delete(path) }
       end
 
-      # THE EXPENSIVE ONE — Postgres has no zero-config default the way
+      # **The expensive one** — Postgres has no zero-config default the way
       # Sqlite/Memory do (`Adapters::Postgres.connect_for` refuses outright
       # with no `database` setting), so dropping `.world` the way the
       # other two do would just move the WiringError from "wrong adapter"
       # to "no adapter." Every domain name this copy declares gets a
-      # FRESH `.world` written for it instead — not a rewrite of whatever
+      # fresh `.world` written for it instead — not a rewrite of whatever
       # was there, a replacement, same reasoning `rewrite_bindings!`
       # already applies to `.hecksagon`: this ephemeral boot owns every
       # binding decision, nothing about a real deployment's own settings
       # is relevant or safe to half-preserve here.
       #
-      # ONE SHARED SCHEMA, DROPPED AND RECREATED BEFORE EVERY BOOT — not a
+      # One shared schema, dropped and recreated before every boot — not a
       # fresh randomly-named one per call. `bin/fuzz` drives every
       # ephemeral boot sequentially (one `IsolatedBoot.call` fully exits
       # before the next begins — see that file's own single-threaded
       # `while` loop), so nothing is ever concurrent here ; a fresh name
       # every time would just leak schemas in `FUZZ_POSTGRES_DATABASE`
-      # forever with nothing to ever drop them. If a caller ever DOES
+      # forever with nothing to ever drop them. If a caller ever does
       # start running fuzz adapters concurrently, this needs to move to a
       # process-unique schema name (`SecureRandom.hex` is already
       # `require`d here for exactly that day) — flagged, not solved,
@@ -174,13 +196,14 @@ module Hecks
       def rebind_to_postgres!(copy)
         require "pg"
         rewrite_bindings!(copy, "Postgres")
+        strip_translations!(copy)
         ensure_fuzz_schema!
 
-        # ONE `.world` PER DIRECTORY A `.hecksagon` ACTUALLY LIVES IN, not
+        # One `.world` per directory a `.hecksagon` actually lives in, not
         # one at `copy`'s own root — `Folder#load_domain` resolves a
-        # SINGLE `bluebook_directory` and globs `*.world` there, non-
+        # single `bluebook_directory` and globs `*.world` there, non-
         # recursively (`Folder#load_each`); a domain can hold several
-        # `Hecks.hecksagon "<Name>" do ... end` SIBLING blocks in that one
+        # `Hecks.hecksagon "<Name>" do ... end` sibling blocks in that one
         # file (banking.hecksagon declares "Banking", "Governance", and
         # "Identity" together), so every name found in one `.hecksagon`
         # file gets bundled into one `.world` written beside it, not
@@ -202,7 +225,7 @@ module Hecks
           end.join("\n"))
         end
 
-        # Any PRE-EXISTING `.world` this copy shipped with (a real
+        # Any pre-existing `.world` this copy shipped with (a real
         # deployment's own connection string) is now redundant with — and
         # would conflict with, `Registry#add_world`'s own header on
         # loading the same domain name twice — the fresh one just
@@ -213,20 +236,20 @@ module Hecks
         end
       end
 
-      # ADMIN CONNECTION LIVES OUTSIDE THE TMP COPY ENTIRELY — same as
+      # Admin connection lives outside the tmp copy entirely — same as
       # every other real-Postgres spec in this repo (`support/
       # postgres_probe.rb`'s own header). Database created once per
       # process and remembered (`@fuzz_database_ready` on this module's
       # own singleton, the same memoization shape `PostgresProbe
       # .available?` already uses) ; the schema inside it is dropped and
-      # recreated on EVERY call, which is what actually isolates one
+      # recreated on every call, which is what actually isolates one
       # ephemeral boot's data from the next.
       def ensure_fuzz_schema!
-        # `Adapters::Postgres#initialize` opens ONE real `PG::Connection`
-        # PER AGGREGATE and never explicitly closes it — fine for a
+        # `Adapters::Postgres#initialize` opens one real `PG::Connection`
+        # per aggregate and never explicitly closes it — fine for a
         # process that boots once and runs, exactly what every other
         # caller of this adapter is. A fuzz run boots dozens to hundreds
-        # of EPHEMERAL times in one process (every seed does at least a
+        # of ephemeral times in one process (every seed does at least a
         # generate + a replay, `replay_is_deterministic` doubles that,
         # shrinking multiplies it further), and `PG::Connection` only
         # actually closes its socket when Ruby's GC finalizes the
@@ -238,7 +261,7 @@ module Hecks
         # ephemeral boots, `PG::ConnectionBad: ... "too many clients
         # already"`. A `GC.start` here — right before the next ephemeral
         # boot's connections open, not on some timer — reclaims every
-        # connection the PREVIOUS boot's now-unreferenced adapters held,
+        # connection the previous boot's now-unreferenced adapters held,
         # keeping the live count bounded regardless of run length. This
         # is a real constraint on running Postgres in a loop, not
         # something to route around by connecting less carefully.
@@ -255,7 +278,7 @@ module Hecks
         end
 
         db = PG.connect(dbname: FUZZ_POSTGRES_DATABASE)
-        # QUIET ON PURPOSE — same as `Adapters::Postgres.connect_for`'s
+        # **Quiet on purpose** — same as `Adapters::Postgres.connect_for`'s
         # own `SET client_min_messages`: a `DROP SCHEMA ... CASCADE` that
         # actually has something to drop (every boot after the first)
         # NOTICEs once per dropped object, which is the ordinary case
@@ -269,7 +292,132 @@ module Hecks
         db.close
       end
 
-      # THE SHARED REWRITE — factored out of `rebind_to_memory!` when
+      # The adapter `:postgres` never touches — `Postgres` and `PostgresEra`
+      # are sibling, not interchangeable, adapters (see postgres_era.rb's
+      # own header: "the only one that declares the LINEAGE capability").
+      # PRD 02 (docs/prds/02-fuzzer-real-adapters.md) shipped `:postgres`
+      # and explicitly scoped `PostgresEra` out: "nothing here touches
+      # era/lineage machinery." That gap is real, not cosmetic —
+      # `examples/directory` (a `compute`/`rekey` translation edge, the
+      # one domain in this corpus that actually exercises PostgresEra-
+      # bound SQL compilation) had to be shelved out of `hecks_qa`'s own
+      # rotation for exactly this reason: every existing fuzz/replay path,
+      # `:memory` included, structurally cannot reach it. This mode closes
+      # that — `bin/qa_sweep --persistence-parity` is its first caller.
+      #
+      # No shared constant database, unlike `:postgres` above — deliberate.
+      # `rebind_to_postgres!`'s own `FUZZ_POSTGRES_DATABASE`/`_SCHEMA` are
+      # module-level constants because `bin/fuzz --adapter postgres` is a
+      # general-purpose, run-it-anytime tool with no caller-tracked
+      # lifecycle of its own. This mode's only caller
+      # (`bin/qa_sweep --persistence-parity`) is different: it dispatches
+      # through `QualityControl::Target.claim!`'s own cross-process lock
+      # first (see that script's own header), so at most one sweep is ever
+      # touching a given target's own disposable database at a time — but
+      # the caller, not this module, is what owns that database's name and
+      # lifecycle (created, and genuinely dropped, by the caller itself),
+      # exactly the discipline `spec/support/qa_sweep_all_fixture.rb`'s own header
+      # describes and this repository's persistence-parity work is
+      # required to follow. Accepting `database:`/`schema:` as required
+      # keyword arguments (never a fallback constant) is what keeps that
+      # ownership from silently drifting back onto this module the way
+      # `:postgres`'s own `FUZZ_POSTGRES_DATABASE` already has.
+      def rebind_to_postgres_era!(copy, database:, schema:)
+        require "pg"
+        if database.to_s.empty? || schema.to_s.empty?
+          raise ArgumentError,
+                "adapter: :postgres_era requires both database: and schema: — a throwaway database/schema " \
+                "THIS CALLER creates and drops itself (see rebind_to_postgres_era!'s own header). " \
+                "There is no shared default, unlike :postgres, so the caller cannot forget to own the lifecycle."
+        end
+
+        rewrite_bindings!(copy, "PostgresEra")
+        ensure_postgres_era_schema!(database: database, schema: schema)
+
+        # Same one-`.world`-per-`.hecksagon`-directory shape `rebind_to_
+        # postgres!` already uses, for the identical reason (`Folder#
+        # load_domain` globs `*.world` non-recursively) — see that
+        # method's own comment on `world_path` above. `PostgresEra`
+        # additionally takes `schema:` (postgres_era.rb's own "shared-
+        # instance isolation" comment): the caller-supplied throwaway
+        # schema is what actually isolates this one ephemeral boot from
+        # the next, the same job `FUZZ_POSTGRES_SCHEMA` does for `:postgres`
+        # — `connect_for` itself idempotently `CREATE SCHEMA IF NOT
+        # EXISTS`s it, so this method only ever needs to drop it first
+        # (in `ensure_postgres_era_schema!`, below) for the zero-history
+        # guarantee every other adapter mode already gives.
+        #
+        # `allow_superuser true` — on the record, on purpose. A bare
+        # `database` connects as the ambient Postgres user, and
+        # PostgresEra refuses to boot at all when that user is a
+        # superuser (its era write-fence is row-level security, which a
+        # superuser walks through — `Lineage#check_fence_applies!`,
+        # BUG#24). That refusal protects a real ledger from an old
+        # checkout's stale writes; nothing here is one. This is an
+        # ephemeral boot into a throwaway schema the caller itself
+        # creates and drops, whose data no second checkout ever shares,
+        # and what it compares is Memory's answers against PostgresEra's
+        # own SQL — the era fence is not under test and cannot be
+        # crossed. So opt in explicitly rather than make every
+        # persistence-parity run first provision a fenced role for a
+        # database it is about to throw away; the one-line warning
+        # PostgresEra prints per boot under the opt-in is the honest
+        # price. Inert on a machine whose ambient user is ordinary.
+        Dir.glob(File.join(copy, "**", "*.hecksagon")).each do |hecksagon_path|
+          names = File.read(hecksagon_path).scan(/Hecks\.hecksagon\s+"([^"]+)"/).flatten.uniq
+          next if names.empty?
+
+          world_path = File.join(File.dirname(hecksagon_path), "hecks_fuzz_postgres_era.world")
+          File.write(world_path, names.map do |name|
+            <<~WORLD
+              Hecks.world "#{name}" do
+                persisted_by("PostgresEra") do
+                  database "#{database}"
+                  schema "#{schema}"
+                  allow_superuser true
+                end
+              end
+            WORLD
+          end.join("\n"))
+        end
+
+        Dir.glob(File.join(copy, "**", "*.world")).each do |path|
+          File.delete(path) unless File.basename(path) == "hecks_fuzz_postgres_era.world"
+        end
+      end
+
+      # The zero-history guarantee for this mode — `DROP SCHEMA ... CASCADE`
+      # before every ephemeral boot, mirroring `ensure_fuzz_schema!` above
+      # (same `GC.start`-before-connecting fix for the identical
+      # `max_connections` exhaustion that method's own comment documents —
+      # `PostgresEra` opens real `PG::Connection`s exactly like `Postgres`
+      # does, same unclosed-until-GC'd lifetime). The database itself is
+      # created here too, idempotently (`CREATE DATABASE IF NOT EXISTS`
+      # has no Postgres spelling, hence the existence check) — but never
+      # dropped here: this module creates it once per process because
+      # `Hecks.boot` needs it to exist before `PostgresEra.connect_for`'s
+      # own `PG.connect(dbname: ...)` can succeed at all, but dropping it
+      # again is the caller's own job (its name and lifecycle belong to
+      # the caller — see `rebind_to_postgres_era!`'s own header), not
+      # something this per-ephemeral-boot helper should ever do mid-sweep.
+      def ensure_postgres_era_schema!(database:, schema:)
+        GC.start
+
+        admin = PG.connect(dbname: "postgres")
+        exists = admin.exec_params(
+          "SELECT 1 FROM pg_database WHERE datname = $1", [database]
+        ).ntuples.positive?
+        admin.exec(%(CREATE DATABASE "#{database}")) unless exists
+        admin.close
+
+        db = PG.connect(dbname: database)
+        db.exec("SET client_min_messages = warning")
+        quoted = db.quote_ident(schema)
+        db.exec("DROP SCHEMA IF EXISTS #{quoted} CASCADE")
+        db.close
+      end
+
+      # The shared rewrite — factored out of `rebind_to_memory!` when
       # Sqlite/Postgres modes needed the identical `.hecksagon` surgery
       # with only the target adapter name differing. `persisted_by`/
       # `projected_by` can be spelled two ways: aggregate-scoped
@@ -283,6 +431,46 @@ module Hecks
       # #read_repository` already falls back to the authoritative
       # repository when none exists, so a read model this ephemeral copy
       # never wires is simply unread, not broken.
+      # A `compute`/`rekey` translation edge refuses to boot at all under
+      # any non-lineage-capable adapter — found live, wiring this very
+      # mode up against `examples/directory`: `Runtime::EraCheck
+      # .check_compute_rules!` (era_check.rb) runs unconditionally for
+      # every loaded bluebook once the era plugin is loaded at all
+      # (`bin/qa_sweep`'s own top-of-file `require "hecks/ports/
+      # persistence/plugins/era"`, needed for the ledger's own
+      # PostgresEra-bound aggregates), and refuses outright — "compute
+      # rules require the Postgres adapter" — for any aggregate whose
+      # lineage carries a `compute` rule and whose bound adapter is not
+      # lineage-capable. `PostgresEra` is the only adapter that answers
+      # `lineage_capable? == true` (postgres_era.rb's own `self.
+      # lineage_capable? = true`) — plain `Postgres` does not, so this
+      # refusal was already real for `:postgres`/`:sqlite`/`:memory`
+      # alike, for any domain with a translation edge, before this
+      # mode's own `:postgres_era` ever existed. This is very likely the
+      # mechanical reason `examples/directory` had to be shelved out of
+      # `hecks_qa`'s own rotation in the first place — not merely "less
+      # interesting to fuzz on Memory," but "cannot boot on Memory at
+      # all" once the era plugin is loaded, which every real
+      # `bin/qa_sweep` invocation already does.
+      #
+      # The fix is to drop the edge, not to chase the refusal — an
+      # ephemeral, zero-history replay boot (every mode `IsolatedBoot`
+      # offers) never has a pre-existing era-1 row to translate in the
+      # first place, so the translation edge is irrelevant to anything a
+      # fuzz/replay run actually exercises (ordinary command dispatch
+      # against a fresh boot) — it only ever matters at mint time,
+      # against a real, pre-existing database
+      # (`PostgresEra::LineageManager.check!`, a wholly separate,
+      # human-approved path this harness was never meant to reach).
+      # Dropping it here is exactly the same move `rebind_to_memory!`
+      # already makes for `.world` (irrelevant/conflicting settings for
+      # an ephemeral boot, deleted outright) — never called for
+      # `:postgres_era` itself, where the bound adapter genuinely is
+      # lineage-capable and the edge causes no refusal to begin with.
+      def strip_translations!(copy)
+        Dir.glob(File.join(copy, "**", "translations", "*.bluebook")).each { |path| File.delete(path) }
+      end
+
       def rewrite_bindings!(copy, adapter_name)
         Dir.glob(File.join(copy, "**", "*.hecksagon")).each do |path|
           lines = File.readlines(path).grep_v(/\bprojected_by\s*\(?\s*"/)

data/lib/hecks/fuzzing/nondeterministic.rb

@@ -0,0 +1,67 @@
+module Hecks
+  module Fuzzing
+    # The one declared set of FIELDS that leave a comparison — partition,
+    # not filter. Every comparison in lib/hecks/fuzzing that drops a field
+    # before comparing two histories names a group here instead of writing
+    # its own literal `except(...)` list, so the reason for dropping a field
+    # is written exactly once, beside the field.
+    #
+    # Two specs hold this set honest (spec/fuzzing/nondeterministic_spec.rb):
+    # a literal except-list naming any of these fields anywhere under
+    # lib/hecks/fuzzing fails the build (the tolerance must be declared
+    # here, not re-derived at a call site), and every declared field must
+    # actually be produced where its group says — a field nothing emits any
+    # more is a stale tolerance and fails too.
+    #
+    # Groups are keyed by the shape the field rides on, since the same name
+    # can be compared on one surface and dropped on another:
+    #
+    # - `query_row`  — one entry of `Replay.call`'s `:queries`.
+    # - `outbox_row` — one row of an `:outbox_traces` entry's `:rows`.
+    # - `event`      — an event hash in full `Event#to_h` form (an outbox
+    #                  row's `:event`, or a Rust binary's `events` entries,
+    #                  string-keyed there).
+    # - `history`    — the top-level `Replay.call` history hash itself.
+    module Nondeterministic
+      FIELDS = {
+        query_row:  {
+          instances_at: "a full state snapshot taken for the query oracle's own use " \
+                        "(Properties::Querying); the same state is already compared as `instances`, " \
+                        "so keeping it would re-report one instances divergence under every query step"
+        }.freeze,
+        outbox_row: {
+          event_uid:   "`Runtime::Outbox::Fanout#rows_for`'s own SecureRandom.uuid, minted fresh per " \
+                       "enqueue and kept off `Event#to_h` — relay bookkeeping, never something the " \
+                       "domain produced, so two otherwise-identical replays carry two different uuids",
+          delivery_id: "`\"\#{event_uid}/\#{consumer}\"` — inherits event_uid's per-enqueue uuid"
+        }.freeze,
+        event:      {
+          occurred_at: "a wall-clock read; never reproducible byte-for-byte between two independent " \
+                       "runs (Replay's own projected `:events` leave it off for the same reason)"
+        }.freeze,
+        history:    {
+          bluebook:  "a live IR object (the first-loaded bluebook) handed to properties — an object " \
+                     "identity, not a value, so two boots never compare equal on it",
+          bluebooks: "the full live IR map, keyed by domain — object identities, same as `bluebook`"
+        }.freeze
+      }.freeze
+
+      module_function
+
+      def names(group)
+        FIELDS.fetch(group).keys
+      end
+
+      # Every declared name, across every group.
+      def all_names
+        FIELDS.values.flat_map(&:keys).uniq
+      end
+
+      # `hash` without `group`'s fields — symbol keys, the shape every
+      # Ruby-side history carries.
+      def strip(hash, group)
+        hash.except(*names(group))
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/persistence_parity.rb

@@ -0,0 +1,161 @@
+require "json"
+require_relative "replay"
+require_relative "nondeterministic"
+
+module Hecks
+  module Fuzzing
+    # **The second differential axis** — bin/qa_sweep's own `diff_ruby_vs_rust`
+    # compares two different engines (the Ruby interpreter vs the compiled
+    # Rust kernel) against the same persistence (Memory, always — see
+    # `SequenceGenerator`'s own header: sequence generation stays
+    # Memory-only, and `IsolatedBoot`'s own header explains why every
+    # existing fuzz/replay path structurally cannot reach a real Postgres-
+    # bound domain's own SQL compilation). This module compares the
+    # opposite pairing: the same one Ruby engine, against two different
+    # persistences — Memory (the reference, exactly as fast and as
+    # deterministic as every other fuzz check) and a real, disposable
+    # `PostgresEra` database (the actual SQL compute/rekey/query-pushdown
+    # path a Postgres-bound domain's users really hit).
+    #
+    # `examples/directory` is why this exists at all: the one domain in
+    # this corpus with a real `compute`/`rekey` translation edge
+    # (docs/prds/02-fuzzer-real-adapters.md's own "What shipped" section
+    # names it directly), which no existing fuzz/replay/property check has
+    # ever been able to exercise against real PostgresEra SQL — every one
+    # of them boots through `IsolatedBoot`, and until `adapter:
+    # :postgres_era` existed (isolated_boot.rb's own header), that meant
+    # Memory, unconditionally, no matter what `directory.world` itself
+    # declares.
+    #
+    # Not a replacement for `bin/qa_sweep`'s own Ruby-vs-Rust differential
+    # mode — a genuinely separate axis, opt-in (`--persistence-parity`),
+    # because this one pays for a real `PG.connect` and real SQL per
+    # dispatch where Memory-vs-Rust pays for neither. See `bin/qa_sweep`'s
+    # own `--persistence-parity` handling for the seed-count dial that
+    # keeps that cost bounded.
+    #
+    # Generalized to `left:`/`right:` — originally hardcoded to Memory vs
+    # PostgresEra (the only pairing that existed), now any two of
+    # `IsolatedBoot`'s own adapter symbols (`:memory`, `:sqlite`,
+    # `:postgres`, `:postgres_era`). Defaults preserve the original
+    # pairing exactly, so every existing caller (this file's own spec,
+    # `bin/qa_sweep`'s `--persistence-parity`) is unchanged. The second
+    # pairing this generalization exists for is Memory vs SQLite
+    # (`QualityControlDials::ADAPTER_PARITY_PAIRS`, `bin/qa_sweep`'s own
+    # `adapter_parity_sqlite` mode) — `:sqlite` is nearly as cheap as
+    # Memory itself (`IsolatedBoot#rebind_to_sqlite!`'s own header: an
+    # on-disk file, no server, no disposable database/schema lifecycle to
+    # own), so that pairing folds straight into the ordinary per-seed
+    # loop instead of needing a deferred wave of its own the way
+    # PostgresEra does.
+    #
+    # `database:`/`schema:` — required only when `:postgres_era` is one of
+    # the two adapters (the caller — today, only `bin/qa_sweep` — owns the
+    # disposable database's whole lifecycle: created before the sweep,
+    # dropped after — see that script's own comment, and the discipline
+    # `IsolatedBoot#rebind_to_postgres_era!` itself refuses to let a
+    # caller skip); every other adapter ignores both, same as `Replay.
+    # call`/`IsolatedBoot.call` already do for their own `adapter:`.
+    module PersistenceParity
+      module_function
+
+      # The same six fields `bin/qa_sweep`'s own `diff_ruby_vs_rust`
+      # compares (its own comment: "instances, events, refusals, queries,
+      # sagas, reactions") — deliberately the identical set, so a report
+      # this mode produces reads exactly like the sibling mode's own,
+      # differing only in which two things were compared, not in what
+      # "found something" means.
+      #
+      # Simpler normalization than `diff_ruby_vs_rust`, on purpose — that
+      # method reduces Rust's own JSON-over-stdout output to "wire
+      # precision" and filters known Ruby/Rust structural gaps, because
+      # it is comparing two genuinely different engines that are allowed
+      # to differ in already-catalogued, understood ways. Both sides here
+      # are the same Ruby engine (`Replay.call`, called twice, adapter
+      # only) — there is no second engine's own known-gap catalogue to
+      # filter against, so any real difference is the finding. Both
+      # results still round-trip through `JSON.generate`/`JSON.parse`
+      # before comparing, matching `diff_ruby_vs_rust`'s own discipline —
+      # not because either side needs a wire-format reduction, but so
+      # `Hash#==`/`Array#==` compares plain, JSON-shaped data on both
+      # sides identically (a `Runtime::Value`, a `Symbol` key, a `Time`
+      # nobody asked for — none of that survives an accidental leak into
+      # this comparison unnoticed).
+      def diff(domain_path, steps, left: :memory, right: :postgres_era, database: nil, schema: nil)
+        left_result  = Replay.call(domain_path, steps, adapter: left, database: database, schema: schema)
+        right_result = Replay.call(domain_path, steps, adapter: right, database: database, schema: schema)
+
+        divergences = []
+        divergences.concat(diff_instances(left_result, right_result, left, right))
+        divergences.concat(diff_events(left_result, right_result, left, right))
+        divergences.concat(diff_refusals(left_result, right_result, left, right))
+        divergences.concat(diff_queries(left_result, right_result, left, right))
+        divergences.concat(diff_sagas(left_result, right_result, left, right))
+        divergences.concat(diff_reactions(left_result, right_result, left, right))
+        divergences
+      end
+
+      def as_json(value) = JSON.parse(JSON.generate(value))
+
+      def diff_instances(left_result, right_result, left, right)
+        l = as_json(left_result[:instances])
+        r = as_json(right_result[:instances])
+        return [] if l == r
+
+        [{ field: "instances", left => l, right => r }]
+      end
+
+      def diff_events(left_result, right_result, left, right)
+        l = as_json(left_result[:events])
+        r = as_json(right_result[:events])
+        return [] if l == r
+
+        [{ field: "events", left => l, right => r }]
+      end
+
+      # `verb:`/`kind:` normalized to plain strings the same way
+      # `diff_ruby_vs_rust`'s own `ruby_refusals` mapping does — both
+      # sides here already answer strings (`Replay#refusal_kind` always
+      # returns one), so this is belt-and-suspenders consistency with the
+      # sibling mode's own shape, not a real coercion.
+      def diff_refusals(left_result, right_result, left, right)
+        normalize = lambda do |refusals|
+          refusals.map { |r| { "verb" => r[:verb].to_s, "kind" => r[:kind].to_s, "error" => r[:error] } }
+        end
+        l = normalize.call(left_result[:refusals])
+        r = normalize.call(right_result[:refusals])
+        return [] if l == r
+
+        [{ field: "refusals", left => l, right => r }]
+      end
+
+      # `Nondeterministic`'s `query_row` group dropped from every entry —
+      # the same group `Differential.diff` drops, for the reason declared
+      # there (already covered by `diff_instances` above).
+      def diff_queries(left_result, right_result, left, right)
+        strip = ->(rows) { rows.map { |row| Nondeterministic.strip(row, :query_row) } }
+        l = as_json(strip.call(left_result[:queries]))
+        r = as_json(strip.call(right_result[:queries]))
+        return [] if l == r
+
+        [{ field: "queries", left => l, right => r }]
+      end
+
+      def diff_sagas(left_result, right_result, left, right)
+        l = as_json(left_result[:sagas])
+        r = as_json(right_result[:sagas])
+        return [] if l == r
+
+        [{ field: "sagas", left => l, right => r }]
+      end
+
+      def diff_reactions(left_result, right_result, left, right)
+        l = as_json(left_result[:reactions])
+        r = as_json(right_result[:reactions])
+        return [] if l == r
+
+        [{ field: "reactions", left => l, right => r }]
+      end
+    end
+  end
+end