hecks 2.8.0 → 2.9.0

data/lib/hecks/bluebook/value_object.rb

@@ -5,48 +5,25 @@ module Hecks
   module Bluebook
     Invariant = Struct.new(:description, :canonical, :predicate, :ast, keyword_init: true)
 
-    # A value object — a declaration holder, never instantiated.
-    #
-    # `ValueObjectBuilder` returns an anonymous subclass whose singleton
-    # carries the declaration : attributes, invariants, members. Nothing ever
-    # calls `.new` on one — coercion builds `Runtime::Value` wrappers, and
-    # invariants run as canonical text through the Evaluator. The runtime
-    # reaches a shape through `aggregate.value_object(name)`, the IR's own
-    # finder ; there is no constant nesting and no second index.
-    #
-    # `to_h` does not move. It is a byte-for-byte contract pinned by the
-    # golden fixtures, so it keeps spelling the short declared name, which
-    # is what `hecks_name` carries. Declarations in the graph, strings in the
-    # export.
+    # A value object: a declaration holder, never instantiated.
+    # `ValueObjectBuilder` returns a subclass carrying attributes, invariants and members;
+    # reach one through `aggregate.value_object(name)`.
+    # `to_h` spells the short declared name (`hecks_name`), a contract pinned by golden fixtures.
     class ValueObject
       extend Construct
-      # Extended, not included — this construct is a class, so its
-      # emission is a class method. See Hecks::IR's own note on
-      # the two shapes.
+      # Extended, not included: this construct is a class, so emission is a class method.
       extend Hecks::IR
       extend Behaviour::ValueObject
 
       emits_ir(
         name:       :hecks_name,
         attributes: many(:attributes),
-        # `ast:` — a JSON-serializable rendering of the same predicate
-        # `canonical` already spells as text, alongside it rather than
-        # replacing it (`canonical` stays the human-facing/doctest-facing
-        # form; parsing it back would just re-derive what `ast` already
-        # states directly). Ground truth and the full reasoning:
-        # `Expression::AstJson`'s own header — built for `rust/host`'s
-        # own mint-time invariant check (`reference_validate.rs`), which
-        # has no kernel crate to parse `canonical` with.
+        # `ast` sits beside `canonical` because rust/host's mint-time invariant check
+        # has no kernel crate to parse `canonical` with (see `Expression::AstJson`).
         invariants: -> { invariants.map { |rule| Expression::AstJson.rule_row(rule) } },
         closed_set: :closed_set?,
-        # The field name is stringified, never the value. A `member` row can
-        # hold any of the scalar types an attribute declares — `Integer 84`
-        # (`StatementFrequency#retention_months`, statements.bluebook), not
-        # only `String` — and stringifying it on the way out would erase
-        # that: `84` and `"84"` (a member some other row might legitimately
-        # spell as text) would become indistinguishable once they reached
-        # `to_h`. The declared name still moves (`field.to_s`) — that half
-        # was never a Ruby object with a type to lose.
+        # Only the field name is stringified: a member value can be an Integer, and
+        # stringifying it would make `84` and `"84"` indistinguishable in `to_h`.
         members:    -> { members.map { |member| member.map { |field, value| [field.to_s, value] } } }
       )
 
@@ -57,10 +34,8 @@ module Hecks
         # the bluebook declares and the thing Ruby holds are one object.
         #
         # @param name [String, Symbol] the value object's declared type name
-        # @param attributes [Array<Bluebook::Attribute>] the value object's declared
-        #   fields
-        # @param invariants [Array<Bluebook::Invariant>] the rules checked against every
-        #   instance of this value object
+        # @param attributes [Array<Bluebook::Attribute>] the value object's declared fields
+        # @param invariants [Array<Bluebook::Invariant>] the rules checked against every instance
         # @param members [Array<Hash{Symbol => Object}>] the declared `one_of` members, one
         #   row of field values per member
         # @param closed_set [Boolean] whether a `one_of` was declared, even with no

data/lib/hecks/bluebook.rb

