hecks 2.8.0 → 3.0.0

data/lib/hecks/bluebook/meta_validator.rb

@@ -1,142 +1,47 @@
 require "digest"
 require "json"
+require_relative "meta_validator/verdict_cache"
 
 module Hecks
   module Bluebook
     # Judges a bluebook by dispatching it into the language declared in itself.
-    #
-    # `lib/hecks/language/bluebook/` declares what a bluebook is —
-    # Chapter, Root, Verb, Shape, Ask, Piece, and the rest, split across files
-    # by domain concept and merged into one chapter at load time (see
-    # GRAMMAR_FILES below). This replays a built IR into that domain and turns
-    # any refusal into a Malformed, so the meta-domain is what actually judges
-    # rather than a description sitting beside the code — for whatever rules
-    # it carries. `spec/meta_rules_spec.rb`'s own header names the plan: port
-    # the language's rules out of builder `raise Malformed` calls and into
-    # `given`/`invariant` here, where they are declarations any reader of the
-    # meta-domain can consume instead of behavior buried in a builder.
-    #
-    # ## This migration is partial, not done
-    #
-    # As of this writing the meta-domain declares 62 given/invariant/ensures
-    # rules (`Hecks::QueryIR.collect_rules` against
-    # `grammar_registry.bluebook("Bluebook")` enumerates them) —
-    # `spec/meta_rule_reachability_spec.rb` is what proves, per declaration,
-    # not per verb, that most of them still lack a spec exercising the
-    # refusal at all (see that file's own KNOWN_GAPS for the current count).
-    # Meanwhile `lib/hecks/bluebook/dsl/` still carries well over a hundred
-    # `raise Malformed` calls of its own — some are genuinely pre-IR
-    # construction errors (arity, argument shape) that cannot become
-    # meta-domain rules, and some are exactly the semantic kind this file
-    # claims to have moved (see `aggregate_builder.rb`'s `seal_*` passes:
-    # a mutation into a field the aggregate never declares, a lifecycle guard
-    # on an aggregate with no lifecycle). No doc currently inventories which
-    # is which, or tracks migrating the latter — that inventory is the actual
-    # next step, not a "delete the folder" thought experiment.
-    #
-    # So: "delete language/bluebook/ and validation stops" is true for the 62
-    # rules actually declared here, and false for whatever a builder's own
-    # `raise Malformed` still checks — the language does not yet own its own
-    # enforcement end to end. The self-hosting mechanism itself is real and
-    # is the point worth keeping : a self-description that only describes is
-    # indistinguishable from enforcement, and the first version of this file
-    # was deleted for exactly that reason. What is not yet real is that
-    # self-hosting being the whole of validation.
-    #
-    # ## Isolation
-    #
-    # The meta-domain is loaded once and its registry reused ; each bluebook is
-    # judged in a fresh in-memory store so no domain can see another's records.
+    # Refusals become `DSL::Malformed`; the meta-domain does the judging, not a builder.
     module MetaValidator
-      # **The folder is the chapter**. Files are grouped by the domain concept they
-      # describe and every one reopens the same `Hecks.bluebook "Bluebook"`.
-      # `BluebookBuilder.build` keeps one builder open per chapter name across
-      # calls, so the sorted folder accumulates one domain. Adding or renaming a
-      # concept file requires no second catalog here; deterministic filename
-      # order is the source order exported to IR.
+      # Deterministic file order becomes the source order exported to IR.
       GRAMMAR_DIR   = File.expand_path("../language/bluebook", __dir__).freeze
       GRAMMAR_FILES = Dir.glob(File.join(GRAMMAR_DIR, "*.bluebook")).freeze
-      # Sibling artifact languages use the same folder-is-the-chapter rule.
-      # Their arrays are discovered, sorted source sets—not filename catalogs.
       WORLD_GRAMMAR = Dir.glob(File.expand_path("../language/world/*.bluebook", __dir__)).freeze
       HECKSAGON_GRAMMAR = Dir.glob(File.expand_path("../language/hecksagon/*.bluebook", __dir__)).freeze
