hecks 1.3.0 → 1.5.0

data/lib/hecks/bluebook/assembly/contracts.rb

@@ -5,12 +5,12 @@ module Hecks
     # Command, ValueObject, Query, ...); see `Contract`'s own header
     # (contract.rb) for the struct format each entry below fills in.
     class Assembly
-      # ONE TABLE, WHERE THERE WERE FIVE HAND-WRITTEN MIRRORS OF IT.
+      # One table, where there were five hand-written mirrors of it.
       #
       # `bluebook.bluebook` already declares what every construct is made of, and
       # `Plan` already reads it — parent, fields, lists, setters. What the language
       # cannot say is the three things Ruby needs to rebuild one, so those are here
-      # and ONLY those:
+      # and only those:
       #
       #   holder    which class holds it
       #   make      :declare for a construct that became a class, :new for an
@@ -19,23 +19,28 @@ module Hecks
       #   fields    each keyword the constructor takes, as
       #             keyword => [key in the declaration, how to read it]
       #
-      # A READER is a symbol naming a method on Marks, or :plain for a value that
+      # A reader is a symbol naming a method on Marks, or :plain for a value that
       # needs no decoding, or [:each, reader] for a list. Nothing here is a rule
       # about whether a declaration is admissible — the language settled that on the
       # way in. This is only how a spelling becomes an object again.
       #
-      # WHY A TABLE AND NOT A METHOD PER CATEGORY. The judge used to carry one
-      # hand-written branch per category, and the price was fourteen verbs the
-      # language declared and the walk never offered — every rule hanging off them
-      # decoration, and nothing red, because a branch that does not exist cannot
-      # fail. An assembler with a method per category is the same shape. So the
-      # table is checked AGAINST the language by spec/assembly_spec: a field the
-      # language declares that no contract consumes is a failure, not a silence.
+      # Why a table and not a method per category: a hand-written branch per
+      # category can decorate a verb the language declares without the walk ever
+      # offering it, and nothing goes red, because a branch that does not exist
+      # cannot fail. An assembler with a method per category is the same shape.
+      # The table avoids it because spec/assembly_spec checks it against the
+      # language: a field the language declares that no contract consumes is a
+      # failure, not a silence.
       #
       # The `derived` list is how a field says it needs no assembling — a parent
       # pointer the containment tree already knows, or something computed from what
       # is here (`query_name` is `Naming.snake(name)`, `creates?` is whether a verb
       # names a root). Naming one is a claim, and the coverage gate holds it.
+      #
+      # @param category [String, Symbol] the construct category name, such as
+      #   `"Aggregate"` or `:Command`
+      # @return [Bluebook::Assembly::Contract] the category's field contract
+      # @raise [KeyError] if no contract is registered for `category`
       def self.contract(category) = CONTRACTS.fetch(category.to_s)
 
       CONTRACTS = {
@@ -47,7 +52,8 @@ module Hecks
             vision:            [:vision,         :plain],
             classification:    [:classification, :plain],
             formerly_known_as: [:formerly_known_as, :plain],
-            attaches_to:       [:attaches_to, :plain]
+            attaches_to:       [:attaches_to, :plain],
+            provides:          [:provides, :plain]
           },
           rows: { normalisations: :normalisation_table },
           derived: { normalisations: :elsewhere }
@@ -60,7 +66,7 @@ module Hecks
             description:      [:description,   :plain],
             identified_by:    [:identified_by, :plain],
             attributes:       [:attributes,    [:each, :attribute]],
-            # THE AGGREGATE BOUNDARY, and the precondition a command may
+            # The aggregate boundary, and the precondition a command may
             # reference by name (S10, ADR 0025 — "Rules"). Same reader
             # shapes ValueObject's own `invariants`/Command's own
             # `givens` already use — `invariant` builds an Invariant,
@@ -101,7 +107,7 @@ module Hecks
             ensures:    [:ensures,    [:each, :given]],
             mutations:  [:mutations,  [:each, :mutation]],
             emits:      [:emits,      :plain],
