hecks 2.7.0 → 2.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a91dfe0fb86ceb9bb96ecc6b08da680213fed526f49f922f1a2f66d9cb89c80e
-  data.tar.gz: 22fc90a2e361f45e27796248c22391997281e62fbfeec01b25ba35378e6e5681
+  metadata.gz: 66f85d62ad01467ff2ae17c6d3be63c706bea69a9e6f7b20839d9f5fc22234a5
+  data.tar.gz: 45413f0bd639bfe548ca9f8f7970d5136ed6aa30a25765870ca0212806af3c90
 SHA512:
-  metadata.gz: 824fd1d23971f6dacfd3c3ea18a35f5d0d61e7f07e2056b789d7be7d105a7bc47d13a61e0391d7aeb46d20bcfe8400e307bf05728ed10f9e4c69b46ac7d0df45
-  data.tar.gz: 3f6e4679c8187f212f913de1d17944c3bac2ed0e4385bcff3bcd259e1b6ccb49d6c8270c7f84885fcc3f308e9ca7def653341050c649d1a048b8a91228ee65e7
+  metadata.gz: b817baff1d4e990f1161080d23f9f10fadd2e1eb8a6f76b1ed551fe021992311f10d64f0eef63218e515905fa2757d879a607abc4b40ecfeb4d0d45a6011a8a6
+  data.tar.gz: '0819f496494a76afe81697f8a83301c07acef480b218501748616f1537f0c5d3c0148d67271dea0fd4eea6b6bcb9bbb278331a203883b3c169c08cd59f384451'

data/exe/hecks

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+# The `hecks` command the gem installs: run, read, check and serve a domain you
+# supply. `hecks` with no arguments lists the subcommands; `hecks <command> --help`
+# prints one's usage. The router is `Hecks::CLI` (lib/hecks/cli.rb).
+#
+# The gem's own `lib` goes first on the load path, as it does for the `bin/`
+# scripts, so this file also runs straight from a checkout.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "hecks/cli"
+
+exit Hecks::CLI.start(ARGV)

data/lib/hecks/adapters/driven/memory.rb

@@ -217,7 +217,7 @@ module Hecks
       #
       # @param id [Integer] the row id `outbox_enqueue` assigned
       # @return [Boolean] true when the row was pending and is now claimed; false when it is
-      #   unknown or no longer pending
+      #   unknown or not pending
       def outbox_claim(id) # rubocop:disable Naming/PredicateMethod
         row = @outbox.find { |held| held.id == id }
         return false unless row&.pending?

data/lib/hecks/adapters/driven/postgres.rb

@@ -247,7 +247,7 @@ module Hecks
       #   an update to apply; nil writes unconditionally. Ignored for a delete
       # @return [Runtime::Instance, PG::Result, nil] for a save, a new instance over the
       #   entry's state with `version` set to the stored `hecks_version`, or nil when
-      #   `expected_version` no longer matched and nothing was written; for a delete, the
+      #   `expected_version` did not match and nothing was written; for a delete, the
       #   `DELETE` statement's `PG::Result`
       # @raise [PG::Error] if the statement fails
       # rubocop:disable Metrics/AbcSize -- the CAS/plain upsert split is one

data/lib/hecks/adapters/driven/prism.rb

@@ -85,7 +85,7 @@ module Hecks
       # never edited out from under it), but wrong for anything that
       # legitimately reloads an edited file in-process: a stale cached
       # tree reports a `given`/`ensures` block at its old line number,
-      # which no longer matches the freshly re-executed file's own
+      # which does not match the freshly re-executed file's own
       # `block.source_location` — surfacing as "did not survive
       # extraction" on a perfectly valid file. Built for real building
       # `Hecks::Codemod` (lib/hecks/codemod.rb), which needs exactly this

data/lib/hecks/adapters/driven/sqlite/projection.rb

@@ -15,7 +15,7 @@ module Hecks
     # Rebuilds a read store from the authoritative journal, entry by entry.
     # A value object is written as its JSON object and a reference as the
     # bare id it holds — the same shapes the command path writes, so there
