hecks 0.2.0 → 0.3.0

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

@@ -0,0 +1,350 @@
+module Hecks
+  module Bluebook
+    module MetaValidator
+      # The parts of a bluebook the walk cannot read by name alone.
+      #
+      # The language now spells its fields exactly as the IR spells them, so the
+      # judge reads almost everything straight through: `command.givens`,
+      # `value_object.invariants`, `read_model.aggregate_heads`. What remains here
+      # is not naming drift — it is places where the IR's SHAPE differs from the
+      # language's, and no amount of renaming would close that:
+      #
+      #   transitions    one declaration expands to SEVERAL rows, because `from`
+      #                  may be a list of states
+      #   value_objects  the IR holds objects ; the language holds their names
+      #   normalisations not on the bluebook at all — they come from the canonical
+      #                  form table the expression grammar keeps
+      #   members        plain hashes, one Member root per row, pairs per entry
+      #   lifecycle      one IR object feeding two separate fields
+      #
+      # Everything in this file is a difference in shape. If something here is
+      # only a difference in NAME, it is in the wrong file: rename the language.
+      module Readings
+        # A list the walk is about to offer, as rows it can shape into dispatches.
+        #
+        # FROM THE TABLE. This was nine hand-written cases keyed "Category.list", and
+        # every one of them was a fact `Assembly::Contracts` is the right place to
+        # keep: which shaper turns this list into rows. A list with no shaper reads
+        # straight off the node, which is most of them.
+        def rows_for(category, list_name, node)
+          shaper = Assembly.contract(category).shaper(list_name)
+          return Array(node.public_send(list_name)) unless shaper
+
+          public_send(shaper, node)
+        end
+
+        # A where-clause is read through its own to_h, which is where the IR spells a
+        # symbol argument as ":ceiling". Reading the OBJECT instead lost the colon,
+        # and nothing downstream could tell an argument from a literal of the same
+        # name.
+        def where_rows(node) = Array(node.wheres).map(&:to_h)
+
+        # The language holds a value object's NAME here ; the IR holds the object.
+        def value_object_names(node) = node.value_objects.map { |shape| { name: shape.hecks_name } }
+
+        # AN IDENTITY IS A LIST OF PARTS, so it is offered one part at a time — the
+        # same way attributes and transitions are. The IR holds the paths ; the
+        # language holds a row per path, and the ORDER between them is the whole
+        # meaning, because the identity is their join.
+        def identity_rows(node) = node.identity_paths.map { |path| { value: path } }
+
+        # Through to_h, which is where Bluebook.render_value spells a symbol argument as
+        # ":source". The raw with_spec lost the colon, and a binding that reads an
+        # argument became indistinguishable from one carrying a literal string.
+        def with_spec_rows(node) = pair_rows(node.to_h[:with_spec])
+
+        # A read model carries the same options an ask does, plus its filters — see
+        # option_rows.
+        def read_model_option_rows(node) = option_rows(node, filters: true)
+
+        # The canonical-form table is the expression grammar's, not this chapter's, so
+        # the node is not consulted at all.
+        def normalisation_table(_node) = normalisation_rows
+
+        # `lifecycle :status do transition "Retire" => "retired", from: ["issued", "active"] end`
+        # is ONE declaration and TWO transitions. Offering it once would leave the
+        # second unjudged, which is the whole failure this judge exists to avoid.
+        def transition_rows(node)
+          lifecycle = node.respond_to?(:lifecycle) ? node.lifecycle : nil
+          return [] unless lifecycle
+
+          lifecycle.transitions.flat_map do |command, transition|
+            froms = transition.constrained? ? Array(transition.from) : [nil]
+            froms.map do |from|
+              { command: command, from_state: from, to_state: transition.target }
+            end
+          end
+        end
+
+        # An OPEN MAP — a member's fields, a dispatch's argument bindings — has no
+        # value object that can hold it, so each entry becomes its own row. This is
+        # why Member and Dispatch are roots in the language rather than lists.
+        def pair_rows(map)
+          Array(map&.to_h).map { |key, value| { key: key, value: value } }
+        end
+
+        # EVERY SPECIFICATION OPTION AN ASK CARRIES, flattened to rows.
+        #
+        # `offset`, `cursor`, `nulls`, `authorize` and `inspect_query` are
+        # five options, one compound (authorize names a policy AND a
+        # tenant). `extra_options_to_h` already spells every one of them
+        # and drops the absent ones, so this reads that rather than
+        # naming them here — a sixth option needs no change on either
+        # side.
+        #
+        # `filters: true` adds a read model's wheres, order_by and limit —
+        # `at` tells repeated rows apart, so two wheres do not collapse.
+        #
+        # THE LANGUAGE MAY HOLD MORE THAN `to_h` CARRIES, and this is where that
+        # mattered. Until 2026-08-11, `ReadModel#to_h` omitted all three —
+        # `extra_options_to_h` rejects them by name, still does — so a read
+        # model's filtering had never been in the wire contract, and I first
+        # read that as a wall: if the wire cannot carry it, the language cannot
+        # hold it, and a graph assembled from the language must lose it.
+        #
+        # That was the wrong conclusion. `to_h` is a PROJECTION ; the language
+        # is the SOURCE. They have to agree about everything
+        # to_h spells, not about everything the language knows. Held as option
+        # rows, the filters survived the round trip regardless of whether the
+        # wire carried them too — which is exactly why, when a LATER task
+        # (Rust read-model codegen) needed `wheres`/`order_by`/`limit` on the
+        # wire for an unrelated reason, `ReadModel#to_h` could be extended to
+        # spell them (the same mechanism `Query#to_h` already used) without
+        # touching this method at all: this reads `node.wheres`/`node.
+        # order_by`/`node.limit` off the live object directly below
+        # (`filter_options`), never off `to_h`, so the wire format moving did
+        # not move this.
+        #
+        # Named `wheres`, `order_by` and `limit` so they gather back into exactly the
+        # declaration keys the assembly already reads.
+        def option_rows(node, filters: false)
+          return [] unless node.respond_to?(:extra_options_to_h)
+
+          spelled = node.extra_options_to_h
+          spelled = filter_options(node).merge(spelled) if filters
+
+          spelled.flat_map do |option, held|
+            case held
+            when Array then held.each_with_index.flat_map { |one, at| parts(option, one, at) }
+            else parts(option, held, nil)
+            end
+          end
+        end
+
+        def filter_options(node)
+          {
+            wheres:   Array(node.wheres).map(&:to_h),
+            order_by: node.order_by&.to_h,
+            limit:    node.limit&.to_h
+          }.reject { |_, held| held.nil? || held == [] }
+        end
+
+        def parts(option, held, at)
+          Hash(held).map do |key, value|
+            { option: option.to_s, key: key.to_s, value: value, at: at&.to_s }
+          end
+        end
+
+        # A mutation is ONE declaration, but the language's Change holds a single
+        # field/kind/source triple — and an append binds SEVERAL fields at once
+        # (`append: { name: :name, amount: :amount }`). So an append is offered
+        # once per binding, and each one is judged.
+        #
+        # The judge used to send `field: v(""), kind: v("argument"), source: v("")`
+        # here — three stubbed values, so every rule about what a mutation reads
+        # was being handed a blank and could never refuse.
+        def mutation_rows(node)
+          Array(node.mutations).flat_map do |mutation|
+            # `:delegate` (CommandBuilder#delegates_to's own comment) rides
+            # the SAME multi-binding shape `:append` does — `with: {...}`
+            # is a field map, same as append's own `fields:`.
+            next set_row(mutation) unless [:append, :delegate].include?(mutation.op)
+
+            mutation.source.map do |field, argument|
+              # Spelled the way Mutation#appended_fields spells it, because
+              # Assembly::Marks reads this row back through the same reader it
+              # reads that field with. `then_set :marks, append: { direction:
+              # "out" }` binds a LITERAL, and storing it raw made it
+              # indistinguishable from an argument called out.
+              { target: mutation.target, op: mutation.op, field: field,
+                kind: argument.is_a?(Symbol) ? "argument" : "literal",
+                source: Literal.render(argument) }
+            end
+          end
+        end
+
+        # A set/increment/decrement reads one thing: a command argument, or a
+        # literal written into the bluebook.
+        def set_row(mutation)
+          classified = mutation.to_h[:source] || {}
+
+          [{ target: mutation.target, op: mutation.op, field: mutation.target,
+             kind: classified[:kind],
+             source: classified[:name] || encode_literal(classified[:value]) }]
+        end
+
+        # The normalisation table belongs to the expression grammar, not to any one
+        # bluebook — it is how the canonical form of a rule is spelled. The language
+        # models it because a bluebook's rules are canonicalised on the way in.
+        def normalisation_rows
+          table = Expression::CanonicalForm.table
+          return [] unless table
+
+          table.map do |entry|
+            {
+              strategy:     entry[:strategy],
+              source_token: entry[:source_token],
+              replacement:  entry[:replacement],
+              boundary:     entry[:boundary],
+              position:     entry[:position]
+            }
+          end
+        rescue StandardError
+          # The table is a convenience of the Ruby side ; a bluebook that cannot
+          # produce one is not malformed.
+          []
+        end
+
+        # What the BLUEBOOK calls a node, whichever kind of thing the node is.
+        #
+        # This used to sniff — `respond_to?(:hecks_name) ? … : node.name` — because
+        # only value objects had crossed over. Every construct answers now, so
+        # there is nothing to choose between. It disappears entirely when the DSL
+        # stops handing the judge nodes at all.
+        def declared_name(node) = node.hecks_name
+
+        # One field of a Declare payload. Mostly a reader of the same name — the
+        # exceptions are fields the IR keeps somewhere else, or not at all.
+        # READ FROM THE TABLE, not from a branch per category.
+        #
+        # These were eight hand-written cases — `Entity.owner`, `Member.shape`, two
+        # lifecycle members twice over, and three of a query's — each one restating
+        # something `Assembly::Contracts` already declares. A parent pointer is
+        # `:parent` there ; a folded field names the object and member it lives in.
+        # So the exceptions are looked up rather than repeated, and a new fold is one
+        # line in one file instead of two lines in two.
+        def field_value(category, node, field, parent_id)
+          return declared_name(node) if field == :name
+
+          contract = Assembly.contract(category)
+          # A setter names its target as a STRING and a Declare field arrives a Symbol,
+          # so the lookup keys on a Symbol either way. The case statement this replaced
+          # was type-blind because it interpolated ; a Hash is not.
+          named    = field.to_sym
+          return parent_id if contract.kind_of(named) == :parent
+
+          object, member = contract.folded(named)
+          return through(node, object, member) if member
+
+          # `limit` is a language field AND an object in the IR — `Array(an_object)`
+          # wraps rather than destructures, so offering it stored
+          # "#<struct LimitSpec value=3>".
+          return node.limit&.to_h&.fetch(:value, nil) if "#{category}.#{field}" == "Query.limit"
+
+          # `provenance from: {...}` is a HASH offered into a text field, and
+          # handing it over raw let the runtime's own coercion spell it — which
+          # meant Ruby's `Hash#to_s`, whose spelling changed under us between
+          # 3.3 and 3.4. Encoded here, the same way `default:` already is and the
+          # same way Shapes#provenance reads it back.
+          return encode_literal(node.provenance) if field == :provenance
+
+          # `identified_by` is no longer a FIELD of any declaration — it is a list,
+          # filled by Identify one part at a time, so it is read through `identity_rows`
+          # like every other list rather than special-cased here. What this branch
+          # existed to protect is now structural : a path cannot come back as its head,
+          # because there is nowhere left that holds only a head.
+
+          node.respond_to?(field) ? node.public_send(field) : nil
+        end
+
+        # One member of the object a field folds into. `to_h` first, because the
+        # member names are the ones the IR SPELLS — a Lifecycle's `default`, an
+        # OrderBy's `direction` — and reading the object raw is how a colon or a type
+        # goes missing.
+        def through(node, object, member)
+          held = node.respond_to?(object) ? node.public_send(object) : nil
+          return nil unless held
+
+          member == :transitions ? held : held.to_h[member]
+        end
+
+        # What a setting command writes. A setter whose source is absent is not
+        # dispatched at all — ABSENT is not EMPTY, and offering "" would turn every
+        # "if you declare it, declare something" rule into "you must declare it".
+        def setter_value(category, node, target)
+          # `rows` folds into `closed_set` and `members` between them, with no single
+          # member to name, so it keeps its own reading — see Contract#folded.
+          return closed_set_size(node) if "#{category}.#{target}" == "ValueObject.rows"
+
+          object, member = Assembly.contract(category).folded(target.to_sym)
+          return through(node, object, member) if member
+
+          node.respond_to?(target) ? node.public_send(target) : nil
+        end
+
+        # Only a DECLARED closed set has a row count. An empty one is the defect,
+        # so `rows` must stay absent rather than arrive as zero.
+        def closed_set_size(node)
+          return nil unless node.respond_to?(:closed_set?) && node.closed_set?
+
+          Array(node.members).size
+        end
+
+        # `Reference<Customer>` is an IR ENCODING, not a domain fact. The fact is
+        # that the attribute points at Customer's head — so the language is offered
+        # that head's ID, and resolution does the rest. Encoding and decoding both
+        # live here, because this is where the IR's shape differs from the
+        # language's and nowhere else should know the spelling.
+        def points_at(row, aggregate_id)
+          return nil unless row.reference?
+
+          # THE CHAPTER THIS HEAD IS IN, AND THE HEAD IT POINTS AT — which is exactly
+          # how an aggregate is identified, so it is built the same way rather than
+          # spelled again with a separator of its own. This is dispatched as a REAL
+          # REFERENCE VALUE (`Aggregate.Reference`'s `points_at:`), resolved by
+          # `repository.find` against the target Aggregate-within-Meta record's OWN
+          # stored id — so it MUST equal what that record's identity actually
+          # derives, not a wire-format spelling. `reference_type`, below, is the
+          # separate later reader that un-derives it back into "Reference<X>".
+          Naming.identity([aggregate_id.split(Naming::IDENTITY_JOIN).first, row.type.target_name])
+        end
+
+        # A LITERAL, written so it can be read back exactly.
+        #
+        # The language holds a default and a literal mutation source as text, and
+        # `to_s` threw the type away: 0.0 came back "0.0", and `{ value: "good" }`
+        # came back its inspect string with nowhere to say it had been a hash. The
+        # language already stores code as text — `canonical: "cents >= 0"` — so an
+        # encoding is in keeping; it simply has to be SELF-DESCRIBING. That rule is
+        # now Hecks::Literal's, stated once and shared with every other
+        # to_h-bound literal field ; Shapes#decode_literal reads it back.
+        #
+        # nil stays nil rather than becoming "nil": absent is a real answer here,
+        # and the language's own field is optional.
+        def encode_literal(value) = value.nil? ? nil : Literal.render(value)
+
+        # The way back out: an aggregate id becomes the type the IR spells. The
+        # id is a JOIN of chapter + name (Naming::IDENTITY_JOIN, the same join
+        # `points_at` built it with, not the "::" a real bluebook's own type
+        # names never carry) ; the wire format wants only the bare name.
+        def reference_type(points_at_id) = "Reference<#{points_at_id.to_s.split(Naming::IDENTITY_JOIN).last}>"
+
+        # One value out of a row, named by the value object's field.
+        def row_value(row, field)
+          # A Hash FIRST. Hash answers to `key` (Hash#key(value)) and to `value` on
+          # some rows, so asking respond_to? before checking for a Hash reads a
+          # member pair through entirely the wrong method.
+          return row[field] if row.is_a?(Hash)
+          return row.public_send(field) if row.respond_to?(field)
+          # A Struct answers to [] but RAISES for a member it does not have, so it
+          # is read through to_h — a field the row simply lacks reads as absent.
+          return row.to_h[field] if row.respond_to?(:to_h) && !row.is_a?(String)
+
+          # A bare scalar row — `emits` is a list of event NAMES, and the
+          # Announcement value object has to call that string something.
+          row
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,312 @@
+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)
+
+        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]).to_s] }
+          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),
+            attributes:    Array(row[:attributes]).map { |field| shape_field(field) },
+            # 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
+
+        def dispatch(row) = declaration("Dispatch", row)
+
+        def read_model(row)
+          declaration("ReadModel", row).merge(query_name: text(row[:query_name])).merge(options_of(row))
+        end
+      end
+    end
+  end
+end