-            # LIFECYCLE STATE AS A COMMAND GUARD (S10, ADR 0025) — a
+            # Lifecycle state as a command guard (S10, ADR 0025) — a
             # literal the same way `provenance`/`default:` already are;
             # one state or an array of them, or nil for a command with
             # no such guard.
@@ -138,7 +144,7 @@ module Hecks
             wheres:         [:wheres,          [:each, :where_clause]],
             order_by:       [:order_by,        :order_by],
             limit:          [:limit,           :limit],
-            # Held by the language as an OPEN MAP, so every one of these reads the
+            # Held by the language as an open map, so every one of these reads the
             # same way and a ninth option needs no new field on either side.
             offset:         [:offset,          [:option, :offset]],
             cursor:         [:cursor,          [:option, :cursor]],
@@ -162,20 +168,20 @@ module Hecks
           fields: {
             name:          [:name,          :plain],
             description:   [:description,   :plain],
-            # A LIST OF PATHS, exactly as an aggregate's is. The two used to differ
-            # — a Symbol here and a String there, which byte equality with `to_h`
-            # COULD NOT SEE because both render as a string, so the assembled graph
-            # got a String and `element_of` looked up `args["sequence"]` in a
-            # symbol-keyed payload and found nothing: "Reverse acts on one
-            # LedgerEntry — pass sequence:", while passing sequence. There is one
-            # spelling now, and no room left for that difference.
+            # A list of paths, exactly as an aggregate's is, with no room left for
+            # the two to differ. A Symbol here and a String there would look
+            # identical to `to_h`'s byte-equality check, since both render as a
+            # string, while diverging at runtime: the assembled graph would carry a
+            # String, and `element_of`'s lookup of `args["sequence"]` in a
+            # symbol-keyed payload would find nothing — refusing "Reverse acts on
+            # one LedgerEntry — pass sequence:" while sequence was in fact passed.
             identified_by: [:identified_by, :plain],
             attributes:    [:attributes,    [:each, :shape_field]],
-            # ADR 0028 — the SAME shape Aggregate's own `preconditions`
+            # ADR 0028 — the same shape Aggregate's own `preconditions`
             # already carries, one level down: a piece's own named
             # `given`, referenced back by one of its own commands.
             preconditions: [:preconditions, [:each, :given]],
-            # Round 7 — the SAME shape Aggregate's own `invariants`
+            # Round 7 — the same shape Aggregate's own `invariants`
             # already carries, one level down: checked against every
             # instance of this piece, not the aggregate's own flat state.
             invariants:    [:invariants,    [:each, :invariant]]
@@ -195,17 +201,18 @@ module Hecks
         "Policy"         => Contract.new(
           holder: Policy, make: :new,
           fields: {
-            name:            [:name,            :plain],
-            aggregate:       [:aggregate,       :plain],
-            on_event:        [:on_event,        :plain],
-            trigger_command: [:trigger_command, :plain],
-            target_domain:   [:target_domain,   :plain],
-            where:           [:where,           :plain],
-            for_each:        [:for_each,        :plain],
-            with_spec:       [:with_spec,       :bindings]
+            name:               [:name,            :plain],
+            aggregate:          [:aggregate,       :plain],
+            on_event:           [:on_event,        :plain],
+            trigger_command:    [:trigger_command, :plain],
+            target_domain:      [:target_domain,   :plain],
+            expect_undelivered: [:expect_undelivered, :plain],
+            where:              [:where,           :plain],
+            for_each:           [:for_each,        :plain],
+            with_spec:          [:with_spec,       :bindings]
           },
           rows: { with_spec: :with_spec_rows },
-          reads: { with_spec: [:from, :with_spec] },
+          reads: { with_spec: [:from, :with_spec], expect_undelivered: :expect_undelivered? },
           derived: { position: :walk }
         ),
 
@@ -213,7 +220,7 @@ module Hecks
           holder: ProcessManager, make: :new,
           fields: {
             name:          [:name,          :plain],
-            # A SYMBOL. `SagaInterpreter` does `event.payload[pm.correlates_by]` — a
+            # **A symbol**. `SagaInterpreter` does `event.payload[pm.correlates_by]` — a
             # hash lookup on a symbol-keyed payload — and `value == pm.correlates_by`
             # when resolving a leg s bindings. A String there finds nothing and
             # resolves to nothing, so the wire never advanced and a drawer that
@@ -224,7 +231,7 @@ module Hecks
             states:        [:states,        :plain]
           },
           reads: { states: :names },
-          # S17, ADR 0026 — `handlers` is a REAL feature of the LANGUAGE's
+          # S17, ADR 0026 — `handlers` is a real feature of the language's
           # own "ProcessManager" declaration now (`attribute :handlers,
           # list_of(Handler)`, reaction.bluebook), consumed by the judge
           # walking `Plan`'s own containment tree (`Handler`'s own
@@ -237,7 +244,7 @@ module Hecks
         # S17, ADR 0026 — Handler is a genuine entity now, nested under
         # ProcessManager (`entity "Handler"`, reaction.bluebook). Neither
         # `position` nor `handler` is a stored field any more: a saga
-        # answers each event ONCE, so `event_type` is Handler's own real,
+        # answers each event once, so `event_type` is Handler's own real,
         # non-positional identity (no walk-minted `position` to derive),
         # and the process manager it belongs to is structural now — which
         # list this element sits in, not a stored field to fold a parent
@@ -251,7 +258,7 @@ module Hecks
           },
           # `dispatches` — same reason ProcessManager's own `handlers`
           # claim, above, is `:children` : a real feature of the
