hecks 0.3.0 → 1.0.0

data/lib/hecks/runtime/saga_interpreter.rb

@@ -4,6 +4,7 @@ require_relative "../bluebook/process_manager"
 require_relative "errors"
 require_relative "reaction_invocation"
 require_relative "value"
+require_relative "saga_pending_dispatch"
 
 module Hecks
   module Runtime
@@ -53,13 +54,34 @@ module Hecks
       # `unwind` go on to mutate in place; round-tripping through JSON
       # is also what guarantees the value is safe for every adapter that
       # itself calls `JSON.generate` on it.
-      def checkpoint(pm, correlation, instance, domain)
+      # `pending:` — see saga_pending_dispatch.rb. Injected into the
+      # WRITTEN copy of memory only, never into `instance[:memory]`
+      # itself: every other reader of a live instance's memory
+      # (`dispatch_args`'s "opening event memory" scope, the fuzzer's
+      # own round-trip/shape checks, `saga_spec.rb`'s exact-equality
+      # assertion against a fresh instance's seeded memory) sees exactly
+      # what it always did. The marker exists ONLY in the persisted
+      # blob, and only for as long as a dispatch cascade is genuinely
+      # in flight for this instance.
+      def checkpoint(pm, correlation, instance, domain, pending: nil)
+        memory = deep_copy(instance[:memory])
+        memory[SAGA_PENDING_DISPATCH_KEY] = pending if pending
         @registry.saga_persistence(domain).save_saga(
           process_manager: pm.name, correlation: correlation,
-          state: instance[:state], memory: deep_copy(instance[:memory])
+          state: instance[:state], memory: memory,
+          completed_compensations: deep_copy_array(instance[:completed_compensations])
         )
       end
 
+      # `deep_copy` is `JSON.parse(JSON.generate(hash), ...)`, which
+      # only accepts an OBJECT at the top level — `completed_compensations`
+      # is an ARRAY, so it gets its own wrap-and-unwrap rather than a
+      # second, parallel `deep_copy_array` reimplementing the same
+      # round-trip. `|| []` — an instance from before this field existed
+      # (or one that has never completed a compensable leg) rehydrates
+      # to an empty ledger, never nil.
+      def deep_copy_array(array) = deep_copy(list: array || [])[:list]
+
       def deep_copy(hash) = JSON.parse(JSON.generate(hash), symbolize_names: true)
 
       def begin_saga(pm, event, domain)
@@ -75,7 +97,23 @@ module Hecks
         created = @registry.saga_mutex.synchronize do
           next false if @registry.saga_instances[pm.name].key?(correlation)
 
-          instance = { state: pm.states.first, memory: event.payload }
+          # `.dup`, NOT THE SAME OBJECT — a fresh saga's own memory starts
+          # as a COPY of the starting event's own payload, never the
+          # payload itself. A saga's own memory is meant to be written
+          # into over its lifetime (remember-style, growing beyond what
+          # the starting event carried) ; the payload it was seeded from
+          # is a fact about something that ALREADY happened, logged and
+          # emitted before the saga ever saw it. Sharing the one Hash
+          # object between them means a write into the saga's own memory
+          # is silently ALSO a write into an already-emitted event's own
+          # payload — retroactively adding a field nothing announced.
+          # `event.payload` is deep-frozen by `Event#emit!` by the time
+          # this runs, so a naive in-place write here would raise
+          # FrozenError rather than corrupt silently — but the `.dup`
+          # still matters: it is what makes the saga's own memory a
+          # normal, writable Hash of its own, rather than one write away
+          # from crashing every future in-place `remember`.
+          instance = { state: pm.states.first, memory: event.payload.dup, completed_compensations: [] }
           @registry.saga_instances[pm.name][correlation] = instance
           checkpoint(pm, correlation, instance, domain)
           true
@@ -100,8 +138,9 @@ module Hecks
         correlation = saga_correlation(pm, event)
         return if correlation.to_s.empty?
 
-        record   = { process_manager: pm.name, on: event.name, instance: correlation }
-        instance = nil
+        record    = { process_manager: pm.name, on: event.name, instance: correlation }
+        instance  = nil
+        pre_state = nil
 
         advanced = @registry.saga_mutex.synchronize do
           instance = @registry.saga_instances[pm.name][correlation]
