hecks 0.3.0 → 1.0.0

data/lib/hecks/runtime/entity_interpreter.rb

@@ -10,11 +10,25 @@ require_relative "routing"
 require_relative "dependency_planning"
 require_relative "../ports/persistence/execution"
 require_relative "entity_element"
+require_relative "command_interpreter/argument_gate"
 
 module Hecks
   module Runtime
     class EntityInterpreter
       include Interpreting
+      # THE SAME PAYLOAD GATE aggregate commands and port operations already
+      # run — bug audit H1 (docs/audits/2026-08-10-main-bug-audit.md): this
+      # class used to run NEITHER refuse_unknown_arguments NOR
+      # refuse_absent_arguments, on a comment claiming "an entity inherits
+      # its aggregate's own gate." Nothing on the entity dispatch path ever
+      # ran one — confirmed live, `LedgerEntry.Reverse` accepted an
+      # unrecognized `bogus_arg:` outright, and dispatching it with no
+      # `narrative:` silently overwrote the stored narrative with `nil`
+      # (`sets :narrative`'s bare self-referential form reads `args[:narrative]`
+      # unconditionally). See `step_refuse_unknown_arguments`/
+      # `step_refuse_absent_arguments`, below, for how the shared gate is
+      # reused rather than reimplemented.
+      include CommandInterpreter::ArgumentGate
 
       attr_reader :registry
 
@@ -23,13 +37,17 @@ module Hecks
       # spec/vocabulary_conformance_spec.rb the same way CommandInterpreter's
       # own DISPATCH_ORDER is; see that constant's doc comment for why this is
       # hand-typed rather than read live off the meta-domain at every dispatch.
-      # Shorter than the aggregate order for the same reasons the declaration
-      # itself gives : no refuse_unknown_arguments/refuse_absent_arguments (an
-      # entity inherits its aggregate's own gate) and no
-      # assign_creation_attributes (an entity is never created through this
+      # `refuse_unknown_arguments`/`refuse_absent_arguments` now lead it, same
+      # position `AggregateDispatchOrder` holds them at (H1, above) — the only
+      # remaining difference from the aggregate order is no
+      # `assign_creation_attributes` (an entity is never created through this
       # path).
       DISPATCH_ORDER = Hecks::Vocabulary.symbols("EntityDispatchOrder")
 
+      # Same safety valve as `CommandInterpreter::MAX_STALE_WRITE_RETRIES` —
+      # see that constant's own comment.
+      MAX_STALE_WRITE_RETRIES = 5
+
       # `instance` is the PARENT aggregate record (what gets saved and
       # returned) ; `element`/`view` are the entity piece itself — `view`
       # wraps `element` as it stood at `locate_element`, pre-mutation, and
@@ -56,6 +74,10 @@ module Hecks
       # comment for the shared reasoning (Dispatcher#dry_run?'s own entry
       # point). `step_save`/`step_emit` are the only two steps here that
       # read it either.
+      # RETRIES THE WHOLE METHOD BODY on `StaleWrite` — same reasoning as
+      # `CommandInterpreter#call`'s own retry: a fresh `ctx`, a fresh
+      # `step_hydrate_parent`/`step_locate_element` re-reading current
+      # state.
       def call(domain, aggregate, dotted, legacy_args, route: nil, with: nil, dry_run: false)
         *entity_names, command_name = dotted.to_s.split(".")
         if entity_names.empty?
@@ -70,13 +92,24 @@ module Hecks
                                                            entity: entity.hecks_name, command: command_name.inspect))
 
         args = Routing.payload(command, with: with, legacy: legacy_args)
