hecks 1.2.0 → 1.4.0

data/lib/hecks/ports/agent.rb

@@ -2,41 +2,51 @@ require_relative "../runtime/registry"
 
 module Hecks
   module Ports
-    # THE INTERVIEWER — whatever asks the next good question, reads a
+    # The interviewer — whatever asks the next good question, reads a
     # sentence back into proposed declarations, judges a model on taste
-    # rather than structure, or suggests a name. Resolved the singleton
-    # way every other port here is (`Ports::IdentityGeneration`'s own
-    # zero/one/many — one interviewer per process, never per-aggregate),
-    # because a second adapter answering this port is exactly as
-    # unchoosable as a second one minting identities.
+    # rather than structure, or suggests a name.
     #
-    # BUILT LAST, ON PURPOSE, AND STILL OPTIONAL. `.claude/skills/
-    # interview/SKILL.md` conducts a whole session with NONE of this —
+    # ## Why a singleton port
+    #
+    # Resolved the same zero/one/many way every other port here is
+    # (`Ports::IdentityGeneration`'s own singleton adapter — one
+    # interviewer per process, never per-aggregate), because a second
+    # adapter answering this port is exactly as unchoosable as a second
+    # one minting identities.
+    #
+    # ## Why this exists
+    #
+    # Built last, on purpose, and still optional. `.claude/skills/
+    # interview/SKILL.md` conducts a whole session with none of this —
     # Claude Code reads `bin/interview state` itself, asks the human
     # directly with real conversation context, and calls `bin/interview
     # ask`/`propose`/`accept` itself. This port exists for what that
-    # cannot reach: a HEADLESS run (`bin/interview suggest`, no model in
+    # cannot reach: a headless run (`bin/interview suggest`, no model in
     # the room otherwise), a batch `critique` over an already-written
     # chapter, and — the actual point of building it at all — a
-    # SCRIPTED double (`spec/fixtures/scripted_agent.rb`) that makes the
+    # scripted double (`spec/fixtures/scripted_agent.rb`) that makes the
     # whole loop testable with no real model involved.
     #
-    # WHAT THIS PORT IS NOT. It does not judge whether a declaration is
-    # WELL-FORMED — that is the meta-domain's own job, answered by a real
-    # dispatch refusing or not (`Interview::Session#offer`). This port
-    # only ever produces SHAPE: a question, a proposed declaration, a
-    # judgement about taste, a name. A proposal naming a category the
-    # language does not declare is an ADAPTER fault, refused HERE, in
-    # `Answers`; a proposal naming a real category but describing the
-    # wrong domain fact is dispatched anyway, so the LANGUAGE gets to say
-    # why. That line is the whole design.
+    # ## What this port is not
+    #
+    # It does not judge whether a declaration is well-formed — that is
+    # the meta-domain's own job, answered by a real dispatch refusing or
+    # not (`Interview::Session#offer`). This port only ever produces
+    # shape: a question, a proposed declaration, a judgement about
+    # taste, a name. A proposal naming a category the language does not
+    # declare is an adapter fault, refused here, in `Answers`; a
+    # proposal naming a real category but describing the wrong domain
+    # fact is dispatched anyway, so the language gets to say why. That
+    # line is the whole design.
     #
-    # PARSING BELONGS TO THIS FILE, NOT THE ADAPTER. An adapter answers
+    # ## Where parsing happens
+    #
+    # Parsing belongs to this file, not the adapter. An adapter answers
     # with a plain, already-JSON-shaped Hash (a real model's parsed
     # reply, or a spec double's own hand-built one) — never a Struct —
     # so every adapter is validated identically here rather than trusting
     # each one to refuse the same way. Two adapters that parsed
-    # differently would mean the SAME malformed answer passing through
+    # differently would mean the same malformed answer passing through
     # one and refusing through the other.
     module Agent
       NAME = "agent".freeze
@@ -54,7 +64,7 @@ module Hecks
       # Nothing answered at all — the binary is missing, the subprocess
       # died, the call timed out. Separate from ValidationError on
       # purpose: unavailable means retry or fall back to asking the
-      # human directly; malformed means the PROMPT is wrong, not the
+      # human directly; malformed means the prompt is wrong, not the
       # transport, and retrying identically will not fix it.
       class Unavailable < StandardError
       end
