hecks 1.3.0 → 1.4.0

data/lib/hecks/language/oidc.json

@@ -76,6 +76,11 @@
       "verb": "Bluebook::Bluebook.Normalise",
       "role": "Language"
     },
+    {
+      "scope": "bluebook:bluebook.provide",
+      "verb": "Bluebook::Bluebook.Provide",
+      "role": "Language"
+    },
     {
       "scope": "bluebook:command.acts_on",
       "verb": "Bluebook::Command.ActsOn",

data/lib/hecks/literal.rb

@@ -1,31 +1,31 @@
 module Hecks
-  # THE ONE SPELLING FOR A CAPTURED RUBY LITERAL ON THE WIRE.
+  # The one spelling for a captured Ruby literal on the wire.
   #
   # Several `to_h` fields hold a value the author wrote in a bluebook —
   # `where(status: { eq: "open" })`, `then_set append: { direction: { value:
   # "credit" } }`, `dispatch ... with: { number: :source }`, an attribute's
-  # `default:` — as TEXT, because the export has to stand on its own and a
+  # `default:` — as text, because the export has to stand on its own and a
   # String field cannot say "this one was a Symbol". Every such field is the
   # same question and now gets the same answer.
   #
   # It was three answers before, and they disagreed on both axes that matter.
-  # `Mutation#appended_fields` spelled a Symbol BARE and everything else
-  # `inspect`; `QuerySpecification.render_value` spelled a Symbol with a COLON
+  # `Mutation#appended_fields` spelled a Symbol bare and everything else
+  # `inspect`; `QuerySpecification.render_value` spelled a Symbol with a colon
   # and everything else `to_s`. So `:amount` crossed as "amount" in a mutation
   # and ":amount" in a saga binding — the same value, two spellings, and each
   # reader had to know which field it was looking at. Worse, `to_s`/`inspect`
-  # on a Hash is Ruby's OWN rendering, which moved under us: 3.3 writes
+  # on a Hash is Ruby's own rendering, which moved under us: 3.3 writes
   # `{:value=>"credit"}` and 3.4 writes `{value: "credit"}` for the identical
   # Hash, so the wire format was silently pinned to an interpreter version.
   #
-  # SELF-DESCRIBING IS THE RULE, stated once here rather than inherited from
+  # Self-describing is the rule, stated once here rather than inherited from
   # whatever `inspect` happens to do: a symbol wears its colon, a string wears
   # its quotes, a hash wears `{key: value}` braces, a list wears its brackets,
   # and a number, a boolean and nil are bare. `read` is the exact inverse, and
   # is the only thing that should ever take one of these strings apart.
-  # A MUTATION SOURCE THAT READS THE RECORD'S OWN STATE — `sets :positions,
+  # A mutation source that reads the record's own state — `sets :positions,
   # append: { knights: state(:knights) }`. A bare Symbol in a mutation
-  # source always names a command ARGUMENT (and imports it as one when
+  # source always names a command argument (and imports it as one when
   # the target's own field carries the same name — `CommandBuilder
   # #resolve_append_fields!`); before this there was no way to say "the
   # value this field already holds", so a command could not snapshot its
@@ -102,7 +102,7 @@ module Hecks
 
     def read_array(raw) = split_items(raw[1..-2]).map { |item| read(item) }
 
-    # Split on the commas that are actually SEPARATORS — never one inside a
+    # Split on the commas that are actually separators — never one inside a
     # quoted string or a nested brace/bracket. Scanned rather than
     # `String#split(", ")`, which tore `"a, b"` in half and lost the second
     # field of anything nested.

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,7 @@ module Hecks
           .downcase
     end
 
-    # AN IDENTIFIER AS A PERSON WOULD SAY IT — `ATMCard` -> "ATM card",
+    # 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
@@ -73,14 +73,14 @@ module Hecks
       end
     end
 
-    # The vowel-LETTER heuristic — safe here for the same reason
+    # 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.
+    # 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
@@ -97,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
@@ -108,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")
@@ -143,19 +143,19 @@ module Hecks
       text.include?(".") ? text.split(".", 2).last : text
     end
 
-    # DOMAIN, AGGREGATE, then the REST dot-joined into one command path.
+    # 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
+    # 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
+    # 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
+    # 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
@@ -179,19 +179,19 @@ module Hecks
     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.
@@ -216,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