-        ctx = Context.new(domain, aggregate, entity, entity_names.join("."), command, command_name, args)
-        ctx.chain = chain
-        ctx.route = route
-        ctx.dry_run = dry_run
-        ctx.plan = DependencyPlanning::Analyzer.call(aggregate: entity, command: command)
-        run_dispatch_order(DISPATCH_ORDER, ctx)
-        [ctx.instance, ctx.result, ctx.plan, ctx.persistence_outcome]
+        attempt = 0
+        begin
+          ctx = Context.new(domain, aggregate, entity, entity_names.join("."), command, command_name, args)
+          ctx.chain = chain
+          ctx.route = route
+          ctx.dry_run = dry_run
+          ctx.plan = DependencyPlanning::Analyzer.call(aggregate: entity, command: command)
+          # RESOLVED HERE, ONCE — see CommandInterpreter#call's own comment;
+          # `step_hydrate_parent` reads `ctx.repository` without re-fetching.
+          ctx.repository = @registry.repository(domain, aggregate)
+          lock_id = Identity.best_effort(aggregate, args, route)
+          run_dispatch_order_with_isolation(DISPATCH_ORDER, ctx, lock_key_id: lock_id)
+          [ctx.instance, ctx.result, ctx.plan, ctx.persistence_outcome]
+        rescue StaleWrite
+          attempt += 1
+          retry if attempt < MAX_STALE_WRITE_RETRIES
+          raise
+        end
       end
 
       private
@@ -100,6 +133,31 @@ module Hecks
         end
       end
 
+      # `extra_identity_heads:` — every entity `ctx.chain` walks through, not
+      # just the root aggregate `ArgumentGate` already knows about. A
+      # two-hop dispatch (`Handler.Dispatch.Bind`) is addressed by BOTH
+      # hops' own identity, each read straight out of `args` by
+      # `EntityElement#element_of` — refusing those as unknown would refuse
+      # every legitimate nested-entity dispatch there is, the same reasoning
+      # `ArgumentGate#refuse_unknown_arguments`'s own header gives for `:id`/
+      # the root's `identity_heads`.
+      def step_refuse_unknown_arguments(ctx)
+        step(:refuse_unknown_arguments) {
+          refuse_unknown_arguments(ctx.domain, ctx.aggregate, ctx.command, ctx.args,
+                                   extra_identity_heads: ctx.chain.flat_map(&:identity_heads))
+        }
+      end
+
+      # No `aggregate:` exemption to pass — that kwarg exists only for a
+      # port operation's own self-address (`ArgumentGate#refuse_absent_
+      # arguments`'s own comment); an entity command's chain identity never
+      # reaches `command.attributes` in the first place (resolved as
+      # addressing above, not as a declared fact), so there is nothing here
+      # for the exemption to need to strip.
+      def step_refuse_absent_arguments(ctx)
+        step(:refuse_absent_arguments) { refuse_absent_arguments(ctx.command, ctx.args) }
+      end
+
       def step_normalize_args(ctx)
         ctx.args = step(:normalize_args) { normalize_args(ctx.aggregate, ctx.command, ctx.args) }
       end
@@ -113,7 +171,8 @@ module Hecks
       end
 
       def step_hydrate_parent(ctx)
-        ctx.repository = @registry.repository(ctx.domain, ctx.aggregate)
+        # `ctx.repository` is resolved once, in `#call`, before the
+        # isolation decision — not here any more.
         ctx.instance = step(:hydrate_parent) {
           parent(ctx.repository, ctx.aggregate, ctx.entity_name, ctx.command_name, ctx.args, ctx.route)
         }
@@ -184,8 +243,20 @@ module Hecks
 
         step(:save) do
           @rules.resolve_state_references(ctx.domain, ctx.aggregate, ctx.instance.state)
-          ctx.repository.save(ctx.instance)
-          ctx.persistence_outcome = Ports::Persistence::Outcome.new(status: :saved, instance: ctx.instance)
+          # `expected_version:` — see CommandInterpreter#step_save's own
+          # comment: nil for a repository that isn't CAS-capable, or an
+          # instance never read from storage, either of which falls
+          # through to a plain save inside `AppendOnly#save`.
+          ctx.persistence_outcome = ctx.repository.save(ctx.instance, expected_version: ctx.instance.version)
+          if ctx.persistence_outcome.status == :stale
+            # NOT a `RefusalWording.render` call — see
+            # `CommandInterpreter#step_save`'s identical branch and
+            # `Runtime::StaleWrite`'s own comment.
+            raise(StaleWrite,
+                  "#{ctx.command.hecks_name} on #{ctx.aggregate.hecks_name} " \
+                  "(#{Identity.reading(ctx.aggregate)}: #{Rendering.describe(ctx.instance.id)}) lost a race — " \
+                  "another write committed against this record after it was read")
+          end
         end
       end
 

