hecks 1.2.0 → 1.3.0

data/lib/hecks/runtime/reaction_invocation.rb

@@ -85,7 +85,7 @@ module Hecks
       # source_receiver_for, command_facts, refuse_unconsumed!) for every
       # piece that IS self-contained; what remains is the sequencing
       # itself, which further splitting would only relocate, not remove.
-      # rubocop:disable-next Metrics/MethodLength
+      # rubocop:disable-next Metrics/MethodLength, Metrics/PerceivedComplexity
       def build(registry:, verb:, projected:, explicit:, passthrough: [], source_receiver: nil)
         args = projected.transform_keys(&:to_sym)
         unless explicit
@@ -99,6 +99,18 @@ module Hecks
           rescue UnknownVerb
             return args
           end
+          # AN ENTITY TARGET HAS NO SHAPE THIS BRANCH CAN BUILD — an
+          # implicit (unprojected) `to:` is always a bare scalar, the
+          # aggregate's own identity alone; an entity command's receiver is
+          # `{aggregate:, entities:}`, which needs the entity's own
+          # identity too, and nothing here resolves one (the same "cannot
+          # invent an entity identity" limit `source_receiver_for`'s own
+          # comment already states). So this stays exactly the pre-BUG#6
+          # behavior for an entity target: no receiver is lifted, and the
+          # payload forwards wholesale, unchanged, same as when there is
+          # no `source_receiver` at all.
+          return args unless target.entities.empty?
+
           inherited_receiver = source_receiver_for(target, source_receiver)
           return inherited_receiver ? args.merge(to: inherited_receiver) : args
         end
@@ -154,6 +166,26 @@ module Hecks
         raise UnknownVerb, "reaction target #{verb.inspect} does not resolve to an aggregate" unless aggregate
 
         *entity_names, command_name = command_path.split(".")
+
+        # A PORT OPERATION, reached by the SAME two-segment tail shape an
+        # entity command uses ("Head.Rest") — checked FIRST, same order
+        # `Dispatcher#dispatch` already resolves a live verb in (an
+        # aggregate that declared both a port and an entity of the same
+        # name would resolve to the port there too; no domain in this
+        # corpus does). A port has no `entities` of its own — the
+        # RECEIVER is always the aggregate itself — so `Target#entities`
+        # stays empty and `#command` holds the `PortOperation`, which
+        # answers `#creates?` (always false) the same way an ordinary
+        # `Command` does, letting `source_receiver_for` lift a same-
+        # aggregate policy's own Event.id as the operation's receiver
+        # exactly as it already does for a plain command.
+        if entity_names.one? && (port = aggregate.port(entity_names.first))
+          operation = port.operation(command_name)
+          raise UnknownVerb, "reaction target #{verb.inspect} does not resolve to a declared port operation" unless operation
+
+          return Target.new(aggregate: aggregate, entities: [], command: operation)
+        end
+
         owner = aggregate
         entities = entity_names.map do |entity_name|
           entity = owner.entities.find { |candidate| candidate.hecks_name == entity_name }
@@ -187,10 +219,45 @@ module Hecks
       # it cannot address another aggregate, invent an entity identity, or turn
       # a creation into a mutation. An explicit projected receiver is resolved
       # first and remains authoritative.
+      #
+      # ANSWERS REGARDLESS OF `target.entities` — the value this method hands
+      # back is ONLY EVER the ROOT AGGREGATE'S OWN identity (`source_receiver`
+      # carries nothing else: `event.aggregate`/`event.id` name the emitting
+      # AGGREGATE, never one of its entities). An entity target's own identity
+      # is resolved entirely separately, from `args` (`build`'s own `entity_
+      # identities` loop) — this method is never consulted for it, so
+      # answering for an entity target does not "invent an entity identity"
+      # any more than answering for a plain one invents THAT identity; it was
+      # already the one thing this method has ever supplied. `build`'s own
+      # EXPLICIT branch (below) already applies this correctly either way
+      # (`aggregate_identity ||= inherited_receiver`, entity identities read
+      # from `args` regardless) — the caller that actually needed a guard
+      # here is the IMPLICIT one, above, which has no shape to build a
+      # `{aggregate:, entities:}` receiver from an inherited scalar alone,
+      # and now guards itself for exactly that reason instead of this method
+      # doing it on that caller's behalf and, as a side effect, also refusing
+      # the EXPLICIT caller's own legitimate case — confirmed missing until
+      # `qa/stress_domains/waybill` (BUG#6) exercised it for the first time
+      # anywhere in the corpus: a saga dispatching into a nested entity's own
+      # command, inheriting its aggregate receiver from the event that
+      # triggered it.
       def source_receiver_for(target, source_receiver)
         return nil unless source_receiver