@@ -115,17 +154,87 @@ module Hecks
             next false
           end
 
+          pre_state = instance[:state]
           instance[:state] = handler.to_state
-          checkpoint(pm, correlation, instance, domain)
+          checkpoint(pm, correlation, instance, domain,
+                     pending: pending_marker(event, handler, pre_state, instance[:state]))
           true
         end
         return unless advanced
 
-        @registry.saga_log << record.merge(advanced: true, from: handler.from_state, to: handler.to_state)
+        settle_transition(pm, event, handler, instance, correlation, domain, record, pre_state)
+      end
+
+      def pending_marker(event, handler, from_state, to_state)
+        { on: event.name, from: from_state, to: to_state, dispatches: handler.dispatches.map(&:command_name) }
+      end
+
+      # THE SHARED TAIL of `advance_saga` and `unwind` — both are "guard,
+      # mutate, checkpoint-with-pending" under the mutex (kept separate
+      # per caller: `advance_saga`'s own guard also has to handle "no
+      # instance at all", `unwind`'s doesn't), then this: log the real
+      # observed transition, run the leg's dispatches, and clear the
+      # pending marker once that cascade — however it ended — is done.
+      def settle_transition(pm, event, handler, instance, correlation, domain, record, pre_state, drain_compensations: false)
+        # `from:`/`to:` are the INSTANCE'S OWN real pre/post state — read
+        # back from `instance` itself, never re-derived from `handler.
+        # from_state`/`handler.to_state` a second time. `Properties.saga_
+        # advances_follow_declared_handlers` (fuzzing/properties.rb) builds
+        # its OWN "declared edges" list from this SAME handler object (via
+        # `pm.handlers`), so a log entry that just echoed `handler.
+        # from_state`/`handler.to_state` back could never disagree with
+        # that list no matter what the runtime actually did — the entry
+        # and the thing it's checked against would be the identical fact,
+        # read twice. Logging the instance's own observed state instead
+        # means a future defect that moves an instance somewhere its own
+        # declared handler didn't say (a stale handler reference, the
+        # wrong handler picked, a second racing mutation) shows up as a
+        # real mismatch instead of vanishing into a tautology.
+        @registry.saga_log << record.merge(advanced: true, from: pre_state, to: instance[:state])
+
+        # DERIVED COMPENSATION FIRST, NEWEST-FIRST — only for `unwind`'s
+        # own call (`drain_compensations: true`): every leg THIS INSTANCE
+        # actually completed that declared its own `compensates`, popped
+        # and dispatched in reverse completion order, BEFORE any
+        # hand-written `on :refused` dispatches below — coexistence, not
+        # replacement. Drained (not just read) as it fires: a saga's own
+        # `on :refused` handler is guarded against re-entry by `unwind`'s
+        # own `instance[:state] == handler.from_state` check, so this can
+        # only ever run once per refusal — but draining rather than
+        # leaving the ledger populated is what makes that true by
+        # construction too, not only by the state guard.
+        if drain_compensations
+          compensations = instance[:completed_compensations] || []
+          deliver_derived_compensation(pm, compensations.pop, correlation, domain) until compensations.empty?
+          checkpoint(pm, correlation, instance, domain)
+        end
 
         handler.dispatches.each do |spec|
           deliver_saga_dispatch(pm, spec, event, instance, correlation, domain)
         end
+
+        # THE CLEAR — guarded by the SAME identity check `end_saga`'s own
+        # `.delete` return value implies: `deliver_saga_dispatch`'s
+        # `@door.reenter` can synchronously trigger this SAME correlation's
+        # `ends_on` event as a nested reaction (a leg's own dispatch is
+        # what makes the saga's terminal event fire), which deletes this
+        # row from the store before this line ever runs. Writing the
+        # clear unconditionally would RESURRECT a legitimately-ended saga
+        # — this diff's own first attempt did exactly that, caught by
+        # `saga_durability_spec.rb`'s "deletes the checkpoint once a saga
+        # genuinely ends" — so this only re-checkpoints when `instance`
+        # is still THE SAME object `@saga_instances` holds for this
+        # correlation (`.equal?`, not `==`: a fresh saga reborn under the
+        # same correlation between then and now is a DIFFERENT instance,
+        # and writing this stale one's state onto that one's row would be
+        # its own corruption). Under the mutex — dispatching is over by
+        # now, so this is not the reentrancy hazard `advance_saga`'s own
+        # comment warns about.
+        @registry.saga_mutex.synchronize do
+          next unless @registry.saga_instances[pm.name][correlation].equal?(instance)
+
+          checkpoint(pm, correlation, instance, domain, pending: nil)
+        end
       end
 
       def deliver_saga_dispatch(pm, spec, event, instance, correlation, domain)
