hecks 1.2.0 → 1.4.0

data/lib/hecks/naming.rb

@@ -5,14 +5,14 @@ module Hecks
   # two readers never invent two different spellings for the same
   # derivation.
   module Naming
-    # WHAT SEPARATES THE PARTS OF A DERIVED IDENTITY.
+    # What separates the parts of a derived identity.
     #
-    # An identity of several parts is their JOIN, and the join has to be spelled the
+    # 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
+    # runtime derived the same identity, the runtime made a fourth, and a reference
     # that resolved by string comparison found nothing.
     IDENTITY_JOIN = ":".freeze
 
@@ -39,7 +39,48 @@ module Hecks
           .downcase
     end
 
-    # The name a COLLECTION of something takes.
+    # An identifier as a person would say it — `ATMCard` -> "ATM card",
+    # `AccrueInterest` -> "Accrue interest", `daily_limit` -> "Daily
+    # limit", `Back office` -> "Back office". The same two word-boundary
+    # splits `snake` uses, with a space instead of an underscore — plus
+    # the one thing `snake` cannot give back: an all-caps run stays an
+    # acronym ("ATM", "KYC") instead of being lowercased into a word
+    # nobody says ("Atm"). First word capitalized, the rest lowercased,
+    # so a headword reads as sentence case whatever casing it was
+    # declared in.
+    def words(text)
+      parts = text.to_s
+                  .tr("_", " ")
+                  .gsub(/([A-Z]+)([A-Z][a-z])/, '\1 \2')
+                  .gsub(/([a-z\d])([A-Z])/, '\1 \2')
+                  .split
+      parts.each_with_index.map do |part, index|
+        next part if part.match?(/\A[A-Z]{2,}\z/)
+
+        index.zero? ? part.capitalize : part.downcase
+      end.join(" ")
+    end
+
+    # "A, B, and C" / "A or B" — the Oxford-comma list every English
+    # sentence a projection writes wants; lived in `NarrateProjector`
+    # alone until a second projection needed it.
+    def to_sentence_list(items, conj: "and")
+      case items.size
+      when 0 then ""
+      when 1 then items[0].to_s
+      when 2 then "#{items[0]} #{conj} #{items[1]}"
+      else "#{items[0..-2].join(', ')}, #{conj} #{items[-1]}"
+      end
+    end
+
+    # The vowel-letter heuristic — safe here for the same reason
+    # `Projections::Statements#article` gives: a construct name is a
+    # plain word, never "hour" or "university".
+    def a_or_an(word)
+      %w[a e i o u].include?(word.to_s[0].to_s.downcase) ? "an" : "a"
+    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
@@ -56,9 +97,9 @@ module Hecks
       "#{word}s"
     end
 
-    # `has_many`'s undo — the plural WRITTEN, back to the singular the target
+    # `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
+    # 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
@@ -67,11 +108,11 @@ module Hecks
       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
+      # `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
+      # 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")
@@ -102,28 +143,55 @@ module Hecks
       text.include?(".") ? text.split(".", 2).last : text
     end
 
+    # Domain, aggregate, then the REST dot-joined into one command path.
+    #
+    # The `::` boundary between domain and aggregate is unambiguous by
+    # construction — every caller here has already prefixed the domain
+    # itself (`PolicyInterpreter#deliver`, `SagaInterpreter#qualified`,
+    # `Router#dispatch`'s own rebuilt string) before this ever runs. A
+    # third `::` segment can still show up past that boundary: a bare
+    # `ScopedConstant` naming a port operation (`command_ref`'s own
+    # comment — `Aggregate::Port::Operation`, three colon-joined
+    # segments with no `.` of its own) only gets its last `::` rewritten
+    # to `.` there, at DSL-build time, because nothing at that point
+    # knows yet whether the constant names a port operation or a
+    # domain-qualified command (`Domain::Aggregate::Command`, the other
+    # shape `command_ref` documents) — both are textually identical.
+    # Here, past the already-resolved domain boundary, any leftover
+    # `::` is unambiguous: it is that same rewrite artifact, and folding
+    # it into the dot-joined tail recovers exactly the
+    # `Aggregate::Port.Operation` shape a working port dispatch already
+    # expects (`spec/port_operation_interpreter_spec.rb`'s own
+    # `"Payments::Payment.PaymentGateway.Receive"`). `Outbox::Fanout
+    # .kind_for` and `ReactionInvocation#resolve_target` both already
+    # assume this contract on their own end; this is what actually
+    # delivers it to them.
     def split_verb(verb)
       path, command = verb.to_s.split(".", 2)