-    # is no second representation to accept here any more.
+    # is no second representation to accept here.
     class SqliteProjection < Sqlite
       # Replaces or deletes the read store's row for one journal entry, encoding the entry's
       # state directly rather than through a `Runtime::Instance`.

data/lib/hecks/adapters/driven/tenant_provisioner.rb

@@ -4,7 +4,7 @@ require "fileutils"
 
 module Hecks
   module Adapters
-    # THE IMPERATIVE HALF of provisioning a tenant, pulled out of
+    # The imperative half of provisioning a tenant, pulled out of
     # `bin/project_tenant` and behind a real driven port
     # (`Deploy::Tenant.port "TenantProvisioning"`) instead — the same
     # hexagonal reasoning `GithubChecks` already gives for its own
@@ -16,34 +16,55 @@ module Hecks
     # `PortOperationInterpreter#ask`'s own "every failure is an answer"
     # comment for why nothing here needs its own rescue.
     #
-    # DELIBERATELY DOES NOT BOOT THE TARGET DOMAIN — that step (proving
+    # ## What it leaves out
+    #
+    # Deliberately does not boot the target domain — that step (proving
     # it boots for real, running the tenant_capable? gate) stays in
-    # `bin/project_tenant` itself, called AFTER this operation answers,
+    # `bin/project_tenant` itself, called after this operation answers,
     # not nested inside it. Booting a whole domain from inside an
     # adapter method that is itself running mid-dispatch (this port
     # operation) is a real, separate concern from writing one file, and
     # keeping the two apart avoids a nested `Hecks.boot` call ever
     # running inside another boot's own dispatch call stack.
     #
-    # RETURNS A HASH SHAPED LIKE `Tenancy::Tenant.Register`'S OWN
-    # ARGUMENTS, on purpose — `tenancy.hecksagon`'s own `translates`
+    # ## Return shape
+    #
+    # Returns a hash shaped like `Tenancy::Tenant.Register`'s own
+    # arguments, on purpose — `tenancy.hecksagon`'s own `translates`
     # reaction forwards an answered event's payload verbatim, so this
-    # adapter's own return value IS the translation from Deploy's
+    # adapter's own return value is the translation from Deploy's
     # vocabulary into Tenancy's, decided here rather than in a mapping
     # layer neither side could see into.
     class TenantProvisioner
+      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
       def initialize(aggregate: nil, settings: {}, root: nil); end
 
-      # `directory:` IS REQUIRED, NOT DERIVED FROM `domain` — a real,
+      # Writes the tenant's environment overlay file under its domain directory.
+      #
+      # `directory:` is required, not derived from `domain` — a real,
       # confirmed bug found only under CI's own real-Postgres suite: a
-      # domain's own DECLARED NAME (`domain`, e.g. "Scratch") is not a
+      # domain's own declared name (`domain`, e.g. "Scratch") is not a
       # filesystem path, and File.expand_path(domain, Dir.pwd) silently
       # resolved to the wrong directory (relative to whatever the
-      # RUNNING PROCESS' own cwd happened to be) whenever the CLI's own
+      # running process' own cwd happened to be) whenever the CLI's own
       # `--domain=` value didn't happen to equal its own directory
       # argument by coincidence. `bin/project_tenant` passes its own
       # real `domain_directory` local straight through.
-
+      #
+      # Every argument arrives either bare or wrapped as `{ value: ... }`; both are read.
+      #
+      # @param slug [String, Hash] the tenant's slug, which names the overlay file
+      # @param domain [String, Hash] the declared domain name the overlay is for
+      # @param realm [String, Hash] the realm the overlay declares
+      # @param schema [String, Hash] the schema the overlay declares
+      # @param database [String, Hash] the database the overlay declares
+      # @param adapter [String, Hash] the persistence adapter the overlay declares
+      # @param directory [String, Hash] the domain's own directory on disk
+      # @return [Hash{Symbol => Object}] `:slug`, `:domain`, `:realm` and `:schema`, as given
       def provision(slug:, domain:, realm:, schema:, database:, adapter:, directory:)
         domain_directory = File.expand_path(directory[:value] || directory)
 

