hecks 2.8.0 → 3.0.0

data/lib/hecks/adapters/driven.rb

@@ -1,37 +1,14 @@
 module Hecks
-  # Reopened here purely to require in every driven adapter under
-  # adapters/driven/ below (see the comment inside for what "driven side"
-  # means) — the actual namespace is declared in adapters.rb.
+  # The driven side: every store or reader an adapter declaration can bind.
   module Adapters
-    # The driven side — every store or reader an adapter declaration can
-    # bind. A small adapter is one file beside this one; sqlite, postgres
-    # and heki keep a directory for their supporting cast. Each `.adapter`
-    # file alongside is the DSL declaration the grammar bootstrap and the
-    # Folder adapter load as data.
   end
 end
 
 require_relative "driven/memory"
 require_relative "driven/sqlite"
 require_relative "driven/postgres"
-# `PostgresEra` is not `require_relative`d here — ADR 0033 moved it, and
-# the rest of the era/lineage/translation subsystem, behind a loadable
-# persistence plugin (`hecks/ports/persistence/plugins/era`) rather than
-# requiring every app to carry it whether or not anything ever binds
-# `persisted_by "PostgresEra"`. `Module#autoload` is the one-line seam
-# that makes that genuinely load-nothing-until-asked instead of pushing
-# an explicit `require` onto every one of the ~15 generic `bin/*` tools
-# that boot an arbitrary checked-in domain (several of which — pizzas,
-# compliance, chess, roster — bind PostgresEra): the first real
-# `Adapters.const_get("PostgresEra")` (`registry/verification.rb`'s own
-# adapter resolution, unchanged) transparently `require`s the plugin
-# entry point, which defines the constant and calls `register_plugin`
-# as its own side effect (`plugins/era.rb`'s last line) — the exact
-# same effect an explicit `require "hecks/ports/persistence/plugins/
-# era"` has, just deferred to the moment something is actually asked
-# for `PostgresEra` rather than sprinkled across every caller that
-# might. A domain that never binds it never triggers the autoload, so
-# never loads a line of era code — unchanged from ADR 0033's own goal.
+# PostgresEra lives in a persistence plugin, autoloaded so a domain that never binds
+# it loads no era code; the plugin entry point registers itself on load (ADR 0033).
 Hecks::Adapters.autoload(:PostgresEra, "hecks/ports/persistence/plugins/era")
 require_relative "driven/lambda"
 require_relative "driven/heki"
@@ -44,16 +21,8 @@ require_relative "driven/tenant_provisioner"
 require_relative "driven/secure_random_identity"
 require_relative "driven/in_process_key_vault"
 require_relative "driven/system_clock"
-# `SequentialIdentity` — the deterministic identity_generation test
-# double — is not required here on purpose. It lives at
-# spec/fixtures/sequential_identity.{adapter,rb}, loaded explicitly by
-# whichever spec wants it: this file's `require_relative` list is what
-# `Folder#load_library`'s `.adapter` glob backs, and `.adapter` DSL
-# declarations register into every registry any real `Hecks.boot` ever
-# builds. Two adapters answering `identity_generation` unconditionally
-# would make the port permanently ambiguous — `Ports::IdentityGeneration
-# .adapter` refuses to choose between more than one — for every
-# consumer, forever, not just specs that want the deterministic one.
+# SequentialIdentity (spec/fixtures) is deliberately not required here: a second
+# `identity_generation` adapter would make that port ambiguous for every boot.
 require_relative "driven/governance_authorization"
 require_relative "driven/identity_registry"
 require_relative "driven/google_authentication"

data/lib/hecks/adapters/driving/github_webhook.rb

@@ -4,85 +4,23 @@ require "rack"
 
 module Hecks
   module Adapters
