hecks 2.8.0 → 2.9.0

data/lib/hecks/framework/bluebook/identity.bluebook

@@ -1,20 +1,13 @@
 Hecks.bluebook "Identity" do
   vision "Authentication proves an identifier; the organization decides what that identity means."
-  # S13, ADR 0025 (coverage standard) — GENERIC, not `supporting`: an
-  # OIDC-shaped external identifier is the textbook generic subdomain
-  # (Vernon's own example of one), off-the-shelf and buyable —
-  # `Governance` (role/scope RBAC beside it) stays `supporting`
-  # instead, since ITS OWN model is bespoke to this codebase's actor/
-  # role/scope shape, not a drop-in replaceable concept the way an
-  # identity provider is.
+  # Generic, not `supporting`: an OIDC-shaped external identifier is the textbook generic
+  # subdomain. Governance's role/scope RBAC is bespoke to this codebase, so it stays
+  # `supporting` (ADR 0025).
   generic
 
-  # WHAT THIS CHAPTER ANSWERS FOR EVERY DOMAIN THAT ATTACHES IT. Same
-  # declared-not-named shape Governance's own `provides "authorization"`
-  # already is. rust/host does not build this chapter's payloads — any
-  # field mapping lives on the consuming hecksagon's `translates` ACL
-  # (any field; this chapter does not list which). Link's reference is
-  # `identity`, not `identity_id` and not `to:`.
+  # What this chapter answers for every attaching domain, declared rather than named as
+  # Governance's `provides "authorization"` is. Field mapping lives on the consuming
+  # hecksagon's `translates` ACL; Link's reference is `identity`, not `identity_id` or `to:`.
   provides "identity",
            register: "Identity.Register",
            link:     "ExternalIdentifier.Link",
@@ -32,10 +25,8 @@ Hecks.bluebook "Identity" do
       invariant("an identity id is present") { !value.to_s.empty? }
     end
 
-    # No natural key exists for "a newly recognized identity" — the
-    # caller mints identity_id via Ports::IdentityGeneration.uuid
-    # before dispatching (see spec/ports/identity_generation_spec.rb),
-    # the same pattern proven there against Pizzas.
+    # No natural key exists for a new identity: the caller mints `identity_id` via
+    # `Ports::IdentityGeneration.uuid` before dispatching.
     command "Register" do
       role "Identity registrar"
       goal "Recognize an identity"
@@ -70,9 +61,7 @@ Hecks.bluebook "Identity" do
       invariant("a subject is present") { !value.to_s.empty? }
     end
 
-    # `key` is deliberately not derived here — a caller-side concern
-    # (e.g. SHA256 of issuer+subject), same as any other identity
-    # field this domain never mints itself.
+    # `key` is not derived here; the caller derives it (e.g. SHA256 of issuer+subject).
     command "Link" do
       role "Identity registrar"
       goal "Associate an external authenticated subject with an identity"
@@ -85,12 +74,8 @@ Hecks.bluebook "Identity" do
       emits ExternalIdentifierLinked
     end
 
-    # THE OIDC-SHAPED LOOKUP — a token hands over `(issuer, subject)`,
-    # never the `key` this aggregate is actually identified by (`key`
-    # is a caller-side derivation, deliberately not reproduced here —
-    # see `Link`'s own comment). `identity` rides the row already,
-    # from `reference_to Identity` above, so a caller reads it straight
-    # off the match rather than needing a second query.
+    # The OIDC-shaped lookup: a token hands over `(issuer, subject)`, never `key`. `identity`
+    # rides the row from `reference_to Identity`, so no second query is needed.
     query "ResolvedBy" do
       description "The external identifier linked to this exact (issuer, subject) pair, if any."
       attribute :issuer,  Issuer

data/lib/hecks/framework/bluebook/privacy.bluebook

@@ -2,12 +2,7 @@ Hecks.bluebook "Privacy" do
   vision "Which fields of a domain's own aggregates are sensitive is a fact about that domain, declared apart from it — the domain itself never spells out that one of its own attributes is PII or PHI."
   supporting
 