data/lib/hecks/behaviors/expectations.rb

@@ -228,7 +228,7 @@ module Hecks
       #   the dispatch's own result
       # @return [Hash{Symbol => Object}] the settled record's current state, read
       #   back from the repository; `result.state` (or `{}`) when the result has no
-      #   id or the repository no longer has that aggregate/record
+      #   id or the repository does not have that aggregate/record
       def settled_state(runtime, verb, result)
         return result.state || {} unless result.respond_to?(:id) && result.id
 
@@ -266,7 +266,7 @@ module Hecks
       # only so long as nothing else ever asked it to resolve a port-operation
       # verb. Now that a `policy` can legitimately `trigger` a port operation
       # (`ReactionInvocation#resolve_target`'s own port-operation branch),
-      # that raise no longer happens, so this checks directly instead.
+      # that raise does not happen, so this checks directly instead.
       #
       # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the suite's
       #   booted runtime

data/lib/hecks/bluebook/assembly/contract.rb

@@ -151,7 +151,7 @@ module Hecks
       #                         Entity's contract claims `owner: :parent`
       #
       # `shape` and `handler` are not on this list — S17 (ADR 0026) made Member and
-      # Dispatch nested entities, so neither is a parent field any more the way
+      # Dispatch nested entities, so neither is a parent field the way
       # `owner` is. `spec/assembly_spec` derives this set from `Plan` and the
       # contracts directly and fails on any drift, rather than trusting this list to
       # stay in sync with a second hand-written copy kept by the model generator.

data/lib/hecks/bluebook/assembly/contracts.rb

@@ -243,7 +243,7 @@ module Hecks
 
         # S17, ADR 0026 — Handler is a genuine entity now, nested under
         # ProcessManager (`entity "Handler"`, reaction.bluebook). Neither
-        # `position` nor `handler` is a stored field any more: a saga
+        # `position` nor `handler` is a stored field: a saga
         # answers each event once, so `event_type` is Handler's own real,
         # non-positional identity (no walk-minted `position` to derive),
         # and the process manager it belongs to is structural now — which
@@ -429,10 +429,10 @@ module Hecks
         # A member's pairs are an open map, which is why Member is its own root in
         # the language. The IR keeps them as a plain hash on the value object, so
         # they are assembled with their shape rather than as a construct.
-        # S17, ADR 0026 — Member is a genuine entity now, nested under
-        # ValueObject (`entity "Member"`, shape.bluebook). It no longer
-        # holds a `shape` field at all (that was the free-text, un-parsed
-        # spelling a standalone root once needed ; an entity's element is
+        # S17, ADR 0026 — Member is a genuine entity, nested under
+        # ValueObject (`entity "Member"`, shape.bluebook). It holds no
+        # `shape` field at all (a free-text, un-parsed spelling would suit
+        # only a standalone root ; an entity's element is
         # never serialized as text) — only `position` (walk-minted, see
         # `entity_own_identity`, judge.rb) and `pairs` (still an open map,
         # still one row per entry, still why a value object cannot hold it

data/lib/hecks/bluebook/assembly/specializer.rb

@@ -21,8 +21,8 @@ module Hecks
       module Specializer
         module_function
 
-        # S17, ADR 0026 — `Handler` is a genuine entity now, nested under
-        # `ProcessManager`, so `.aggregate` alone no longer finds it —
+        # S17, ADR 0026 — `Handler` is a genuine entity, nested under
+        # `ProcessManager`, so `.aggregate` alone does not find it —
         # it hangs off some aggregate's own `.entities` instead
         # (searched recursively, the same reason `Value::Coercion#find_
         # entity` does: a nested entity, like `Dispatch` inside

data/lib/hecks/bluebook/assembly.rb

@@ -31,7 +31,7 @@ module Hecks
     # ## What stays hand-written
     #
     # The containment — which construct holds which — stays hand-written; it is
-    # not a field table. The runtime surface is no longer built here at all — the
+    # not a field table. The runtime surface is not built here at all — the
     # door is a per-boot projection, facade/surface.rb.
     class Assembly
       # Builds the graph the runtime runs from one chapter's declared hash.

