hecks 0.3.0 → 1.0.0

data/lib/hecks/bluebook/expression/resolver.rb

@@ -58,6 +58,26 @@ module Hecks
         Size           = Struct.new(:receiver, keyword_init: true)
         Lookup         = Struct.new(:path, keyword_init: true)
 
+        # UPDATE 2026-08-27: every "vendored addition, not (yet) upstream
+        # hecks" comment on this file's own MatchesRegex/Presence/Split/
+        # First/Last/StartsWith/EndsWith below (plus ArrayLiteral above)
+        # described a REAL gap, found the hard way, in the history each
+        # comment tells — and that history stays exactly as written,
+        # on purpose. What changed is the PRESENT TENSE claim "not (yet)
+        # upstream": a review of this exact migration found these eight
+        # symbols had working Ruby parse/interpret arms but had NEVER
+        # gone through Propose -> Render -> Admit
+        # (lib/hecks/grammar/expression_operators.json) the way every
+        # other operator here has — a closed-vocabulary guard
+        # (spec/operator_conformance_spec.rb) built entirely over TABLES
+        # structurally could not see hand-coded Struct/parse/interpret
+        # additions, so eight operators ran in Ruby, admitted nowhere,
+        # invisible to the one guard whose whole job was "reads in every
+        # target." All eight are now ledger-admitted for real, with full
+        # Rust kernel parity (rust/src/kernel/expression_operators/
+        # {pattern_match,presence,text,positional}.rs) — the two-tier
+        # gap is closed, not merely tracked.
+        #
         # `receiver.match?(/pattern/)` -- vendored addition, not (yet)
         # upstream hecks (migration plan task 8): confirmed the
         # SINGLE most impactful corpus-wide dispatch-time gap of the
@@ -332,6 +352,15 @@ module Hecks
           options |= Regexp::EXTENDED   if flags.include?("x")
 
           Regexp.new(pattern, options).match?(text)
+        rescue RegexpError => e
+          # M9: a malformed pattern between the slashes (an unclosed
+          # character class, say) is a defect in the EXPRESSION TEXT
+          # itself, exactly the same category of author mistake an
+          # unresolvable attribute name already refuses for — `Regexp.new`
+          # raising a raw `RegexpError` crossed this sublanguage's own
+          # refusal boundary the same way the `ZeroDivisionError`/
+          # `TypeError` cases elsewhere in this file did.
+          raise EvaluationError, "match? given an invalid pattern #{pattern.inspect} — #{e.message}"
         end
 
         # The elements of a bracketed literal, or nil if this isn't one.
@@ -392,9 +421,19 @@ module Hecks
               quote = nil if char == quote
             elsif ['"', "'"].include?(char)
               quote = char
-            elsif ["(", "{"].include?(char)
+            # `[`/`]` -- the identical lesson this method's own `(`/`{`
+            # comment already names, a third time (found live via the
+            # type-directed bounded-exhaustive expression generator,
+            # Phase 7 of the equivalence-gap plan): `ArrayLiteral` can
+            # appear as a general sub-expression now, not only as
+            # `.include?`'s own haystack, so an array element containing
+            # its own top-level `+` (`[0, 0 + 0]`) used to read as THIS
+            # expression's own addition split point -- the whole
+            # receiver before `.all?`/`.any?`/etc. torn in half before
+            # `parse_block_opener` ever saw it as one atomic leaf.
+            elsif ["(", "{", "["].include?(char)
               depth += 1
-            elsif [")", "}"].include?(char)
+            elsif [")", "}", "]"].include?(char)
               depth -= 1
             elsif char == "+" && depth.zero?
               return [expr[0...index].strip, expr[(index + 1)..].strip]
@@ -518,18 +557,109 @@ module Hecks
           Evaluator.apply(node.operator, number, 0)
         end
 