-      # so is a port — whole-project table-unification survey, item #13's
-      # remaining builders. Backs the new PortJudge door the same way
-      # WORLD_GRAMMAR backs WorldJudge.
+      # Backs PortJudge, the same door shape as WorldJudge.
       PORT_GRAMMAR = File.expand_path("../language/port.bluebook", __dir__).freeze
-      # so is an adapter — same reasoning, one file over. Backs AdapterJudge.
+      # Backs AdapterJudge, one file over.
       ADAPTER_GRAMMAR = File.expand_path("../language/adapter.bluebook", __dir__).freeze
-      # so is a translation — same reasoning, one file over. Backs
-      # TranslationJudge.
+      # Backs TranslationJudge, one file over.
       TRANSLATION_GRAMMAR = Dir.glob(File.expand_path("../language/translation/*.bluebook", __dir__)).freeze
 
-      # ADR 0026's own seam: the core does not name its extension points.
-      #
-      # A sub-language chapter (Paging, so far the only one) is an ordinary
-      # bluebook — declared with the same `aggregate`/`value_object`/
-      # `attaches_to` words every domain has, judged through the language
-      # the normal way, not bootstrapped raw the way GRAMMAR_FILES is. What
-      # makes it special is only where it lives: any file in this directory
-      # is discovered and loaded here, by the directory's own existence,
-      # never by a name this file would have to know. Add a chapter here
-      # and it is attached ; nothing in this file changes.
+      # (ADR 0026) Any bluebook file placed here is auto-discovered and
+      # loaded as an extension chapter; nothing else in this file changes.
       ATTACHED_GRAMMAR_DIR = File.expand_path("../language/bluebook/attaches", __dir__).freeze
 
-      # The chapters that are the language — loaded raw during bootstrap, then
-      # judged through themselves and replaced by their own assembled graphs
-      # (see grammar_registry). Each is named after its file : Bluebook describes
-      # bluebooks (language/bluebook/) ; World describes worlds (world.bluebook),
-      # and backs the WorldJudge door ; Hecksagon describes hecksagons
-      # (hecksagon.bluebook) — declared for the same self-description reasons as
-      # World, but without a judge door of its own : nothing dispatches a real
-      # .hecksagon file through it yet, so HecksagonBuilder's own behavior is
-      # unchanged. What this buys is what syntax.bluebook needed — a real shape
-      # `subscribe`'s `fills: "subscriptions"` can point at — not new validation
-      # on top of the corpus's existing .hecksagon files.
+      # The chapters loaded raw at bootstrap, then judged through themselves
+      # and replaced by their own self-assembled graphs.
       LANGUAGE_CHAPTERS = %w[Bluebook World Hecksagon].freeze
 
-      # The meta-domain is itself a bluebook. Judging it while loading it would
-      # recurse, so the load path marks the bootstrap and skips — but the skip
-      # is only the first pass. Once every grammar file is loaded and merged,
-      # grammar_registry judges the language through itself and keeps the
-      # assembled result (the fixpoint, made load-bearing).
+      # Whether the language's own grammar is still loading raw, unjudged.
+      # Judging it while it loads would recurse, so the bootstrap sets this
+      # and the fixpoint clears it once every grammar file is merged.
       #
-      # @return [Boolean] whether the language's own grammar is still
-      #   loading raw, unjudged
+      # @return [Boolean]
       def self.bootstrapping? = @bootstrapping
 
-      # A chapter may be split across files, so it cannot be judged until
-      # every file has been read.
-      #
-      # `BluebookBuilder.build` already merges — `registry.bluebook_builder
-      # (name)` memoises one builder per chapter name, so nine files each
-      # saying `Hecks.bluebook "Bluebook"` accumulate into one. What it
-      # also does is call `MetaValidator.call` once per file, judging a
-      # chapter that is still eight files short: `Aggregate`'s reference
-      # to `Bluebook` dangles because `Bluebook` has not been declared
-      # yet, and the load dies.
-      #
-      # The language's own grammar has always needed this and got it
-      # privately, through `@bootstrapping` (see load_grammar_into) —
-      # which is exactly why the language could not boot the way the
-      # domains it describes boot. This is that same two-phase load,
-      # available to anything: `Folder#load_domain` reads every
-      # `*.bluebook` inside `defer`, then judges each composed chapter
-      # once, before hecksagons and worlds load (DOMAIN_ORDER already
-      # puts every chapter ahead of those).
+      # Whether `call` is queuing chapters instead of judging them, while a
+      # chapter's own files are still being merged (see `defer`).
       #