data/lib/hecks/bluebook/behaviour/chapter.rb

@@ -91,15 +91,18 @@ module Hecks
           @ports_by_name[port.name] = port
         end
 
-        # A TRANSLATED REACTION IS ALSO DECLARED IN THE HECKSAGON —
+        # A translated reaction is also declared in the hecksagon —
         # `HecksagonBuilder#translates` builds an ordinary `Policy` (same
         # shape, same `PolicyInterpreter` runtime, as one written inside a
         # `policy` block in this chapter's own `.bluebook`) and attaches it
         # here, after the chapter already exists, the same reasoning
         # `add_port` gives one method up. Kept out of the bluebook itself
-        # on purpose: which FOREIGN domain's event this chapter reacts to
+        # on purpose: which foreign domain's event this chapter reacts to
         # is a wiring/context-mapping decision, not a fact the domain
         # states about its own model.
+        #
+        # @param policy [Bluebook::Policy] the translated reaction to attach
+        # @return [Array<Bluebook::Policy>] this chapter's policies, with `policy` appended
         def add_policy(policy)
           @policies << policy
         end

data/lib/hecks/bluebook/behaviour/read_model.rb

@@ -9,6 +9,24 @@ module Hecks
         # @return [Array<Symbol>] each declared `group_by` field's name, in declaration order
         def group_by_fields = @group_by.map { |row| row[:field].to_sym }
 
+        # Reports whether this read model's `group_by` names every identity head
+        # of the aggregate it groups (ADR 0061, decision D1).
+        #
+        # Such a key path cannot be shared by two rows, so it is accepted from the
+        # declaration alone and never checked for a collision at dispatch. Any
+        # other key path is checked per request.
+        #
+        # @param aggregate [Bluebook::Aggregate, nil] the aggregate of this read
+        #   model's one many-side head
+        # @return [Boolean] false when `aggregate` is nil or declares no identity,
+        #   since uniqueness cannot then be shown
+        def groups_by_identity?(aggregate)
+          return false unless aggregate
+
+          identity = Array(aggregate.identity_heads).map(&:to_sym)
+          !identity.empty? && (identity - group_by_fields).empty?
+        end
+
         # `!!` rather than a bare `@count` — the DSL/reconstruction
         # boundary (ReadModel#initialize) already normalises to
         # `true`/`nil`, so this is belt and braces against a future

data/lib/hecks/bluebook/capabilities.rb

@@ -19,11 +19,11 @@ module Hecks
       # Who may sign in, and with what role — rust/host's Google-OAuth
       # provision/member_rows resolve this instead of an env var naming
       # the aggregate (HECKS_MEMBERSHIP_AGGREGATE). Same declared-
-      # not-named shape AUTHORIZATION already is for Governance.
+      # not-named shape `AUTHORIZATION` already is for Governance.
       MEMBERSHIP = "membership".freeze
       # A stable organizational identity, independent of how it was
       # authenticated — recognised by declaration, not the literal name
-      # "Identity". Same declared-not-named shape AUTHORIZATION already
+      # "Identity". Same declared-not-named shape `AUTHORIZATION` already
       # is. rust/host does not build this chapter's payloads; any field
       # mapping lives on the consuming hecksagon's `translates` ACL.
       IDENTITY = "identity".freeze

data/lib/hecks/bluebook/chapter.rb

@@ -4,7 +4,7 @@ require_relative "../ir"
 
 module Hecks
   module Bluebook
-    # The chapter, and no longer the namespace it lives in.
+    # The chapter, which is not the namespace it lives in.
     #
     # `Hecks::Bluebook` was briefly a class, because dropping the
     # old `IR::` segment would otherwise have produced

data/lib/hecks/bluebook/dsl/aggregate_builder.rb

@@ -198,7 +198,7 @@ module Hecks
         # never `[]`). Wave 6 (identity-and-relationships arc) un-deprecates
         # all three for real: a relationship word now retains the author's
         # domain concept in IR — still stored as one or more target
