hecks 0.2.0 → 1.0.0

data/lib/hecks/bluebook/meta_validator/reconstruction.rb

@@ -0,0 +1,351 @@
+module Hecks
+  module Bluebook
+    module MetaValidator
+      # A bluebook rebuilt FROM the meta-domain, in the shape the builder produces.
+      #
+      # This is the second half of the claim at the top of bluebook.bluebook —
+      # "loading a domain becomes dispatching commands into this meta-domain ; the
+      # IR it stores must equal the IR the DSL builder produces". The judge is the
+      # first half. This reads the records back and assembles `to_h`.
+      #
+      # It is the INVERSE OF THE WALK and shares its plan: the walk reads a node's
+      # lists through the command that appends to each, and this reads them back out
+      # of the rows those commands wrote. The retired `experiment/replay.rb` needed
+      # 420 hand-written lines because the dispatch half was hand-written too; there
+      # is nothing to hand-write when both directions are one table.
+      #
+      # This file is the TRAVERSAL. The hashes at its tips, and the encodings they
+      # undo, are in Shapes.
+      #
+      # IT READS LEVEL BY LEVEL, THROUGH `DeclaredIn`, AND NOT THROUGH THE READ
+      # MODEL — which is the difference between a reconstruction that can be the
+      # SOURCE and one that can only be a check.
+      #
+      # `Meta.whole_bluebook` gathers a chapter in a single read, and it sorts:
+      # `ReadModelInterpreter#matching` ends `.sort_by(&:id)` deliberately, because
+      # a store's iteration order is an accident, and a read model returning store
+      # order would let that accident leak into an answer.
+      # Right for a read model, fatal here — the order a bluebook declares its
+      # commands in is a FACT ABOUT THE SOURCE, and the IR is a contract field for
+      # field and index for index ; the export carries that order verbatim.
+      # `DeclaredIn` preserves it (spec/executes_spec says so), so this asks each
+      # level for its own children rather than filtering one sorted gather.
+      #
+      # The parent key of every level is read from the language's own plan, the same
+      # Plan the walk dispatches from — so the two directions really are one table,
+      # which is what the header above has always claimed.
+      #
+      # WHAT IT CANNOT REBUILD matters as much as what it can, and
+      # spec/round_trip_spec pins the difference as an exact set: a field the language
+      # does not hold appears there as a named gap, and a field it stops holding
+      # appears as a failure.
+      class Reconstruction
+        include Readings
+        include Shapes
+
+        def self.of(runtime, chapter) = new(runtime, chapter).to_h
+
+        def initialize(runtime, chapter)
+          @runtime = runtime
+          @plan    = Plan.for(MetaValidator.grammar_registry)
+          @chapter = runtime.query("Bluebook::Bluebook.Called", name: { value: chapter }).first or
+            raise NotFound, "the meta-domain holds no bluebook called #{chapter.inspect}"
+        end
+
+        def to_h
+          {
+            name:              text(@chapter[:name]),
+            version:           text(@chapter[:version]),
+            vision:            text(@chapter[:vision]),
+            classification:    text(@chapter[:classification]),
+            formerly_known_as: text(@chapter[:formerly_known_as]),
+            attaches_to:       attached_contexts(@chapter),
+            aggregates:        declared("Aggregate", chapter_id).map { |row| aggregate(row) },
+            read_models:       declared("ReadModel", chapter_id).map { |row| read_model(row) },
+            policies:          declared("Policy", chapter_id).map { |row| policy(row) },
+            process_managers:  declared("ProcessManager", chapter_id).map { |row| process_manager(row) }
+          }
+        end
+
+        private
+
+        def chapter_id = @chapter[:id].to_s
+
+        # Everything DECLARED IN one parent, in the order it was declared. The key
+        # is the one the language's own creating command carries, read from Plan.
+        def declared(category, parent_id)
+          key = @plan.category(category).parent_key
+          @runtime.query("Bluebook::#{category}.DeclaredIn", key.to_sym => { value: parent_id.to_s })
+        end
+
+        # ONE DECLARATION, BUILT FROM THE CONTRACT.
+        #
+        # There were eleven methods here, one per category, each spelling out the same
+        # keys `Assembly::Contracts` already names — which is the shape the judge used
+        # to have and paid fourteen unoffered verbs for. The keys come from the table
+        # now, and the exceptions come from its `reads:` column: a list needs a reader
+        # per element, a folded field is gathered rather than fetched, and everything
+        # else is one cell.
+        #
+        # `extra` is what the containment supplies — children, and the folded objects
+        # a row cannot hold on its own.
+        def declaration(category, row, extra = {})
+          contract = Assembly.contract(category)
+
+          contract.fields.each_with_object({}) do |(_keyword, (key, _build)), out|
+            next if extra.key?(key)
+
+            out[key] = read_row(contract.reader(key), key, row)
+          end.merge(extra)
+        end
+
+        def read_row(spec, key, row)
+          case spec
+          when nil      then text(row[key])
+          when :symbol  then text(row[key])&.to_sym
+          when :names   then Array(row[key]).map { |held| text(held[:name]) }
+          when Array    then read_shaped(spec, key, row)
+          else send(spec, row)
+          end
+        end
+
+        # The readers are the ones `Shapes` already has, called by name — no wrappers,
+        # so nothing shadows them. `:each_with_id` is the single exception that needs
+        # more than the element: an attribute's type came in as the ID of whatever it
+        # names, so reading it back needs the row it belongs to.
+        def read_shaped(spec, key, row)
+          shape, named = spec
+
+          case shape
+          when :each         then Array(row[key]).map { |held| send(named, held) }
+          when :each_with_id then Array(row[key]).map { |held| send(named, held, row[:id]) }
+          when :call         then send(named, row)
+          when :from         then pairs(row[named])
+          end
+        end
+
+        def pairs(with) = Array(with).map { |binding| [text(binding[:key]), text(binding[:value])] }
+
+        # THE PARTS, IN THE ORDER THEY WENT IN, because the identity is their join
+        # and a join read out of order names a different record.
+        def identity_paths(row) = Array(row[:identified_by]).map { |part| text(part[:value]).to_s }
+
+        # THE CONTEXTS ONE CHAPTER NAMES ITSELF ONTO, in the order they were
+        # attached — same shape identity_paths reads back, one level up.
+        def attached_contexts(row) = Array(row[:attaches_to]).map { |part| text(part[:value]).to_s }
+
+        # Every cell of the meta-domain is a single-field value object, so a row
+        # arrives holding Values rather than Strings.
+        def text(cell)
+          return nil if cell.nil?
+          return cell.to_h.values.first if cell.respond_to?(:to_h) && !cell.is_a?(String)
+
+          cell
+        end
+
+        # An aggregate's OWN verbs and asks — the ones no entity declared. Both carry
+        # the parent link either way, because that is the head the reference resolves
+        # against, so the entity ones have to be told apart by `entity_id`. Rejecting
+        # from an ORDERED read keeps the order.
+        def own(category, aggregate_id)
+          declared(category, aggregate_id).reject { |row| text(row[:entity_id]).to_s != "" }
+        end
+
+        # A piece's own verbs and asks. There is no `DeclaredIn` keyed by entity, so
+        # this reads the aggregate's — in declaration order — and keeps the ones that
+        # name this piece. `row[:aggregate]` — an ENTITY row's own `reference_to
+        # Aggregate` (bare, no `_id` since ADR 0025) — not `entity_id`, which
+        # STAYS suffixed below : that one is Command/Query's own EXPLICIT `as:`,
+        # never touched by the rename.
+        def within(category, row)
+          declared(category, text(row[:aggregate]))
+            .select { |held| text(held[:entity_id]).to_s == row[:id].to_s }
+        end
+
+        def aggregate(row)
+          id = row[:id]
+
+          {
+            name:             text(row[:name]),
+            description:      text(row[:description]),
+            identified_by:    identity_paths(row),
+            attributes:       Array(row[:attributes]).map { |field| attribute(field, id) },
+            value_objects:    declared("ValueObject", id).map { |shape| value_object(shape) },
+            commands:         own("Command", id).map { |verb| command(verb) },
+            # THE AGGREGATE BOUNDARY, and the precondition a command may
+            # reference by name (S10, ADR 0025 — "Rules") — the same
+            # `rule` reader `command`'s own givens/ensures already use
+            # (Assembly::Contracts' generic `declaration()` path), read
+            # here by hand because `aggregate(row)` itself is hand-typed,
+            # unlike `command`/`value_object`/`query` below.
+            invariants:       Array(row[:invariants]).map { |held| rule(held) },
+            preconditions:    Array(row[:preconditions]).map { |held| rule(held) },
+            # S12, ADR 0025 — same reason invariants/preconditions are
+            # read by hand two lines up: `aggregate(row)` is hand-typed.
+            projected_fields: Array(row[:projected_fields]).map { |held| projected_field(held) },
+            lifecycle:        lifecycle(row),
+            entities:         direct_entities(id, id).map { |piece| entity(piece) },
+            queries:          own("Query", id).map { |ask| query(ask) },
+            provenance:       provenance(row)
+          }
+        end
+
+        def value_object(row) = declaration("ValueObject", row)
+
+        def closed_set_of(row) = !text(row[:rows]).nil?
+
+        # A closed set's admitted rows. S17, ADR 0026 — Member is a genuine
+        # ENTITY now (`entity "Member" do ... end`, nested under
+        # ValueObject), created by `ValueObject.Member` (an ordinary append,
+        # the same way `Account.LogEntry` creates a LedgerEntry) and mutated
+        # by its own dotted `ValueObject.Member.Pair`. Its data therefore
+        # lives INLINE on the value object's own dispatched state — same as
+        # any other entity list — not behind a separate `DeclaredIn` query:
+        # there is no such query any more, because there is no top-level
+        # "Member" aggregate left to hold one. Pairs are still an OPEN MAP,
+        # which no value object can hold, so they still come back one pair
+        # at a time.
+        def members_row(row) = members_of(row)
+
+        # THE KEY IS STRINGIFIED, NEVER THE VALUE — the same split
+        # `Bluebook::ValueObject#to_h`'s own `members:` emission makes
+        # (lib/hecks/bluebook/value_object.rb, L7 docs/audits/
+        # 2026-08-11-bug-triage.md). `Pair.value` is declared `String`
+        # (shape.bluebook), but a real pair can hold whatever native Ruby
+        # type the source member line actually wrote (`StatementFrequency`'s
+        # own `retention_months: 84`, examples/banking/bluebook/
+        # statements.bluebook) — `text` already unwraps the stored Value to
+        # that real type, so calling `.to_s` here erased it a second time,
+        # on the side spec/round_trip_spec.rb compares straight against a
+        # fresh raw load (`Reconstruction.of` directly, no Assembly in
+        # between): `declared 84, read back "84"` the moment `to_h` stopped
+        # erasing it on the OTHER side and this one kept erasing it alone.
+        def members_of(value_object_row)
+          Array(value_object_row[:members]).map do |member|
+            Array(member[:pairs]).map { |pair| [text(pair[:key]).to_s, text(pair[:value])] }
+          end
+        end
+
+        def command(row) = declaration("Command", row)
+
+        def query(row) = declaration("Query", row).merge(options_of(row))
+
+        # EVERY DIRECT ENTITY OF ONE OWNER — S17, ADR 0026. `declared
+        # ("Entity", root_id)` returns EVERY entity sharing the same
+        # ROOT aggregate, nested or not (Dispatch and Handler both carry
+        # `aggregate: process_manager_id`) — `owner` is the field that
+        # actually tells them apart : `Judge#nest_entities`'s own
+        # comment explains why it is the one to repurpose. Called with
+        # `owner_id == root_id` for an aggregate's own direct entities
+        # (Handler), and with `owner_id == some entity's own id` for
+        # THAT entity's own nested ones (Dispatch, owned by Handler).
+        def direct_entities(root_id, owner_id)
+          declared("Entity", root_id).select { |held| text(held[:owner]).to_s == owner_id.to_s }
+        end
+
+        def entity(row)
+          {
+            name:          text(row[:name]),
+            description:   text(row[:description]),
+            # The same shape as an aggregate's now. It was a String here and a
+            # Symbol there — the IR was not uniform about it, and only a round trip
+            # ever said so.
+            identified_by: identity_paths(row),
+            # `text(row[:aggregate])` — the OWNING aggregate, the same one
+            # `Judge#owning_aggregate_ref` resolved this piece's own
+            # attribute types against on the way in, so reconstruction reads
+            # a value-object-typed attribute back the identical way an
+            # aggregate's own is (`Shapes#shape_field`'s own comment).
+            attributes:    Array(row[:attributes]).map { |field| shape_field(field, text(row[:aggregate])) },
+            # ADR 0028 — the SAME shape `aggregate(row)`'s own
+            # `preconditions:` reads two hand-typed methods up, read by
+            # hand for the identical reason: `entity(row)` is hand-typed
+            # too, unlike `command`/`value_object`/`query`.
+            preconditions: Array(row[:preconditions]).map { |held| rule(held) },
+            # Round 7 — the SAME shape `aggregate(row)`'s own
+            # `invariants:` reads, one level down: a piece's own shape
+            # rule, checked against every instance of this piece.
+            invariants:    Array(row[:invariants]).map { |held| rule(held) },
+            commands:      within("Command", row).map { |verb| command(verb) },
+            queries:       within("Query", row).map { |ask| query(ask) },
+            # S17, ADR 0026 — Dispatch, inside Handler : an entity's own
+            # NESTED entities, found the same way its own direct ones
+            # were one level up.
+            entities:      direct_entities(text(row[:aggregate]), row[:id]).map { |piece| entity(piece) },
+            # An entity has its own state machine, and the language has held it all
+            # along — Entity.Lifecycle and Entity.Transition were two of the fourteen
+            # verbs that started firing when the judge became a walk. Only the
+            # reconstruction had never asked for them.
+            lifecycle:     lifecycle(row)
+          }
+        end
+
+        # Assembled from three fields, because the IR keeps one object where the
+        # language keeps the parts — the same difference Readings holds for the walk,
+        # in the other direction.
+        def lifecycle(row)
+          field = text(row[:state_field])
+          return nil if field.to_s.empty?
+
+          {
+            field:       field,
+            default:     text(row[:state_start]),
+            transitions: Array(row[:transitions]).map { |move| transition(move) }
+          }
+        end
+
+        def policy(row) = declaration("Policy", row)
+
+        # S17, ADR 0026 — Handler is a genuine entity now, nested under
+        # ProcessManager, created by `ProcessManager.Handler` (an
+        # ordinary append, the same way `Account.LogEntry` creates a
+        # LedgerEntry) and mutated by its own dotted `ProcessManager.
+        # Handler.Dispatch`/`...Dispatch.Bind`. Its data therefore lives
+        # INLINE on the process manager's own dispatched state — same as
+        # any other entity list — not behind a separate `DeclaredIn`
+        # query : there is no such query any more, the same fix
+        # `Reconstruction#members_of` already made for Member.
+        def process_manager(row)
+          declaration("ProcessManager", row,
+                      handlers: Array(row[:handlers]).map { |leg| handler(leg) })
+        end
+
+        # S17, ADR 0026 — Dispatch, one level further in : nested under
+        # Handler, its data lives inline on the HANDLER row this method
+        # was just handed (`row` here IS one element of `handlers`,
+        # above), not behind any query either.
+        def handler(row)
+          declaration("Handler", row,
+                      dispatches: Array(row[:dispatches]).map { |leg| dispatch(leg) })
+        end
+
+        # `compensates` — TWO FLAT FIELDS on this same row
+        # (`process_manager.bluebook`'s own comment on `Dispatch` for
+        # why), assembled BY HAND into the shape its own field actually
+        # is — `declaration()`'s generic per-field hash-build has no
+        # way to turn two cells into a second object, so this reads
+        # them directly and passes the result through `extra:`, the
+        # same seam `handler`/`process_manager` already use for a
+        # `:children` shape a flat Contract cannot describe.
+        # `compensates_command_name` absent means no compensation at
+        # all — a plain dispatch with nothing to undo. A PLAIN HASH, the
+        # SAME declaration shape `to_h` spells for everything else in
+        # this file (this file's own top comment) — never a real
+        # `DispatchSpec` here; `Assembly#dispatch` is the one place a
+        # declaration hash becomes the real object, and building it
+        # twice, in two different shapes, is exactly the kind of drift
+        # this whole arc exists to remove.
+        def dispatch(row)
+          name = text(row[:compensates_command_name])
+          compensates = name && { command_name: name, with_spec: pairs(row[:compensates_with_spec]) }
+
+          declaration("Dispatch", row, compensates: compensates)
+        end
+
+        def read_model(row)
+          declaration("ReadModel", row).merge(query_name: text(row[:query_name])).merge(options_of(row))
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/meta_validator/shapes.rb