-        return nil unless target.entities.empty?
-        return nil if target.command.creates?
+        # `target.command.creates?` ALONE MISREADS EVERY ENTITY COMMAND —
+        # `Behaviour::Command#creates?`'s own comment: "a verb declared on
+        # an ENTITY always acts on that piece... which means `creates?`
+        # answers true for every one of them" (it never sets `@references`
+        # the way an aggregate-level command's own `reference_to` does,
+        # not because it brings anything new into being). `build`'s own
+        # `if target.entities.empty? && target.command.creates?` guard,
+        # 20-odd lines below, already reads `creates?` correctly for
+        # exactly this reason — an entity command is never a genuine
+        # creation, whatever `creates?` alone answers — so this checks the
+        # SAME compound condition instead of the bare, misleading half of
+        # it. Left unfixed, an entity target's own receiver was refused
+        # here even after this method stopped refusing on `target.entities`
+        # alone — the second half of BUG#6's own fix.
+        return nil if target.entities.empty? && target.command.creates?
 
         source = source_receiver.transform_keys(&:to_sym)
         source_aggregate = source[:aggregate].to_s

data/lib/hecks/runtime/refusal_wording.rb

@@ -69,8 +69,8 @@ module Hecks
         "{command} refused — {field} is {current}, and {command} moves it only from {allowed}",
         %w[TypeMismatch value_object_shape]           =>
         "{name} is a {type} — pass its fields as an object, not {offered}",
-        %w[TypeMismatch reference_as_object]          =>
-        "{command} refused — a reference is an id, and {attribute} arrived as an object{known_by}",
+        %w[TypeMismatch reference_wrong_shape]         =>
+        "{command} refused — a reference is an id, and {attribute} arrived as {offered}{known_by}",
         %w[TypeMismatch multi_field_scalar]           =>
         "{type} has multiple fields and cannot stand in for a scalar",
         %w[TypeMismatch composite_identity]           =>
@@ -106,6 +106,9 @@ module Hecks
         "{query} declares authorize with tenant: {field} — pass {field}: to name which {field} this ask is scoped to",
         %w[Unauthorized role_mismatch]                =>
         "{command} refused — role: {role}, and the caller stated {caller_role}",
+        %w[Unauthorized cross_tenant_reference]        =>
+        "{aggregate} {field} is {tenant}, but {attribute} names a {target} whose own {target_field} " \
+        "is {other} — a cross-tenant reference",
         %w[AttributeAbsent absent_read]               =>
         "{aggregate} {field} is absent on this record — declared, not optional, and added since it was written. Backfill it " \
         "in a translation (backfill :{field}, default: ...), or declare it optional: true",

data/lib/hecks/runtime/registry.rb

@@ -70,6 +70,15 @@ module Hecks
         # a boot with no era-plugin domain at all, whose first touch would
         # otherwise be a live dispatch's own `RepositoryFactory.build` read.
         @resolved_eras = {}
+        # THE SIBLING FACT `EraResolver.check!` records for an OLD checkout:
+        # domain name -> the newest held ordinal that superseded the era this
+        # boot resolved to; absent for every domain booting the current era.
+        # `RepositoryFactory.build` hands it to the adapter as
+        # `superseded_by:`, and `PostgresEra#append` refuses on it before
+        # ever issuing an INSERT — the in-process half of the era fence, the
+        # half that holds even for a connection row-level security cannot
+        # bite (BUG#24). Eager for exactly the reason `@resolved_eras` is.
+        @superseded_eras = {}
         # EAGER, NOT LAZY — see `#capability_graph`'s own comment for why.
         # `CapabilityGraph.new` only stores the registry reference; there is
         # no reason to defer it, and doing so removes the exact same
