hecks 1.0.2 → 1.2.0

data/lib/hecks/query_specification/common/where_clause.rb

@@ -1,8 +1,21 @@
 module Hecks
   module QuerySpecification
     module Common
-      WhereClause = Struct.new(:field, :op, :value, keyword_init: true) do
-        def to_h = { field: field.to_s, op: op.to_s, value: QuerySpecification.render_value(value) }
+      # `target` — which many-side `include`d aggregate this clause applies
+      # to on a `read_model` with more than one (ADR 0055's own `on:`,
+      # `ReadModelBuilder#where_impl`). Always `nil` for a plain `Query`'s
+      # own `where` (that builder never overrides `where_impl` to accept
+      # `on:`), and `nil` for a `read_model` with a single many-side head,
+      # where naming one is unnecessary. `to_h` omits the key entirely
+      # rather than emitting `target: nil` — the same "absent, not null"
+      # convention `count`/`median_field` already established
+      # (`lib/hecks/bluebook/read_model.rb`), so every read model that
+      # never uses `on:` keeps its existing wire shape byte-identical.
+      WhereClause = Struct.new(:field, :op, :value, :target, keyword_init: true) do
+        def to_h
+          base = { field: field.to_s, op: op.to_s, value: QuerySpecification.render_value(value) }
+          target ? base.merge(target: target.to_s) : base
+        end
       end
     end
   end

data/lib/hecks/query_specification/field_path.rb

@@ -85,8 +85,8 @@ module Hecks
       # or a value object carrying at least one numeric member. A dotted
       # path must land on a numeric primitive itself — the convention does
       # not reach through a named path, it IS the absence of one.
-      def numeric?(attribute, segments, &value_object)
-        leaf = leaf_attribute(attribute, segments, &value_object)
+      def numeric?(attribute, segments, &)
+        leaf = leaf_attribute(attribute, segments, &)
         return false if leaf.nil? || leaf.list? || leaf.reference?
         return true if NUMERIC_PRIMITIVES.include?(leaf.type.to_s)
         return false unless segments.empty?
@@ -98,8 +98,8 @@ module Hecks
       # A dotted path must end on a SCALAR member — landing on a value
       # object would hand SQL a JSON object where the reference
       # interpreter unwraps a hash, and the two would answer differently.
-      def scalar_leaf?(attribute, segments, &value_object)
-        leaf = leaf_attribute(attribute, segments, &value_object)
+      def scalar_leaf?(attribute, segments, &)
+        leaf = leaf_attribute(attribute, segments, &)
         !leaf.nil? && !leaf.list? && !leaf.reference? && SCALAR_PRIMITIVES.include?(leaf.type.to_s)
       end
     end

data/lib/hecks/query_specification/read_model/specification.rb

@@ -3,11 +3,14 @@ require_relative "../common/options"
 module Hecks
   module QuerySpecification
     module ReadModel
+      # The read-model-specific specification: Common::Options' shared
+      # query attributes plus `joins`, the one thing a read model
+      # declares that a plain Query does not.
       class Specification < Common::Options
         attr_reader :joins
 
-        def initialize(joins: [], **options)
-          super(**options)
+        def initialize(joins: [], **)
+          super(**)
           @joins = joins
         end
 

data/lib/hecks/router/namespace_installer.rb

@@ -7,12 +7,19 @@ module Hecks
     # resolution stays in Router; this object only adapts it to constants and
     # method calls.
     class NamespaceInstaller
+      # Returned by the `.options(version:)` method installed on each
+      # namespace module — forwards any command/query verb called on it
+      # to the router, pinned to this specific FQN version rather than
+      # the router's default resolution.
       class OptionsProxy
         def initialize(router:, realm:, domain:, aggregate:, options:)
           unknown = options.keys - [:version]
           raise ArgumentError, "unknown router options: #{unknown.join(', ')}" unless unknown.empty?
 
-          @router, @realm, @domain, @aggregate = router, realm, domain, aggregate
+          @router = router
+          @realm = realm
+          @domain = domain
+          @aggregate = aggregate
           @version = options[:version]&.to_s
         end
 