-          # LANGUAGE's own "Handler" declaration (`attribute :dispatches,
+          # language's own "Handler" declaration (`attribute :dispatches,
           # list_of(Dispatch)`), consumed by the judge walking `Plan`'s
           # own containment tree rather than by any field this contract
           # reads.
@@ -261,31 +268,31 @@ module Hecks
         # S17, ADR 0026 — Dispatch is a genuine entity now, nested under
         # Handler (`entity "Dispatch"`, process_manager.bluebook) — two
         # levels deep, "no life outside its Handler" (the ADR's own
-        # words). `command_name` ALONE used to be Dispatch's own
-        # identity, until items #151/#152 (`process_manager.bluebook`'s
-        # own `DispatchPosition` comment) found it collided the instant a
-        # real handler fanned the same command out more than once —
-        # `position` now joins it, walk-minted the same way every other
+        # words). `command_name` alone is not Dispatch's own identity —
+        # items #151/#152 (`process_manager.bluebook`'s own
+        # `DispatchPosition` comment) found it collides the instant a
+        # real handler fans the same command out more than once, so
+        # `position` joins it, walk-minted the same way every other
         # category's own `position` is (`derived: { position: :walk }`,
         # the same entry ProcessManager's own contract carries above) —
         # never a stored field on `DispatchSpec` itself, exactly like
         # `handler` before it.
-        # `compensates_command_name`/`compensates_with_spec` — FOLDED,
-        # the SAME kind `Lifecycle`'s own `state_field`/`default` claim
-        # (one IR OBJECT, `DispatchSpec#compensates`, feeding two
+        # `compensates_command_name`/`compensates_with_spec` — folded,
+        # the same kind `Lifecycle`'s own `state_field`/`default` claim
+        # (one IR object, `DispatchSpec#compensates`, feeding two
         # separate language fields): `Readings#field_value`'s own
         # `contract.folded` branch reads
         # `node.compensates.to_h[:command_name]` / `[:with_spec]` for
-        # the JUDGE'S offering side, nil-safe when there is no
+        # the judge's offering side, nil-safe when there is no
         # compensation at all (`through`'s own `return nil unless
-        # held`). `compensates_with_spec` ALSO needs its own row shaper
-        # (`compensates_with_spec_rows`, readings.rb) for the JUDGE'S
+        # held`). `compensates_with_spec` also needs its own row shaper
+        # (`compensates_with_spec_rows`, readings.rb) for the judge's
         # list-offering side — the with_spec pairs still need one
         # "BindCompensation" append per pair, the same reason
         # `with_spec` itself needs `with_spec_rows`, one level deeper.
         # `Reconstruction#dispatch` reads the two flat fields back off
         # the row and assembles the nested `DispatchSpec` by hand — a