+        # FOUND LIVE via the type-directed bounded-exhaustive expression
+        # generator (Phase 7, equivalence-gap plan — spec/
+        # bounded_exhaustive_expression_spec.rb): `.modulo(`'s own
+        # argument position accepts any numeric sub-expression, including
+        # ANOTHER `.modulo(...)` call — `0.modulo(num_b.modulo(-1))` is
+        # perfectly well-typed — but `expr.rindex(marker)` finds the
+        # RIGHTMOST (innermost) `.modulo(` in the whole string, not the
+        # OUTERMOST one a nested call needs split at. For that expression
+        # it found the INNER `.modulo(` (inside `num_b.modulo(-1)`) and
+        # split there, producing a receiver of `"0.modulo(num_b"` and a
+        # divisor of `"-1)"` — both garbage, both re-parsed as bogus
+        # `Lookup` paths, both then refusing with "cannot resolve" — a
+        # SILENT MISPARSE that happened to fail safe into a real
+        # `EvaluationError` rather than a raw crash, which is exactly why
+        # this had gone unnoticed: nothing before this generator existed
+        # ever fed `.modulo` a nested `.modulo` call, random fuzzing
+        # essentially never manufactures that specific shape by chance,
+        # and the resulting refusal LOOKS like an ordinary, correct one
+        # unless you already know every name this generator's own
+        # synthetic state declares (real corpus authors would see this as
+        # a mysterious "cannot resolve" on text they never wrote).
+        #
+        # Fixed the same way `split_addition`/`Evaluator.top_level_index`
+        # already handle nested `(`/`{` elsewhere in this exact file:
+        # find the FIRST (leftmost, outermost) occurrence of the marker,
+        # then track paren/quote depth from there to find ITS OWN
+        # matching close — not just strip the string's own trailing `)`
+        # and hope it belongs to this call.
+        # Not just the FIRST occurrence, either — `.modulo` also CHAINS
+        # (`x.modulo(a).modulo(b)`, the receiver of the OUTER call itself
+        # ending in a `.modulo(...)` call), a second real shape the
+        # leftmost-occurrence-only version of this fix still mis-parsed:
+        # the first `.modulo(`'s own matching close paren lands mid-
+        # string (right after `a)`, before the second `.modulo(b)`), so
+        # it correctly fails the "reaches the end" check below and must
+        # be tried again at the NEXT occurrence rather than giving up.
+        # Trying occurrences strictly left to right and taking the FIRST
+        # one whose matching close reaches the string's last character
+        # handles both shapes with the same rule: for NESTING
+        # (`.modulo(x.modulo(y))`), the leftmost (outer) occurrence's own
+        # paren-depth tracking already walks straight through the inner
+        # call to the true final `)`; for CHAINING, the leftmost
+        # occurrence's close lands short and is rejected, so the next
+        # occurrence (the true outermost call) is tried instead.
         def match_call(expr, marker)
-          index = expr.rindex(marker)
-          return nil unless index && expr.end_with?(")")
+          start = 0
+          while (index = expr.index(marker, start))
+            close = matching_paren(expr, index + marker.length)
+            return [expr[0...index], expr[(index + marker.length)...close]] if close == expr.length - 1
 
-          [expr[0...index], expr[(index + marker.length)...-1]]
+            start = index + 1
+          end
+          nil
         end
 
+        # `matching_brace` (resolver/block_predicates.rb)'s own twin, one
+        # bracket pair over: `start` is the index just past the OPENING
+        # `(` already consumed by the caller (depth starts at 1, not 0,
+        # for the same reason).
+        def matching_paren(expr, start)
+          depth = 1
+          quote = nil
+          index = start
+          while index < expr.length
+            char = expr[index]
+            if quote
+              quote = nil if char == quote
+            elsif ['"', "'"].include?(char)
+              quote = char
+            elsif char == "("
+              depth += 1
+            elsif char == ")"
+              depth -= 1
+              return index if depth.zero?
+            end
+            index += 1
+          end
+          nil
+        end
+
+        # Both operands are coerced to a real Integer/Float BEFORE the
+        # zero-check, and the check reads the COERCED divisor — not the
+        # raw `divisor_value` (which might not even respond to `.zero?`,
+        # a String for instance) and not a `.to_i`-truncated stand-in for
+        # it either. The old order checked a truncated `divisor.to_i`
+        # AFTER already validating the untruncated value wasn't zero, so
+        # a divisor merely small (`0.3`, truncating to `0`) sailed past
+        # the guard and then blew up `Integer#%` with a raw
+        # `ZeroDivisionError` the moment it reached zero anyway.
+        #
+        # The modulo itself is plain `%` on the coerced values, matching
+        # `add`'s own no-truncation precedent just above — Ruby's native
+        # `%` already handles every Integer/Float combination correctly
+        # (promoting to Float when either side is one), so rounding both
+        # operands down to Integer first was pure data loss with no
+        # purpose: `7.5.modulo(2.5)` silently became `7 % 2` (`1`)
+        # instead of the real `0.0`.
         def apply_modulo(receiver_value, divisor_value)
