hecks 0.2.0 → 1.0.0

data/lib/hecks/naming.rb

@@ -0,0 +1,174 @@
+module Hecks
+  module Naming
+    # WHAT SEPARATES THE PARTS OF A DERIVED IDENTITY.
+    #
+    # An identity of several parts is their JOIN, and the join has to be spelled the
+    # same everywhere or two readers name two different records off one declaration.
+    # It was spelled three ways at once here — "::" for an aggregate under a
+    # chapter, "." for everything under an aggregate, "#" for the three that keyed
+    # off position — and each was written where it happened to be needed. Once the
+    # runtime derived the same identity, the runtime made a FOURTH, and a reference
+    # that resolved by string comparison found nothing.
+    IDENTITY_JOIN = ":".freeze
+
+    module_function
+
+    # The parts of an identity, joined in declaration order.
+    def identity(parts) = Array(parts).join(IDENTITY_JOIN)
+
+    def demodulise(type)
+      type.to_s.split("::").last.to_s
+    end
+
+    # snake_case -> PascalCase. The name a synthesised closed-set value object
+    # takes when an attribute declares one inline. The derivation is part of
+    # the IR contract: the same bluebook must always produce the same name.
+    def pascal(text)
+      text.to_s.split("_").map { |part| part.sub(/\A(.)/) { Regexp.last_match(1).upcase } }.join
+    end
+
+    def snake(text)
+      text.to_s
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .downcase
+    end
+
+    # The name a COLLECTION of something takes.
+    #
+    # There were two of these and one was wrong. A read model's gathered heads
+    # derived their name with a bare `"#{snake(target)}s"`, so the meta-domain's
+    # own whole-bluebook read model handed back `querys`, `entitys`, `policys`
+    # and `dispatchs` — and every check was green, because the checks compared
+    # the wrong rule against itself. Agreement is not correctness; it never was.
+    #
+    # So: one pluraliser, three rules, and every collection name flows through it.
+    def plural(text)
+      word = text.to_s
+      return "#{word[0..-2]}ies" if word.match?(/[^aeiou]y\z/)
+      return "#{word}es"         if word.match?(/(s|x|z|ch|sh)\z/)
+
+      "#{word}s"
+    end
+
+    # `has_many`'s undo — the plural WRITTEN, back to the singular the target
+    # aggregate is actually named. Deliberately the crude half of a pair: `plural`
+    # above earns its precision (three suffix rules) because getting a COLLECTION
+    # name wrong reads as a typo forever ; this only ever recovers a name someone
+    # already wrote as a real aggregate, so "ies -> y, trailing s dropped" is the
+    # whole rule — enough for `has_many Invoices` to resolve to the aggregate
+    # actually named Invoice.
+    def singularize(text)
+      word = text.to_s
+      return "#{word[0..-4]}y" if word.length > 3 && word.end_with?("ies")
+
+      # `plural`'s OWN second rule adds "es" (not bare "s") after
+      # s/x/z/ch/sh — undone here the same way, or a word `plural`
+      # itself would have suffixed with "es" comes back missing its
+      # own trailing letter ("Boxes" -> "Boxe", not "Box") once this
+      # only ever knew how to drop a bare "s". Checked BEFORE the
+      # bare-"s" rule below: stripping "es" first and confirming what
+      # is left actually ends in one of those five shapes is what
+      # keeps an ordinary "-es" word (e.g. "Invoices" -> "Invoice")
+      # from also losing a letter it never doubled.
+      if word.length > 3 && word.end_with?("es") && word[0..-3].match?(/(s|x|z|ch|sh)\z/)
+        return word[0..-3]
+      end
+
+      return word[0..-2] if word.length > 1 && word.end_with?("s")
+
+      word
+    end
+
+    def reference_key(type)
+      snake(demodulise(type)).to_sym
+    end
+
+    def split_dotted(dotted)
+      first, second = dotted.to_s.split(".", 2)
+      [first.to_s, second.to_s]
+    end
+
+    def qualifier(dotted)
+      text = dotted.to_s
+      text.include?(".") ? text.split(".", 2).first : nil
+    end
+
+    def unqualified(dotted)
+      text = dotted.to_s
+      text.include?(".") ? text.split(".", 2).last : text
+    end
+
+    def split_verb(verb)
+      path, command = verb.to_s.split(".", 2)
+      domain, aggregate = path.to_s.split("::", 2)
+      return nil unless domain && aggregate && command
+
+      [domain, aggregate, command]
+    end
+
+    # `trigger Account::Debit` / `dispatch Account::Debit` — a bare
+    # CONSTANT reference (`ConstShim`'s own `ScopedConstant`, S0b), not
+    # text (ADR 0025, "events and reactions" — command references become
+    # first-class). Ruby's `::` joins EVERY segment the same way a
+    # constant path always does, but a command's own `hecks_fqn` joins
+    # its aggregate with `.` (`Construct#hecks_separator`'s default,
+    # only an AGGREGATE overrides it to `::`) — so only the LAST `::`
+    # becomes a `.`; everything before it (the chapter, when a domain is
+    # spelled at all: `Banking::Account::Debit`) stays `::`-joined.
+    #
+    # A STRING PASSES THROUGH UNCHANGED, on purpose — legacy era text
+    # (S0a's own shadow-parsed spelling) already mixes `::` (domain) and
+    # `.` (command) correctly on its own, e.g. `"Banking::Account.Debit"`,
+    # and re-splitting that by content rather than by TYPE would corrupt
+    # it (its own last `::` sits between the domain and the aggregate,
+    # not the aggregate and the command). Only an actual constant object
+    # — never seen holding a `.` of its own — needs the rewrite at all.
+    def command_ref(value)
+      return value.to_s if value.is_a?(::String) || value.is_a?(::Symbol)
+
+      text = value.to_s
+      path, _, command = text.rpartition("::")
+      path.empty? ? text : "#{path}.#{command}"
+    end
+
+    # `emits Account::AccountFrozen` / `on Account::AccountFrozen` — the
+    # event-side twin of `command_ref`, above (ADR 0025, S6 — "events
+    # first-class"). Identical transform (a bare `ScopedConstant`'s last
+    # `::` becomes `.`, a String passes through unchanged for legacy
+    # `shadow_parse` text and for corpus sites this pass didn't migrate —
+    # see that method's own comment for why both rules exist), given its
+    # own name because the two references mean different things even
+    # though the rewrite is byte-identical: an event name is not a
+    # command name that happens to share a format.
+    def event_ref(value) = command_ref(value)
+
+    # `transition Account::AccountDebited => "state"` / `starts_on
+    # Transfer::TransferRequested` / `ends_on Transfer::TransferSettled`
+    # — a process manager's OWN event references (ADR 0025, S6),
+    # DELIBERATELY NOT `event_ref` — found live, not assumed, wiring a
+    # real migrated corpus site into `bin/model_check` for the first
+    # time (2026-08-28): `SagaInterpreter#begin_saga`/`#advance_saga`
+    # match `pm.starts_on`/`pm.handler_for` against `event.name`, which
+    # `CommandRules::Emission#emit` stamps BARE — a command's own
+    # `emits AccountDebited` never carries its aggregate's name at all
+    # (unlike a policy's cross-aggregate `on`, matched instead by
+    # `Naming.demodulise(event.aggregate)` split apart from the bare
+    # name — `PolicyInterpreter#policies_for`). Handing a saga's own
+    # matcher the DOTTED `event_ref` form ("Account.AccountDebited")
+    # would silently name an event no command in the domain ever
+    # actually emits — caught by `bin/model_check`'s own `deaf_handler`/
+    # `deaf_trigger` findings the moment a real qualified corpus site
+    # existed to trip them, not by any unit test in isolation.
+    #
+    # A qualifier is still worth WRITING (`Account::`) — the same
+    # provenance a reader gets from `trigger Account::Debit` — it is
+    # only not worth KEEPING: `demodulise` drops everything but the
+    # final segment, so `Account::AccountDebited` and a bare
+    # `AccountDebited` resolve to the identical stored string. A String
+    # passes through unchanged either way, exactly like `command_ref`'s
+    # own legacy branch — this corpus never spelled one dotted to begin
+    # with, so there is nothing here to strip.
+    def event_name_ref(value) = demodulise(value)
+  end
+end

