hecks 1.3.0 → 1.5.0

data/lib/hecks/bluebook/meta_validator/syntax_boot.rb

@@ -1,35 +1,42 @@
+require "digest"
+require "fileutils"
+
 module Hecks
   module Bluebook
     module MetaValidator
-      # S14, ADR 0026 — DISPATCHES THE LANGUAGE'S OWN GRAMMAR TABLE INTO
-      # ITSELF, once, so `Keyword`/`Argument`'s own `status` genuinely IS a
+      # S14, ADR 0026 — dispatches the language's own grammar table into
+      # itself, once, so `Keyword`/`Argument`'s own `status` genuinely is a
       # lifecycle — checked at real dispatch time (the same admission/
       # coercion/lifecycle-guard door every other command goes through),
       # not merely declared and never exercised.
       #
-      # THE SOURCE STAYS STATIC. Aggregate-local `KeywordSeed`/
-      # `ArgumentSeed` value objects (still hand-written `member` rows —
-      # now beside the concepts they spell) are what gets WRITTEN ; this
-      # is what turns them into what gets READ. `Judge`/`Reconstruction`
-      # already draw exactly this line everywhere else in the meta-domain
-      # (a chapter's own DECLARATIONS versus what gets DISPATCHED from
-      # them) — this runs the same distinction one level further out, for
-      # the language's own grammar table.
+      # ## The source stays static
+      #
+      # Aggregate-local `KeywordSeed`/`ArgumentSeed` value objects (still
+      # hand-written `member` rows — now beside the concepts they spell)
+      # are what gets written ; this is what turns them into what gets
+      # read. `Judge`/`Reconstruction` already draw exactly this line
+      # everywhere else in the meta-domain (a chapter's own declarations
+      # versus what gets dispatched from them) — this runs the same
+      # distinction one level further out, for the language's own grammar
+      # table.
+      #
+      # ## A dedicated runtime
       #
-      # A DEDICATED RUNTIME, not `MetaValidator.fresh_runtime`. That one
-      # is reserved for `Judge`'s own bootstrap (dispatching a CHAPTER's
-      # declarations INTO the meta-domain's grammar) — a different act
-      # from this one (dispatching the meta-domain's OWN grammar table
-      # data into a live "Bluebook" domain instance). Sharing the runtime
-      # would let one boot's own repository state leak into the other's.
+      # Not `MetaValidator.fresh_runtime`. That one is reserved for
+      # `Judge`'s own bootstrap (dispatching a chapter's declarations into
+      # the meta-domain's grammar) — a different act from this one
+      # (dispatching the meta-domain's own grammar table data into a live
+      # "Bluebook" domain instance). Sharing the runtime would let one
+      # boot's own repository state leak into the other's.
       #
-      # Usage:
+      # ## Usage
       #
       #   MetaValidator.syntax_table  # => { keywords: [...], arguments: [...] }
       #
       # each row a plain Hash, string values, `status` included — the
       # exact shape `ParserTable`/`syntax_conformance_spec` already read
-      # off the OLD closed-set members, so neither consumer had to change
+      # off the old closed-set members, so neither consumer had to change
       # what it does with a row, only where the row comes from.
       module SyntaxBoot
         module_function
@@ -40,21 +47,21 @@ module Hecks
         # conformance_spec, bin/reference) should each pay for on every
         # call.
         #
-        # KEYED BY THE GRAMMAR REGISTRY'S OWN CHAPTER SET, not by a
+        # Keyed by the grammar registry's own chapter set, not by a
         # "ready" flag. `boot` reads exactly two things: the registry's
         # "Bluebook" chapter (the core seed rows) and every chapter in the
         # registry that `attaches_to` a core context (Paging's rows). So
-        # the table is a pure function of which chapter OBJECTS the
+        # the table is a pure function of which chapter objects the
         # registry holds — and that is the cache key: the same chapters,
         # by identity, mean the same table; a chapter replaced (the
         # fixpoint judge swapping a raw chapter for its assembled self)
         # or added (`load_attached_grammar_into`) means a fresh boot.
         #
-        # WHY NOT THE EARLIER `grammar_registry_ready?` GUARD. That guard
+        # Why not the earlier `grammar_registry_ready?` guard. That guard
         # was right about the hazard — a snapshot taken mid-build, before
         # Paging attached, would be missing limit/offset/cursor/nulls
         # forever — and wrong about the cost of its cure. It refused to
