hecks 2.8.0 → 2.9.0

data/lib/hecks/release/runner/preflight.rb

@@ -5,18 +5,10 @@ require_relative "git"
 module Hecks
   module Release
     class Runner
-      # The checks that run before a release does anything: the tools are
-      # installed, the checkout is a clean, current `main`, the gem and the
-      # JavaScript client agree on a version, and the changelog names it.
-      #
-      # Every refusal says what to do about it.
+      # The checks that run before a release does anything: tools installed, a
+      # clean current `main`, matching versions, and a changelog entry.
       class Preflight
-        # What the checks learned about the release.
-        #
-        # @!attribute [r] version
-        #   @return [String] the version `lib/hecks/version.rb` declares
-        # @!attribute [r] sha
-        #   @return [String] the commit `HEAD` points at, which is also `origin/main`
+        # What the checks learned; `sha` is also `origin/main`, enforced by check_current.
         Facts = Struct.new(:version, :sha, keyword_init: true)
 
         INSTALL_HINTS = {
@@ -29,10 +21,6 @@ module Hecks
         VERSION_LINE = /^\s*VERSION\s*=\s*"(?<version>[^"]+)"/
         CLIENT_PACKAGE = "packages/hecks-client/package.json".freeze
 
-        # @param root [String] the repository root
-        # @param commands [#capture] runs the tool probes
-        # @param git [Git] the repository the release is cut from
-        # @param tools [Array<String>] the executables the release needs on PATH
         def initialize(root:, commands:, git:, tools:)
           @root = root
           @commands = commands
@@ -40,10 +28,7 @@ module Hecks
           @tools = tools
         end
 
-        # Runs every check.
-        #
-        # @return [Facts] the version and commit the release is cut from
-        # @raise [Refusal] on the first check that fails, naming the fix
+        # Runs every check; the first refusal stops it.
         def check!
           check_tools
           check_branch

data/lib/hecks/release/runner/tagger.rb

@@ -7,21 +7,14 @@ module Hecks
       # Makes sure the release tag `vX.Y.Z` is an annotated tag on the release
       # commit and is on origin, creating and pushing it only when it is missing.
       class Tagger
-        # @param git [Git] the repository the release is cut from
-        # @param console [Console] asks before the tag is created or pushed
-        # @param dry_run [Boolean] report what would happen and change nothing
         def initialize(git:, console:, dry_run:)
           @git = git
           @console = console
           @dry_run = dry_run
         end
 
-        # Brings the tag to the state described above, saying what it did.
-        #
-        # @param facts [Preflight::Facts] the version and commit being released
-        # @return [Boolean] false when the person declined the question, true otherwise
-        # @raise [Refusal] if the tag already points at another commit, locally or on origin
-        # @raise [CommandFailed] if creating or pushing the tag fails
+        # Brings the tag to the state described above, saying what it did; returns
+        # false only when the person declined the confirmation.
         def ensure!(facts)
           tag = "v#{facts.version}"
           local = local_commit(tag)

data/lib/hecks/release/runner.rb

@@ -11,39 +11,10 @@ require_relative "runner/ci_publisher"
 module Hecks
   module Release
     # Performs the release once the release PR has merged: tags the merge
-    # commit, publishes the gem to rubygems.org and gets the JavaScript client
-    # published to npm.
+    # commit, publishes the gem, and gets the JS client published to npm.
     #