data/lib/hecks/ports/access_control.port

@@ -0,0 +1,9 @@
+Hecks.port "access_control" do
+  verb    "granted_by"
+  signal  :reply
+  answers :session_for_identity
+  answers :provision
+  answers :available_roles
+  answers :grant
+  answers :all_people
+end

data/lib/hecks/ports/access_control.rb

@@ -0,0 +1,62 @@
+require_relative "../runtime/registry"
+
+module Hecks
+  module Ports
+    # WHO CAN SIGN IN, AND WHAT ROLE DO THEY HOLD — the domain-specific
+    # half of sign-in `Ports::Authentication` deliberately stays out of
+    # (see that port's own header: it only ever talks to the external
+    # provider, never this registry's own data). Resolved the same way
+    # every other port here resolves its adapter: one adapter
+    # registry-wide answers this, since an app has no reason to want a
+    # different "who's allowed in" source per aggregate.
+    #
+    # Every domain shapes this differently — who its own "a person who
+    # can sign in" aggregate is, what admits them, what grants them
+    # access — so this port is pure delegation, same as every sibling
+    # port. The one piece of this that IS generic (a live Governance
+    # grant should win over whatever an aggregate's own role field
+    # says) lives on `Ports::Authorization#live_role_for` instead —
+    # a domain's adapter here calls that directly, rather than this
+    # port re-deriving Governance-query logic another port already owns.
+    module AccessControl
+      NAME = "access_control"
+
+      module_function
+
+      def session_for_identity(registry, identity_id:)
+        adapter(registry).session_for_identity(registry, identity_id: identity_id)
+      end
+
+      def provision(registry, email:, issuer:, subject:)
+        adapter(registry).provision(registry, email: email, issuer: issuer, subject: subject)
+      end
+
+      def available_roles(registry)
+        adapter(registry).available_roles(registry)
+      end
+
+      def grant(registry, email:, role:)
+        adapter(registry).grant(registry, email: email, role: role)
+      end
+
+      def all_people(registry)
+        adapter(registry).all_people(registry)
+      end
+
+      def adapter(registry)
+        implementations = registry.adapters.values.select { |a| a.port == NAME }
+
+        case implementations.size
+        when 1 then registry.adapter_class(implementations.first.name)
+        when 0
+          raise Runtime::WiringError,
+                "no adapter implements the #{NAME} port — nothing can answer who's allowed in"
+        else
+          raise Runtime::WiringError,
+                "#{implementations.size} adapters implement the #{NAME} port " \
+                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/agent/answers.rb