-      # Only chapters declared inside the window are judged afterwards.
-      # Re-judging one already assembled — a framework member pulled in
-      # earlier by `uses_framework`, say — would re-run Assembly and hand
-      # out a second set of classes for a graph something already holds.
-      #
-      # @return [Boolean] whether `call` is currently queuing chapters
-      #   instead of judging them
+      # @return [Boolean]
       def self.deferring? = @deferring
 
-      # Opens the two-phase-load window: every chapter `call` sees while
-      # the block runs is queued (see `deferred_chapters`) rather than
-      # judged immediately.
+      # Queues every chapter `call` sees while the block runs, instead of
+      # judging them immediately (see `deferred_chapters`).
       #
       # @yield the caller's own load of every file in one chapter window
       # @return [Object] the block's own return value
@@ -173,75 +78,32 @@ module Hecks
           chapter = registry.bluebook(name)
           next unless chapter
 
-          # A bare chapter-given left pending by any file of this
-          # chapter (`AggregateBuilder#pending_chapter_given`) resolves
-          # first — before anything below reads a `Given`'s fields.
-          # `registry.bluebook_builder(name)` is the same instance every
-          # one of this chapter's own files built onto (`#self.build`'s
-          # own comment); it is guaranteed already open here, since it
-          # is what produced `chapter` in the first place — the block is
-          # dead code, never actually invoked.
+          # Bare chapter-level givens must resolve before anything below
+          # reads a `Given`'s fields. The `raise` block never runs — this
+          # chapter's builder is always already open by the time `chapter` exists.
           builder = registry.bluebook_builder(name) { raise "internal: no open builder for #{name}" }
           builder.resolve_pending_chapter_givens!
-          # The entity-scoped analogue, one level down — same reason,
-          # same timing: a bare entity-level given left pending by any
-          # file of this chapter (`EntityBuilder#pending_chapter_entity_
-          # given`) must resolve before anything below reads a piece's
-          # own `Given` fields too.
+          # Same, one level down: entity-scoped pending givens.
           builder.resolve_pending_chapter_entity_givens!
 
-          # `BluebookBuilder#build` skipped its own whole-chapter battery
-          # (hops, projected fields, correlation keys, event shapes,
-          # `with:` projections) for every file of this chapter while
-          # `deferring?` was true, the same reason `call` below queued
-          # instead of judging — each of those checks needs every file
-          # loaded first (see `BluebookBuilder.validate_assembled!`'s own
-          # comment). `chapter` here is exactly that: whatever the last
-          # file's own `add_bluebook` left in the registry, which by now
-          # holds every aggregate/policy/process_manager the whole
-          # chapter declares. Run once, here, instead of once per file.
+          # Whole-chapter checks (hops, projected fields, event shapes) were
+          # skipped per file while deferring; `chapter` now holds every
+          # file's declarations, so they run once here instead of per file.
           DSL::BluebookBuilder.validate_assembled!(chapter)
           registry.add_bluebook(call(chapter))
         end
       end
 