@@ -1,36 +1,19 @@
-# Hecks::Bluebook
-#
-# Everything a .bluebook file becomes on its way to running: the expression
-# language (expression/), the model itself (the chapter class plus
-# everything it declares), the assembly that turns
-# declarations back into that graph (assembly.rb + assembly/), the authoring
-# DSL (dsl/), and the meta-validator that judges a chapter against the
-# language's own grammar (meta_validator.rb + meta_validator/).
-#
-# The require order below matters: expression and IR load first (pure
-# declarations), assembly's collaborators load before its face, and the DSL
-# loads before the meta-validator that its builders call at build time.
+# Everything a .bluebook file becomes on its way to running: expression language, model,
+# assembly, authoring DSL and meta-validator.
 
 module Hecks
-  # Declared as a class, not a module — `Hecks::Bluebook` is a
-  # chapter (bluebook/chapter.rb carries its body). Everything a chapter
-  # declares nests under it, as do the ways to build one (`DSL`) and to
-  # judge one (`MetaValidator`). Reopening this anywhere must say `class`.
+  # `Hecks::Bluebook` is a class defined in bluebook/chapter.rb; reopen it with `class`.
   module Bluebook
   end
 end
 
-# What the chapter's own files lean on at class-body level (`extend
-# Construct`, the assembly's QuerySpecification marks) — required here
-# because those files' contents are frozen and cannot say so themselves.
+# Required here because the chapter's frozen files lean on these at class-body level.
+# Load order: expression and IR first, assembly's collaborators before its face, DSL last.
 require_relative "construct"
 require_relative "literal"
 require_relative "query_specification"
 
 require_relative "bluebook/expression"
-# **The model itself** — the chapter class's own body first, then everything
-# a chapter declares. Order matters only for reading: each is a bag of
-# declarations with no load-time cross-references.
 require_relative "bluebook/chapter"
 require_relative "bluebook/reference"
 require_relative "bluebook/attribute"

data/lib/hecks/cache_dir.rb

@@ -3,30 +3,11 @@ require "fileutils"
 require "tmpdir"
 
 module Hecks
-  # The one place the runtime's own scratch files live, outside the gem.
+  # The one place the runtime's own scratch files live, outside the gem: an
+  # installed gem is read-only, and a checkout's `tmp/` isn't this library's to assume.
   #
-  # The syntax-boot cache and the Storehouse audit log are written on a
-  # normal run, so they cannot sit under the gem's own directory: an
-  # installed gem is read-only, and a checkout's `tmp/` is not a place a
-  # library gets to assume. Both ask this module for a subdirectory instead.
-  #
-  # ## Where the root is
-  #
-  # The first of these that can be made a private directory wins:
-  #
-  # 1. `$XDG_CACHE_HOME/hecks`, when `XDG_CACHE_HOME` is set to an absolute path
-  # 2. `~/.cache/hecks`
-  # 3. `<system temp dir>/hecks-<uid>`
-  #
-  # ## Private, or not used
-  #
-  # The syntax-boot cache is read back with `Marshal.load`, so a directory
-  # another account can write to is a way to run code as this one. A
-  # candidate is accepted only if it is owned by the current user and
-  # writable by nobody else; the shared temp directory in particular is
-  # where a predictable name can be planted by someone else. When no candidate
-  # qualifies, a fresh per-process directory stands in: the cache still
-  # works within the process and is never shared with a stranger.
+  # A candidate root is used only if it is private to the current user, since the
+  # syntax-boot cache it holds is read back with `Marshal.load`.
   module CacheDir
     module_function
 

data/lib/hecks/cli/document.rb

@@ -5,23 +5,7 @@ module Hecks
     # The command behind `bin/docs`, `bin/narrate`, `hecks docs` and `hecks narrate`:
     # one domain's document, projected from its own bluebook, to stdout.
     #
-    # `:docs` answers the usage document a console's `<Domain>.docs` prints; `:narrate`
-    # answers the same chapter read back in English, for the subject-matter expert
-    # (`Projector::NarrateProjector`). Nothing is written for the caller: redirect it,
-    # so the caller decides where a generated file lands and git decides whether it
-    # drifted.
-    #
-    # ## Every failure is a sentence
-    #
-    # A misspelled aggregate refuses by name rather than printing nothing and exiting
-    # 0. A caller cannot tell an empty document from an empty domain, so this refuses
-    # instead and names what is actually there.
-    #
-    # ## Standing in a domain is enough
-    #
-    # `Adapters::Folder#domain_root` walks up for the nearest `.hecksagon`, which makes
-    # the first argument ambiguous. The rule: a directory is a domain, anything else
-    # is an aggregate name, and the two-argument form says which is which.
+    # Nothing is written for the caller: redirect it, so git decides whether it drifted.
     module Document
       # Build output and other trees under a root that hold no domain a caller means.
       # Matched against the path relative to the root, because a substring test