-        # nested OBJECT is not one of the shapes `declaration()`'s own
+        # nested object is not one of the shapes `declaration()`'s own
         # generic per-field hash-build can produce, the identical reason
         # `handler`/`process_manager` pass a `:children` list through
         # `extra:` instead.
@@ -372,7 +379,7 @@ module Hecks
             # is what `Assembly::Build` needs (fed the native `to_h`
             # value directly, already `true`/`nil`/a String), and the
             # `reads:` entry below is what `Reconstruction` needs
-            # instead (fed the STRINGIFIED meta-domain row).
+            # instead (fed the stringified meta-domain row).
             count:            [:count,            :plain],
             median_field:     [:median_field,     :plain],
             # A read model inherits every option an ask has, so it reads them the
@@ -392,12 +399,12 @@ module Hecks
           # `nil` — even though a read model's row never carries `wheres` as a
           # native field the way Query's does (`[:each, :where_clause]` over an
           # absent `row[:wheres]` is `Array(nil).map { ... }`, i.e. `[]`, always).
-          # The REAL values, when a read model declares any, arrive through
+          # The real values, when a read model declares any, arrive through
           # `options_of(row)`'s merge in `read_model` below (dispatched as
           # generic Option rows, `read_model_option_rows`/`filter_options` — not
           # as dedicated where-clause rows), which overrides this default. Until
           # `ReadModel#to_h` spelled `wheres`/`order_by`/`limit`
-          # unconditionally, `round_trip_spec`'s own "SOURCE KEYS ONLY" +compare
+          # unconditionally, `round_trip_spec`'s own "source keys only" +compare
           # never asked about this key at all, so the `nil`-vs-`[]` gap between
           # this contract's default and `to_h`'s own `[]` default went unnoticed.
           # `order_by`/`limit` need no matching entry — the generic reader's
@@ -419,7 +426,7 @@ module Hecks
           }
         ),
 
-        # A member's pairs are an OPEN MAP, which is why Member is its own root in
+        # A member's pairs are an open map, which is why Member is its own root in
         # the language. The IR keeps them as a plain hash on the value object, so
         # they are assembled with their shape rather than as a construct.
         # S17, ADR 0026 — Member is a genuine entity now, nested under

data/lib/hecks/bluebook/assembly/marks.rb

@@ -6,10 +6,10 @@ module Hecks
       # `to_h` spells things as text so the export stands on its own, and every
       # one of those spellings has to come back apart here. This is the same family
       # of work `MetaValidator::Shapes` does for the reconstruction — the difference
-      # is that Shapes rebuilds HASHES and this rebuilds OBJECTS, so it has to
+      # is that Shapes rebuilds hashes and this rebuilds objects, so it has to
       # recover types rather than just strings.
       #
-      # ENCODING LOSSES ARE THE LARGEST FAMILY OF BUG IN THIS CODEBASE, and every
+      # Encoding losses are the largest family of bug in this codebase, and every
       # member has the same shape: reading an object where `to_h` holds a spelling.
       # So each method below names the spelling it inverts.
       module Marks
@@ -18,6 +18,14 @@ module Hecks
         # `Attribute#to_h` spells a type with `to_s`, so a reference arrives as
         # "Reference<Customer>" and has to become an edge again. Everything else is
         # a name and stays one.
+        #
+        # @param field [Hash{Symbol => Object}] one attribute's declared row, keyed
+        #   `:type` (String, a plain type name or `"Reference<Target>"`), `:name`
+        #   (String), `:list` and `:optional` (read as truthy), `:default` (Object,
+        #   nil), `:pattern` (String, nil), `:admits` (String, nil) and
+        #   `:relationship` (String, nil), each the raw declared value
+        # @return [Bluebook::Attribute] the attribute, with `type` resolved to a
+        #   `Bluebook::Reference` when the row spelled one
         def attribute(field)
           type = field[:type].to_s
           target = type[/\AReference<(.+)>\z/, 1]
@@ -27,7 +35,7 @@ module Hecks
             type:         target ? Reference.new(target) : type,
             list:         field[:list] ? true : false,
             default:      field[:default],