-      # `&& !@forcing_fixpoint` — see `while_forcing_fixpoint` below, whose own
-      # window must win even while a growth spec's `while_disabled` is open,
-      # for the reason recorded there. Uses the same stack-restore shape
-      # `while_shadow_parsing`/`while_forcing_fixpoint` use, deliberately not
-      # a bare env toggle (`ENV["HECKS_META_VALIDATION"] == "off"`, read
-      # directly, with no `previous`/`ensure` of its own): the gap between
-      # "bare toggle" and "stack-restore" is not cosmetic — a test's
-      # temporary window could reach code it was never meant to touch. If
-      # `grammar_registry`'s one-time lazy build (below) happens to land
-      # inside that window, every language chapter gets cached in its raw,
-      # never-judged form for the rest of the process — `unmark_scalar`'s
-      # String->Integer/Boolean fix (assembly/marks.rb) never runs, so a
-      # `Command`'s own `required: true` stays `required: "true"` forever
-      # after, permanently memoized. Found live: an intermittent,
-      # parallel_rspec-only ir_golden_spec.rb failure, order-dependent on
-      # whether identifier_numeric_coercion_growth_spec.rb's
-      # disabled-validation window raced the one lazy build in its own worker
-      # process — reproduced in isolation by disabling validation before the
-      # first `grammar_registry` call. `&& !@forcing_fixpoint` was the first
-      # fix and is kept ; `@disabled` itself uses this same stack-restore
-      # shape to close the gap for every other caller of `while_disabled`,
-      # not just the one race that was actually observed — nothing outside
-      # this file reads `ENV["HECKS_META_VALIDATION"]` (every growth spec
-      # calls `while_disabled` instead), so there is no bare global left to
-      # race.
+      # Whether meta-domain judging is off (ignored while a fixpoint build
+      # is forced).
+      # Stack-restored, not a bare flag, so a disabled window can never
+      # leak past its own scope.
       #
-      # @return [Boolean] whether meta-domain judging is currently switched
-      #   off (and not overridden by a fixpoint build in progress)
+      # @return [Boolean]
       def self.disabled? = @disabled && !@forcing_fixpoint
 
-      # The same stack-restore shape `while_shadow_parsing`/`while_forcing_
-      # fixpoint` use. This toggle's real, intended use is a growth spec
-      # that boots a scratch bluebook from a tempfile and wants the runtime
-      # behaviour without the validation overhead ; that is always a single
-      # bounded window around one boot, never a flag meant to survive past
-      # it, so the flag itself is scoped in the same `previous`/`ensure`
-      # shape rather than a plain assignment a caller could forget to undo.
+      # Runs `block` with `disabled?` true, restoring it afterward — for a
+      # growth spec that boots a scratch bluebook without validation overhead.
       #
       # @yield the caller's own boot, with `disabled?` true throughout
       # @return [Object] the block's own return value
@@ -253,24 +115,11 @@ module Hecks
         @disabled = previous
       end
 
-      # ADR 0025's own prerequisite (docs/dsl-work-slices.md, S0a): a word
-      # a later slice removes from the live grammar must still parse
-      # frozen era text — `EraGuard.shadow_parse` (runtime/era_guard.rb)
-      # is a plain `Kernel.eval` of stored source, run at boot, at mint,
-      # and during tamper detection, against whatever grammar is live
-      # today, not whatever grammar was live when that text was written.
-      # Judging it again here would refuse history the day a spelling it
-      # used is removed — proved with a rule that already lives only in
-      # the meta-domain, never duplicated as a builder's own `raise
-      # Malformed` (`vision`'s own comment: "moved to the language").
-      #
-      # Mirrors `defer`'s own stack-restore shape — this must never leak
-      # past the one shadow-parse call that set it, the same reason
-      # `ConstShim.with`/`.active?` (bluebook/dsl/const_shim.rb) restores in
-      # an `ensure` rather than being flipped and left.
+      # (ADR 0025) Whether frozen era text is currently being shadow-parsed
+      # by `EraGuard`. Judging it again here would refuse history whenever a
+      # spelling it used gets removed from the live grammar.
       #
-      # @return [Boolean] whether frozen era text is currently being
-      #   shadow-parsed
+      # @return [Boolean]
       def self.shadow_parsing? = @shadow_parsing
 
       # Wraps `block` with `shadow_parsing?` true, restoring it afterward.
@@ -285,13 +134,8 @@ module Hecks
         @shadow_parsing = previous
       end
 
