hecks 1.0.2 → 1.1.0

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

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

@@ -111,9 +111,7 @@ module Hecks
           op = sign.positive? ? "increment" : "decrement"
           current ||= 0
 
-          if current.is_a?(Value) && amount.is_a?(Value)
-            return arithmetic_value_object(current, amount, target, sign, op)
-          end
+          return arithmetic_value_object(current, amount, target, sign, op) if current.is_a?(Value) && amount.is_a?(Value)
 
           # `current` genuinely absent (no declared default, never set) and
           # `amount` arrives VO-wrapped — a real command argument typed the
@@ -145,10 +143,30 @@ module Hecks
                                                       op: op, target: target, offered: Rendering.describe(current))
           end
 
-          current + (sign * amount)
+          bounded(current + (sign * amount), op, current, sign * amount, sign.positive? ? "+" : "-")
+        end
+
+        # C3.3/C3.4 — an effect's arithmetic is held to the same value
+        # model an expression's is: Integer is signed 64-bit, Float is
+        # finite. A result outside that is an evaluation FAULT (never a
+        # refusal, C8.3), worded as the Rust kernel's own generated
+        # `checked_add`/`checked_sub`/`checked_mul` word it.
+        INT64_RANGE = (-(2**63))..((2**63) - 1)
+
+        def bounded(result, oper, lhs, rhs, symbol)
+          if result.is_a?(Integer)
+            return result if INT64_RANGE.cover?(result)
+
+            raise Bluebook::Expression::EvaluationError,
+                  "#{oper} overflowed: #{lhs} #{symbol} #{rhs.abs} does not fit in a 64-bit integer"
+          end
+          return result unless result.is_a?(Float) && !result.finite?
+
+          raise Bluebook::Expression::EvaluationError,
+                "#{oper} overflowed: #{lhs} #{symbol} #{rhs.abs} is not a finite number"
         end
 
-        def arithmetic_value_object(current, amount, target, sign, op)
+        def arithmetic_value_object(current, amount, target, sign, oper)
           current_fields = current.to_h
           amount_fields  = amount.to_h
           # Widened from Integer to Numeric -- see #arithmetic's own
@@ -162,11 +180,12 @@ module Hecks
           end
           unless shared_numeric.size == 1
             raise TypeMismatch,
-                  RefusalWording.render("TypeMismatch", "arithmetic_shared_field", op: op, target: target)
+                  RefusalWording.render("TypeMismatch", "arithmetic_shared_field", op: oper, target: target)
           end
 
           field = shared_numeric.first
-          current.with(field, current[field] + (sign * amount[field]))
+          current.with(field, bounded(current[field] + (sign * amount[field]), oper,
+                                      current[field], amount[field], sign.positive? ? "+" : "-"))
         end
 
         # Not a bare `.find(...)&.sign || -1` — that silently answered
@@ -180,9 +199,9 @@ module Hecks
         # raise is not a real runtime path yet — it is the same
         # backstop one level down, in case a future caller reaches
         # #sign_of directly for an op that was never meant to have one.
-        def sign_of(op)
-          MUTATION_OPS.find { |candidate| candidate.name == op.to_s }&.sign ||
-            raise(WiringError, "no sign declared for mutation op #{op.inspect} — add one before calling #sign_of")
+        def sign_of(oper)
+          MUTATION_OPS.find { |candidate| candidate.name == oper.to_s }&.sign ||
+            raise(WiringError, "no sign declared for mutation op #{oper.inspect} — add one before calling #sign_of")
         end
 
         # Vendored addition, not (yet) upstream hecks (migration plan
@@ -196,7 +215,9 @@ module Hecks
           current ||= 0
 
           if current.is_a?(Value) && amount.is_a?(Value)
-            return combine_value_object(current, amount, target, "multiply") { |c, a| c * a }
+            return combine_value_object(current, amount, target, "multiply") do |c, a|
+              bounded(c * a, "multiply", c, a, "*")
+            end
           end
 
           # Same absent-`current`, VO-wrapped-`amount` gap as `#arithmetic`
@@ -209,7 +230,7 @@ module Hecks
                                                       offered: Rendering.describe(current.is_a?(Numeric) ? amount : current))
           end
 
-          current * amount
+          bounded(current * amount, "multiply", current, amount, "*")
         end
 
         # Vendored addition, not (yet) upstream hecks (migration plan
@@ -270,7 +291,7 @@ module Hecks
           fields[numeric_fields.first]
         end
 
-        def combine_value_object(current, amount, target, op)
+        def combine_value_object(current, amount, target, oper)
           current_fields = current.to_h
           amount_fields  = amount.to_h
           shared_numeric = current_fields.keys.select do |field|
@@ -278,7 +299,7 @@ module Hecks
           end
           unless shared_numeric.size == 1
             raise TypeMismatch,
-                  RefusalWording.render("TypeMismatch", "arithmetic_shared_field", op: op, target: target)
+                  RefusalWording.render("TypeMismatch", "arithmetic_shared_field", op: oper, target: target)
           end
 
           field = shared_numeric.first