-            # The LAST place optionality can be dropped, and the one that was
+            # The last place optionality can be dropped, and the one that was
             # dropping it. Every bluebook in the registry is the round-trip
             # product — MetaValidator dispatches the declaration in and reads it
             # back — so a fact this constructor does not carry is a fact the
@@ -35,9 +43,9 @@ module Hecks
             # wrote it.
             optional:     field[:optional] ? true : false,
             pattern:      field[:pattern],
-            # THE SAME LESSON, ONE FACT LATER. `admits` is not on `to_h` — the
+            # **The same lesson, one fact later**. `admits` is not on `to_h` — the
             # wire does not carry it, on purpose — but it must still survive the
-            # round trip, because the grammar registry keeps the ASSEMBLED graph
+            # round trip, because the grammar registry keeps the assembled graph
             # and downstream projections read the link off that. Dropped here, the
             # language could not say `admits` about itself no matter how plainly
             # the source wrote it, which is word for word what the note above
@@ -50,27 +58,45 @@ module Hecks
         # The same shape. Two names because a head's field and a verb's argument are
         # different things in the language even though the IR keeps one class for
         # both — `Aggregate.Attribute` and `Command.Argument` are separate verbs.
+        #
+        # @param field [Hash{Symbol => Object}] see `attribute`
+        # @return [Bluebook::Attribute] see `attribute`
         def shape_field(field) = attribute(field)
 
-        # ONE PART OF AN IDENTITY. It goes in as a row so the language can hold an
+        # One part of an identity. It goes in as a row so the language can hold an
         # ordered list of them, and comes back out as the path it always was —
         # a String, because `identity_paths` splits paths and never symbols.
+        #
+        # @param part [Hash{Symbol => Object}] one identity-path row, keyed `:value`
+        #   (Object, read via `to_s`)
+        # @return [String] the path segment
         def identity_path(part) = part[:value].to_s
 
-        # A member's fields — an OPEN MAP, which is why Member is its own root in
+        # A member's fields — an open map, which is why Member is its own root in
         # the language and why the pairs arrive as a list rather than a value object.
         #
-        # The values are UNMARKED, because `ValueObject#to_h` spells them with `to_s`
+        # The values are unmarked, because `ValueObject#to_h` spells them with `to_s`
         # and the language stores them as text: `member code: "JPY", minor_units: 0`
         # came back with a minor_units of "0", and a closed set that admits the string
         # would refuse the number the caller passes.
+        #
+        # @param pairs [Array<Array(String, Object)>] one member's own field pairs,
+        #   each `[field_name, raw_value]` as declared
+        # @return [Hash{Symbol => Object}] the member's fields, keyed by field name,
+        #   each value read back to its native type through `unmark_scalar`
         def member(pairs)
           pairs.to_h { |key, value| [key.to_sym, unmark_scalar(value)] }
         end
 
         # A read model's gathered head. The keys must be symbols whichever way the
-        # declaration arrived, and `as` must be one too: it NAMES the reader the
+        # declaration arrived, and `as` must be one too: it names the reader the
         # projection answers to, and `ReadModel#to_h` spells it `to_s`.
+        #
+        # @param row [Hash{Symbol => Object}] one aggregate-head row, keyed
+        #   `:aggregate` (String), `:as` (String, the reader name) and `:many`
+        #   (Boolean)
+        # @return [Hash{Symbol => Object}] the head, with every key a Symbol and
+        #   `:as` read back to a Symbol
         def head(row)
           row.to_h { |key, value| [key.to_sym, key.to_sym == :as ? value.to_sym : value] }
         end
@@ -78,12 +104,20 @@ module Hecks
         # A group_by field's own name — the builder's native shape is already
         # `{field: :symbol}`, so this matches it rather than leaving `field`
         # as the String `Shapes#group_by_field` reads back.
+        #
+        # @param row [Hash{Symbol => String}] one group-by row, keyed `:field`
+        # @return [Hash{field: Symbol}] the row with `:field` read back to a Symbol
         def group_by_field(row) = { field: row[:field].to_sym }
 
         # A scalar that was written as itself rather than inspected — a member's
         # value, where the language holds text and the type has to be read back from
         # the shape of it. Unlike `read`, a bare word stays a String here, because
         # a closed set admits words far more often than symbols.