-          divisor = require_number(divisor_value, "modulo")
+          receiver = require_number(receiver_value, "modulo")
+          divisor  = require_number(divisor_value, "modulo")
           raise EvaluationError, "divided by 0" if divisor.zero?
 
-          require_number(receiver_value, "modulo").to_i % divisor.to_i
+          receiver % divisor
         end
 
         def lookup(expr, state, attrs)
@@ -544,13 +674,34 @@ module Hecks
         # `found_of` (the `Find` node's own path projection) can walk a
         # `.find { ... }`-produced element the identical way `lookup`
         # walks a plain attribute path, rather than duplicating the
-        # `value[segment.to_sym] || value[segment]` step twice in this
-        # file.
+        # symbol-or-string key step twice in this file. `key?` decides
+        # which spelling answers — a bare `||` between the two would
+        # treat a genuinely-held `false` the same as an absent key and
+        # fall through to the other spelling, landing on `nil`.
         def walk_path(value, segments)
           segments.reduce(value) do |current, segment|
             break nil unless current.respond_to?(:[])
 
-            current[segment.to_sym] || current[segment]
+            if current.is_a?(Hash)
+              sym = segment.to_sym
+              current.key?(sym) ? current[sym] : current[segment]
+            else
+              begin
+                current[segment]
+              rescue TypeError
+                # M9 (docs/audits/2026-08-10-main-bug-audit.md): a dotted
+                # path can walk onto an Array (e.g. the result of `.split`,
+                # or a `list_of` attribute) — Array#[] demands an
+                # Integer/Range and raises a raw TypeError for a String
+                # segment ("no implicit conversion of String into
+                # Integer"), which used to cross straight past this
+                # sublanguage's own refusal boundary and crash the
+                # runtime instead of reading as "this predicate doesn't
+                # apply here."
+                raise EvaluationError,
+                      "cannot read #{segment.inspect} from #{describe(current)}"
+              end
+            end
           end
         end
 

data/lib/hecks/bluebook/hexagon.rb

@@ -3,7 +3,7 @@ require_relative "../ir"
 
 module Hecks
   module Bluebook
-    Port = Struct.new(:name, :verb, :signal, keyword_init: true) do
+    Port = Struct.new(:name, :verb, :signal, :answers, keyword_init: true) do
       def reply?  = signal == :reply
       def effect? = signal == :effect
     end

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

@@ -25,10 +25,23 @@ module Hecks
       class Judge
         include Readings
 
-        # Children offered BEFORE the parent's own lists. An attribute's type is
-        # offered as the id of the thing it names, so both the value objects and the
-        # entities have to exist before any attribute names one.
-        EAGER_CHILDREN = { "Aggregate" => %w[Entity ValueObject] }.freeze
+        # Children offered BEFORE the parent's own lists, IN THIS ORDER. An
+        # attribute's type is offered as the id of the thing it names, so the
+        # value objects have to exist before anything that can name one — an
+        # aggregate's own attributes, AND an entity's own (M13: an entity is its
+        # own root, repeating the aggregate's whole shape one level down, so its
+        # attributes resolve against the SAME value-object pool). ValueObject
+        # first, Entity second, so an entity's own attributes are never offered
+        # before the value objects they may reference exist — a self-hosting
+        # casualty found live: the meta-grammar's own Handler/Dispatch/Member/
+        # Keyword/Argument entities (S17, ADR 0026) failed reference resolution
+        # on their own plain value-object-typed attributes (`HandlerText`,
+        # `MemberPosition`, ...) the moment entity attributes started being
+        # checked at all, because `@plan.names`' own (incidental) declaration
+        # order happened to walk Entity first. The order is stated here, not
+        # left to whatever order the plan's own category table iterates in —
+        # see `detail_node`'s own use of this constant, below.
+        EAGER_CHILDREN = { "Aggregate" => %w[ValueObject Entity] }.freeze
 
         # Categories an ENTITY declares as well as an aggregate. The IR reuses
         # Command and Query for a piece's own commands and queries, so the
@@ -157,13 +170,32 @@ module Hecks
           identity     = extra.merge(node_identity(plan, category, node, index, parent_id))
           receiver   ||= { aggregate: id, entities: [] }
           eager, later = children_of(category).partition { |child| eager?(category, child) }