@@ -0,0 +1,104 @@
+module Hecks
+  module Ports
+    module Agent
+      # WHERE A RAW HASH BECOMES A STRUCT — the one place, so every
+      # adapter (the real `claude_code` one, and any scripted double
+      # standing in for it in a spec) is held to the identical shape.
+      # An adapter's whole job ends at "here is what came back, already
+      # JSON"; whether that hash is USABLE is decided once, here, not
+      # re-decided per adapter.
+      #
+      # Every failure raises `ValidationError` — never lets a bare
+      # `NoMethodError` on nil, or a `KeyError`, reach a caller looking
+      # for an agent-shaped failure. `bin/interview` catches exactly one
+      # class for "the model answered badly," not a grab-bag of Ruby's
+      # own.
+      module Answers
+        VERB_PATTERN = /\A[A-Za-z]+::[A-Za-z]+\.[A-Za-z]+\z/
+
+        module_function
+
+        def questions(raw)
+          rows(raw, "questions").map { |row| Question.new(text: text!(row, "text"), because: text!(row, "because")) }
+        end
+
+        def proposals(raw)
+          rows(raw, "proposals").map do |row|
+            Proposal.new(verb: verb!(row), rationale: text!(row, "rationale"), arguments: arguments!(row))
+          end
+        end
+
+        def findings(raw)
+          rows(raw, "findings").map do |row|
+            Finding.new(kind: kind!(row), severity: severity!(row), subject: text!(row, "subject"),
+                        message: text!(row, "message"))
+          end
+        end
+
+        def suggestions(raw)
+          rows(raw, "names").map do |row|
+            Suggestion.new(name: text!(row, "name"), because: text!(row, "because"),
+                           rejected: Array(row["rejected"]).map(&:to_s))
+          end
+        end
+
+        # ── shared checks, each named for what it refuses ───────────────
+
+        def rows(raw, key)
+          raise ValidationError, "expected a Hash back, got #{raw.class}: #{raw.inspect}" unless raw.is_a?(Hash)
+
+          value = raw[key]
+          return value if value.is_a?(Array)
+
+          raise ValidationError, "no #{key.inspect} array in the answer: #{raw.inspect}"
+        end
+
+        def text!(row, key)
+          value = row[key]
+          return value.to_s if value && !value.to_s.strip.empty?
+
+          raise ValidationError, "#{key.inspect} missing or blank in #{row.inspect}"
+        end
+
+        # A VERB THE LANGUAGE COULD NOT EVEN PARSE IS AN ADAPTER FAULT,
+        # refused right here — the same `not_fully_qualified` shape the
+        # language's own grammar already refuses by, reused rather than
+        # reinvented. A verb naming a real category that turns out to
+        # describe the wrong fact is NOT this port's business: that one
+        # dispatches, and `Interview::Session#offer` is what says no.
+        def verb!(row)
+          verb = row["verb"].to_s
+          return verb if VERB_PATTERN.match?(verb)
+
+          raise ValidationError, "#{verb.inspect} is not a fully-qualified verb (Chapter::Aggregate.Command)"
+        end
+
+        def kind!(row)
+          kind = row["kind"].to_s.to_sym
+          return kind if CRITIQUE_KINDS.include?(kind)
+
+          raise ValidationError, "#{kind.inspect} is not a critique kind this port knows (#{CRITIQUE_KINDS.join(', ')})"
+        end
+
+        def severity!(row)
+          severity = row["severity"].to_s.to_sym
+          return severity if SEVERITIES.include?(severity)
+
+          raise ValidationError, "#{severity.inspect} is not a severity this port knows (#{SEVERITIES.join(', ')})"
+        end
+
+        # ROWS SHAPED EXACTLY AS `Interview::Proposal::Argument` — a
+        # reference's `field` is legitimately blank (a reference IS an
+        # id), so only `name` is required here.
+        def arguments!(row)
+          Array(row["arguments"]).map do |argument|
+            name = argument["name"].to_s
+            raise ValidationError, "argument row has no name: #{argument.inspect}" if name.empty?
+
+            { name: name, field: argument["field"].to_s, value: argument["value"].to_s }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/agent.port