@@ -0,0 +1,266 @@
+module Hecks
+  module Bluebook
+    module MetaValidator
+      # The leaf shapes of a reconstructed bluebook, and the encodings that go with
+      # them.
+      #
+      # Reconstruction walks the tree; this rebuilds the small hashes at its tips —
+      # an attribute, a rule, a where-clause, a transition — and undoes the two
+      # things the walk encodes on the way in: an attribute's type offered as the ID
+      # of whatever it names, and an append flattened to one row per binding.
+      #
+      # Separate from the traversal because they are different concerns, and because
+      # the two together were 211 code lines against a 200 limit.
+      module Shapes
+        # The type came in as the id of what it names, so it goes back out as the
+        # name — or, for another aggregate's head, as the encoding the IR spells.
+        def attribute(field, aggregate_id)
+          type = text(field[:type]).to_s
+
+          {
+            name:         text(field[:name])&.to_sym,
+            type:         owned_type(type, aggregate_id) || reference_type(type),
+            list:         text(field[:list]).to_s == "true",
+            default:      decode_literal(text(field[:default])),
+            # Read back the same way `list` is — both are booleans about the
+            # attribute, held as text, and dropping either would rebuild a
+            # bluebook that no longer says what it said.
+            optional:     text(field[:optional]).to_s == "true",
+            pattern:      presence(text(field[:pattern])),
+            # THE ROUND TRIP IS THE ONLY WAY IN. The grammar registry keeps the
+            # ASSEMBLED graph — the language as its own judge read it back — so a
+            # fact dropped here is a fact no downstream projection ever sees, no
+            # matter how plainly the .bluebook file declares it.
+            admits:       presence(text(field[:admits])),
+            relationship: presence(text(field[:relationship]))
+          }
+        end
+
+        # A TYPE THIS AGGREGATE OWNS, offered as its id and read back as its name.
+        # Prefixed with the owner and the identity join, because that IS the value
+        # object's identity — the aggregate it belongs to, then its name.
+        def owned_type(type, aggregate_id)
+          prefix = Naming.identity([aggregate_id, ""])
+          return nil unless type.start_with?(prefix)
+
+          type.delete_prefix(prefix)
+        end
+
+        # ONE PART OF AN IDENTITY, read back as the path it went in as. The inverse
+        # of `Marks#identity_path`, and named the same so the two directions read
+        # as one table.
+        def identity_path(part) = text(part[:value]).to_s
+
+        # An argument, a parameter, a piece's attribute — the three places an
+        # attribute is written that carry no owner id to strip... except a
+        # piece's own attribute now does : an entity is its own root (repeating
+        # the aggregate's whole shape one level down), so ITS attributes name a
+        # value object exactly the way an aggregate's own do (`Judge#cell`'s own
+        # comment), and reconstruction has to undo the same owned-vs-reference
+        # split `attribute`, below, already undoes for an aggregate — not the
+        # cruder "any qualified name is a Reference" guess this used before,
+        # which mistook a piece's own value-object type for a cross-aggregate
+        # head every time.
+        #
+        # `aggregate_id`, passed only for a piece's own attribute (an
+        # argument or a parameter carries no value-object type at all — see
+        # entity.bluebook's/command.bluebook's own comments on why — so the
+        # generic reader path calls this with one argument and gets the
+        # OLD reading unchanged), is the piece's OWNING aggregate — the same
+        # one its own attribute types were resolved against on the way in
+        # (`Judge#owning_aggregate_ref`).
+        #
+        # A REFERENCE among the other two came in as the head's ID, because
+        # that is what Command/Query.Reference offer, so it goes back out as
+        # the encoding the IR spells. A qualified name is the tell : an
+        # ordinary type names something declared beside it (`Money`,
+        # `AccountNumber`) and never carries a chapter, while a head's id
+        # always does.
+        def shape_field(field, aggregate_id = nil)
+          return attribute(field, aggregate_id) if aggregate_id
+
+          type = text(field[:type]).to_s
+
+          {
+            name:         text(field[:name])&.to_sym,
+            # A QUALIFIED name is the tell : an ordinary type names something
+            # declared beside it (`Money`, `AccountNumber`) and carries no join at
+            # all, where a head's id always does (chapter + name, joined the way
+            # every derived id is).
+            type:         type.include?(Naming::IDENTITY_JOIN) ? reference_type(type) : text(field[:type]),
+            list:         text(field[:list]).to_s == "true",
+            default:      decode_literal(text(field[:default])),
+            optional:     text(field[:optional]).to_s == "true",
+            pattern:      presence(text(field[:pattern])),
+            admits:       presence(text(field[:admits])),
+            relationship: presence(text(field[:relationship]))
+          }
+        end
+
+        # An ABSENT pattern is nil, not "". The language holds every field as
+        # text, so a field nobody set comes back as the empty string — and ""
+        # is a real regex (it matches everything), so keeping it would turn
+        # "no pattern" into "a pattern that always passes" and quietly cost the
+        # IR its round trip.
+        def presence(text)
+          value = text.to_s
+          value.empty? ? nil : value
+        end
+
+        # A literal, read back from the self-describing form Readings#encode_literal
+        # wrote — the same reader Assembly::Marks uses, because it is the same
+        # spelling. The forms are exactly the five the Primitive vocabulary admits —
+        # String, Integer, Float, TrueClass, FalseClass — plus a symbol, and an
+        # object literal, which is what `to: { value: "good" }` is: a value object's
+        # fields written inline.
+        def decode_literal(text) = Literal.read(text)
+
+        def rule(row) = { description: text(row[:description]), canonical: text(row[:canonical]) }
+
+        # S12, ADR 0025 — `projects :name, from: :"reference.remote_field"`,
+        # read back the same three plain identifiers `rule` above reads
+        # description/canonical as.
+        def projected_field(row)
+          { name: text(row[:name]), reference: text(row[:reference]), remote_field: text(row[:remote_field]) }
+        end
+
+        # `provenance from: {...}` rides the same literal encoding `default:`
+        # does — an object literal, self-describing via Hecks::Literal — one
+        # level up: a whole keyword's argument rather than an attribute's
+        # `default:`.
+        def provenance(row) = decode_literal(text(row[:provenance]))
+
+        # `command "Debit", from: "open"` — the SAME literal encoding
+        # `provenance`/`default:` already ride (S10, ADR 0025), one
+        # state or an array of them, or nil for a command with no
+        # lifecycle guard.
+        def from(row) = decode_literal(text(row[:from]))
+
+        # THE OPTION ROWS, GATHERED BACK into the shapes `extra_options_to_h` spells.
+        #
+        # One row per part, so a compound option is several rows and a repeated one is
+        # several groups told apart by `at`. Grouping by option name and then by `at`
+        # rebuilds both without either knowing which options exist — the whole point
+        # of holding them as an open map.
+        def options_of(row)
+          Array(row[:options])
+            .group_by { |part| text(part[:option]) }
+            .to_h { |option, parts| [option.to_sym, gathered(parts)] }
+        end
+
+        def gathered(parts)
+          repeated, single = parts.partition { |part| !text(part[:at]).to_s.empty? }
+          return single.to_h { |part| [text(part[:key]).to_sym, text(part[:value])] } if repeated.empty?
+
+          repeated.group_by { |part| text(part[:at]) }
+                  .values
+                  .map { |group| group.to_h { |part| [text(part[:key]).to_sym, text(part[:value])] } }
+        end
+
+        # The IR keeps a where's field as a STRING, not a symbol — it is read back
+        # out, never called. The value stays RAW TEXT here on purpose : this
+        # feeds the declaration hash Assembly::Marks#where_clause decodes
+        # from (via `read`), and decoding twice is worse than once — a
+        # kwarg reference (":ceiling") decoded here into the Symbol :ceiling
+        # would have its colon stripped by `read`'s own `.to_s` and come
+        # back out as the plain string "ceiling", indistinguishable from a
+        # literal of the same name. One decode, at the one place that builds
+        # the object every comparator actually reads.
+        def where_clause(row)
+          { field: text(row[:field]), op: text(row[:op]), value: text(row[:value]) }
+        end
+
+        # One object in the IR, two fields in the language.
+        def order_by(row)
+          field = text(row[:order_field])
+          return nil if field.to_s.empty?
+
+          { field: field, direction: text(row[:order_way]) }
+        end
+
+        def limit(row)
+          ceiling = text(row[:limit])
+          return nil if ceiling.to_s.empty?
+
+          { value: ceiling }
+        end
+
+        def transition(row)
+          {
+            command:    text(row[:command]),
+            from_state: text(row[:from_state]),
+            to_state:   text(row[:to_state])
+          }
+        end
+
+        def head(row)
+          {
+            aggregate: text(row[:aggregate]),
+            # A String, like an entity's identified_by. The IR is not uniform about
+            # this and only a round trip says so.
+            as:        text(row[:as]),
+            many:      text(row[:many]).to_s == "true"
+          }
+        end
+
+        def group_by_field(row) = { field: text(row[:field]) }
+
+        # `count`'s own boolean, read back the SAME way `head`'s own
+        # `many` is (`text(row[:many]).to_s == "true"`) — except a
+        # `ReadModel.Count` command is dispatched AT ALL only when
+        # `@count` was truthy (`MetaValidator::Judge#setters` skips a
+        # setter whose every source is absent), so an undeclared read
+        # model's own `count` field never gets written and comes back
+        # `nil` here, never `"false"` — matching `ReadModel#to_h`'s own
+        # `true`/`nil` pair (never `false`) exactly, rather than the
+        # unconditional `true`/`false` `head`'s own `many` needs (every
+        # head DOES get a `Gather` dispatch, declared or derived).
+        def read_model_count(row) = (true if text(row[:count]).to_s == "true")
+
+        # THE APPEND FLATTENING, IN REVERSE.
+        #
+        # An append binds several fields at once and the language's Change holds one
+        # field/kind/source triple, so the walk offers an append once PER BINDING.
+        # Rebuilding groups those rows back into the single mutation the IR keeps —
+        # the only place here that undoes something rather than simply reading it.
+        def mutations(row)
+          Array(row[:mutations])
+            .group_by { |change| [text(change[:target]), text(change[:op])] }
+            .map { |(target, op), bindings| mutation(target, op, bindings) }
+        end
+
+        # `sign:` — read the SAME way the declared side computes it
+        # (`Bluebook::Mutation.sign_for`, item #5 of the whole-project
+        # table-unification survey), not stored on any row here — the
+        # meta-domain's own Change entity carries no `sign` field of its
+        # own (it is a pure function of `op`, nothing to persist), so
+        # reconstruction recomputes it the same way a freshly-built
+        # Mutation's own `to_h` lambda does, rather than leaving the key
+        # silently absent (spec/round_trip_spec's whole point: a field the
+        # language does not hold is a named gap, not a byte-for-byte one).
+        def mutation(target, op, bindings)
+          base = { target: target.to_sym, op: op.to_sym, sign: Hecks::Bluebook::Mutation.sign_for(op) }
+          # `:delegate`/`:corrects` (CommandBuilder#delegates_to's and
+          # #corrects_impl's own comments) ride the SAME multi-binding
+          # shape `:append` does.
+          return base.merge(fields: appended(bindings)) if ["append", "delegate", "corrects"].include?(op)
+
+          base.merge(source: classified(bindings.first))
+        end
+
+        def appended(bindings)
+          bindings.to_h { |binding| [text(binding[:field]).to_sym, text(binding[:source])] }
+        end
+
+        def classified(binding)
+          kind  = text(binding[:kind])
+          value = text(binding[:source])
+
+          return { kind: kind, name: value } if %w[argument state].include?(kind)
+
+          { kind: "literal", value: decode_literal(value) }
+        end
+      end
+    end
+  end
+end