@@ -163,6 +172,9 @@ module Hecks
       # `Hecks/ThreadSharedIvarMutation` is the reason there is no `||=`
       # left here to flag.
       attr_reader :resolved_eras
+      # Domain name -> the ordinal that superseded this boot's own era, for
+      # an old checkout only — see `initialize`'s own comment on it.
+      attr_reader :superseded_eras
 
       def bluebook(name)  = @bluebooks[name.to_s]
       def hecksagon(name) = @hecksagons[name.to_s]

data/lib/hecks/runtime/routing.rb

@@ -1,5 +1,6 @@
 require_relative "errors"
 require_relative "refusal_wording"
+require_relative "../rendering"
 
 module Hecks
   module Runtime
@@ -19,7 +20,7 @@ module Hecks
       def envelope(to, entity_depth: 0)
         return nil if to.nil?
 
-        aggregate, entities = to.is_a?(Hash) ? parse_envelope_hash(to) : [to, []]
+        aggregate, entities = to.is_a?(Hash) ? parse_envelope_hash(to) : scalar_envelope(to)
 
         raise TypeMismatch, "to: must name the receiving aggregate identity" if aggregate.nil? || aggregate.to_s.empty?
         if entities.size != entity_depth
@@ -34,6 +35,49 @@ module Hecks
         Envelope.new(aggregate: aggregate, entities: entities)
       end
 
+      # BUG#7 — the non-Hash half of `to:` used to accept ANY Ruby object
+      # (`[to, []]`, unconditionally) as though it were a ready-made
+      # aggregate identity scalar. That is looser than the JSON step
+      # boundary (`bin/run`/`Fuzzing::Replay`/`StepBuilder`) ever needs it
+      # to be — every legitimate caller already hands this a `String`
+      # (`Naming.identity` canonicalizes every identity to one before it
+      # ever reaches a `to:`/legacy-args door) — and looser than Rust's own
+      # hand-written mirror of this exact boundary
+      # (`rust/src/kernel/routing.rs#RoutingEnvelope::from_json`, its own
+      # header: "Generated routers accept this shape while retaining the
+      # legacy mixed-args object as a compatibility input during
+      # migration"), which refuses anything that is neither a JSON string
+      # nor object outright, TypeMismatch, before ever reaching a domain's
+      # own command payload.
+      #
+      # The gap surfaced live on `examples/roster` — the first domain in
+      # this corpus to declare a command attribute literally named `to`
+      # (`Roster::Roster.Mark`, deliberately, per that bluebook's own
+      # header comment). `bin/qa_sweep`'s legacy-args dispatch convention
+      # (`runtime.dispatch(verb, **symbolize(args))`, `step_builder.rb`)
+      # flattens a command's own declared fact and its routing target into
+      # ONE Ruby kwargs hash — completely ordinary for every other domain,
+      # since Ruby's keyword-argument binding only steals a key that
+      # collides with `dispatch`'s own `to:`/`with:`/`saga_correlation:`
+      # parameter names. `Mark`'s `to` does collide, so a fuzzer-corrupted
+      # scalar offered for it (an out-of-range Integer, from
+      # `InvalidValueGenerator.corrupt`) was routed here as the AGGREGATE
+      # IDENTITY instead of the domain's own required argument — accepted
+      # unconditionally, leaving `Mark`'s own `to` fact absent from the
+      # payload entirely. Ruby refused `AbsentArgument` ("Mark was not
+      # given to — it takes to"); Rust's stricter `RoutingEnvelope::
+      # from_json` refuses the malformed scalar itself, TypeMismatch,
+      # before the domain payload is ever examined — the observed
+      # divergence. Tightening this branch to Rust's own contract (a
+      # scalar `to:` must be a `String`) makes both refuse the same way,
+      # for the same reason, at the same step.
+      def scalar_envelope(to)
+        return [to, []] if to.is_a?(String)
+
+        raise TypeMismatch, "to: must be a string aggregate identity or an entity route, got #{Rendering.describe(to)}"
+      end
+      private_class_method :scalar_envelope
+
       # The Hash-shaped half of `to:` — pulled out of `envelope` because
       # it is a self-contained parse (raises on an unrecognized key, then
       # returns the pair) with no dependency on anything `envelope` does
@@ -98,10 +142,31 @@ module Hecks
       end
       private_class_method :refuse_absent_facts!
 
