hecks 2.8.0 → 3.0.0

data/lib/hecks/ports/agent.rb

@@ -2,103 +2,28 @@ require_relative "../runtime/registry"
 
 module Hecks
   module Ports
-    # 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.
-    #
-    # ## 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
-    # 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
-    # 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.
-    #
-    # ## 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
-    # one and refusing through the other.
+    # The interviewer: asks questions, reads prose into proposed declarations, critiques a
+    # model on taste, and suggests names. One adapter per process.
     module Agent
       NAME = "agent".freeze
 
-      # The answer came back and could not be used — no JSON in it, a
-      # category the language does not declare, a severity outside the
-      # two that exist. A foreign failure (JSON::ParserError, a missing
-      # key) wrapped into something this port owns, the same shape
-      # `Ports::Authentication::ValidationError` already is, so no
-      # caller ever rescues a raw parser error leaking out of an
-      # adapter.
+      # The adapter's answer arrived but was unusable; retrying the same prompt will not help.
       class ValidationError < StandardError
       end
 
-      # 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
-      # transport, and retrying identically will not fix it.
+      # Nothing answered (missing binary, dead subprocess, timeout); retry or ask the human.
       class Unavailable < StandardError
       end
 
-      # ── what the four operations hand back ──────────────────────────
-      #
-      # Structs, not hashes, for the reason `Bluebook::ModelCheck::Finding`
-      # already is one: a `keyword_init` Struct raises on a key nobody
-      # 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
-      # can see it, not decoration — the same "show your work" the
-      # language's own refusal messages already practice.
+      # keyword_init Structs raise on an undeclared key, so an invented field fails at the edge.
+
+      # One question; `because` is the reasoning shown to the human.
       Question = Struct.new(:text, :because, keyword_init: true)
 
-      # 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
-      # 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.
+      # `arguments` are `{name:, field:, value:}` rows, as `bin/interview propose --arg` takes.
       Proposal = Struct.new(:verb, :arguments, :rationale, keyword_init: true)
 
-      # 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
-      # 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).
+      # Kinds are closed: an open kind is an open prompt, and an open prompt drifts.
       CRITIQUE_KINDS = %i[
         anemic_aggregate wrong_boundary crud_verb leaky_value_object
         missing_lifecycle missing_invariant ubiquitous_language
@@ -106,132 +31,82 @@ module Hecks
       ].freeze
       SEVERITIES = %i[error warning].freeze
 
+      # Same shape as `Bluebook::ModelCheck::Finding`, so gaps and critiques sort together.
       Finding = Struct.new(:kind, :severity, :subject, :message, keyword_init: true) do
         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
-      # they were passed over — free at the point the model is choosing
-      # anyway, and the part a human actually learns from.
+      # `rejected` holds the near-misses and why each was passed over.
       Suggestion = Struct.new(:name, :because, :rejected, keyword_init: true)
 
+      # Adapters return plain Hashes; validating here makes every adapter refuse the same way.
       module_function
 
-      # 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.
+      # Asks the adapter for the next question.
       #
       # @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`)
+      # @param state [Hash] declaration plus gaps; adapters keep no memory between calls
+      # @param asked [Array<Object>] questions already asked, so the adapter does not repeat one
+      # @return [Array<Ports::Agent::Question>]
+      # @raise [Ports::Agent::ValidationError] unless the answer is a Hash whose `"questions"`
+      #   rows each carry a non-blank `"text"` and `"because"`
+      # @raise [Ports::Agent::Unavailable] if the adapter cannot answer
+      # @raise [Runtime::WiringError] unless exactly one adapter implements the port
       def ask(registry, state:, asked: [])
         Answers.questions(adapter(registry).ask(state: state, asked: asked))
       end
 
-      # 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.
+      # Turns a sentence into proposed declarations; `[]` when it named none.
       #
       # @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`)
+      # @param state [Hash] declaration plus gaps
+      # @return [Array<Ports::Agent::Proposal>]
+      # @raise [Ports::Agent::ValidationError] unless the answer is a Hash whose `"proposals"`
+      #   rows have a `Chapter::Aggregate.Command` verb, a rationale and named arguments
+      # @raise [Ports::Agent::Unavailable] if the adapter cannot answer
+      # @raise [Runtime::WiringError] unless exactly one adapter implements the port
       def interpret(registry, prose:, state:)
         Answers.proposals(adapter(registry).interpret(prose: prose, state: state))
       end
 
-      # 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.
+      # Asks the adapter to judge a declared model on taste.
       #
       # @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`)
+      # @param declared [Hash] the chapter as declared so far
+      # @param refusals [Array<Object>] refusals the language already raised
+      # @param findings [Array<Object>] `Session#gaps` findings; both are passed so the
+      #   adapter spends its judgement on what neither can see
+      # @return [Array<Ports::Agent::Finding>]
+      # @raise [Ports::Agent::ValidationError] if a kind is outside `CRITIQUE_KINDS` or a
+      #   severity outside `SEVERITIES`
+      # @raise [Ports::Agent::Unavailable] if the adapter cannot answer
       def critique(registry, declared:, refusals: [], findings: [])
         Answers.findings(adapter(registry).critique(declared: declared, refusals: refusals, findings: findings))
       end
 
-      # 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.
+      # Suggests names for a construct.
       #
-      # 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
-      # 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.
+      # Not called `name`: a module function of that name shadows `Module#name`.
       #
       # @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`)
+      # @param kind [String] the construct being named, such as `"event"`
+      # @param near [Array<String>] names already in use; a suggestion must not collide
+      # @return [Array<Ports::Agent::Suggestion>]
+      # @raise [Ports::Agent::ValidationError] unless the answer is a Hash whose `"names"`
+      #   rows each carry a non-blank `"name"` and `"because"`
+      # @raise [Ports::Agent::Unavailable] if the adapter cannot answer
       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.
+      # 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 the 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,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