-        # identities, but no longer collapsed to a bare `reference_to`
+        # identities, but not collapsed to a bare `reference_to`
         # during assembly. `MetaValidator.shadow_parsing?` still routes to
         # `legacy_has_many`/`legacy_has_one` so frozen era text written
         # under the old (lying/collapsing) meaning still parses the way it
@@ -511,7 +511,7 @@ module Hecks
         # are this construct's own refusal wording, not shared, since
         # `declared_by:` only exists here so far. Unresolved (no
         # candidate yet, or `declared_by:` naming an aggregate that
-        # hasn't declared it yet) is no longer a fourth branch that
+        # hasn't declared it yet) is not a fourth branch that
         # raises here — see `#pending_chapter_given`, below, for why:
         # a chapter split across files can genuinely reference a
         # precondition a later file declares, and "not found among

data/lib/hecks/bluebook/dsl/binding_proxy.rb

@@ -77,7 +77,7 @@ module Hecks
         end
 
         def method_missing(verb, *args, **kwargs, &block)
-          # A BARE CALL — no args, no kwargs, no block — starts (or
+          # **A bare call** — no args, no kwargs, no block — starts (or
           # continues, on `AttributePath` itself below) a Privacy
           # marking chain: `Registration.attendee.medications.has_phi(
           # readable_by: "Privacy officer")`. No existing real
@@ -115,10 +115,15 @@ module Hecks
           @path = path
         end
 
+        # Records a `has_<category>` marking, or extends the attribute path by one segment.
+        #
         # @param verb [Symbol] `has_<category>` to record the marking and end the chain;
         #   any other bare name to extend the path one segment further
         # @param readable_by [String] required only for a `has_<category>` call — the
         #   Governance role a read must hold to see this field unredacted
+        # @param args [Array] must be empty; a positional argument is refused
+        # @param kwargs [Hash] must be empty; any keyword but `readable_by:` is refused
+        # @param block [Proc, nil] must be absent; a block is refused
         # @return [Bluebook::DSL::AttributePath, nil] a longer chain for a plain segment;
         #   `nil` (nothing further to chain) for a `has_<category>` call
         # @raise [Malformed] if a `has_<category>` call omits `readable_by:`, or any call

data/lib/hecks/bluebook/dsl/bluebook_builder.rb

@@ -431,9 +431,9 @@ module Hecks
         #   manager's own structural check fails
         def self.build(name, version: nil, &block)
           registry = Hecks.current_registry
-          # WHICH FILE CALLED `Hecks.bluebook`, recorded for
+          # Which file called `Hecks.bluebook`, recorded for
           # `Registry#record_bluebook_source` — two frames up: this
-          # method's own caller is `Hecks.bluebook` (hecks.rb), and ITS
+          # method's own caller is `Hecks.bluebook` (hecks.rb), and its
           # caller is the real `.bluebook` file's own top-level call site.
           caller_location = caller_locations(2, 1)&.first
           registry&.record_bluebook_source(name, caller_location&.path)

data/lib/hecks/bluebook/dsl/entity_builder.rb

@@ -243,7 +243,7 @@ module Hecks
         # since ADR 0028, `command` only queues a descriptor and actually
         # builds at `#drain_pending!` time, well after this whole block
         # (including every `given` in it) has already run, so textual
-        # order within the block no longer actually matters here; named
+        # order within the block does not actually matter here; named
         # for the reader anyway, since `given`'s own resolution logic
         # (`CommandBuilder#reference_named_given`) still reads whatever
         # `@named_givens` holds at the command's own build time, not by

data/lib/hecks/bluebook/dsl/generic_dispatch.rb

@@ -8,7 +8,7 @@ module Hecks
       # already shipped) only checks a word's admissibility; this module
       # executes the safe, mechanical subset of what a word actually
       # does, read live off the same self-hosted grammar table — so a
-      # builder method for one of these words no longer needs to be
+      # builder method for one of these words need not be
       # hand-written at all. Called from `WordGate#method_missing`'s own
       # "admitted here, no builder method for it yet" branch, so it only
       # ever sees a word whose (context, word) pair the grammar already

