hecks 3.4.2 → 3.6.0

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

@@ -4,6 +4,8 @@ require_relative "../errors"
 require_relative "../refusal_wording"
 require_relative "../value"
 require_relative "../instance"
+require_relative "guard_state"
+require_relative "invariants"
 
 module Hecks
   module Runtime
@@ -11,44 +13,8 @@ module Hecks
       # Whether a command may run at all: its declared givens, and the
       # lifecycle transition it asks for.
       module Admissibility
-        # Wraps `subject` so a guard reads a declared, optional attribute
-        # that predates the record as nil instead of raising.
-        class GuardState
-          def initialize(instance)
-            @instance = instance
-            @declared = instance.respond_to?(:aggregate) ? instance.aggregate.attributes.to_h { |a| [a.name, a] } : {}
-            # Separate index: a projected field's absence raises its own
-            # refusal, not AttributeAbsent's (ADR 0025).
-            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)
-
-          # Nil for an absent optional attribute; raises for anything else absent.
-          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?
+        include Invariants
 
-            raise AttributeAbsent,
-                  RefusalWording.render_site("AttributeAbsent", "absent_read",
-                                             aggregate: @instance.aggregate.hecks_name, field: name)
-          end
-
-          private
-
-          def raise_projection_absent(projected)
-            raise ProjectionAbsent,
-                  RefusalWording.render_site("ProjectionAbsent", "absent_read",
-                                             aggregate: @instance.aggregate.hecks_name, field: projected.name,
-                                             reference: projected.reference, remote_field: projected.remote_field)
-          end
-        end
         private_constant :GuardState
 
         # Checks whether `command` may run against `subject`: its declared
@@ -61,24 +27,14 @@ module Hecks
         # @param correction [Hash{Symbol => Object}] `corrects` event bindings
         # @return [void]
         # @raise [Runtime::GivenNotMet] a declared `given` does not hold
-        # @raise [Runtime::LifecycleRefused] `declaring`'s `from:` guard refuses
-        #   the current lifecycle state
+        # @raise [Runtime::LifecycleRefused] `declaring`'s `from:` guard refuses the state
+        # rubocop:disable-next Metrics/ParameterLists -- the dispatch context every interpreter passes by keyword
         def enforce_givens(subject, command, args, domain:, declaring: nil, parent: nil, correction: {})
-          state = GuardState.new(subject)
           # A rule reads only within its own aggregate boundary (ADR 0025);
           # `dereference` below resolves fresh reference arguments only,
           # never a stored `projects` field, which `state` already has.
-          attrs = args.merge(dereference(domain, command, args))
-          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_rule(given, state, attrs)
-
-            raise GivenNotMet.new(
-              "#{command.hecks_name} refused — #{given.description}",
-              detail: Bluebook::Expression::Evaluator.comparison_detail(given.canonical, state, attrs)
-            )
-          end
+          attrs = with_rule_context(args.merge(dereference(domain, command, args)), parent, correction)
+          refuse_unmet_givens(command, GuardState.new(subject), attrs)
 
           enforce_lifecycle_guard(declaring, command, subject) if declaring
         end
@@ -116,29 +72,12 @@ module Hecks
         #   for a mutation with no `as:`
         # @raise [Runtime::NothingToCorrect] a named event `instance` never emitted
         def enforce_correction_target(instance, aggregate, command, domain:)
-          bindings = {}
-          command.mutations.each do |mutation|
-            next unless mutation.op == :corrects
-
-            event_key  = "#{domain}::#{aggregate.hecks_name}"
-            event_name = mutation.target.to_s
-            # Most recent match wins if this record emitted the same event
-            # more than once; aggregate and id are already scoped by
-            # correction_history, so only the event name is filtered here.
-            corrected = correction_history(domain, aggregate, event_key, instance.id).reverse.find do |event|
-              event.name == event_name
-            end
-
-            unless corrected
-              raise NothingToCorrect,
-                    "#{command.hecks_name} refused — corrects #{event_name}, but " \
-                    "#{event_key} ##{instance.id} has never emitted it"
-            end
-
+          corrections = command.mutations.select { |mutation| mutation.op == :corrects }
+          corrections.each_with_object({}) do |mutation, bindings|
+            corrected = corrected_event(instance, aggregate, command, mutation, domain)
             as = mutation.source[:as]
             bindings[as.to_sym] = corrected.payload if as && !as.to_s.empty?
           end
