hecks 1.2.0 → 1.3.0

data/lib/hecks/fuzzing/isolated_boot.rb

@@ -44,11 +44,21 @@ 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
 
@@ -65,16 +75,26 @@ 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
@@ -118,6 +138,7 @@ 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
@@ -143,6 +164,7 @@ 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
 
@@ -174,6 +196,7 @@ 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
@@ -269,6 +292,131 @@ module Hecks
         db.close
       end
 
+      # 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/qa_sweep_all_spec.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`/
@@ -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/persistence_parity.rb

@@ -0,0 +1,163 @@
+require "json"
+require_relative "replay"
+
+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
+
+      # `instances_at:` dropped from every entry — the same reason
+      # `diff_ruby_vs_rust` excludes it (`row.except(:instances_at)`):
+      # it is a full state snapshot taken for the QUERY oracle's own use,
+      # already covered by `diff_instances` above, and would make every
+      # query-step entry re-litigate the SAME instances divergence a
+      # second time under a different field name.
+      def diff_queries(left_result, right_result, left, right)
+        strip = ->(rows) { rows.map { |row| row.except(:instances_at) } }
+        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

data/lib/hecks/fuzzing/properties/corrections.rb

@@ -0,0 +1,100 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # ANGLE-9 — `corrects` (retroactive correction) had exactly one
+      # declaration anywhere in the corpus (`examples/banking/bluebook/
+      # deposit_accounts.bluebook:353`, aggregate-level) and no property
+      # anywhere in this file ever checked it, and no `FEATURE_COVERAGE`
+      # claim either — confirmed absent before this file existed. `qa/
+      # stress_domains/corrections` gives it its first real coverage; see
+      # that domain's own NOTES.md for what it found (an entity-level
+      # `corrects` crashes Ruby at dispatch outright, and Rust's own
+      # generated code has NO admissibility check for it AT ALL — neither
+      # engine can be compared on the untested combination this property
+      # was written to watch, which is itself the headline finding).
+      module Corrections
+        # Every event named by a `corrects` mutation, on any command a
+        # booted history's own bluebooks declare — aggregate-level, or
+        # nested inside an entity at any depth (`each_command_including_
+        # entities`, below, is the same recursive walk `SequenceGenerator::
+        # Catalog#each_entity_chain` already uses, for the identical reason:
+        # `Aggregate#entities`/`Entity#entities` nest, ADR 0026, S17). For
+        # every such command, every event THIS history actually recorded
+        # under one of the command's own `emits` names must have an event
+        # named by the command's own `corrects` target — same aggregate-
+        # qualified name, same id — appearing STRICTLY EARLIER in the same
+        # history.
+        #
+        # `history[:events]` is already in occurrence order (`Replay.call`'s
+        # own `runtime.events`, appended as each step dispatches) — "earlier"
+        # is therefore "earlier in this array," no timestamp comparison
+        # needed, and no per-step attribution back to which command produced
+        # which event is needed either: an event's own declared NAME already
+        # identifies the one command in its aggregate that can produce it
+        # (`AggregateBuilder::Sealing#seal_correction_targets`'s own
+        # `emitted_by` hash reads the identical fact, one level shallower).
+        #
+        # WHY THIS CANNOT BE `GUARANTEED_BY_CONSTRUCTION` THE WAY THE
+        # AGGREGATE-LEVEL CASE ALMOST IS: `CommandRules::Admissibility#
+        # enforce_correction_target` (the dispatch-time check) and
+        # `AggregateBuilder::Sealing#seal_correction_targets` (the build-time
+        # check) both exist ONLY for an aggregate-level `corrects` —
+        # `EntityInterpreter#step_enforce_givens` never calls the former at
+        # all, and the latter walks only `@commands` (the aggregate's own
+        # top-level list), never `@entities`. An entity-level `corrects`
+        # mutation is invisible to BOTH doors today — this property is the
+        # only thing anywhere, on either engine, that would ever catch one
+        # going wrong.
+        def corrections_reference_an_emitted_event(history)
+          violations = []
+
+          (history[:bluebooks] || {}).each do |domain, bluebook|
+            bluebook.aggregates.each do |aggregate|
+              aggregate_key = "#{domain}::#{aggregate.hecks_name}"
+
+              each_command_including_entities(aggregate) do |command|
+                corrects_mutations = command.mutations.select { |mutation| mutation.op == :corrects }
+                next if corrects_mutations.empty?
+
+                corrects_mutations.each do |mutation|
+                  corrected_event = mutation.target.to_s
+
+                  command.emits.each do |produced_event_name|
+                    violations.concat(unmatched_corrections(history[:events], aggregate_key,
+                                                            produced_event_name.to_s, corrected_event,
+                                                            command.hecks_name))
+                  end
+                end
+              end
+            end
+          end
+
+          violations.empty? || violations.uniq.join("; ")
+        end
+
+        def unmatched_corrections(events, aggregate_key, produced_event_name, corrected_event, command_name)
+          own_events = events.each_with_index.select do |event, _index|
+            event[:name] == produced_event_name && event[:aggregate] == aggregate_key
+          end
+
+          own_events.filter_map do |event, index|
+            preceding = events.first(index)
+            next if preceding.any? do |earlier|
+              earlier[:name] == corrected_event && earlier[:aggregate] == aggregate_key &&
+              earlier[:id].to_s == event[:id].to_s
+            end
+
+            "#{command_name} (#{aggregate_key}##{event[:id]}) emitted #{produced_event_name}, claiming to " \
+              "correct #{corrected_event}, but no #{corrected_event} for the same aggregate/id appears " \
+              "earlier in this history"
+          end
+        end
+
+        def each_command_including_entities(owner, &block)
+          owner.commands.each(&block)
+          owner.entities.each { |entity| each_command_including_entities(entity, &block) }
+        end
+      end
+    end
+  end
+end