hecks 1.2.0 → 1.3.0

data/lib/hecks/fuzzing/concurrent_dispatch.rb

@@ -0,0 +1,266 @@
+require "fileutils"
+require "tmpdir"
+require "tempfile"
+require "json"
+require_relative "isolated_boot"
+
+module Hecks
+  module Fuzzing
+    # A GENERATED SEQUENCE, RACED FOR REAL — `spec/adapters/driven/
+    # postgres_era_concurrent_dispatch_spec.rb` proves ADR 0036's own fix
+    # (a real `pg_advisory_xact_lock` serializes a PostgresEra-bound
+    # dispatch across separate OS processes) against ONE hand-authored
+    # fixture and ONE hand-picked conflicting pair (two `$6,000` Debits
+    # against a `$10,000` account). This module asks the SAME question —
+    # does the cross-process write lock actually serialize concurrent
+    # writers? — of an ARBITRARY generated sequence against a REAL target
+    # domain, so the practice's own adversarial generator gets to pick the
+    # conflict instead of a human picking it once and never again.
+    #
+    # THE MECHANISM, GENERALIZED FROM THAT SPEC RATHER THAN REDERIVED: a
+    # command step partway through a generated sequence is chosen as the
+    # RACE STEP; every step before it is SETUP (replayed once, sequentially,
+    # to bring a fresh disposable schema to the state the race step expects
+    # to act against); the race step is then dispatched TWICE — once from
+    # each of two real, separate, forked OS processes racing against that
+    # SAME schema, no artificial gating, whichever the scheduler favors.
+    #
+    # THE ORACLE IS THE SAME PAIR, DISPATCHED SEQUENTIALLY, NOT A
+    # HARDCODED EXPECTATION — unlike the hand-authored spec (which can
+    # assert `%w[refused succeeded]` because it knows its own fixture's
+    # business rule), this module has no idea whether an arbitrary
+    # generated race step conflicts with itself at all. So it asks the
+    # DOMAIN: replay the identical setup on a SEPARATE fresh schema, then
+    # dispatch the SAME race step twice, one after the other, in one
+    # process, with no contention at all — genuinely correct by
+    # construction, since nothing else can touch that schema while it
+    # runs. Two conflicting writes settle as {"succeeded", "refused"};
+    # two independent ones settle as {"succeeded", "succeeded"}; either
+    # way, THAT is the multiset the concurrent pair must also produce if
+    # the write lock actually serializes them — order does not matter
+    # (which real racer wins a genuine race is never controlled), the SET
+    # of outcomes does.
+    #
+    # WHAT A BROKEN LOCK LOOKS LIKE HERE: the concurrent pair settling as
+    # {"succeeded", "succeeded"} where the sequential oracle says
+    # {"succeeded", "refused"} — two processes each hydrated the
+    # pre-write state, neither saw the other's write, and the second
+    # commit landed as a silent lost update instead of failing its own
+    # `given`. That is the EXACT corruption class ADR 0036 fixed for
+    # PostgresEra and `postgres_concurrent_dispatch_spec.rb` still
+    # documents, unfixed, for plain Postgres.
+    #
+    # NOT A REPLACEMENT for the hand-authored spec — that spec proves the
+    # mechanism once, precisely, with controlled gating so the assertion
+    # is deterministic; this module proves the SAME mechanism holds for
+    # whatever a real domain's own generated sequences throw at it, with
+    # no gating (a genuine, ungated race), on every sweep this mode runs.
+    module ConcurrentDispatch
+      module_function
+
+      COMMAND_STEP = ->(step) { step["verb"] && !step["query"] && !step["dry_run"] }
+
+      # ONE DIVERGENCE LIST, THE SAME SHAPE EVERY OTHER MODE IN THIS
+      # PRACTICE PRODUCES — `[]` when nothing was found (including the
+      # legitimate "this seed's generated sequence has no command step to
+      # race at all" case: a sequence of pure queries/dry-runs has nothing
+      # to concurrently dispatch, and that is not a finding).
+      #
+      # `database:` is the shared, never-dropped scratch database
+      # (`bin/qa_sweep`'s own `persistence_parity_database`, reused here
+      # for the identical reason: a container, not the thing that's
+      # unique per run). `race_schema:`/`reference_schema:` are two
+      # DIFFERENT disposable schema names this ONE call owns for its own
+      # duration — the caller creates neither ahead of time (both are
+      # wiped fresh by the boots below) and drops both afterward, the
+      # same lifecycle `persistence_parity_schema` already has.
+      def check(domain_path, steps, database:, race_schema:, reference_schema:)
+        normalized = steps.map { |step| step.transform_keys(&:to_s) }
+        race_index = pick_race_index(normalized)
+        return [] unless race_index
+
+        setup_steps = normalized[0...race_index]
+        race_step   = normalized[race_index]
+
+        reference  = reference_outcomes(domain_path, setup_steps, race_step, database: database, schema: reference_schema)
+        concurrent = concurrent_outcomes(domain_path, setup_steps, race_step, database: database, schema: race_schema)
+
+        divergences_for(race_step, reference, concurrent)
+      rescue StandardError => e
+        [{ field: "process", detail: "#{e.class}: #{e.message}" }]
+      end
+
+      # THE COMMAND STEP CLOSEST TO THE MIDDLE OF THE SEQUENCE — not the
+      # first (racing a bare identity-creation with no setup at all is a
+      # legitimate, useful case, so index 0 is not excluded) and not
+      # chosen for any domain-specific reason: a mid-sequence step has, on
+      # average, the deepest state to act against and the best odds of
+      # actually conflicting with itself. `nil` when the generated
+      # sequence has no command step at all (every step a query or a dry
+      # run) — nothing here for this seed to race.
+      def pick_race_index(steps)
+        command_indices = steps.each_index.select { |i| COMMAND_STEP.call(steps[i]) }
+        return nil if command_indices.empty?
+
+        command_indices[command_indices.size / 2]
+      end
+
+      def divergences_for(race_step, reference, concurrent)
+        crashes = (reference + concurrent).select { |outcome| outcome.start_with?("crashed:") }.uniq
+        return crashes.map { |c| { field: "concurrency_crash", verb: race_step["verb"], detail: c } } if crashes.any?
+
+        return [] if reference.sort == concurrent.sort
+
+        [{ field: "concurrency_race", verb: race_step["verb"], reference: reference, concurrent: concurrent,
+           detail: "two concurrent cross-process dispatches of #{race_step['verb']} settled as #{concurrent.sort} " \
+                   "where the identical pair, dispatched sequentially with no contention, settled as " \
+                   "#{reference.sort} — the cross-process write lock did not correctly serialize this write" }]
+      end
+
+      # THE ORACLE — one boot, one process, the setup then the race step
+      # TWICE in immediate succession. Nothing else ever touches this
+      # schema while this runs, so whatever the domain itself settles on
+      # is correct by construction, not asserted.
+      def reference_outcomes(domain_path, setup_steps, race_step, database:, schema:)
+        outcomes = []
+        IsolatedBoot.call(domain_path, adapter: :postgres_era, database: database, schema: schema) do |copy|
+          runtime = Hecks.boot(copy)
+          dispatch_all!(runtime, setup_steps)
+          outcomes << dispatch_one(runtime, race_step)
+          outcomes << dispatch_one(runtime, race_step)
+        end
+        outcomes
+      end
+
+      # THE RACE ITSELF — setup runs ONCE, sequentially, in THIS process
+      # (the same `IsolatedBoot.call` wipe-then-boot every other mode
+      # here already uses), and only THEN do the two real racers run.
+      # Each racer boots its OWN fresh copy of the domain against the
+      # SAME now-populated schema — `boot_preserving_schema`, below,
+      # deliberately skips the wipe `IsolatedBoot.call` always does, or
+      # the setup this line just wrote would be gone before either racer
+      # ever dispatched anything.
+      #
+      # REAL, SEPARATE OS PROCESSES, NOT `Thread.new` — `postgres_era_
+      # concurrent_dispatch_spec.rb`'s own header explains why:
+      # `Runtime::AggregateLock`'s in-process registry would fully (and
+      # misleadingly) serialize two THREADS sharing one process even with
+      # the cross-process lock fix reverted. Only two genuinely separate
+      # OS processes exercise the gap this check exists to catch.
+      #
+      # `Process.spawn`, NOT `Process.fork` — `bin/qa_sweep`'s own
+      # top-of-file comment on `--all` names the identical hazard this
+      # sidesteps: by the time a `concurrency` seed runs, THIS process
+      # already holds the QualityControl ledger's own live PostgresEra
+      # connection (this module's own caller, `bin/qa_sweep`, booted it
+      # long before any seed ran). `Process.fork` duplicates every open
+      # file descriptor, SSL session state included — confirmed live
+      # while wiring this mode up: forking directly from here corrupted
+      # the LEDGER's own connection the moment either racer child exited,
+      # surfacing on the NEXT unrelated ledger write, nowhere near this
+      # method's own code. `bin/qa_concurrency_racer` is this method's own
+      # worker, one real `ruby` process per racer — read that script's own
+      # header for the rest of this reasoning.
+      def concurrent_outcomes(domain_path, setup_steps, race_step, database:, schema:)
+        IsolatedBoot.call(domain_path, adapter: :postgres_era, database: database, schema: schema) do |copy|
+          dispatch_all!(Hecks.boot(copy), setup_steps)
+        end
+
+        root = File.expand_path("../../..", __dir__)
+        racer = File.join(root, "bin/qa_concurrency_racer")
+        args_json = JSON.generate(race_step["args"] || {})
+        logs = Array.new(2) { Tempfile.new(["qa-concurrency-racer-", ".log"]) }
+        logs.each(&:unlink)
+
+        pids = logs.map do |log|
+          Process.spawn("bundle", "exec", "ruby", racer, domain_path, database, schema, race_step["verb"], args_json,
+                        out: log, err: log, chdir: root)
+        end
+
+        pids.each { |pid| Process.wait(pid) }
+        logs.map do |log|
+          log.rewind
+          output = log.read
+          log.close
+          output.strip.empty? ? "crashed:no output from bin/qa_concurrency_racer" : output.lines.last.chomp
+        end
+      end
+
+      # ONE STEP, ONE OUTCOME — never raises: a declared domain refusal is
+      # "refused" (the expected, ordinary answer a `given`/invariant can
+      # give), anything else escaping is "crashed:<class>: <message>", a
+      # genuine finding this module's own caller surfaces rather than lets
+      # kill a forked racer silently.
+      def dispatch_one(runtime, step)
+        args = (step["args"] || {}).transform_keys(&:to_sym)
+        runtime.dispatch(step["verb"], **args)
+        "succeeded"
+      rescue *Hecks::Runtime::DOMAIN_REFUSALS, Hecks::Bluebook::Expression::EvaluationError
+        "refused"
+      rescue StandardError => e
+        "crashed:#{e.class}: #{e.message}"
+      end
+
+      # SETUP TOLERATES AN ORDINARY REFUSAL (a generated sequence's own
+      # earlier step can legitimately refuse — every other mode in this
+      # practice already replays a prefix that way) but never a crash: an
+      # unexpected exception during setup means the schema this race is
+      # about to run against is in an unknown state, which is itself
+      # worth surfacing, not silently racing anyway.
+      def dispatch_all!(runtime, steps)
+        steps.each do |step|
+          outcome = dispatch_one(runtime, step)
+          raise "setup step #{step['verb']} #{outcome}" if outcome.start_with?("crashed:")
+        end
+      end
+
+      # THE SAME COPY-AND-REBIND `IsolatedBoot.call(..., adapter:
+      # :postgres_era, ...)` DOES, MINUS THE SCHEMA WIPE — deliberately
+      # NOT reusing `IsolatedBoot.rebind_to_postgres_era!` itself, which
+      # bundles `ensure_postgres_era_schema!`'s own `DROP SCHEMA` into the
+      # same call with no way to opt out (see that method's own header:
+      # the wipe is the "zero-history guarantee every other adapter mode
+      # already gives," exactly the guarantee THIS caller must NOT have —
+      # the whole point of a race is booting against what setup already
+      # wrote). `copy_dereferencing`/`rewrite_bindings!` are the same two
+      # public steps that method itself calls first; only the `.world`
+      # this writes is duplicated from it, not re-derived, because the
+      # shape a `PostgresEra`-bound copy's `.world` needs is exactly that
+      # method's own, one step short.
+      def boot_preserving_schema(domain_path, database:, schema:)
+        Dir.mktmpdir("hecks-concurrency") do |tmp|
+          copy = File.join(tmp, File.basename(domain_path))
+          IsolatedBoot.copy_dereferencing(domain_path, copy)
+          FileUtils.rm_rf(File.join(copy, "data"))
+          IsolatedBoot.rewrite_bindings!(copy, "PostgresEra")
+          write_postgres_era_world!(copy, database: database, schema: schema)
+          yield copy
+        end
+      end
+
+      def write_postgres_era_world!(copy, database:, schema:)
+        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
+    end
+  end
+end

data/lib/hecks/fuzzing/era_boundary.rb

@@ -0,0 +1,105 @@
+require "hecks/ports/persistence/plugins/era"
+
+module Hecks
+  module Fuzzing
+    # THE FORK-LOSS CLASS, AS A CHECK — not a fuzz. Every other mode in
+    # this file generates a sequence and compares two answers to the SAME
+    # question; this one asks a single, unconditional question of a
+    # target's own REAL, already-configured `PostgresEra` ledger:
+    # does any ancestor era still hold writes nobody has merged forward?
+    #
+    # THE BUG THIS TARGETS, NAMED EXACTLY. Minting a new era (an attribute
+    # or aggregate addition — `StorageShape.project`, lib/hecks/ports/
+    # persistence/plugins/era/storage_shape.rb) advances the readable head
+    # to a NEW partition; an OLD checkout, or a process that boots slower
+    # than the mint, can keep writing into the era it still believes is
+    # current. Those writes are not lost — `Lineage#diverged_count`
+    # (postgres_era/lineage/tail_merge.rb) can always find them — but
+    # nothing EVER asked it automatically. The practice's own ledger found
+    # exactly this live, twice: once as an operational gap this session's
+    # Step 0 recovered by hand (`bin/merge_tail`, three conflicting
+    # records, three eras deep), and once as BUG#24 (a superuser
+    # connection walking straight through the era write-fence — fixed by
+    # refusing that connection outright, `Lineage#check_fence_applies!`).
+    # Both are "a fork happened and nothing said so" — this module is the
+    # automatic version of the question `bin/merge_tail`'s own diagnostic
+    # line already answers by hand, run as an ordinary sweep Check instead
+    # of only when a human remembers to ask.
+    #
+    # THE TARGET'S REAL DATABASE, READ-ONLY, NEVER A DISPOSABLE ONE — every
+    # other Postgres-touching mode here (`persistence_parity`,
+    # `adapter_parity_sqlite`) owns a throwaway schema for the exact
+    # reason it must never look at what a real deployment actually holds;
+    # this check exists FOR what a real deployment actually holds, so it
+    # connects the same way `bin/merge_tail` itself does — the target's
+    # own `.world` binding — and never writes anything: `eras`/
+    # `diverged_count` are both plain `SELECT`s, and `ensure_base!` only
+    # ever provisions (`CREATE TABLE IF NOT EXISTS`) when THIS connection
+    # is the database's own provisioning owner, the identical idempotent
+    # call every ordinary boot already makes. A target with no real,
+    # reachable database configured (nothing provisioned locally, say) is
+    # reported `checked: false` with the reason — an operational note this
+    # mode's own caller surfaces once, never a crash and never silently
+    # "clean".
+    module EraBoundary
+      module_function
+
+      # `{ checked: true, diverged_total:, breakdown: [{ordinal:, diverged:}] }`
+      # or `{ checked: false, reason: "..." }` — the caller decides what a
+      # `false` means (an operational note, not a finding); a `true` with
+      # `diverged_total.positive?` is the finding this module exists to
+      # surface: real post-cut writes an ancestor era is still holding.
+      def diverged_ancestor_writes(domain_path)
+        registry, directory = load_registry(domain_path)
+        bluebook = registry.bluebooks.values.first
+        return unchecked("no bluebook in #{directory}") unless bluebook
+
+        first = bluebook.aggregates.first
+        return unchecked("#{bluebook.name} declares no aggregates") unless first
+
+        adapter_name = Hecks::Ports::Persistence::BindingPolicy.resolve(registry, bluebook.name, first).adapter
+        return unchecked("#{bluebook.name} is bound to #{adapter_name}, not PostgresEra") unless adapter_name == "PostgresEra"
+
+        settings = registry.world(bluebook.name)&.for_binding(Hecks::Ports::Persistence::VERB, adapter_name) || {}
+        db = Hecks::Adapters::PostgresEra.connect_for(bluebook.name, settings)
+        begin
+          lineage = Hecks::Adapters::PostgresEra::Lineage.new(db, bluebook.name)
+          lineage.ensure_base!
+          eras = lineage.eras
+          # `bin/merge_tail`'s own arithmetic, restated read-only: every
+          # ancestor era (every ordinal strictly before the head's own) may
+          # still hold post-cut writes the head has never interleaved.
+          breakdown = if eras.size > 1
+                        (1...eras.last[:ordinal]).map do |ordinal|
+                          { ordinal: ordinal, diverged: lineage.diverged_count(ordinal) }
+                        end
+                      else
+                        []
+                      end
+          { checked: true, era_count: eras.size, breakdown: breakdown, diverged_total: breakdown.sum { |b| b[:diverged] } }
+        ensure
+          db.close
+        end
+      rescue StandardError => e
+        unchecked("#{e.class}: #{e.message}")
+      end
+
+      def unchecked(reason) = { checked: false, reason: reason }
+
+      # THE SAME LOAD `bin/merge_tail` ITSELF PERFORMS (that script's own
+      # top half) — a fresh `Registry`, never the ledger's own (this asks
+      # about the SWEPT TARGET's lineage, not QualityControl's own).
+      def load_registry(domain_path)
+        loading = Hecks::Ports::Loading.bootstrap
+        directory = loading.bluebook_directory(domain_path)
+        registry = Hecks::Runtime::Registry.new(root: File.dirname(directory))
+        Hecks.with_registry(registry) do
+          loading.load_library
+          loading.load_project(loading.shared_root(nil, directory))
+          loading.load_domain(directory)
+        end
+        [registry, directory]
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/form_census.rb

