hecks 1.4.0 → 1.5.1

data/lib/hecks/runtime/command_interpreter.rb

@@ -31,7 +31,7 @@ module Hecks
       # both directions.
       DISPATCH_ORDER = Hecks::Vocabulary.symbols("AggregateDispatchOrder")
 
-      # **A last-resort safety valve, not the normal outcome path** — see
+      # A last-resort safety valve, not the normal outcome path — see
       # `Runtime::StaleWrite`'s own comment. Two concurrent writers
       # against one aggregate resolve through exactly one retry in the
       # ordinary case (the loser's retried hydrate reads the winner's now-
@@ -41,14 +41,17 @@ module Hecks
       # two-writer case.
       MAX_STALE_WRITE_RETRIES = 5
 
-      # Every cross-step local `call` used to thread through its own literal
-      # sequence, held in one place now that the sequence is data-driven —
+      # Every cross-step local held in one place, now that the sequence is
+      # data-driven rather than `call`'s own literal method-call sequence —
       # `result` and `transition`/`old_state` default to nil until the step
-      # that sets them runs, same as they were unset locals before that point.
+      # that sets them runs, the same as unset locals would be before that point.
       Context = Struct.new(:domain, :aggregate, :command, :args, :repository, :instance, :transition, :old_state,
                            :result, :correlation, :route, :plan, :strategy, :persistence_outcome, :pending_delegation,
                            :dry_run, :correction_bindings, :outbox_rows, :invocation)
 
+      # @param registry [Runtime::Registry] the booted registry this interpreter reads
+      # @param rules [Runtime::CommandRules] the shared rules engine (admissibility,
+      #   references, arithmetic, authorization, emission) dispatch runs through
       def initialize(registry, rules:)
         @registry = registry
         @rules    = rules
@@ -69,6 +72,27 @@ module Hecks
       # `invocation` — the `Runtime::Invocation` `Dispatcher` built for this
       # call. `ctx.args` is `invocation.to_args` (the same Hash routing
       # always handed this method), `ctx.route` its `target`.
+      #
+      # @param domain [String, Symbol] the domain `aggregate` belongs to
+      # @param aggregate [Bluebook::Aggregate] the aggregate the command acts on
+      # @param command [Class] the command class (`Bluebook::Command` subclass) to dispatch
+      # @param invocation [Runtime::Invocation] the invocation `Dispatcher` built for
+      #   this call
+      # @param correlation [Hash{Symbol => Object}, nil] correlation head => value,
+      #   stamped on every emitted event when a saga leg causes this dispatch; nil
+      #   otherwise
+      # @param dry_run [Boolean] whether to run every step through validation without
+      #   saving, emitting or enqueueing
+      # @return [Array(Runtime::Instance, Array<Runtime::Event>,
+      #   Runtime::DependencyPlanning::Plan, Ports::Persistence::Execution,
+      #   Array<Runtime::Outbox::Row>)] the settled instance, emitted events,
+      #   execution plan, persistence outcome and outbox rows — the last
+      #   three nil on a dry run, which skips save/emit/outbox
+      # @raise [StandardError] any class in `Runtime::DOMAIN_REFUSALS` when a
+      #   given/ensures/invariant/authorization/admissibility rule refuses
+      # @raise [Runtime::StaleWrite] if concurrent writers beat this one through every
+      #   retry (`MAX_STALE_WRITE_RETRIES`)
+      # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
       def call(domain, aggregate, command, invocation, correlation = nil, dry_run: false)
         args    = invocation.to_args
         route   = invocation.target
@@ -273,9 +297,9 @@ module Hecks
           # `ensures`/`enforce_invariants`/`save` steps still run after
           # this one. The target's emission is parked and performed by
           # `step_emit`, after the parent committed — where every other
-          # command's events are emitted too. (Before this, the entity
-          # leg's events were on the event log and in the adapter before
-          # the parent could refuse.)
+          # command's events are emitted too. (Without parking it here, the
+          # entity leg's events would be on the event log and in the adapter
+          # before the parent could refuse.)
           ctx.pending_delegation = [target_command, target_args]
         end
       end
@@ -350,7 +374,7 @@ module Hecks
 
       def persist_instance(ctx)
         if ctx.strategy == DependencyPlanning::ATOMIC_PUT