@@ -66,26 +76,26 @@ module Hecks
       # declared, which turns "the model invented a field" into a
       # failure at the boundary rather than a nil three calls in.
 
-      # ONE QUESTION. `because` is the reasoning quoted back so a human
+      # One question. `because` is the reasoning quoted back so a human
       # can see it, not decoration — the same "show your work" the
       # language's own refusal messages already practice.
       Question = Struct.new(:text, :because, keyword_init: true)
 
-      # ONE PROPOSED DECLARATION, already shaped as
+      # One proposed declaration, already shaped as
       # `Interview::Proposal`'s own `Argument` rows — `{name:, field:,
       # value:}`, the exact triple `bin/interview propose --arg
       # name:field:value` already takes and `Interview::Lowering`
-      # already knows how to lower. Nothing here decides HOW to address
+      # already knows how to lower. Nothing here decides how to address
       # a record or whether a value is bare or wrapped — that was
       # already the proposal-writer's job in `interview.bluebook`'s own
       # design (see `Argument`'s own comment there); this only adds the
-      # PROSE reasoning a human typed does not carry on its own.
+      # prose reasoning a human typed does not carry on its own.
       Proposal = Struct.new(:verb, :arguments, :rationale, keyword_init: true)
 
-      # CRITIQUE REUSES `Bluebook::ModelCheck::Finding`'S OWN SHAPE —
+      # Critique reuses `Bluebook::ModelCheck::Finding`'s own shape —
       # same fields, same severities, so a mechanical finding
       # (`Session#gaps`) and a judgement (this) print in one list and
-      # sort together. The KIND vocabulary is NOT shared — ModelCheck's
+      # sort together. The kind vocabulary is not shared — ModelCheck's
       # eleven kinds are structural facts about a graph; these are
       # opinions about a model, closed here on purpose (an open kind
       # field is an open prompt, and an open prompt drifts).
@@ -100,54 +110,128 @@ module Hecks
         def to_s = "#{severity.to_s.upcase.ljust(7)} #{kind.to_s.ljust(20)} #{subject}  —  #{message}"
       end
 
-      # ONE SUGGESTED NAME. `rejected` carries the near-misses and why
+      # One suggested name. `rejected` carries the near-misses and why
       # they were passed over — free at the point the model is choosing
       # anyway, and the part a human actually learns from.
       Suggestion = Struct.new(:name, :because, :rejected, keyword_init: true)
 
       module_function
 
-      # THE NEXT BEST QUESTION. `state` is the whole picture — normally
+      # Asks the adapter for the next best question and validates its raw answer into structs.
+      #
+      # `state` is the whole picture — normally
       # `Interview::Session#declaration` plus `#gaps`, so an adapter
       # needs no memory of its own between calls; that is what lets a
       # headless run be a series of one-shot processes, same as
       # `bin/interview` itself already is.
+      #
+      # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
+      # @param state [Hash] the interview's whole current picture (declaration plus gaps),
+      #   JSON-able because an adapter may serialise it into a prompt
+      # @param asked [Array<Object>] JSON-able record of the questions already asked, so the
+      #   adapter does not repeat one; `[]` when nothing has been asked
+      # @return [Array<Ports::Agent::Question>] the questions the adapter answered with, in
+      #   its order; `[]` if it offered none
+      # @raise [Ports::Agent::ValidationError] if the answer is not a Hash holding a
+      #   `"questions"` array whose rows each carry a non-blank `"text"` and `"because"`
+      # @raise [Ports::Agent::Unavailable] if the adapter cannot answer at all (missing
+      #   binary, failed subprocess, timeout, or an exhausted scripted queue)
+      # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
+      #   (see `adapter`)
       def ask(registry, state:, asked: [])
         Answers.questions(adapter(registry).ask(state: state, asked: asked))
       end
 
-      # PROSE -> PROPOSED DECLARATIONS. Returns `[]` when the sentence
+      # Turns a human's sentence into proposed declarations, validated into structs.
+      #
+      # Returns `[]` when the sentence
       # carried no declaration at all (a clarifying question back from
       # the human, say) — a legitimate answer, not a failure.
