hecks 1.3.0 → 1.5.0

data/lib/hecks/fuzzing/invalid_value_generator.rb

@@ -1,6 +1,6 @@
 module Hecks
   module Fuzzing
-    # A value that is DELIBERATELY THE WRONG SHAPE for the attribute it is handed
+    # A value that is deliberately the wrong shape for the attribute it is handed
     # to — the sibling of ValueGenerator, which only ever builds values that satisfy
     # a declared type.
     #
@@ -14,7 +14,7 @@ module Hecks
     # Rendering's whole story), and no generated value
     # could ever have produced it.
     #
-    # These are expected to be REFUSED, and that is the point : a refusal is an
+    # These are expected to be refused, and that is the point : a refusal is an
     # answer, and its wording is pinned byte-for-byte. The bugs live in
     # the sentence, not in the happy path.
     module InvalidValueGenerator
@@ -32,15 +32,32 @@ module Hecks
         null
       ].freeze
 
+      # Builds one value of the wrong shape for `attribute`, chosen from the
+      # confusions that are actually meaningful for its declared type.
+      #
+      # @param attribute [Bluebook::Attribute] the attribute the corrupted value is
+      #   handed to
+      # @param aggregate [Bluebook::Aggregate] the aggregate that declares
+      #   `attribute` (and any value objects it references)
+      # @param random [Random] the seeded RNG to draw the kind and value from
+      # @return [Object] a value of the wrong shape for `attribute` — an Integer,
+      #   Float, String, Array, Hash, or boolean, depending on the kind drawn
       def corrupt(attribute, aggregate, random:)
         kind = kinds_for(attribute, aggregate).sample(random: random)
         build(kind, attribute, aggregate, random: random)
       end
 
-      # Only the confusions that MEAN anything for this attribute. Offering
+      # Only the confusions that mean anything for this attribute. Offering
       # `scalar_for_object` for a plain Integer would just be a second spelling of
       # `numeral_string`, and a kind that cannot be wrong for the attribute it is
       # handed teaches the corpus nothing.
+      #
+      # @param attribute [Bluebook::Attribute] the attribute to find applicable
+      #   confusions for
+      # @param aggregate [Bluebook::Aggregate] the aggregate that declares
+      #   `attribute` (and any value objects it references)
+      # @return [Array<Symbol>] the subset of `KINDS` that are a real confusion for
+      #   `attribute`'s declared type
       def kinds_for(attribute, aggregate)
         value_object = aggregate.value_object(attribute.type.to_s)
         return %i[scalar_for_object array_for_scalar null] if value_object
@@ -49,6 +66,16 @@ module Hecks
         %i[object_for_scalar array_for_scalar boolean_for_string null]
       end
 
+      # Builds the actual corrupted value for one already-chosen `kind`.
+      #
+      # @param kind [Symbol] one of `KINDS`
+      # @param attribute [Bluebook::Attribute] the attribute the value will be
+      #   handed to
+      # @param aggregate [Bluebook::Aggregate] the aggregate that declares
+      #   `attribute` (and any value objects it references)
+      # @param random [Random] the seeded RNG to draw the value from
+      # @return [Object, nil] the corrupted value for `kind`; `nil` if `kind` is not
+      #   one `KINDS` declares
       def build(kind, attribute, aggregate, random:)
         case kind
         when :object_for_scalar then { "cents" => random.rand(1..1000) }
@@ -60,16 +87,25 @@ module Hecks
         end
       end
 
-      # A bare scalar where a value object is declared. A SINGLE-FIELD value object
+      # A bare scalar where a value object is declared. A single-field value object
       # legitimately accepts one (that is the standing-in rule every domain relies
-      # on), so the interesting case is a value object with SEVERAL fields, where a
+      # on), so the interesting case is a value object with several fields, where a
       # scalar cannot stand for anything and the refusal has to say so.
+      # @param attribute [Bluebook::Attribute] the value-object-typed attribute to
+      #   build a bare scalar for
+      # @param aggregate [Bluebook::Aggregate] the aggregate that declares
+      #   `attribute`'s value object
+      # @param random [Random] accepted for a uniform call signature with `#build`;
+      #   this method draws nothing from it
+      # @return [String, Hash] `"a bare scalar"` when a scalar would legitimately be
+      #   accepted (a single-field value object); otherwise a Hash corrupting the
+      #   sole field's own type instead
       def scalar_for(attribute, aggregate, random:)
         value_object = aggregate.value_object(attribute.type.to_s)
         sole = value_object&.sole_attribute
         return "a bare scalar" unless sole
 