@@ -166,7 +275,29 @@ module Hecks
         end
 
         attempt = 0
+        compensation_recorded = false
         begin
+          # RECORDED BEFORE DISPATCHING, not after `@door.reenter`
+          # returns — `@door.reenter` can recursively RE-ENTER THIS SAME
+          # saga interpreter (the event THIS dispatch emits triggers a
+          # LATER handler, which can itself refuse and unwind) entirely
+          # WITHIN this one call, before it ever returns here. Recording
+          # "after reenter succeeds" would be too late for a NESTED
+          # refusal to ever see this leg's own compensation — found
+          # live: Settlement's own AccountDebited handler refuses
+          # Account.Credit and unwinds from INSIDE Account.Debit's own
+          # `reenter` call, so "delivered: true, then record" left the
+          # ledger empty at the exact moment it was needed. Popped back
+          # off in the rescues below if THIS leg's own attempt is the
+          # one that failed — never left recorded for a refusal that
+          # was never this leg's own to compensate.
+          if spec.compensates && !compensation_recorded
+            resolved = dispatch_args(pm, spec.compensates, event, instance, correlation)
+            instance[:completed_compensations] << { command_name: spec.compensates.command_name, args: resolved }
+            checkpoint(pm, correlation, instance, domain)
+            compensation_recorded = true
+          end
+
           invocation = ReactionInvocation.build(
             registry:        @registry,
             verb:            qualified(spec.command_name, domain),
@@ -179,6 +310,7 @@ module Hecks
                         saga_correlation: { pm.correlation_head.to_s => correlation }, **invocation)
           @registry.saga_log << record.merge(delivered: true)
         rescue *DOMAIN_REFUSALS => error
+          unrecord_compensation(instance, correlation, domain, pm) if compensation_recorded
           # Same rule as the policy interpreter : a refusal by the target is
           # a recorded outcome, and the leg that raised it UNWINDS — see
           # `unwind`'s own comment for why the procedure runs its
@@ -187,6 +319,8 @@ module Hecks
           @registry.saga_log << record.merge(delivered: false, reason: error.message)
           unwind(pm, event, instance, correlation, domain)
         rescue StandardError => error
+          unrecord_compensation(instance, correlation, domain, pm) if compensation_recorded
+          compensation_recorded = false
           # A DEFECT, not a refusal — see PolicyInterpreter#deliver's own
           # comment for the full reasoning: the same DOMAIN_REFUSALS split,
           # and the same "the triggering command already succeeded and
@@ -222,6 +356,22 @@ module Hecks
         end
       end
 
+      # THE ROLLBACK HALF of `deliver_saga_dispatch`'s own speculative
+      # pre-record (that method's own comment for why it has to be
+      # speculative) — THIS leg's own attempt is the one that failed,
+      # so whatever was just pushed for it was never actually earned.
+      # `.pop`, not a search-and-delete: nothing else can have pushed
+      # AFTER this leg's own entry without this leg's own `@door.
+      # reenter` call having already returned (the recursive re-entry
+      # this whole mechanism exists for only ever runs BETWEEN this
+      # push and this leg's own return, and a nested refusal that
+      # consumed it already popped it itself — this rollback only ever
+      # runs for THIS leg's own, still-present entry).
+      def unrecord_compensation(instance, correlation, domain, pm)
+        instance[:completed_compensations].pop
+        checkpoint(pm, correlation, instance, domain)
+      end
+
       # A refused leg UNWINDS — the procedure runs the leg declared `on :refused`,
       # which is where the compensation lives. So does a leg that hit the
       # reaction-depth ceiling, and so does a leg that crashed and stayed
@@ -231,7 +381,7 @@ module Hecks
       # Until this existed a refusal was RECORDED and nothing else happened. The
       # wire's thousand was taken from the source, refused by the destination, and
       # sat nowhere until a human dispatched the reversal by hand ; banking's