-  # A DOMAIN ATTACHING THIS NEVER MARKS ITSELF — `Mark`'s `role
-  # "Deployment"` matches every other wiring-time command in this
-  # codebase (`Hecksagon::UsesFramework`, `Tenancy::Tenant.Register`):
-  # something outside the domain's own bluebook decides a field is
-  # sensitive, the same way persistence binds are a wiring decision
-  # and not baked into an aggregate's own declaration.
+  # A domain never marks itself: `Mark` is a wiring-time command (role "Deployment").
   aggregate "Marking" do
     description "One attribute of one domain's own aggregate, flagged sensitive — and the role required to read it unredacted."
 
@@ -23,20 +18,13 @@ Hecks.bluebook "Privacy" do
       invariant("a marking names the domain it applies to") { !value.to_s.empty? }
     end
 
-    # DOTTED, same convention Forms' own `Field#path` and a query's
-    # cross-object `where` clause already use — `"attendee.medications"`,
-    # not a bare leaf name, so a marking can reach into a nested value
-    # object rather than only a top-level attribute.
+    # Dotted, e.g. "attendee.medications", so a marking can reach a nested value object.
     value_object "AttributePath" do
       attribute :value, String
       invariant("a marking names an attribute path") { !value.to_s.empty? }
     end
 
-    # OPEN-ENDED ON PURPOSE — "pii", "phi", whatever else a consuming
-    # domain finds itself needing, none of it enumerated here. This
-    # bluebook is the mechanism (mark, gate, redact); it does not also
-    # own the vocabulary of sensitivity categories that exist in the
-    # world.
+    # Open-ended on purpose ("pii", "phi", ...): this bluebook does not own the vocabulary.
     value_object "Category" do
       attribute :value, String
       invariant("a marking is categorized") { !value.to_s.empty? }
@@ -75,15 +63,8 @@ Hecks.bluebook "Privacy" do
     end
   end
 
-  # **Cryptoshredding** — a right-to-erasure request satisfied without
-  # rewriting or deleting a single event. `key_reference` is an opaque
-  # handle a caller obtains from `Ports::KeyVault.issue` before
-  # dispatching `Issue`, the same "nothing is minted inside a bluebook"
-  # convention `Identity::Register`'s own `identity_id` and
-  # `Delivery::Record`'s own `message_id` already hold to (the
-  # expression sublanguage cannot call a port at all). The key material
-  # itself never appears here or on any emitted event — only the fact
-  # that a reference exists, and the fact that it was destroyed.
+  # Cryptoshredding: erasure without rewriting events. `key_reference` is an opaque handle
+  # from `Ports::KeyVault.issue`, obtained before `Issue`; key material never appears here.
   aggregate "SubjectKey" do
     description "One data subject's own encryption key, from the moment it exists to the moment it is destroyed."
 
@@ -108,9 +89,7 @@ Hecks.bluebook "Privacy" do
       invariant("a key carries the vault's own opaque reference to it") { !value.to_s.empty? }
     end
 
-    # `Shred`'s own guard against running twice — the same mechanism
-    # `Compliance::PrivacyReview`'s `Clear`/`Escalate` already use rather
-    # than an optional timestamp plus a hand-written `given`.
+    # Guards `Shred` against running twice.
     lifecycle :status, default: "active" do
       transition "Shred" => "shredded", from: "active"
     end
@@ -130,12 +109,8 @@ Hecks.bluebook "Privacy" do
       emits SubjectKeyIssued
     end
 
-    # **Records destruction, never performs it** — the actual
-    # `Ports::KeyVault.destroy` call happens in driving-side code before
-    # this is ever dispatched, the same boundary `send_issue.rb` draws
-    # around `Delivery::Record` for an already-sent email. This
-    # command's own job is to make an already-irreversible fact
-    # durable, not to cause it.
+    # Records the destruction, never performs it: `Ports::KeyVault.destroy` runs in
+    # driving-side code before this is dispatched.
     command "Shred" do
       role "Privacy officer"
       goal "Mark this subject's key destroyed, so its ciphertext is recorded as permanently unrecoverable"