-        # One field, so a scalar is legal — corrupt the FIELD's own type instead,
+        # One field, so a scalar is legal — corrupt the field's own type instead,
         # which is still a shape the attribute cannot accept.
         { sole.name.to_s => ["nested", "array"] }
       end
@@ -77,6 +113,9 @@ module Hecks
       # An attribute the command never declared. `refuse_unknown_arguments` is a
       # real dispatch step (Vocabulary::AggregateDispatchOrder), and nothing
       # generated had ever exercised it.
+      # @param random [Random] the seeded RNG to draw the name and value from
+      # @return [Array(String, String)] a `[name, value]` pair naming an argument
+      #   no command declares
       def undeclared_argument(random:)
         name = %w[colour flavour rank note].sample(random: random)
         [name, %w[red loud third scribbled].sample(random: random)]

data/lib/hecks/fuzzing/isolated_boot.rb

@@ -4,37 +4,41 @@ require "securerandom"
 
 module Hecks
   module Fuzzing
-    # A FRESH, IN-PROCESS ADAPTER FOR EVERY EPHEMERAL BOOT.
+    # A fresh, in-process adapter for every ephemeral boot.
+    #
+    # ## Why rebind at all
     #
     # 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
-    # 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,
-    # persisted, SQL-backed one — and `spec/adapters/query_agreement_spec
-    # .rb` already found 4 shipped query bugs from exactly that
-    # comparison, on a fixed corpus far smaller than what the fuzzer
-    # generates. `:sqlite` rewrites to `"SqlitePersistence"` — the name
+    # ## `adapter:` modes
+    #
+    # `adapter:` (PRD 02) picks which real persistence one ephemeral boot
+    # answers through. `:memory` is the default and the only mode every
+    # caller that passes no `adapter:` still gets. `:sqlite` rebinds to
+    # the real SQLite adapter instead of the in-memory one: 15 declared
+    # properties (properties.rb) and every fuzz/replay run only ever
+    # exercised Memory's own hand-written repository until this mode
+    # existed, and `spec/adapters/query_agreement_spec.rb` already found 4
+    # shipped query bugs from exactly that comparison, on a fixed corpus
+    # far smaller than what the fuzzer generates. `:sqlite` rewrites to
+    # `"SqlitePersistence"` — the name
     # `lib/hecks/adapters/driven/sqlite.adapter` actually registers under
     # (`Sqlite` is the class; `SqlitePersistence` is a thin subclass
     # that's the one real port binding names) — and needs no `.world`
@@ -44,25 +48,23 @@ 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. 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
+    # file instead of a Hash. `:postgres` (PRD 02, docs/prds/02-fuzzer-
+    # real-adapters.md) and `:postgres_era` (`rebind_to_postgres_era!`'s
+    # own header, below) are the two real-Postgres modes. 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: `: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
@@ -75,7 +77,7 @@ 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.
-      # `database:`/`schema:` are ONLY meaningful for `adapter: :postgres_era`
+      # `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;
@@ -83,6 +85,20 @@ module Hecks
       # signature per adapter) keeps `SequenceGenerator`/`Replay`'s own
       # single passthrough (`adapter:`, now joined by these two) uniform
       # across all four modes.
+      #
+      # @param domain_path [String] path to the real domain directory to copy and isolate
+      # @param adapter [Symbol] which persistence the copy answers through: `:memory`
+      #   (default), `:sqlite`, `:postgres`, or `:postgres_era`
+      # @param database [String, nil] the database name, required only for
+      #   `adapter: :postgres_era`; ignored by every other adapter
+      # @param schema [String, nil] the schema name, required only for
+      #   `adapter: :postgres_era`; ignored by every other adapter
+      # @yield [String] the freshly rebound copy's root directory, ready to boot
+      # @yieldreturn [Object] anything; becomes this method's own return value
+      # @return [Object] whatever the given block returns
+      # @raise [ArgumentError] if `adapter` is not `:memory`, `:sqlite`, `:postgres`, or
+      #   `:postgres_era`, or if `adapter: :postgres_era` is given without both
+      #   `database:` and `schema:`
       def call(domain_path, adapter: :memory, database: nil, schema: nil)
         Dir.mktmpdir("hecks-fuzz") do |tmp|
           copy = File.join(tmp, File.basename(domain_path))
@@ -100,8 +116,8 @@ module Hecks
         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
@@ -109,10 +125,14 @@ 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.
+      #
+      # @param source [String] the real domain directory to copy
+      # @param destination [String] the tmpdir path to copy it into; created if missing
+      # @return [void]
       def copy_dereferencing(source, destination)
         FileUtils.mkdir_p(destination)
         Dir.glob(File.join(source, "**", "*"), File::FNM_DOTMATCH).each do |path|