@@ -66,10 +50,8 @@ module Hecks
 
       # Lists every directory under `root` that `Hecks.boot` would accept.
       #
-      # Found by their wiring, not their chapters: a `.hecksagon` is what says "this
-      # is a domain, and here is how its aggregates are stored", while most
-      # `.bluebook` files (era translations, the language's own grammar,
-      # `spec/fixtures`) are not domains anybody boots.
+      # Found by their wiring, not their chapters: a `.hecksagon` says this is a
+      # domain, while most `.bluebook` files (era translations, grammar, fixtures) are not.
       #
       # @param root [String] the directory to search under
       # @return [Array<String>] domain directory paths relative to `root`,

data/lib/hecks/cli/ir.rb

@@ -6,17 +6,15 @@ require_relative "../ports/persistence/plugins/era"
 module Hecks
   module CLI
     # The command behind `bin/ir` and `hecks ir`: a booted domain's IR as JSON, the
-    # same `to_h` the golden specs pin and `StorageShape` hashes into an era, for
-    # reading rather than asserting on.
+    # same `to_h` the golden specs pin and `StorageShape` hashes into an era.
     module Ir
       module_function
 
       # Prints the IR `argv` asks for.
       #
-      # `--meta` prints the language's own IR, the chapters under
-      # `lib/hecks/language/bluebook/` merged into one. It is reached through
+      # `--meta` prints the language's own IR, reached through
       # `Bluebook::MetaValidator.grammar_registry`, the real boot sequence, so it
-      # cannot drift from what `MetaValidator` itself loads.
+      # can't drift from what `MetaValidator` loads.
       #
       # @param argv [Array<String>] a domain path and `--translations`, or `--meta`
       # @param program [String] the name the usage message calls this command by

data/lib/hecks/cli/mcp.rb

@@ -5,9 +5,8 @@ module Hecks
     # The command behind `bin/hecks_mcp_door` and `hecks mcp`: the MCP door onto the
     # storehouse bus, over stdio only.
     #
-    # This file loads nothing but `McpStdioGuard`, so the transport check runs before
-    # the framework does. The door itself is `McpDoor`, required only once the check
-    # passes.
+    # This file loads nothing but `McpStdioGuard`, so the transport check runs
+    # before the framework does.
     module Mcp
       # The server name the guard's refusals and warnings carry.
       SERVER = "hecks-mcp-door".freeze

data/lib/hecks/cli/mcp_door.rb

@@ -4,56 +4,17 @@ require_relative "mcp"
 
 module Hecks
   module CLI
-    # The MCP door onto the storehouse bus: one MCP server for every booted domain,
-    # not one per command, hand-rolled JSON-RPC over stdio (newline-delimited JSON,
-    # flushed after every write, no gem dependency).
+    # The MCP door onto the storehouse bus: hand-rolled JSON-RPC over stdio, one
+    # server per booted domain. All logic and the JSON shape answered with live in
+    # `Storehouse`; this is plumbing only. A `role:`/`actor_id:` a caller sends is
+    # asserted, not verified, unless Governance is attached.
     #