-        # cache ANYTHING until the whole grammar registry had finished
+        # cache anything until the whole grammar registry had finished
         # building, calling that window "narrow" and recomputing in it
         # "cheap". Measured (hecks_ai_training, a six-entity chess domain,
         # 2026-08-22): every `word_gate_dispatch` landing in that window
@@ -69,20 +76,37 @@ module Hecks
         # chapter objects, so it invalidates this the same way it always
         # invalidated `grammar_registry_ready?`.
         #
-        # `equal?`, NOT `==`, on the chapters — identity is the fact being
+        # `equal?`, not `==`, on the chapters — identity is the fact being
         # tracked. Holding the chapter objects themselves (not their ids)
         # in the key also means a collected chapter can never hand its id
         # to a newcomer behind this cache's back.
+        # @return [Hash{Symbol => Array<Hash{Symbol => String}>}] `:keywords`
+        #   and `:arguments`, each an array of plain, string-valued row
+        #   hashes (`status` included)
         def call
           chapters = MetaValidator.grammar_registry.bluebooks.to_a
           return @call if @call && same_chapters?(@call_chapters, chapters)
 
-          result = boot
+          result = read_disk_cache(chapters) || begin
+            fresh = boot
+            write_disk_cache(chapters, fresh)
+            fresh
+          end
+
           @call = result
           @call_chapters = chapters
           result
         end
 
+        # Compares the in-process cache key against the registry's current
+        # chapters.
+        #
+        # @param cached [Array<Array(String, Object)>] the `[name, chapter]`
+        #   pairs `call` last cached against
+        # @param current [Array<Array(String, Object)>] the registry's
+        #   current `[name, chapter]` pairs
+        # @return [Boolean] whether `cached` and `current` name the same
+        #   chapters, by identity, in the same order
         def same_chapters?(cached, current)
           cached.size == current.size &&
             cached.zip(current).all? do |(cached_name, cached_chapter), (name, chapter)|
@@ -90,14 +114,155 @@ module Hecks
             end
         end
 