-      # The same stack-restore shape `while_shadow_parsing` uses, for the
-      # same reason: whatever this wraps must never see `disabled?` answer
-      # true, however a test elsewhere has a `while_disabled` window open at
-      # that exact moment. Only `grammar_registry`'s own one-time build
-      # (below) wraps itself in this — nothing else needs it, and nothing
-      # else should reach for it just to dodge `disabled?` for a domain
-      # bluebook, which is precisely the toggle's real, intended use.
+      # Wraps `block` with `disabled?` forced false, restoring it afterward.
+      # Only `grammar_registry`'s one-time fixpoint build uses this.
       #
       # @yield the one-time fixpoint build, with `disabled?` forced false
       #   throughout
@@ -304,18 +148,18 @@ module Hecks
         @forcing_fixpoint = previous
       end
 
-      # The same bluebook judged twice gets the same verdict, and a suite reloads
-      # its fixtures constantly — banking alone is ~200 dispatches per build.
-      # Keyed on the IR itself, so a changed bluebook is always re-judged.
+      # Process-wide judging cache, keyed on a SHA-256 digest of the judged
+      # artifact so a changed bluebook is always re-judged.
       #
-      # @return [Hash{String => Array<String>}] the process-wide judging
-      #   cache, keyed by a SHA-256 digest of the judged artifact; each
-      #   value is that artifact's own list of refusal messages (`[]` when
-      #   well formed)
-      def self.verdicts = @verdicts ||= {}
-
-      # A world is not a bluebook, so it gets its own door. Same judge, same
-      # meta-domain registry — a different artifact and a different language file.
+      # Seeded once per process with the chapter verdicts earlier processes
+      # stored (see `VerdictCache`); every other verdict starts empty.
+      #
+      # @return [Hash{String => Object}] refusal messages per digest for a
+      #   world/port/adapter/translation (`[]` when well formed); the held
+      #   verdict Hash for a chapter
+      def self.verdicts = @verdicts ||= VerdictCache.seed
+
+      # Judges `world` through the meta-domain's own `WorldJudge` door.
       #
       # @param world [Bluebook::World] the world to judge
       # @return [Bluebook::World] `world` unchanged, if well formed or
@@ -332,9 +176,7 @@ module Hecks
               "#{world.domain}'s world is not well formed; #{refusals.join('; ')}"
       end
 
-      # A port is not a bluebook either — same door shape as call_world,
-      # one artifact over. Whole-project table-unification survey, item
-      # #13's remaining builders.
+      # Judges `port` through the meta-domain's own `PortJudge` door.
       #
       # @param port [Bluebook::Port] the port to judge
       # @return [Bluebook::Port] `port` unchanged, if well formed or while
@@ -351,9 +193,7 @@ module Hecks
               "#{port.name}'s port is not well formed; #{refusals.join('; ')}"
       end
 
-      # An adapter is not a bluebook either — same door shape, one more
-      # artifact over. Whole-project table-unification survey, item
-      # #13's remaining builders.
+      # Judges `adapter` through the meta-domain's own `AdapterJudge` door.
       #
       # @param adapter [Bluebook::Adapter] the adapter to judge
       # @return [Bluebook::Adapter] `adapter` unchanged, if well formed or
@@ -370,17 +210,8 @@ module Hecks
               "#{adapter.name}'s adapter is not well formed; #{refusals.join('; ')}"
       end
 
-      # A translation is not a bluebook either — same door shape, one more
-      # artifact over (a `translations/*.bluebook` edge — `data_translation`'s
-      # own real, established convention; there is no separate extension).
-      # TranslationJudge walks the whole built translation (every nested
-      # aggregate's own rule table) in one pass — only
-      # TranslationBuilder's own top-level `build` calls this;
-      # TranslationAggregateBuilder#build stays a plain struct constructor,
-      # the same way `WorldJudge` judges every `Wiring` a `.world` declares
-      # in one pass over `World::World.Declare`'s own caller, not from a
-      # separate door per binding. Whole-project table-unification survey,
-      # item #13's remaining builders.
+      # Judges `translation` through the meta-domain's own `TranslationJudge`
+      # door, walking every nested aggregate's own rule table in one pass.
       #
       # @param translation [Bluebook::Translation] the translation to judge
       # @return [Bluebook::Translation] `translation` unchanged, if well