-          # **A second creation is not a fresh one** — see
+          # A second creation is not a fresh one — see
           # hydrate_complete_state's own comment; the
           # same refusal, on the same terms, for the
           # complete-state path. `insert_only:` asks the
@@ -441,8 +465,9 @@ module Hecks
           # `:delegate` mutation.
           if ctx.pending_delegation
             target_command, target_args = ctx.pending_delegation
-            # The same dispatch, so the same correlation — a saga-driven
-            # door's events used to lose their stamp here.
+            # The same dispatch, so the same correlation — without
+            # threading `ctx.correlation` through, a saga-driven door's
+            # events would lose their stamp here.
             next @rules.emit(target_command, ctx.domain, ctx.aggregate, ctx.instance, target_args, ctx.repository,
                              ctx.correlation)
           end
@@ -562,7 +587,7 @@ module Hecks
                                                         aggregate: aggregate.hecks_name,
                                                         identity:  identity_reading(aggregate)))
 
-        # **A second creation is not a fresh one** — `creates?` on an identity
+        # A second creation is not a fresh one — `creates?` on an identity
         # a record already exists under refuses (`AlreadyExists`) rather
         # than silently overwriting it, the same refusal `hydrate_prior_
         # or_initial`'s own body gives for its own complete-but-state-
@@ -604,7 +629,7 @@ module Hecks
                                                         identity:  identity_reading(aggregate)))
         found = repository.find(id)
 
-        # **A second creation is not a fresh one** — see hydrate_complete_
+        # A second creation is not a fresh one — see hydrate_complete_
         # state's own comment; the same refusal, on the same terms, for
         # a complete-but-state-dependent command (one with a `given`
         # reading its own prior state, which is what routes here instead
@@ -614,10 +639,10 @@ module Hecks
         # prior state this branch exists to supply), so only a genuine
         # creation reusing an already-occupied identity is a duplicate.
         # `SafeDepositBox.Rent` is exactly this shape — `given("box is