+        # Cross-process persistence for the same ~1s-per-build work `call`
+        # above already memoizes in-process — this file's own chapter-
+        # identity keying only ever helps callers sharing one process (the
+        # in-memory fixpoint window, or `bin/reference`'s single run); every
+        # fresh process (a `qa_sweep --all` child, a `parallel_rspec`
+        # worker, `bin/qa_sweep` itself) pays both real builds again from
+        # scratch even when the grammar source hasn't changed at all since
+        # the last process that built it.
+        #
+        # Not a fix for the two-builds-per-process shape — investigated and
+        # confirmed genuine, not waste (see this module's own header
+        # history: the previous "wait for the whole registry" design cost
+        # 42 rebuilds/32s per process precisely because real callers need a
+        # correct table mid-bootstrap, before Paging attaches). Both builds
+        # still happen once each per process; this only makes each of them
+        # a cheap disk read instead of a real ~1s dispatch, once some
+        # earlier process has already paid for that exact chapter-set +
+        # grammar-content combination.
+        #
+        # Keyed the same way `same_chapters?` is, translated across process
+        # boundaries — chapter *object identity* (what the in-memory cache
+        # keys on) means nothing to a different process; chapter *names*,
+        # in the same order, do. Combined with a content hash of every
+        # grammar file `boot` can read from (`seed_chapters` walks every
+        # bluebook the registry holds, so this must cover the core chapters
+        # and every attached one, not just "Bluebook" + "Paging") — a
+        # source edit anywhere in that set correctly misses the old cache
+        # entry rather than silently serving a stale table.
+        #
+        # Fails toward a real boot, never toward a wrong table — same
+        # loud-not-silent discipline this codebase already holds CI to
+        # (`postgres_io_relevant_changed`'s own header). A missing file, a
+        # corrupt Marshal blob, a permission error, an unwritable `tmp/` —
+        # every one of these degrades to "no disk cache today", never to a
+        # crash or a served-but-wrong table. `tmp/` is already gitignored
+        # for exactly this kind of local, disposable-but-useful-while-it-
+        # lasts artifact (`Storehouse::LOG_ROOT`'s own header names the
+        # same convention).
+        #
+        # **Atomic write, not a lock** — `qa_sweep --all` spawns up to 4
+        # children at once, any of which could reach a cold cache
+        # simultaneously and each compute the identical real boot result
+        # for the identical key. Writing to a PID-suffixed temp file and
+        # `File.rename`ing it into place (a single atomic syscall on the
+        # same filesystem) means a concurrent second writer's rename just
+        # overwrites the first with byte-identical content — never a torn
+        # or partially-written file a concurrent reader could observe.
+        #
+        # `HECKS_SYNTAX_BOOT_CACHE=off` — an escape hatch needing no code
+        # change, the same shape `Storehouse::BOOT_ROOT`'s own
+        # `HECKS_STOREHOUSE_ROOT` override uses, for the day this needs to
+        # be ruled out while debugging something else entirely.
+        CACHE_DIR = File.expand_path("../../../../tmp/hecks_syntax_boot_cache", __dir__).freeze
+
+        # Reports whether the cross-process disk cache is turned on.
+        #
+        # @return [Boolean] whether the cross-process disk cache is turned
+        #   on (`HECKS_SYNTAX_BOOT_CACHE=off` turns it off)
+        def disk_cache_enabled? = ENV["HECKS_SYNTAX_BOOT_CACHE"] != "off"
+
+        # Reads an already-written cache entry for `chapters`, if any.
+        #
+        # @param chapters [Array<Array(String, Object)>] the `[name,
+        #   chapter]` pairs to key the cache entry on
+        # @return [Hash{Symbol => Array<Hash{Symbol => String}>}, nil] the
+        #   cached syntax table, or `nil` if the cache is disabled, no entry
+        #   exists yet, or the entry could not be read
+        def read_disk_cache(chapters)
+          return nil unless disk_cache_enabled?
+
+          path = disk_cache_path(chapters)
+          return nil unless File.exist?(path)
+
+          Marshal.load(File.binread(path)) # rubocop:disable Security/MarshalLoad -- own process-local cache, never external input
+        rescue StandardError
+          nil
+        end
+
+        # Writes `result` to the disk cache for `chapters`, atomically.
+        #
+        # @param chapters [Array<Array(String, Object)>] the `[name,
+        #   chapter]` pairs to key the cache entry on
+        # @param result [Hash{Symbol => Array<Hash{Symbol => String}>}] the
+        #   syntax table to persist
+        # @return [void]
+        def write_disk_cache(chapters, result)
+          return unless disk_cache_enabled?
+
+          path = disk_cache_path(chapters)
+          FileUtils.mkdir_p(CACHE_DIR)
+          tmp_path = "#{path}.#{Process.pid}.tmp"
+          File.binwrite(tmp_path, Marshal.dump(result))
+          File.rename(tmp_path, path)
+        rescue StandardError
+          nil
+        end
+
+        # Builds the disk cache file path for `chapters`.
+        #
+        # @param chapters [Array<Array(String, Object)>] the `[name,
+        #   chapter]` pairs to key the cache entry on
+        # @return [String] the disk cache file path for `chapters`
+        def disk_cache_path(chapters)
+          File.join(CACHE_DIR, "#{disk_cache_key(chapters)}.marshal")
+        end
+
+        # Builds the cache key for `chapters`.
+        #
+        # @param chapters [Array<Array(String, Object)>] the `[name,
+        #   chapter]` pairs to key the cache entry on
+        # @return [String] a SHA-256 digest of the chapter names and the
+        #   current grammar source
+        def disk_cache_key(chapters)
+          names = chapters.map { |name, _chapter| name }
+          Digest::SHA256.hexdigest("#{names.join(',')}:#{grammar_content_digest}")
+        end
+
+        # Every file `boot` can possibly read from, via `seed_chapters`
+        # walking every bluebook the registry holds — not just "Bluebook"
+        # and "Paging" (the two chapters this module's own comments name
+        # most often), because World/Hecksagon/any future attached chapter
+        # are equally eligible to carry their own `KeywordSeed`/
+        # `ArgumentSeed` value object. Coarser than strictly necessary (any
+        # one file changing invalidates every cached key, not just the
+        # chapter it belongs to) — deliberately, since under-covering this
+        # set is a correctness bug (a stale table survives a real grammar
+        # edit) and over-covering it is only ever a wasted cache miss.
+        # @return [String] a SHA-256 digest of every grammar file's own
+        #   current content, sorted for a stable digest
+        def grammar_content_digest
+          files = (MetaValidator::GRAMMAR_FILES + MetaValidator::WORLD_GRAMMAR + MetaValidator::HECKSAGON_GRAMMAR +
+                    Dir.glob(File.join(MetaValidator::ATTACHED_GRAMMAR_DIR, "*.bluebook"))).sort
+          Digest::SHA256.hexdigest(files.map { |file| File.read(file) }.join("\0"))
+        end
+
+        # Dispatches every seed row into a fresh "Bluebook" instance and
+        # reads the result back.
+        #
+        # @return [Hash{Symbol => Array<Hash{Symbol => String}>}] `:keywords`
+        #   and `:arguments`, each an array of plain, string-valued row
+        #   hashes (`status` included)
         def boot
           bluebook = MetaValidator.grammar_registry.bluebook("Bluebook")
           # `MetaValidator.fresh_runtime`, not a brand-new `Runtime::
           # Registry` — the grammar registry's own copy already has
           # "Bluebook" registered (`grammar_registry`'s own boot already
