hecks 0.2.0 → 1.0.0

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

@@ -0,0 +1,357 @@
+require_relative "../../bluebook/expression/evaluator"
+require_relative "../../rendering"
+require_relative "../errors"
+require_relative "../refusal_wording"
+require_relative "../value"
+require_relative "../instance"
+
+module Hecks
+  module Runtime
+    class CommandRules
+      # Whether a command may run at all: its declared givens, and the
+      # lifecycle transition it asks for.
+      module Admissibility
+        # WRAPS `subject` so a guard can read a DECLARED-but-storage-absent
+        # optional attribute as nil, not "cannot resolve." `Instance
+        # #hydrate_with_defaults` deliberately leaves one absent rather
+        # than nil-filled — "an attribute with no default stays absent,
+        # exactly as stored," that file's own comment — which is right
+        # for storage fidelity but wrong for a `given`/`ensures` reading
+        # an optional field a record predates (measured, not assumed: a
+        # real Item.Promote crashed on `!promoted` against a record from
+        # before `promoted` existed). Defensive on purpose — a `subject`
+        # with no `.aggregate` (an entity's own view/settled wrapper,
+        # entity_interpreter.rb's own callers) just degrades to today's
+        # exact behavior, zero risk to a path this bug was never measured
+        # against.
+        #
+        # NIL IS NOT THE ONLY OUTCOME, though. The Item.Promote fix above
+        # covered an OPTIONAL field — the honest case, where absence is
+        # exactly what optional means. It also, as a side effect, let a
+        # NON-optional field predating a record read nil the same way,
+        # which is the `ne:`/array-`in:` bug class applied to rule
+        # evaluation: a predicate silently answers against a value nobody
+        # ever wrote (ADR 0025, "Added attributes and absence"). `[]`
+        # below narrows the nil-read back to what it was built for —
+        # optional stays nil, non-optional raises a named refusal
+        # identifying the field, so a rule that reads it fails loud
+        # instead of quietly wrong.
+        class GuardState
+          def initialize(instance)
+            @instance = instance
+            @declared = instance.respond_to?(:aggregate) ? instance.aggregate.attributes.to_h { |a| [a.name, a] } : {}
+            # S12, ADR 0025 — a SEPARATE index, the same reason
+            # `Aggregate#projected_fields` is a separate IR collection
+            # rather than folded into `attributes` (see that field's
+            # own comment): a projected field's absence means
+            # something different from an ordinary attribute's, so it
+            # needs its own refusal below, not `AttributeAbsent`'s.
+            # `projects` is AGGREGATE-scoped only — an entity's own
+            # `instance.aggregate` answers the ENTITY construct here
+            # (EntityInterpreter's own subject), which declares no
+            # `projected_fields` of its own, hence the extra guard
+            # `@declared` above does not need.
+            owner = instance.aggregate if instance.respond_to?(:aggregate)
+            @projected = owner.respond_to?(:projected_fields) ? owner.projected_fields.to_h { |f| [f.name, f] } : {}
+          end
+
+          def key?(name) = @declared.key?(name.to_sym) || @projected.key?(name.to_sym) || @instance.key?(name)
+
+          def [](name)
+            return @instance[name] if @instance.key?(name)
+
+            projected = @projected[name.to_sym]
+            return raise_projection_absent(projected) if projected
+
+            attribute = @declared[name.to_sym]
+            return nil if attribute.nil? || attribute.optional?
+
+            raise AttributeAbsent,
+                  RefusalWording.render("AttributeAbsent", "absent_read",
+                                        aggregate: @instance.aggregate.hecks_name, field: name)
+          end
+
+          private
+
+          def raise_projection_absent(projected)
+            raise ProjectionAbsent,
+                  RefusalWording.render("ProjectionAbsent", "absent_read",
+                                        aggregate: @instance.aggregate.hecks_name, field: projected.name,
+                                        reference: projected.reference, remote_field: projected.remote_field)
+          end
+        end
+        private_constant :GuardState
+
+        # `domain:` is only needed to dereference a reference-typed field
+        # (`customer.status`) — see References#dereference. `owner` is the
+        # declaring aggregate/entity when `subject` carries one (an
+        # entity's pre-mutation `view` does, same as an aggregate's
+        # `Instance`); a `subject` with no `.aggregate` just hydrates
+        # nothing from state, same as GuardState degrades above.
+        #
+        # MERGE ORDER MATTERS, and it is NOT "args always win": an
+        # unaliased command-level reference dereferences under a
+        # different name than the argument holds (`account_id` the arg,
+        # `account` the hydrated key — no collision, order is moot). An
+        # ALIASED one (`reference_to Customer, as: :customer`) hydrates
+        # under the SAME name the argument itself holds — `customer` is
+        # both the raw id an arg puts there and the key `customer.status`
+        # expects to dig into. If `args` merged last, the raw id (a
+        # String) would win and `.status` on a String is where a fuzzer
+        # found this — TypeError, not a refusal. Command-level
+        # dereferencing is the one thing that is SUPPOSED to override
+        # its own source argument for exactly this reason; args still
+        # wins over stored OWNER state (unchanged from before this fix).
+        # `parent:` is an entity command's OWN parent aggregate record
+        # (EntityInterpreter's `ctx.instance` — "the PARENT aggregate
+        # record", its own doc comment) — the entity's containment, not a
+        # declared reference attribute, so it doesn't come from
+        # `dereference`'s attribute scan the way `owner`'s do. Hydrated
+        # the same shape regardless: the parent's own state, MERGED so
+        # the dereferenced hash wins over the raw reference it replaces
+        # (ADR 0025 dropped the `_id` suffix that used to keep the two
+        # apart by name, so `parent.state.merge(dereference(...))` is
+        # now load-bearing, not redundant) — plus ITS OWN references
+        # dereferenced one level in, so `parent.customer.status` (a
+        # parent aggregate reaching ITS OWN customer) resolves the same
+        # way `account.customer.status` does for a command-level reference.
+        # nil for an aggregate command — CommandInterpreter never passes it.
+        def enforce_givens(subject, command, args, domain:, declaring: nil, parent: nil)
+          state = GuardState.new(subject)
+          # A RULE MAY ONLY READ WITHIN ITS OWN AGGREGATE BOUNDARY (S12,
+          # ADR 0025) — `subject`'s own STORED references are no longer
+          # dereferenced here at all. What used to be a live query against
+          # another aggregate's own repository is now just `subject`'s own
+          # state: a `projects :customer_status, from: :"customer.status"`
+          # field is a REGULAR stored attribute, already present in
+          # `subject`/`state` with no hydration step needed. `dereference`
+          # is still called on `command`/`args`, below — that is a
+          # DIFFERENT case the ADR explicitly keeps in bounds ("its command
+          # arguments"): a reference-typed ARGUMENT this dispatch was just
+          # handed (`Dispute`'s own `disputed_by`, say) has nothing stored
+          # to project yet, so resolving it here, once, synchronously with
+          # THIS command's own admission, is not the live-query-against-
+          # another-aggregate's-stored-state pattern the boundary rule
+          # forbids.
+          attrs = args.merge(dereference(domain, command, args))
+          attrs = attrs.merge(parent: parent.state) if parent
+          command.givens.each do |given|
+            next if Bluebook::Expression::Evaluator.call(given.canonical, state, attrs)
+
+            raise GivenNotMet, "#{command.hecks_name} refused — #{given.description}"
+          end
+
+          enforce_lifecycle_guard(declaring, command, subject) if declaring
+        end
+
+        # `corrects` — CommandBuilder#corrects_impl's own comment. NOT
+        # expressible as an ordinary `given`: "has this exact record
+        # already emitted this exact event" is not a predicate over the
+        # record's OWN fields, it is a fact about the event log, so it is
+        # raised structurally here, the same way NotFound/AlreadyExists
+        # are, rather than through the expression evaluator. The build-
+        # time half — does ANYTHING in this aggregate ever emit the named
+        # event at all — is `AggregateBuilder#seal_correction_targets`;
+        # this is the dispatch-time half — has THIS record actually done
+        # so yet.
+        def enforce_correction_target(instance, aggregate, command, domain:)
+          command.mutations.each do |mutation|
+            next unless mutation.op == :corrects
+
+            event_key  = "#{domain}::#{aggregate.hecks_name}"
+            event_name = mutation.target.to_s
+            next if @registry.event_log.any? do |event|
+              event.name == event_name && event.aggregate == event_key && event.id == instance.id
+            end
+
+            raise NothingToCorrect,
+                  "#{command.hecks_name} refused — corrects #{event_name}, but " \
+                  "#{event_key} ##{instance.id} has never emitted it"
+          end
+        end
+
+        # LIFECYCLE STATE AS A COMMAND GUARD (S10, ADR 0025) — `command
+        # "Debit", from: "open"` checked here, folded into the SAME
+        # dispatch step `given` already runs at (both are preconditions,
+        # evaluated before any mutation) rather than earning its own
+        # DISPATCH_ORDER entry. A GUARD, never a transition: it names no
+        # target state and `step_advance_lifecycle` never sees it — see
+        # `admissible_transition`, right below, for the transition this
+        # is deliberately NOT reusing (its own `StateTransition#target`
+        # is required, and a guard-only command has none to give it).
+        def enforce_lifecycle_guard(declaring, command, subject)
+          return unless command.from
+
+          lifecycle = declaring.lifecycle
+          current   = Value.scalar(subject[lifecycle.field]).to_s
+          return if Array(command.from).include?(current)
+
+          # ROUTED THROUGH RefusalWording's OWN "transition_blocked"
+          # TEMPLATE — the same one #admissible_transition, right below,
+          # already raises LifecycleRefused through for the same
+          # refusal class. This used to hand-roll its own wording
+          # inline ("...only runs from..." vs. the template's "...moves
+          # it only from...") — two shapes for one refusal kind, so
+          # anything string-matching a LifecycleRefused message (a
+          # property, a spec, a caller) had to know both existed rather
+          # than one.
+          raise LifecycleRefused,
+                RefusalWording.render("LifecycleRefused", "transition_blocked",
+                                      command: command.hecks_name, field: lifecycle.field,
+                                      current: Rendering.describe(current),
+                                      allowed: Array(command.from).map(&:inspect).join(" or "))
+        end
+
+        # The far side of the contract: evaluated against the SETTLED record
+        # — after mutations and the lifecycle move, before anything persists
+        # — with `old` carrying the state as the givens saw it. Injected into
+        # the attrs at evaluation time only; the payload gate never sees it.
+        #
+        # `old` — and every dispatch ARGUMENT — wins over a same-named STATE
+        # field in expression scope (Resolver#fetch checks attrs first). An
+        # ensures naming a field the command also takes as an argument (or,
+        # on an entity, a field that doubles as the addressing argument
+        # element_of reads) will read the ARGUMENT, not the settled value.
+        # Not new to ensures — `given` lives under the same rule — but an
+        # ensures is more likely to collide, since it typically re-reads a
+        # field the command just took in to mutate it.
+        def enforce_ensures(subject, command, args, old:, domain:, parent: nil)
+          state = GuardState.new(subject)
+          # S12, ADR 0025 — same boundary reasoning as enforce_givens
+          # above: `subject`'s own stored references are no longer
+          # dereferenced here; a `projects`-maintained field is already
+          # part of `state`. `command`/`args` still dereferences — a
+          # fresh reference-typed ARGUMENT stays in bounds.
+          # `old` still wins over everything, unchanged.
+          attrs = args.merge(dereference(domain, command, args))
+          attrs = attrs.merge(parent: parent.state) if parent
+          attrs = attrs.merge(old: old)
+          command.ensures.each do |rule|
+            next if Bluebook::Expression::Evaluator.call(rule.canonical, state, attrs)
+
+            raise EnsuresNotMet, "#{command.hecks_name} refused — #{rule.description}"
+          end
+        end
+
+        # THE AGGREGATE BOUNDARY, checked after every command, before
+        # save (S10, ADR 0025 — "Rules") — the same point `enforce_
+        # ensures` already checks at, and for the same reason: an
+        # invariant is a claim about the SETTLED record, not the
+        # command that produced it, so it reads no `args`/`old` at all,
+        # only the record's own state. `subject` here is
+        # always the AGGREGATE's own instance — `CommandInterpreter`
+        # passes its own `ctx.instance`, and `EntityInterpreter` passes
+        # the PARENT record (`ctx.instance`, not the element), since an
+        # entity mutation changes data inside the SAME aggregate
+        # boundary the invariant guards; there is no separate "entity
+        # invariant" to check the piece's own view against.
+        #
+        # NO `dereference` (S12, ADR 0025) — an invariant may only read
+        # `subject`'s own boundary, same rule `enforce_givens`/
+        # `enforce_ensures` now hold to. No invariant in the corpus has
+        # ever read across a `reference_to` (verified before this
+        # change), so this is not a migration, just closing the same
+        # capability off here that was already unused.
+        def enforce_invariants(subject, aggregate, domain:)
+          state = GuardState.new(subject)
+          attrs = {}
+          aggregate.invariants.each do |invariant|
+            next if Bluebook::Expression::Evaluator.call(invariant.canonical, state, attrs)
+
+            raise InvariantViolation, "#{aggregate.hecks_name} refused — #{invariant.description}"
+          end
+
+          check_entity_invariants(aggregate, subject, domain: domain)
+        end
+
+        # A PIECE'S OWN SHAPE RULE, checked against EVERY INSTANCE the
+        # aggregate holds — not a separate boundary from the aggregate's
+        # own invariants just above (same two checkpoints: after every
+        # mutation, before save), just a WIDER one: the aggregate's own
+        # consistency includes each of its pieces individually looking
+        # right, the same way `ValueObject#invariants` already checks
+        # each of ITS OWN instances one construct up. RECURSES into
+        # nested pieces (S17, ADR 0026 — Dispatch inside Handler) the
+        # same way `check_entity_invariants`'s own caller recurses
+        # nowhere else needs to, since a piece's `entities` are already
+        # exactly as reachable as an aggregate's.
+        #
+        # `list_attr` reuses the EXACT lookup `EntityInterpreter#
+        # element_of` already makes to locate a SINGLE addressed
+        # element by identity — this reads every element instead, but
+        # the "which field on the owner holds this piece's own
+        # instances" question is the identical one. A piece declaring
+        # invariants that nothing on its owner actually holds (no
+        # matching list attribute) is a static-analysis gap for a
+        # future gate, not a runtime concern here — `next` past it
+        # rather than raising mid-enforcement for an unrelated command.
+        def check_entity_invariants(owner_construct, owner_instance, domain:)
+          owner_construct.entities.each do |entity|
+            next if entity.invariants.empty?
+
+            list_attr = owner_construct.attributes.find { |a| a.list? && a.type.to_s == entity.hecks_name }
+            next unless list_attr
+
+            Array(owner_instance[list_attr.name]).each do |element|
+              wrapped = Instance.new(aggregate: entity, id: nil, state: element)
+              element_state = GuardState.new(wrapped)
+              # NO `dereference` (S12, ADR 0025) — same boundary rule as
+              # enforce_invariants above; `parent` (the owner's own
+              # state, projected fields included) stays readable.
+              attrs = { parent: owner_instance.state }
+
+              entity.invariants.each do |invariant|
+                next if Bluebook::Expression::Evaluator.call(invariant.canonical, element_state, attrs)
+
+                raise InvariantViolation, "#{entity.hecks_name} refused — #{invariant.description}"
+              end
+
+              check_entity_invariants(entity, wrapped, domain: domain)
+            end
+          end
+        end
+
+        def admissible_transition(declaring, command, subject)
+          lifecycle = declaring.lifecycle
+          return nil unless lifecycle
+
+          candidates = lifecycle.transitions_for(command.hecks_name)
+          return nil if candidates.empty?
+
+          # `Value.scalar` unwrap -- vendored addition, not (yet)
+          # upstream hecks (migration plan task 9): a VO-typed
+          # lifecycle field (the norm, not the exception, per this
+          # corpus's own no-primitive-envy convention) holds a real
+          # `Runtime::Value` here, and a bare `.to_s` on that hit Ruby's
+          # default `Object#to_s` instead of unwrapping the inner
+          # scalar first -- `current` came back as a raw object-pointer
+          # string (`"#<Hecks::Runtime::Value:0x...>"`) that could
+          # never match any declared `from` state, so EVERY transition
+          # on a VO-typed lifecycle field refused unconditionally, and
+          # when it refused the message leaked the pointer too.
+          # Confirmed live via `Plan::Task.Complete` (status defaults to
+          # `TaskStatus`, a single-field VO), not inferred. Reuses
+          # `Value.scalar` -- this file's own third candidate for "how
+          # to unwrap a Value/Hash-shaped field," already built and
+          # already documented for exactly this job ("rendering a value
+          # object into a column or a message, where there is no path
+          # to consult," `value/coercion.rb`'s own comment) -- rather
+          # than inventing a second unwrap helper beside `Resolver#
+          # unwrap_scalar`'s bare-comparison one. Duck-typed the same
+          # way : a bare, non-VO lifecycle field passes through
+          # unchanged (`Value.scalar` only opens a `Value` instance).
+          current  = Value.scalar(subject[lifecycle.field]).to_s
+          admitted = candidates.find { |t| !t.constrained? || Array(t.from).include?(current) }
+          return admitted if admitted
+
+          allowed = candidates.flat_map { |t| Array(t.from) }.uniq
+          raise LifecycleRefused,
+                RefusalWording.render("LifecycleRefused", "transition_blocked",
+                                      command: command.hecks_name, field: lifecycle.field,
+                                      current: Rendering.describe(current),
+                                      allowed: allowed.map(&:inspect).join(" or "))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,260 @@
+require_relative "../../rendering"
+require_relative "../errors"
+require_relative "../refusal_wording"
+require_relative "../value"
+
+module Hecks
+  module Runtime
+    class CommandRules
+      # The arithmetic half of mutation: what a source resolves to, and how
+      # increment/decrement land on an Integer or a one-numeric-field value
+      # object.
+      module Arithmetic
+        # The ops Runtime::CommandInterpreter applies. Declared the same way in
+        # Vocabulary::MutationOp (language/bluebook/vocabulary.bluebook) —
+        # spec/vocabulary_conformance_spec holds the two tables equal, so
+        # increment/decrement's sign cannot drift from what the language says
+        # each op means. set/append carry no sign — they do no arithmetic.
+        MutationOp = Struct.new(:name, :sign, keyword_init: true)
+
+        MUTATION_OPS = [
+          MutationOp.new(name: "set",       sign: nil),
+          MutationOp.new(name: "append",    sign: nil),
+          MutationOp.new(name: "increment", sign: 1),
+          MutationOp.new(name: "decrement", sign: -1),
+          # Vendored addition, not (yet) upstream hecks (migration
+          # plan task 4, i106): multiply/clamp carry no sign -- like
+          # set/append, they do no add-or-subtract arithmetic (multiply
+          # scales, clamp bounds). See #multiply/#clamp below.
+          MutationOp.new(name: "multiply",  sign: nil),
+          MutationOp.new(name: "clamp",     sign: nil),
+          # Vendored addition, not (yet) upstream hecks (migration
+          # plan task 4): remove -- carries no sign, like set/append; it
+          # matches a list element by value rather than doing arithmetic.
+          # Declared here so this table stays exactly what
+          # Vocabulary::MutationOp declares (spec/vocabulary_conformance_spec
+          # holds the two equal) -- MutationApplier's own `when :remove`
+          # branch (mutation_applier.rb) never calls #sign_of, so this was
+          # a declared-vocabulary gap, not a behaviour gap.
+          MutationOp.new(name: "remove",    sign: nil),
+          # Vendored addition, not (yet) upstream hecks —
+          # CommandBuilder#delegates_to's own comment gives the full
+          # reasoning; carries no sign, like set/append/remove — it does
+          # no arithmetic, only a synchronous handoff into one nested
+          # entity command. Declared here so this table stays exactly
+          # what Vocabulary::MutationOp declares — MutationApplier's own
+          # `when :delegate` branch (mutation_applier.rb) never calls
+          # #sign_of either, same as `remove`'s own note above.
+          MutationOp.new(name: "delegate",  sign: nil),
+          # CommandBuilder#corrects_impl's own comment gives the full
+          # reasoning — a command amending a past event rather than
+          # acting fresh. Carries no sign, like delegate: it does no
+          # arithmetic of its own; the record's actual change, if any,
+          # is an ordinary `sets` declared alongside it.
+          MutationOp.new(name: "corrects",  sign: nil)
+        ].freeze
+
+        # A mutation's source is either the NAME OF AN ARGUMENT or a LITERAL, and
+        # the two are told apart by type : a Symbol is always a name, a String or a
+        # number is always a value. Checked across all eight chapters — `to: :name`
+        # and `to: "sold"`, never a Symbol meant as a value.
+        #
+        # `&& args.key?(source)` used to guard the lookup, and that guard is what
+        # made an ABSENT argument fall through to `source` and return THE SYMBOL
+        # ITSELF as the value. `Customer.Register` without its `name` set name to
+        # the literal `:name`, coercion met a Symbol where a PersonName belonged,
+        # and the refusal read "name is a PersonName — pass its fields as an
+        # object, not :name" — a message describing a mistake the caller had not
+        # made. The real mistake, an absent argument, was never the one refused,
+        # which is what fuzz surfaced.
+        #
+        # Absent now resolves to nil. Whether it should be REFUSED instead
+        # is a separate question — the language cannot yet say which arguments are
+        # optional, and the meta-domain has plenty that are.
+        def resolve_source(source, args)
+          return args[source] if source.is_a?(Symbol)
+
+          source
+        end
+
+        def arithmetic(current, amount, target, sign)
+          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
+
+          # `current` genuinely absent (no declared default, never set) and
+          # `amount` arrives VO-wrapped — a real command argument typed the
+          # same as the attribute, but with nothing to combine field-by-
+          # field against yet (that is what `arithmetic_value_object`,
+          # above, is for once BOTH sides carry real fields). Before this,
+          # falling straight to `unless amount.is_a?(Numeric)` below
+          # refused with "increment needs an Integer, got 500" — true of
+          # nothing: 500 is exactly the Integer it asked for, just still
+          # wearing the Money wrapper the command's own declared attribute
+          # type put it in. Unwrapped here, the same shape #clamp already
+          # falls through to for an absent VO-typed attribute
+          # (`current ||= 0`, then a raw scalar) — the mutation applier
+          # re-wraps the raw result into the declared VO type on write,
+          # the same way it already does for clamp's own result.
+          amount = unwrap_single_numeric_field(amount) if amount.is_a?(Value)
+
+          # Widened from Integer to Numeric (migration plan task 4, i106):
+          # miette's organ math increments a Float (`increment: 0.02`) --
+          # the raw, non-value-object path only ever mattered for Integer
+          # counters before this corpus existed. Integer stays the common
+          # case; Float is now accepted the same way.
+          unless amount.is_a?(Numeric)
+            raise TypeMismatch, RefusalWording.render("TypeMismatch", "arithmetic_amount",
+                                                      op: op, target: target, offered: Rendering.describe(amount))
+          end
+          unless current.is_a?(Numeric)
+            raise TypeMismatch, RefusalWording.render("TypeMismatch", "arithmetic_current",
+                                                      op: op, target: target, offered: Rendering.describe(current))
+          end
+
+          current + (sign * amount)
+        end
+
+        def arithmetic_value_object(current, amount, target, sign, op)
+          current_fields = current.to_h
+          amount_fields  = amount.to_h
+          # Widened from Integer to Numeric -- see #arithmetic's own
+          # comment. A synthesised value-object wrapper around a bare
+          # Float attribute (miette's Synapse#strength, auto-wrapped per
+          # Part 3a's "bare primitives forbidden" finding) lands here as
+          # a one-Float-field Value exactly the way a one-Integer-field
+          # Value already did.
+          shared_numeric = current_fields.keys.select do |field|
+            current_fields[field].is_a?(Numeric) && amount_fields[field].is_a?(Numeric)
+          end
+          unless shared_numeric.size == 1
+            raise TypeMismatch,
+                  RefusalWording.render("TypeMismatch", "arithmetic_shared_field", op: op, target: target)
+          end
+
+          field = shared_numeric.first
+          current.with(field, current[field] + (sign * amount[field]))
+        end
+
+        # Not a bare `.find(...)&.sign || -1` — that silently answered
+        # DECREMENT'S sign for BOTH an op this table has never heard of
+        # AND a declared, real op that simply carries no sign at all
+        # (set/append/multiply/clamp/remove — see MUTATION_OPS above).
+        # Callers today only ever reach this for :increment/:decrement
+        # (both MutationApplier#apply and EntityInterpreter#
+        # apply_to_element gate every other op through their own `case`
+        # first, each with its own loud WiringError backstop), so this
+        # 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")
+        end
+
+        # Vendored addition, not (yet) upstream hecks (migration plan
+        # task 4, i106): `current * amount` -- the scaling counterpart to
+        # increment/decrement's add/subtract. Same raw-vs-value-object
+        # branch shape as #arithmetic/#arithmetic_value_object, reused
+        # rather than duplicated verb-for-verb (a `Proc` picks the actual
+        # arithmetic; everything else -- the Value unwrap/rewrap, the
+        # TypeMismatch refusals -- is identical to the additive pair).
+        def multiply(current, amount, target)
+          current ||= 0
+
+          if current.is_a?(Value) && amount.is_a?(Value)
+            return combine_value_object(current, amount, target, "multiply") { |c, a| c * a }
+          end
+
+          # Same absent-`current`, VO-wrapped-`amount` gap as `#arithmetic`
+          # — see that method's own comment.
+          amount = unwrap_single_numeric_field(amount) if amount.is_a?(Value)
+
+          unless amount.is_a?(Numeric) && current.is_a?(Numeric)
+            raise TypeMismatch, RefusalWording.render("TypeMismatch", "arithmetic_amount",
+                                                      op: "multiply", target: target,
+                                                      offered: Rendering.describe(current.is_a?(Numeric) ? amount : current))
+          end
+
+          current * amount
+        end
+
+        # Vendored addition, not (yet) upstream hecks (migration plan
+        # task 4, i106): bound the CURRENT value into `[min, max]` -- no
+        # "amount" to combine, so it does not go through
+        # #arithmetic/#multiply's shared-numeric-field matching at all;
+        # it clamps whichever single numeric field the wrapping value
+        # object carries (a synthesised wrapper always carries exactly
+        # one, per Part 3a's auto-synthesis).
+        def clamp(current, bounds, target)
+          min, max = bounds
+          # THE SAME `current ||= 0` #arithmetic/#multiply both give a
+          # PHANTOM (never-set) numeric field, one line up from each —
+          # this was the one arithmetic op that didn't, so a VO-typed
+          # attribute with no declared `default:` (genuinely absent,
+          # `Instance.defaults`/`#default_for`) hit TypeMismatch on the
+          # FIRST clamp. (#arithmetic/#multiply's OWN absent-current gap
+          # was a real, separate bug this comment used to describe wrong —
+          # they did not "silently treat the same absent field as zero";
+          # they raised too, blaming a perfectly valid `amount` for not
+          # being an Integer when it was one, just still Money-wrapped.
+          # Fixed alongside this one — see #unwrap_single_numeric_field.)
+          current ||= 0
+          if current.is_a?(Value)
+            fields = current.to_h
+            field  = fields.keys.find { |f| fields[f].is_a?(Numeric) } or
+              raise TypeMismatch, RefusalWording.render("TypeMismatch", "arithmetic_current",
+                                                        op: "clamp", target: target, offered: Rendering.describe(current))
+            return current.with(field, fields[field].clamp(min, max))
+          end
+
+          unless current.is_a?(Numeric)
+            raise TypeMismatch, RefusalWording.render("TypeMismatch", "arithmetic_current",
+                                                      op: "clamp", target: target, offered: Rendering.describe(current))
+          end
+
+          current.clamp(min, max)
+        end
+
+        private
+
+        # `amount` arrives VO-wrapped whenever the command's own declared
+        # attribute type says so (a real `Money`, not a bare Integer) —
+        # true whether or not `current` has ever been set. Only meaningful
+        # to call once `current` is known NOT to be a Value itself (the
+        # `current.is_a?(Value) && amount.is_a?(Value)` branch, above in
+        # both callers, already owns the case where both sides carry real
+        # fields to combine). Refuses rather than guesses when more than
+        # one field is numeric — genuinely ambiguous which one an absent
+        # `current` should be treated as zero for, the same reasoning
+        # `combine_value_object`'s own `shared_numeric.size == 1` check
+        # already holds to when both sides ARE present.
+        def unwrap_single_numeric_field(value)
+          fields = value.to_h
+          numeric_fields = fields.keys.select { |field| fields[field].is_a?(Numeric) }
+          return value unless numeric_fields.size == 1
+
+          fields[numeric_fields.first]
+        end
+
+        def combine_value_object(current, amount, target, op)
+          current_fields = current.to_h
+          amount_fields  = amount.to_h
+          shared_numeric = current_fields.keys.select do |field|
+            current_fields[field].is_a?(Numeric) && amount_fields[field].is_a?(Numeric)
+          end
+          unless shared_numeric.size == 1
+            raise TypeMismatch,
+                  RefusalWording.render("TypeMismatch", "arithmetic_shared_field", op: op, target: target)
+          end
+
+          field = shared_numeric.first
+          current.with(field, yield(current[field], amount[field]))
+        end
+      end
+    end
+  end
+end