+      # BUG#18 — an entity route naming NO entity at all (`entities: []`,
+      # or neither `entity:` nor `entities:` present) used to come back
+      # `[]` here unremarked, which only ever refused downstream for an
+      # ENTITY command (`envelope`'s own `entities.size != entity_depth`
+      # check, entity_depth >= 1) — for an AGGREGATE-level command
+      # (entity_depth 0), `[].size == 0` trivially satisfied that check,
+      # so the degenerate Hash `{aggregate:, entities: []}` reached the
+      # command's own validation instead of being refused as malformed
+      # routing. Rust's `RoutingEnvelope::from_json` never let it get
+      # that far: the Hash branch refuses "entity route requires at
+      # least one entity identity" unconditionally, before any
+      # entity_depth is known. Refusing it here too, at the same point,
+      # closes the gap without touching the scalar branch (a bare
+      # aggregate identity, no Hash at all) that every ordinary aggregate
+      # dispatch already uses instead of this shape (`Facade::Handle#
+      # dispatch`'s own `to: @id`, `CommandRequest`'s own header —
+      # "aggregate command: { to: "record-id", ... }" — and, now,
+      # `Judge#address`).
       def entity_identities(hash)
         raise TypeMismatch, "to: takes entity: or entities:, not both" if hash.key?(:entities) && hash.key?(:entity)
 
-        hash.key?(:entities) ? Array(hash[:entities]) : Array(hash[:entity])
+        identities = hash.key?(:entities) ? Array(hash[:entities]) : Array(hash[:entity])
+        raise TypeMismatch, "to: entity route requires at least one entity identity" if identities.empty?
+
+        identities
       end
       private_class_method :entity_identities
     end

data/lib/hecks/runtime/saga_interpreter.rb

@@ -506,8 +506,45 @@ module Hecks
         )
       end
 
+      # BUG#6 — UNCONDITIONALLY THE SAGA'S OWN HOME DOMAIN, never inferred
+      # from `command_name`'s own shape. This used to guess: a leftover
+      # `::` after `Naming.command_ref`'s own rewrite was read as "already
+      # domain-qualified" and left alone. That heuristic cannot actually
+      # tell a genuinely cross-domain reference (`Banking::Account::
+      # Debit` -> one `::` survives) apart from a SAME-DOMAIN entity
+      # command reference (`Manifest::Slot::Fill` -> one `::` survives
+      # too, for an unrelated reason — entity nesting, not a domain
+      # qualifier) — both collapse to the identical "one `::` left" shape,
+      # and the string alone carries no further signal to split them
+      # (confirmed against `Naming.command_ref`'s own rewrite: it only
+      # ever strips the LAST `::`, so the count of what remains is blind
+      # to why it's there). Picking the cross-domain reading unconditionally
+      # left `qa/stress_domains/waybill`'s own `Packing` saga dispatching
+      # `Manifest::Slot::Fill` — an entity command in its OWN domain —
+      # unprefixed, so `Naming.split_verb` read "Manifest" as a domain
+      # name instead of this chapter's own aggregate, and the dispatch
+      # failed with `UnknownVerb`, silently recorded as an ordinary
+      # domain refusal rather than surfacing as the real bug it is.
+      #
+      # THE FIX MIRRORS `PolicyInterpreter#deliver`'s OWN MECHANISM,
+      # which never had this bug: a policy's cross-domain target is a
+      # SEPARATE, EXPLICIT field (`Policy#target_domain`, set only by the
+      # `across` keyword) — `deliver` unconditionally builds
+      # `"#{policy.target_domain || domain}::#{policy.trigger_command}"`,
+      # never asking whether `trigger_command` LOOKS already-qualified.
+      # A saga's own `dispatch`/`compensates` has no such explicit field
+      # and no keyword to set one — and, confirmed against the ENTIRE
+      # corpus (banking's Onboarding/Settlement/ExternalSettlement,
+      # quality_control's BugCiWatch, and this domain's own Packing),
+      # no saga anywhere ever dispatches genuinely cross-domain: "every
+      # command a saga fires lands inside its own bluebook chapter"
+      # (`Projections::Diagrams#saga_diagram`'s own comment, written
+      # independently of this fix and still true). So the home domain IS
+      # the only explicit context a saga dispatch ever has — this applies
+      # it the same way `deliver` applies its own default (no `across`)
+      # case, without inventing a keyword nothing in the corpus needs.
       def qualified(command_name, domain)