data/lib/hecks/runtime/errors.rb

@@ -51,6 +51,28 @@ module Hecks
     # itself, not whether the caller actually holds `policy`. See
     # Runtime::TenantScope.
     class Unauthorized < StandardError; end
+    # `corrects` names a past event this record must have already emitted
+    # (CommandBuilder#corrects_impl's own comment) — a fact the expression
+    # evaluator cannot check (it is not a predicate over the record's OWN
+    # fields, it is "did this exact record ever announce this"), so it is
+    # raised structurally, the same way AlreadyExists/NotFound are, rather
+    # than being expressible as an ordinary `given`. Raised by
+    # `CommandRules::Admissibility#enforce_correction_target`.
+    class NothingToCorrect < StandardError; end
+
+    # A RUNTIME FAULT, NOT A DOMAIN REFUSAL — deliberately absent from
+    # `DOMAIN_REFUSALS` below and from `vocabulary.bluebook`'s own
+    # `DomainRefusal` list. Raised when an optimistic-concurrency CAS write
+    # (`AppendOnly#save`'s `expected_version:`) finds the stored version has
+    # moved since this instance was read — someone else's write committed
+    # in between. `CommandInterpreter#call`/`EntityInterpreter#call` catch
+    # this themselves and retry the whole dispatch from a fresh hydrate, so
+    # `enforce_givens` re-evaluates against the now-current state; a caller
+    # only ever sees this escape when every retry is exhausted under
+    # sustained contention — an operational condition (many concurrent
+    # writers hammering one aggregate), not a business rule a domain author
+    # declared. See docs/decisions/ (concurrency-control ADR).
+    class StaleWrite < StandardError; end
 
     # A Lambda-routed domain's own refusal (rust/host, `Runtime::
     # RemoteDispatcher`), carrying Rust's own refusal text verbatim —

data/lib/hecks/runtime/identity.rb

@@ -23,6 +23,15 @@ module Hecks
     module Identity
       module_function
 
+      # A hash read that decides which spelling of a key answers by
+      # PRESENCE, never by `||` — a bare `||` treats a genuinely-held
+      # `false` the same as an absent key and falls through to the other
+      # spelling, landing on `nil` instead of the real, stored answer.
+      def hash_lookup(hash, key)
+        sym = key.to_sym
+        hash.key?(sym) ? hash[sym] : hash[key]
+      end
+
       # The head names the ATTRIBUTE and is consumed by whoever looked the value
       # up; what is left is the walk down into it. A path with no fields to walk
       # — an aggregate that declares no identity and falls back to `id` — hands
@@ -32,7 +41,7 @@ module Hecks
         return held if fields.empty?
 
         fields.reduce(Value.materialize(held)) do |dug, field|
-          dug.is_a?(Hash) ? (dug[field.to_sym] || dug[field]) : nil
+          dug.is_a?(Hash) ? hash_lookup(dug, field) : nil
         end
       end
 
@@ -83,7 +92,7 @@ module Hecks
           # arrived whole has to be opened.
           return held.to_s unless held.is_a?(Hash)
 
-          return rest.reduce(held) { |h, f| h.is_a?(Hash) ? (h[f.to_sym] || h[f]) : nil }&.to_s
+          return rest.reduce(held) { |h, f| h.is_a?(Hash) ? hash_lookup(h, f) : nil }&.to_s
         end
 
         # Coerced against the identity ATTRIBUTE only when the caller actually
@@ -123,6 +132,25 @@ module Hecks
       def reading(construct)
         construct.identity_paths.join(", ")
       end
+
+      # BEST-EFFORT, FOR A LOCK KEY ONLY — `Runtime::AggregateLock`'s own
+      # per-record striping needs SOME id to key on before dispatch has run
+      # far enough to hydrate for real, so this walks the identical chain
+      # `CommandInterpreter#hydrate_existing`/`#hydrate_prior_or_initial`
+      # and `EntityInterpreter#parent` already use to locate the real
+      # record — but wrapped to never raise. Choosing which Mutex to hold
+      # must never itself become a crash. `nil` means "could not resolve
+      # from the raw, pre-normalized payload this runs against" — the
+      # caller locks by aggregate type alone in that case (coarser, still
+      # correct, just less concurrent).
+      def best_effort(construct, args, route = nil, reference_key: nil)
+        route&.aggregate ||
+          of(construct, args) ||
+          from(construct, args, :id) ||
+          (reference_key && from(construct, args, reference_key))
+      rescue StandardError
+        nil
+      end
     end
   end
 end