-    # ## Plumbing only
-    #
-    # All the logic and the JSON shape it answers with live in `Storehouse`, the bus
-    # itself, transport-blind. A door of another shape (a plain CLI, an HTTP door)
-    # would sit beside this one, calling `Storehouse` the same way and sharing its
-    # audit log and caller-identity handling.
-    #
-    # ## Identity is asserted, not verified
-    #
-    # `dispatch` and `query` take `role:` and `actor_id:`, bound for the call through
-    # `Hecks.as_caller`, so a role-gated command is checked against them rather than
-    # merely documented by `describe`; `dispatch` refuses a role-declaring command
-    # called without one. Nothing here verifies the claim beyond the string (or, with
-    # Governance attached, a `Governance::RoleAssignment` lookup). The readers take
-    # no role, and `query` gates on none.
-    #
-    # ## Stdio only, enforced
-    #
-    # The door has no authentication. `Mcp.call` runs
-    # `McpStdioGuard.enforce_stdio!` before this file loads, and `serve` prints the
-    # warning to stderr, never stdout, which carries the protocol. `domain:` is
-    # confined to `Storehouse::BOOT_ROOT` (`confine!`), but a domain within that
-    # root still boots real Ruby, so this is a code execution surface for anyone who
-    # can write to stdin. A network transport needs authentication first; see
-    # `docs/decisions/0062-mcp-servers-need-real-authentication-before-any-network-transport.md`.
-    #
-    # ## Reader mode
-    #
-    # Whoever spawns the door can narrow it with `HECKS_DOOR_TOOLS=readers` and
-    # `HECKS_DOOR_DOMAINS=<dir>[:<dir>...]` (`Hecks::McpDoorScope`, ADR 0072 decision 2).
-    # A reader door serves only `McpDoorScope::READER_TOOLS` (`query`, `events`,
-    # `state`, `catalog`, `describe`, `validate`, `domains`, `history`, `follow`), lists
-    # only those in `tools/list`, and refuses `dispatch` (so `dry_run` and `steps` too),
-    # `behaviors` and any other name with an answer that names the mode. Its `domain:`
-    # must resolve to one of the named directories, checked before anything boots, so no
-    # other domain's Ruby is loaded. The door keeps no domain loaded between calls, so
-    # the named list is the whole allowed set. This limits what one spawned agent can
-    # reach; it identifies no one and is not authentication. The names sit outside
-    # `HECKS_MCP_*` because the stdio guard refuses every name in that prefix but the
-    # transport, and that refusal belongs to ADR 0062. With neither variable set, the
-    # door serves every tool as described above.
-    #
-    # ## One boot per call
-    #
-    # `Hecks.boot(domain, install_facade: false)` is cheap, and it lets one server
-    # answer calls against two domains back to back with no shared, staling state.
+    # There is no authentication: `domain:` boots real Ruby confined to
+    # `Storehouse::BOOT_ROOT`, so this is a code execution surface for anyone who
+    # can write to stdin (ADR 0062). Spawning with `HECKS_DOOR_TOOLS=readers` and
+    # `HECKS_DOOR_DOMAINS=<dir>[:<dir>...]` narrows a door to read-only tools and
+    # named domains (`McpDoorScope`); this limits what one agent can reach and is
+    # not itself authentication.
     module McpDoor
       PROTOCOL_VERSION = "2024-11-05".freeze
 
@@ -271,27 +232,17 @@ module Hecks
 
       module_function
 
-      # The scope this door was spawned with: every tool and any domain, or a reader
-      # door narrowed by `HECKS_DOOR_TOOLS`/`HECKS_DOOR_DOMAINS`. Read once, on first use,
-      # so a bad setting refuses to start the door before anything is written to stdout.
-      #
-      # @return [McpDoorScope]
+      # Read once, so a bad setting refuses to start the door before anything is
+      # written to stdout.
       def scope
         @scope ||= McpDoorScope.start!(server: Mcp::SERVER)
       end
 
-      # The notes the stdio warning carries: the standing ones, then what this door's
-      # scope says about `domain:`.
-      #
-      # @return [Array<String>]
+      # The standing notes, then what this door's scope says about `domain:`.
       def warning_notes
         NOTES[0, 2] + (scope.restricted? ? scope.notes : [NOTES[2]])
       end
 
-      # Prints the stdio warning to stderr, then answers one JSON-RPC request per
-      # line of `$stdin` until it closes.
-      #
-      # @return [void]
       def serve
         McpStdioGuard.warn!(server: Mcp::SERVER, notes: warning_notes)
         $stdout.sync = true
@@ -315,29 +266,14 @@ module Hecks
         end
       end
 