data/lib/hecks/framework.rb

@@ -1,67 +1,12 @@
 require_relative "runtime/registry"
 
 module Hecks
-  # **The registry of framework bluebooks** — Governance, Identity, and
-  # whatever lands beside them in `lib/hecks/framework/bluebook/`:
-  # domain-agnostic chapters no single example owns, shared by reference
-  # rather than copied into every domain that wants one.
-  #
-  # ## Where it lives
-  #
-  # Under `lib/`, not a top-level sibling — a real consumer (embryonaut)
-  # vendors only `lib/` (`bin/vendor-hecks`, and this gem's own
-  # `hecks.gemspec`, both glob `lib/**/*`), so a `framework/`
-  # sitting beside `lib/` rather than inside it packaged and vendored
-  # cleanly but left `uses_framework` finding nothing at runtime —
-  # `Framework::ROOT` pointed at a directory that simply never shipped.
-  # Nothing in this repo's own suite caught it, since every spec here
-  # reads the working tree directly; only vendoring into a real consumer
-  # did. Same reasoning `lib/hecks/language/bluebook/` already
-  # settled for the self-hosted grammar's own `.bluebook` files —
-  # non-Ruby data a module owns lives inside `lib/` with the code that
-  # reads it, not beside it.
-  #
-  # ## Derived, not hand-listed
-  #
-  # Derived from the directory, not hand-listed a second time — the same
-  # reasoning `Assembly::CONTRACTS` gives for reading the language's own
-  # fields from a table instead of restating them: a member added here
-  # and forgotten in a list would be a member `uses_framework` could
-  # never find, and a hand-kept list is exactly the shape that goes
-  # stale in silence. `spec/corpus_spec.rb`'s own `FRAMEWORK_MEMBERS`
-  # glob is the precedent this mirrors.
-  #
-  # ## Naming
-  #
-  # Named by file stem, capitalized — `governance.bluebook` holds
-  # `Hecks.bluebook "Governance"`, the same one-to-one spelling every
-  # other chapter in this codebase already keeps between its filename
-  # and its declared name.
+  # Registry of framework bluebooks (Governance, Identity, ...) in `lib/hecks/framework/bluebook/`.
+  # Members are derived from the directory and named by capitalized file stem.
   module Framework
-    # Loaded from its own real path, always — never a copy. A domain
-    # booted through `Fuzzing::IsolatedBoot`'s tmp-directory copy still
-    # reaches the same `framework/bluebook/governance.bluebook` this
-    # constant points at, because `uses_framework` runs `Kernel.load`
-    # against `ROOT`, not against anything inside the copied domain
-    # directory — there is nothing here for a relocated copy to break,
-    # the way a symlink carried along with the copy would.
-    #
-    # Only the bluebook — a framework member's own `.hecksagon`, if it
-    # has one, is not auto-loaded. Persistence is a wiring decision, the
-    # same as any other aggregate's, and belongs to whoever is doing the
-    # deploying, not to a default baked into the framework member
-    # itself: a consuming app needs `Governance::RoleAssignment` durable
-    # (Postgres, say), and a framework member hard-coding Memory for its
-    # own specs would silently make that decision for every app that
-    # attaches it. The consuming app declares its own, separate
-    # `Hecks.hecksagon "Governance" do ... end` block for that — not
-    # binds folded into its own hecksagon, which would build but never
-    # resolve: `Ports::Persistence::BindingPolicy.resolve` looks up
-    # `registry.hecksagon` by the aggregate's own domain name, not the
-    # domain doing the binding, the one invariant this runtime holds
-    # everywhere else too. See `examples/banking/bluebook/banking.hecksagon`
-    # for the pattern — a real `.hecksagon` file can hold more than one
-    # `Hecks.hecksagon` call, one per domain it wires.
+    # Directory the members load from, never a copy, so relocated domain copies still resolve.
+    # Lives under `lib/` because consumers vendor only `lib/`.
+    # Only the bluebook loads: persistence is the consumer's own `Hecks.hecksagon` block.
     ROOT = File.expand_path("framework/bluebook", __dir__).freeze
 
     # Every framework member available to attach, by declared name.