@@ -136,12 +156,17 @@ module Hecks
         end
       end
 
+      # Rewrites every `.hecksagon` in the copy to bind through Memory and drops its
+      # `.world` files, so the boot needs no settings at all.
+      #
+      # @param copy [String] the isolated copy's root directory
+      # @return [void]
       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
@@ -154,7 +179,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
@@ -162,30 +187,33 @@ module Hecks
       # needed" property Memory has. `data/` itself is left for Sqlite to
       # recreate on first write, same as it always was for Memory/Heki —
       # nothing here creates it up front.
+      #
+      # @param copy [String] the isolated copy's root directory
+      # @return [void]
       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,
@@ -193,17 +221,22 @@ module Hecks
       FUZZ_POSTGRES_DATABASE = "hecks_fuzz".freeze
       FUZZ_POSTGRES_SCHEMA   = "hecks_fuzz".freeze
 
+      # Rewrites every `.hecksagon` in the copy to bind through Postgres, against the
+      # shared `FUZZ_POSTGRES_DATABASE`/`FUZZ_POSTGRES_SCHEMA` scratch schema.
+      #
+      # @param copy [String] the isolated copy's root directory
+      # @return [void]
       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
@@ -225,7 +258,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
@@ -236,20 +269,22 @@ 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.
+      #
+      # @return [void]
       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
@@ -261,7 +296,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.
@@ -278,7 +313,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
@@ -292,11 +327,11 @@ module Hecks
         db.close
       end
 
-      # THE ADAPTER `:postgres` NEVER TOUCHES — `Postgres` and `PostgresEra`
-      # are SIBLING, NOT interchangeable, adapters (see postgres_era.rb's
+      # 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
+      # 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-
@@ -305,23 +340,29 @@ module Hecks
       # `: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.
+      # 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
+      # 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
+      # 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
+      # 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
+      # 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.
+      #
+      # @param copy [String] the isolated copy's root directory
+      # @param database [String] the caller-owned throwaway database name
+      # @param schema [String] the caller-owned throwaway schema name
+      # @return [void]
+      # @raise [ArgumentError] if `database` or `schema` is empty
       def rebind_to_postgres_era!(copy, database:, schema:)
         require "pg"
         if database.to_s.empty? || schema.to_s.empty?
@@ -334,25 +375,25 @@ module Hecks
         rewrite_bindings!(copy, "PostgresEra")
         ensure_postgres_era_schema!(database: database, schema: schema)
 
-        # SAME ONE-`.world`-PER-`.hecksagon`-DIRECTORY SHAPE `rebind_to_
+        # 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
+        # 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
+        # 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
+        # `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
+        # 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,
@@ -386,20 +427,25 @@ module Hecks
         end
       end
 
-      # THE ZERO-HISTORY GUARANTEE FOR THIS MODE — `DROP SCHEMA ... CASCADE`
+      # 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
+      # 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
+      # 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
+      # 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.
+      #
+      # @param database [String] the caller-owned database name, created if it does not
+      #   already exist
+      # @param schema [String] the caller-owned schema name, dropped and recreated
+      # @return [void]
       def ensure_postgres_era_schema!(database:, schema:)
         GC.start
 
@@ -417,7 +463,7 @@ module Hecks
         db.close
       end
 
-      # THE SHARED REWRITE — factored out of `rebind_to_memory!` when
+      # 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
@@ -431,46 +477,57 @@ 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
+      # 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
+      # .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
+      # 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
+      # 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
+      # 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
+      # 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
+      # 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
+      # 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 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
+      # `:postgres_era` itself, where the bound adapter genuinely is
       # lineage-capable and the edge causes no refusal to begin with.
+      #
+      # @param copy [String] the isolated copy's root directory
+      # @return [void]
       def strip_translations!(copy)
         Dir.glob(File.join(copy, "**", "translations", "*.bluebook")).each { |path| File.delete(path) }
       end
 
+      # Rewrites every `persisted_by` bind — aggregate-scoped or bare at the
+      # hecksagon's own root — in the copy's `.hecksagon` files to name `adapter_name`,
+      # and drops every `projected_by` bind outright.
+      #
+      # @param copy [String] the isolated copy's root directory
+      # @param adapter_name [String] the port binding name to rewrite every
+      #   `persisted_by` to, such as `"Memory"` or `"SqlitePersistence"`
+      # @return [void]
       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*"/)