-          # ran `registry.add_bluebook`) AND its adapter ports already
+          # ran `registry.add_bluebook`) and its adapter ports already
           # loaded ; a standalone registry would need both wired by hand.
-          # `fresh_runtime` resets `@repositories` on the SAME registry —
+          # `fresh_runtime` resets `@repositories` on the same registry —
           # the identical isolation `Judge.new` already relies on for
           # every real domain it judges, proven safe by every dispatch
           # this session has ever made.
@@ -110,28 +275,42 @@ module Hecks
           read_back(runtime, bluebook)
         end
 
+        # Wraps `text` as a single-field value-object payload, for a
+        # dispatch's own `with:`.
+        #
         # An Integer stays an Integer — `position` is `Position`-typed
         # (`attribute :value, Integer`), so stringifying it fails the type
         # gate rather than feeding it, the same reading `Judge#v` gives.
+        #
+        # @param text [String, Integer] the scalar to wrap
+        # @return [Hash{Symbol => String, Integer}] `{value: text}`,
+        #   stringified unless `text` is already an Integer
         def v(text)
           return { value: text } if text.is_a?(Integer)
 
           { value: text.to_s }
         end
 
-        # ABSENT STAYS ABSENT. A seed row's own optional columns ("was",
+        # Wraps `text` as an `optional: true` command argument's own
+        # payload, or omits it.
+        #
+        # Absent stays absent. A seed row's own optional columns ("was",
         # "at", "named", ...) are empty strings, not nil — `Literal`/CSV-
         # shaped grammar data has no `nil` to write — so this is the one
         # place that decides "" means "not given" for the purpose of an
         # `optional: true` command argument, the same reading `Judge#v`
         # makes for the meta-domain's own dispatches.
+        #
+        # @param text [String, nil] the seed row's own column value
+        # @return [Hash{Symbol => String}, nil] `v(text)`, or `nil` when
+        #   `text` is `nil` or empty
         def optional(text)
           return nil if text.nil? || text.to_s.empty?
 
           v(text)
         end
 
-        # `Syntax.Declare`'s own `reference_to Bluebook` names the CHAPTER
+        # `Syntax.Declare`'s own `reference_to Bluebook` names the chapter
         # it belongs to — the same fact every other top-level aggregate's
         # own creating command carries (`ProcessManager.Declare`,
         # `Policy.Declare`, ...). This fresh runtime holds no chapter
@@ -139,25 +318,39 @@ module Hecks
         # declared first, named after the real chapter, purely to satisfy
         # the reference — its own vision/classification are never read
         # by anything this boot does.
+        #
+        # @param runtime [Runtime::Dispatcher] the fresh runtime to
+        #   dispatch into
+        # @param bluebook [Bluebook::Chapter] the language's own assembled
+        #   "Bluebook" chapter, read for its `hecks_name` and `"Syntax"`
+        #   aggregate
+        # @return [void]
         def declare_syntax(runtime, bluebook)
           syntax = bluebook.aggregate("Syntax")