-    # **The driving side** — code an outside caller reaches in through,
-    # rather than code the domain reaches out through. Every existing
-    # file under `adapters/driven/` is the latter: a store or reader a
-    # `persisted_by`/`port` binding resolves to, called by this
-    # framework's own runtime. Nothing under this repository has ever
-    # been the mirror image before — code that receives a request from
-    # the outside world and turns it into a dispatch — so this is the
-    # first entry, and the directory itself is new.
+    # Driving adapters: code an outside caller reaches in through.
     module Driving
-      # **A GitHub webhook receiver, transport only** — the same split
-      # `Hecks::Adapters::GithubChecks` (qa/adapters/github_checks.rb,
-      # this class's own pull-side sibling) already draws for itself:
-      # this file owns proving a request really came from GitHub and
-      # unwrapping GitHub's own webhook envelope (`X-GitHub-Event`, the
-      # JSON body, GitHub's own automatic `ping` check) — never which
-      # commands to dispatch about what it finds inside. That is exactly
-      # as domain-specific as `GithubChecks#run` turning `check-runs`
-      # JSON into green-or-raise, and lives exactly where that class's
-      # own header explains such logic belongs: outside this library,
-      # in `qa/adapters/github_ci_webhook.rb`, the subclass of this file
-      # that actually knows what a `QualityControl::Clearance` is.
+      # A GitHub webhook receiver, transport only: a rack app that verifies the signature.
+      # A subclass implements `#handle_event(event, action, payload)` returning `[status, body]`.
       #
-      # ## A plain rack app
-      #
-      # A plain rack app (`#call(env)`) — no Sinatra, no Rails — the same
-      # shape `Hecks::Forms::App` (lib/hecks/forms/app.rb) already
-      # established for the one other HTTP-facing surface this library
-      # ships. `rack` is a lazy Gemfile dependency for exactly the reason
-      # that file's own header gives: this file is never required by
-      # `require "hecks"` (nothing under `adapters.rb`'s own eager
-      # `adapters/driven` load names it — see that file's own header),
-      # so a project that never mounts a driving adapter never needs
-      # `rack` installed, the same "opt in by requiring the file at all"
-      # contract `hecks/forms.rb` already has for `Forms::App`.
-      #
-      # ## Subclass responsibility
-      #
-      # Implement `#handle_event(event, action,
-      # payload)`, returning `[http_status, response_body_hash]`. Called
-      # only after the signature has verified and the body has parsed as
-      # JSON — a subclass never has to re-check either. `event` is
-      # GitHub's own `X-GitHub-Event` header value ("check_suite",
-      # "check_run", "pull_request", ...); `action` is the payload's own
-      # top-level `"action"` field when it has one (GitHub's webhooks
-      # nearly all carry one — "completed", "requested", "opened", ...)
-      # and nil when it does not. `ping` — GitHub's own automatic
-      # connectivity check, sent once when a webhook is first saved in
-      # repository settings — is answered here and never reaches a
-      # subclass at all; there is nothing domain-specific to decide
-      # about it.
+      # Not required by `require "hecks"`, so `rack` stays an opt-in dependency.
       class GithubWebhook
-        # **Refused, loudly** — the same shape a domain refusal already takes
-        # everywhere else in this codebase (`Runtime::DOMAIN_REFUSALS`,
-        # `Forms::App`'s own `{error:, message:}` JSON body for a bad
-        # command). A request that cannot prove it came from GitHub gets
-        # a real 401 and a named reason, never a silent 200 that would
-        # let a forged "CI passed" payload regress nothing while looking
-        # exactly like success in a log nobody re-reads.
+        # Raised for a request that cannot prove it came from GitHub; answered with a 401.
         class InvalidSignature < StandardError; end
 
-        # **The body did not even parse** — distinct from a signature refusal:
-        # this body genuinely came from whoever signed it (checked
-        # first, before parsing ever runs — see `#call`), and simply
-        # is not JSON. Still refused, never guessed at.
+        # Raised when a correctly signed body is not JSON; answered with a 400.
         class MalformedPayload < StandardError; end
 
         SIGNATURE_HEADER = "HTTP_X_HUB_SIGNATURE_256".freeze
         EVENT_HEADER     = "HTTP_X_GITHUB_EVENT".freeze
 