@@ -0,0 +1,184 @@
+require "json"
+
+module Hecks
+  module Fuzzing
+    # WHAT AN AGGREGATE CAN EXHIBIT, AND WHICH PAIRS IT PUTS TOGETHER.
+    #
+    # Extracted from `spec/combination_coverage_spec.rb`'s own pairwise
+    # table so it has exactly two consumers that can never drift: that
+    # spec (the golden corpus, held to every pair) and `bin/qa_domain_
+    # novelty` (a CANDIDATE stress domain, measured against every path
+    # the QA ledger already sweeps — see that script's own header for why
+    # a new domain has to name the pair no existing target meets before
+    # it earns a place in the rotation).
+    #
+    # THE UNIT IS ONE AGGREGATE. Two forms in the same chapter but
+    # different heads never meet at dispatch; two forms on one head do
+    # — that spec's own header has the four defects that argument came
+    # from. Each entry below is a form the language declares and a
+    # runtime has to handle, chosen because it has produced a defect or
+    # sits one step from one; adding one here is how a new form joins
+    # BOTH gates at once, and it will name its own uncovered pairs on the
+    # first run of each.
+    #
+    # ONE FLAT TABLE, ON PURPOSE — each entry is an independent boolean
+    # check against the same string-keyed aggregate IR hash (the shape
+    # `spec/golden/ir/*.json` carries and `Projector::Exporter.call`
+    # round-trips to through JSON), laid out so every declared form can
+    # be read, and added to, at a glance.
+    module FormCensus
+      # A `given`'s own lookup path crossing at least two references —
+      # `member.sponsor.standing`, `source.customer.status`: the
+      # `CommandRules::References#dereference` recursion, walked only
+      # on a fresh command argument (S12, ADR 0025) and hydrated one
+      # repository lookup per hop.
+      TWO_HOP_GIVEN_PATH_LENGTH = 3
+
+      FORMS = {
+        "composite_id"       => ->(a) { (a["identified_by"] || []).size >= 2 },
+        "has_entity"         => ->(a) { entities(a).any? },
+        "two_entities"       => ->(a) { entities(a).size >= 2 },
+        "composite_piece"    => ->(a) { entities(a).any? { |piece| (piece["identified_by"] || []).size >= 2 } },
+        "multi_emit"         => ->(a) { commands(a).any? { |verb| (verb["emits"] || []).size >= 2 } },
+        "lifecycle"          => ->(a) { !a["lifecycle"].nil? },
+        "piece_lifecycle"    => ->(a) { entities(a).any? { |piece| !piece["lifecycle"].nil? } },
+        "has_query"          => ->(a) { queries(a).any? },
+        "list_attr"          => ->(a) { attributes(a).any? { |held| held["list"] } },
+        "reference_attr"     => ->(a) { attributes(a).any? { |held| reference?(held) } },
+        "closed_set"         => ->(a) { (a["value_objects"] || []).any? { |shape| shape["closed_set"] } },
+        "has_default"        => ->(a) { attributes(a).any? { |held| !held["default"].nil? } },
+        "has_optional"       => ->(a) { commands(a).any? { |verb| (verb["attributes"] || []).any? { |held| held["optional"] } } },
+        # THE REFERENCE-HOP FAMILY (ANGLE-2, qa/bluebook ledger) — the
+        # forms `qa/stress_domains/referral_chain` exists for, absent
+        # from the census until that domain named them. Each is one
+        # step from a catalogued gap: `two_hop_given` is `dereference`'s
+        # own recursion (`DEREFERENCE_DEPTH`); `multi_hop_where` is a
+        # `/`-chain `HopPath` walks for real and `rust/project/queries.
+        # rb` structurally refuses (D2 of the equivalence-gap plan);
+        # `revalued_reference` is ADR 0037 Finding 5's exact trigger — a
+        # command redeclaring the aggregate's own reference field under
+        # a non-reference type, so only `resolve_state_references` (never
+        # ported) can catch a dangling id.
+        "two_hop_given"      => ->(a) { two_hop_given?(a) },
+        "multi_hop_where"    => ->(a) { multi_hop_where?(a) },
+        "revalued_reference" => ->(a) { revalued_reference?(a) }
+      }.freeze
+
+      module_function
+
+      def entities(aggregate)   = aggregate["entities"] || []
+      def commands(aggregate)   = aggregate["commands"] || []
+      def attributes(aggregate) = aggregate["attributes"] || []
+      def queries(aggregate)    = aggregate["queries"] || []
+      def reference?(attribute) = attribute["type"].to_s.start_with?("Reference<")
+
+      def two_hop_given?(aggregate)
+        commands(aggregate).any? { |verb| (verb["givens"] || []).any? { |given| deep_lookup?(given["ast"]) } }
+      end
+
+      # A `where` whose field crosses two `/` — `member/sponsor/standing`.
+      def multi_hop_where?(aggregate)
+        queries(aggregate).any? { |query| (query["wheres"] || []).any? { |where| where["field"].to_s.count("/") >= 2 } }
+      end
+
+      # A command attribute sharing a name with one of the aggregate's
+      # own reference-typed attributes while carrying a DIFFERENT, non-
+      # reference type — `attribute :member, Handle` against
+      # `reference_to Member`.
+      def revalued_reference?(aggregate)
+        references = attributes(aggregate).select { |held| reference?(held) }.to_set { |held| held["name"].to_s }
+        commands(aggregate).any? do |verb|
+          (verb["attributes"] || []).any? { |held| references.include?(held["name"].to_s) && !reference?(held) }
+        end
+      end
+
+      # Walks a given's own exported AST for any `lookup` whose path is
+      # long enough to have crossed two references.
+      def deep_lookup?(node)
+        case node
+        when Hash
+          return true if node["op"] == "lookup" && Array(node["path"]).size >= TWO_HOP_GIVEN_PATH_LENGTH
+
+          node.each_value.any? { |child| deep_lookup?(child) }
+        when Array
+          node.any? { |child| deep_lookup?(child) }
+        else
+          false
+        end
+      end
+
+      # Every form, answered for one aggregate — the table above, applied.
+      def properties(aggregate)
+        FORMS.transform_values { |form| form.call(aggregate) }
+      end
+
+      # Every unordered pair of forms, each rendered "left + right" in
+      # alphabetical order — the key both gates' excuse tables use.
+      def pairs
+        FORMS.keys.combination(2).map { |pair| pair_key(*pair) }
+      end
+
+      def pair_key(left, right) = [left, right].sort.join(" + ")
+
+      # `held` is `[[aggregate_name, properties], ...]`. Answers which
+      # pairs are met on ONE aggregate, and by which — a Hash from pair
+      # key to the names carrying it, so a caller can say who.
+      def covered_pairs(held)
+        held.each_with_object(Hash.new { |h, k| h[k] = [] }) do |(name, shows), covered|
+          shows.select { |_, present| present }.keys.combination(2).each do |left, right|
+            covered[pair_key(left, right)] << name
+          end
+        end
+      end
+
+      # `[[\"Chapter::Aggregate\", properties], ...]` for every aggregate
+      # a string-keyed chapter IR declares — the same walk the golden
+      # spec makes over `spec/golden/ir/*.json`.
+      def aggregates_in(chapter_ir)
+        (chapter_ir["aggregates"] || []).map do |aggregate|
+          ["#{chapter_ir['name']}::#{aggregate['name']}", properties(aggregate)]
+        end
+      end
+
+      # WHERE A DOMAIN PATH KEEPS ITS BLUEBOOKS — `<domain>/bluebook/*.
+      # bluebook` (every example and stress domain), or the directory
+      # itself (`qa/bluebook`, the ledger's own `Target.path`): the same
+      # two shapes `bin/model_check`'s `bluebook_in` reads. `nil` when
+      # neither holds a bluebook.
+      def bluebook_files(domain_path)
+        [File.join(domain_path, "bluebook"), domain_path].each do |dir|
+          files = Dir[File.join(dir, "*.bluebook")]
+          return files unless files.empty?
+        end
+        nil
+      end
+
+      # THE SAME CENSUS OVER A DOMAIN ON DISK, booted the lightweight
+      # way `bin/model_check` and `Hecks::Codemod.load_bluebook` already
+      # do (ports and the two in-process adapters, no `Hecks.boot`, no
+      # live database, no `.hecksagon`: the census reads declared SHAPE,
+      # and a framework chapter a `.hecksagon` would attach is not this
+      # domain's own). Only the domain's own chapter is measured — the
+      # first bluebook loaded, the same "target chapter is always first"
+      # fact `bin/project_rust` relies on.
+      def census(domain_path)
+        root = File.expand_path("../../..", __dir__)
+        files = bluebook_files(domain_path)
+        raise ArgumentError, "#{domain_path} has no bluebook/*.bluebook (or *.bluebook) to measure" if files.nil?
+
+        registry = Hecks::Runtime::Registry.new(root: File.expand_path(domain_path))
+        Hecks.with_registry(registry) do
+          Kernel.load(File.join(root, "lib/hecks/ports/persistence.port"))
+          Kernel.load(File.join(root, "lib/hecks/ports/extraction.port"))
+          Kernel.load(File.join(root, "lib/hecks/adapters/driven/memory.adapter"))
+          Kernel.load(File.join(root, "lib/hecks/adapters/driven/prism.adapter"))
+          files.each { |file| Kernel.load(file) }
+        end
+
+        chapter_name = registry.bluebooks.keys.first
+        exported = JSON.parse(JSON.generate(Hecks::Projector::Exporter.call(registry).fetch(chapter_name)))
+        aggregates_in(exported)
+      end
+    end
+  end
+end