-          runtime.dispatch("Bluebook::Bluebook.Declare", name:           v(bluebook.hecks_name),
-                                                         vision:         v("the language's own grammar table, " \
-                                                                           "dispatched into itself"),
-                                                         classification: v("core"))
-          runtime.dispatch("Bluebook::Syntax.Declare", bluebook: bluebook.hecks_name, name: v(syntax.hecks_name))
+          runtime.dispatch("Bluebook::Bluebook.Declare",
+                           with: { name:           v(bluebook.hecks_name),
+                                   vision:         v("the language's own grammar table, " \
+                                                     "dispatched into itself"),
+                                   classification: v("core") })
+          runtime.dispatch("Bluebook::Syntax.Declare",
+                           with: { bluebook: bluebook.hecks_name, name: v(syntax.hecks_name) })
         end
 
-        # `to: "Syntax"` NAMES THE RECORD ALREADY OPENED BY `declare_syntax`
-        # ABOVE — an append onto an existing aggregate, not a second creation
-        # of it. This used to smuggle `name: v("Syntax")` into the payload
-        # instead, the pre-routing convention `Judge#appends` (the same
-        # append shape, for `ValueObject.Member`/`ProcessManager.Handler`)
-        # already left behind for `to:`/`with:` — carrying the receiver in
-        # the payload made `Syntax.Keyword`'s own `command.creates?` (true:
-        # it declares no `reference_to`) look like a fresh identity to mint,
-        # which collided with the very "Syntax" row `declare_syntax` had
-        # just opened.
+        # `to: "Syntax"` names the record already opened by `declare_syntax`
+        # above — an append onto an existing aggregate, not a second creation
+        # of it. Smuggling `name: v("Syntax")` into the payload instead — the
+        # pre-routing convention `Judge#appends` (the same append shape, for
+        # `ValueObject.Member`/`ProcessManager.Handler`) already left behind
+        # for `to:`/`with:` — would carry the receiver in the payload,
+        # making `Syntax.Keyword`'s own `command.creates?` (true: it
+        # declares no `reference_to`) look like a fresh identity to mint,
+        # colliding with the very "Syntax" row `declare_syntax` just opened.
+        #
+        # @param runtime [Runtime::Dispatcher] the fresh runtime to
+        #   dispatch into
+        # @param bluebook [Bluebook::Chapter] the language's own assembled
+        #   "Bluebook" chapter, read for its `KeywordSeed` rows
+        # @return [void]
         def admit_keywords(runtime, bluebook)
           all_rows(bluebook, "KeywordSeed").each_with_index do |row, index|
             runtime.dispatch("Bluebook::Syntax.Keyword", to:   "Syntax",
@@ -175,6 +368,14 @@ module Hecks
           end
         end
 
+        # Admits every `ArgumentSeed` row as a `Syntax.Argument`, the same
+        # `to: "Syntax"` append shape `admit_keywords` uses one type over.
+        #
+        # @param runtime [Runtime::Dispatcher] the fresh runtime to
+        #   dispatch into
+        # @param bluebook [Bluebook::Chapter] the language's own assembled
+        #   "Bluebook" chapter, read for its `ArgumentSeed` rows
+        # @return [void]
         def admit_arguments(runtime, bluebook)
           all_rows(bluebook, "ArgumentSeed").each_with_index do |row, index|
             runtime.dispatch("Bluebook::Syntax.Argument", to:   "Syntax",
@@ -194,13 +395,21 @@ module Hecks
           end
         end
 
-        # EVERY AGGREGATE-LOCAL TABLE IN EVERY LOADED LANGUAGE CHAPTER.
+        # Every aggregate-local table in every loaded language chapter.
         # The table's presence is the registration: no chapter, aggregate,
         # filename, or context catalog is maintained here. This finds the core
         # Bluebook concepts, the sibling artifact languages (World, Hecksagon,
         # Port, Adapter, Translation), and attached sub-languages alike.
-        # Concatenated into ONE sequence because `position` is minted from the
+        # Concatenated into one sequence because `position` is minted from the
         # walk index and must not collide across concepts.
+        #
+        # @param bluebook [Bluebook::Chapter] the language's own assembled
+        #   "Bluebook" chapter, read first, before every other loaded
+        #   chapter
+        # @param name [String] the local value-object name to collect rows
+        #   of, such as `"KeywordSeed"`
+        # @return [Array<Hash{Symbol => String}>] every matching row, across
+        #   every loaded chapter, in chapter order
         def all_rows(bluebook, name)
           seed_chapters(bluebook).flat_map { |chapter| rows(chapter, name) }
         end
@@ -209,6 +418,11 @@ module Hecks
         # sibling/extension. The name rejection avoids reading the same core
         # object twice without relying on object identity across fixpoint
         # assembly.
+        #
+        # @param bluebook [Bluebook::Chapter] the language's own assembled
+        #   "Bluebook" chapter
+        # @return [Array<Bluebook::Chapter>] `bluebook` first, then every
+        #   other chapter the grammar registry holds
         def seed_chapters(bluebook)
           [bluebook] + MetaValidator.grammar_registry.bluebooks.values.reject { |chapter| chapter.name == bluebook.name }
         end
@@ -217,6 +431,13 @@ module Hecks
         # every aggregate that owns a same-named local value object. Repeating
         # the value-object shape is deliberate: each concept remains readable
         # by itself, while this discovery is the only grouping mechanism.
+        #
+        # @param bluebook [Bluebook::Chapter] the chapter to search
+        # @param name [String] the local value-object name to collect rows
+        #   of, such as `"KeywordSeed"`
+        # @return [Array<Hash{Symbol => String}>] one hash per member row,
+        #   `[]` if no aggregate in `bluebook` owns a value object named
+        #   `name`
         def rows(bluebook, name)
           bluebook.aggregates.flat_map do |aggregate|
             value_object = aggregate.value_objects.find { |vo| vo.hecks_name == name }
@@ -226,10 +447,18 @@ module Hecks
           end
         end
 
-        # Reads the dispatched result back into the SAME shape `rows`
+        # Reads the dispatched result back into the same shape `rows`
         # above hands the seed data in as — plain hashes, string values,
         # `status` included — so `ParserTable`/`syntax_conformance_spec`
         # need not know or care that a real dispatch happened in between.
+        #
+        # @param runtime [Runtime::Dispatcher] the runtime `boot` dispatched
+        #   every seed row into
+        # @param bluebook [Bluebook::Chapter] the language's own assembled
+        #   "Bluebook" chapter, read for its `"Syntax"` aggregate
+        # @return [Hash{Symbol => Array<Hash{Symbol => String}>}] `:keywords`
+        #   and `:arguments`, each an array of plain, string-valued row
+        #   hashes (`status` included)
         def read_back(runtime, bluebook)
           syntax = bluebook.aggregate("Syntax")
           repository = runtime.registry.repository("Bluebook", syntax)
@@ -241,12 +470,23 @@ module Hecks
           }
         end
 
+        # Flattens one dispatched record into a plain, string-valued row.
+        #
+        # @param row [Object] one dispatched keyword or argument record,
+        #   answering `to_h`
+        # @return [Hash{Symbol => String}] `row`'s own fields, each value
+        #   unwrapped and stringified
         def stringify(row)
           row.to_h.transform_values do |cell|
             scalar(cell).to_s
           end
         end
 
+        # Unwraps one field's stored value to its bare scalar.
+        #
+        # @param cell [Object] one field's stored value
+        # @return [Object] `cell`'s sole wrapped value, if `cell` is a
+        #   to_h-able non-String; `cell` unchanged otherwise
         def scalar(cell)
           return cell.to_h.values.first if cell.respond_to?(:to_h) && !cell.is_a?(String)
 

data/lib/hecks/bluebook/meta_validator/translation_judge.rb

@@ -10,7 +10,7 @@ module Hecks
       # AdapterJudge already are — its own file, its own door, judged
       # through its own self-hosted language (translation.bluebook)
       # rather than left as plain Ruby structs nothing checks. Walks the
-      # WHOLE built translation in one pass — the top-level Declare/
+      # whole built translation in one pass — the top-level Declare/
       # Retire commands, then every nested aggregate's own Declare plus
       # one Add* command per rule it carries — the same "one judge, every
       # nested record" shape WorldJudge already gives Wiring. Field names
@@ -22,6 +22,7 @@ module Hecks
       class TranslationJudge
         attr_reader :refusals
 
+        # @param translation [Bluebook::Translation] the built translation to judge
         def initialize(translation)
           @translation = translation
           @refusals    = []
@@ -35,18 +36,18 @@ module Hecks
 
         def args(pairs) = pairs.compact
 
-        # `Runtime::AlreadyExists` is rescued HERE but not by World/Port/
+        # `Runtime::AlreadyExists` is rescued here but not by World/Port/
         # Adapter's own sibling judges — found live, not by inspection.
-        # Those three each judge a SINGLE aggregate per build (Port/Adapter)
+        # Those three each judge a single aggregate per build (Port/Adapter)
         # or a Hash keyed by verb (World's own settings, deduped by
         # construction), so a duplicate-identity Declare can never reach
         # their own runtime. `TranslationBuilder#aggregate` appends every
         # block to a plain Array (`@aggregates << builder.build`) with no
         # dedup — two `aggregate "Account" do ... end` blocks in the same
-        # translation are syntactically legal and reach here for real. Left
-        # unrescued, the second Declare's `AlreadyExists` crashed straight
-        # through `call_translation` instead of becoming a clean refusal —
-        # confirmed via direct dispatch before this fix.
+        # translation are syntactically legal and reach here for real.
+        # Left unrescued, the second Declare's `AlreadyExists` would crash
+        # straight through `call_translation` instead of becoming a clean
+        # refusal — confirmed via direct dispatch.
         def offer(label)
           yield
         rescue Runtime::GivenNotMet, Runtime::InvariantViolation, Runtime::TypeMismatch,
@@ -65,13 +66,13 @@ module Hecks
           send_to("Translation::Translation.Declare", t.domain,
                   with: { domain: v(t.domain), from: v(t.from), to: v(t.to) })
 
-          # `id:`, computed the SAME way — `Naming.identity([domain, from,
-          # to])` — Translation's own identity is COMPOSITE
+          # `id:`, computed the same way — `Naming.identity([domain, from,
+          # to])` — Translation's own identity is composite
           # (`identified_by :domain, :from, :to`), the same reason
           # `Wiring.Set`'s own self-reference dispatch (world.bluebook,
           # `WorldJudge#judge_wiring`) needs a computed `id:` rather than
           # a bare field value — a single-field identity (TranslationAggregate's
-          # own `name`) is the ONE case where the bare value itself IS the
+          # own `name`) is the one case where the bare value itself is the
           # id, confirmed live via direct dispatch testing, not assumed.
           translation_id = Naming.identity([t.domain, t.from, t.to])
           Array(t.retired).each do |name|

data/lib/hecks/bluebook/meta_validator/world_judge.rb

@@ -3,13 +3,14 @@ module Hecks
     module MetaValidator
       # Offers a built .world to the language that describes worlds.
       #
-      # A world is a SIBLING of a bluebook — the same domain runs in many of
+      # A world is a sibling of a bluebook — the same domain runs in many of
       # them — so it is judged through its own door, against its own language
       # file, and its settings normalise the same way a mutation's fields do:
       # an open map becomes one Wiring per verb and one Setting row per value.
       class WorldJudge
         attr_reader :refusals
 
+        # @param world [Bluebook::World] the built world to judge
         def initialize(world)
           @world    = world
           @refusals = []
@@ -51,14 +52,14 @@ module Hecks
         end
 
         def judge_wiring(domain, verb, values)
-          # THE SAME JOIN THE LANGUAGE ITSELF DERIVES. Wiring is
+          # The same join the language itself derives. Wiring is
           # `identified_by do world; verb.value end` — `Wiring.Declare`
-          # (a creating command) ignores this `id:` entirely and computes its OWN
+          # (a creating command) ignores this `id:` entirely and computes its own
           # from `world`/`verb`, so a locally minted "#{domain}.#{verb}" named a
           # record `Wiring.Set` could never find : the id passed here has to be
-          # the SAME derivation, not a second guess at what it must be.
+          # the same derivation, not a second guess at what it must be.
           id = Naming.identity([domain, verb])
-          # `world_ref` is the WORLD's id and goes bare, the way every reference
+          # `world_ref` is the world's id and goes bare, the way every reference
           # does now ; the language gives it that explicit `as:` because `world`
           # beside it is an ordinary text attribute that happens to hold the same
           # string, and stays a value object. The two look alike and are not —