-        # vacant")` makes it state-dependent, so a second Rent used to
-        # silently hydrate the existing box as "prior state" and refuse
-        # for the wrong reason (not vacant) instead of the right one
-        # (already exists).
+        # vacant")` makes it state-dependent, so without this check a
+        # second Rent would silently hydrate the existing box as "prior
+        # state" and refuse for the wrong reason (not vacant) instead of
+        # the right one (already exists).
         if found && command.creates?
           raise(AlreadyExists, RefusalWording.render_site("AlreadyExists", "creating_duplicate",
                                                           command: command.hecks_name, aggregate: aggregate.hecks_name,
@@ -628,7 +653,7 @@ module Hecks
         found ? found.dup : Instance.new(aggregate: aggregate, id: id, args: args)
       end
 
-      # **The join, the dig, and the reading** — all shared with `EntityInterpreter`
+      # The join, the dig, and the reading — all shared with `EntityInterpreter`
       # now, in `Runtime::Identity`, rather than kept as two copies that could
       # only ever drift. See that module for the reasoning ; these three stay
       # here, at the old names, purely so nothing below has to change.

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

@@ -37,6 +37,8 @@ module Hecks
         # identifying the field, so a rule that reads it fails loud
         # instead of quietly wrong.
         class GuardState
+          # @param instance [Runtime::Instance] the record a `given`/`ensures`/
+          #   `invariant` rule reads state from
           def initialize(instance)
             @instance = instance
             @declared = instance.respond_to?(:aggregate) ? instance.aggregate.attributes.to_h { |a| [a.name, a] } : {}
@@ -55,8 +57,23 @@ module Hecks
             @projected = owner.respond_to?(:projected_fields) ? owner.projected_fields.to_h { |f| [f.name, f] } : {}
           end
 
+          # Reports whether `name` is a declared attribute, a projected field, or
+          # a key `instance`'s own state actually holds.
+          #
+          # @param name [String, Symbol] the field name to check
+          # @return [Boolean] true if `name` is readable one of those three ways
           def key?(name) = @declared.key?(name.to_sym) || @projected.key?(name.to_sym) || @instance.key?(name)
 
+          # Reads one field, the way a `given`/`ensures`/`invariant` rule expects
+          # absence to read.
+          #
+          # @param name [String, Symbol] the field name to read
+          # @return [Object, nil] the stored value; nil for a declared, optional
+          #   attribute the record predates
+          # @raise [Runtime::AttributeAbsent] if `name` is a declared, non-optional
+          #   attribute the record's own state does not hold
+          # @raise [Runtime::ProjectionAbsent] if `name` is a `projects` field the
+          #   record's own state does not hold
           def [](name)
             return @instance[name] if @instance.key?(name)
 
@@ -101,7 +118,7 @@ module Hecks
         # 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).
+        # wins over stored owner state.
         # `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
@@ -109,9 +126,9 @@ module Hecks
         # `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
+        # (ADR 0025 drops the `_id` suffix that once kept the two
         # apart by name, so `parent.state.merge(dereference(...))` is
-        # now load-bearing, not redundant) — plus its own references
+        # 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.
@@ -122,14 +139,34 @@ module Hecks
         # `enforce_ensures`, below — it is a fresh local binding a
         # `corrects` command introduces, not a real argument/state field
         # a caller could collide with by accident.
+        #
+        # @param subject [Runtime::Instance] the pre-mutation record a `given` is
+        #   checked against
+        # @param command [Class] the command class (`Bluebook::Command` subclass)
+        #   whose declared `givens` are checked
+        # @param args [Hash{String, Symbol => Object}] the offered command arguments,
+        #   readable by a given
+        # @param domain [String, Symbol] the domain a reference-typed argument is
+        #   dereferenced in
+        # @param declaring [Bluebook::Aggregate, Bluebook::Entity, nil] the construct
+        #   `command` is declared on; also checks `enforce_lifecycle_guard` when given
+        # @param parent [Runtime::Instance, nil] an entity command's own parent
+        #   aggregate record, readable as `parent.*`; nil for an aggregate command
+        # @param correction [Hash{Symbol => Object}] the `{as_name => payload}`
+        #   bindings a `corrects` command's located old event offers
+        # @return [void]
+        # @raise [Runtime::GivenNotMet] if a declared `given` does not hold
+        # @raise [Runtime::LifecycleRefused] if `declaring` is given and the command's
+        #   own `from:` guard refuses the record's current lifecycle state
+        # @raise [Bluebook::Expression::EvaluationError] if a given's own rule cannot
+        #   be evaluated (an unresolvable field, a bad comparison)
         def enforce_givens(subject, command, args, domain:, declaring: nil, parent: nil, correction: {})
           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
+          # dereferenced here at all: a `projects :customer_status, from:
+          # :"customer.status"` field is just `subject`'s own
+          # field, 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
@@ -180,16 +217,64 @@ module Hecks
         # one, made deliberately: `as:` reads as "the instance being
         # corrected," which is naturally the latest fact on record, not
         # an arbitrary one.
+        # Reads the durable event history a `corrects` mutation is judged against.
+        #
         # C9.2 (docs/semantics/bluebook-semantics.md) — a correction target
         # is judged against the record's durable history: the events the
         # aggregate's own store recorded (`AppendOnly#events`), which
         # survive a restart the way the Rust kernel's persisted
         # `emitted_<event>` flag does. The in-process log is the fallback
         # only for an adapter that records no readable history.
+        #
+        # @param domain [String, Symbol] the domain `aggregate` belongs to
+        # @param aggregate [Bluebook::Aggregate] the aggregate whose repository is read
+        # @return [Array<Runtime::Event>] the aggregate's own durably recorded events
+        #   if its repository keeps a readable log, otherwise the registry's in-process
+        #   event log
         def correction_history(domain, aggregate)
           @registry.repository(domain, aggregate).events || @registry.event_log
         end
 
+        # Locates each `:corrects` mutation's own already-emitted target event, and
+        # binds every `as:`-named one for `given`/`ensures` to reference.
+        #
+        # `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.
+        #
+        # Also locates the matched event now, not just its existence, and
+        # returns a `{as_name => payload}` bindings hash — one entry per
+        # `:corrects` mutation that named an `as:` — so `given`/`ensures`
+        # on a corrects-bearing command can reference the located old
+        # event by that name, the same shape `enforce_ensures`'s own
+        # `old:` binding already has (CommandBuilder#corrects_impl's own
+        # comment: `as:` was stored, from the start, specifically to be
+        # wired into the evaluator once a real runtime consumer existed —
+        # this is that consumer). `.reverse.find` — the most recent
+        # matching event, if this record has somehow emitted the same
+        # correction target more than once; the prior existence-only
+        # check never had to make this choice, so it's a genuinely new
+        # one, made deliberately: `as:` reads as "the instance being
+        # corrected," which is naturally the latest fact on record, not
+        # an arbitrary one.
+        #
+        # @param instance [Runtime::Instance] the record being corrected
+        # @param aggregate [Bluebook::Aggregate] the aggregate `instance` belongs to
+        # @param command [Class] the command class (`Bluebook::Command` subclass)
+        #   whose `:corrects` mutations are located
+        # @param domain [String, Symbol] the domain `aggregate` belongs to
+        # @return [Hash{Symbol => Object}] the located event's payload, keyed by
+        #   each `:corrects` mutation's own `as:` name; empty for a mutation with
+        #   no `as:`
+        # @raise [Runtime::NothingToCorrect] if a `:corrects` mutation names an
+        #   event `instance` has never emitted
         def enforce_correction_target(instance, aggregate, command, domain:)
           bindings = {}
           command.mutations.each do |mutation|
@@ -222,6 +307,16 @@ module Hecks
         # `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).
+        #
+        # @param declaring [Bluebook::Aggregate, Bluebook::Entity] the construct
+        #   whose lifecycle field is checked
+        # @param command [Class] the command class (`Bluebook::Command` subclass)
+        #   whose `from:` guard is checked
+        # @param subject [Runtime::Instance] the pre-mutation record to read the
+        #   current lifecycle state off
+        # @return [void]
+        # @raise [Runtime::LifecycleRefused] if `command` declares `from:` and the
+        #   record's current lifecycle state is not one of them
         def enforce_lifecycle_guard(declaring, command, subject)
           return unless command.from
 
@@ -232,12 +327,12 @@ module Hecks
           # 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
+          # refusal class, rather than hand-rolling its own wording
           # inline ("...only runs from..." vs. the template's "...moves
-          # it only from...") — two shapes for one refusal kind, so
+          # 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.
+          # property, a spec, a caller) would have to know both existed
+          # rather than one.
           raise LifecycleRefused,
                 RefusalWording.render_site("LifecycleRefused", "transition_blocked",
                                            command: command.hecks_name, field: lifecycle.field,
@@ -258,6 +353,25 @@ module Hecks
         # 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.
+        #
+        # @param subject [Runtime::Instance] the settled, post-mutation record an
+        #   `ensures` is checked against
+        # @param command [Class] the command class (`Bluebook::Command` subclass)
+        #   whose declared `ensures` are checked
+        # @param args [Hash{String, Symbol => Object}] the offered command arguments,
+        #   readable by an ensures unless `subject` shares the same field name
+        # @param old [Hash{Symbol => Object}, nil] the pre-mutation state, readable
+        #   as `old.*`; nil when `command` declares no ensures (dup skipped upstream)
+        # @param domain [String, Symbol] the domain a reference-typed argument is
+        #   dereferenced in
+        # @param parent [Runtime::Instance, nil] an entity command's own parent
+        #   aggregate record, readable as `parent.*`; nil for an aggregate command
+        # @param correction [Hash{Symbol => Object}] the `{as_name => payload}`
+        #   bindings a `corrects` command's located old event offers
+        # @return [void]
+        # @raise [Runtime::EnsuresNotMet] if a declared `ensures` does not hold
+        # @raise [Bluebook::Expression::EvaluationError] if an ensures's own rule
+        #   cannot be evaluated (an unresolvable field, a bad comparison)
         def enforce_ensures(subject, command, args, old:, domain:, parent: nil, correction: {})
           state = GuardState.new(subject)
           # S12, ADR 0025 — same boundary reasoning as enforce_givens
@@ -302,9 +416,21 @@ module Hecks
         # 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.
+        # ever read across a `reference_to` (verified by grep), so this
+        # is not a migration, just closing the same capability off here
+        # that was already unused.
+        #
+        # @param subject [Runtime::Instance] the settled aggregate record an
+        #   invariant is checked against
+        # @param aggregate [Bluebook::Aggregate] the aggregate whose declared
+        #   `invariants` are checked
+        # @param domain [String, Symbol] the domain `aggregate` belongs to, passed
+        #   through to `check_entity_invariants`
+        # @return [void]
+        # @raise [Runtime::InvariantViolation] if a declared invariant does not hold,
+        #   on `aggregate` itself or any of its entities
+        # @raise [Bluebook::Expression::EvaluationError] if an invariant's own rule
+        #   cannot be evaluated (an unresolvable field, a bad comparison)
         def enforce_invariants(subject, aggregate, domain:)
           state = GuardState.new(subject)
           attrs = {}
@@ -338,6 +464,17 @@ module Hecks
         # 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.
+        #
+        # @param owner_construct [Bluebook::Aggregate, Bluebook::Entity] the
+        #   construct whose nested entities are checked
+        # @param owner_instance [Runtime::Instance] the settled record holding
+        #   `owner_construct`'s own entity lists
+        # @param domain [String, Symbol] the domain `owner_construct` belongs to
+        # @return [void]
+        # @raise [Runtime::InvariantViolation] if a declared entity invariant does
+        #   not hold, on any element or its own nested entities
+        # @raise [Bluebook::Expression::EvaluationError] if an invariant's own rule
+        #   cannot be evaluated (an unresolvable field, a bad comparison)
         def check_entity_invariants(owner_construct, owner_instance, domain:)
           owner_construct.entities.each do |entity|
             next if entity.invariants.empty?
@@ -364,6 +501,20 @@ module Hecks
           end
         end
 
+        # Finds the lifecycle transition `command` admits from `subject`'s current
+        # state, if `declaring` declares a lifecycle and `command` moves it.
+        #
+        # @param declaring [Bluebook::Aggregate, Bluebook::Entity] the construct
+        #   whose lifecycle is checked
+        # @param command [Class] the command class (`Bluebook::Command` subclass)
+        #   to find a declared transition for
+        # @param subject [Runtime::Instance] the pre-mutation record to read the
+        #   current lifecycle state off
+        # @return [Bluebook::StateTransition, nil] the admitted transition, or nil
+        #   when `declaring` has no lifecycle or `command` declares no transition
+        # @raise [Runtime::LifecycleRefused] if `command` declares one or more
+        #   transitions, each constrained by its own `from:`, and none admits the
+        #   record's current lifecycle state
         def admissible_transition(declaring, command, subject)
           lifecycle = declaring.lifecycle
           return nil unless lifecycle

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

@@ -279,6 +279,9 @@ module Hecks
           bounded(current * amount, "multiply", current, amount, "*")
         end
 
+        # Bounds an attribute's current value into `[min, max]`, on a bare number or on
+        # the one numeric field the wrapping value object carries.
+        #
         # 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
@@ -286,6 +289,15 @@ module Hecks
         # it clamps whichever single numeric field the wrapping value
         # object carries (a synthesised wrapper always carries exactly
         # one, per Part 3a's auto-synthesis).
+        #
+        # @param current [Numeric, Runtime::Value, nil] the attribute's pre-dispatch value; nil
+        #   (never set) counts as 0
+        # @param bounds [Array<Numeric>] the two-element `[min, max]` range to clamp into
+        # @param target [Symbol, String] name of the attribute, used only to word a refusal
+        # @return [Numeric, Runtime::Value] the clamped value: a `Runtime::Value` when
+        #   `current` is one, otherwise a bare number the caller re-wraps
+        # @raise [Runtime::TypeMismatch] if `current` is a value object with no single
+        #   numeric field, or is neither numeric nor a value object
         def clamp(current, bounds, target)
           min, max = bounds
           # The same `current ||= 0` #arithmetic/#multiply both give a
@@ -294,11 +306,11 @@ module Hecks
           # 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.)
+          # is a real, separate bug: they do not silently treat an absent
+          # field as zero; they raise too, blaming a perfectly valid
+          # `amount` for not being an Integer when it is 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