@@ -390,15 +221,9 @@ module Hecks
       def self.call_translation(translation)
         return translation if disabled? || bootstrapping? || shadow_parsing?
 
-        # `Translation`/`TranslationAggregate` are plain classes (attr_
-        # reader, not Struct — lib/hecks/bluebook/translation.rb),
-        # so neither carries a `.to_h`; `.inspect` is JSON-safe (a plain
-        # string) and, unlike a Struct's own memoization-friendly `.to_h`,
-        # doesn't need one — the small correctness cost is that its
-        # embedded object-id prefix makes two structurally-identical
-        # translations hash differently, so `verdicts` simply never
-        # cache-hits here (an efficiency loss, not a correctness one —
-        # judged fresh every time instead of memoized).
+        # `Translation` has no `.to_h`; `.inspect` embeds an object-id, so
+        # structurally-identical translations never cache-hit here (a lost
+        # optimization, not a correctness issue).
         key = Digest::SHA256.hexdigest(translation.inspect)
         refusals = verdicts[key] ||= TranslationJudge.new(translation).refusals
         return translation if refusals.empty?
@@ -407,45 +232,9 @@ module Hecks
               "#{translation.domain}'s translation is not well formed; #{refusals.join('; ')}"
       end
 
-      # The language hands the graph back.
-      #
-      # A bluebook judged elsewhere only checks: dispatch every declaration
-      # in, collect refusals, throw the records away — which is all a
-      # boundary check needs. This is the one call that returns what the
-      # meta-domain holds instead, assembled into the graph the runtime
-      # runs, so the builder's own object graph exists only to be
-      # dispatched — nothing keeps it. `Hecks.bluebook` registers whatever
-      # comes back from here, so this one line is the difference between a
-      # language that checks a domain and a language that is the source of
-      # one: the runtime runs what the meta-domain holds, not the builder's
-      # own graph.
-      #
-      # What is cached is the declarations, not the graph. A hash carries no
-      # Ruby classes, so a second load of the same chapter re-assembles
-      # fresh ones — the behaviour `Namespace.install` and
-      # `spec/construct_spec` both expect. Caching the graph would hand two
-      # boots the same classes.
-      #
-      # One belief stayed unlanded for a while, worth naming because it
-      # looked so much like a wall: that the language may only hold what
-      # `to_h` carries. `ReadModel#to_h` omitted a read model's filters
-      # until 2026-08-11, so read-model filtering seemed impossible to read
-      # back — and hoisted policies lost which head declared them for the
-      # same reason. But `to_h` is a projection and the language is the
-      # source. They must agree about everything `to_h` spells ; they need
-      # not be the same size. Both were held even before the wire format
-      # carried them, as declarations the wire format didn't yet see.
-      #
-      # The wire format did later move, for a reason unrelated to this
-      # file — a Rust-codegen task needed `wheres`/`order_by`/`limit` on
-      # the wire to compile a read model's real declared filtering, and the
-      # boundary described above was never load-bearing for this mechanism
-      # (`option_rows`/`filter_options` in meta_validator/readings.rb read
-      # `node.wheres`/`node.order_by`/`node.limit` off the live object
-      # directly, never off `to_h`), so extending `to_h` changed nothing
-      # here. `ReadModel#to_h` now spells all three explicitly, the same
-      # mechanism `Query#to_h` already used — purely additive, still
-      # agreeing with the language about everything it spells.
+      # Dispatches `bluebook` into the language and returns the graph the
+      # meta-domain assembles from its own judged declarations, not the
+      # builder's original object graph.
       #
       # @param bluebook [Object] a built bluebook chapter graph (an
       #   `Aggregate`/`Entity`/`ValueObject`/... instance from
@@ -464,7 +253,7 @@ module Hecks
         end
 
         key = Digest::SHA256.hexdigest(JSON.generate(bluebook.to_h))