-    # ## Why it exists
-    #
-    # A release is four steps that have to happen in one order, and only
-    # the contributing guide remembered it. This runs them in that order, refuses to
-    # start from a checkout that is not the merged `main`, and can be run again:
-    # it asks the registries what is already published and skips it, so a run
-    # that died between the gem and the package resumes at the package.
-    #
-    # ## Steps
-    #
-    # 1. Preflight: tools installed, on a clean `main` equal to `origin/main`,
-    #    the gem and the client at one version, the changelog naming it.
-    # 2. Published state: which of the gem and the package are already out.
-    # 3. Tag: an annotated `vX.Y.Z` on the release commit, pushed to origin.
-    # 4. Gem: `bin/release_gem`, unchanged.
-    # 5. npm, one of two ways:
-    #    - by default CI publishes: the tag triggers `publish-client.yml`, which
-    #      uses npm trusted publishing, and this waits for the version to appear
-    #      (`--no-wait` skips the wait);
-    #    - with `--npm-local` this publishes from the machine, with a
-    #      bypass-two-factor token 1Password holds: the way to make the first
-    #      publish, before trusted publishing can be configured, and the fallback
-    #      when CI is down.
-    #
-    # ## Injectable commands and time
-    #
-    # Every process is started through `commands`, any object answering
-    # `capture(*argv, env:, chdir:)` and `run!(*argv, env:, chdir:)` like
-    # {Commands}, so a spec drives the whole release with a recorder. The wait for
-    # CI takes its clock and its pause as callables for the same reason.
+    # Idempotent: it asks the registries what is already published and skips
+    # it, so a run that died between the gem and the package resumes at the package.
     class Runner
       # Which steps to run and how.
       class Options

data/lib/hecks/rendering.rb

@@ -1,19 +1,9 @@
 require "json"
 
 module Hecks
-  # How a value reads inside a refusal, in one place, because a refusal is an
-  # answer and its wording is contract — pinned byte-for-byte by the corpus.
+  # How a value reads inside a refusal; the wording is contract, pinned by the corpus.
   #
-  # `inspect` and JSON agree on scalars and disagree on everything composite :
-  # a hash is `{"cents"=>100}` against `{"cents":100}`, an array is `["a", "b"]`
-  # against `["a","b"]`. Each such spelling is invisible until a composite
-  # actually reaches a message, which is why both known cases were found by
-  # something deliberately passing the wrong shape rather than by review — the
-  # first by hand in spec/corpus/banking.json, the second by bin/fuzz, at a
-  # different site, after the first was patched where it was found.
-  #
-  # So it lives here rather than in whichever file noticed it, and the house style
-  # is JSON because that is what every other refusal in the corpus already prints.
+  # `inspect` and JSON disagree on composites, so refusals use JSON throughout.
   module Rendering
     module_function
 
@@ -28,20 +18,8 @@ module Hecks
       when nil then "nil"
       when Hash, Array then JSON.generate(value)
       else
-        # A Hecks::Runtime::Value reaching a refusal message (an
-        # arithmetic op's own `amount`/`current`, an Admissibility
-        # `current`, ...) had no case here, falling straight through to
-        # Ruby's own #inspect and leaking a raw object pointer
-        # ("#<Hecks::Runtime::Value:0x...>") into an otherwise
-        # correct domain refusal. Duck-typed on `respond_to?(:to_h)`
-        # rather than naming `Runtime::Value` directly — `Runtime::Value`
-        # itself requires this file (`runtime/value.rb`'s own
-        # `require_relative "../rendering"`), so naming it here would be
-        # circular. A single-field wrapper (the overwhelming common case
-        # — an amount, an id, a lifecycle field) unwraps to its bare
-        # scalar, described recursively; a genuinely multi-field value
-        # renders as its fields' JSON, same as a bare Hash already does
-        # two lines up.
+        # Duck-typed on `to_h`: naming Runtime::Value here would be circular, since
+        # it requires this file. A one-field wrapper unwraps to its bare scalar.
         if value.respond_to?(:to_h) && !value.is_a?(Hash) && !value.is_a?(Array)
           fields = value.to_h
           fields.size == 1 ? describe(fields.values.first) : JSON.generate(fields)

data/lib/hecks/router/namespace_installer.rb

@@ -3,22 +3,13 @@ require_relative "../facade/handle"
 
 module Hecks
   class Router