+          # ORDERED AS `EAGER_CHILDREN` DECLARES, not as `children_of` happens to
+          # list them — `children_of` reads `@plan.names`, whose own order is an
+          # accident of which .bluebook file registered which category first,
+          # never a promise about which of two eager children exists before the
+          # other. `EAGER_CHILDREN`'s own array IS that promise (ValueObject
+          # before Entity), so the walk keeps only what this parent actually
+          # has, in the order the constant states — see that constant's own
+          # comment for the bug this exact reordering fixes.
+          eager = Array(EAGER_CHILDREN[category]) & eager
 
           eager.each { |child| walk_all(child, node, id, entity_child_extra(child, identity), receiver: receiver) }
           setters(plan, category, node, receiver)
-          appends(plan, category, node, receiver)
+          # BEFORE `appends`, not after — the same reason `EAGER_CHILDREN`
+          # walks an aggregate's OWN entities before its OWN attributes
+          # (M13): a piece nested inside a piece (Handler's own
+          # `dispatches, list_of(Dispatch)` — S17, ADR 0026) must exist
+          # before this piece's own attribute list can reference it as a
+          # HELD entity, the same way `Account#ledger` needs Account's own
+          # entities walked eagerly. `nest_entities` is a no-op for every
+          # category but "Entity" (its own early return), so reordering it
+          # ahead of `appends` costs nothing for anything else that walks
+          # through here.
+          nest_entities(category, node, id, parent_id)
+          appends(plan, category, node, receiver, parent_id)
           later.each { |child| walk_all(child, node, id, entity_child_extra(child, identity), receiver: receiver) }
           within_entity(category, node, id, parent_id)
-          nest_entities(category, node, id, parent_id)
           sealers(plan, category, receiver)
         end
 
@@ -353,8 +385,9 @@ module Hecks
           end
         end
 
-        def appends(plan, category, node, receiver)
+        def appends(plan, category, node, receiver, parent_id)
           id = receiver[:entities].last || receiver[:aggregate]
+          owner_id = owning_aggregate_ref(category, id, parent_id)
           plan.appends.each do |list_name, append|
             rows_for(category, list_name, node).each_with_index do |row, index|
               chosen = append_for(category, list_name, append, row, node)
@@ -367,7 +400,7 @@ module Hecks
                           v(index)
                         else
                           carried(@plan.category(category), chosen.verb, argument,
-                                  cell(category, list_name, row, field, id, chosen))
+                                  cell(category, list_name, row, field, id, chosen, owner_id))
                         end
                 [argument.to_sym, value]
               end
@@ -378,21 +411,41 @@ module Hecks
           end
         end
 
+        # WHICH AGGREGATE OWNS THE VALUE OBJECTS an attribute's TYPE may
+        # resolve against. An aggregate owns its own — `id` already names
+        # it. An entity never has value objects of its own (Entity
+        # deliberately never answers `value_object` — see entity.rb's own
+        # comment on why); its attributes read the SAME pool its
+        # enclosing aggregate declares, one level up the construct tree
+        # no matter how many entities deep this attribute is nested —
+        # `parent_id` names it because `detail_node`/`nest_entities`
+        # thread the ROOT aggregate's id down as `parent_id` at every
+        # entity level, never the direct (possibly entity) parent.
+        def owning_aggregate_ref(category, id, parent_id)
+          category == "Entity" ? parent_id : id
+        end
+
         def sealers(plan, category, receiver)
           id = receiver[:entities].last || receiver[:aggregate]
           plan.sealers.each { |verb| send_to("Bluebook::#{verb_for(plan, verb)}", id, to: receiver) }
         end
 
-        # An aggregate's attribute names its value object by TYPE, and the language
-        # models that as a reference — so the type is offered as the value object's
-        # own id. This is the rule "attributes must use value-object types",
-        # enforced by reference resolution rather than by a predicate.
+        # An aggregate's or an entity's attribute names its value object by TYPE,
+        # and the language models that as a reference — so the type is offered as
+        # the value object's own id. This is the rule "attributes must use
+        # value-object types", enforced by reference resolution rather than by a
+        # predicate — for a HEAD's own attributes, aggregate or entity alike: an
+        # entity is its own root, repeating the aggregate's whole shape one level
+        # down (entity.rb's own words), and an undeclared type on an entity's
+        # attribute must fail the same reference resolution an aggregate's own
+        # does, not go unchecked because only "Aggregate.attributes" was ever
+        # asked.
         # An attribute's type is offered as the ID OF THE THING IT NAMES, so the
         # language resolves it as a reference and "the type is declared" costs no
         # predicate. Three kinds, three ids: a value object and an entity both hang
         # off this aggregate, so they share its prefix; another aggregate's head
         # hangs off the chapter.