-        command_name.include?("::") ? command_name : "#{domain}::#{command_name}"
+        "#{domain}::#{command_name}"
       end
 
       def end_saga(process_manager, event, domain)

data/lib/hecks/runtime/value/coercion.rb

@@ -55,13 +55,22 @@ module Hecks
         # itself, so a `reference: {value: ...}` offered against a `String`
         # query field is the documented allowance (see banking's own
         # `Account.OpenForCustomer`), not a C3.8 mismatch.
-        # `argument: true` is the CALLER'S door only (`Interpreting#normalize_
-        # args`, every command/entity/port dispatch): the one place a nil
-        # for a non-optional attribute is the caller leaving a required
-        # argument empty (C3.7). Every other caller — `sets` copying an
+        # `argument: true` is the COMMAND/ENTITY/PORT argument door only
+        # (`Interpreting#normalize_args`, every command/entity/port
+        # dispatch): the one place a nil for a non-optional attribute is
+        # the caller leaving a required argument empty (C3.7), absorbed
+        # via the type's own field defaults when every field has one
+        # (`nil_argument` below). Every other caller — `sets` copying an
         # optional argument into state, hydration, entity elements,
-        # identity, defaults — is state assembly, where nil is a legitimate
-        # "absent is not empty" value the aggregate's own attribute may hold.
+        # identity, defaults — is state assembly, where nil is a
+        # legitimate "absent is not empty" value the aggregate's own
+        # attribute may hold. `QueryInterpreter#normalize_args` never
+        # passes `argument: true` — a null required value-object-typed
+        # QUERY argument is checked, and refused, entirely on its own
+        # side (`null_vo_argument!`, query_interpreter.rb) precisely so
+        # it does NOT reach this default-absorbing fallback (QualityControl
+        # BUG#36 — a query's own null VO argument must refuse regardless
+        # of any default, unlike a command's).
         def for_attribute(aggregate, attribute, value, boundary: true, argument: false)
           return nil_or_missing(aggregate, attribute, value, argument) if attribute.nil? || value.nil?
           return reference_list(attribute, value) if attribute.list? && attribute.reference?
@@ -372,108 +381,6 @@ module Hecks
 
         def trusting_stored_state? = Thread.current[TRUSTED_LOAD_KEY] == true
 