@@ -103,12 +110,12 @@ module Hecks
 
         target.define_singleton_method(:find) do |id|
           found = dispatcher.registry.repository(domain, ir).find(id)
-          found && Facade::Handle.new(dispatcher: dispatcher, domain: domain, ir: ir, instance: found)
+          found && Facade::Handle.new(dispatcher: dispatcher, domain: domain, aggregate: ir, instance: found)
         end
 
         target.define_singleton_method(:all) do
           dispatcher.registry.repository(domain, ir).all.map do |instance|
-            Facade::Handle.new(dispatcher: dispatcher, domain: domain, ir: ir, instance: instance)
+            Facade::Handle.new(dispatcher: dispatcher, domain: domain, aggregate: ir, instance: instance)
           end
         end
       end
@@ -118,16 +125,17 @@ module Hecks
         current_entries.reject { |entry| entry.fqn.aggregate.nil? }
                        .group_by { |entry| [entry.fqn.aggregate, entry.fqn.verb] }
                        .each do |(aggregate, verb), candidates|
-          shortcut_target(aggregate).define_singleton_method(verb) { |**args|
+          shortcut_target(aggregate).define_singleton_method(verb) do |**args|
             installer.send(:dispatch_short, candidates, **args)
-          }
+          end
         end
       end
 
       def dispatch_short(candidates, **args)
         if candidates.length > 1
           shown = candidates.map { |entry| entry.fqn.to_s }.sort.join(", ")
-          aggregate, verb = candidates.first.fqn.aggregate, candidates.first.fqn.verb
+          aggregate = candidates.first.fqn.aggregate
+          verb = candidates.first.fqn.verb
           raise AmbiguousShortRoute, "#{aggregate}.#{verb} is ambiguous — choose one of: #{shown}"
         end
 
@@ -137,8 +145,10 @@ module Hecks
 
       def shortcut_target(aggregate)
         constant = Object.const_get(aggregate, false) if Object.const_defined?(aggregate, false)
-        raise NameError,
-              "cannot install Bluebook shortcut #{aggregate}: it is not a module" if constant && !constant.is_a?(Module)
+        if constant && !constant.is_a?(Module)
+          raise NameError,
+                "cannot install Bluebook shortcut #{aggregate}: it is not a module"
+        end
 
         constant || Object.const_set(aggregate, Module.new)
       end
@@ -146,8 +156,10 @@ module Hecks
       def namespace_for(realm, domain, aggregate)
         [realm, domain, aggregate].compact.reduce(Object) do |parent, name|
           constant = parent.const_get(name, false) if parent.const_defined?(name, false)
-          raise NameError,
-                "cannot install Bluebook route under #{parent}::#{name}: it is not a module" if constant && !constant.is_a?(Module)
+          if constant && !constant.is_a?(Module)
+            raise NameError,
+                  "cannot install Bluebook route under #{parent}::#{name}: it is not a module"
+          end
 
           constant || parent.const_set(name, Module.new)
         end

data/lib/hecks/runtime/command_interpreter/mutation_applier.rb

@@ -18,17 +18,39 @@ module Hecks
           end
         end
 
-        def apply(instance, aggregate, mutation, args)
+        # A CASE STATEMENT OVER A CLOSED, DECLARED SET — every mutation op
+        # the grammar can emit gets its own branch, including the `else`
+        # backstop for the day a new op reaches this method undeclared (see
+        # its own comment). Splitting each branch into its own method would
+        # not reduce what a reader has to hold at once (each op's own
+        # comment already explains why IT is shaped the way it is) and
+        # would obscure that the set is closed and exhaustive.
+        # rubocop:disable Lint/DuplicateBranch -- :delegate and :corrects
+        # both no-op here, for two unrelated documented reasons (see each
+        # branch's own comment below); merging would blur that distinction.
+        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
+        #
+        # `pre` — THE PRE-DISPATCH STATE (C4.2): every source below reads
+        # it, every target is written to `instance`. A command's effects
+        # are one update set; declaration order carries no meaning, and
+        # build refuses a field written twice (`CommandBuilder#
+        # refuse_duplicate_targets!`).
+        def apply(instance, aggregate, mutation, args, pre = instance)
           case mutation.op
           when :set
-            value = mutation.source.is_a?(StateRef) ? instance[mutation.source.name] : @rules.resolve_source(mutation.source, args)
+            value = if mutation.source.is_a?(StateRef)
+                      pre[mutation.source.name]
+                    else
+                      @rules.resolve_source(mutation.source,
+                                            args)
+                    end
             instance[mutation.target] = Value.for(aggregate, mutation.target, value)
           when :append
-            instance[mutation.target] = appended(instance, aggregate, mutation, args)
+            instance[mutation.target] = appended(pre, aggregate, mutation, args)
           when :increment, :decrement
             amount = @rules.resolve_source(mutation.source, args)
             attribute = aggregate.attribute(mutation.target)
-            current   = instance[mutation.target]
+            current   = pre[mutation.target]
             # Vendored fix, not (yet) upstream hecks (migration plan
             # task 9): see #rewrap_arithmetic_result's own comment below
             # -- `amount` is wrapped ONLY when `current` already is, not
@@ -42,7 +64,7 @@ module Hecks
           # RemoveDependency/DeactivateSprint: "a concurrent Add can
           # never be lost").
           when :remove
-            instance[mutation.target] = removed(instance, aggregate, mutation, args)
+            instance[mutation.target] = removed(pre, aggregate, mutation, args)
           # Vendored addition, not (yet) upstream hecks (migration
           # plan task 4, i106): multiply/clamp, the scale/bound pair
           # alongside increment/decrement's add/subtract pair -- see
@@ -50,7 +72,7 @@ module Hecks
           when :multiply
             amount = @rules.resolve_source(mutation.source, args)
             attribute = aggregate.attribute(mutation.target)
-            current   = instance[mutation.target]
+            current   = pre[mutation.target]
             amount = Value.for_attribute(aggregate, attribute, amount) if attribute && current.is_a?(Value)
             result = @rules.multiply(current, amount, mutation.target)
             instance[mutation.target] = rewrap_arithmetic_result(aggregate, attribute, current, result)
@@ -61,7 +83,7 @@ module Hecks
           # a no-op for an Array (it only special-cases Symbol), so it's
           # read straight.
           when :clamp
-            instance[mutation.target] = @rules.clamp(instance[mutation.target], mutation.source, mutation.target)
+            instance[mutation.target] = @rules.clamp(pre[mutation.target], mutation.source, mutation.target)
           # `delegates_to` — CommandBuilder#delegates_to's own comment gives
           # the full reasoning for storing it as a mutation at all. A REAL
           # no-op here, not a gap: it targets no field on THIS instance —
@@ -94,6 +116,8 @@ module Hecks
             raise Runtime::WiringError, "no mutation applier handles :#{mutation.op} — add one before declaring it"
           end
         end
+        # rubocop:enable Lint/DuplicateBranch
+        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity
 
         # A CALLER-SUPPLIED ARG, FIRST -- an append's own field can also
         # name something the SUBJECT ALREADY KNOWS about itself, falling
@@ -122,21 +146,23 @@ module Hecks
           fields       = mutation.source.transform_values { |source| resolve_append_source(source, instance, args) }
           element_type = aggregate.attribute(mutation.target)&.type
           value_object = aggregate.value_object(element_type)
-          if value_object
-            value_object.attributes.each do |attribute|
-              held = fields[attribute.name]
-              # A SINGLE-FIELD VALUE unwraps to its scalar so it bridges
-              # into the element's own (differently named) wrapper; a
-              # MULTI-FIELD one (a `state(:en_passant_square)` Square
-              # copied off the record) has no scalar to stand in for it
-              # and is handed across whole — `Value.for_attribute` keeps a
-              # value of the element field's own type as it is.
-              fields[attribute.name] = Value.scalar(held) if held.is_a?(Value) && held.to_h.size == 1
-            end
+          value_object&.attributes&.each do |attribute|
+            held = fields[attribute.name]
+            # A SINGLE-FIELD VALUE unwraps to its scalar so it bridges
+            # into the element's own (differently named) wrapper; a
+            # MULTI-FIELD one (a `state(:en_passant_square)` Square
+            # copied off the record) has no scalar to stand in for it
+            # and is handed across whole — `Value.for_attribute` keeps a
+            # value of the element field's own type as it is.
+            fields[attribute.name] = Value.scalar(held) if held.is_a?(Value) && held.to_h.size == 1
           end
-          element = value_object ? Value.build(value_object, fields,
-                                               aggregate) : entity_element(aggregate, element_type, instance[mutation.target],
-                                                                           fields)
+          element = if value_object
+                      Value.build(value_object, fields,
+                                  aggregate)
+                    else
+                      entity_element(aggregate, element_type, instance[mutation.target],
+                                     fields)
+                    end
 
           # FROZEN, like every other value the domain hands back. An
           # appended list used to come back mutable, so a caller could
@@ -215,7 +241,7 @@ module Hecks
           end
           if entity.identified_by && !fields.key?(entity.identified_by)
             attribute = entity.attribute(entity.identified_by)
-            fields[entity.identified_by] = Value.from_identifier(aggregate, attribute, Array(current).size + 1)
+            fields[entity.identified_by] = Value.from_identifier(aggregate, attribute, next_identity(current, entity))
           else
             check_entity_collision(aggregate, entity, current, fields)
           end
@@ -223,6 +249,15 @@ module Hecks
           fields
         end
 
+        # THE MINTED IDENTITY IS ONE PAST THE HIGHEST HELD (C4.5) — not
+        # `size + 1`, which repeats an identity the moment the list has
+        # ever shrunk. One strategy for the language, so the IR declares
+        # none; the Rust generators mint by the same rule.
+        def next_identity(current, entity)
+          held = Array(current).map { |element| Value.scalar(element[entity.identified_by]).to_i }
+          held.max.to_i + 1
+        end
+
         # THE SAME CHECK #hydrate GIVES EVERY CREATING AGGREGATE COMMAND
         # (`repository.find(id)`, above this file in command_interpreter.rb),
         # one level down. Reached only on the two branches #entity_element

data/lib/hecks/runtime/command_interpreter.rb

@@ -47,8 +47,8 @@ module Hecks
       # `result` and `transition`/`old_state` default to nil until the step
       # that sets them runs, same as they were unset locals before that point.
       Context = Struct.new(:domain, :aggregate, :command, :args, :repository, :instance, :transition, :old_state,
-                           :result, :correlation, :route, :plan, :strategy, :persistence_outcome, :delegated_events,
-                           :dry_run, :correction_bindings)
+                           :result, :correlation, :route, :plan, :strategy, :persistence_outcome, :pending_delegation,
+                           :dry_run, :correction_bindings, :outbox_rows)
 
       def initialize(registry, rules:)
         @registry = registry
@@ -82,7 +82,7 @@ module Hecks
           ctx.repository = @registry.repository(domain, aggregate)
           lock_id = Identity.best_effort(aggregate, args, route, reference_key: reference_key(command))
           run_dispatch_order_with_isolation(DISPATCH_ORDER, ctx, lock_key_id: lock_id)
-          [ctx.instance, ctx.result, ctx.plan, ctx.persistence_outcome]
+          [ctx.instance, ctx.result, ctx.plan, ctx.persistence_outcome, ctx.outbox_rows]
         rescue StaleWrite
           attempt += 1
           retry if attempt < MAX_STALE_WRITE_RETRIES
@@ -116,7 +116,7 @@ module Hecks
         # `ctx.repository` is resolved once, in `#call`, before the
         # isolation decision (lock vs. CAS+retry) — not here any more.
         ctx.strategy = ctx.plan.strategy_for(capabilities: ctx.repository.capabilities)
-        ctx.instance = step(:hydrate) {
+        ctx.instance = step(:hydrate) do
           if ctx.plan.complete_state? && ctx.plan.state_independent?
             hydrate_complete_state(ctx.repository, ctx.aggregate, ctx.command, ctx.args, ctx.route, ctx.strategy)
           elsif ctx.plan.complete_state?
@@ -126,11 +126,11 @@ module Hecks
           else
             hydrate_existing(ctx.repository, ctx.aggregate, ctx.command, ctx.args, ctx.route)
           end
-        }
+        end
       end
 
       def step_enforce_givens(ctx)
-        step(:enforce_givens) {
+        step(:enforce_givens) do
           # STRUCTURAL, before the declared givens — the same ordering
           # NotFound/AlreadyExists already get at hydration: "does the
           # fact this command's corrects names even exist" is not a
@@ -142,7 +142,7 @@ module Hecks
           ctx.correction_bindings = @rules.enforce_correction_target(ctx.instance, ctx.aggregate, ctx.command, domain: ctx.domain)
           @rules.enforce_givens(ctx.instance, ctx.command, ctx.args, domain: ctx.domain,
                                 declaring: ctx.aggregate, parent: ctx.instance, correction: ctx.correction_bindings)
-        }
+        end
       end
 
       def step_admissible_transition(ctx)
@@ -161,11 +161,17 @@ module Hecks
         # arithmetic via Value#with, append builds a new array), never
         # edit a held value in place.
         ctx.old_state = ctx.instance.state.dup unless ctx.command.ensures.empty?
-        step(:apply_mutations) {
-          ctx.command.mutations.each { |mutation|
-            apply(ctx.instance, ctx.aggregate, mutation, ctx.args)
-          }
-        }
+        step(:apply_mutations) do
+          # ONE UPDATE SET OVER THE PRE-DISPATCH STATE (C4.2, docs/
+          # semantics/bluebook-semantics.md): every effect's sources read
+          # `pre` — the state as it was before this command — and its
+          # target is written to the candidate; declaration order carries
+          # no meaning, and build refuses a field written twice.
+          pre = ctx.instance.state.dup
+          ctx.command.mutations.each do |mutation|
+            apply(ctx.instance, ctx.aggregate, mutation, ctx.args, pre)
+          end
+        end
       end
 
       def step_advance_lifecycle(ctx)
@@ -188,11 +194,21 @@ module Hecks
       # `step_locate_element`/`step_apply_mutations` mutate their OWN
       # freshly-loaded copy — the only difference is WHICH already-in-
       # memory record gets handed in.
+      #
+      # Reimplements the entity command pipeline's own order (givens,
+      # transition, mutations, ensures, emit) inline, deliberately — see
+      # the comment above on why this must run strictly between this
+      # command's own mutations and its ensures/invariants/save. Splitting
+      # it would scatter that exact ordering across method boundaries and
+      # force threading element/view/transition/old_element/settled
+      # through as parameters — the `with:` bug documented just below is
+      # exactly the kind of ordering/plumbing mistake that shape invites.
+      # rubocop:disable-next Metrics/AbcSize
       def step_delegate_to_entity(ctx)
         delegation = ctx.command.mutations.find { |mutation| mutation.op == :delegate }
         return unless delegation
 
-        step(:delegate_to_entity) {
+        step(:delegate_to_entity) do
           entity_name, _dot, command_name = delegation.target.to_s.rpartition(".")
           entity = ctx.aggregate.entities.find { |e| e.hecks_name == entity_name } ||
                    raise(WiringError, "#{ctx.command.hecks_name} delegates_to #{entity_name}." \
@@ -227,23 +243,32 @@ module Hecks
           transition = @rules.admissible_transition(entity, target_command, view)
 
           old_element = target_command.ensures.empty? ? nil : element.dup
-          target_command.mutations.each { |mutation|
-            EntityElement.apply_to_element(@rules, ctx.aggregate, entity, element, mutation, target_args)
-          }
+          pre = element.dup # C4.2 — the update set reads the element as it was
+          target_command.mutations.each do |mutation|
+            EntityElement.apply_to_element(@rules, ctx.aggregate, entity, element, mutation, target_args, pre)
+          end
           element[entity.lifecycle.field] = transition.target if transition
 
           settled = Instance.new(aggregate: entity, id: view.id, state: element)
           @rules.enforce_ensures(settled, target_command, target_args, old: old_element, domain: ctx.domain, parent: ctx.instance)
 
-          ctx.delegated_events = @rules.emit(target_command, ctx.domain, ctx.aggregate, ctx.instance, target_args, ctx.repository)
-        }
+          # NOT emitted here — C7.2 (docs/semantics/bluebook-semantics.md):
+          # a refused command records nothing, and the parent's own
+          # `ensures`/`enforce_invariants`/`save` steps still run after
+          # this one. The target's emission is parked and performed by
+          # `step_emit`, after the parent committed — where every other
+          # command's events are emitted too. (Before this, the entity
+          # leg's events were on the event log and in the adapter before
+          # the parent could refuse.)
+          ctx.pending_delegation = [target_command, target_args]
+        end
       end
 
       def step_enforce_ensures(ctx)
-        step(:enforce_ensures) {
+        step(:enforce_ensures) do
           @rules.enforce_ensures(ctx.instance, ctx.command, ctx.args, old: ctx.old_state,
                                  domain: ctx.domain, parent: ctx.instance, correction: ctx.correction_bindings || {})
-        }
+        end
       end
 
       def step_enforce_invariants(ctx)
@@ -261,41 +286,49 @@ module Hecks
         step(:save) do
           @rules.resolve_state_references(ctx.domain, ctx.aggregate, ctx.instance.state)
           seed_projected_fields(ctx)
-          ctx.persistence_outcome = if ctx.strategy == DependencyPlanning::ATOMIC_PUT
-                                      # A SECOND CREATION IS NOT A FRESH ONE — see
-                                      # hydrate_complete_state's own comment; the
-                                      # same refusal, on the same terms, for the
-                                      # complete-state path. `insert_only:` asks the
-                                      # ADAPTER to decide and refuse ATOMICALLY
-                                      # (never writing a `creates?` command over an
-                                      # identity that already names a record) rather
-                                      # than this interpreter reading the record
-                                      # first to check — a `repository.find` before
-                                      # every atomic_put would be exactly the read
-                                      # this strategy exists to skip.
-                                      ctx.repository.atomic_put(ctx.instance, insert_only: ctx.command.creates?)
-                                    else
-                                      # `expected_version:` is `ctx.instance.version` — nil for a
-                                      # brand-new record (never read from storage) or when the
-                                      # repository isn't CAS-capable, either of which falls straight
-                                      # through to a plain, unconditional save inside `AppendOnly#save`.
-                                      ctx.repository.save(ctx.instance, expected_version: ctx.instance.version)
-                                    end
-          if ctx.persistence_outcome.status == :conflicted
-            raise(AlreadyExists, RefusalWording.render("AlreadyExists", "creating_duplicate",
-                                                       command: ctx.command.hecks_name, aggregate: ctx.aggregate.hecks_name,
-                                                       identity: identity_reading(ctx.aggregate),
-                                                       offered: Rendering.describe(ctx.instance.id)))
-          elsif ctx.persistence_outcome.status == :stale
-            # NOT a `RefusalWording.render` call — this is not a declared
-            # vocabulary refusal, just a plain, informative message. See
-            # `Runtime::StaleWrite`'s own comment: caught by `#call`'s
-            # retry loop, re-raised only once retries are exhausted.
-            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
+          ctx.persistence_outcome = persist_instance(ctx)
+          raise_for_persistence_outcome!(ctx)
+        end
+      end
+
+      def persist_instance(ctx)
+        if ctx.strategy == DependencyPlanning::ATOMIC_PUT
+          # A SECOND CREATION IS NOT A FRESH ONE — see
+          # hydrate_complete_state's own comment; the
+          # same refusal, on the same terms, for the
+          # complete-state path. `insert_only:` asks the
+          # ADAPTER to decide and refuse ATOMICALLY
+          # (never writing a `creates?` command over an
+          # identity that already names a record) rather
+          # than this interpreter reading the record
+          # first to check — a `repository.find` before
+          # every atomic_put would be exactly the read
+          # this strategy exists to skip.
+          ctx.repository.atomic_put(ctx.instance, insert_only: ctx.command.creates?)
+        else
+          # `expected_version:` is `ctx.instance.version` — nil for a
+          # brand-new record (never read from storage) or when the
+          # repository isn't CAS-capable, either of which falls straight
+          # through to a plain, unconditional save inside `AppendOnly#save`.
+          ctx.repository.save(ctx.instance, expected_version: ctx.instance.version)
+        end
+      end
+
+      def raise_for_persistence_outcome!(ctx)
+        if ctx.persistence_outcome.status == :conflicted
+          raise(AlreadyExists, RefusalWording.render("AlreadyExists", "creating_duplicate",
+                                                     command: ctx.command.hecks_name, aggregate: ctx.aggregate.hecks_name,
+                                                     identity: identity_reading(ctx.aggregate),
+                                                     offered: Rendering.describe(ctx.instance.id)))
+        elsif ctx.persistence_outcome.status == :stale
+          # NOT a `RefusalWording.render` call — this is not a declared
+          # vocabulary refusal, just a plain, informative message. See
+          # `Runtime::StaleWrite`'s own comment: caught by `#call`'s
+          # retry loop, re-raised only once retries are exhausted.
+          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
 
@@ -334,9 +367,10 @@ module Hecks
 
       # A DELEGATING COMMAND EMITS NOTHING OF ITS OWN (`CommandBuilder#build`'s
       # own guard refuses declaring `emits` alongside `delegates_to`) — its
-      # result IS whatever `step_delegate_to_entity` already collected from
-      # the target entity command's own `emits`, not a second, empty call
-      # into `@rules.emit` for a command with no announced events at all.
+      # result IS the target entity command's own `emits`, parked by
+      # `step_delegate_to_entity` and emitted HERE, after save (C7.2), not
+      # a second, empty call into `@rules.emit` for a command with no
+      # announced events at all.
       #
       # `dry_run:` skips this too, same reasoning as `step_save` — nothing
       # was committed, so `ctx.result` stays nil and `Dispatcher#dry_run?`
@@ -344,15 +378,20 @@ module Hecks
       def step_emit(ctx)
         return if ctx.dry_run
 
-        ctx.result = step(:emit) {
-          # `ctx.delegated_events` is only ever set by `step_delegate_to_entity`,
-          # and only when this command carries a `:delegate` mutation — an
-          # empty Array (the target genuinely emitted nothing) is still
-          # truthy in Ruby, so this reads correctly either way.
-          next ctx.delegated_events if ctx.delegated_events
+        ctx.result = step(:emit) do
+          # `ctx.pending_delegation` is only ever set by
+          # `step_delegate_to_entity`, and only when this command carries a
+          # `:delegate` mutation.
+          if ctx.pending_delegation
+            target_command, target_args = ctx.pending_delegation
+            # The same dispatch, so the same correlation — a saga-driven
+            # door's events used to lose their stamp here.
+            next @rules.emit(target_command, ctx.domain, ctx.aggregate, ctx.instance, target_args, ctx.repository,
+                             ctx.correlation)
+          end
 
           @rules.emit(ctx.command, ctx.domain, ctx.aggregate, ctx.instance, ctx.args, ctx.repository, ctx.correlation)
-        }
+        end
       end
 
       def hydrate_existing(repository, aggregate, command, args, route = nil)

data/lib/hecks/runtime/command_rules/admissibility.rb

@@ -143,9 +143,12 @@ module Hecks
           attrs = attrs.merge(parent: parent.state) if parent
           attrs = attrs.merge(correction) unless correction.empty?
           command.givens.each do |given|
-            next if Bluebook::Expression::Evaluator.call(given.canonical, state, attrs)
+            next if Bluebook::Expression::Evaluator.call_rule(given, state, attrs)
 
-            raise GivenNotMet, "#{command.hecks_name} refused — #{given.description}"
+            raise GivenNotMet.new(
+              "#{command.hecks_name} refused — #{given.description}",
+              detail: Bluebook::Expression::Evaluator.comparison_detail(given.canonical, state, attrs)
+            )
           end
 
           enforce_lifecycle_guard(declaring, command, subject) if declaring
@@ -177,6 +180,16 @@ module Hecks
         # one, made deliberately: `as:` reads as "the instance being
         # corrected," which is naturally the latest fact on record, not
         # an arbitrary one.
+        # C9.2 (docs/semantics/bluebook-semantics.md) — a correction target
+        # is judged against the record's DURABLE history: the events the
+        # aggregate's own store recorded (`AppendOnly#events`), which
+        # survive a restart the way the Rust kernel's persisted
+        # `emitted_<event>` flag does. The in-process log is the fallback
+        # only for an adapter that records no readable history.
+        def correction_history(domain, aggregate)
+          @registry.repository(domain, aggregate).events || @registry.event_log
+        end
+
         def enforce_correction_target(instance, aggregate, command, domain:)
           bindings = {}
           command.mutations.each do |mutation|
@@ -184,8 +197,8 @@ module Hecks
 
             event_key  = "#{domain}::#{aggregate.hecks_name}"
             event_name = mutation.target.to_s
-            corrected = @registry.event_log.reverse.find do |event|
-              event.name == event_name && event.aggregate == event_key && event.id == instance.id
+            corrected = correction_history(domain, aggregate).reverse.find do |event|
+              event.name == event_name && event.aggregate == event_key && event.id.to_s == instance.id.to_s
             end
 
             unless corrected
@@ -257,12 +270,17 @@ module Hecks
           # one) wins right alongside it — a settled-record ensures can
           # reference the correction target exactly as freely as a
           # pre-mutation given already can.
-          attrs = args.merge(dereference(domain, command, args))
+          # C2.3 (docs/semantics/bluebook-semantics.md) — an ensures reads
+          # the SETTLED STATE first: an argument that shares a field's
+          # name does not shadow the candidate here (it does in a given,
+          # C2.2), so `sets :note` + `ensures { note == ... }` judges what
+          # landed, and `old.<field>` remains the pre-state.
+          attrs = args.reject { |name, _| subject.key?(name) }.merge(dereference(domain, command, args))
           attrs = attrs.merge(parent: parent.state) if parent
           attrs = attrs.merge(correction) unless correction.empty?
           attrs = attrs.merge(old: old)
           command.ensures.each do |rule|
-            next if Bluebook::Expression::Evaluator.call(rule.canonical, state, attrs)
+            next if Bluebook::Expression::Evaluator.call_rule(rule, state, attrs)
 
             raise EnsuresNotMet, "#{command.hecks_name} refused — #{rule.description}"
           end
@@ -291,7 +309,7 @@ module Hecks
           state = GuardState.new(subject)
           attrs = {}
           aggregate.invariants.each do |invariant|
-            next if Bluebook::Expression::Evaluator.call(invariant.canonical, state, attrs)
+            next if Bluebook::Expression::Evaluator.call_rule(invariant, state, attrs)
 
             raise InvariantViolation, "#{aggregate.hecks_name} refused — #{invariant.description}"
           end
@@ -336,7 +354,7 @@ module Hecks
               attrs = { parent: owner_instance.state }
 
               entity.invariants.each do |invariant|
-                next if Bluebook::Expression::Evaluator.call(invariant.canonical, element_state, attrs)
+                next if Bluebook::Expression::Evaluator.call_rule(invariant, element_state, attrs)
 
                 raise InvariantViolation, "#{entity.hecks_name} refused — #{invariant.description}"
               end