hecks 0.2.0 → 0.3.0

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

@@ -0,0 +1,409 @@
+module Hecks
+  module Bluebook
+    class Assembly
+      # 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:
+      #
+      #   holder    which class holds it
+      #   make      :declare for a construct that became a class, :new for an
+      #             instance — the boundary `Query` sits on, since its body is
+      #             inherited instance methods
+      #   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
+      # 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.
+      #
+      # 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.
+      def self.contract(category) = CONTRACTS.fetch(category.to_s)
+
+      CONTRACTS = {
+        "Bluebook"       => Contract.new(
+          holder: Chapter, make: :new,
+          fields: {
+            name:              [:name,           :plain],
+            version:           [:version,        :plain],
+            vision:            [:vision,         :plain],
+            classification:    [:classification, :plain],
+            formerly_known_as: [:formerly_known_as, :plain],
+            attaches_to:       [:attaches_to, :plain]
+          },
+          rows: { normalisations: :normalisation_table },
+          derived: { normalisations: :elsewhere }
+        ),
+
+        "Aggregate"      => Contract.new(
+          holder: Aggregate, make: :new,
+          fields: {
+            name:             [:name,          :plain],
+            description:      [:description,   :plain],
+            identified_by:    [:identified_by, :plain],
+            attributes:       [:attributes,    [:each, :attribute]],
+            # 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,
+            # `given` a Given, the same struct AggregateBuilder#given
+            # hands a referencing command's own resolved list.
+            invariants:       [:invariants,    [:each, :invariant]],
+            preconditions:    [:preconditions, [:each, :given]],
+            # S12, ADR 0025 — the local half of "projects :name, from:
+            # :\"reference.remote_field\"", read the same way
+            # invariants/preconditions above are: a synthetic command
+            # (Aggregate.Projects) the judge dispatches once per
+            # declaration, folded into a list on the owning aggregate.
+            projected_fields: [:projected_fields, [:each, :projected_field]],
+            provenance:       [:provenance, :plain]
+          },
+          rows: { transitions: :transition_rows, value_objects: :value_object_names, identified_by: :identity_rows },
+          reads: { identified_by: [:each, :identity_path], attributes: [:each_with_id, :attribute],
+                   invariants: [:each, :rule], preconditions: [:each, :rule],
+                   projected_fields: [:each, :projected_field] },
+          derived: {
+            position:      :walk,
+            state_field:   [:folded, :lifecycle, :field],
+            state_start:   [:folded, :lifecycle, :default],
+            transitions:   [:folded, :lifecycle, :transitions],
+            value_objects: :children
+          }
+        ),
+
+        "Command"        => Contract.new(
+          holder: Command, make: :declare,
+          fields: {
+            name:       [:name,       :plain],
+            role:       [:role,       :plain],
+            goal:       [:goal,       :plain],
+            references: [:references, :plain],
+            attributes: [:attributes, [:each, :shape_field]],
+            givens:     [:givens,     [:each, :given]],
+            ensures:    [:ensures,    [:each, :given]],
+            mutations:  [:mutations,  [:each, :mutation]],
+            emits:      [:emits,      :plain],
+            # 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.
+            from:       [:from,       :plain],
+            provenance: [:provenance, :plain]
+          },
+          rows: { mutations: :mutation_rows },
+          reads: { attributes: [:each, :shape_field], givens: [:each, :rule], ensures: [:each, :rule],
+                  mutations: [:call, :mutations], emits: :names, provenance: :provenance, from: :from },
+          derived: { position: :walk }
+        ),
+
+        "ValueObject"    => Contract.new(
+          holder: ValueObject, make: :declare,
+          fields: {
+            name:       [:name,       :plain],
+            attributes: [:attributes, [:each, :shape_field]],
+            invariants: [:invariants, [:each, :invariant]],
+            members:    [:members,    [:each, :member]],
+            closed_set: [:closed_set, :flag]
+          },
+          # The language counts the admitted rows ; the IR keeps a flag and the rows.
+          reads: { attributes: [:each, :shape_field], invariants: [:each, :rule],
+                  closed_set: [:call, :closed_set_of], members: [:call, :members_row] },
+          derived: { position: :walk, rows: [:folded, %i[closed_set members], nil] }
+        ),
+
+        "Query"          => Contract.new(
+          holder: Query, make: :new,
+          fields: {
+            name:           [:name,        :plain],
+            description:    [:description, :plain],
+            attributes:     [:attributes,  [:each, :shape_field]],
+            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
+            # same way and a ninth option needs no new field on either side.
+            offset:         [:offset,          [:option, :offset]],
+            cursor:         [:cursor,          [:option, :cursor]],
+            null_semantics: [:null_semantics,  [:option, :null_semantics]],
+            authorization:  [:authorization,   [:option, :authorization]],
+            inspection:     [:inspection,      [:option, :inspection]]
+          },
+          rows: { wheres: :where_rows, options: :option_rows },
+          reads: { attributes: [:each, :shape_field], wheres: [:each, :where_clause],
+                  order_by: [:call, :order_by], limit: [:call, :limit] },
+          derived: {
+            position:    :walk,
+            order_field: [:folded, :order_by, :field],
+            order_way:   [:folded, :order_by, :direction],
+            options:     [:folded, %i[offset cursor null_semantics authorization inspection], nil]
+          }
+        ),
+
+        "Entity"         => Contract.new(
+          holder: Entity, make: :declare,
+          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.
+            identified_by: [:identified_by, :plain],
+            attributes:    [:attributes,    [:each, :shape_field]],
+            # 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`
+            # already carries, one level down: checked against every
+            # instance of this piece, not the aggregate's own flat state.
+            invariants:    [:invariants,    [:each, :invariant]]
+          },
+          rows: { transitions: :transition_rows, identified_by: :identity_rows },
+          reads: { identified_by: [:each, :identity_path], attributes: [:each, :shape_field],
+                   preconditions: [:each, :rule], invariants: [:each, :rule] },
+          derived: {
+            position:    :walk,
+            owner:       :parent,
+            state_field: [:folded, :lifecycle, :field],
+            state_start: [:folded, :lifecycle, :default],
+            transitions: [:folded, :lifecycle, :transitions]
+          }
+        ),
+
+        "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]
+          },
+          rows: { with_spec: :with_spec_rows },
+          reads: { with_spec: [:from, :with_spec] },
+          derived: { position: :walk }
+        ),
+
+        "ProcessManager" => Contract.new(
+          holder: ProcessManager, make: :new,
+          fields: {
+            name:          [:name,          :plain],
+            # 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
+            # should have held 2500 held 0. to_h could not show it: it stringifies.
+            correlates_by: [:correlates_by, :identity],
+            starts_on:     [:starts_on,     :plain],
+            ends_on:       [:ends_on,       :plain],
+            states:        [:states,        :plain]
+          },
+          reads: { states: :names },
+          # 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
+          # `.parent == "ProcessManager"`) rather than by any field this
+          # contract itself reads — the same `:children` shape Aggregate's
+          # own `value_objects` claim already uses, one level in.
+          derived: { position: :walk, handlers: :children }
+        ),
+
+        # 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,
+        # 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
+        # pointer out of.
+        "Handler"        => Contract.new(
+          holder: ProcessManagerHandler, make: :new,
+          fields: {
+            event_type: [:event_type, :plain],
+            from_state: [:from_state, :plain],
+            to_state:   [:to_state,   :plain]
+          },
+          # `dispatches` — same reason ProcessManager's own `handlers`
+          # claim, above, is `:children` : a real feature of the
+          # 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.
+          derived: { dispatches: :children }
+        ),
+
+        # S17, ADR 0026 — Dispatch is a genuine entity now, nested under
+        # Handler (`entity "Dispatch"`, reaction.bluebook) — two levels
+        # deep, "no life outside its Handler" (the ADR's own words).
+        # `command_name` is Dispatch's own real, non-positional identity
+        # — neither `position` nor `handler` is a stored field any more,
+        # the same reason Handler's own contract, above, dropped them.
+        "Dispatch"       => Contract.new(
+          holder: DispatchSpec, make: :new,
+          fields: {
+            command_name: [:command_name, :plain],
+            with_spec:    [:with_spec,    :bindings]
+          },
+          rows: { with_spec: :with_spec_rows },
+          reads: { with_spec: [:from, :with_spec] },
+          derived: {}
+        ),
+
+        # S14, ADR 0026 — Syntax/Keyword/Argument are never built via
+        # `Build`/`Reconstruction`'s own generic path — their own data
+        # lives in a dedicated repository `SyntaxBoot` (meta_validator/
+        # syntax_boot.rb) reads directly, never through the meta-
+        # domain's own reconstruction, the same reason `Member`'s own
+        # entry (above) carries `holder: nil, make: nil` too. These
+        # entries exist purely so the introspection specs
+        # (assembly_spec.rb) can hold them to the same "every field
+        # claimed" discipline every other category answers to.
+        "Syntax"         => Contract.new(
+          holder: nil, make: nil,
+          fields: { name: [:name, :plain] },
+          derived: { keywords: :children, arguments: :children }
+        ),
+
+        "Keyword"        => Contract.new(
+          holder: nil, make: nil,
+          fields: {
+            word:          [:word,          :plain],
+            context:       [:context,       :plain],
+            body:          [:body,          :plain],
+            inner:         [:inner,         :plain],
+            opens:         [:opens,         :plain],
+            fills:         [:fills,         :plain],
+            was:           [:was,           :plain],
+            resolves_via:  [:resolves_via,  :plain],
+            disambiguator: [:disambiguator, :plain],
+            calls:         [:calls,         :plain]
+          },
+          derived: { position: :walk }
+        ),
+
+        "Argument"       => Contract.new(
+          holder: nil, make: nil,
+          fields: {
+            keyword:          [:keyword,          :plain],
+            context:          [:context,          :plain],
+            at:               [:at,               :plain],
+            named:            [:named,            :plain],
+            kind:             [:kind, :plain],
+            required:         [:required,         :plain],
+            fills:            [:fills,            :plain],
+            selects:          [:selects,          :plain],
+            pair_key_fills:   [:pair_key_fills,   :plain],
+            pair_value_fills: [:pair_value_fills, :plain],
+            pairs_shape:      [:pairs_shape,      :plain],
+            variadic:         [:variadic,         :plain],
+            minimum:          [:minimum,          :plain],
+            coerce:           [:coerce,           :plain],
+            blank_message:    [:blank_message,    :plain]
+          },
+          derived: { position: :walk }
+        ),
+
+        "ReadModel"      => Contract.new(
+          holder: ReadModel, make: :new,
+          fields: {
+            name:             [:name,             :plain],
+            description:      [:description,      :plain],
+            reference_name:   [:reference_name,   :identity],
+            reference_target: [:reference_target, :plain],
+            aggregate_heads:  [:aggregate_heads,  [:each, :head]],
+            group_by:         [:group_by,         [:each, :group_by_field]],
+            # `count`/`median_field` are `group_by`'s own two siblings —
+            # scalars, not lists, so no `[:each, ...]` shape ; `:plain`
+            # 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).
+            count:            [:count,            :plain],
+            median_field:     [:median_field,     :plain],
+            # A read model inherits every option an ask has, so it reads them the
+            # same way — see Query.
+            wheres:           [:wheres,           [:each, :where_clause]],
+            order_by:         [:order_by,         :order_by],
+            limit:            [:limit,            :limit],
+            offset:           [:offset,           [:option, :offset]],
+            cursor:           [:cursor,           [:option, :cursor]],
+            null_semantics:   [:null_semantics,   [:option, :null_semantics]],
+            authorization:    [:authorization,    [:option, :authorization]],
+            inspection:       [:inspection,       [:option, :inspection]]
+          },
+          rows: { options: :read_model_option_rows },
+          # `wheres` needs its own reader for the same reason Query's does — a
+          # list defaults to `[]`, not the generic `text(row[key])` cell reader's
+          # `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
+          # `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
+          # 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
+          # `nil` already agrees with `to_h`'s own nil-when-undeclared default
+          # for those two. `group_by` needs its own reader the same way — a
+          # rootless read model's grouping keys, added independently on main.
+          reads: { reference_name: :symbol, aggregate_heads: [:each, :head],
+                  group_by: [:each, :group_by_field], wheres: [:each, :where_clause],
+                  # `count` needs the boolean coercion `Shapes#read_model_count`
+                  # gives it (a stringified "true"/absent on the wire, a real
+                  # `true`/`nil` in `to_h`) — `median_field` needs none: the
+                  # default `text(row[key])` cell reader already returns the
+                  # same String-or-nil `ReadModel#to_h`'s own `&.to_s` does.
+                  count: :read_model_count },
+          derived: {
+            position:   :walk,
+            query_name: [:computed, :query_name],
+            options:    [:folded, %i[offset cursor null_semantics authorization inspection], nil]
+          }
+        ),
+
+        # 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
+        # ValueObject (`entity "Member"`, shape.bluebook). It no longer
+        # holds a `shape` field at all (that was the free-text, un-parsed
+        # spelling a standalone root once needed ; an entity's element is
+        # never serialized as text) — only `position` (walk-minted, see
+        # `entity_own_identity`, judge.rb) and `pairs` (still an open map,
+        # still one row per entry, still why a value object cannot hold it
+        # directly).
+        "Member"         => Contract.new(
+          holder: nil, make: nil,
+          fields: {},
+          rows: { pairs: :pair_rows },
+          derived: { position: :walk, pairs: [:folded, %i[members], nil] }
+        )
+      }.freeze
+    end
+  end
+end

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