-      domain, aggregate = path.to_s.split("::", 2)
-      return nil unless domain && aggregate && command
+      return nil unless path && command
+
+      domain, aggregate, *rest = path.to_s.split("::")
+      return nil unless domain && aggregate
+
+      command = "#{rest.join('.')}.#{command}" unless rest.empty?
 
       [domain, aggregate, command]
     end
 
     # `trigger Account::Debit` / `dispatch Account::Debit` — a bare
-    # CONSTANT reference (`ConstShim`'s own `ScopedConstant`, S0b), not
+    # 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
+    # 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 `::`
+    # 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
+    # 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
+    # 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.
@@ -148,25 +216,25 @@ module Hecks
 
     # `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
+    # — 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
+    # `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")
+    # 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
+    # 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
+    # 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

data/lib/hecks/ports/access_control.rb

@@ -2,7 +2,7 @@ require_relative "../runtime/registry"
 
 module Hecks
   module Ports
-    # WHO CAN SIGN IN, AND WHAT ROLE DO THEY HOLD — the domain-specific
+    # 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
@@ -13,7 +13,7 @@ module Hecks
     # 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
+    # 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
@@ -23,26 +23,82 @@ module Hecks
 
       module_function
 
+      # Asks the domain's adapter for the session an already-resolved identity signs into.
+      #
+      # No adapter or spec double for 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 identity_id [Object] adapter-defined identity key, forwarded unchanged
+      # @return [Object] adapter-defined session representation
+      # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
+      #   (see `adapter`)
       def session_for_identity(registry, identity_id:)
         adapter(registry).session_for_identity(registry, identity_id: identity_id)
       end
 
+      # Admits a new person, in whatever way this domain's adapter defines admission.
+      #
+      # The keywords carry the names of a verified sign-in (`Ports::Authentication.verify`
+      # answers `issuer`, `subject` and `email`), but nothing in this repository wires the
+      # two together, so their shapes here are adapter-defined.
+      #
+      # @param registry [Runtime::Registry] the booted registry, used to resolve the adapter
+      #   and handed on to it
+      # @param email [Object] adapter-defined, forwarded unchanged; the person's email
+      # @param issuer [Object] adapter-defined, forwarded unchanged; the OIDC issuer that
+      #   authenticated the person
+      # @param subject [Object] adapter-defined, forwarded unchanged; the OIDC subject the
+      #   issuer vouches for
+      # @return [Object] adapter-defined representation of the newly admitted person
+      # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
+      #   (see `adapter`)
       def provision(registry, email:, issuer:, subject:)
         adapter(registry).provision(registry, email: email, issuer: issuer, subject: subject)
       end
 
+      # Asks the domain's adapter which roles it can grant.
+      #
+      # @param registry [Runtime::Registry] the booted registry, used to resolve the adapter
+      #   and handed on to it
+      # @return [Object] adapter-defined collection of grantable roles
+      # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
+      #   (see `adapter`)
       def available_roles(registry)
         adapter(registry).available_roles(registry)
       end
 
+      # Grants a role to a person, by whatever means the domain's adapter records a grant.
+      #
+      # @param registry [Runtime::Registry] the booted registry, used to resolve the adapter
+      #   and handed on to it
+      # @param email [Object] adapter-defined, forwarded unchanged; the person receiving the role
+      # @param role [Object] adapter-defined, forwarded unchanged; the role to grant
+      # @return [Object] adapter-defined representation of the grant
+      # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
+      #   (see `adapter`)
       def grant(registry, email:, role:)
         adapter(registry).grant(registry, email: email, role: role)
       end
 
+      # Lists every person the domain's adapter knows about.
+      #
+      # @param registry [Runtime::Registry] the booted registry, used to resolve the adapter
+      #   and handed on to it
+      # @return [Object] adapter-defined collection of people
+      # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
+      #   (see `adapter`)
       def all_people(registry)
         adapter(registry).all_people(registry)
       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/agent/answers.rb