-      # settlement left a debit standing with no credit and no reversal at all.
+      # settlement left a debit standing with no credit and no compensation at all.
       # Both bluebooks had written the compensating leg. Nothing armed it.
       #
       # A compensation that is itself refused does NOT unwind again, and needs no
@@ -242,7 +392,8 @@ module Hecks
         handler = pm.handler_for(REFUSED)
         return unless handler && instance
 
-        record = { process_manager: pm.name, on: REFUSED, instance: correlation }
+        record    = { process_manager: pm.name, on: REFUSED, instance: correlation }
+        pre_state = nil
 
         # Same non-reentrancy reasoning as `advance_saga`'s own comment —
         # the mutex covers only the check-and-mutate-and-checkpoint step.
@@ -253,16 +404,67 @@ module Hecks
             next false
           end
 
+          pre_state = instance[:state]
           instance[:state] = handler.to_state
-          checkpoint(pm, correlation, instance, domain)
+          checkpoint(pm, correlation, instance, domain,
+                     pending: pending_marker(event, handler, pre_state, instance[:state]))
           true
         end
         return unless advanced
 
-        @registry.saga_log << record.merge(advanced: true, from: handler.from_state, to: handler.to_state)
+        # See `settle_transition`'s own comment on `pre_state`/
+        # `instance[:state]` — the real observed transition, not a
+        # second read of the SAME handler object `Properties.saga_
+        # advances_follow_declared_handlers` checks this log against.
+        # `drain_compensations: true` — only `unwind`'s own call site
+        # fires derived compensation; `advance_saga`'s own call never
+        # does.
+        settle_transition(pm, event, handler, instance, correlation, domain, record, pre_state,
+                          drain_compensations: true)
+      end
 
-        handler.dispatches.each do |spec|
-          deliver_saga_dispatch(pm, spec, event, instance, correlation, domain)
+      # A DERIVED COMPENSATION — `entry[:args]` is already resolved
+      # (`record_completed_compensation`'s own comment for why), so this
+      # skips `dispatch_args` entirely and goes straight to delivery,
+      # through the SAME retry-on-defect path an ordinary forward leg
+      # uses. Never re-enters `unwind` on its own failure — a
+      # compensation that itself refuses is a real, pre-existing gap
+      # this feature makes visible rather than closes (see this file's
+      # own class-level notes); `compensation_failed: true` tags it
+      # distinctly in the log instead of recording it identically to an
+      # ordinary failed delivery, and every OTHER completed compensation
+      # still queued still gets its own attempt.
+      def deliver_derived_compensation(pm, entry, correlation, domain)
+        record = { process_manager: pm.name, instance: correlation, dispatch: entry[:command_name] }
+
+        attempt = 0
+        begin
+          invocation = ReactionInvocation.build(
+            registry:        @registry,
+            verb:            qualified(entry[:command_name], domain),
+            projected:       entry[:args],
+            explicit:        true,
+            passthrough:     [pm.correlation_head],
+            source_receiver: nil
+          )
+          @door.reenter(qualified(entry[:command_name], domain),
+                        saga_correlation: { pm.correlation_head.to_s => correlation }, **invocation)
+          @registry.saga_log << record.merge(delivered: true, compensation: true)
+        rescue *DOMAIN_REFUSALS => error
+          @registry.saga_log << record.merge(delivered: false, reason: error.message, compensation: true, compensation_failed: true)
+        rescue StandardError => error
+          attempt += 1
+          if attempt <= MAX_DEFECT_RETRIES
+            @registry.saga_log << record.merge(delivered: false, reason: error.message, compensation: true,
+                                               defect: true, error_class: error.class.name,
+                                               attempt: attempt, retrying: true)
+            retry
+          end
+
+          warn "[hecks] defect compensating saga #{pm.name} — instance #{correlation.inspect} " \
+               "dispatching #{entry[:command_name]} after #{attempt} attempts: #{error.class}: #{error.message}"
+          @registry.saga_log << record.merge(delivered: false, reason: error.message, compensation: true,
+                                             defect: true, error_class: error.class.name, compensation_failed: true)
         end
       end
 

data/lib/hecks/runtime/saga_pending_dispatch.rb