-        # `secret:` has no default, on purpose — the same rule
-        # `GoogleAuthentication`'s own header states for its own
-        # `ENV.fetch`, restated here because the consequence is worse for
-        # a webhook: an unverified signature check is not "half
-        # configured", it is no verification at all, silently accepting
-        # anything claiming to be GitHub. A caller passes the real
-        # secret explicitly — from `ENV.fetch("GITHUB_WEBHOOK_SECRET")`
-        # or wherever it keeps one — rather than this class reaching into
-        # the environment itself and hiding that requirement inside a
-        # default.
+        # `secret:` has no default: a missing secret would silently disable verification.
         # @param secret [String] the shared webhook secret (e.g. `ENV.fetch
         #   ("GITHUB_WEBHOOK_SECRET")`), checked against each request's `X-Hub-Signature-256`
         # @raise [ArgumentError] if `secret` is nil or empty
@@ -120,13 +58,7 @@ module Hecks
 
         private
 
-        # Constant-time compare, not `==`. A byte-by-byte `==` returns
-        # the moment it finds the first mismatching byte, so how long
-        # that took leaks how many leading bytes of a forged signature
-        # were already right to anyone timing the response — GitHub's
-        # own webhook documentation calls this out by name and recommends
-        # exactly the constant-time compare `Rack::Utils.secure_compare`
-        # already gives for free, reused rather than hand-rolled.
+        # Constant-time compare: `==` leaks how many leading bytes of a forged signature matched.
         def verify_signature!(request, body)
           header = request.get_header(SIGNATURE_HEADER)
           raise InvalidSignature, "missing #{SIGNATURE_HEADER.sub('HTTP_', '').tr('_', '-')} header" if header.to_s.empty?

data/lib/hecks/behaviors/dsl.rb

@@ -1,20 +1,12 @@
 require_relative "ir"
 
-# The authoring surface for `Hecks.behaviors "Name" do ... end` — one
-# `test "description" do ... end` block per case, `tests`/`setup`/`input`/
-# `expect` inside. `instance_eval`-based, the same shape every other
-# hecks DSL builder uses (`WorldBuilder`, `HecksagonBuilder`).
+# The authoring surface for `Hecks.behaviors "Name" do ... end`, built with `instance_eval`.
 module Hecks
   module Behaviors
-    # Raised at `Hecks.behaviors` build time — a missing `vision` or
-    # `loads` line names the fix directly rather than failing later, deep
-    # inside a boot, over a suite that was never going to be scoped.
+    # Raised at build time, so a missing `vision` or `loads` fails with the fix named.
     class Malformed < StandardError; end
 
-    # The `test "description" do ... end` block's own receiver — collects
-    # `tests`/`setup`/`input`/`expect` calls and builds a `TestCase` (ir.rb).
-    # `validate_expect!` (private, below) is where a malformed or empty
-    # `expect` is refused at build time rather than silently passing later.
+    # The `test "description" do ... end` receiver; builds a `TestCase` (ir.rb).
     class TestCaseBuilder
       # @param description [String] the `test "description" do ... end` text
       def initialize(description)
@@ -82,14 +74,8 @@ module Hecks
 
       private
 
-      # Closes the silent-pass paths a free-form `expect(**kwargs)` merge
-      # otherwise leaves open: a test with no `expect` at all asserts
-      # nothing and passes whenever dispatch doesn't raise; `count:` on a
-      # command and `emits:` on a query are each read by neither runner
-      # (Expectations#run_command/#run_query), so they're accepted here
-      # and then silently ignored at run time. Checking both at build
-      # time, not in the runners, makes them errors on the file that
-      # wrote them rather than green checks nobody questions.
+      # Refuses expectations that would pass silently: an empty `expect`, `count:` on a command,
+      # or `emits:` on a query (neither runner reads those). Checked at build time.
       def validate_expect!
         if @expect.empty?
           raise Malformed, "test #{@description.inspect} has no `expect` — say what this " \