@@ -1,11 +1,11 @@
 module Hecks
   module Ports
     module Agent
-      # WHERE A RAW HASH BECOMES A STRUCT — the one place, so every
+      # 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
+      # JSON"; whether that hash is usable is decided once, here, not
       # re-decided per adapter.
       #
       # Every failure raises `ValidationError` — never lets a bare
@@ -18,16 +18,43 @@ module Hecks
 
         module_function
 
+        # Validates an adapter's raw answer to `ask` into `Question` structs.
+        #
+        # @param raw [Hash{String => Object}] the adapter's parsed reply, expected to hold a
+        #   `"questions"` array of `{"text" =>, "because" =>}` rows; any other shape is refused
+        # @return [Array<Ports::Agent::Question>] one struct per row, in the answer's order;
+        #   `[]` for an empty `"questions"` array
+        # @raise [Ports::Agent::ValidationError] if `raw` is not a Hash, holds no
+        #   `"questions"` array, or a row's `"text"` or `"because"` is missing or blank
         def questions(raw)
           rows(raw, "questions").map { |row| Question.new(text: text!(row, "text"), because: text!(row, "because")) }
         end
 
+        # Validates an adapter's raw answer to `interpret` into `Proposal` structs.
+        #
+        # @param raw [Hash{String => Object}] the adapter's parsed reply, expected to hold a
+        #   `"proposals"` array of `{"verb" =>, "rationale" =>, "arguments" =>}` rows
+        # @return [Array<Ports::Agent::Proposal>] one struct per row, its `arguments` an Array
+        #   of `{name:, field:, value:}` Hashes (see `arguments!`); `[]` for an empty
+        #   `"proposals"` array
+        # @raise [Ports::Agent::ValidationError] if `raw` is not a Hash, holds no
+        #   `"proposals"` array, or a row has a verb that is not fully qualified, a blank
+        #   `"rationale"`, or an argument row with no `"name"`
         def proposals(raw)
           rows(raw, "proposals").map do |row|
             Proposal.new(verb: verb!(row), rationale: text!(row, "rationale"), arguments: arguments!(row))
           end
         end
 