-    # Installs optional Ruby syntax over an already-loaded router. FQN
-    # resolution stays in Router; this object only adapts it to constants and
-    # method calls.
+    # Installs optional Ruby syntax over an already-loaded router; FQN
+    # resolution stays in Router, this only adapts it to constants and methods.
     class NamespaceInstaller
-      # Returned by the `.options(version:)` method installed on each
-      # namespace module — forwards any command/query verb called on it
-      # to the router, pinned to this specific FQN version rather than
-      # the router's default resolution.
+      # Returned by `.options(version:)`; forwards command/query verbs to the
+      # router, pinned to this FQN version rather than the router's default.
       class OptionsProxy
-        # @param router [Router] router to dispatch resolved calls through
-        # @param realm [String, nil] realm segment of the FQN this proxy pins
-        # @param domain [String] domain segment of the FQN this proxy pins
-        # @param aggregate [String, nil] aggregate segment, or nil for a domain-level query
-        # @param options [Hash{Symbol => Object}] the `.options(...)` call's keywords; only
-        #   `:version` is accepted
-        # @raise [ArgumentError] if `options` has a key other than `:version`
+        # Only the `:version` keyword is accepted; any other key raises `ArgumentError`.
         def initialize(router:, realm:, domain:, aggregate:, options:)
           unknown = options.keys - [:version]
           raise ArgumentError, "unknown router options: #{unknown.join(', ')}" unless unknown.empty?
@@ -52,16 +43,12 @@ module Hecks
         end
       end
 
-      # @param router [Router] router whose current routes get Ruby constants and methods
       def initialize(router)
         @router = router
       end
 
-      # Installs every current-version route as a namespace constant/method,
-      # plus the aggregate `find`/`all`/`count`/`events`/`repository` door and
-      # short `Aggregate.verb` shortcuts.
-      #
-      # @return [self]
+      # Installs every current-version route as a namespace constant/method, plus
+      # the aggregate CRUD door and short `Aggregate.verb` shortcuts.
       def install!
         current_entries.each { |entry| install_namespace_entry(entry) }
         install_shortcuts!
@@ -90,18 +77,8 @@ module Hecks
         end
       end
 
-      # `.find`/`.all`/`.count`/`.events`/`.repository` — the same read/CRUD
-      # surface `Facade::Surface::AggregateDoor` gives a plain `Hecks
-      # .boot`, missing here until now: `install_namespace_entry` above
-      # installs one method per declared verb, so an aggregate with no
-      # commands or queries of its own shape (or simply never asked for
-      # a `find`-shaped query) had no way to look up one record by id
-      # through the router surface at all — real gap, hit live building
-      # a `List` aggregate meant to be read this way. Grouped by
-      # (realm, domain, aggregate) rather than installed per-verb,
-      # because unlike a command or query this is the same five methods
-      # regardless of which verb happened to trigger this aggregate's
-      # own namespace module into existing.
+      # `.find`/`.all`/`.count`/`.events`/`.repository`, matching `Hecks.boot`'s
+      # door; grouped by (realm, domain, aggregate) since the five don't vary by verb.
       def install_aggregate_doors!
         current_entries.reject { |entry| entry.fqn.aggregate.nil? }
                        .group_by { |entry| [entry.fqn.realm, entry.fqn.domain, entry.fqn.aggregate] }
@@ -138,10 +115,9 @@ module Hecks
         current_entries.reject { |entry| entry.fqn.aggregate.nil? }
                        .group_by { |entry| [entry.fqn.aggregate, entry.fqn.verb] }
                        .each do |(aggregate, verb), candidates|
-          # Bounded chapters wrap in their own module (`Domain::Aggregate`)
-          # so two BCs can both declare `Person` without colliding on
-          # Object::Person. Folder-spread files of the same chapter still
-          # get the shortcut — they are not BCs.
+          # Bounded chapters wrap in their own module (`Domain::Aggregate`) so two
+          # BCs can both declare `Person` without colliding on `Object::Person`.
+          # Folder-spread files of the same chapter aren't BCs, so they still get it.
           next if bounded_chapter?(candidates)
 
           shortcut_target(aggregate).define_singleton_method(verb) do |**args|

data/lib/hecks/router.rb

@@ -16,8 +16,7 @@ module Hecks
     # @return [Router] the built router
     def self.load(root) = new(Bluebook::ProjectLoader.load(root))
 
-    # Install one project router for ordinary application calls. The explicit
-    # `Router.load` API remains useful for tests and embedded hosts.
+    # Installs one project router as `.default` for ordinary application calls.
     #
     # @param root [String] project root to discover bluebooks under
     # @return [Router] the booted router, also stored as `.default`
@@ -75,14 +74,12 @@ module Hecks
     # Dispatches a command to its resolved aggregate.
     #
     # @param address [String] a fully-qualified command address, realm included
-    # @param args [Hash] command facts, plus the dispatcher's optional `:to`, `:with`,
-    #   and `:saga_correlation` keys
+    # @param args [Hash] command facts, plus optional `:to`, `:with`, `:saga_correlation`
     # @return [Runtime::Dispatcher::Result] the dispatch result
     # @raise [UnknownAddress] if `address` has no realm, or names no known route
     # @raise [WrongVerbKind] if `address` names a query
     # @raise [Runtime::UnknownVerb] if the resolved verb names something undeclared
-    # @raise [StandardError] any class in `Runtime::DOMAIN_REFUSALS` when the domain refuses
-    #   the call
+    # @raise [StandardError] any `Runtime::DOMAIN_REFUSALS` class when the domain refuses
     # @raise [Runtime::StaleWrite] if concurrent writers beat this one through every retry
     # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
     def dispatch(address, **args)
@@ -97,13 +94,12 @@ module Hecks
     # @param address [String] a fully-qualified query address, realm included
     # @param args [Hash{Symbol => Object}] the query's declared arguments
     # @return [Array<Hash>] one row Hash per match; see `Runtime::Dispatcher#query`
-    #   for the exact shape per address kind
     # @raise [UnknownAddress] if `address` has no realm, or names no known route
     # @raise [WrongVerbKind] if `address` names a command
     # @raise [Runtime::UnknownVerb] if the resolved verb names something undeclared
     # @raise [Runtime::NotFound] if a read model's root reference names no record
     # @raise [Runtime::TypeMismatch] if an argument cannot be coerced to its declared type
-    # @raise [KeyError] if a rooted read model is asked without its reference argument
+    # @raise [KeyError] if a rooted read model lacks its reference argument
     # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
     def query(address, **args)
       entry = resolve(address)

data/lib/hecks/runtime/aggregate_lock.rb

@@ -1,29 +1,10 @@
 module Hecks
   module Runtime
-    # **A process-wide, striped mutex registry** — the concurrency-control
-    # mechanism for every adapter that does not declare
-    # `:optimistic_concurrency` (Heki, Memory today; see
-    # `CommandInterpreter#call`/`EntityInterpreter#call`, which choose
-    # between this and Postgres's CAS+retry purely off
-    # `repository.capabilities`).
+    # A process-wide, striped mutex registry, keyed by `[domain, aggregate, id]`.
+    # Serializes hydrate-through-save for adapters without `:optimistic_concurrency`.
     #
-    # Why a lock suffices here and CAS is not needed: both adapters hold
-    # process-local data. `Adapters::Memory.tenant_capable?`'s own comment
-    # states the confirmed fact this relies on — two `Runtime.boot` calls
-    # get two entirely separate adapter instances; there is never a second
-    # process writing the same Heki file or the same Memory Hash, only
-    # possibly other threads within this one process. A `Mutex` held for
-    # the full hydrate-through-save critical section closes the identical
-    # lost-update gap CAS closes for Postgres, with no schema, no version
-    # column, and no retry loop — the second thread simply doesn't start
-    # its own hydrate until the first thread's save has landed.
-    #
-    # **Striped, not one global lock**: keyed by `[domain, aggregate.hecks_name,
-    # id]`, so two dispatches against two different records never block
-    # each other. The registry Hash itself is guarded by its own top-level
-    # Mutex only for the moment a new per-key Mutex is created — two
-    # threads locking different keys for the first time never wait on one
-    # another beyond that brief creation window.
+    # A lock suffices because those adapters (Heki, Memory) hold process-local data:
+    # only threads of this process can write the same record.
     module AggregateLock
       @registry_lock = Mutex.new
       @locks = {}
@@ -31,19 +12,13 @@ module Hecks
       class << self
         # Returns the Mutex striped to one record, creating it on first use.
         #
-        # `AggregateLock.for(domain, aggregate, id).synchronize { ... }`
-        # `id: nil` — identity could not be resolved yet (see
-        # `Identity.best_effort`) — locks by aggregate type alone, coarser
-        # (every record of this aggregate serializes against every other)
-        # but still correct: it can only ever make dispatch more
-        # conservative than a resolved id would.
+        #   AggregateLock.for(domain, aggregate, id).synchronize { ... }
         #
         # @param domain [String] the domain the aggregate belongs to
         # @param aggregate [Bluebook::Aggregate] the aggregate being dispatched
-        # @param id [String, nil] the resolved record id, or nil to stripe by aggregate type
-        #   alone
-        # @return [Mutex] the mutex for this `[domain, aggregate, id]` key, held for the full
-        #   hydrate-through-save critical section
+        # @param id [String, nil] the record id; nil locks by aggregate type alone, which
+        #   is coarser but still correct
+        # @return [Mutex] the mutex for this `[domain, aggregate, id]` key
         def for(domain, aggregate, id = nil)
           key = id.nil? ? [domain.to_s, aggregate.hecks_name] : [domain.to_s, aggregate.hecks_name, id.to_s]
           @registry_lock.synchronize { @locks[key] ||= Mutex.new }

data/lib/hecks/runtime/boot_gates.rb

@@ -1,24 +1,9 @@
 module Hecks
   module Runtime
-    # A boot's own small set of phase-tagged, conditionally-present gates —
-    # ADR 0031. Registration is instance-scoped, one per `Loader.boot`
-    # call, never a module-level singleton: a process that boots more than
-    # one registry in its lifetime (every spec suite does) must never let
-    # one boot's capability profile leak into the next boot's gate list.
+    # A boot's own set of phase-tagged, conditionally-present gates (ADR 0031).
+    # A gate is anything responding to `.call(registry, directory)`; run in registration order.
     #
-    # A gate is anything `.call(registry, directory)`-able — an existing
-    # module method handed over as a `Method` object (`EraCheck.method
-    # (:check_lineage!)`) needs no wrapper; a bare block does. Phases run
-    # in the order `run!` is called, gates within a phase in registration
-    # order — today exactly one gate per phase, so ordering among
-    # same-phase gates has never been exercised.
-    #
-    # This is deliberately not the same registry `Hecks::Projector` uses
-    # (ADR 0027) — that one is a process-wide, static IR-in/artifact-out
-    # registry with no bindings and no live-state mutation; this one is
-    # per-boot and gates real I/O (a Postgres mint, a saga-store read).
-    # Sharing a primitive between them is deferred until a third consumer
-    # actually wants it (0031's own Rejected Alternatives).
+    # Instance-scoped, one per `Loader.boot`, so one boot's gates never leak into the next.
     class BootGates
       # @return [void]
       def initialize

data/lib/hecks/runtime/caller.rb

@@ -1,38 +1,14 @@
 module Hecks
   module Runtime
-    # Who is dispatching, bound for the duration of a block — the ambient
-    # counterpart to `Runtime.with_registry`, but `Thread.current`-backed
-    # rather than a plain module ivar: registry-binding happens at boot
-    # time (single-threaded by construction), this happens at dispatch
-    # time, which a future per-request caller (docs/rails-integration.md's
-    # still-unbuilt `WebDoor`) needs to bind safely under concurrency.
-    #
-    # A child `Thread.new` spawned mid-block does not inherit this — plain
-    # Ruby thread-local semantics — but nothing in this codebase spawns a
-    # worker thread mid-dispatch today, so this is a fact worth naming
-    # rather than a gap worth solving.
+    # Who is dispatching, bound for the duration of a block.
+    # `Thread.current`-backed, so per-request callers bind safely under concurrency;
+    # a child thread spawned mid-block does not inherit it.
     module Caller
-      # `actor_id` is optional, on top of the role that has always been
-      # here — a caller that states only a role (every caller before this)
-      # is checked the way it always was, string equality against the
-      # command's own `role`. A caller that also names who it is lets
-      # `CommandRules::Authorization` check a real Governance
-      # `RoleAssignment` instead, once the command's domain has Governance
-      # attached — see that module's own header for the full split.
+      # The bound caller: a role, plus optional `actor_id`, `as_of` and `scope`.
       #
-      # `as_of` and `scope` are both optional too, and both self-asserted
-      # by the caller rather than derived from the command — deliberately:
-      # `as_of` is filled at the door from `Ports::Clock.now`, never
-      # inside the interpreter (see `Ports::Clock`'s own header), so
-      # there is no other place to source it from. `scope` stays here
-      # rather than becoming a command-level DSL construct on purpose —
-      # a scope check that lived in the bluebook would put an
-      # authorization concern inside the domain declaration itself; this
-      # keeps it an application-boundary fact instead, the same shape
-      # `role`/`actor_id` already are. The tradeoff: a caller states what
-      # scope it is acting in, and `holds_role?` verifies a live grant
-      # exists for that scope — it does not independently confirm the
-      # scope matches whatever the command's own target data belongs to.
+      # All but `role` are self-asserted by the caller, not derived from the command;
+      # `scope` is deliberately not a DSL construct, and `holds_role?` checks only that a grant
+      # exists for it, not that it matches the command's target data.
       Current = Struct.new(:role, :actor_id, :as_of, :scope, keyword_init: true)
 
       module_function
@@ -43,27 +19,17 @@ module Hecks
       #   block is on the stack for this thread
       def current = Thread.current[:hecks_caller]
 
-      # Binds the ambient caller for the duration of the block, restoring whatever
-      # caller (if any) was bound before, even if the block raises.
+      # Binds the ambient caller for the duration of the block, restoring the previous
+      # one even if the block raises.
       #
-      # `actor_id`, `as_of` and `scope` are each optional, self-asserted facts about
-      # the caller rather than derived from the command — see `Current`'s own header
-      # above for why each stays here instead of becoming a command-level DSL
-      # construct.
-      #
-      # @param role [String] the role the caller states it holds, checked by string
-      #   equality against the command's declared `role`
-      # @param actor_id [String, nil] who the caller is; when given, lets
-      #   `CommandRules::Authorization` check a real Governance `RoleAssignment`
-      #   instead of the bare role-string comparison
-      # @param as_of [Integer, nil] Unix epoch seconds the caller asserts as "now",
-      #   filled at the door from `Ports::Clock.now`; nil leaves a `RoleAssignment`'s
-      #   `starts_at` unchecked
-      # @param scope [String, nil] the scope the caller states it is acting in,
-      #   checked against the matching `RoleAssignment`'s own `scope`; nil skips
-      #   that check
-      # @yield the code that should see `role`/`actor_id`/`as_of`/`scope` as the
-      #   ambient caller
+      # @param role [String] the role the caller holds, checked against the command's `role`
+      # @param actor_id [String, nil] who the caller is; when given, `CommandRules::Authorization`
+      #   checks a real Governance `RoleAssignment`
+      # @param as_of [Integer, nil] Unix epoch seconds taken as "now"; nil leaves a
+      #   `RoleAssignment`'s `starts_at` unchecked
+      # @param scope [String, nil] the scope acted in, checked against the `RoleAssignment`'s
+      #   `scope`; nil skips that check
+      # @yield the code that sees these values as the ambient caller
       # @return [Object] the block's result
       def as(role:, actor_id: nil, as_of: nil, scope: nil)
         previous = Thread.current[:hecks_caller]