-        # S17, ADR 0026 — SEARCHES THE WHOLE ENTITY TREE, not only the
-        # root's own direct children. `aggregate` here is always the
-        # ROOT aggregate — `for_attribute`'s own `aggregate` argument is
-        # never reassigned as hydration recurses into a nested element,
-        # because coercion has to resolve value objects, and only the
-        # root answers `.value_object` at all (Entity's own header
-        # comment: an entity must NOT answer to it, or `Value.
-        # for_attribute` could no longer tell a piece from a head). So
-        # a NESTED entity — Dispatch, inside Handler — is not a direct
-        # child of the root the way Handler itself is, and a plain
-        # `aggregate.entities.find` stops one level short of it.
-        def find_entity(construct, name)
-          construct.entities.each do |candidate|
-            return candidate if candidate.hecks_name == name
-
-            found = find_entity(candidate, name)
-            return found if found
-          end
-          nil
-        end
-
-        # Frozen through: a list read back out of the store is an answer,
-        # not a handle on what is stored.
-        #
-        # ADR 0047 — this used to bail (`return value unless entity`) the
-        # moment `attribute.type` named a value object rather than an
-        # entity, handing back the raw, un-hydrated argument untouched.
-        # A `sets :field` mutation sourced from a whole-array argument (as
-        # opposed to element-by-element `append:`) went straight through
-        # `for_attribute`'s `:list` branch, so `Banking::CardPayment.
-        # Authorize`'s own `sets :tags` (`list_of(Tag)`) stored plain
-        # Ruby Hashes as its `tags` elements forever — never a real
-        # `Value`, never through `Tag`'s own `pattern:`/`invariant`
-        # checks. `remove:`'s `==` comparison (a real `Value` against a
-        # raw `Hash`) then always failed, since `Hash#==` refuses anything
-        # that isn't itself a compatible Hash — the bug ADR 0047 traces in
-        # full. Delegating to `hydrate_value_object_list` below closes
-        # that gap the same way the ENTITY branch already worked: build a
-        # real, validated `Value` per element, reusing `for_attribute`'s
-        # own composite-construction path rather than inventing a second
-        # one.
-        def hydrate_entity_list(aggregate, attribute, value)
-          entity = find_entity(aggregate, attribute.type.to_s)
-          return hydrate_value_object_list(aggregate, attribute, value) unless entity
-
-          hydrated = Array(value).map do |element|
-            next element unless element.is_a?(Hash)
-
-            element.each_with_object({}) do |(name, field_value), acc|
-              key = name.to_sym
-              field = entity.attribute(key)
-              acc[key] = field ? for_attribute(aggregate, field, field_value) : field_value
-            end
-          end
-          Freezer.deep(hydrated)
-        end
-
-        # The value-object sibling of the entity branch above: an element
-        # already shaped like the target `Value` (or a `Hash`/scalar that
-        # `fields_for` can still open) is rebuilt through the SAME `build`
-        # a scalar composite attribute already uses (`for_attribute`'s own
-        # `coerced = ... build(value_object, fields_for(...), aggregate)`
-        # line) — same defaults, same `pattern:`/`admits:`/invariant
-        # checks, same `trusting_stored_state?` bypass on a trusted load.
-        # `attribute.type` naming neither an entity nor a value object
-        # (a `list_of(String)`, say) has no shape to rebuild into, so the
-        # element passes through unchanged, exactly as the entity branch's
-        # own non-Hash elements do.
-        #
-        # NOT `Array(value).map` (unlike the entity branch above) — `value`
-        # here is not always genuinely list-shaped. `MutationApplier#
-        # removed`'s own `Value.for_attribute(aggregate, attribute, value)`
-        # call (`attribute` = the LIST attribute, `mutation.target`; `value`
-        # = the single REMOVE-target argument, already a real `Value` by
-        # the time it gets here) reuses this exact branch — for `remove:`,
-        # not for a whole-list `sets`. `Array(a_real_Value)` alone would be
-        # harmless (`Value` defines neither `to_a` nor `to_ary`, so Kernel
-        # wraps it `[value]`), but `Array(a_Hash)` is NOT harmless: Ruby's
-        # `Array()` opens a bare Hash into its own `[[k, v], ...]` pairs,
-        # not `[hash]` — silently shredding a single-element Hash-shaped
-        # target into garbage instead of hydrating it. Branching on
-        # `value.is_a?(Array)` up front (true only for a genuine whole-list
-        # `sets`/hydrate load) keeps the single-target shape a single
-        # target, hydrated the same way, never listified.
-        def hydrate_value_object_list(aggregate, attribute, value)
-          return value unless aggregate.respond_to?(:value_object)
-
-          value_object = value_object_for(aggregate, attribute.type)
-          return value unless value_object
-
-          return hydrate_value_object_element(aggregate, attribute, value_object, value) unless value.is_a?(Array)
-
-          hydrated = value.map { |element| hydrate_value_object_element(aggregate, attribute, value_object, element) }
-          Freezer.deep(hydrated)
-        end
-
-        def hydrate_value_object_element(aggregate, attribute, value_object, element)
-          return element if element.is_a?(self) && element.type_name == value_object.hecks_name
-
-          build(value_object, fields_for(value_object, attribute.name, element), aggregate)
-        end
-
         # `Value.identifier` used to live here: hand it a one-field value object
         # and it opened it, so `identified_by :number` could pass for an identity
         # and the runtime would guess which field was meant. THAT GUESS IS GONE.
@@ -490,7 +397,7 @@ module Hecks
         # it carried said retiring it meant changing how references are STORED ;
         # that is what happened.
 
-        # A REFERENCE IS AN ID, SO AN OBJECT IS NOT ONE.
+        # A REFERENCE IS AN ID, SO ANYTHING ELSE IS NOT ONE.
         #
         # Nothing coerces a reference — `for_attribute` misses on
         # "Reference<Account>", which is no value object's name, and hands the
@@ -502,21 +409,76 @@ module Hecks
         # coercion because the sentence names the COMMAND, and `for_attribute`
         # never learns which command it is serving.
         #