data/lib/hecks/bluebook/dsl/hecksagon_builder.rb

@@ -31,7 +31,7 @@ module Hecks
           @translates         = []
         end
 
-        # Marks THIS chapter as a bounded context — a consumer-owned chapter
+        # Marks this chapter as a bounded context — a consumer-owned chapter
         # that `uses_framework` / `uses_embryonaut_bluebook` will not load.
         # Framework and vendored packages get the mark automatically from
         # those words; they never write `bounded` in their own bluebooks.
@@ -158,12 +158,12 @@ module Hecks
           bluebook_ir.add_port(built)
         end
 
-        # A TRANSLATION BOUNDARY, NOT A BUSINESS RULE — `translates "Name"
+        # A translation boundary, not a business rule — `translates "Name"
         # do on Foreign::Domain::SomeEvent; trigger Local.Command; end`
-        # builds the EXACT SAME `Policy` a `policy` block inside this
+        # builds the exact same `Policy` a `policy` block inside this
         # domain's own `.bluebook` would (same `on_impl`/`trigger_impl`,
         # same `PolicyInterpreter` runtime — reusing `PolicyBuilder`
-        # directly, zero new runtime semantics). What's new is only WHERE
+        # directly, zero new runtime semantics). What's new is only where
         # it can be written: a cross-domain reaction is a wiring/context-
         # mapping decision (this chapter conforming to a foreign chapter's
         # published event), the same kind of decision `port`/
@@ -171,23 +171,28 @@ module Hecks
         # model states about itself, which `policy` (inside the bluebook)
         # remains the right word for.
         #
-        # MUST BE A BLOCK, not `translates Event, into: Command` — a flat
-        # call's arguments are evaluated eagerly, under THIS builder's own
+        # Must be a block, not `translates Event, into: Command` — a flat
+        # call's arguments are evaluated eagerly, under this builder's own
         # `ConstShim` resolver (`BindingProxy.namespace`, set up by
-        # `self.build` below), which mints a `BindingProxy` INSTANCE per
+        # `self.build` below), which mints a `BindingProxy` instance per
         # segment and cannot answer a further `::` (it is not a Module) —
         # a multi-segment reference like `Deploy::Tenant::TenantProvisioned`
         # would raise before this method ever ran. `port_impl`'s own
         # `ConstShim.with(->(const) { const })` swap only works because
         # its own callers never pass a multi-segment bare constant as an
         # eagerly-evaluated argument — everything of that shape lives
-        # inside ITS block, evaluated later, under the swapped resolver.
+        # inside its block, evaluated later, under the swapped resolver.
         # A block defers evaluation the same way; a flat call cannot.
+        #
+        # @param name [String, Symbol] the reaction's name
+        # @yield the `on`/`trigger` block, evaluated later under the scoped resolver
+        # @return [Array<Bluebook::Policy>] the chapter's policies, with the new one appended
+        # @raise [Malformed] if no bluebook is registered for this domain to attach the reaction to
         def translates(name, &block)
           bluebook_ir = Hecks.current_registry.bluebook(@domain) or
             raise Malformed, "#{@domain} declares no such bluebook — translates needs one to attach its reaction to"
 
-          # SAME RESOLVER BluebookBuilder ITSELF uses for a `policy`
+          # Same resolver BluebookBuilder itself uses for a `policy`
           # block's own `on`/`trigger` (bluebook_builder.rb) — a
           # `ScopedConstant`, not the bare passthrough `port_impl` swaps
           # to, because `on`/`trigger` here take genuinely multi-segment

data/lib/hecks/bluebook/dsl/rule_reference.rb

@@ -147,8 +147,8 @@ module Hecks
                   .find { |rule| rule.description == description }
         end
 
-        # **Which construct uses which primitive** — no longer a Ruby-only
-        # Hash (that was this constant's own shape, one round ago): the
+        # **Which construct uses which primitive** — not a Ruby-only
+        # Hash, because the
         # user's own correction — "my goal is that if they read the same
         # table they behave identically" — means a table only Ruby ever
         # reads cannot deliver that, no matter how faithfully it is