@@ -0,0 +1,227 @@
+module Hecks
+  module Bluebook
+    class Assembly
+      # The leaf shapes an assembly reads, and the encodings it undoes.
+      #
+      # `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
+      # recover types rather than just strings.
+      #
+      # 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
+        module_function
+
+        # `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.
+        def attribute(field)
+          type = field[:type].to_s
+          target = type[/\AReference<(.+)>\z/, 1]
+
+          Attribute.new(
+            name:         field[:name],
+            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
+            # 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
+            # language cannot state about itself, however plainly the source
+            # wrote it.
+            optional:     field[:optional] ? true : false,
+            pattern:      field[:pattern],
+            # 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
+            # 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
+            # already learned about `optional`.
+            admits:       field[:admits],
+            relationship: field[:relationship]
+          )
+        end
+
+        # 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.
+        def shape_field(field) = attribute(field)
+
+        # 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.
+        def identity_path(part) = part[:value].to_s
+
+        # 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`
+        # 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.
+        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
+        # projection answers to, and `ReadModel#to_h` spells it `to_s`.
+        def head(row)
+          row.to_h { |key, value| [key.to_sym, key.to_sym == :as ? value.to_sym : value] }
+        end
+
+        # 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.
+        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.
+        def unmark_scalar(value)
+          text = value.to_s
+          return true       if text == "true"
+          return false      if text == "false"
+          return text.to_i  if text.match?(/\A-?\d+\z/)
+          return text.to_f  if text.match?(/\A-?\d+\.\d+\z/)
+
+          text
+        end
+
+        # 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.
+        def bindings(with) = Array(with).to_h { |key, value| [key.to_sym, read(value)] }
+
+        def invariant(rule)
+          Invariant.new(description: rule[:description], canonical: rule[:canonical])
+        end
+
+        def given(rule)
+          Given.new(description: rule[:description], canonical: rule[:canonical])
+        end
+
+        # S12, ADR 0025 — `projects :name, from: :"reference.remote_field"`.
+        # 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.
+        def projected_field(row)
+          ProjectedField.new(name: row[:name].to_sym, reference: row[:reference].to_sym,
+                             remote_field: row[:remote_field].to_sym)
+        end
+
+        # `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
+        # whole reason `append: { direction: "out" }` was once indistinguishable
+        # from an argument named `out`.
+        def mutation(change)
+          target = change[:target].to_sym
+          op     = change[:op].to_sym
+
+          # `:delegate` (CommandBuilder#delegates_to's own comment) rides
+          # the SAME multi-binding shape `:append` does.
+          return Mutation.new(target: target, op: op, source: appended(change[:fields])) if [:append, :delegate].include?(op)
+
+          Mutation.new(target: target, op: op, source: classified(change[:source]))
+        end
+
+        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
+        # name, or a literal by value.
+        def classified(source)
+          return nil if source.nil?
+
+          case source[:kind].to_s
+          when "argument" then source[:name].to_sym
+          when "state"    then StateRef.new(source[:name].to_sym)
+          else source[:value]
+          end
+        end
+
+        # 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.
+        def read(value) = Literal.read(value)
+
+        def where_clause(clause)
+          QuerySpecification::Common::WhereClause.new(
+            field: clause[:field], op: clause[:op].to_sym, value: read(clause[:value])
+          )
+        end
+
+        def order_by(declared)
+          return nil unless declared
+
+          QuerySpecification::Common::OrderBy.new(
+            field: declared[:field], direction: declared[:direction].to_sym
+          )
+        end
+
+        def limit(declared)
+          return nil unless declared
+
+          QuerySpecification::Common::LimitSpec.new(value: read(declared[:value]))
+        end
+
+        # 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
+        # ninth option is one row here and nothing else — the language already holds
+        # it, because it holds options as an open map rather than a field each.
+        OPTIONS = {
+          offset:         [QuerySpecification::Common::OffsetSpec,        %i[value]],
+          cursor:         [QuerySpecification::Common::CursorSpec,        %i[value]],
+          null_semantics: [QuerySpecification::Common::NullSemantics,     []],
+          authorization:  [QuerySpecification::Common::AuthorizationSpec, %i[policy tenant]],
+          inspection:     [QuerySpecification::Common::InspectionSpec,    []]
+        }.freeze
+
+        # `mode` and `policy` are read as symbols because the DSL declares them that
+        # way — `nulls :last`, `authorize :customer_access` — and `to_h` spells them
+        # with `to_s`, so the colon is not there to strip.
+        SYMBOLIC = %i[mode policy tenant].freeze
+
+        def option(name, declared)
+          return nil if declared.nil?
+
+          holder, marked = OPTIONS.fetch(name)
+          holder.new(**Hash(declared).to_h { |key, value| [key, option_value(key, value, marked)] })
+        end
+
+        def option_value(key, value, marked)
+          return nil               if value.nil?
+          return read(value)       if marked.include?(key)
+          return value.to_sym      if SYMBOLIC.include?(key)
+
+          value
+        end
+      end
+    end
+  end
+end