-      # Boots one domain for a single call, confined to `Storehouse::BOOT_ROOT`.
-      #
-      # @param domain [String] the domain directory, e.g. `"examples/banking"`
-      # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
-      # @raise [Runtime::TypeMismatch] if `domain` resolves outside `Storehouse::BOOT_ROOT`, or,
-      #   on a reader door, outside `HECKS_DOOR_DOMAINS`
-      # @raise [Runtime::WiringError] if the domain fails to boot
+      # `domain:` is confined to `Storehouse::BOOT_ROOT`, and further to a reader
+      # door's `HECKS_DOOR_DOMAINS`, before anything boots.
       def boot(domain)
         Hecks.boot(Storehouse.confine!(scope.admit_domain!(domain), "domain"), install_facade: false)
       end
 
-      # Runs one registered MCP tool by delegating to the matching `Storehouse` call.
-      #
-      # A closed-set dispatch table, one `when` per tool, so the size is the tool
-      # count and the shared `rescue` catches every branch's escape once.
-      #
-      # @param name [String] the tool name, one of `TOOLS`'s own `:name` values
-      # @param args [Hash{String => Object}] the tool's JSON arguments, shaped per that
-      #   tool's `inputSchema`
-      # @return [Hash{Symbol => Object}] the delegated `Storehouse` result on a known
-      #   tool name; `{ok: false, error: String}` for an unknown tool name or any
-      #   `StandardError` this door did not anticipate (a domain refusal is already
-      #   `{ok: false, ...}` from inside `Storehouse` itself)
+      # One `when` per tool, so the shared `rescue` catches every branch's escape
+      # once; a domain refusal is already `{ok: false, ...}` from `Storehouse`.
       def call_tool(name, args) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
         case name
         when "dispatch"
@@ -378,60 +314,29 @@ module Hecks
           { ok: false, error: "no such tool: #{name.inspect} — known: #{TOOLS.map { |t| t[:name] }.join(', ')}" }
         end
       rescue StandardError => e
-        # **A defect, not a refusal** — every domain refusal is already answered as
-        # `{ok: false, error: "..."}` inside `Storehouse`. Reaching here means a bad
-        # domain path or an argument shape `Facade::JsonDoor` could not symbolize,
-        # still answered as structured content rather than an MCP-level `isError`,
-        # so a calling agent reads one shape for every outcome.
+        # A defect, not a refusal: reaching here means a bad domain path or an
+        # argument shape `Facade::JsonDoor` could not symbolize.
         { ok: false, error: "#{e.class}: #{e.message}" }
       end
 
-      # Runs one MCP tool call if this door's mode serves it, and refuses it otherwise.
-      #
-      # @param name [String] the tool name from the `tools/call` request
-      # @param args [Hash{String => Object}] the tool's JSON arguments
-      # @return [Hash{Symbol => Object}] the `call_tool` result, or `scope.refusal(name)`
-      #   when a reader door does not serve `name`
       def answer_tool(name, args)
         return scope.refusal(name) unless scope.permits_tool?(name)
 
         call_tool(name, args)
       end
 
-      # Wraps a `call_tool` payload in the MCP `tools/call` result shape.
-      #
-      # @param payload [Hash{Symbol => Object}] a `call_tool` result
-      # @return [Hash{Symbol => Object}] `{content: [{type: "text", text: ...}], isError: Boolean}`,
-      #   pretty-printing `payload` as the text and setting `isError` from `payload[:ok]`
       def tool_result(payload)
         { content: [{ type: "text", text: JSON.pretty_generate(payload) }], isError: payload[:ok] == false }
       end
 
-      # Writes one JSON-RPC success response line to stdout.
-      #
-      # @param id [String, Integer, nil] the request's own `id`, echoed back
-      # @param result [Object] the JSON-serializable result payload
-      # @return [void]
       def send_response(id, result)
         puts JSON.generate({ jsonrpc: "2.0", id: id, result: result })
       end
 
-      # Writes one JSON-RPC error response line to stdout.
-      #
-      # @param id [String, Integer, nil] the request's own `id`, echoed back; nil when
-      #   the request itself could not be parsed
-      # @param code [Integer] the JSON-RPC error code
-      # @param message [String] the error message
-      # @return [void]
       def send_error(id, code, message)
         puts JSON.generate({ jsonrpc: "2.0", id: id, error: { code: code, message: message } })
       end
 
-      # Dispatches one parsed JSON-RPC request to its method and writes the response.
-      #
-      # @param request [Hash{String => Object}] one parsed JSON-RPC request, with
-      #   `"id"`, `"method"`, and optional `"params"`
-      # @return [void]
       def handle(request)
         id     = request["id"]
         method = request["method"]

data/lib/hecks/cli/model_check.rb

@@ -5,26 +5,13 @@ module Hecks
   module CLI
     # The command behind `bin/model_check` and `hecks model_check`: static analysis
     # over the IR, printed per domain, exiting non-zero when any error-severity
-    # finding is left.
+    # finding is left — unreachable lifecycle states, dead transitions, unreached
+    # saga states, dispatches to a nonexistent command, handlers for an event
+    # nothing emits. The runtime checks none of these; a dead transition never
+    # fires, in silence.
     #
-    # It finds unreachable lifecycle states, transitions nothing can fire, saga
-    # states no handler chain reaches, a compensation whose `from_state` is
-    # unreachable, dispatches to a command that does not exist, and handlers
-    # listening for an event nothing emits. The runtime checks none of these: a dead
-    # transition never fires, in silence.
-    #
-    # ## Named domains, or the whole corpus
-    #
-    # Given domain paths, it boots each and runs one cross-domain check across all
-    # of them. Given none, it sweeps the repository's corpus (`Corpus.model_check_members`)
-    # and the language's own chapters; that needs `root:`, the repository, so an
-    # installed gem without one asks for a domain path instead.
-    #
-    # ## Options
-    #
-    # `--strict` makes a `rust_reserved_name` finding an error for every target, not
-    # only for those with a Cargo feature under `root`'s `rust/Cargo.toml`.
-    # `--profile client` adds `Bluebook::ModelCheck::ClientProfile`'s error findings.
+    # Given domain paths it checks just those, cross-domain; given none it sweeps
+    # the repository's corpus and the language's own chapters, which needs `root:`.
     module ModelCheck
       # The directory the framework's own `.port` and `.adapter` files live under.
       HECKS_DIR = File.expand_path("..", __dir__)
@@ -64,10 +51,6 @@ module Hecks
         exit(ok ? 0 : 1)
       end
 
-      # Reads `--profile client` or `--profile=client` and removes it from `argv`.
-      #
-      # @param argv [Array<String>] the arguments, changed in place
-      # @return [Symbol, nil] the requested profile, or nil when none was asked for
       def take_profile(argv)
         inline = argv.find { |arg| arg.start_with?("--profile=") }
         index = argv.index("--profile")
@@ -79,13 +62,8 @@ module Hecks
         name.to_sym
       end
 
-      # Boots each named domain and examines them against one shared set of known
-      # domains and emitted events, so a cross-domain reaction between two of them
-      # is checked.
-      #
-      # @param domain_args [Array<String>] domain directory paths
-      # @param options [Options] the run's configuration
-      # @return [Boolean] true when every domain passes
+      # Examines every named domain against one shared set of known domains and
+      # emitted events, so a cross-domain reaction between two of them is checked.
       def check_domains(domain_args, options)
         booted = domain_args.map do |domain_arg|
           [File.basename(domain_arg.chomp("/")), boot(bluebook_dir(domain_arg.chomp("/")) || domain_arg)]
@@ -93,15 +71,8 @@ module Hecks
         examine_all(booted, options)
       end
 
-      # Boots every corpus member once, then examines each against the set of names
-      # every member declares, then examines the language itself.
-      #
       # Two passes over the same boots, because a single boot's own registry cannot
       # answer whether a target domain exists anywhere in the corpus.
-      #
-      # @param root [String] the repository root
-      # @param options [Options] the run's configuration
-      # @return [Boolean] true when every member and the language pass
       def check_corpus(root, options)
         require_relative "../corpus"
         targets = Corpus.model_check_members(root: root).map { |member| [member.stem, Corpus.source_of(member)] }
@@ -110,17 +81,8 @@ module Hecks
         examine_language(options) && ok
       end
 