+        #
+        # @param value [Object] the raw declared scalar, read via `to_s`
+        # @return [true, false, Integer, Float, String] `true`/`false` for those
+        #   literal words, a number when the text matches a bare integer or decimal
+        #   pattern, or the string itself otherwise
         def unmark_scalar(value)
           text = value.to_s
           return true       if text == "true"
@@ -97,12 +131,32 @@ module Hecks
         # A saga's argument bindings. Each value rides Literal's spelling, which
         # marks a Symbol with a leading colon — lose it and an argument reads as a
         # string of the same name.
+        #
+        # @param with [Array<Array(String, String)>, nil] the declared bindings,
+        #   each `[argument_name, literal_spelling]` pair, or `nil` for none
+        # @return [Hash{Symbol => Object}] the bindings, keyed by argument name,
+        #   each value read back through `Literal.read`
         def bindings(with) = Array(with).to_h { |key, value| [key.to_sym, read(value)] }
 
+        # Builds one aggregate or value object invariant from its declared row.
+        #
+        # @param rule [Hash{Symbol => String}] one invariant's declared row, keyed
+        #   `:description` and `:canonical` (the canonical-form rendering of the
+        #   rule's expression)
+        # @return [Bluebook::Invariant] the invariant, with `predicate`/`ast` left
+        #   `nil` — `Expression::Evaluator` parses `canonical` on demand when
+        #   neither is set
         def invariant(rule)
           Invariant.new(description: rule[:description], canonical: rule[:canonical])
         end
 
+        # Builds one command precondition from its declared row.
+        #
+        # @param rule [Hash{Symbol => String}] one given's declared row, keyed
+        #   `:description` and `:canonical` (the canonical-form rendering of the
+        #   rule's expression)
+        # @return [Bluebook::Given] the given, with `predicate`/`ast` left `nil` —
+        #   `Expression::Evaluator` parses `canonical` on demand when neither is set
         def given(rule)
           Given.new(description: rule[:description], canonical: rule[:canonical])
         end
@@ -111,6 +165,11 @@ module Hecks
         # All three fields are identifiers, unlike Invariant/Given's own
         # free text, so — like `attribute`'s own `name`/`type` below —
         # they come back as Symbols.
+        #
+        # @param row [Hash{Symbol => String}] one projected-field's declared row,
+        #   keyed `:name`, `:reference` and `:remote_field` (each an identifier)
+        # @return [Bluebook::ProjectedField] the projected field, with each
+        #   identifier read back to a Symbol
         def projected_field(row)
           ProjectedField.new(name: row[:name].to_sym, reference: row[:reference].to_sym,
                              remote_field: row[:remote_field].to_sym)
@@ -118,16 +177,24 @@ module Hecks
 
         # `Mutation#to_h` branches on the operation, so this does too.
         #
-        # An APPEND binds several fields at once, each either an ARGUMENT (a
-        # Symbol, wearing its colon) or a LITERAL — the distinction that is the
+        # An append binds several fields at once, each either an argument (a
+        # Symbol, wearing its colon) or a literal — the distinction that is the
         # whole reason `append: { direction: "out" }` was once indistinguishable
         # from an argument named `out`.
+        #
+        # @param change [Hash{Symbol => Object}] one mutation's declared row, keyed
+        #   `:target` (String), `:op` (String, such as `"set"`, `"append"`,
+        #   `"delegate"` or `"corrects"`), `:fields` (Array, for the append-shaped
+        #   ops) and `:source` (Hash, for any other op)
+        # @return [Bluebook::Mutation] the mutation, with `source` a
+        #   `Hash{Symbol => Object}` of field bindings for an append-shaped op, or
+        #   `classified`'s own result for any other
         def mutation(change)
           target = change[:target].to_sym
           op     = change[:op].to_sym
 
           # `:delegate`/`:corrects` (CommandBuilder#delegates_to's and
-          # #corrects_impl's own comments) ride the SAME multi-binding
+          # #corrects_impl's own comments) ride the same multi-binding
           # shape `:append` does.
           return Mutation.new(target: target, op: op, source: appended(change[:fields])) if [:append, :delegate,
                                                                                              :corrects].include?(op)