+      #
+      # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
+      # @param prose [String] a human's plain-English sentence
+      # @param state [Hash] the interview's whole current picture, JSON-able because an
+      #   adapter may serialise it into a prompt
+      # @return [Array<Ports::Agent::Proposal>] one proposal per declaration the sentence
+      #   named; `[]` when it named none
+      # @raise [Ports::Agent::ValidationError] if the answer is not a Hash holding a
+      #   `"proposals"` array, a row's `"verb"` is not `Chapter::Aggregate.Command`, its
+      #   `"rationale"` is blank, or one of its argument rows has no `"name"`
+      # @raise [Ports::Agent::Unavailable] if the adapter cannot answer at all (missing
+      #   binary, failed subprocess, timeout, or an exhausted scripted queue)
+      # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
+      #   (see `adapter`)
       def interpret(registry, prose:, state:)
         Answers.proposals(adapter(registry).interpret(prose: prose, state: state))
       end
 
-      # WHAT IS WRONG WITH THIS AS A MODEL — handed everything already
+      # Asks the adapter to judge a declared model on taste, validated into structs.
+      #
+      # What is wrong with this as a model — handed everything already
       # known (the language's own refusals, `Session#gaps`'s mechanical
       # findings) so it spends its judgement on what neither of those
       # can see, rather than restating them.
+      #
+      # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
+      # @param declared [Hash] the chapter as declared so far, JSON-able because an adapter
+      #   may serialise it into a prompt
+      # @param refusals [Array<Object>] JSON-able refusals the language itself already
+      #   raised; `[]` when there are none
+      # @param findings [Array<Object>] JSON-able mechanical findings `Session#gaps` already
+      #   found; `[]` when there are none
+      # @return [Array<Ports::Agent::Finding>] the adapter's judgements; `[]` when it has
+      #   nothing worth saying
+      # @raise [Ports::Agent::ValidationError] if the answer is not a Hash holding a
+      #   `"findings"` array, a row's `"kind"` is outside `CRITIQUE_KINDS`, its `"severity"`
+      #   is outside `SEVERITIES`, or its `"subject"` or `"message"` is blank
+      # @raise [Ports::Agent::Unavailable] if the adapter cannot answer at all (missing
+      #   binary, failed subprocess, timeout, or an exhausted scripted queue)
+      # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
+      #   (see `adapter`)
       def critique(registry, declared:, refusals: [], findings: [])
         Answers.findings(adapter(registry).critique(declared: declared, refusals: refusals, findings: findings))
       end
 
-      # VOCABULARY HELP. `near` is what the chapter already calls
+      # Asks the adapter to suggest a name for a construct, validated into structs.
+      #
+      # Vocabulary help. `near` is what the chapter already calls
       # things, so a suggestion cannot collide with a name in use.
       #
-      # NAMED `suggest_name`, NOT `name` — the plan's own word for this
+      # Named `suggest_name`, not `name` — the plan's own word for this
       # operation, but `Module#name` already exists and is load-bearing
       # everywhere (backtraces, RSpec's own description building,
-      # `inspect`): a module-function called `name` SHADOWS it the
+      # `inspect`): a module-function called `name` shadows it the
       # instant it's defined, and `SomeModule.name` (no args) then
       # raises `ArgumentError: missing keywords` the next time anything
       # — not this file, something else entirely — asks the module its
       # own name. Measured, not theoretical: this exact collision broke
       # RSpec's own failure-message formatting the first time it was
       # named `name` here.
+      #
+      # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
+      # @param meaning [String] what the new name needs to mean
+      # @param kind [String] the kind of construct being named, such as `"event"`; an
+      #   adapter interpolates it into its prompt
+      # @param near [Array<String>] names already in use in this chapter, which a suggestion
+      #   must not collide with; `[]` when there are none
+      # @return [Array<Ports::Agent::Suggestion>] the suggested names, each with its
+      #   `rejected` near-misses as Strings
+      # @raise [Ports::Agent::ValidationError] if the answer is not a Hash holding a
+      #   `"names"` array whose rows each carry a non-blank `"name"` and `"because"`
+      # @raise [Ports::Agent::Unavailable] if the adapter cannot answer at all (missing
+      #   binary, failed subprocess, timeout, or an exhausted scripted queue)
+      # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
+      #   (see `adapter`)
       def suggest_name(registry, meaning:, kind:, near: [])
         Answers.suggestions(adapter(registry).suggest_name(meaning: meaning, kind: kind, near: near))
       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,