@@ -74,11 +19,7 @@ module Hecks
       end
     end
 
-    # Every member whose own bluebook declares `provides capability` —
-    # read off the member's real IR (each loaded into a scratch registry,
-    # never the caller's), not off its name. Used where a check needs to
-    # say which member would satisfy it (`refuse_ungoverned_roles!`'s own
-    # suggestion, `Fuzzing::TargetCapabilities`).
+    # Every member whose bluebook declares `provides capability`, read from its IR, not its name.
     #
     # @param capability [String, Symbol] the capability name to look for
     # @return [Array<String>] the names of every framework member that provides it,
@@ -101,9 +42,7 @@ module Hecks
       lib = File.expand_path("..", __dir__)
       registry = Runtime::Registry.new
       Hecks.with_registry(registry) do
-        # The same four a chapter needs to build at all (a predicate's
-        # source is recovered through the extraction port) — the seed
-        # `Grammar#grammar_chapters` and `bin/model_check` use.
+        # A chapter needs these four to build (predicate source is recovered via extraction).
         Kernel.load(File.join(lib, "hecks/ports/persistence.port"))
         Kernel.load(File.join(lib, "hecks/ports/extraction.port"))
         Kernel.load(File.join(lib, "hecks/adapters/driven/memory.adapter"))
@@ -113,18 +52,10 @@ module Hecks
       registry.bluebook(name.to_s)
     end
 
-    # Idempotent, per registry — `uses_framework` is now called more than
-    # once for the same member within a single boot (S8: a domain
-    # attaching Governance for its own role check, plus a framework
-    # sibling attaching it too, e.g. `banking.hecksagon`'s Identity
-    # block). `Kernel.load` always re-executes the file, unlike
-    # `require`, so a second call would re-run `Hecks.bluebook
-    # "Governance"` a second time — and the self-hosting meta-domain
-    # records every declaration as a real dispatched command against its
-    # own ledger, so a second `Declare` for the same aggregate is a real
-    # `AlreadyExists`, not a no-op. Skipped once the member's bluebook is
-    # already registered in this registry — the same chapter, not merely
-    # a same-named one from a stale prior boot.
+    # Loads a member's bluebook unless this registry already holds it.
+    #
+    # `Kernel.load` re-executes the file, and a second `Declare` of the same aggregate is
+    # `AlreadyExists`, so repeated `uses_framework` calls in one boot must skip.
     #
     # @param name [String, Symbol] the member's name, such as `"Governance"`
     # @return [Boolean, nil] true when this call loaded the member's bluebook, nil when

data/lib/hecks/freezer.rb

@@ -1,38 +1,10 @@
 module Hecks
-  # The one place that knows how to freeze a domain value.
-  #
-  # Freezing here has been fixed four times in four places, each time by
-  # topping the container and leaving the contents: list attributes, the
-  # event log, query rows, and value objects. `.freeze` on a Hash stops a
-  # key being added or removed and nothing else — the String, Array or
-  # Hash a field holds stays mutable, so a caller reaches straight
-  # through and edits in place. Each fix looked complete and none was.
-  #
-  # ## What should be frozen, and why it is not everything
-  #
-  #   a value object has no identity to change over. `with` already
-  #   answers a new one rather than mutating, so freezing it through is
-  #   what it always claimed to be.
-  #
-  #   an emitted event is a record of something that happened. A mutable
-  #   audit trail is not one.
-  #
-  #   a query row is an answer, not a handle — mutating one edits nobody's
-  #   state and silently disagrees with the store.
-  #
-  #   an instance's state is not frozen, deliberately: the interpreter
-  #   builds it up across a dispatch, and a command's whole job is to
-  #   change it. Its values are frozen; the holder is not.
-  #
-  #   a command's arguments are not frozen either. They arrive from
-  #   outside, are normalised and coerced on the way in, and the coerced
-  #   result is what becomes a frozen value.
+  # The one place that freezes a domain value all the way down, not just its container.
+  # Instance state and command arguments are deliberately left unfrozen; values and events are.
   module Freezer
     module_function
 