-        held = verdicts[key] ||= hold(bluebook)
+        held = verdicts[key] || (verdicts[key] = hold(bluebook).tap { |fresh| VerdictCache.record(key, fresh) })
 
         unless held[:refusals].empty?
           raise DSL::Malformed,
@@ -474,9 +263,9 @@ module Hecks
         Assembly.call(held[:declaration])
       end
 
-      # Dispatch it in and read it back. A refused chapter has no declarations to
-      # read — the records are half-written by definition — so it carries refusals
-      # and nothing else.
+      # Dispatches `bluebook` into the meta-domain and reads the result back.
+      # A refused chapter carries only its refusals — the records are
+      # half-written by definition.
       #
       # @param bluebook [Object] a built bluebook chapter graph, as `call`
       #   receives it
@@ -499,72 +288,38 @@ module Hecks
       def self.grammar_registry
         @grammar_registry ||= begin
           registry = load_grammar_into(Runtime::Registry.new)
-          # Assigned before the fixpoint judge below: judging re-enters
-          # grammar_registry through fresh_runtime (judge.rb) and Plan.for
-          # (judge.rb, reconstruction.rb) — a bare ||= would still be nil
-          # while its right-hand side evaluates, and recurse forever. That
-          # reentrancy window is real: a caller landing here before the
-          # fixpoint/attach below have run sees the same registry object,
-          # correctly, but one still missing the attached chapters (Paging's
-          # `attaches_to` among them) — see grammar_registry_ready? below.
+          # Assigned before the fixpoint judge below, since judging re-enters
+          # grammar_registry (via fresh_runtime/Plan.for) and a bare `||=`
+          # would still be nil mid-evaluation, recursing forever.
           @grammar_registry = registry
-          # **The fixpoint made load-bearing**. The bootstrap loaded the language
-          # raw ; now the language judges itself, its records are read back,
-          # and the assembled graph replaces the raw one — so every bluebook
-          # judged from here on is judged by the language the language itself
-          # produced. Outside load_grammar_into on purpose : its ensure clears
-          # @bootstrapping, and call() must see bootstrapping? == false to do
-          # anything at all. `while_forcing_fixpoint`-wrapped so a growth
-          # spec's own `while_disabled` window can never leave this
-          # one-time build cached in its raw, never-judged form — see
-          # `disabled?`'s own comment.
+          # The language now judges itself; every bluebook from here on is
+          # judged by that assembled graph, not the raw bootstrap one. Must
+          # run after load_grammar_into's ensure clears @bootstrapping.
           while_forcing_fixpoint do
             LANGUAGE_CHAPTERS.each { |name| registry.add_bluebook(call(registry.bluebook(name))) }
             load_attached_grammar_into(registry)
           end
-          # Stamped last, keyed by this registry's own identity rather than
-          # a bare boolean — a manual reset (fixpoint_spec.rb's own
-          # `@grammar_registry = nil`) makes @grammar_registry not equal
-          # this object_id again until a fresh build finishes, so a stale
-          # "ready" from the previous cycle can never leak into the next.
+          # Keyed on this registry's object identity, not a bare boolean, so
+          # a manual reset can never leave a stale "ready" from the previous
+          # cycle.
           @grammar_ready_for = registry.object_id
           registry
         end
       end
 
-      # A reentrant call during the fixpoint/attach window above gets a
-      # real, correctly-mutating registry object back — no infinite loop,
-      # no wrong data for that caller's own purposes. But anything that
-      # memoizes a snapshot derived from it must not lock that snapshot
-      # in forever : this is one signal such a cache can check. Found
-      # live — SyntaxBoot.call had cached a Query keyword list missing
-      # every Paging-attached word (limit/offset/cursor/nulls) because
-      # something called it inside this exact window.
+      # Whether `grammar_registry`'s memoized singleton has finished its
+      # fixpoint judge and attached-chapter load.
       #