data/lib/hecks/runtime/instance.rb

@@ -1,16 +1,34 @@
 require_relative "value"
+require_relative "identity"
 
 module Hecks
   module Runtime
     class Instance
       attr_reader :aggregate, :id
       attr_accessor :state
-
-      def initialize(aggregate:, id:, state: nil)
+      # OUT-OF-BAND ADAPTER BOOKKEEPING, NOT DOMAIN STATE — the optimistic-
+      # concurrency version a CAS-capable adapter (Postgres today) stamps
+      # on a record it reads/writes, so a later `save` can assert "commit
+      # only if nobody has written since". Deliberately absent from
+      # `to_h`/`[]`/`[]=`/`method_missing` : a domain author never declares
+      # this, a `given`/`ensures`/`invariant` can never read it, and no
+      # adapter that doesn't understand it (Memory, Heki) ever sets it —
+      # `nil` there just means "no CAS attempted", which is exactly what a
+      # plain `save` already does. See docs/decisions/ (concurrency-control
+      # ADR) for the full mechanism.
+      attr_accessor :version
+
+      # `args:` — THE ORIGINAL COMMAND PAYLOAD, offered only by a fresh
+      # creation (`CommandInterpreter#hydrate_legacy_creation`/
+      # `#hydrate_complete_state`/`#hydrate_prior_or_initial`, each already
+      # holding it when they mint a brand-new record). See
+      # `materialize_identity!` for why a composite identity needs it.
+      def initialize(aggregate:, id:, state: nil, args: nil)
         @aggregate = aggregate
         @id        = id
         @state     = state ? self.class.hydrate_with_defaults(aggregate, state) : self.class.defaults(aggregate)
-        materialize_identity!
+        @version   = nil
+        materialize_identity!(args)
       end
 
       # Loading existing state runs the same default-fill a fresh instance
@@ -103,7 +121,29 @@ module Hecks
 
       private
 
-      def materialize_identity!
+      # M17 — a COMPOSITE identity (`identity_heads.size > 1`, e.g.
+      # `identified_by :branch_code, :box_number`) has no single
+      # `identified_by` to fall back to `:id` for — `@aggregate.identified_by`
+      # is nil the moment there is more than one head (`Behaviour::Identified
+      # #derive_identity`), so the single-head branch below never runs for
+      # it at all. A creating command that declares those heads as ordinary
+      # attributes but doesn't ALSO `sets` them (redundant with the identity
+      # the command's own args already named) used to persist every head as
+      # nil — the id correctly named the record, but the record's own
+      # attributes forgot what named it.
+      #
+      # Filled from `args`, never from splitting `@id` back apart — the
+      # same reason the single-head branch below won't guess a multi-path
+      # identifier from its joined string: `@id` is a display key, not a
+      # reversible serialization, and a composite's own separator can
+      # collide with a part's own text. `args` is only offered by a FRESH
+      # creation (`Instance.new`'s own `args:` comment); an existing record
+      # read back from storage has no args to lean on, and doesn't need
+      # one since a correctly-persisted record already carries its own
+      # heads.
+      def materialize_identity!(args = nil)
+        return materialize_composite_identity!(args) if @aggregate.identity_heads.size > 1
+
         identity  = @aggregate.identified_by || :id
         attribute = @aggregate.attribute(identity)
         return unless attribute && @state[identity].nil?
@@ -115,6 +155,21 @@ module Hecks
 
         @state[identity] = Value.from_identifier(@aggregate, attribute, @id)
       end
