hecks 2.7.0 → 2.9.0

data/lib/hecks/ports/authentication.rb

@@ -2,27 +2,12 @@ require_relative "../runtime/registry"
 
 module Hecks
   module Ports
-    # The OIDC handshake itself — building the URL a browser goes to,
-    # and turning the code a provider sends back into a Hash of verified
-    # claims (`issuer`, `subject`, `email`, `email_verified`). Resolved the same way every
-    # other port here resolves its adapter: one adapter registry-wide
-    # answers this, not a per-aggregate binding, since a domain has no
-    # reason to want a different sign-in provider per aggregate.
-    #
-    # The other half of "who is this" — what a verified pair means to
-    # this app, whether it resolves to an existing Identity — is
-    # `Ports::IdentityResolution`'s job, not this one's. This port only
-    # ever talks to the external provider; it never touches the
-    # registry's own Identity/Governance data (it takes `registry`
-    # purely to resolve which adapter answers it, same as every port
-    # here already does).
+    # The OIDC handshake: builds the provider URL and turns the returned code into verified claims.
+    # One adapter registry-wide answers it; it never touches the registry's Identity data.
     module Authentication
       NAME = "authentication".freeze
 
-      # A sign-in that could not be verified — a state mismatch, a failed code
-      # exchange, a missing or invalid ID token. An adapter wraps its own
-      # libraries' errors into this, so a caller rescues one class whichever
-      # provider answers the port.
+      # A sign-in that could not be verified (state mismatch, failed code exchange, bad ID token).
       class ValidationError < StandardError
       end
 
@@ -30,17 +15,13 @@ module Hecks
 
       # Builds the provider URL that starts a sign-in, with the CSRF state minted for it.
       #
-      # The caller keeps the state (in a session, typically) and hands it back to `verify`
-      # as `expected_state`.
+      # The caller keeps the state and hands it back to `verify` as `expected_state`.
       #
       # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
       # @return [Array(String, String)] the URL to send the browser to, then the fresh
       #   `state` value embedded in it
       # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
-      #   (see `adapter`)
       # @raise [KeyError] if the adapter's required configuration is unset
-      #   (`GoogleAuthentication` reads `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` and
-      #   `GOOGLE_REDIRECT_URI` with no defaults)
       def authorization_url(registry)
         adapter(registry).authorization_url
       end
@@ -50,28 +31,20 @@ module Hecks
       # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
       # @param code [String] the authorization code the provider sent back
       # @param state [String, nil] the state parameter the provider returned; nil is refused
-      # @param expected_state [String, nil] the state `authorization_url` handed out before
-      #   the redirect; nil is refused
-      # @return [Hash{Symbol => Object}] the verified claims: `issuer:` and `subject:`
-      #   (String), `email:` (String, or nil if the token carries none) and
-      #   `email_verified:` (Boolean) — never the raw token
-      # @raise [Ports::Authentication::ValidationError] if either state is nil or the two
-      #   differ, the code exchange fails, the response has no ID token, or the ID token
-      #   does not verify
+      # @param expected_state [String, nil] the state `authorization_url` returned; nil is refused
+      # @return [Hash{Symbol => Object}] the verified claims: `issuer:`, `subject:`, `email:`
+      #   (nil if the token carries none) and `email_verified:` -- never the raw token
+      # @raise [Ports::Authentication::ValidationError] if a state is nil or they differ, the
+      #   code exchange fails, or the ID token is missing or does not verify
       # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
-      #   (see `adapter`)
-      # @raise [KeyError] if the adapter's required configuration is unset, or a verified
-      #   token lacks an `iss` or `sub` claim
+      # @raise [KeyError] if required configuration is unset, or the token lacks `iss`/`sub`
       def verify(registry, code:, state:, expected_state:)
         adapter(registry).verify(code: code, state: state, expected_state: expected_state)
       end
 
-      # Finds the single adapter bound to this port, refusing an ambiguous wiring.
+      # Finds the single adapter bound to this port.
       #