@@ -108,9 +94,7 @@ module Hecks
       end
     end
 
-    # The top-level `Hecks.behaviors "Name" do ... end` receiver — collects
-    # `vision`/`loads`/`test` calls and builds a `BehaviorsSuite` (ir.rb),
-    # refusing to build one missing either `vision` or `loads` (`#build`).
+    # The top-level `Hecks.behaviors` receiver; builds a `BehaviorsSuite` (ir.rb).
     class BehaviorsBuilder
       # @param name [String] the suite's declared name
       # @param source_path [String] the `.behaviors` file's own path
@@ -129,9 +113,7 @@ module Hecks
       # @return [String] `text`, unchanged
       def vision(text) = @vision = text
 
-      # Relative to this `.behaviors` file, never to the filesystem's cwd
-      # or a same-stem convention — scope is a fact this file declares,
-      # not one a runner infers.
+      # Paths are relative to this `.behaviors` file, never the cwd.
       #
       # @param paths [Array<String>] paths to the files this suite's domain boots
       #   from, relative to the `.behaviors` file

data/lib/hecks/behaviors/expectations.rb

@@ -5,45 +5,11 @@ require_relative "../runtime/value"
 require_relative "../runtime/reaction_invocation"
 require_relative "../ports/persistence/binding_policy"
 
-# Hecks::Behaviors::Expectations
-#
-# ## What it does
-#
-# One test case, start to finish: take the suite's own runtime (booted
-# once for exactly what its `loads` names, reset to nothing between
-# tests — `runtime_for`), replay `setup` dispatches, dispatch (or query)
-# the command under test, check `expect`. Split out of
-# runner.rb the same way the file-count/sweep concern is split from a
-# single test's own execution.
-#
-# ## Deviations from a prior port
-#
-# Two deliberate deviations from a prior port of this same idea (read
-# before writing this, not reinvented):
-#
-# 1. A `setup` refusal and a refusal from the command under test are
-#    caught in separate rescue scopes. The prior port wrapped the whole
-#    test body — setups included — in one `rescue *REFUSAL_CLASSES`, so a
-#    broken setup could spuriously satisfy `expect refused: "..."` if its
-#    own refusal happened to match the expected substring. Here, any
-#    domain refusal during `setup` is unconditionally an error — the
-#    example never got to the situation it claims to test.
-#
-# 2. `emits:` is read off a `registry.event_log` diff around the tested
-#    dispatch, not off `Result#events` alone. `Result#events` only holds
-#    the events the outermost dispatch announced; a policy's own cascade
-#    reenters through the same `Dispatcher#dispatch` (`PolicyInterpreter
-#    #deliver` → `door.reenter` → `dispatch`), and every dispatch's
-#    events — outer and reentrant alike — land in the one shared
-#    `registry.event_log`, in order (`CommandRules::Emission#emit`,
-#    `PortOperationInterpreter#emit`/`#call`). Diffing that log's length
-#    before/after the tested dispatch is the one read that actually sees
-#    a cascade — this DSL has no `kind: :cascade` because cascades are
-#    always on and `emits:` is expected to see them.
+# Runs one behaviors test case: replays its setup dispatches, dispatches (or
+# queries) the command under test, and checks the result against `expect`.
 module Hecks
   module Behaviors
-    # See this file's own header above for what this module does and the
-    # two deliberate deviations from the prior port it's built from.
+    # Runs one behaviors test case: replays its setup, dispatches the command, checks `expect`.
     module Expectations
       module_function
 
@@ -66,6 +32,8 @@ module Hecks
 
         current_setup = nil
         begin
+          # Caught separately from the tested command's own refusal, so a broken
+          # setup can't spuriously satisfy `expect refused: "..."` by coincidence.
           test.setups.each do |setup|
             current_setup = setup
             dispatch_command(runtime, qualify(setup.command, nil, bluebooks, kind: :command), setup.args)
@@ -79,20 +47,9 @@ module Hecks
         error_result(test, "#{e.class}: #{e.message}")
       end
 
-      # One boot per suite, not per test. The isolation a test needs is a
-      # runtime with nothing in it — and a boot of the same files gives
-      # exactly that back for the price of `Registry#reset_runtime_state!`
-      # instead of ~2s of loading, verifying and era-checking the same
-      # bluebook again (chess: 76 behaviours, 155s of which was booting
-      # `chess.bluebook` 76 times). Keyed by the suite's own `loads` and
-      # their mtimes, so an edited bluebook boots fresh on the next test
-      # rather than running against a stale one — the property a watch
-      # loop or a long rspec session actually relies on. `runtime:` lets
-      # a caller that already holds a booted runtime (a spec, a REPL)
-      # hand it in; it is reset the same way.
-      # Not frozen — a real cache, mutated below (`RUNTIMES[key] ||=
-      # boot_and_guard(files)`) and by #reset!. False positive for
-      # Style/MutableConstant.
+      # Cached per suite, keyed by `loads`' file paths and mtimes, so a boot is
+      # reused across tests but an edited bluebook boots fresh on the next one.
+      # Mutated in place (`RUNTIMES[key] ||= boot_and_guard(files)`, and #reset!).
       # rubocop:disable-next Style/MutableConstant
       RUNTIMES      = {}
       RUNTIMES_LOCK = Mutex.new
@@ -115,16 +72,8 @@ module Hecks
         end
       end
 
-      # `reset_runtime_state!` only drops repository objects between
-      # tests (registry.rb) — sufficient isolation for `Memory`, whose
-      # `@records` is a plain per-instance ivar, so a fresh object really
-      # is a fresh store. Against anything else (Sqlite, Postgres) the
-      # rows themselves stay put: tests leak into each other, and a
-      # suite booted against a domain's real hecksagon writes to a real
-      # database. Refusing that wiring here, at boot, is the same shape
-      # of guard `BindingPolicy` already applies to a missing bind — the
-      # project's identity is refusing bad wiring up front, not
-      # discovering it mid-suite.
+      # Refuses at boot when any aggregate binds to a non-Memory adapter —
+      # `reset_runtime_state!` only resets Memory's own per-instance store.
       #
       # @param files [Array<String>] absolute paths to the bluebook/hecksagon/world
       #   files to boot
@@ -132,7 +81,7 @@ module Hecks
       #   Memory-only-guarded runtime
       # @raise [Malformed] if any aggregate is bound to a non-Memory adapter
       def boot_and_guard(files)
-        runtime = Hecks::Runtime::Loader.boot_files(files, install_facade: false)
+        runtime = Hecks::Runtime::Loader.boot_files(files, install_doors: false)
         guard_memory_only!(runtime)
         runtime
       end
@@ -209,17 +158,8 @@ module Hecks
         check_ok(test) || check_fields(test, settled_state(runtime, verb, result)) || pass_result(test)
       end
 
-      # A field expectation reads the aggregate as it stands once the
-      # dispatch and its whole cascade have run — the same "cascades are
-      # always on" reading `emits:` already commits to. `Result#state` is
-      # the wrong source for that: it snapshots the instance the outer
-      # dispatch saved, and a policy's own reentrant dispatch (a ply
-      # advancing off a Moved event, a move count bumping) hydrates and
-      # saves a fresh record afterward — so a field the cascade wrote
-      # read back stale (found live: `expect move_count: 1` got 0 while
-      # `emits:` saw MoveCountBumped in the same test). The repository
-      # holds the settled record; read it back by the id the dispatch
-      # itself answered with.
+      # Reads the aggregate back from the repository, not `Result#state` — a
+      # policy's own reentrant dispatch can re-save the record afterward.
       #
       # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the suite's
       #   booted runtime
@@ -241,44 +181,15 @@ module Hecks
         record ? record.state : (result.state || {})
       end
 
-      # A behaviors test writes a dispatch the way the guide's own chess
-      # examples do — receiver identity and command facts side by side
-      # (`label: "g", id: "wn", to: { file: 2, rank: 2 }`) — and since
-      # #335 the dispatcher's own `to:` keyword is the routing envelope,
-      # so forwarding those kwargs loose collides the moment a domain
-      # declares a command fact named `to` (chess does: every Move's own
-      # destination). Found live: every such test failed with "to: does
-      # not recognize file, rank" while this guide promised the spelling
-      # works. `ReactionInvocation.build` is #335's own seam for turning
-      # mixed facts into the strict envelope — identities lifted into
-      # `to:`, declared facts into `with:` — so a behaviors dispatch now
-      # goes through the exact same separation a policy's projection
-      # does. A verb that names a port operation (checked explicitly,
-      # below — "Pizzas::Order.PaymentGateway.Receive") keeps the loose
-      # passthrough instead: its own input already spells the port
-      # form's `to:`/`with:`, which the dispatcher's port branch reads
-      # directly, and `ReactionInvocation.build`'s explicit envelope
-      # expects a command's own declared attributes at the top level,
-      # not a port operation's already-wrapped `to:`/`with:` shape.
+      # Splits a mixed dispatch (receiver identity plus declared facts, e.g.
+      # `to: { file: 2, rank: 2 }`) into the dispatcher's strict `to:`/`with:` envelope.
       #
-      # Checks for a port operation directly rather than leaning on
-      # `resolve_target` to raise `UnknownVerb` for one — a refusal that held
-      # 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 does not happen, so this checks directly instead.
-      #
-      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the suite's
-      #   booted runtime
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the suite's booted runtime
       # @param verb [String] the command's dotted FQN, or a port operation's
-      # @param args [Hash{Symbol => Object}] the command's (or setup's) facts, mixing
-      #   receiver identity and declared arguments
-      # @return [Runtime::Dispatcher::Result, Runtime::RemoteDispatcher::Result] the
-      #   dispatch's own result
-      # @raise [Runtime::UnknownVerb] if `verb` is not fully qualified or names an
-      #   undeclared domain, aggregate, command, entity or port operation
-      # @raise [StandardError] any class in `Runtime::DOMAIN_REFUSALS` when the
-      #   domain refuses the call
+      # @param args [Hash{Symbol => Object}] the facts, mixing identity and declared arguments
+      # @return [Runtime::Dispatcher::Result, Runtime::RemoteDispatcher::Result] the dispatch result
+      # @raise [Runtime::UnknownVerb] if `verb` names an undeclared construct
+      # @raise [StandardError] any `Runtime::DOMAIN_REFUSALS` class, when the domain refuses
       def dispatch_command(runtime, verb, args)
         return runtime.dispatch_flat(verb, args) if port_operation?(runtime, verb)
 
@@ -297,10 +208,8 @@ module Hecks
         end
       end
 
-      # The same "Head.Rest" shape `Dispatcher#dispatch` and
-      # `ReactionInvocation#resolve_target` both already check — a bare
-      # domain/aggregate lookup plus a port-name lookup, no command
-      # resolution needed since all this asks is whether one exists.
+      # The same "Head.Rest" split `Dispatcher#dispatch` already uses — just a
+      # domain/aggregate and port-name lookup, no command resolution needed.
       #
       # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the suite's
       #   booted runtime
@@ -358,12 +267,8 @@ module Hecks
         test.expect.keys.any? { |key| !SPECIAL_KEYS.include?(key) }
       end
 
-      # A field expectation on a query names one row's shape, so it only
-      # makes sense once the query has settled on exactly one — the same
-      # reason `expect status: "sold"` on a multi-row answer would be
-      # ambiguous about which row it's describing. `check_fields` itself
-      # stays row-shaped (it already is, for `run_command`'s settled
-      # state); this picks which row it reads.
+      # A field expectation on a query only makes sense once it has settled on
+      # exactly one row; this picks that row (or fails naming the row count).
       #
       # @param test [Behaviors::TestCase] the test case, for the fail message
       # @param rows [Array<Hash>, Hash] the query's own result