-    # Numbers, symbols, nil and booleans are already immediate or frozen;
-    # a Value froze itself when it was built. What is left is the mutable
-    # trio, and each has to be walked rather than topped.
+    # Freezes a Hash, Array or String and everything inside it.
     #
     # @param held [Object] any domain value
     # @return [Object] `held`, recursively frozen if it is a Hash, Array, or
@@ -46,17 +18,13 @@ module Hecks
       end
     end
 
-    # The question a gate asks, rather than the act. Answers false for the
-    # first thing that is reachable and mutable, which is what makes a
-    # failure message worth reading.
+    # True when `held` and everything reachable from it is frozen.
     #
     # @param held [Object] any domain value
     # @return [Boolean] true if `held` and everything reachable from it is frozen
     def deeply_frozen?(held) = unfrozen_within(held).nil?
 
     # The path to the first mutable thing reachable from `held`, or nil.
-    # A path rather than a boolean because "something in this event is
-    # mutable" is not an actionable sentence.
     #
     # @param held [Object] any domain value
     # @param path [Array<String>] the owner path accumulated by the recursive
@@ -72,9 +40,7 @@ module Hecks
       end
     end
 
-    # Immediates are frozen in every Ruby that matters, but asking
-    # `frozen?` of them and trusting the answer has bitten enough people
-    # that it is worth being explicit.
+    # Explicit rather than trusting `frozen?` on immediates.
     #
     # @param held [Object] any domain value
     # @return [Boolean] true if `held` is nil, true, false, a Numeric, or a Symbol

data/lib/hecks/grammar/expression.bluebook

@@ -6,21 +6,9 @@ Hecks.bluebook "Expression" do
   aggregate "Operator" do
     description "One admitted operation — its symbol, its precedence, and how it reads in every target that must evaluate it."
 
-    # WHAT IS NOT HERE, on purpose. The outer grammar
-    # has two rules that are not operators: parenthesization (a structural
-    # strip-and-recurse, no symbol of its own) and the bare-leaf fallback
-    # (whatever matches nothing else falls through to the inner grammar).
-    # Its inner grammar has three more: integer/float/string/bool/nil/
-    # array literals and the dotted-lookup fallback are TERMINAL
-    # productions — they recognize text, they do not combine operands,
-    # and they have nothing meaningful to render per target (a literal's
-    # spelling does not differ between targets the way an operation's
-    # might — `rust/src/kernel/expr.rs`'s own `Expr::Array` is a LEAF
-    # there too, for the identical reason, not routed through
-    # `OperatorCategory`).
-    # Forcing them into this shape would stretch `renderings` and the
-    # Arity invariant past what they mean. They stay declared only in
-    # prose — named here rather than silently left out.
+    # Not operators, so not declared here: parenthesization, the bare-leaf fallback,
+    # and the terminal literals and dotted lookup. They recognize text rather than
+    # combine operands, and a literal reads the same in every target.
     identified_by :symbol
 
     attribute :symbol,     OperatorSymbol
@@ -54,47 +42,34 @@ Hecks.bluebook "Expression" do
 
     value_object "Arity" do
       attribute :value, Integer
-      # WRITTEN ACROSS LINES ON PURPOSE, and this is the only predicate in the
-      # corpus that is. A CONTINUATION line is where extraction used to break:
-      # a naive line join reads `value > 0 && && value <= 3` — a different
-      # canonical form for the same source, waiting for the first multi-line
-      # rule anyone wrote. Every predicate here was kept on one line to dodge
-      # that. The join is continuation-aware now, so this case holds the fix:
-      # if it regresses, the canonical text of THIS invariant changes and the
-      # golden IR goes red.
+      # Written across lines on purpose: it pins continuation-aware line joining in
+      # extraction. If that regresses, this invariant's canonical text changes and
+      # the golden IR goes red.
       invariant("an operator takes one, two or three operands") do
         value > 0 &&
           value <= 3
       end
     end
 
