hecks 1.3.0 → 1.4.0

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

@@ -1,25 +1,28 @@
+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`/
+      # **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`
+      # 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
+      # (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, 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
+      # 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.
       #
@@ -29,7 +32,7 @@ module Hecks
       #
       # 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 +43,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,7 +72,7 @@ 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.
@@ -77,7 +80,12 @@ module Hecks
           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
@@ -90,14 +98,118 @@ 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
+
+        def disk_cache_enabled? = ENV["HECKS_SYNTAX_BOOT_CACHE"] != "off"
+
+        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
+
+        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
+
+        def disk_cache_path(chapters)
+          File.join(CACHE_DIR, "#{disk_cache_key(chapters)}.marshal")
+        end
+
+        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.
+        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
+
         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.
@@ -119,7 +231,7 @@ module Hecks
           { value: text.to_s }
         end
 
-        # ABSENT STAYS ABSENT. A seed row's own optional columns ("was",
+        # 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
@@ -131,7 +243,7 @@ module Hecks
           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
@@ -141,15 +253,17 @@ module Hecks
         # by anything this boot does.
         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
+        # `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`)
@@ -194,12 +308,12 @@ 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.
         def all_rows(bluebook, name)
           seed_chapters(bluebook).flat_map { |chapter| rows(chapter, name) }
@@ -226,7 +340,7 @@ 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.

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
@@ -35,9 +35,9 @@ 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
@@ -65,13 +65,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,7 +3,7 @@ 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.
@@ -51,14 +51,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 —