@@ -135,12 +202,27 @@ module Hecks
           Mutation.new(target: target, op: op, source: classified(change[:source]))
         end
 
+        # Reads an append mutation's field bindings back off their declared rows.
+        #
+        # @param fields [Array<Array(String, String)>, nil] the append's declared
+        #   field bindings, each `[field_name, literal_spelling]` pair, or `nil`
+        #   for none
+        # @return [Hash{Symbol => Object}] the bindings, keyed by field name, each
+        #   value read back through `Literal.read`
         def appended(fields)
           Array(fields).to_h { |field, source| [field.to_sym, read(source)] }
         end
 
-        # A SET reads one thing, and `classified_source` said which: an argument by
+        # A set reads one thing, and `classified_source` said which: an argument by
         # name, or a literal by value.
+        #
+        # @param source [Hash{Symbol => Object}, nil] the mutation's declared
+        #   source, keyed `:kind` (String, `"argument"`, `"state"` or a literal
+        #   kind) plus `:name` (String, for `"argument"`/`"state"`) or `:value`
+        #   (Object, for a literal), or `nil` for no source
+        # @return [Symbol, Hecks::StateRef, Object, nil] the command argument name,
+        #   a state self-reference, the literal value, or `nil` when `source` is
+        #   `nil`
         def classified(source)
           return nil if source.nil?
 
@@ -151,41 +233,57 @@ module Hecks
           end
         end
 
-        # EVERY LITERAL FIELD ON THE WIRE, read back — one spelling, one reader.
+        # Every literal field on the wire, read back — one spelling, one reader.
         #
         # A where-clause value, a saga's argument bindings, an append binding, a
         # limit: all of them ride Literal's self-describing form, so all of them
-        # come back through here. There were two readers (`read` and `unmark`)
-        # that disagreed about quoted strings and numbers, and which one a call
-        # site got was a coin toss the comments had to keep apologising for.
-        #
-        # AN OBJECT LITERAL is the one that bit. A saga leg binds `narrative: {
-        # text: "transfer out" }` — a value object's fields written inline — and
-        # `to_s` on a Hash used to be its inspect form, so it came back as text.
-        # Read as a string it reached the runtime as `"{:text=>\"transfer out\"}"`,
-        # coercion refused it, the debit leg was never delivered, and the whole
-        # settlement wire stopped: banking emitted TransferRequested five times and
-        # TransferDebited never. A whole-history replay gate caught what every other
-        # gate missed, because a saga that silently does nothing looks exactly like
-        # a saga with nothing to do.
+        # come back through this one reader, never a second one that might
+        # disagree about a quoted string or a number.
+        #
+        # An object literal is the one that bites hardest. A saga leg binds
+        # `narrative: { text: "transfer out" }` — a value object's fields written
+        # inline — and reading it as a plain string rather than through `Literal`
+        # would reach the runtime as `"{:text=>\"transfer out\"}"`, which coercion
+        # refuses: the debit leg is never delivered, and the whole settlement wire
+        # stops — banking emits TransferRequested five times and TransferDebited
+        # never. A whole-history replay gate is what catches this, because a saga
+        # that silently does nothing looks exactly like a saga with nothing to do.
+        #
+        # @param value [String, Object] wire spelling produced by `Literal.render`,
+        #   or a bare word
+        # @return [nil, true, false, Integer, Float, Symbol, Hecks::StateRef,
+        #   String, Hash, Array] the value read back — see `Literal.read`
         def read(value) = Literal.read(value)
 
         # `target:` (ADR 0055) — read straight off the wire, unconverted:
-        # it's already the bare aggregate-name STRING `WhereClause#to_h`/
+        # it's already the bare aggregate-name string `WhereClause#to_h`/
         # `OrderBy#to_h`/`LimitSpec#to_h` wrote (`resolve_target`'s own
         # `Naming.demodulise` already ran once, at DSL-build time; this is
-        # the REPLAY path every real boot actually goes through, reading
+        # the replay path every real boot actually goes through, reading
         # that same wire shape back — see this class's own header). Absent
         # from `clause`/`declared` entirely on older wire data that never
         # declared `on:` — `clause[:target]`/`declared[:target]` reads
         # `nil` for a missing key exactly like an explicit `nil` would,
         # so this is additive, not a migration.