+
+      def materialize_composite_identity!(args)
+        return unless args
+
+        @aggregate.identity_paths.each do |path|
+          head = path.to_s.split(".").first.to_sym
+          attribute = @aggregate.attribute(head)
+          next unless attribute && @state[head].nil?
+
+          raw = Identity.from(@aggregate, args, path, value_owner: @aggregate)
+          next if raw.nil?
+
+          @state[head] = Value.from_identifier(@aggregate, attribute, raw)
+        end
+      end
     end
   end
 end

data/lib/hecks/runtime/interpreting.rb

@@ -1,4 +1,5 @@
 require_relative "value"
+require_relative "aggregate_lock"
 
 module Hecks
   module Runtime
@@ -43,6 +44,26 @@ module Hecks
         order.each { |name| send(:"step_#{name}", ctx) }
       end
 
+      # THE CONCURRENCY-CONTROL SPLIT — see docs/decisions/ (concurrency
+      # control ADR) for the full mechanism. A repository that declares
+      # `:optimistic_concurrency` (Postgres today) already closes the
+      # lost-update gap itself, via `step_save`'s CAS + `#call`'s own
+      # `StaleWrite` retry loop — an extra in-process lock here would be
+      # pointless overhead, not incorrect, so it's skipped for clarity.
+      # Every other repository (Heki, Memory — confirmed process-local
+      # data, never a second process writing the same store) gets a
+      # striped `Mutex` held for the WHOLE dispatch-order run, so a second
+      # thread's own hydrate can't start until the first thread's save has
+      # landed. `lock_key_id` is best-effort (`Identity.best_effort`) —
+      # `nil` still locks correctly, just coarser (by aggregate type).
+      def run_dispatch_order_with_isolation(order, ctx, lock_key_id:)
+        if ctx.repository.capabilities.include?(:optimistic_concurrency)
+          run_dispatch_order(order, ctx)
+        else
+          AggregateLock.for(ctx.domain, ctx.aggregate, lock_key_id).synchronize { run_dispatch_order(order, ctx) }
+        end
+      end
+
       # Every declared attribute present in the payload passes the reference
       # gate, then coercion — the same walk whether the command acts on an
       # aggregate or on one of its entity's elements.

data/lib/hecks/runtime/loader.rb

@@ -1,8 +1,9 @@
 require_relative "../facade/surface"
 require_relative "../ports/loading"
+require_relative "../ports/persistence"
 require_relative "dispatcher"
 require_relative "remote_dispatcher"
-require_relative "era_check"
+require_relative "boot_gates"
 require_relative "registry"
 
 module Hecks
@@ -42,20 +43,7 @@ module Hecks
           loading.load_domain(directory, environment: environment)
         end
 
-        # The era gate runs BEFORE verify! builds repositories: minting an
-        # era (Postgres) must have created its partition and head views
-        # before any adapter opens them, and a refused era must refuse
-        # before any adapter touches data.
-        EraCheck.check!(registry, directory)
-        registry.verify!
-        # AFTER verify! (conservative — any wiring error surfaces first,
-        # not strictly required since resolution only needs the
-        # hecksagon binds, already loaded), BEFORE the dispatcher is
-        # built — repopulates `saga_instances` from whatever durable
-        # store each domain's own adapter answers with (§2-§4), so a
-        # process manager mid-flight at the last shutdown/crash/cold-
-        # start doesn't start this boot looking like it never began.
-        registry.rehydrate_sagas!
+        run_boot_gates!(registry, directory)
         dispatcher = dispatcher_for(registry)
         install_facade ? bind_runtime(dispatcher) : dispatcher
       end
@@ -95,13 +83,66 @@ module Hecks
           loading.load_selected(files, environment: environment)
         end
 
-        EraCheck.check!(registry, directory)
-        registry.verify!
-        registry.rehydrate_sagas!
+        run_boot_gates!(registry, directory)
         dispatcher = dispatcher_for(registry)
         install_facade ? bind_runtime(dispatcher) : dispatcher
       end
 