-        def cell(category, list_name, row, field, id, append)
+        def cell(category, list_name, row, field, id, append, aggregate_id)
           value = row_value(row, field)
           # A default keeps its TYPE by being written as a literal — 0.0 rather than
           # "0.0" — because the language holds it as text and text alone forgets.
@@ -400,13 +453,22 @@ module Hecks
           return value unless field == :type
           # A REFERENCE names another head WHEREVER it is written — on a head, on
           # a command, on a piece, on an ask — so it is offered as that head's
-          # id in all four. Only the head's own attributes additionally qualify
+          # id in all four. Only a HEAD's own attributes additionally qualify
           # an ordinary type into a value object's id ; a command argument's
           # type is text and stays text.
           return points_at(row, id) if append.verb == "Reference"
-          return value unless "#{category}.#{list_name}" == "Aggregate.attributes"
+          return value unless attribute_list?(category, list_name)
+
+          Naming.identity([owning_aggregate_id(aggregate_id, value), value])
+        end
 
-          Naming.identity([owning_aggregate_id(id, value), value])
+        # A HEAD'S OWN ATTRIBUTES — an aggregate's, or an entity's (its own root,
+        # one level down). Every other "attributes" list belongs to something that
+        # is not a head at all (a command's arguments, a value object's own
+        # fields), and a type written there is a name, not a reference — the same
+        # distinction `cell`'s own comment draws.
+        def attribute_list?(category, list_name)
+          list_name.to_s == "attributes" && %w[Aggregate Entity].include?(category)
         end
 
         # `id` NAMES THE ATTRIBUTE'S OWN AGGREGATE, not necessarily the

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

@@ -40,6 +40,10 @@ module Hecks
         def judge!
           send_to("Port::Port.Declare", @port.name, name: v(@port.name),
                   verb: v(@port.verb), signal: v(@port.signal))
+
+          Array(@port.answers).each do |answer|
+            send_to("Port::Port.AddAnswer", @port.name, name: @port.name, value: v(answer))
+          end
         end
       end
     end

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

@@ -53,6 +53,14 @@ module Hecks
         # argument became indistinguishable from one carrying a literal string.
         def with_spec_rows(node) = pair_rows(node.to_h[:with_spec])
 
+        # THE SAME READ, ONE LEVEL IN — `compensates` folds `DispatchSpec`
+        # into the language's own `compensates_command_name`/
+        # `compensates_with_spec` (`Assembly::Contracts`' own comment on
+        # "Dispatch"), so its OWN with_spec pairs live nested one hash
+        # down from where `with_spec_rows` looks. `&.dig(...)` — no
+        # compensation at all is not an error, it is `pair_rows(nil)`, empty.
+        def compensates_with_spec_rows(node) = pair_rows(node.to_h[:compensates]&.dig(: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)
@@ -155,10 +163,12 @@ module Hecks
         # 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)
+            # `:delegate`/`:corrects` (CommandBuilder#delegates_to's and
+            # #corrects_impl's own comments) ride the SAME multi-binding
+            # shape `:append` does — `with: {...}`/the assembled
+            # `as:`/`reason:`/`reverses:` hash is a field map, same as
+            # append's own `fields:`.
+            next set_row(mutation) unless [:append, :delegate, :corrects].include?(mutation.op)
 
             mutation.source.map do |field, argument|
               # Spelled the way Mutation#appended_fields spells it, because

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

@@ -207,9 +207,22 @@ module Hecks
         # 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]).to_s] }
+            Array(member[:pairs]).map { |pair| [text(pair[:key]).to_s, text(pair[:value])] }
           end
         end
 
@@ -238,7 +251,12 @@ module Hecks
             # 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) },
+            # `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
@@ -301,7 +319,28 @@ module Hecks
                       dispatches: Array(row[:dispatches]).map { |leg| dispatch(leg) })
         end
 
-        def dispatch(row) = declaration("Dispatch", row)
+        # `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))

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

@@ -52,14 +52,33 @@ module Hecks
         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.
+        # 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.
         #
-        # A REFERENCE among them came in as the head's ID, because that is what
-        # Command/Entity/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`, 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
 
           {
@@ -221,9 +240,10 @@ module Hecks
         # 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` (CommandBuilder#delegates_to's own comment) rides
-          # the SAME multi-binding shape `:append` does.
-          return base.merge(fields: appended(bindings)) if ["append", "delegate"].include?(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