-      # Boots one source into a fresh registry, with its sibling hecksagons so a
-      # policy bound from there is visible too.
-      #
-      # `root:` is the source's parent: a directory source is already the domain's
-      # own `bluebook/` folder, and without a root a member declaring
-      # `uses_embryonaut_bluebook` refuses with "needs a registry with a root to
-      # vendor from".
-      #
-      # @param source [String] a directory to boot (every bluebook within), or a
-      #   single `.bluebook` file path
-      # @return [Runtime::Registry] the registry populated with the booted bluebooks
+      # `root:` is the source's parent, so a member declaring
+      # `uses_embryonaut_bluebook` can vendor from it.
       def boot(source)
         root = File.directory?(source) ? File.dirname(source) : nil
         registry = Runtime::Registry.new(root: root)
@@ -142,10 +104,8 @@ module Hecks
         end
 
         # A port attaches to its aggregate from the hecksagon, not the bluebook, so a
-        # deaf-policy check that never loads it would see a policy reacting to an
-        # event nothing appears to emit. A directory loads every `*.hecksagon` in it,
-        # as a real boot does. Recording a bind builds IR only, so no adapter needs to
-        # resolve here.
+        # deaf-policy check that skipped it would miss a policy reacting to an event
+        # nothing emits. Recording a bind builds IR only; no adapter resolves here.
         hecksagons = if File.directory?(source)
                        Dir.glob(File.join(source, "*.hecksagon"))
                      else
@@ -167,17 +127,6 @@ module Hecks
         end
       end
 
-      # Runs `Bluebook::ModelCheck` over one booted domain's chapters, prints its
-      # findings against the allowlist, and reports whether it passes.
-      #
-      # @param name [String] the domain's display name, for the header and the
-      #   `ALLOWED_FINDINGS` lookup
-      # @param registry [Runtime::Registry] a booted registry holding the domain's chapters
-      # @param options [Options] the run's configuration
-      # @param known_domains [Set<String>] every bluebook and hecksagon name booted this run
-      # @param global_emitted_events [Set<String>] every event any booted chapter emits
-      # @return [Boolean] false if an allowlist entry is stale; otherwise true when no
-      #   error-severity finding is left
       def domain_passes?(name, registry, options, known_domains:, global_emitted_events:)
         puts "── #{name}"
 
@@ -203,12 +152,9 @@ module Hecks
         passes?(findings, "   clean — #{chapters.size} chapter(s), no dead states, no unreachable protocol steps")
       end
 
-      # Examines the language's own `Bluebook` and `World` chapters through
-      # `MetaValidator.grammar_registry`, the judged graph its conformance specs use,
-      # because any one grammar file booted alone is a fraction of the language.
-      #
-      # @param options [Options] the run's configuration
-      # @return [Boolean] true when neither chapter has an error-severity finding
+      # Checked through `MetaValidator.grammar_registry`, the judged graph its
+      # conformance specs use, because any one grammar file booted alone is a
+      # fraction of the language.
       def examine_language(options)
         ok = true
         ["Bluebook", "World"].each do |name|
@@ -235,16 +181,8 @@ module Hecks
         errors.empty?
       end
 
-      # Says whether the domain has a Cargo feature, which makes a
-      # `rust_reserved_name` finding an error for it.
-      #
-      # The check reads `rust/Cargo.toml` through the repository-only fuzzing
-      # tooling, so it is loaded only when there is a `rust/` to read.
-      #
-      # @param name [String] the domain's display name
-      # @param rust_dir [String, nil] the repository's `rust/` directory; nil without a
-      #   checkout
-      # @return [Boolean] true when `rust_dir` declares a feature named after the domain
+      # The repository-only fuzzing tooling is loaded lazily, only when there is a
+      # `rust/` to read.
       def rust_target?(name, rust_dir)
         return false unless rust_dir
 
@@ -252,12 +190,7 @@ module Hecks
         Fuzzing::TargetCapabilities.rust_feature?(name, rust_dir)
       end
 
-      # The directory holding a domain's bluebooks: `<domain>/bluebook/` or the
-      # domain directory itself, the same rule `Corpus.bluebook_dir` applies.
-      #
-      # @param domain_path [String] a domain directory path
-      # @return [String, nil] the directory of the first `.bluebook` found, or nil when
-      #   neither place holds one
+      # The same rule `Corpus.bluebook_dir` applies.
       def bluebook_dir(domain_path)
         [File.join(domain_path, "bluebook"), domain_path].each do |dir|
           files = Dir[File.join(dir, "*.bluebook")]