-      # @param registry [Runtime::Registry] the booted registry to search
-      # @return [Module] the adapter module or class implementing this port
-      # @raise [Runtime::WiringError] if no adapter, or more than one, implements this port,
-      #   or the one that does has no Ruby implementation under `Hecks::Adapters`
+      # @raise [Runtime::WiringError] if none, or more than one, implements this port
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 

data/lib/hecks/ports/authorization.rb

@@ -2,28 +2,8 @@ require_relative "../runtime/registry"
 
 module Hecks
   module Ports
-    # Two yes/no questions and one value an application asks before
-    # binding a caller — resolved the same way `Ports::IdentityGeneration`
-    # resolves its own adapter: one adapter registry-wide answers this
-    # port, not a per-aggregate binding, since a domain has no reason to
-    # want a different authorization source per aggregate. What answers
-    # it is deliberately not named here — the governance-backed adapter
-    # is one implementation, not the only possible one, the same way
-    # `SequentialIdentity` and `SecureRandomIdentity` are two
-    # implementations of `identity_generation`.
-    #
-    # A caller decides what to do with the answer — dispatch under that
-    # role, refuse, log, prefer it over some other fallback value — this
-    # only answers the question asked. Nothing here binds a
-    # `Runtime::Caller`.
-    #
-    # `CommandRules::Authorization#refuse_role_mismatch` calls `holds_role?`
-    # directly, once a caller binds an `actor_id` and the command's domain
-    # has Governance attached (see that rule's own header). `spec/
-    # act_as_spec.rb` remains the precedent for the other shape — two
-    # separate registries, queried directly by name — for whenever
-    # Governance is not in the same boot as the caller; this port is the
-    # same questions asked through one adapter when it is.
+    # Role questions an application asks before binding a caller. One adapter registry-wide
+    # answers them; it only answers, and never binds a `Runtime::Caller`.
     module Authorization
       NAME = "authorization".freeze
 
@@ -35,15 +15,11 @@ module Hecks
       # @param actor_id [String] the actor whose grants are checked
       # @param role [String, Symbol] the role name to look for, compared as a String
       # @param as_of [Integer, nil] Unix epoch seconds (from `Ports::Clock.now`); a grant whose
-      #   `starts_at` is later, or does not parse as a time, does not count. nil skips the
-      #   `starts_at` check entirely
-      # @param scope [String, nil] the scope the caller acts in; only a grant made for that
-      #   scope counts. nil skips the scope check, so a grant in any scope counts
-      # @return [Boolean] true if at least one live grant of `role` to `actor_id` passes the
-      #   `as_of` and `scope` checks
-      # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
-      #   (see `adapter`), or the governance-backed adapter finds no single loaded chapter
-      #   providing `"authorization"`
+      #   `starts_at` is later, or does not parse as a time, does not count. nil skips the check
+      # @param scope [String, nil] only a grant made for this scope counts; nil counts any scope
+      # @return [Boolean] true if at least one live grant of `role` to `actor_id` passes
+      # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter,
+      #   or the governance-backed adapter finds no single chapter providing `"authorization"`
       def holds_role?(registry, actor_id:, role:, as_of: nil, scope: nil)
         adapter(registry).holds_role?(registry, actor_id: actor_id, role: role, as_of: as_of, scope: scope)
       end
@@ -56,32 +32,29 @@ module Hecks
       #   String
       # @return [Boolean] true if a live (not ended) allowance lets `from_role` act as
       #   `to_role`
-      # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
-      #   (see `adapter`), or the governance-backed adapter finds no single loaded chapter
-      #   providing `"authorization"`
+      # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter,
+      #   or the governance-backed adapter finds no single loaded chapter providing
+      #   `"authorization"`
       def authorized_as?(registry, from_role:, to_role:)
         adapter(registry).authorized_as?(registry, from_role: from_role, to_role: to_role)
       end
 
-      # Looks up the role an actor holds right now, rather than checking a guessed one.
+      # Looks up the role an actor holds right now.
       #
       # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
       # @param actor_id [String] the actor to look up
       # @return [String, nil] the role name of the actor's first live (not ended) grant, or
       #   nil if it has none; the caller supplies any fallback
-      # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
-      #   (see `adapter`), or the governance-backed adapter finds no single loaded chapter
-      #   providing `"authorization"`
+      # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter,
+      #   or the governance-backed adapter finds no single loaded chapter providing
+      #   `"authorization"`
       def live_role_for(registry, actor_id:)
         adapter(registry).live_role_for(registry, actor_id: actor_id)
       end
 
-      # Finds the single adapter bound to this port, refusing an ambiguous wiring.
+      # Finds the single adapter bound to this port.
       #
-      # @param registry [Runtime::Registry] the booted registry to search
-      # @return [Module] the adapter module or class implementing this port
-      # @raise [Runtime::WiringError] if no adapter, or more than one, implements this port,
-      #   or the one that does has no Ruby implementation under `Hecks::Adapters`
+      # @raise [Runtime::WiringError] if none, or more than one, implements this port
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 

data/lib/hecks/ports/clock.rb

@@ -2,42 +2,8 @@ require_relative "../runtime/registry"
 
 module Hecks
   module Ports
-    # What time it is — the one fact a domain cannot derive and must not invent.
-    #
-    # Resolved exactly the way `Ports::IdentityGeneration` resolves its own
-    # adapter: one adapter registry-wide implements this, not a per-aggregate
-    # binding, because two aggregates in one running app have no real reason to
-    # disagree about the time.
-    #
-    # ## Why a port and not `Time.now`
-    #
-    # A staleness rule — "another agent may take this claim after fifteen
-    # minutes" — is untestable against the real clock: a spec for it would
-    # either sleep for fifteen minutes or never run at all. Bound to a fixed
-    # adapter, the same rule is three lines. That is the whole argument, and
-    # it is the same one `SequentialIdentity` makes next door.
-    #
-    # ## Why a predicate still can't ask the time
-    #
-    # The expression sublanguage has no clock and should not: a `given` that
-    # read the time would evaluate differently on two runs over the same
-    # record, and every replay, audit and fuzz oracle in this repository
-    # assumes it does not. So `now` remains an argument the predicate merely
-    # reads, and this port is what lets a caller stop typing it — the door
-    # fills it in, the value is baked into the dispatch, and the recorded
-    # step carries the concrete number forever after.
-    #
-    # ## Why the runtime never calls this directly
-    #
-    # `IdentityGeneration`'s own note works through the replay question for
-    # a minted uuid and lands on "the value gets baked into the caller's
-    # args at the first live dispatch". A clock consulted inside the
-    # interpreter would not have that property: a recorded corpus step
-    # replayed tomorrow would silently get tomorrow's time, and the
-    # fuzzer's oracle and the adapter-agreement gate both compare runs of
-    # exactly that shape. So the filling happens at the door, where a
-    # human or an agent is typing, and never on the dispatch path a replay
-    # uses.
+    # What time it is, as one registry-wide adapter answers it.
+    # Predicates cannot read the clock (replays must be deterministic), so the door fills `now`.
     module Clock
       NAME = "clock".freeze
 
@@ -45,23 +11,17 @@ module Hecks
 
       # Reads the current time from the bound clock adapter.
       #
-      # Seconds, as an integer, because that is what the sublanguage can do
-      # arithmetic on. `claimed_at.value + window.value <= now.value` is
-      # addition and comparison — the only two things it has — and a Time
+      # Integer seconds, because the expression sublanguage can add and compare but a Time
       # object supports neither.
       #
       # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
       # @return [Integer] the current time, in Unix epoch seconds
       # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
-      #   (see `adapter`)
       def now(registry) = adapter(registry).now
 
-      # Finds the single adapter bound to this port, refusing an ambiguous wiring.
+      # Finds the single adapter bound to this port.
       #
-      # @param registry [Runtime::Registry] the booted registry to search
-      # @return [Module] the adapter module or class implementing this port
-      # @raise [Runtime::WiringError] if no adapter, or more than one, implements this port,
-      #   or the one that does has no Ruby implementation under `Hecks::Adapters`
+      # @raise [Runtime::WiringError] if none, or more than one, implements this port
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 

data/lib/hecks/ports/extraction.rb

@@ -2,10 +2,8 @@ require_relative "../runtime/registry"
 
 module Hecks
   module Ports
-    # The `extraction` port: resolves whichever adapter can recover a
-    # predicate's own source (`canonical`). Reads `Hecks.current_registry`
-    # directly rather than taking a registry argument, since extraction only
-    # ever happens while a bluebook is loading, never after boot.
+    # Resolves the adapter that recovers a predicate's own source (`canonical`).
+    # Reads `Hecks.current_registry`, since extraction only happens while a bluebook loads.
     module Extraction
       NAME = "extraction".freeze
 
@@ -16,19 +14,16 @@ module Hecks
       # @param block [Proc] a block written in a bluebook file, such as a `given` predicate
       #   or an `identified_by` path
       # @return [String, nil] the block body's source, normalised by
-      #   `Bluebook::Expression::CanonicalForm` (whitespace collapsed, linked replacements
-      #   applied); nil if the block's file cannot be read, no block starts on its line, or
-      #   the block has an empty body
+      #   `Bluebook::Expression::CanonicalForm`; nil if the block's file cannot be read, no
+      #   block starts on its line, or the block has an empty body
       # @raise [Runtime::WiringError] if called outside a boot, or this port does not resolve
-      #   to exactly one adapter (see `adapter`)
+      #   to exactly one adapter
       def canonical(block) = adapter.canonical(block)
 
       # Finds the single adapter bound to this port in the registry currently booting.
       #
-      # @return [Module] the adapter module or class implementing this port
-      # @raise [Runtime::WiringError] if `Hecks.current_registry` is nil (resolved outside a
-      #   boot), if no adapter, or more than one, implements this port, or if the one that
-      #   does has no Ruby implementation under `Hecks::Adapters`
+      # @raise [Runtime::WiringError] if called outside a boot, or none, or more than one,
+      #   implements this port
       def adapter
         registry = Hecks.current_registry
         unless registry

data/lib/hecks/ports/identity_assignment.rb

@@ -2,21 +2,8 @@ require_relative "../runtime/registry"
 
 module Hecks
   module Ports
-    # Which value a creating command's own identity field gets, when
-    # neither a slug-from-another-field nor a sequence-with-prefix
-    # mechanically answers it — a driving app's own console, say,
-    # falls back to this when a collection's identity strategy names
-    # "port" rather than "slug"/"sequence" (both of those stay pure
-    # config-driven mechanics, computed by whoever is dispatching,
-    # never by this port).
-    #
-    # Pure delegation, same as every sibling port (AccessControl,
-    # IdentityGeneration): an app's own domain declares what "port"
-    # actually means for it — mint a real UUID via
-    # Ports::IdentityGeneration, derive something else entirely — this
-    # port just resolves the one adapter that domain wired and calls
-    # it, the same "one adapter registry-wide, refuse if zero or many"
-    # resolution every other port here already uses.
+    # Which value a creating command's identity field gets when its strategy names "port".
+    # Delegates to the one adapter the domain wired.
     module IdentityAssignment
       NAME = "identity_assignment".freeze
 
@@ -24,29 +11,21 @@ module Hecks
 
       # Asks the domain's adapter which value a creating command's identity field gets.
       #
-      # No adapter, spec double or caller of this port ships in this repository, so every
-      # shape below other than `registry` is adapter-defined: the port forwards it untouched.
+      # Every argument other than `registry` is adapter-defined and forwarded untouched.
       #
       # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
-      # @param agg_name [Object] adapter-defined, forwarded unchanged; names the aggregate
-      #   whose identity field is being assigned
-      # @param field_name [Object] adapter-defined, forwarded unchanged; names the identity
-      #   field
-      # @param args [Object] adapter-defined, forwarded unchanged; the creating command's own
-      #   arguments
+      # @param agg_name [Object] adapter-defined; names the aggregate being assigned
+      # @param field_name [Object] adapter-defined; names the identity field
+      # @param args [Object] adapter-defined; the creating command's own arguments
       # @return [Object] adapter-defined value to assign as the identity
       # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
-      #   (see `adapter`)
       def assign(registry, agg_name:, field_name:, args:)
         adapter(registry).assign(registry, agg_name: agg_name, field_name: field_name, args: args)
       end
 
-      # Finds the single adapter bound to this port, refusing an ambiguous wiring.
+      # Finds the single adapter bound to this port.
       #
-      # @param registry [Runtime::Registry] the booted registry to search
-      # @return [Module] the adapter module or class implementing this port
-      # @raise [Runtime::WiringError] if no adapter, or more than one, implements this port,
-      #   or the one that does has no Ruby implementation under `Hecks::Adapters`
+      # @raise [Runtime::WiringError] if none, or more than one, implements this port
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 

data/lib/hecks/ports/identity_generation.rb

@@ -2,27 +2,9 @@ require_relative "../runtime/registry"
 
 module Hecks
   module Ports
-    # A creating command with no natural key needs a value from
-    # somewhere to be its identity — this is that somewhere. Resolved
-    # the same way `Ports::Extraction` resolves its own adapter (one
-    # adapter registry-wide implements this port, not a per-aggregate
-    # binding the way persistence needs — different aggregates have no
-    # real reason to want different id-generation strategies within
-    # one running app).
-    #
-    # Replay needs no suppression here, on purpose. A UUID minted for a
-    # creating command's identity gets baked into that step's own args
-    # — an ordinary string value — the moment it's generated, by
-    # whoever issues the first, live dispatch. A recorded corpus
-    # script or a captured fuzz-replay step already holds that
-    # concrete value; replaying it calls `dispatch` with the same
-    # args, and this module is never consulted again, for the same
-    # reason `SecureRandom.uuid` never runs twice for one
-    # already-recorded step today. `Event#occurred_at`
-    # (`command_rules/emission.rb`) is the one other "environmental
-    # fact, not caller-supplied" this codebase has, and it's handled
-    # the identical way: it fires on every dispatch, replay included,
-    # and comparison simply excludes it.
+    # Supplies the identity for a creating command with no natural key.
+    # One adapter registry-wide implements it. Replay never calls it: the minted value is
+    # already baked into the recorded step's args.
     module IdentityGeneration
       NAME = "identity_generation".freeze
 
@@ -32,18 +14,13 @@ module Hecks
       #
       # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
       # @return [String] a newly minted identity: a random UUID from `SecureRandomIdentity`,
-      #   or a decimal counter (`"1"`, `"2"`, …) from the deterministic `SequentialIdentity`
-      #   spec double — unique per adapter, not guaranteed UUID-shaped
+      #   or a decimal counter from the deterministic `SequentialIdentity` spec double
       # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
-      #   (see `adapter`)
       def uuid(registry) = adapter(registry).uuid
 
-      # Finds the single adapter bound to this port, refusing an ambiguous wiring.
+      # Finds the single adapter bound to this port.
       #
-      # @param registry [Runtime::Registry] the booted registry to search
-      # @return [Module] the adapter module or class implementing this port
-      # @raise [Runtime::WiringError] if no adapter, or more than one, implements this port,
-      #   or the one that does has no Ruby implementation under `Hecks::Adapters`
+      # @raise [Runtime::WiringError] if none, or more than one, implements this port
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 

data/lib/hecks/ports/identity_resolution.rb

@@ -2,16 +2,8 @@ require_relative "../runtime/registry"
 
 module Hecks
   module Ports
-    # An authenticated (issuer, subject) pair, resolved to the id of a stable
-    # `Identity` — the other half of the same symmetry `Authorization`
-    # already has for Governance: one adapter registry-wide answers this
-    # port, resolved the same zero/one/many way, so an application never
-    # has to name `Identity` directly to ask "who is this."
-    #
-    # Answers `nil` for a pair nothing has linked — the caller decides
-    # what that means (refuse, prompt to register, whatever), the same
-    # way `Authorization#holds_role?` answering `false` decides nothing
-    # on its own.
+    # Resolves an authenticated (issuer, subject) pair to a stable identity id.
+    # One adapter registry-wide answers this port.
     module IdentityResolution
       NAME = "identity_resolution".freeze
 

data/lib/hecks/ports/key_vault.rb

@@ -2,55 +2,23 @@ require_relative "../runtime/registry"
 
 module Hecks
   module Ports
-    # A subject's own encryption key lives here, one boundary removed from
-    # any event or bluebook attribute — cryptoshredding depends on the key
-    # material never being reachable except through this port's opaque
-    # reference (see `Privacy::SubjectKey`, `lib/hecks/framework/bluebook/
-    # privacy.bluebook`). Resolved the same way `Ports::IdentityGeneration`
-    # resolves its own adapter: one adapter registry-wide answers this
-    # port, not a per-aggregate binding.
+    # A subject's encryption key, one boundary removed from any event or
+    # bluebook attribute, so cryptoshredding never exposes key material.
     module KeyVault
       NAME = "key_vault".freeze
 
       module_function
 
-      # Mints a fresh per-subject encryption key and hands back an opaque reference to it.
-      #
-      # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
-      # @param subject_id [String] the data subject the key is being issued for
-      # @return [String] an opaque key reference; the key material itself never leaves the
-      #   bound adapter, and is never suitable to store on an event or a bluebook attribute
+      # Mints a per-subject key; the key material itself never leaves the bound adapter.
       def issue(registry, subject_id:) = adapter(registry).issue(subject_id: subject_id)
 
-      # Irrevocably destroys a key that {#issue} already returned a reference for.
-      #
-      # Ciphertext produced under `key_reference` becomes permanently unrecoverable the
-      # moment this returns — the mechanism a right-to-erasure request satisfies without
-      # rewriting or deleting any event.
-      #
-      # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
-      # @param key_reference [String] the opaque reference {#issue} returned
-      # @return [Boolean] true when a live key was destroyed; false when this reference was
-      #   already destroyed, or was never issued
+      # Irrevocably destroys a key; ciphertext under it becomes unrecoverable at once —
+      # how a right-to-erasure request is satisfied without rewriting or deleting events.
       def destroy(registry, key_reference:) = adapter(registry).destroy(key_reference: key_reference)
 
-      # Erases one subject: destroys their key in the vault, then durably records that it
-      # happened — in that fixed order, so a caller cannot dispatch `Shred` before the key
-      # is actually gone the way calling {#destroy} and `dispatch_flat` separately would
-      # allow. `Privacy::SubjectKey.Shred`'s own lifecycle guard (`from: "active"`) still
-      # refuses a raw double-dispatch; this is what closes the gap one level up, where the
-      # danger isn't a duplicate `Shred` but `Shred` running *before* {#destroy} does.
-      #
-      # Idempotent: a subject with no live `SubjectKey` record, or one already shredded,
-      # is left alone and answered `false` — a retried erasure request never re-destroys
-      # an already-gone key or double-dispatches `Shred`.
-      #
-      # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted
-      #   dispatcher both the lookup query and the `Shred` dispatch run through
-      # @param domain [String] the subject's own domain FQN, e.g. `"Site::Registration"`
-      # @param subject_id [String] the data subject to erase
-      # @return [Boolean] true when a live key was found and shredded by this call; false
-      #   when no `SubjectKey` record exists for this subject, or it was already shredded
+      # Destroys the subject's key, then dispatches Shred, in that fixed order — never the
+      # reverse, so Shred cannot be dispatched before the key is actually gone. Idempotent:
+      # a subject with no live key, or one already shredded, is left alone and returns false.
       def shred!(dispatcher, domain:, subject_id:) # rubocop:disable Naming/PredicateMethod
         record = dispatcher.query("Privacy::SubjectKey.ForSubject", domain: domain, subject_id: subject_id).first
         return false unless record
@@ -61,11 +29,7 @@ module Hecks
         true
       end
 
-      # Finds the single adapter bound to this port, refusing an ambiguous wiring.
-      #
-      # @param registry [Runtime::Registry] the booted registry to search
-      # @return [Module] the adapter module or class implementing this port
-      # @raise [Runtime::WiringError] if no adapter, or more than one, implements this port
+      # Refuses an ambiguous wiring rather than choosing an adapter arbitrarily.
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }