hecks 2.7.0 → 2.9.0

data/lib/hecks/release/runner.rb

@@ -0,0 +1,215 @@
+require_relative "runner/commands"
+require_relative "runner/console"
+require_relative "runner/git"
+require_relative "runner/preflight"
+require_relative "runner/published"
+require_relative "runner/tagger"
+require_relative "runner/gem_publisher"
+require_relative "runner/npm_publisher"
+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, and gets the JS client published to npm.
+    #
+    # 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
+        # @return [Boolean] run every check and build, but tag, push and publish nothing
+        attr_reader :dry_run
+
+        # @param dry_run [Boolean] run every check and build, but tag, push and publish nothing
+        # @param gem_only [Boolean] publish the gem, not the package
+        # @param npm_only [Boolean] do the npm step only, not the gem: wait for CI's publish, or
+        #   with `npm_local` publish from here
+        # @param npm_local [Boolean] publish the package from this machine, not by CI
+        # @param no_wait [Boolean] do not wait for CI's publish to reach npm
+        # @param yes [Boolean] answer every confirmation yes
+        # @raise [ArgumentError] if the flags contradict each other
+        def initialize(dry_run: false, gem_only: false, npm_only: false, npm_local: false, no_wait: false, yes: false)
+          check_flags(gem_only, npm_only, npm_local, no_wait)
+
+          @dry_run = dry_run
+          @gem_only = gem_only
+          @npm_only = npm_only
+          @npm_local = npm_local
+          @no_wait = no_wait
+          @yes = yes
+        end
+
+        # Says whether confirmations are answered automatically.
+        #
+        # @return [Boolean] true under `--yes`
+        def yes?
+          @yes
+        end
+
+        # Says whether the gem step is in scope.
+        #
+        # @return [Boolean] true unless `--npm-only`
+        def gem?
+          !@npm_only
+        end
+
+        # Says whether the npm step is in scope.
+        #
+        # @return [Boolean] true unless `--gem-only`
+        def npm?
+          !@gem_only
+        end
+
+        # Says whether the package is published from this machine.
+        #
+        # @return [Boolean] true under `--npm-local`
+        def npm_local?
+          @npm_local
+        end
+
+        # Says whether to wait for CI's publish to reach npm.
+        #
+        # @return [Boolean] true unless `--no-wait`
+        def wait?
+          !@no_wait
+        end
+
+        private
+
+        def check_flags(gem_only, npm_only, npm_local, no_wait)
+          raise ArgumentError, "--gem-only and --npm-only cannot be combined" if gem_only && npm_only
+          raise ArgumentError, "--gem-only and --npm-local cannot be combined" if gem_only && npm_local
+          return unless no_wait && npm_local
+
+          raise ArgumentError, "--no-wait applies to CI's publish, so it cannot be combined with --npm-local"
+        end
+      end
+
+      # @param root [String] the repository root
+      # @param options [Options] which steps to run and how
+      # @param commands [#capture, #run!] starts every process the release runs
+      # @param input [IO] where confirmations are read from
+      # @param out [IO] where progress is written
+      # @param err [IO] where refusals and failures are written
+      # @param pause [#call] sleeps for a number of seconds while waiting for CI
+      # @param now [#call] answers the current time in seconds, monotonically, while waiting for CI
+      def initialize(root:, options: Options.new, commands: Commands.new, input: $stdin, out: $stdout, err: $stderr,
+                     pause: ->(seconds) { sleep(seconds) }, now: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+        @root = root
+        @options = options
+        @commands = commands
+        @console = Console.new(input: input, out: out, err: err, assume_yes: options.yes?)
+        @git = Git.new(root: root, commands: commands)
+        @published = Published.new(root: root, commands: commands)
+        @ci = CiPublisher.new(root: root, published: @published, console: @console, pause: pause, now: now)
+      end
+
+      # Runs the release.
+      #
+      # @return [Integer] 0 when the release finished or had nothing to do, 1 when a check refused,
+      #   a step failed, CI's publish did not arrive in time or a confirmation was declined
+      def call
+        facts = Preflight.new(root: @root, commands: @commands, git: @git, tools: tools).check!
+        pending = pending_steps(facts.version)
+        require_workflow(pending)
+        return declined unless Tagger.new(git: @git, console: @console, dry_run: @options.dry_run).ensure!(facts)
+
+        publish(facts, pending)
+      rescue Refusal, CommandFailed => e
+        @console.warn(e.message)
+        1
+      end
+
+      private
+
+      def tools
+        list = %w[git curl]
+        list << "gem" if @options.gem?
+        list << "npm" if @options.npm?
+        list << "op" if !@options.dry_run && (@options.gem? || @options.npm_local?)
+        list
+      end
+
+      def pending_steps(version)
+        [
+          (:gem if @options.gem? && !done?("hecks #{version} is already on rubygems.org", @published.gem?(version))),
+          (:npm if @options.npm? && !done?("@hecks/client #{version} is already on npm", @published.npm?(version)))
+        ].compact
+      end
+
+      def done?(message, published)
+        @console.say("#{message}; skipping.") if published
+        published
+      end
+
+      def ci_publishes?(pending)
+        pending.include?(:npm) && !@options.npm_local?
+      end
+
+      def require_workflow(pending)
+        return unless ci_publishes?(pending) && !@ci.workflow?
+
+        raise Refusal, "#{CiPublisher::WORKFLOW} is not in this checkout, so CI cannot publish @hecks/client; " \
+                       "publish it from here with --npm-local (the first publish, before trusted publishing is set up)"
+      end
+
+      def publish(facts, pending)
+        if pending.empty?
+          @console.say("Nothing to publish for #{facts.version}.")
+          return 0
+        end
+        return declined unless @options.dry_run || publish_confirmed?(facts.version, pending)
+
+        run_steps(facts.version, pending)
+      end
+
+      def publish_confirmed?(version, pending)
+        targets = []
+        targets << "hecks #{version} to rubygems.org" if pending.include?(:gem)
+        targets << "@hecks/client #{version} to npm" if pending.include?(:npm) && @options.npm_local?
+        return true if targets.empty?
+
+        suffix = ci_publishes?(pending) ? " (CI then publishes @hecks/client from the tag)" : ""
+        @console.confirm?("Publish #{targets.join(' and ')}#{suffix}? This cannot be undone.")
+      end
+
+      def run_steps(version, pending)
+        dry_run = @options.dry_run
+        publish_gem(version, dry_run) if pending.include?(:gem)
+        return 1 if pending.include?(:npm) && !publish_npm!(version, dry_run, ci_publishes?(pending))
+
+        @console.say(dry_run ? "Dry run complete; nothing was tagged, pushed or published." : "Released hecks #{version}.")
+        0
+      end
+
+      def publish_gem(version, dry_run)
+        GemPublisher.new(root: @root, commands: @commands, console: @console).publish!(version, dry_run: dry_run)
+      end
+
+      def publish_npm!(version, dry_run, via_ci)
+        return wait_for_ci!(version, dry_run) if via_ci
+
+        NpmPublisher.new(root: @root, commands: @commands, console: @console).publish!(version, dry_run: dry_run)
+        true
+      rescue CommandFailed => e
+        @console.warn("npm publish failed: #{e.message}")
+        unless dry_run
+          @console.warn("Finish the release with: bin/release --npm-only --npm-local (published steps are not repeated)")
+        end
+        raise
+      end
+
+      def wait_for_ci!(version, dry_run)
+        arrived = @ci.wait!(version, dry_run: dry_run, wait: @options.wait?)
+        @console.warn(CiPublisher.timeout_hint(version)) unless arrived
+        arrived
+      end
+
+      def declined
+        @console.warn("Aborted; nothing was published.")
+        1
+      end
+    end
+  end
+end

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 = []