@@ -437,12 +342,8 @@ module Hecks
         fail_result(test, "expected refused: #{expected.inspect}, got #{msg.inspect}")
       end
 
-      # The real corpus this DSL is proven against writes VO-typed
-      # `expect` values both ways — bare (`expect kind: "bishop"`) and
-      # wrapped (`expect kind: { value: "bishop" }`). A live record's
-      # field always comes back as a `Hecks::Runtime::Value`;
-      # normalizing both sides to the same bare-scalar-or-plain-hash
-      # shape is the one comparison that accepts either spelling.
+      # Normalizes both `expect` spellings (bare or `{value: ...}`) and a live
+      # `Hecks::Runtime::Value` field to the same bare-scalar-or-plain-hash shape.
       #
       # @param value [Object] a stored field's value, or an `expect` value to compare
       #   it against
@@ -455,13 +356,8 @@ module Hecks
         value
       end
 
-      # A bare `tests`/`setup` command name carries no domain — `loads`
-      # can name more than one bluebook, so resolution searches every
-      # aggregate across every bluebook the suite booted for the one that
-      # actually declares the command. `on:` (when given, only ever on
-      # the tested command — `setup` never receives it, see the DSL
-      # contract) narrows the search to one aggregate by name instead of
-      # searching all of them.
+      # Searches every aggregate of every bluebook the suite booted for the one
+      # declaring `command`; `on:` narrows the search to one aggregate by name.
       #
       # @param command [String, Symbol] a bare verb, or an already-dotted FQN
       # @param on_aggregate [String, Symbol, nil] the aggregate to search, or nil to
@@ -478,11 +374,8 @@ module Hecks
         disambiguate_qualified_name(candidates, command, kind, bluebooks)
       end
 
-      # Finds every aggregate that could be what a bare command/query name refers to.
-      #
-      # **The search** — every (bluebook, aggregate) pair that declares a
-      # command/query named `command`, narrowed to `on_aggregate` by name
-      # when given.
+      # Finds every (bluebook, aggregate) pair that declares a command/query
+      # named `command`, narrowed to `on_aggregate` by name when given.
       #
       # @param command [String, Symbol] the bare verb to search for
       # @param on_aggregate [String, Symbol, nil] the aggregate to search, or nil to
@@ -502,11 +395,8 @@ module Hecks
         pairs.select { |_, agg| agg.public_send(members).any? { |m| m.hecks_name == command.to_s } }
       end
 
-      # Resolves a search's candidates to exactly one dotted FQN, or refuses.
-      #
-      # **The report** — zero candidates and more-than-one candidates both
-      # refuse (with a different message); exactly one resolves to its
-      # dotted FQN.
+      # Resolves a search's candidates to exactly one dotted FQN; zero or more
+      # than one both refuse, each with a different message.
       #
       # @param candidates [Array<Array(Bluebook::Chapter, Bluebook::Aggregate)>] the
       #   matching (chapter, aggregate) pairs found by `qualify_candidates`

data/lib/hecks/behaviors/ir.rb

@@ -1,29 +1,17 @@
 # Hecks::Behaviors::{TestSetup,TestCase,BehaviorsSuite}
 #
-# The `.behaviors` authoring surface's own IR — plain Structs, holding
-# exactly what `Hecks.behaviors "Name" do ... end` collected. Deliberately
-# not part of `Hecks::IR`/`emits_ir` — a behaviors suite is never
-# collected into a domain Registry (see `Hecks.behaviors`), never
-# dispatched through MetaValidator, and carries none of the self-hosted
-# round-trip machinery a real bluebook construct does. It is a test
-# artifact a runner reads on demand, not a domain a boot needs.
+# Plain Structs holding what `Hecks.behaviors "Name" do ... end` collected; a suite is never
+# collected into a domain Registry.
 module Hecks
-  # The `.behaviors` toolkit: the DSL a `.behaviors` file is written against
-  # (`Hecks.behaviors`, dsl.rb), the plain-Struct IR it builds (this file), the runner
-  # that boots a suite's domain and checks each test (runner.rb, expectations.rb), and
-  # an rspec shim for a consuming app's own suite (rspec.rb).
+  # The `.behaviors` toolkit: DSL, IR, runner and rspec shim.
   module Behaviors
     TestSetup = Struct.new(:command, :args, keyword_init: true)
 
     TestCase = Struct.new(:description, :tests_command, :on_aggregate, :kind,
                           :setups, :input, :expect, keyword_init: true) do
-      # Tells whether `tests_command` is already a fully qualified verb name.
+      # Whether `tests_command` is already a fully qualified verb name.
       #
-      # An already-dotted tests_command is a literal FQN; otherwise `on:`
-      # composes with the domain name resolved once setups/the tested
-      # dispatch actually run (see Expectations — the domain isn't known
-      # until `loads` is booted, so it's a runtime concern, not a field
-      # here).
+      # @return [Boolean] true when `tests_command` contains a `.`
       #
       # @return [Boolean] true when `tests_command` contains a `.`
       def dotted? = tests_command.to_s.include?(".")
@@ -34,9 +22,8 @@ module Hecks
       def query? = kind == :query
     end
 
-    # `loads` — absolute paths, already resolved against the `.behaviors`
-    # file's own directory by the DSL (`BehaviorsBuilder#loads`). `path` is
-    # the `.behaviors` file itself, kept for error messages.
+    # `loads` holds absolute paths resolved against the `.behaviors` file's directory;
+    # `path` is that file, kept for error messages.
     BehaviorsSuite = Struct.new(:name, :vision, :loads, :tests, :path, keyword_init: true)
   end
 end

data/lib/hecks/behaviors/rspec.rb

@@ -1,13 +1,8 @@
 require_relative "../behaviors"
 
-# Hecks::Behaviors::RSpec.describe_file(path) — the shim a consumer's
-# `bundle exec rspec` uses to run `.behaviors` files as ordinary examples,
-# one `it` per test, named by the test's own description string. Same
-# shape `spec/guides_spec.rb` uses for doctested guides: the file is
-# parsed at collection time (cheap — `Behaviors.parse`, no test actually
-# run yet, just enough to know the `it` names), and each test's own
-# `Expectations.run_one` runs lazily inside its own `it`, exactly when
-# rspec actually executes it.
+# Hecks::Behaviors::RSpec.describe_file(path) registers one `it` per test in a `.behaviors` file,
+# so a consumer's `bundle exec rspec` runs it. The file is parsed at collection time; each test
+# runs lazily inside its own `it`.
 #
 #   require "hecks/behaviors/rspec"
 #
@@ -16,19 +11,13 @@ require_relative "../behaviors"
 #   end
 module Hecks
   module Behaviors
-    # See this file's own header above for what `describe_file` does and
-    # how a consumer wires it into their own `bundle exec rspec` run.
+    # Registers one example per test in a `.behaviors` file so a consumer's suite runs it.
     module RSpec
       module_function
 
-      # Parses one `.behaviors` file and registers an rspec example group for it, one
-      # `it` per test named by the test's own description.
+      # Registers an rspec example group for one `.behaviors` file, one `it` per test.
       #
-      # @param path [String] the `.behaviors` file's path
-      # @return [void]
-      # @raise [RuntimeError] not raised by this call itself; wraps `parsed.parse_error`'s
-      #   message and is raised only when rspec later runs the generated "loads without a
-      #   parse error" example, so it surfaces as that example's failure
+      # A parse error surfaces as a failing "loads without a parse error" example.
       def describe_file(path)
         parsed = Behaviors.parse(path)