@@ -0,0 +1,8 @@
+Hecks.port "agent" do
+  verb    "asked_by"
+  signal  :reply
+  answers :ask
+  answers :interpret
+  answers :critique
+  answers :suggest_name
+end

data/lib/hecks/ports/agent.rb

@@ -0,0 +1,167 @@
+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. 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.
+    #
+    # 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.
+    #
+    # 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.
+    module Agent
+      NAME = "agent"
+
+      # 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.
+      ValidationError = Class.new(StandardError)
+
+      # 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.
+      Unavailable = Class.new(StandardError)
+
+      # ── 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.
+      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.
+      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).
+      CRITIQUE_KINDS = %i[
+        anemic_aggregate wrong_boundary crud_verb leaky_value_object
+        missing_lifecycle missing_invariant ubiquitous_language
+        overreaching_identity untold_rule
+      ].freeze
+      SEVERITIES = %i[error warning].freeze
+
+      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.
+      Suggestion = Struct.new(:name, :because, :rejected, keyword_init: true)
+
+      module_function
+
+      # THE NEXT BEST QUESTION. `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.
+      def ask(registry, state:, asked: [])
+        Answers.questions(adapter(registry).ask(state: state, asked: asked))
+      end
+
+      # PROSE -> PROPOSED DECLARATIONS. Returns `[]` when the sentence
+      # carried no declaration at all (a clarifying question back from
+      # the human, say) — a legitimate answer, not a failure.
+      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
+      # 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.
+      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
+      # things, so a suggestion cannot collide with a name in use.
+      #
+      # 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.
+      def suggest_name(registry, meaning:, kind:, near: [])
+        Answers.suggestions(adapter(registry).suggest_name(meaning: meaning, kind: kind, near: near))
+      end
+
+      def adapter(registry)
+        implementations = registry.adapters.values.select { |a| a.port == NAME }
+
+        case implementations.size
+        when 1 then registry.adapter_class(implementations.first.name)
+        when 0
+          raise Runtime::WiringError,
+                "no adapter implements the #{NAME} port — nothing can conduct an interview"
+        else
+          raise Runtime::WiringError,
+                "#{implementations.size} adapters implement the #{NAME} port " \
+                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
+        end
+      end
+    end
+  end
+end
+
+require_relative "agent/answers"