+      # ADR 0031 — replaces two previously-hardcoded, unconditional calls
+      # with a per-boot `BootGates` instance holding exactly the gates THIS
+      # registry's own bound adapters have a capability for. Ordering is
+      # preserved: era-checking (when a persistence plugin contributes one)
+      # still runs before `verify!`, saga rehydration still runs after
+      # (conservative — see `SagaPersistence#rehydrate_sagas!`'s own
+      # comment).
+      #
+      # ADR 0033 — this loader no longer names `EraCheck`, or any other
+      # era-specific class, at all. Every LOADED persistence plugin
+      # (`Ports::Persistence.each_plugin` — nothing here if nothing was
+      # ever `require`d) is asked to contribute its own `:pre_verify`/
+      # `:post_verify` gates generically; `:saga_rehydration` is the one
+      # gate core still registers directly, because ADR 0031 already
+      # proved it's not era-specific.
+      def self.run_boot_gates!(registry, directory)
+        gates = BootGates.new
+        Ports::Persistence.each_plugin { |plugin| plugin.contribute_boot_gates(registry, gates) }
+        check_compute_rules_backstop!(registry)
+
+        gates.run!(:pre_verify, registry, directory)
+        registry.verify!
+
+        gates.register(:saga_rehydration, ->(reg, _dir) { reg.rehydrate_sagas! }, phase: :post_verify) if
+          registry.hecksagons.each_key.any? { |domain| registry.saga_persistence(domain) != Ports::Persistence::NULL_SAGA_STORE }
+        gates.run!(:post_verify, registry, directory)
+        gates
+      end
+
+      # The one piece of the old, era-owned `check_compute_rules!` core
+      # still carries — deliberately thinner. `registry.translations` is
+      # plain `Bluebook::Translation`/`TranslationAggregate`/
+      # `TranslationCompute`/`TranslationRekey` data (`bluebook/
+      # translation.rb`, core, no era-specific class involved), so this
+      # needs nothing plugin-specific to ask "does anything declare a
+      # compute/rekey rule at all." A LOADED persistence plugin (e.g. the
+      # era plugin's own `:era_compute_rules` gate, registered above) runs
+      # the real, adapter-aware version of this check and refuses by name
+      # ("...is bound to Memory") long before this ever would; this only
+      # fires when nothing did, because nothing was loaded to.
+      def self.check_compute_rules_backstop!(registry)
+        return if Ports::Persistence.plugins_loaded?
+
+        registry.translations.each do |translation|
+          translation.aggregates.each do |aggregate|
+            next if aggregate.computes.empty? && aggregate.rekeys.empty?
+
+            raise WiringError,
+                  "cannot boot #{translation.domain}::#{aggregate.name}: a compute/rekey rule is declared, but no " \
+                  "persistence plugin that can interpret it is loaded (e.g. require " \
+                  "\"hecks/ports/persistence/plugins/era\")"
+          end
+        end
+      end
+
       # `RemoteDispatcher` for a domain routed through Lambda,
       # `Dispatcher` otherwise — the ONE place this decision gets
       # made, so everything built on top (`Handle`, `AggregateDoor`,

data/lib/hecks/runtime/query_interpreter.rb

@@ -177,11 +177,26 @@ module Hecks
 
         ordered = ordered_elements(rows, declared.order_by, declared.null_semantics,
                                    parent_key, entity.identity_heads)
-        declared.limit ? ordered.first(resolve_query_value(declared.limit.value, args).to_i) : ordered
+        # OFFSET FIRST, THEN LIMIT — same fix, same reasoning, as
+        # #interpret's own rows above. `entity_rows` is the ONLY engine
+        # for entity/sub-list queries, so a declared offset here silently
+        # vanished for every entity query, not merely one path among
+        # several.
+        skipped = declared.offset ? ordered.drop(resolve_query_value(declared.offset.value, args).to_i) : ordered
+        declared.limit ? skipped.first(resolve_query_value(declared.limit.value, args).to_i) : skipped
       end
 
+      # FieldPath.dig, not a raw `element[clause.field.to_sym]` — an
+      # entity sub-list row is a plain hash merged from stored state
+      # (mixed string/symbol keys depending on adapter, per `#cell`'s own
+      # comment below), and a dotted `where` (`where "price.cents" < 100`)
+      # needs the same segment-by-segment walk every other query path
+      # already gets. Reading only the symbol spelling of the WHOLE
+      # dotted string as one key always missed — `element[:"price.cents"]`
+      # is never a real key — so a dotted where on an entity query
+      # silently matched nothing, on the only engine entity queries have.
       def element_where_holds?(clause, element, args)