@@ -75,14 +41,8 @@ module Hecks
         Thread.current[:hecks_caller] = previous
       end
 
-      # Clears the ambient caller for the duration of the block, restoring
-      # whatever caller (if any) was bound before, even if the block raises.
-      #
-      # A reaction is the system acting, not the caller who happened to be
-      # on the stack when the triggering command ran — `Dispatcher#reenter`
-      # clears the ambient caller around a reaction's own dispatch so a
-      # triggering caller's role can neither satisfy nor block a reaction
-      # command it has nothing to do with.
+      # Clears the ambient caller for the duration of the block, restoring the previous one.
+      # A reaction is the system acting, so `Dispatcher#reenter` clears the caller around it.
       #
       # @yield the code that should see no ambient caller bound
       # @return [Object] the block's result

data/lib/hecks/runtime/capability_graph.rb

@@ -1,18 +1,7 @@
 module Hecks
   module Runtime
-    # Which ports a boot can actually fulfill, read off the registry it already
-    # holds. `registry.ports` names every port a domain declared a dependency
-    # on ; `registry.adapters` names every adapter wired to implement one — the
-    # same `adapter.port == port.name` match `Ports::Extraction` and
-    # `Ports::IdentityGeneration` already make for themselves, one at a time,
-    # each time they resolve. This is that same question asked once, for
-    # every port at once, so a gap in the wiring is something a caller can ask
-    # about rather than something a live dispatch discovers by refusing.
-    #
-    # `cycles` answers `[]`, always, and honestly: nothing in this port model
-    # lets one port depend on another — a port names a verb and a signal, an
-    # adapter names the port it implements, and neither can point at a third
-    # port. There is no edge for a cycle to be made of.
+    # Which ports a boot can fulfill: each declared port matched to the adapters wired to it,
+    # so a wiring gap can be asked about before a dispatch refuses.
     class CapabilityGraph
       # @param registry [Runtime::Registry] the booted registry to read ports and adapters from
       # @return [void]
@@ -20,9 +9,7 @@ module Hecks
         @registry = registry
       end
 
-      # { port name => [adapter name, ...] }, for every port the registry
-      # declares — including the ports nothing implements, so a caller can
-      # tell "declared, unfulfilled" from "never declared at all".
+      # Maps each declared port's name to the names of its adapters, unfulfilled ports included.
       #
       # @return [Hash{String => Array<String>}] each declared port's name mapped to the names
       #   of every adapter bound to it (empty when none are)
@@ -30,17 +17,14 @@ module Hecks
         @fulfillments ||= @registry.ports.each_key.to_h { |name| [name, adapters_for(name)] }
       end
 
-      # The ports with zero adapters bound — the gap `Runtime::WiringError`
-      # would otherwise only surface at the moment something tries to dispatch
-      # through one.
+      # The ports with zero adapters bound.
       #
       # @return [Array<String>] the names of every declared port with no adapter bound to it
       def unfulfilled
         fulfillments.select { |_, adapters| adapters.empty? }.keys
       end
 
-      # Reports the port-dependency cycles this registry has — always none; see the module
-      # header for why no port model here can express one.
+      # Reports the port-dependency cycles; always none, as a port cannot depend on another port.
       #
       # @return [Array] always empty
       def cycles = []