@@ -0,0 +1,45 @@
+module Hecks
+  module Runtime
+    # THE ONE SHARED CONSTANT between `SagaInterpreter` (the writer) and
+    # `Registry::SagaPersistence#rehydrate_sagas!` (the reader) for a
+    # scoped, minimal answer to the saga-durability review's item 8 (a
+    # durable outbox): a marker that survives exactly the window a crash
+    # in `advance_saga`/`unwind` can otherwise hide.
+    #
+    # THE PROBLEM THIS CLOSES — `checkpoint` persists a saga's new state
+    # BEFORE the leg that justifies it (`handler.dispatches`) runs, and
+    # deliberately so: the mutex it holds is not reentrant, and a
+    # dispatch can re-enter this same interpreter. If the process dies
+    # in that window, the store says the transition happened and there
+    # is no record that its dispatch(es) never ran — not a refusal (the
+    # domain never got asked), not a defect (nothing raised), just
+    # silence indistinguishable from a leg that finished cleanly.
+    #
+    # THE FIX — `checkpoint` now writes this key into the SAME already-
+    # durable `memory` blob (no new column, no adapter/schema change:
+    # `memory` is already an opaque, adapter-agnostic JSON blob every
+    # `save_saga` implementation round-trips verbatim) whenever it
+    # checkpoints a state a dispatch cascade hasn't run for YET, and
+    # clears it (a second checkpoint, `pending: nil`) once that cascade
+    # — success, refusal-compensated, defect-compensated, or ceiling-
+    # compensated — has actually run. A crash between those two writes
+    # leaves the marker standing; `rehydrate_sagas!` strips it back out
+    # of the LIVE instance's own `:memory` (so no dispatch/`given`/
+    # fuzzer/doc consumer of a saga's memory ever sees this key — it
+    # exists only in the persisted blob) and surfaces it loudly instead.
+    #
+    # WHAT THIS DELIBERATELY DOES NOT DO — auto-redrive the pending leg.
+    # Redelivering a dispatch whose outcome is genuinely unknown is only
+    # safe with idempotent delivery (the downstream command recognizing
+    # and no-op'ing a duplicate), which hecks's command/event pipeline
+    # has no mechanism for today. Blindly re-dispatching without that is
+    # how a stalled transfer becomes a DOUBLE-CREDITED one — a strictly
+    # worse defect than the stall it would replace. So this is real,
+    # durable, crash-surviving VISIBILITY into exactly what a stalled
+    # saga was doing when the process died — the missing half of "no
+    # reconciliation pass exists" — not the full pending → claimed →
+    # delivered outbox `future-features.md` still lists as unbuilt, and
+    # not a substitute for it.
+    SAGA_PENDING_DISPATCH_KEY = :__hecks_saga_pending_dispatch__
+  end
+end

data/lib/hecks/runtime/value/admission.rb

@@ -14,7 +14,7 @@ module Hecks
           discriminant = value_object.attributes.first.name
           offered      = fields[discriminant]
           admitted     = value_object.members.map { |member| member[discriminant].to_s }
-          return if admitted.include?(offered.to_s)
+          return if value_object.members.any? { |member| member_matches?(member, fields) }
 
           raise InvariantViolation,
                 RefusalWording.render("InvariantViolation", "closed_set_member",
@@ -22,6 +22,24 @@ module Hecks
                                       admitted: admitted.map(&:inspect).join(", "), offered: offered.inspect)
         end
 
+        # EVERY DECLARED FIELD, not only the discriminant — a multi-column
+        # `member` row (`StatementFrequency`'s `cadence`/`retention_months`/
+        # `paper_fee_cents`, statements.bluebook) names a whole tuple, and a
+        # caller offering the right `cadence` with the wrong
+        # `retention_months` is not a genuine member just because the FIRST
+        # column happened to match. `admitted.include?(offered.to_s)` above
+        # used to be the entire check, so it stopped at that first column —
+        # confirmed live: `Value.build(StatementFrequency, cadence:
+        # "monthly", retention_months: 999, paper_fee_cents: 999)` was
+        # admitted outright, no member of the closed set declares that row.
+        # A single-field set (`AccountKind`, `LedgerDirection`, ...) has
+        # exactly one key here, so this reduces to the original discriminant-
+        # only comparison for every set that only ever had one column to
+        # begin with — same refusal, same wording, unchanged.
+        private def member_matches?(member, fields)
+          member.all? { |field, value| fields[field].to_s == value.to_s }
+        end
+
         # THE SAME REFUSAL, FOR A SET NAMED SOMEWHERE ELSE.
         #
         # `admit_member` above refuses a non-member when the value object BEING