-      # SyntaxBoot.call does not use this. Gating its cache on "the
-      # whole registry is finished" meant nothing was cached for the
-      # entire window, and the window is not narrow — every word routed
-      # through `word_gate_dispatch` while the language judged itself
-      # re-ran the ~284-dispatch syntax boot (42 times, 32 seconds, per
-      # process — see SyntaxBoot.call's own comment). It keys its cache
-      # on the registry's chapter set instead, which is the actual input
-      # the snapshot is a function of. Kept here for any other derived
-      # cache that genuinely needs "is the build finished" rather than
-      # "have my inputs changed".
+      # A cache keyed on "finished" instead of its own inputs already missed
+      # data for a whole build window once.
       #
-      # @return [Boolean] whether `grammar_registry`'s memoized singleton
-      #   has finished its fixpoint judge and attached-chapter load
+      # @return [Boolean]
       def self.grammar_registry_ready?
         @grammar_registry && @grammar_ready_for == @grammar_registry.object_id
       end
 
-      # Attached chapters load after the fixpoint, not during bootstrap —
-      # they are declared in the language the language just finished
-      # judging itself through, so they are ordinary bluebooks, judged the
-      # ordinary way (`Hecks.bluebook` → `BluebookBuilder#build` →
-      # `MetaValidator.call`, `bootstrapping?` already false). A directory
-      # with nothing in it loads nothing ; this is a no-op until a chapter
-      # is added there.
+      # Loads every `ATTACHED_GRAMMAR_DIR` chapter file into `registry`,
+      # judged the ordinary way since the fixpoint has already run.
       #
       # @param registry [Runtime::Registry] the registry to load every
       #   `ATTACHED_GRAMMAR_DIR` chapter file into
@@ -575,27 +330,14 @@ module Hecks
         end
       end
 
-      # The one place the grammar's own boot sequence is spelled — ports, the
-      # memory/prism adapters, the (now nine-file) chapter itself, then the
-      # sibling world grammar. `grammar_registry` uses this for its memoised
-      # singleton ; anything that needs an isolated registry (a spec wanting a
-      # fresh store per example, say) calls this directly instead of hand-
-      # copying the sequence.
+      # Loads the whole grammar (ports, adapters, every language chapter)
+      # into `registry`, raw and unjudged.
       #
-      # The bootstrap guard lives here, not just around the singleton. Splitting
-      # the chapter into several files means each file's own `Hecks.bluebook
-      # "Bluebook"` call now runs `BluebookBuilder#build` once per file — and
-      # `MetaValidator.call` judges whatever it is handed unless `bootstrapping?`
-      # is true. A caller that loaded the grammar files by hand into its own
-      # registry, without this guard, would get each file dispatched and judged
-      # alone the moment it loaded — and a lone file like `aggregate.bluebook`
-      # refuses immediately, since `Aggregate.Attribute` references `ValueObject`
-      # and `Aggregate.Holds` references `Entity`, both declared in later files.
-      # Every caller of the grammar must go through here for exactly that reason.
+      # The `@bootstrapping` guard matters: without it a chapter split
+      # across files would get judged one file at a time and refuse early.
       #
       # @param registry [Runtime::Registry] the registry to load the whole
-      #   grammar (ports, adapters, and every language chapter) into, raw
-      #   and unjudged
+      #   grammar into, raw and unjudged
       # @return [Runtime::Registry] `registry`, unchanged in identity
       def self.load_grammar_into(registry)
         @bootstrapping = true
@@ -616,15 +358,8 @@ module Hecks
         @bootstrapping = false
       end
 
-      # A fresh store per bluebook. The registry memoises repositories, so
-      # reusing it let every bluebook see the records of every bluebook judged
-      # before it. The parsed grammar is reused ; only the records are cleared.
-      # (During grammar_registry's own fixpoint judge this clear runs on the
-      # singleton mid-memoisation — harmless for the same reason : the grammar
-      # is what is kept, the records were never meant to survive a judging.)
-      # No `bind_runtime` here : judging dispatches by FQN and never opens the
-      # door, and binding would re-install the language's own facade constants
-      # once per judged chapter.
+      # A dispatcher over the shared grammar registry with its records
+      # cleared, so one bluebook's judging can never see another's records.
       #
       # @return [Runtime::Dispatcher] a dispatcher over the shared grammar
       #   registry, with its records cleared