-          bindings
         end
 
         # Checks a command's own `from:` lifecycle guard — a precondition,
@@ -158,13 +97,7 @@ module Hecks
           current   = Value.scalar(subject[lifecycle.field]).to_s
           return if Array(command.from).include?(current)
 
-          # Routed through the same "transition_blocked" template
-          # `#admissible_transition` uses, so both raise identical wording.
-          raise LifecycleRefused,
-                RefusalWording.render_site("LifecycleRefused", "transition_blocked",
-                                           command: command.hecks_name, field: lifecycle.field,
-                                           current: Rendering.describe(current),
-                                           allowed: Array(command.from))
+          raise_transition_blocked(command, lifecycle, current, Array(command.from))
         end
 
         # Checks `command`'s declared `ensures` against `subject`, the settled
@@ -177,15 +110,14 @@ module Hecks
         # @param correction [Hash{Symbol => Object}] `corrects` event bindings, if any
         # @return [void]
         # @raise [Runtime::EnsuresNotMet] a declared `ensures` does not hold
+        # rubocop:disable-next Metrics/ParameterLists -- the dispatch context every interpreter passes by keyword
         def enforce_ensures(subject, command, args, old:, domain:, parent: nil, correction: {})
           state = GuardState.new(subject)
           # Same aggregate-boundary rule as enforce_givens (ADR 0025) —
           # `state` already carries projected fields; only a fresh
           # reference-typed argument needs `dereference` here.
-          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)
+          fresh = args.reject { |name, _| subject.key?(name) }.merge(dereference(domain, command, args))
+          attrs = with_rule_context(fresh, parent, correction).merge(old: old)
           command.ensures.each do |rule|
             next if Bluebook::Expression::Evaluator.call_rule(rule, state, attrs)
 
@@ -193,67 +125,6 @@ module Hecks
           end
         end
 
-        # Checks `aggregate`'s declared invariants against the settled
-        # `subject`, then each of its entities' own invariants.
-        #
-        # No `dereference` here (ADR 0025) — an invariant may only read
-        # `subject`'s own boundary, same rule enforce_givens/ensures hold to.
-        #
-        # @param subject [Runtime::Instance] the settled aggregate record checked
-        # @param aggregate [Bluebook::Aggregate] the aggregate whose invariants are checked
-        # @param domain [String, Symbol] domain `aggregate` belongs to
-        # @return [void]
-        # @raise [Runtime::InvariantViolation] a declared invariant does not hold, on
-        #   `aggregate` itself or any of its entities
-        def enforce_invariants(subject, aggregate, domain:)
-          state = GuardState.new(subject)
-          attrs = {}
-          aggregate.invariants.each do |invariant|
-            next if Bluebook::Expression::Evaluator.call_rule(invariant, state, attrs)
-
-            raise InvariantViolation, "#{aggregate.hecks_name} refused — #{invariant.description}"
-          end
-
-          check_entity_invariants(aggregate, subject, domain: domain)
-        end
-
-        # Checks each of `owner_construct`'s entity types' own invariants
-        # against every instance it holds, recursing into nested entities.
-        #
-        # An entity with no matching list attribute on its owner is skipped,
-        # not raised — a static-analysis gap, not a runtime concern here.
-        #
-        # @param owner_construct [Bluebook::Aggregate, Bluebook::Entity] whose entities are checked
-        # @param owner_instance [Runtime::Instance] settled record holding the entity lists
-        # @param domain [String, Symbol] the domain `owner_construct` belongs to
-        # @return [void]
-        # @raise [Runtime::InvariantViolation] an entity invariant does not hold
-        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` (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_rule(invariant, element_state, attrs)
-
-                raise InvariantViolation, "#{entity.hecks_name} refused — #{invariant.description}"
-              end
-
-              check_entity_invariants(entity, wrapped, domain: domain)
-            end
-          end
-        end
-
         # Finds the lifecycle transition `command` admits from `subject`'s
         # current state, if `declaring` declares a lifecycle and moves it.
         #
@@ -271,13 +142,59 @@ module Hecks
           candidates = lifecycle.transitions_for(command.hecks_name)
           return nil if candidates.empty?
 
+          admitted_transition(candidates, command, lifecycle, subject)
+        end
+
+        private
+
+        # Layers an entity command's parent state and a correction's bindings onto the attributes
+        # a rule reads.
+        def with_rule_context(attrs, parent, correction)
+          attrs = attrs.merge(parent: parent.state) if parent
+          attrs = attrs.merge(correction) unless correction.empty?
+          attrs
+        end
+
+        def refuse_unmet_givens(command, state, attrs)
+          command.givens.each do |given|
+            next if Bluebook::Expression::Evaluator.call_rule(given, state, attrs)
+
+            raise GivenNotMet.new(
+              "#{command.hecks_name} refused — #{given.description}",
+              detail: Bluebook::Expression::Evaluator.comparison_detail(given.canonical, state, attrs)
+            )
+          end
+        end
+
+        # The most recent emission of the event a `corrects` mutation names. Most recent match wins
+        # if this record emitted the same event more than once; aggregate and id are already scoped
+        # by correction_history, so only the event name is filtered here.
+        def corrected_event(instance, aggregate, command, mutation, domain)
+          event_key  = "#{domain}::#{aggregate.hecks_name}"
+          event_name = mutation.target.to_s
+          corrected  = correction_history(domain, aggregate, event_key, instance.id).reverse.find do |event|
+            event.name == event_name
+          end
+          return corrected if corrected
+
+          raise NothingToCorrect,
+                "#{command.hecks_name} refused — corrects #{event_name}, but " \
+                "#{event_key} ##{instance.id} has never emitted it"
+        end
+
+        # The candidate that admits the record's current state, or a refusal naming every state
+        # the candidates would move from.
+        def admitted_transition(candidates, command, lifecycle, subject)
           # `Value.scalar` unwraps a VO-typed lifecycle field before `.to_s`;
           # without it, a wrapped field never matches any `from:` state.
-          current  = Value.scalar(subject[lifecycle.field]).to_s
-          admitted = candidates.find { |t| !t.constrained? || Array(t.from).include?(current) }
-          return admitted if admitted
+          current = Value.scalar(subject[lifecycle.field]).to_s
+          candidates.find { |t| !t.constrained? || Array(t.from).include?(current) } ||
+            raise_transition_blocked(command, lifecycle, current, candidates.flat_map { |t| Array(t.from) }.uniq)
+        end
 
-          allowed = candidates.flat_map { |t| Array(t.from) }.uniq
+        # Routed through one "transition_blocked" template, so a lifecycle guard and a
+        # transition raise identical wording.
+        def raise_transition_blocked(command, lifecycle, current, allowed)
           raise LifecycleRefused,
                 RefusalWording.render_site("LifecycleRefused", "transition_blocked",
                                            command: command.hecks_name, field: lifecycle.field,

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

@@ -2,6 +2,7 @@ require_relative "../../rendering"
 require_relative "../errors"
 require_relative "../refusal_wording"
 require_relative "../value"
+require_relative "operands"
 
 module Hecks
   module Runtime
@@ -9,6 +10,8 @@ module Hecks
       # The arithmetic half of mutation: source resolution, and how
       # increment/decrement land on an Integer or a one-numeric-field value object.
       module Arithmetic
+        include Operands
+
         # Mirrors Vocabulary::MutationOp (language/bluebook/vocabulary.bluebook) so
         # increment/decrement's sign cannot drift from the language's own definition.
         # Ops with no arithmetic (set, append, multiply, clamp, remove, delegate,
@@ -52,23 +55,15 @@ module Hecks
           op = sign.positive? ? "increment" : "decrement"
           current ||= 0
 
-          return arithmetic_value_object(current, amount, target, sign, op) if current.is_a?(Value) && amount.is_a?(Value)
+          return arithmetic_value_object(current, amount, target, sign, op) if value_objects?(current, amount)
 
           # A VO-typed attribute with no declared default is genuinely absent
           # here (`current` is 0, not a Value), so `amount` still needs
           # unwrapping to compare against a bare number.
           amount = unwrap_single_numeric_field(amount) if amount.is_a?(Value)
+          refuse_non_numeric!(op, target, amount, current)
 
-          unless amount.is_a?(Numeric)
-            raise TypeMismatch, RefusalWording.render_site("TypeMismatch", "arithmetic_amount",
-                                                           op: op, target: target, offered: Rendering.describe(amount))
-          end
-          unless current.is_a?(Numeric)
-            raise TypeMismatch, RefusalWording.render_site("TypeMismatch", "arithmetic_current",
-                                                           op: op, target: target, offered: Rendering.describe(current))
-          end
-
-          bounded(current + (sign * amount), op, current, sign * amount, sign.positive? ? "+" : "-")
+          bounded(current + (sign * amount), op, current, sign * amount, sign_symbol(sign))
         end
 
         # An effect's arithmetic is held to the same value model an expression's is:
@@ -113,21 +108,10 @@ module Hecks
         # @raise [Bluebook::Expression::EvaluationError] if the result overflows Integer, or isn't
         #   finite
         def arithmetic_value_object(current, amount, target, sign, oper)
-          current_fields = current.to_h
-          amount_fields  = amount.to_h
-          # A synthesized value-object wrapper around a bare numeric attribute
-          # always carries exactly one numeric field.
-          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_site("TypeMismatch", "arithmetic_shared_field", op: oper, target: target)
+          symbol = sign_symbol(sign)
+          combine_value_object(current, amount, target, oper) do |held, by|
+            bounded(held + (sign * by), oper, held, by, symbol)
           end
-
-          field = shared_numeric.first
-          current.with(field, bounded(current[field] + (sign * amount[field]), oper,
-                                      current[field], amount[field], sign.positive? ? "+" : "-"))
         end
 
         # Looks up whether a mutation op adds or subtracts, from the generated
@@ -159,7 +143,7 @@ module Hecks
         def multiply(current, amount, target)
           current ||= 0
 
-          if current.is_a?(Value) && amount.is_a?(Value)
+          if value_objects?(current, amount)
             return combine_value_object(current, amount, target, "multiply") do |c, a|
               bounded(c * a, "multiply", c, a, "*")
             end
@@ -167,12 +151,7 @@ module Hecks
 
           # Same absent-current, VO-wrapped-amount gap as #arithmetic, above.
           amount = unwrap_single_numeric_field(amount) if amount.is_a?(Value)
-
-          unless amount.is_a?(Numeric) && current.is_a?(Numeric)
-            raise TypeMismatch, RefusalWording.render_site("TypeMismatch", "arithmetic_amount",
-                                                           op: "multiply", target: target,
-                                                           offered: Rendering.describe(current.is_a?(Numeric) ? amount : current))
-          end
+          refuse_unmultipliable!(target, amount, current)
 
           bounded(current * amount, "multiply", current, amount, "*")
         end
@@ -190,49 +169,11 @@ module Hecks
         def clamp(current, bounds, target)
           min, max = bounds
           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_site("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_site("TypeMismatch", "arithmetic_current",
-                                                           op: "clamp", target: target, offered: Rendering.describe(current))
-          end
+          return clamp_value_object(current, min, max, target) if current.is_a?(Value)
 
+          refuse_clamp_current!(current, target) unless current.is_a?(Numeric)
           current.clamp(min, max)
         end
-
-        private
-
-        # Only meaningful once `current` is known not to itself be a Value (the
-        # both-sides-are-Values branch owns that case in each caller). Refuses
-        # rather than guesses when more than one field is numeric.
-        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, oper)
-          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_site("TypeMismatch", "arithmetic_shared_field", op: oper, target: target)
-          end
-
-          field = shared_numeric.first
-          current.with(field, yield(current[field], amount[field]))
-        end
       end
     end
   end

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

@@ -26,15 +26,7 @@ module Hecks
           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,
-                                                          as_of: caller.as_of, scope: caller.scope)
-            else
-              caller.role == command.role
-            end
-
-          return if authorized
+          return if role_held?(caller, command, domain)
 
           raise Unauthorized, RefusalWording.render_site("Unauthorized", "role_mismatch",
                                                          command: command.hecks_name, role: command.role,
@@ -43,6 +35,14 @@ module Hecks
 
         private
 
+        # An identified caller holds the role by a live grant; an unidentified one by its string.
+        def role_held?(caller, command, domain)
+          return caller.role == command.role unless caller.actor_id && governance_attached?(domain)
+
+          Ports::Authorization.holds_role?(registry, actor_id: caller.actor_id, role: command.role,
+                                                     as_of: caller.as_of, scope: caller.scope)
+        end
+
         # The provider's own commands are checked too, so the first administrator grant must
         # come from a caller with no `actor_id` (the string-compared path).
         def governance_attached?(domain)

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

@@ -7,31 +7,30 @@ module Hecks
       module Emission
         # Builds one frozen event per name the command `emits` and records each.
         #
-        # `correlation` is set at construction so the event can be frozen the moment it exists.
-        #
         # @param command [Bluebook::Command] the command whose `emits` names the events
         # @param domain [String] the emitting domain's name
         # @param aggregate [Bluebook::Aggregate] the aggregate the record belongs to
         # @param instance [Runtime::Instance] the settled record; its `id` stamps every event
         # @param args [Hash{Symbol => Object}] the normalized arguments, used as each payload
         # @param repository [Ports::Persistence::AppendOnly] asked to `record_event` if it can
-        # @param correlation [Hash, nil] saga correlation for a saga-caused dispatch
+        # @param correlation [Hash, nil] saga correlation, set before the event freezes
         # @return [Array<Runtime::Event>] the emitted events in `emits` order
+        # rubocop:disable-next Metrics/ParameterLists -- the positional signature both interpreters call
         def emit(command, domain, aggregate, instance, args, repository, correlation = nil)
+          stamp = { aggregate: "#{domain}::#{aggregate.hecks_name}", id: instance.id,
+                    payload: args, correlation: correlation }
           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
+            record_emitted(Event.new(name: event_name, occurred_at: Time.now.utc.iso8601, **stamp), repository)
           end
         end
+
+        private
+
+        def record_emitted(event, repository)
+          @registry.event_log << event.emit!
+          repository.record_event(event) if repository.respond_to?(:record_event)
+          event
+        end
       end
     end
   end

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

@@ -0,0 +1,49 @@
+require_relative "../errors"
+require_relative "../refusal_wording"
+
+module Hecks
+  module Runtime
+    class CommandRules
+      module Admissibility
+        # Wraps `subject` so a guard reads a declared, optional attribute
+        # that predates the record as nil instead of raising.
+        class GuardState
+          def initialize(instance)
+            @instance = instance
+            @declared = instance.respond_to?(:aggregate) ? instance.aggregate.attributes.to_h { |a| [a.name, a] } : {}
+            # Separate index: a projected field's absence raises its own
+            # refusal, not AttributeAbsent's (ADR 0025).
+            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)
+
+          # Nil for an absent optional attribute; raises for anything else absent.
+          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_site("AttributeAbsent", "absent_read",
+                                             aggregate: @instance.aggregate.hecks_name, field: name)
+          end
+
+          private
+
+          def raise_projection_absent(projected)
+            raise ProjectionAbsent,
+                  RefusalWording.render_site("ProjectionAbsent", "absent_read",
+                                             aggregate: @instance.aggregate.hecks_name, field: projected.name,
+                                             reference: projected.reference, remote_field: projected.remote_field)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,84 @@
+require_relative "../../bluebook/expression/evaluator"
+require_relative "../errors"
+require_relative "../instance"
+require_relative "guard_state"
+
+module Hecks
+  module Runtime
+    class CommandRules
+      module Admissibility
+        # Holds a settled record to its aggregate's declared invariants, and to each of its
+        # entities' own.
+        module Invariants
+          # Checks `aggregate`'s declared invariants against the settled
+          # `subject`, then each of its entities' own invariants.
+          #
+          # No `dereference` here (ADR 0025) — an invariant may only read
+          # `subject`'s own boundary, same rule enforce_givens/ensures hold to.
+          #
+          # @param subject [Runtime::Instance] the settled aggregate record checked
+          # @param aggregate [Bluebook::Aggregate] the aggregate whose invariants are checked
+          # @param domain [String, Symbol] domain `aggregate` belongs to
+          # @return [void]
+          # @raise [Runtime::InvariantViolation] a declared invariant does not hold, on
+          #   `aggregate` itself or any of its entities
+          def enforce_invariants(subject, aggregate, domain:)
+            refuse_unmet_invariants(aggregate, GuardState.new(subject), {})
+
+            check_entity_invariants(aggregate, subject, domain: domain)
+          end
+
+          # Checks each of `owner_construct`'s entity types' own invariants
+          # against every instance it holds, recursing into nested entities.
+          #
+          # An entity with no matching list attribute on its owner is skipped,
+          # not raised — a static-analysis gap, not a runtime concern here.
+          #
+          # @param owner_construct [Bluebook::Aggregate, Bluebook::Entity] whose entities are
+          #   checked
+          # @param owner_instance [Runtime::Instance] settled record holding the entity lists
+          # @param domain [String, Symbol] the domain `owner_construct` belongs to
+          # @return [void]
+          # @raise [Runtime::InvariantViolation] an entity invariant does not hold
+          def check_entity_invariants(owner_construct, owner_instance, domain:)
+            owner_construct.entities.each do |entity|
+              next if entity.invariants.empty?
+
+              list_attr = entity_list_attribute(owner_construct, entity)
+              next unless list_attr
+
+              Array(owner_instance[list_attr.name]).each do |element|
+                check_element_invariants(entity, element, owner_instance, domain)
+              end
+            end
+          end
+
+          private
+
+          def entity_list_attribute(owner_construct, entity)
+            owner_construct.attributes.find { |a| a.list? && a.type.to_s == entity.hecks_name }
+          end
+
+          # An aggregate's or entity's own invariants, read against `state` and `attrs`.
+          def refuse_unmet_invariants(construct, state, attrs)
+            construct.invariants.each do |invariant|
+              next if Bluebook::Expression::Evaluator.call_rule(invariant, state, attrs)
+
+              raise InvariantViolation, "#{construct.hecks_name} refused — #{invariant.description}"
+            end
+          end
+
+          def check_element_invariants(entity, element, owner_instance, domain)
+            wrapped = Instance.new(aggregate: entity, id: nil, state: element)
+            # No `dereference` (ADR 0025) — same boundary rule as
+            # enforce_invariants above; `parent` (the owner's own
+            # state, projected fields included) stays readable.
+            refuse_unmet_invariants(entity, GuardState.new(wrapped), { parent: owner_instance.state })
+
+            check_entity_invariants(entity, wrapped, domain: domain)
+          end
+        end
+      end
+    end
+  end
+end