data/lib/hecks/runtime/value/coercion.rb

@@ -121,7 +121,13 @@ module Hecks
             segments = path.to_s.split(".")
             segments.shift if direct_head && segments.first == direct_head
             segments.reduce(materialized) do |held, segment|
-              held.is_a?(Hash) ? (held[segment.to_sym] || held[segment]) : nil
+              next nil unless held.is_a?(Hash)
+
+              # `key?` decides which spelling answers, never `||` — a
+              # genuinely-held `false` must not fall through to the
+              # other spelling (usually absent) and read as `nil`.
+              sym = segment.to_sym
+              held.key?(sym) ? held[sym] : held[segment]
             end
           end
           return value if parts.any? { |part| part.nil? || (part.respond_to?(:empty?) && part.empty?) }
@@ -197,6 +203,20 @@ module Hecks
         # value_object(name)`, so callers with no aggregate in reach
         # (`Value#with`, always re-setting an already-scalar arithmetic
         # field) simply skip this and keep their prior behavior.
+        # RECURSES INTO EACH NESTED FIELD'S OWN VALIDATION TOO, not only its
+        # shape — found live alongside the shape bug this method's header
+        # already describes: a nested `Price`/`Size` (a value-object-typed
+        # field of ANOTHER value object, e.g. `Pizza.price_cents`,
+        # `Pizza.size`) had its Hash shape normalized here but never ran
+        # `validate!` — `build`, below, only ever validated the OUTER value
+        # object's own direct fields, so a negative `price_cents.cents` or an
+        # out-of-`one_of` `size.value` sailed through a `Pizza`-typed command
+        # argument untouched, while the exact same nested type declared as a
+        # direct, top-level command attribute (`SafeDepositBox.Rent`'s own
+        # `attribute :size, Size`) was already checked correctly. `apply_
+        # defaults` runs first, same as the outer value object gets in
+        # `build`, so a nested field's own default is filled in before its
+        # own invariants read it.
         def normalize_composite_fields(aggregate, value_object, fields)
           return fields unless aggregate&.respond_to?(:value_object)
 
@@ -209,17 +229,27 @@ module Hecks
             nested = value_object_for(aggregate, attribute.type)
             next unless nested
 
-            fields[attribute.name] = normalize_composite_fields(aggregate, nested, fields_for(nested, attribute.name, raw))
+            nested_fields = apply_defaults(nested, fields_for(nested, attribute.name, raw))
+            nested_fields = normalize_composite_fields(aggregate, nested, nested_fields)
+            validate!(nested, nested_fields)
+            fields[attribute.name] = nested_fields
           end
 
           fields
         end
 
-        def build(value_object, fields, aggregate = nil)
-          fields = value_object.attributes.each_with_object(fields.transform_keys(&:to_sym)) do |attribute, completed|
+        def apply_defaults(value_object, fields)
+          value_object.attributes.each_with_object(fields) do |attribute, completed|
             completed[attribute.name] = attribute.default unless completed.key?(attribute.name) || attribute.default.nil?
           end
-          fields = normalize_composite_fields(aggregate, value_object, fields)
+        end
+
+        # THE FULL DOOR A VALUE OBJECT'S OWN FIELDS PASS THROUGH — shared by
+        # `build` (the outer value object) and `normalize_composite_fields`
+        # (every nested one), so a nested `Price`/`Size` is refused exactly
+        # the same way, with exactly the same wording, as the identical type
+        # declared directly on a command.
+        def validate!(value_object, fields)
           admit_member(value_object, fields)
           check_admitted(value_object, fields)
           check_numeric_fields(value_object, fields)
@@ -233,6 +263,12 @@ module Hecks
                                         name: value_object.hecks_name, description: invariant.description,
                                         offered: canonical_fields(fields))
           end
+        end
+
+        def build(value_object, fields, aggregate = nil)
+          fields = apply_defaults(value_object, fields.transform_keys(&:to_sym))
+          fields = normalize_composite_fields(aggregate, value_object, fields)
+          validate!(value_object, fields)
           new(value_object, fields)
         end
 
@@ -424,12 +460,41 @@ module Hecks
             next unless expected
 
             given = fields[attribute.name]
-            next if given.nil? || given.is_a?(expected)
+            next if given.nil?
 
-            raise TypeMismatch,
-                  RefusalWording.render("TypeMismatch", "numeric_field",
-                                        type: value_object.hecks_name, field: attribute.name,
-                                        expected: attribute.type, offered: Rendering.describe(given))
+            unless given.is_a?(expected)
+              raise TypeMismatch,
+                    RefusalWording.render("TypeMismatch", "numeric_field",
+                                          type: value_object.hecks_name, field: attribute.name,
+                                          expected: attribute.type, offered: Rendering.describe(given))
+            end
+
+            # PRD 05 (numeric-boundary-coverage) — `given.is_a?(expected)`
+            # alone waves a NaN or an Infinity straight through: both are
+            # real `Float`s, so `is_a?(Numeric)`/`is_a?(Float)` is true for
+            # either. Never exercised before this, because
+            # `ValueGenerator::FLOAT_EDGE_CASES` had no non-finite value in
+            # it — the fuzzer could not have found this on its own until
+            # the table was widened alongside this fix. Left unchecked, a
+            # non-finite Float reaches `CommandRules::Arithmetic#clamp`
+            # (`current.clamp(min, max)` — `ArgumentError: comparison of
+            # Float with X failed`, a genuine Ruby-level crash, not a
+            # domain refusal, exactly the same failure mode this method's
+            # own header describes for a mistyped field) or all the way to
+            # storage, where `JSON.generate`/`#to_json` raises
+            # `JSON::GeneratorError: NaN/Infinity not allowed in JSON` the
+            # moment anything tries to persist or replay it — again a raw
+            # crash, not a refusal. `-0.0` is deliberately NOT refused
+            # here: it IS finite, round-trips through JSON as `-0.0`
+            # cleanly (confirmed empirically), and is a legitimate,
+            # meaningful float value (a signed zero), not a corruption
+            # risk — only NaN and +/-Infinity are.
+            if given.is_a?(Float) && !given.finite?
+              raise TypeMismatch,
+                    RefusalWording.render("TypeMismatch", "non_finite_field",
+                                          type: value_object.hecks_name, field: attribute.name,
+                                          offered: Rendering.describe(given))
+            end
           end
         end
 

data/lib/hecks/runtime.rb

@@ -50,10 +50,6 @@ require_relative "runtime/policy_interpreter"
 require_relative "runtime/saga_interpreter"
 require_relative "runtime/dispatcher"
 require_relative "runtime/rebuild_sweep"
-require_relative "runtime/era_guard"
-require_relative "runtime/storage_shape"
-require_relative "runtime/era_tamper"
-require_relative "runtime/era_check"
 require_relative "runtime/tenant_check"
 require_relative "runtime/loader"
 
@@ -89,7 +85,23 @@ module Hecks
       # Bind the ambient caller (see Runtime::Caller) for the duration of
       # the block — who a command's declared `role`, if any, is checked
       # against.
-      def as_caller(role:, actor_id: nil, &block) = Caller.as(role: role, actor_id: actor_id, &block)
+      #
+      # `as_of:` is OPTIONAL, same opt-in shape as `actor_id:` — a caller
+      # that wants a Governance `RoleAssignment`'s `starts_at` enforced
+      # passes `as_of: Ports::Clock.now(registry)` here, at the door,
+      # exactly where `cli_runner.rb` already merges `Clock.now` into a
+      # command's own args. Nothing on the dispatch path calls the clock
+      # itself — see `Ports::Clock`'s own header for why — so an unbound
+      # `as_of` leaves `starts_at` unchecked, exactly as before.
+      #
+      # `scope:` is OPTIONAL too — a caller that states which scope it is
+      # acting in gets that scope checked against the matching
+      # `RoleAssignment`'s own `scope`, not just its `role_name`. See
+      # `Runtime::Caller::Current`'s own header for why this lives here
+      # rather than as a command-level DSL construct.
+      def as_caller(role:, actor_id: nil, as_of: nil, scope: nil, &block)
+        Caller.as(role: role, actor_id: actor_id, as_of: as_of, scope: scope, &block)
+      end
     end
   end
 end