-        holds?(clause, element[clause.field.to_sym], args)
+        holds?(clause, QuerySpecification::FieldPath.dig(element, clause.field), args)
       end
 
       # A row's own key, however the store spells it. A sub-list row is a plain hash
@@ -191,7 +206,13 @@ module Hecks
       # to remove. It rides `comparable` for the same reason a where-clause does : an
       # identity is a value object, and `to_s` on one is an OBJECT ADDRESS — a sort key
       # that differs run to run, which is worse than the store order it replaced.
-      def cell(row, key) = row[key.to_sym] || row[key.to_s]
+      # `key?` decides which spelling answers, never `||` — a row whose
+      # value is a genuinely-held `false` must not fall through to the
+      # other spelling (usually absent) and land on `nil`.
+      def cell(row, key)
+        sym = key.to_sym
+        row.key?(sym) ? row[sym] : row[key.to_s]
+      end
 
       # A sub-list row is identified by its PARENT and then its own key : two
       # entities under different parents can share a sequence, so the parent has
@@ -244,10 +265,21 @@ module Hecks
 
       def comparable(value) = QuerySpecification::Common::Comparison.comparable(value)
 
+      # FieldPath.dig, not a raw `record[field]` — `record` is an Instance
+      # here, and a dotted order_by (`order_by "price.cents"`) is a
+      # single symbol key (`:"price.cents"`) that never matches anything
+      # `Instance#[]` actually holds, so a dotted order_by silently sorted
+      # by all-nil (the identity tier alone deciding every tie) on this,
+      # the reference/no-native-hook engine — the same bug already fixed
+      # for `where` (see `where_holds?` above) and for entity rows (see
+      # `ordered_elements` below), just not yet for this, the aggregate-
+      # level order_by.
       def ordered(records, order_by, null_semantics = nil)
         field = order_by&.field
         Ports::Query::Ordering.apply(records, order_by, null_semantics,
-                                     identity: ->(record) { record.id.to_s }) { |record| comparable(record[field]) }
+                                     identity: ->(record) { record.id.to_s }) { |record|
+          comparable(QuerySpecification::FieldPath.dig(record, field))
+        }
       end
     end
   end

data/lib/hecks/runtime/reaction_invocation.rb

@@ -52,8 +52,16 @@ module Hecks
                     visible = normalized_scopes.find { |scope| scope.facts.key?(source) }
                     unless visible
                       names = normalized_scopes.map(&:name).join(" then ")
+                      # WHAT IS VISIBLE, NAMED. A refusal that only says which name is
+                      # missing sent a modeler guessing field after field
+                      # (`number`, `reference`…) at a fan-out row that is addressed
+                      # by ONE key — `account`, the lowercase aggregate — which
+                      # nothing else in the domain spells out. The names each scope
+                      # actually offers are the whole diagnosis; the refusal now
+                      # lists them, scope by scope.
+                      offered = normalized_scopes.map { |scope| "#{scope.name}: #{scope.facts.keys.sort.join(', ')}" }.join("; ")
                       raise UnknownArgument,
-                            "#{label}'s with: reads :#{source}, which is not visible in #{names}"
+                            "#{label}'s with: reads :#{source}, which is not visible in #{names} (visible — #{offered})"
                     end
                     visible.facts.fetch(source)
                   end

data/lib/hecks/runtime/read_model_interpreter.rb

@@ -68,7 +68,7 @@ module Hecks
         root_heads, other_heads = model.aggregate_heads.partition { |head| head[:aggregate] == model.reference_target }
         projected = []
         rows_by_as = {}
-        (root_heads + other_heads).each do |head|
+        (root_heads + order_other_heads(bluebook, root_heads, other_heads)).each do |head|
           rows = if head[:aggregate] == model.reference_target
                    [fetch(bluebook, domain, head[:aggregate], reference_id)]
                  elsif rootless
@@ -112,6 +112,81 @@ module Hecks
         end]
       end
 
+      # THE ROOT-FIRST FIX'S OWN FIX — root-first alone only reaches one
+      # level: it guarantees the root is in `projected` before any other
+      # head is matched, but a CHAIN of non-root heads (a head that
+      # references another non-root head, not the root) is still
+      # matched against whatever declaration order happened to put in
+      # `projected` so far. `include Coupon` before `include Promotion`
+      # on a read model rooted at Item, where Coupon references
+      # Promotion (which references Item), silently returned an empty
+      # `coupons` array — Coupon's match ran while `projected` held only
+      # Item, one level short of what it needed.
+      #
+      # Fixed the same way root-first was: not by asking bluebook authors
+      # to declare `include` in dependency order (the same promise
+      # `read_model_builder.rb` already makes and this file is the one
+      # place obligated to keep), but by topologically sorting the
+      # non-root heads on their OWN declared reference fields before
+      # this method's runtime matching ever runs — Kahn's algorithm,
+      # picking ready heads in DECLARED order at each step so declaring
+      # order still governs whenever there is no dependency to break a
+      # tie. This generalizes root-first (a chain of length 1) to a
+      # chain of any depth, and to a head depending on more than one
+      # other head at once (not just a straight chain).
+      #
+      # A cycle among non-root heads (A references B which references A)
+      # has no valid topological order at all — falls back to the
+      # remaining heads' declared order rather than looping forever, the
+      # same "whichever runs first finds nothing" behaviour this method
+      # had for every non-root head before root-first existed.
+      def order_other_heads(bluebook, root_heads, other_heads)
+        resolved = root_heads.map { |head| head[:aggregate] }
+        remaining = other_heads.dup
+        ordered = []
+        until remaining.empty?
+          ready, blocked = remaining.partition do |head|
+            depends_on(bluebook, head, other_heads).all? { |target| resolved.include?(target) }
+          end
+          if ready.empty?
+            ordered.concat(remaining)
+            break
+          end
+          ordered.concat(ready)
+          resolved.concat(ready.map { |head| head[:aggregate] })
+          remaining = blocked
+        end
+        ordered
+      end
+
+      # Which OTHER declared (non-root) heads a head's own aggregate
+      # holds a reference field toward — the same relationship this
+      # file's runtime matching checks record-by-record, asked here
+      # statically, once, to order heads before any record is read.
+      #
+      # `head[:aggregate]` names whatever `include` was given — and
+      # `include` accepts a nested ENTITY (Member, nested under
+      # ValueObject ; Handler and Dispatch, nested under ProcessManager
+      # — bluebook.bluebook's own `WholeBluebook` read model includes
+      # all three) just as readily as a top-level aggregate.
+      # `bluebook.aggregate` only ever finds the latter
+      # (Behaviour::Chapter#aggregate searches `@aggregates`, which
+      # holds no entities), so it returns nil for an entity-headed
+      # include — a real case, not a malformed one. `records`, below,
+      # already treats that nil as "no rows of its own to fetch" ;
+      # a head with no rows of its own has nothing to check for a
+      # reference field either, so it depends on nothing here, the
+      # same as it always silently read empty before this file's
+      # topological sort existed.
+      def depends_on(bluebook, head, other_heads)
+        aggregate = bluebook.aggregate(head[:aggregate])
+        return [] unless aggregate
+
+        other_heads.reject { |other| other[:aggregate] == head[:aggregate] }
+                   .select { |other| reference_fields(aggregate, other[:aggregate]).any? }
+                   .map { |other| other[:aggregate] }
+      end
+
       # `group_by`'s own declared fields, checked against the ONE
       # many-side head they apply to (`seal_group_by` already refuses
       # zero or several) — resolved here, once, rather than re-derived

data/lib/hecks/runtime/refusal_wording.rb

@@ -70,6 +70,8 @@ module Hecks
                                                          "{type} is a composite identity — an identity must have exactly one field",
         %w[TypeMismatch numeric_field]                =>
                                                          "{type}.{field} expects {expected}, got {offered}",
+        %w[TypeMismatch non_finite_field]             =>
+                                                         "{type}.{field} must be a finite number, got {offered}",
         %w[TypeMismatch pattern_mismatch]             =>
                                                          "{type}.{field} must match {pattern}, got {offered}",
         %w[TypeMismatch arithmetic_amount]            =>