-        # An Array is deliberately not refused here. A reference is never a list
-        # today, and inventing a rule for a shape the language cannot declare is
-        # how decoration gets written.
+        # WIDENED PAST THE OBJECT SHAPE BY BUG#27 (QualityControl ledger,
+        # found live on `qa/stress_domains/referral_chain`'s `Member.Join`/
+        # `Referral.Issue`). A bare Boolean, Array, or `null` used to sail
+        # through here untouched — nothing but Hash/Value ever refused —
+        # then get `.to_s`'d into a lookup key by `CommandRules::
+        # References#reference_key` ("true", "false", "[8, 8]") and answer
+        # NotFound, or, for `null`, skip the lookup outright
+        # (`next if held.nil?`, command_rules/references.rb) and let the
+        # command run on to whatever its own `given` happened to say — a
+        # shape error misreading as a missing record, or as an unrelated
+        # domain refusal. Rust's generated `from_json` requires a JSON
+        # string for a required reference field before anything else runs
+        # (`JoinArgs.sponsor: expected String`); this closes the same gate
+        # at the same DISPATCH_ORDER step Ruby already runs it at
+        # (`normalize_args`, `Vocabulary::AggregateDispatchOrder`/
+        # `EntityDispatchOrder`), strictly before `resolve_references` ever
+        # receives a value to look up — so the two engines now agree on
+        # BOTH kind and order, not just kind.
+        #
+        # `nil` STAYS LEGITIMATE for a `reference_to ..., optional: true`
+        # argument (`Improvement.Open`'s own `reference_to Angle, optional:
+        # true` — `qa/bluebook/quality_control.bluebook`): the caller
+        # genuinely may have nothing to name yet, and `nil_argument`
+        # (interpreting.rb) already passes an optional reference's `nil`
+        # through untouched. A REQUIRED reference offered as `null` is a
+        # caller leaving a required argument empty in every OTHER sense
+        # this runtime already refuses (C3.7) — refusing it HERE, rather
+        # than falling through to `resolve_references`' own nil-skip and
+        # then whatever the command's `given` happens to say, is what
+        # actually names the empty argument instead of something else.
+        #
+        # A `has_many` reference's own Array shape is still never refused
+        # by ITS wrapper (`Array(value).find { ... }` only inspects the
+        # list's ELEMENTS) — a reference is never a scalar list-of-lists
+        # today, and inventing a rule for a shape the language cannot
+        # declare is how decoration gets written. `reference_list` (below)
+        # already owns "not an Array at all" for that case.
         def refuse_object_reference(command, attribute, value)
           return unless attribute.reference?
 
-          offered = attribute.list? ? Array(value).find { |item| item.is_a?(Hash) || item.is_a?(self) } : value
-          return unless offered.is_a?(Hash) || offered.is_a?(self)
+          if attribute.list?
+            offered = Array(value).find { |item| item.is_a?(Hash) || item.is_a?(self) }
+            return unless offered
+          else
+            return if value.nil? && attribute.optional?
+            return if value.is_a?(String)
+
+            offered = value
+          end
 
           raise TypeMismatch,
-                RefusalWording.render("TypeMismatch", "reference_as_object",
+                RefusalWording.render("TypeMismatch", "reference_wrong_shape",
                                       command: command.hecks_name, attribute: attribute.name,
+                                      offered: reference_shape_description(offered),
                                       known_by: known_by(attribute))
         end
 
+        # "an object" for the Hash/Value shape — the ORIGINAL wording this
+        # method always gave, pinned byte for byte by
+        # `spec/runtime/reference_shape_spec.rb`, kept unchanged by BUG#27's
+        # widening. `Rendering.describe` for everything else: `true`,
+        # `false`, `nil`, `[8, 8]` — the same rendering every other
+        # TypeMismatch in this file already uses for "here is what you
+        # actually sent."
+        def reference_shape_description(value)
+          return "an object" if value.is_a?(Hash) || value.is_a?(self)
+
+          Rendering.describe(value)
+        end
+
         # "(Account is known by number)" — what to send instead. No article, on
         # purpose: "an Account" and "a Customer" differ by the target's first
         # letter, and a refusal pinned byte-for-byte should not hinge on an