-    # OUTER checks a leaf against `.include?`/comparators/`!` before falling
-    # through to INNER's arithmetic/dotted-lookup grammar — two stacked
-    # grammars. Which one an operator belongs
-    # to is not derivable from its symbol alone (`+` reads like it could be
-    # either), so it is its own column rather than inferred.
+    # The outer grammar checks `.include?`, comparators and `!` before falling through
+    # to the inner arithmetic and dotted-lookup grammar. The symbol alone does not say
+    # which one an operator belongs to, so it is its own column.
     value_object "Grammar" do
       attribute :value, String
       invariant("an operator belongs to one of the two stacked grammars") { !value.to_s.empty? }
     end
 
-    # HOW the check recognizes this operator's text, not WHERE it binds
-    # (that's precedence) or WHEN it's tried (that's position). Four shapes
-    # cover every admitted operator: split at a top-level occurrence
-    # (`||`, comparators), strip a leading marker (`!`), strip a trailing
-    # suffix (`.empty?`), or match a call-with-argument pattern
-    # (`.include?(needle)`).
+    # How the check recognizes an operator's text: split at a top-level occurrence
+    # (`||`), strip a leading marker (`!`) or trailing suffix (`.empty?`), or match a
+    # call pattern (`.include?(needle)`).
     value_object "Strategy" do
       attribute :value, String
       invariant("an operator names how its check recognizes it") { !value.to_s.empty? }
     end
 
-    # THE WITHIN-GRAMMAR CHECK ORDER — what precedence alone cannot say,
-    # since the six comparators all share one precedence tier and something
-    # still has to break the tie (grammar.md: `>=` before `<=` before `<`
-    # before `>` before `==` before `!=`, so `<` splitting does not fire
-    # inside `>=`). Scoped per `grammar`, mirroring Normalisation's own
-    # Position column below — each grammar starts its own count at 1.
+    # The check order within a grammar, counted from 1 per grammar. It breaks the tie
+    # precedence cannot: the six comparators share a tier, and `>=` must be tried
+    # before `>` so a split on `>` does not fire inside `>=`.
     value_object "Position" do
       attribute :value, Integer
       invariant("an operator sits somewhere in its grammar's check order") { value > 0 }

data/lib/hecks/grammar/translation.bluebook

@@ -18,12 +18,9 @@ Hecks.bluebook "Translation" do
       transition "Retire" => "retired",  from: "admitted"
     end
 