+        #
+        # @param clause [Hash{Symbol => Object}] one where-clause's declared row,
+        #   keyed `:field` (String), `:op` (String, a comparator name), `:value`
+        #   (String, Literal's spelling) and `:target` (String, `nil` when absent)
+        # @return [QuerySpecification::Common::WhereClause] the clause, with `op`
+        #   read to a Symbol and `value` read back through `Literal.read`
         def where_clause(clause)
           QuerySpecification::Common::WhereClause.new(
             field: clause[:field], op: clause[:op].to_sym, value: read(clause[:value]), target: clause[:target]
           )
         end
 
+        # Builds a query's declared ordering, if it declares one.
+        #
+        # @param declared [Hash{Symbol => Object}, nil] the declared order-by row,
+        #   keyed `:field` (String), `:direction` (String) and `:target` (String,
+        #   `nil` when absent), or `nil` when the construct declares no ordering
+        # @return [QuerySpecification::Common::OrderBy, nil] the order-by, with
+        #   `direction` read to a Symbol, or `nil` when `declared` is `nil`
         def order_by(declared)
           return nil unless declared
 
@@ -194,13 +292,21 @@ module Hecks
           )
         end
 
+        # Builds a query's declared limit, if it declares one.
+        #
+        # @param declared [Hash{Symbol => Object}, nil] the declared limit row,
+        #   keyed `:value` (String, Literal's spelling) and `:target` (String,
+        #   `nil` when absent), or `nil` when the construct declares no limit
+        # @return [QuerySpecification::Common::LimitSpec, nil] the limit, with
+        #   `value` read back through `Literal.read`, or `nil` when `declared` is
+        #   `nil`
         def limit(declared)
           return nil unless declared
 
           QuerySpecification::Common::LimitSpec.new(value: read(declared[:value]), target: declared[:target])
         end
 
-        # EVERY OTHER SPECIFICATION OPTION, from one table.
+        # Every other specification option, from one table.
         #
         # Each entry names the struct and which of its members carry a value that
         # rode Literal's spelling rather than plain text. A
@@ -219,6 +325,20 @@ module Hecks
         # with `to_s`, so the colon is not there to strip.
         SYMBOLIC = %i[mode policy tenant].freeze
 
+        # Builds one query specification option from its declared row and `OPTIONS`.
+        #
+        # @param name [Symbol] the option's name, a key of `OPTIONS` (`:offset`,
+        #   `:cursor`, `:null_semantics`, `:authorization` or `:inspection`)
+        # @param declared [Hash{Symbol => Object}, nil] the option's declared row,
+        #   or `nil` when the construct does not declare this option
+        # @return [QuerySpecification::Common::OffsetSpec,
+        #   QuerySpecification::Common::CursorSpec,
+        #   QuerySpecification::Common::NullSemantics,
+        #   QuerySpecification::Common::AuthorizationSpec,
+        #   QuerySpecification::Common::InspectionSpec, nil] the option built
+        #   through the holder `OPTIONS` names for `name`, or `nil` when `declared`
+        #   is `nil`
+        # @raise [KeyError] if `name` is not a key of `OPTIONS`
         def option(name, declared)
           return nil if declared.nil?
 
@@ -226,6 +346,15 @@ module Hecks
           holder.new(**Hash(declared).to_h { |key, value| [key, option_value(key, value, marked)] })
         end
 
+        # Reads one option member's declared value back to its native type.
+        #
+        # @param key [Symbol] the option member's name being read
+        # @param value [Object, nil] the declared value for that member
+        # @param marked [Array<Symbol>] the members of this option that ride
+        #   Literal's spelling, from `OPTIONS`
+        # @return [Object, nil] `value` read back through `Literal.read` when
+        #   `key` is marked, a Symbol when `key` is one of `SYMBOLIC`, the raw
+        #   `value` otherwise, or `nil` when `value` is `nil`
         def option_value(key, value, marked)
           return nil               if value.nil?
           return read(value)       if marked.include?(key)