@@ -172,7 +172,7 @@ module Hecks
         # after `grammar_registry` is fully built and memoized, so reads
         # the real table, every time, no exception.
         #
-        # No longer kept in sync by hand — the same `resolves_via`/
+        # Not kept in sync by hand — the same `resolves_via`/
         # `disambiguator` columns, projected ahead of time into the
         # committed lib/hecks/bluebook/dsl/bootstrap_table.rb
         # (bin/project_bootstrap_table, pinned by spec/bootstrap_table_spec.rb).

data/lib/hecks/bluebook/dsl/translation_builder.rb

@@ -268,7 +268,7 @@ module Hecks
       # Parses a whole `.translation` file into a `Translation` — the
       # domain's own `from:`/`to:` era pair, its list of `aggregate`
       # translation blocks (each built by `TranslationAggregateBuilder`
-      # above), and any `retired` aggregates that no longer exist in the
+      # above), and any `retired` aggregates that do not exist in the
       # destination era.
       class TranslationBuilder
         GRAMMAR_CONTEXT = "Translation".freeze

data/lib/hecks/bluebook/dsl/world_builder.rb

@@ -13,6 +13,11 @@ module Hecks
 
         # A call with a block records the block's own settings as a nested Hash, so a bind can
         # group settings (`preview do ... end`); a call without one records its argument.
+        #
+        # @param key [Symbol] the setting's name, recorded verbatim
+        # @param args [Array] the setting's value: one argument is kept as is, several as an array
+        # @param block [Proc, nil] a nested settings block, evaluated on a fresh collector
+        # @return [Object] the value recorded under `key`
         def method_missing(key, *args, &block)
           @values[key.to_sym] =
             if block

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

@@ -302,7 +302,7 @@ module Hecks
         end
 
         # Entity-owned categories have no top-level aggregate for the runtime
-        # to route a bare verb into any more — `Member`'s own "Pair" reaches
+        # to route a bare verb into — `Member`'s own "Pair" reaches
         # the runtime as `ValueObject.Member.Pair`, and a nested one
         # (`Dispatch`, inside `Handler`) reaches it as `ProcessManager.
         # Handler.Dispatch.Bind` — the dotted shape `EntityInterpreter#call`
@@ -567,8 +567,8 @@ module Hecks
         #   Reference  its type is Reference<X>, another aggregate's head
         #   Holds      its type names an entity this aggregate declares
         #
-        # Nothing is skipped any more. Reference and Holds did not exist, so the
-        # walk dropped both kinds and the meta-domain silently did not contain
+        # Nothing is skipped. Without Reference and Holds the walk would drop
+        # both kinds and the meta-domain would silently not contain
         # Account#customer_id or Account#ledger.
         # Each alternate carries its own map, read from the language. Borrowing the
         # primary's map dispatched `type:` where Reference declares `points_at:`,

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

@@ -108,7 +108,7 @@ module Hecks
             # S17, ADR 0026 — Member/Handler/Dispatch are entities now
             # (`entity "Member" do ... end`, nested under `ValueObject`/
             # `ProcessManager`/`Handler`), not their own top-level
-            # aggregates — so `meta.aggregates` alone no longer finds
+            # aggregates — so `meta.aggregates` alone does not find
             # them the way it always found a standalone `aggregate
             # "Member"`. Each still needs its own named category here:
             # `Assembly::Contracts` keeps a bespoke entry for each
@@ -125,8 +125,8 @@ module Hecks
             # itself ever declares are exactly the three this ADR
             # names. `entity_owned: true` records why this is a
             # category at all — the real runtime has no top-level
-            # aggregate named "Member" to dispatch a bare verb into
-            # any more, so the judge has to build a dotted one instead
+            # aggregate named "Member" to dispatch a bare verb into,
+            # so the judge has to build a dotted one instead
             # (see `Judge#verb_for`).
             #
             # Recurses — `Dispatch` nests inside `Handler`, which nests