-    # THE CLOSED SET OF RULE KINDS — declared as members, not a hand-rolled
-    # OR-chain, so the set is data a conformance spec can hold the live
-    # builder to (spec/translation_vocabulary_conformance_spec.rb). Nine of
-    # these are TranslationAggregateBuilder's own rule methods ; "retired" is
-    # the edge-level declaration (TranslationBuilder#retired), in the set
-    # because it is one admitted way a shape survives — by not surviving.
+    # The closed set of rule kinds, kept as data so a conformance spec can hold the
+    # builder to it. All but "retired" are TranslationAggregateBuilder rule methods;
+    # "retired" is the edge-level declaration (TranslationBuilder#retired).
     value_object "Kind" do
       attribute :value, String,
                 one_of: ["rename", "move", "convert", "drop", "retype", "retired", "compute", "rekey",

data/lib/hecks/grammar.rb

@@ -1,32 +1,23 @@
 require "json"
 
-# The whole framework, deliberately: booting a grammar chapter exercises
-# the DSL, the meta-validator, and the runtime — and nothing the entry
-# point loads ever requires this file back, so the require is acyclic.
+# Loads the whole framework on purpose; nothing the entry point loads
+# requires this file back, so the require is acyclic.
 require_relative "../hecks"
 
 module Hecks
-  # The sublanguage grammar domains (grammar/*.bluebook) and the one boot
-  # path for reading them as data — the expression chapter replayed
-  # through its own admission ledger, so anything derived from it (the
-  # operator projections, the conformance specs) reads the set that
-  # actually survived the Admit gates, never a hand-copied list.
+  # The sublanguage grammar domains (grammar/*.bluebook) and the one boot path
+  # for reading them as data, replayed through the expression admission ledger.
   #
-  # Booted on call, never at require: the Prism adapter normalises every
-  # predicate through CanonicalForm while a bluebook loads, so the
-  # expression machinery cannot boot the chapter that configures it —
-  # this module exists precisely so generators and specs boot it in a
-  # scratch registry instead.
+  # Booted on call, never at require: the Prism adapter normalises predicates
+  # while a bluebook loads, so the expression machinery cannot boot its own chapter.
   module Grammar
     DIR    = File.expand_path("grammar", __dir__)
     LEDGER = File.join(DIR, "expression_operators.json")
 
     module_function
 
-    # Boot the expression chapter and replay the admission ledger through
-    # its real commands. A refused step raises — a generator running off
-    # a half-admitted ledger would project a table the gates never
-    # accepted.
+    # Boots the expression chapter and replays the admission ledger through
+    # its real commands; a refused step raises.
     #
     # @return [Runtime::Dispatcher] the dispatcher bound to the booted, replayed
     #   expression chapter
@@ -104,16 +95,9 @@ module Hecks
       registry.repository("Expression", aggregate).all
     end
 
-    # The operators the language stands on. Every guard and invariant in
-    # the language's own chapters — the meta-domain (Bluebook, World) and
-    # the grammar chapters beside this file — evaluates through the very
-    # operator table the ledger admits. An operator one of those
-    # predicates uses is self-bearing: retire it and the language can no
-    # longer read its own rules — found the hard way, as a projection
-    # missing `!=` that could not boot the chapter to fix itself. This
-    # derives the set, with a usage site per operator, so the generator
-    # and the conformance spec can refuse the retirement by name instead
-    # of wedging.
+    # The operators the language's own guards and invariants (Bluebook, World and
+    # the grammar chapters) evaluate through. Retiring one would leave the
+    # language unable to read its own rules, so callers refuse it by name.
     #
     # @return [Hash{String => Array<String>}] each self-bearing operator symbol
     #   mapped to the `"Chapter Aggregate.command"`/`"Chapter Aggregate::ValueObject"`
@@ -147,8 +131,7 @@ module Hecks
       sites.transform_values(&:uniq)
     end
 
-    # Every grammar/*.bluebook chapter, booted the same way the corpus
-    # boots them — each alone, in a scratch registry.
+    # Every grammar/*.bluebook chapter, each booted alone in a scratch registry.
     #
     # @return [Array<Class>] each grammar chapter, booted alone in its own scratch
     #   registry
@@ -167,9 +150,8 @@ module Hecks
       end
     end
 
-    # Which admitted operators one canonical text evaluates through —
-    # the evaluator's own parse, walked for its operator nodes, leaves
-    # walked for the resolver's arithmetic.
+    # Which admitted operators one canonical text evaluates through, found by
+    # walking the evaluator's own parse.
     #
     # @param canonical [String] canonical expression text to parse
     # @return [Array<String>] operator symbols the expression evaluates through, or
@@ -184,15 +166,8 @@ module Hecks
       walk_operators(node, evaluator).uniq
     end
 
-    # A recursive descent over a closed, declared set of AST node types
-    # (Evaluator's boolean/compare/include nodes, Resolver's arithmetic
-    # nodes, and the generic Struct fallback) — each branch does the
-    # same one thing (name the node's own operator, recurse into its
-    # children) and the branches don't interact, but the ABC score adds
-    # every branch's cost together. Splitting the case out per node type
-    # would trade one place that shows the whole operator vocabulary for
-    # several that each show a fragment, with no reduction in real
-    # complexity.
+    # One case over the closed set of AST node types, kept together so the whole
+    # operator vocabulary reads in one place.
     # @param node [Object] an evaluator/resolver AST node, or a Struct fallback
     # @param evaluator [Module] `Bluebook::Expression::Evaluator`, passed through
     #   so nested calls don't re-resolve the constant