+        # Validates an adapter's raw answer to `critique` into `Finding` structs.
+        #
+        # @param raw [Hash{String => Object}] the adapter's parsed reply, expected to hold a
+        #   `"findings"` array of `{"kind" =>, "severity" =>, "subject" =>, "message" =>}` rows
+        # @return [Array<Ports::Agent::Finding>] one struct per row, with `kind` and `severity`
+        #   as Symbols; `[]` for an empty `"findings"` array
+        # @raise [Ports::Agent::ValidationError] if `raw` is not a Hash, holds no
+        #   `"findings"` array, or a row's kind is outside `CRITIQUE_KINDS`, its severity is
+        #   outside `SEVERITIES`, or its `"subject"` or `"message"` is missing or blank
         def findings(raw)
           rows(raw, "findings").map do |row|
             Finding.new(kind: kind!(row), severity: severity!(row), subject: text!(row, "subject"),
@@ -35,6 +62,14 @@ module Hecks
           end
         end
 
+        # Validates an adapter's raw answer to `suggest_name` into `Suggestion` structs.
+        #
+        # @param raw [Hash{String => Object}] the adapter's parsed reply, expected to hold a
+        #   `"names"` array of `{"name" =>, "because" =>, "rejected" =>}` rows
+        # @return [Array<Ports::Agent::Suggestion>] one struct per row, its `rejected` an
+        #   Array of Strings (`[]` when the row carries none); `[]` for an empty `"names"` array
+        # @raise [Ports::Agent::ValidationError] if `raw` is not a Hash, holds no `"names"`
+        #   array, or a row's `"name"` or `"because"` is missing or blank
         def suggestions(raw)
           rows(raw, "names").map do |row|
             Suggestion.new(name: text!(row, "name"), because: text!(row, "because"),
@@ -44,6 +79,13 @@ module Hecks
 
         # ── shared checks, each named for what it refuses ───────────────
 
+        # Reads the array of rows an answer holds under one key, refusing any other shape.
+        #
+        # @param raw [Object] the adapter's reply; only a Hash is accepted
+        # @param key [String] the key the rows sit under, such as `"questions"`
+        # @return [Array<Object>] the rows exactly as the adapter gave them, unvalidated
+        # @raise [Ports::Agent::ValidationError] if `raw` is not a Hash, or `raw[key]` is
+        #   not an Array
         def rows(raw, key)
           raise ValidationError, "expected a Hash back, got #{raw.class}: #{raw.inspect}" unless raw.is_a?(Hash)
 
@@ -53,6 +95,13 @@ module Hecks
           raise ValidationError, "no #{key.inspect} array in the answer: #{raw.inspect}"
         end
 
+        # Reads one required text field off a row, refusing a missing or blank one.
+        #
+        # @param row [Hash{String => Object}] one row of the adapter's answer
+        # @param key [String] the field to read, such as `"because"`
+        # @return [String] the field's value as a String, whitespace untouched
+        # @raise [Ports::Agent::ValidationError] if the field is nil, false, empty, or only
+        #   whitespace
         def text!(row, key)
           value = row[key]
           return value.to_s if value && !value.to_s.strip.empty?
@@ -60,12 +109,19 @@ module Hecks
           raise ValidationError, "#{key.inspect} missing or blank in #{row.inspect}"
         end
 
-        # A VERB THE LANGUAGE COULD NOT EVEN PARSE IS AN ADAPTER FAULT,
+        # Reads a proposal row's verb, refusing one that is not fully qualified.
+        #
+        # 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
+        # describe the wrong fact is not this port's business: that one
         # dispatches, and `Interview::Session#offer` is what says no.
+        #
+        # @param row [Hash{String => Object}] one proposal row of the adapter's answer
+        # @return [String] the row's `"verb"`, shaped `Chapter::Aggregate.Command`
+        # @raise [Ports::Agent::ValidationError] if the verb is missing or does not match
+        #   `VERB_PATTERN`
         def verb!(row)
           verb = row["verb"].to_s
           return verb if VERB_PATTERN.match?(verb)
@@ -73,6 +129,12 @@ module Hecks
           raise ValidationError, "#{verb.inspect} is not a fully-qualified verb (Chapter::Aggregate.Command)"
         end
 
+        # Reads a finding row's kind, refusing one outside the closed critique vocabulary.
+        #
+        # @param row [Hash{String => Object}] one finding row of the adapter's answer
+        # @return [Symbol] the row's `"kind"`, a member of `CRITIQUE_KINDS`
+        # @raise [Ports::Agent::ValidationError] if the kind is missing or not in
+        #   `CRITIQUE_KINDS`
         def kind!(row)
           kind = row["kind"].to_s.to_sym
           return kind if CRITIQUE_KINDS.include?(kind)
@@ -80,6 +142,12 @@ module Hecks
           raise ValidationError, "#{kind.inspect} is not a critique kind this port knows (#{CRITIQUE_KINDS.join(', ')})"
         end
 
+        # Reads a finding row's severity, refusing anything but the two that exist.
+        #
+        # @param row [Hash{String => Object}] one finding row of the adapter's answer
+        # @return [Symbol] the row's `"severity"`, a member of `SEVERITIES`
+        # @raise [Ports::Agent::ValidationError] if the severity is missing or not in
+        #   `SEVERITIES`
         def severity!(row)
           severity = row["severity"].to_s.to_sym
           return severity if SEVERITIES.include?(severity)
@@ -87,9 +155,18 @@ module Hecks
           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
+        # Normalises a proposal row's arguments into symbol-keyed, all-String rows.
+        #
+        # 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.
+        #
+        # @param row [Hash{String => Object}] one proposal row of the adapter's answer
+        # @return [Array<Hash{Symbol => String}>] one `{name:, field:, value:}` Hash per
+        #   argument, `field` and `value` being `""` when absent; `[]` when the row has no
+        #   `"arguments"`
+        # @raise [Ports::Agent::ValidationError] if an argument row's `"name"` is missing or
+        #   empty
         def arguments!(row)
           Array(row["arguments"]).map do |argument|
             name = argument["name"].to_s