data/lib/hecks/ports/authentication.port

@@ -0,0 +1,6 @@
+Hecks.port "authentication" do
+  verb    "authenticated_by"
+  signal  :reply
+  answers :authorization_url
+  answers :verify
+end

data/lib/hecks/ports/authentication.rb

@@ -0,0 +1,50 @@
+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
+    # 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).
+    module Authentication
+      NAME = "authentication"
+
+      ValidationError = Class.new(StandardError)
+
+      module_function
+
+      def authorization_url(registry)
+        adapter(registry).authorization_url
+      end
+
+      def verify(registry, code:, state:, expected_state:)
+        adapter(registry).verify(code: code, state: state, expected_state: expected_state)
+      end
+
+      def adapter(registry)
+        implementations = registry.adapters.values.select { |a| a.port == NAME }
+
+        case implementations.size
+        when 1 then registry.adapter_class(implementations.first.name)
+        when 0
+          raise Runtime::WiringError,
+                "no adapter implements the #{NAME} port — nothing can authenticate a sign-in"
+        else
+          raise Runtime::WiringError,
+                "#{implementations.size} adapters implement the #{NAME} port " \
+                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/authorization.port

@@ -0,0 +1,7 @@
+Hecks.port "authorization" do
+  verb    "authorized_by"
+  signal  :reply
+  answers :holds_role?
+  answers :authorized_as?
+  answers :live_role_for
+end

data/lib/hecks/ports/authorization.rb

@@ -0,0 +1,62 @@
+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`.
+    #
+    # 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.
+    module Authorization
+      NAME = "authorization"
+
+      module_function
+
+      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
+
+      def authorized_as?(registry, from_role:, to_role:)
+        adapter(registry).authorized_as?(registry, from_role: from_role, to_role: to_role)
+      end
+
+      def live_role_for(registry, actor_id:)
+        adapter(registry).live_role_for(registry, actor_id: actor_id)
+      end
+
+      def adapter(registry)
+        implementations = registry.adapters.values.select { |a| a.port == NAME }
+
+        case implementations.size
+        when 1 then registry.adapter_class(implementations.first.name)
+        when 0
+          raise Runtime::WiringError,
+                "no adapter implements the #{NAME} port — nothing can answer a role check"
+        else
+          raise Runtime::WiringError,
+                "#{implementations.size} adapters implement the #{NAME} port " \
+                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/clock.port

@@ -0,0 +1,5 @@
+Hecks.port "clock" do
+  verb    "timed_by"
+  signal  :reply
+  answers :now
+end