+      #   or the one that does has no Ruby implementation under `Hecks::Adapters`
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 

data/lib/hecks/ports/authentication.rb

@@ -2,14 +2,14 @@ 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 verified
-    # (issuer, subject, email) triple. Resolved the same way every
+    # 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
+    # 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
@@ -19,19 +19,59 @@ module Hecks
     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.
       class ValidationError < StandardError
       end
 
       module_function
 
+      # 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`.
+      #
+      # @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
 
+      # Exchanges the authorization code a provider sent back for a Hash of verified claims.
+      #
+      # @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
+      # @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
       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.
+      #
+      # @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`
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 

data/lib/hecks/ports/authorization.rb

@@ -2,7 +2,7 @@ require_relative "../runtime/registry"
 
 module Hecks
   module Ports
-    # TWO YES/NO QUESTIONS AND ONE VALUE an application asks BEFORE
+    # 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
@@ -12,37 +12,79 @@ module Hecks
     # `SequentialIdentity` and `SecureRandomIdentity` are two
     # implementations of `identity_generation`.
     #
-    # A caller decides what to DO with the answer — dispatch under that
+    # 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`.
     #
-    # STALE AS OF THE `as_of`/`scope` split below, this used to also say
-    # nothing here is consulted by `CommandRules::Authorization` — it now
-    # is: `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.
+    # `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.
     module Authorization
       NAME = "authorization".freeze
 
       module_function
 
+      # Answers whether an actor holds a live (not ended) grant of a role.
+      #
+      # @param registry [Runtime::Registry] the booted registry, used to resolve the adapter
+      #   and handed on to it
+      # @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"`
       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
 
+      # Answers whether one role may act as another.
+      #
+      # @param registry [Runtime::Registry] the booted registry, used to resolve the adapter
+      #   and handed on to it
+      # @param from_role [String, Symbol] the role the caller holds, compared as a String
+      # @param to_role [String, Symbol] the role the caller wants to act as, compared as a
+      #   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"`
       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.
+      #
+      # @param registry [Runtime::Registry] the booted registry, used to resolve the adapter
+      #   and handed on to it
+      # @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"`
       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.
+      #
+      # @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`
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 

data/lib/hecks/ports/clock.rb

@@ -2,47 +2,66 @@ require_relative "../runtime/registry"
 
 module Hecks
   module Ports
-    # WHAT TIME IT IS — the one fact a domain cannot derive and must not invent.
+    # 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 port and not `Time.now`
     #
-    # A PREDICATE STILL CANNOT ASK THE TIME, and this does not change that. 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.
+    # 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.
     #
-    # WHICH IS WHY THE RUNTIME DOES NOT CALL THIS. `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.
+    # ## 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.
     module Clock
       NAME = "clock".freeze
 
       module_function
 
-      # SECONDS, AS AN INTEGER, because that is what the sublanguage can do
+      # 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
       # 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.
+      #
+      # @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`
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 

data/lib/hecks/ports/extraction.rb

@@ -11,8 +11,24 @@ module Hecks
 
       module_function
 
+      # Recovers a block's body as canonical source text, so a rule is carried as text.
+      #
+      # @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
+      # @raise [Runtime::WiringError] if called outside a boot, or this port does not resolve
+      #   to exactly one adapter (see `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`
       def adapter
         registry = Hecks.current_registry
         unless registry

data/lib/hecks/ports/identity_assignment.rb

@@ -2,7 +2,7 @@ require_relative "../runtime/registry"
 
 module Hecks
   module Ports
-    # WHICH VALUE A CREATING COMMAND'S OWN IDENTITY FIELD GETS, when
+    # 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
@@ -12,7 +12,7 @@ module Hecks
     #
     # 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
+    # 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"
@@ -22,10 +22,32 @@ module Hecks
 
       module_function
 
+      # 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.
+      #
+      # @param registry [Runtime::Registry] the booted registry, used to resolve the adapter
+      #   and handed on to it
+      # @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
+      # @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.
+      #
+      # @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`
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }