hecks 0.2.0 → 0.3.0

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

@@ -0,0 +1,307 @@
+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)
+          owner = subject.aggregate if subject.respond_to?(:aggregate)
+          attrs = dereference(domain, owner, subject).merge(args).merge(dereference(domain, command, args))
+          attrs = attrs.merge(parent: parent.state.merge(dereference(domain, parent.aggregate, 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
+
+        # 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)
+          owner = subject.aggregate if subject.respond_to?(:aggregate)
+          # Same merge-order reasoning as enforce_givens above: an
+          # aliased command-level reference must override its own raw
+          # id argument, not the other way round. `old` still wins over
+          # everything, unchanged.
+          attrs = dereference(domain, owner, subject).merge(args).merge(dereference(domain, command, args))
+          attrs = attrs.merge(parent: parent.state.merge(dereference(domain, parent.aggregate, 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 (dereferenced) 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.
+        def enforce_invariants(subject, aggregate, domain:)
+          state = GuardState.new(subject)
+          attrs = dereference(domain, aggregate, subject)
+          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)
+              attrs = dereference(domain, entity, wrapped)
+                      .merge(parent: owner_instance.state.merge(dereference(domain, owner_construct, owner_instance)))
+
+              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,254 @@
+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)
+        ].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

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

@@ -0,0 +1,64 @@
+require_relative "../caller"
+require_relative "../errors"
+require_relative "../refusal_wording"
+require_relative "../../ports/authorization"
+
+module Hecks
+  module Runtime
+    class CommandRules
+      # Whether the caller may run this command at all — a `role` mismatch,
+      # the one check that runs before any domain-state work, alongside the
+      # argument gate rather than after it.
+      #
+      # TWO CHECKS, NOT A REPLACEMENT — ADR 0025 §9's own caution against
+      # "silently downgrading `role` to documentation" cuts both ways: a
+      # caller who never named WHO they are (every caller before this) is
+      # checked exactly the way it always has been, string equality
+      # against the command's own `role`. Only a caller that ALSO binds an
+      # `actor_id` (`Hecks.as_caller(role:, actor_id:)`) reaches the
+      # real check — a live Governance::RoleAssignment lookup through
+      # `Ports::Authorization`, once the command's domain declares
+      # `uses_framework "Governance"` (`HecksagonBuilder` refuses any
+      # domain that declares a `role` and does not, at build time — see
+      # its own `refuse_ungoverned_roles!`). An identified caller is never
+      # let back through the string fallback: a real identity that holds
+      # no matching grant is refused, not waved through because it also
+      # happens to type the right word.
+      module Authorization
+        # OPT-IN, on BOTH sides. No caller bound: unchecked, exactly as
+        # today. No role declared: unchecked too — `role` is genuinely
+        # optional in this language (roughly a third of banking's own
+        # commands declare none), so a command that never named a role has
+        # nothing to check a caller against.
+        def refuse_role_mismatch(command, domain)
+          caller = Caller.current
+          return unless caller
+          return if command.role.to_s.empty?
+
+          authorized =
+            if caller.actor_id && governance_attached?(domain)
+              Ports::Authorization.holds_role?(registry, actor_id: caller.actor_id, role: command.role)
+            else
+              caller.role == command.role
+            end
+
+          return if authorized
+
+          raise Unauthorized, RefusalWording.render("Unauthorized", "role_mismatch",
+                                                    command: command.hecks_name, role: command.role,
+                                                    caller_role: caller.role)
+        end
+
+        private
+
+        # SELF-EXEMPT, like `HecksagonBuilder#refuse_ungoverned_roles!` —
+        # Governance IS the thing a `holds_role?` lookup runs against, so
+        # its own commands are always checked by the string fallback, not
+        # a lookup against itself.
+        def governance_attached?(domain)
+          domain.to_s == "Governance" || registry.hecksagon(domain)&.framework_members&.include?("Governance") || false
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+require_relative "../event"
+
+module Hecks
+  module Runtime
+    class CommandRules
+      # What a command's `emits` becomes: an Event in the registry's log,
+      # and — where the store can hold one — a recorded event beside the
+      # data it describes.
+      module Emission
+        # `correlation` arrives HERE rather than being merged onto the
+        # event afterwards. It is part of the transaction — known from
+        # `dispatch`'s own argument before anything is emitted — and an
+        # event that is still being written to is not yet a record of
+        # what happened. Setting it at construction is what lets the
+        # event be frozen the moment it exists.
+        def emit(command, domain, aggregate, instance, args, repository, correlation = nil)
+          command.emits.map do |event_name|
+            event = Event.new(
+              name:        event_name,
+              aggregate:   "#{domain}::#{aggregate.hecks_name}",
+              id:          instance.id,
+              payload:     args,
+              occurred_at: Time.now.utc.iso8601,
+              correlation: correlation
+            )
+            @registry.event_log << event.emit!
+            repository.record_event(event) if repository.respond_to?(:record_event)
+            event
+          end
+        end
+      end
+    end
+  end
+end