@@ -158,7 +158,7 @@ module Hecks
         # Every verb the language declares, spelled as the judge would
         # dispatch it. S17, ADR 0026 — an entity-owned category (its
         # own `entity_owned` flag) has no real top-level aggregate the
-        # runtime can route a bare verb into any more, so it is
+        # runtime can route a bare verb into, so it is
         # spelled dotted here too — `Bluebook::ValueObject.Member.
         # Declare`, `Bluebook::ProcessManager.Handler.Dispatch.Bind` —
         # matching `Judge#verb_for`/`#dotted_prefix`'s own build

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

@@ -364,7 +364,7 @@ module Hecks
           # same way Shapes#provenance reads it back.
           return encode_literal(node.provenance) if field == :provenance
 
-          # `identified_by` is no longer a field of any declaration — it is a list,
+          # `identified_by` is not a field of any declaration — it is a list,
           # filled by Identify one part at a time, so it is read through `identity_rows`
           # like every other list rather than special-cased here. What this branch
           # existed to protect is now structural : a path cannot come back as its head,

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

@@ -228,7 +228,7 @@ module Hecks
         # by its own dotted `ValueObject.Member.Pair`. Its data therefore
         # lives inline on the value object's own dispatched state — same as
         # any other entity list — not behind a separate `DeclaredIn` query:
-        # there is no such query any more, because there is no top-level
+        # there is no such query, because there is no top-level
         # "Member" aggregate left to hold one. Pairs are still an open map,
         # which no value object can hold, so they still come back one pair
         # at a time.
@@ -330,7 +330,7 @@ module Hecks
         # Handler.Dispatch`/`...Dispatch.Bind`. Its data therefore lives
         # inline on the process manager's own dispatched state — same as
         # any other entity list — not behind a separate `DeclaredIn`
-        # query : there is no such query any more, the same fix
+        # query : there is no such query, the same fix
         # `Reconstruction#members_of` already made for Member.
         def process_manager(row)
           declaration("ProcessManager", row,

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

@@ -32,7 +32,7 @@ module Hecks
             default:      decode_literal(text(field[:default])),
             # Read back the same way `list` is — both are booleans about the
             # attribute, held as text, and dropping either would rebuild a
-            # bluebook that no longer says what it said.
+            # bluebook that says something other than what was written.
             optional:     text(field[:optional]).to_s == "true",
             pattern:      presence(text(field[:pattern])),
             # The round trip is the only way in. The grammar registry keeps the

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

@@ -1,5 +1,6 @@
 require "digest"
 require "fileutils"
+require_relative "../../cache_dir"
 
 module Hecks
   module Bluebook
@@ -145,13 +146,10 @@ module Hecks
         #
         # 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).
+        # (`postgres_io_relevant_changed`'s own header). A missing file, a corrupt
+        # Marshal blob, a permission error or an unwritable cache directory degrades
+        # to "no disk cache today", never to a crash or a served-but-wrong table.
+        # The cache lives under `Hecks::CacheDir`, never the gem's read-only directory.
         #
         # **Atomic write, not a lock** — `qa_sweep --all` spawns up to 4
         # children at once, any of which could reach a cold cache
@@ -166,7 +164,10 @@ module Hecks
         # 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
+        #
+        # @return [String] the directory cache entries are written to:
+        #   `hecks_syntax_boot_cache` under `Hecks::CacheDir`
+        def cache_dir = Hecks::CacheDir.path("hecks_syntax_boot_cache")
 
         # Reports whether the cross-process disk cache is turned on.
         #
@@ -203,7 +204,7 @@ module Hecks
           return unless disk_cache_enabled?
 
           path = disk_cache_path(chapters)
-          FileUtils.mkdir_p(CACHE_DIR)
+          FileUtils.mkdir_p(cache_dir)
           tmp_path = "#{path}.#{Process.pid}.tmp"
           File.binwrite(tmp_path, Marshal.dump(result))
           File.rename(tmp_path, path)
@@ -217,7 +218,7 @@ module Hecks
         #   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")
+          File.join(cache_dir, "#{disk_cache_key(chapters)}.marshal")
         end
 
         # Builds the cache key for `chapters`.