hecks 0.3.0 → 1.0.0

data/lib/hecks/bluebook/meta_validator.rb

@@ -8,16 +8,39 @@ module Hecks
     # `lib/hecks/language/bluebook/` declares what a bluebook IS —
     # Chapter, Root, Verb, Shape, Ask, Piece, and the rest, split across files
     # by domain concept and merged into one chapter at load time (see
-    # GRAMMAR_FILES below) — and carries the language's rules as `given` and
-    # `invariant` rather than as `raise Malformed` scattered across seven
-    # builder files. This replays a built IR into that domain and turns any
-    # refusal into a Malformed, so the meta-domain is what actually judges
-    # rather than a description sitting beside the code.
+    # GRAMMAR_FILES below). This replays a built IR into that domain and turns
+    # any refusal into a Malformed, so the meta-domain is what actually judges
+    # rather than a description sitting beside the code — for whatever rules
+    # it carries. `spec/meta_rules_spec.rb`'s own header names the plan: port
+    # the language's rules OUT of builder `raise Malformed` calls and INTO
+    # `given`/`invariant` here, where they are declarations any reader of the
+    # meta-domain can consume instead of behavior buried in a builder.
     #
-    # Delete language/bluebook/ and validation stops. That is the whole
-    # point : a self-description that only describes is indistinguishable from
-    # enforcement, and the first version of this file was deleted for exactly
-    # that reason.
+    # THIS MIGRATION IS PARTIAL, NOT DONE. As of this writing the meta-domain
+    # declares 62 given/invariant/ensures rules (`Hecks::QueryIR.collect_rules`
+    # against `grammar_registry.bluebook("Bluebook")` enumerates them) —
+    # `spec/meta_rule_reachability_spec.rb` is what proves, per declaration,
+    # not per verb, that most of them still lack a spec exercising the
+    # refusal at all (see that file's own KNOWN_GAPS for the current count).
+    # Meanwhile `lib/hecks/bluebook/dsl/` still carries well over a hundred
+    # `raise Malformed` calls of its own — some are genuinely pre-IR
+    # construction errors (arity, argument shape) that cannot become
+    # meta-domain rules, and some are exactly the semantic kind this file
+    # claims to have moved (see `aggregate_builder.rb`'s `seal_*` passes:
+    # a mutation into a field the aggregate never declares, a lifecycle guard
+    # on an aggregate with no lifecycle). No doc currently inventories which
+    # is which, or tracks migrating the latter — that inventory is the actual
+    # next step, not a "delete the folder" thought experiment.
+    #
+    # So: "delete language/bluebook/ and validation stops" is true for the 62
+    # rules actually declared here, and false for whatever a builder's own
+    # `raise Malformed` still checks — the language does not yet own its own
+    # enforcement end to end, and this comment used to claim it already did.
+    # The self-hosting mechanism itself is real and is the point worth
+    # keeping : a self-description that only describes is indistinguishable
+    # from enforcement, and the first version of this file was deleted for
+    # exactly that reason. What is not yet real is that self-hosting being
+    # the WHOLE of validation.
     #
     # The meta-domain is loaded ONCE and its registry reused ; each bluebook is
     # judged in a fresh in-memory store so no domain can see another's records.
@@ -131,6 +154,12 @@ module Hecks
           # dead code, never actually invoked.
           builder = registry.bluebook_builder(name) { raise "internal: no open builder for #{name}" }
           builder.resolve_pending_chapter_givens!
+          # THE ENTITY-SCOPED ANALOGUE, one level down — same reason,
+          # same timing: a bare entity-level given left PENDING by any
+          # file of this chapter (`EntityBuilder#pending_chapter_entity_
+          # given`) must resolve before anything below reads a piece's
+          # own `Given` fields too.
+          builder.resolve_pending_chapter_entity_givens!
 
           # `BluebookBuilder#build` skipped its own whole-chapter battery
           # (hops, projected fields, correlation keys, event shapes,
@@ -147,7 +176,48 @@ module Hecks
         end
       end
 
-      def self.disabled? = ENV["HECKS_META_VALIDATION"] == "off"
+      # `&& !@forcing_fixpoint` — see `while_forcing_fixpoint` below, whose own
+      # window must win even while a growth spec's `while_disabled` is open,
+      # for the reason recorded there. Otherwise the SAME stack-restore shape
+      # `while_shadow_parsing`/`while_forcing_fixpoint` use, not a bare env
+      # toggle any more — it used to be exactly that (`ENV["HECKS_META_
+      # VALIDATION"] == "off"`, read directly, with no `previous`/`ensure` of
+      # its own), and the gap between "bare toggle" and "stack-restore" was
+      # not cosmetic: a test's temporary window could reach code it was never
+      # meant to touch. If `grammar_registry`'s ONE-TIME lazy build (below)
+      # happened to land inside that window, EVERY language chapter got
+      # cached in its raw, never-judged form for the rest of the process —
+      # `unmark_scalar`'s String->Integer/Boolean fix (assembly/marks.rb)
+      # never ran, so a `Command`'s own `required: true` stayed
+      # `required: "true"` forever after, permanently memoized. Found live:
+      # an intermittent, parallel_rspec-only ir_golden_spec.rb failure,
+      # order-dependent on whether identifier_numeric_coercion_growth_spec.rb's
+      # disabled-validation window raced the ONE lazy build in its own worker
+      # process — reproduced in isolation by disabling validation before the
+      # first `grammar_registry` call. `&& !@forcing_fixpoint` was the first
+      # fix and is kept ; converting `@disabled` itself to this shape closes
+      # the gap for every OTHER caller of `while_disabled`, not just the one
+      # race that was actually observed — nothing outside this file reads
+      # `ENV["HECKS_META_VALIDATION"]` any more (confirmed: every one of the
+      # dozen growth specs that used to hand-roll `previous = ENV[...] ;
+      # ENV[...] = "off" ; ... ; ensure ENV[...] = previous` now calls
+      # `while_disabled` instead), so there is no bare global left to race.
+      def self.disabled? = @disabled && !@forcing_fixpoint
+
+      # THE SAME STACK-RESTORE SHAPE `while_shadow_parsing`/`while_forcing_
+      # fixpoint` USE. This toggle's real, intended use is a growth spec
+      # that boots a scratch bluebook from a tempfile and wants the runtime
+      # behaviour without the validation overhead ; that is always a single
+      # bounded window around one boot, never a flag meant to survive past
+      # it, so the flag itself is scoped in the same `previous`/`ensure`
+      # shape rather than a plain assignment a caller could forget to undo.
+      def self.while_disabled
+        previous  = @disabled
+        @disabled = true
+        yield
+      ensure
+        @disabled = previous
+      end
 
       # ADR 0025's own prerequisite (docs/dsl-work-slices.md, S0a): a word
       # a later slice removes from the LIVE grammar must still parse
@@ -175,6 +245,21 @@ module Hecks
         @shadow_parsing = previous
       end
 
+      # THE SAME STACK-RESTORE SHAPE `while_shadow_parsing` USES, for the
+      # same reason: whatever this wraps must never see `disabled?` answer
+      # true, however a test elsewhere has the env toggle set at that
+      # exact moment. Only `grammar_registry`'s own one-time build (below)
+      # wraps itself in this — nothing else needs it, and nothing else
+      # should reach for it just to dodge `disabled?` for a domain
+      # bluebook, which is precisely the toggle's real, intended use.
+      def self.while_forcing_fixpoint
+        previous          = @forcing_fixpoint
+        @forcing_fixpoint = true
+        yield
+      ensure
+        @forcing_fixpoint = previous
+      end
+
       # The same bluebook judged twice gets the same verdict, and a suite reloads
       # its fixtures constantly — banking alone is ~200 dispatches per build.
       # Keyed on the IR itself, so a CHANGED bluebook is always re-judged.
@@ -348,9 +433,14 @@ module Hecks
           # judged from here on is judged by the language the language itself
           # produced. Outside load_grammar_into on purpose : its ensure clears
           # @bootstrapping, and call() must see bootstrapping? == false to do
-          # anything at all.
-          LANGUAGE_CHAPTERS.each { |name| registry.add_bluebook(call(registry.bluebook(name))) }
-          load_attached_grammar_into(registry)
+          # anything at all. `while_forcing_fixpoint`-wrapped so a growth
+          # spec's own `while_disabled` window can never leave this
+          # ONE-TIME build cached in its raw, never-judged form — see
+          # `disabled?`'s own comment.
+          while_forcing_fixpoint do
+            LANGUAGE_CHAPTERS.each { |name| registry.add_bluebook(call(registry.bluebook(name))) }
+            load_attached_grammar_into(registry)
+          end
           # Stamped LAST, keyed by this registry's own identity rather than
           # a bare boolean — a manual reset (fixpoint_spec.rb's own
           # `@grammar_registry = nil`) makes @grammar_registry not equal

data/lib/hecks/bluebook/model_check.rb

@@ -46,18 +46,51 @@ module Hecks
       # states), so a state nothing ever transitions into or out of no
       # longer exists to be unreachable — the finding this allowlisted
       # cannot occur any more, by construction.
-      ALLOWED_FINDINGS = {}.freeze
+      #
+      # "banking"/NotifyOnClosure, FlagKeyReturn — real, confirmed
+      # findings, not bugs to fix. `across "Notifications"` names a
+      # domain that does not exist anywhere in this repo — no
+      # Notifications bluebook, no hecksagon, nothing to `uses_framework`
+      # or `subscribe` to. This is deliberate: `spec/runtime/policy_spec.
+      # rb` (a test literally named "records a reaction it cannot
+      # deliver rather than swallowing it") and `lib/hecks/runtime/
+      # errors.rb`'s own `UnknownVerb` comment both treat "target domain
+      # not loaded" as the EXPECTED outcome for it — Notifications is
+      # used on purpose to exercise the undelivered-reaction runtime
+      # path, not left half-built. There is no real `subscribe` line to
+      # add (no event of Notifications' own to name) and no real domain
+      # to point `uses_framework` at.
+      ALLOWED_FINDINGS = {
+        "banking" => [
+          [:unacknowledged_relationship, "NotifyOnClosure"],
+          [:unknown_target_domain, "NotifyOnClosure"],
+          [:unacknowledged_relationship, "FlagKeyReturn"],
+          [:unknown_target_domain, "FlagKeyReturn"]
+        ]
+      }.freeze
 
       module_function
 
-      def call(bluebook)
+      # `hecksagon:`/`known_domains:` — both optional, both `nil`-safe
+      # (every existing caller with no sibling hecksagon, or checking one
+      # domain in isolation, behaves exactly as before). `hecksagon` is
+      # THIS bluebook's own sibling wiring file, if the caller loaded one
+      # (see `emitted_events`'s own comment on why a caller that didn't
+      # simply finds none, correctly). `known_domains` is the caller's
+      # OWN corpus-wide view — every bluebook/hecksagon name it has
+      # booted anywhere, across every domain it has looked at, not just
+      # this one — used only to catch a typo'd `across`/`uses_framework`
+      # target; see `cross_domain_policy_findings`'s own comment for why
+      # this can only ever be a corpus-scoped heuristic, never a general
+      # correctness guarantee.
+      def call(bluebook, hecksagon: nil, known_domains: nil)
         findings = []
         bluebook.aggregates.each do |aggregate|
           findings.concat(lifecycle_findings(aggregate, aggregate))
           aggregate.entities.each { |entity| findings.concat(lifecycle_findings(aggregate, entity)) }
         end
         bluebook.process_managers.each { |pm| findings.concat(saga_findings(bluebook, pm)) }
-        bluebook.policies.each { |policy| findings.concat(policy_findings(bluebook, policy)) }
+        bluebook.policies.each { |policy| findings.concat(policy_findings(bluebook, policy, hecksagon, known_domains)) }
         findings
       end
 
@@ -200,6 +233,23 @@ module Hecks
                                              "declares no command at — cross-domain dispatch is out of this " \
                                              "checker's scope, same as CommandRules#resolve_references")
           end
+
+          # A `compensates` DECLARED WITH NOWHERE TO EVER FIRE — the exact
+          # shape of the real bug this whole feature closes ("the
+          # reversal was written and never armed"), caught at build/
+          # model-check time instead of discovered in production. No
+          # handler anywhere answers REFUSED (`pm.saga?` false) means
+          # `SagaInterpreter#unwind` never runs for this process
+          # manager at all, so a declared `compensates` is structurally
+          # unreachable — not a warning about style, a dead declaration.
+          if !pm.saga? && handler.dispatches.any?(&:compensates)
+            handler.dispatches.select(&:compensates).each do |dispatch|
+              findings << Finding.new(kind: :unarmed_compensation, severity: :error, subject: pm.name,
+                                      message: "#{dispatch.command_name} compensates #{dispatch.compensates.command_name}, " \
+                                               "but no handler anywhere in this saga answers a refusal — the " \
+                                               "compensation is declared and can never fire")
+            end
+          end
         end
 
         if pm.saga? && !reached.include?(pm.saga.from_state)
@@ -240,8 +290,8 @@ module Hecks
 
       # ── policies ───────────────────────────────────────────────────────
 
-      def policy_findings(bluebook, policy)
-        return [] if policy.target_domain # cross-domain: CommandRules skips it too; so does this checker.
+      def policy_findings(bluebook, policy, hecksagon, known_domains)
+        return cross_domain_policy_findings(policy, hecksagon, known_domains) if policy.target_domain
 
         emitted = emitted_events(bluebook)
         findings = []
@@ -276,6 +326,83 @@ module Hecks
         findings
       end
 
+      # ── cross-domain policies (Context Mapping) ───────────────────────
+      #
+      # `uses_framework "X"` already IS a Shared Kernel relationship — it
+      # merges X's own bluebook into THIS registry, no boundary. A cross-
+      # domain `policy ... across: "X"` already IS a Customer/Supplier
+      # relationship — it dispatches into X over real cross-Lambda RPC in
+      # the Rust host (`rust/host/src/lambda_client.rs`). Neither is a new
+      # word; this makes the CHOICE between them checked instead of a
+      # prose comment nobody enforces (`examples/banking/bluebook/
+      # banking.hecksagon`'s own hand-written note explaining why
+      # Compliance is reached via `across`, never `uses_framework`).
+      #
+      # NO NEW KEYWORD ANYWHERE — ADR 0025 principle 1 ("one idea, one
+      # spelling") refuses a `relationship:`/`as:` argument that would
+      # just restate, as a string, the fact the chosen keyword (
+      # `uses_framework` vs `across`) already states completely. The
+      # DDD vocabulary (Shared Kernel, Customer/Supplier) lives here, in
+      # the finding's own name and this comment, and in prose docs — not
+      # in the grammar.
+      def cross_domain_policy_findings(policy, hecksagon, known_domains)
+        return [] unless hecksagon # no sibling hecksagon loaded — nothing to check a relationship against.
+
+        target = policy.target_domain
+        findings = []
+
+        if hecksagon.framework_members.include?(target)
+          # SHARED KERNEL AND CUSTOMER/SUPPLIER ARE MUTUALLY EXCLUSIVE
+          # CLAIMS about the SAME target — `uses_framework` means "X is
+          # loaded in-process, right here"; `across` means "X is a
+          # separate deployment, reached only by RPC." Declaring both is
+          # either a pointless RPC to a domain already local, or a
+          # `uses_framework` that isn't really doing what its name says.
+          findings << Finding.new(kind: :contradictory_relationship, severity: :error, subject: policy.name,
+                                  message: "across #{target.inspect} dispatches over RPC (Customer/Supplier), " \
+                                           "but this hecksagon also uses_framework #{target.inspect} (Shared " \
+                                           "Kernel) — #{target} is already loaded in-process here, so the two " \
+                                           "relationship declarations contradict each other for the same " \
+                                           "target domain")
+        elsif hecksagon.subscriptions.none? { |subscribed| Naming.qualifier(subscribed) == target }
+          # THIS IS WHAT FINALLY GIVES `subscribe` REAL TEETH — checked
+          # here, at model-check time, still never routed at runtime
+          # (nothing dispatches off a `subscribe` line; see hecksagon.md's
+          # own "checked, not routed" section). ADR 0025 names `subscribe`
+          # by number as failing the corpus-use bar; this is the real use.
+          findings << Finding.new(kind: :unacknowledged_relationship, severity: :error, subject: policy.name,
+                                  message: "across #{target.inspect} declares a Customer/Supplier " \
+                                           "relationship, but nothing in this hecksagon records the " \
+                                           "expectation — add subscribe \"#{target}.SomeEvent\" for what " \
+                                           "you expect back from it, or uses_framework #{target.inspect} to " \
+                                           "attach it in-process instead")
+        end
+
+        # TYPO DETECTION, DELIBERATELY WEAKER — `known_domains` can only
+        # ever be a MONOREPO-SCOPED heuristic: a real external hecks
+        # consumer's own domain (this repo's own embryonaut/lifeadelics-
+        # shaped case) lives in a genuinely separate repository this
+        # corpus scan can never see, so a target this check cannot find
+        # is "unknown to THIS corpus," never proof of a typo. Two real,
+        # legitimate reasons a target is unresolvable — genuinely
+        # undefined by design (the corpus's own "Notifications," used
+        # deliberately to exercise the undelivered-reaction runtime path)
+        # and real-but-external (a separate repository) — both go in
+        # `ALLOWED_FINDINGS`, the same judged-exception mechanism this
+        # file already uses for ExternalSettlement, rather than a new
+        # keyword invented to declare "this one's fine."
+        if known_domains && !known_domains.include?(target)
+          findings << Finding.new(kind: :unknown_target_domain, severity: :error, subject: policy.name,
+                                  message: "across #{target.inspect} names a domain nowhere in the corpus " \
+                                           "this check has booted — a typo, or a real domain intentionally " \
+                                           "outside this corpus (undefined by design, or living in a " \
+                                           "separate repository) belongs in ALLOWED_FINDINGS, named and " \
+                                           "explained, not silently assumed correct")
+        end
+
+        findings
+      end
+
       # ── shared enumeration ────────────────────────────────────────────
 
       # A PORT OPERATION EMITS TOO — the primary/driving port an adapter

data/lib/hecks/bluebook/pattern_subset.rb

@@ -66,6 +66,14 @@ module Hecks
       def validate(pattern)
         chars = pattern.to_s.chars
         index = 0
+        # A CHARACTER-CLASS INTERIOR IS A DIFFERENT ALPHABET : inside `[...]`,
+        # `*`, `+`, `?`, `(`, `?` are literal characters, not quantifiers or
+        # group syntax — `[*+]` means "a literal asterisk or plus". `]` is
+        # only the class's close when it isn't the first character after `[`
+        # or `[^` (where it is itself a literal, per POSIX bracket-expression
+        # rules).
+        in_class = false
+        class_start = nil
 
         while index < chars.length
           if chars[index] == "\\"
@@ -78,14 +86,36 @@ module Hecks
             next
           end
 
+          if in_class
+            if chars[index] == "]" && index != class_start
+              in_class = false
+              index += 1
+              next
+            end
+
+            return refuse(:posix_class) if posix_class_at?(chars, index)
+
+            index += 1
+            next
+          end
+
+          if chars[index] == "["
+            return refuse(:posix_class) if posix_class_at?(chars, index)
+
+            in_class = true
+            class_start = index + 1
+            class_start += 1 if chars[class_start] == "^"
+            index += 1
+            next
+          end
+
           if chars[index] == "(" && chars[index + 1] == "?"
             return refuse(:lookahead)    if %w[= !].include?(chars[index + 2])
             return refuse(:lookbehind)   if chars[index + 2] == "<" && %w[= !].include?(chars[index + 3])
             return refuse(:atomic_group) if chars[index + 2] == ">"
           end
 
-          return refuse(:posix_class)  if posix_class_at?(chars, index)
-          return refuse(:possessive)   if %w[* + ?].include?(chars[index]) && chars[index + 1] == "+"
+          return refuse(:possessive) if possessive_at?(chars, index)
 
           index += 1
         end
@@ -115,6 +145,40 @@ module Hecks
         cursor += 1 while chars[cursor]&.match?(/[a-zA-Z]/)
         chars[cursor] == ":" && chars[cursor + 1] == "]"
       end
+
+      # A possessive quantifier is `*+`, `++`, `?+`, or a bounded `{n}`/{n,m}`
+      # immediately followed by `+` — only checked OUTSIDE a character class,
+      # where `*`, `+`, `?`, `{`, `}` are quantifier syntax rather than
+      # literal characters.
+      def possessive_at?(chars, index)
+        return true if %w[* + ?].include?(chars[index]) && chars[index + 1] == "+"
+        return false unless chars[index] == "{"
+
+        len = bounded_quantifier_length(chars, index)
+        !len.nil? && chars[index + len] == "+"
+      end
+
+      # Length of a `{n}` / `{n,}` / `{n,m}` bound starting at `index`, or nil
+      # if what's there isn't one.
+      def bounded_quantifier_length(chars, index)
+        cursor = index + 1
+        digit_seen = false
+
+        while chars[cursor]&.match?(/[0-9]/)
+          digit_seen = true
+          cursor += 1
+        end
+        return nil unless digit_seen
+
+        if chars[cursor] == ","
+          cursor += 1
+          cursor += 1 while chars[cursor]&.match?(/[0-9]/)
+        end
+
+        return nil unless chars[cursor] == "}"
+
+        cursor - index + 1
+      end
     end
   end
 end

data/lib/hecks/bluebook/process_manager.rb

@@ -3,7 +3,16 @@ require_relative "../ir"
 
 module Hecks
   module Bluebook
-    DispatchSpec = Struct.new(:command_name, :with_spec, keyword_init: true) do
+    # `compensates` — a SECOND `DispatchSpec`, shape-identical to this
+    # one, naming the command that undoes THIS dispatch specifically
+    # (see `ProcessManagerBuilder::HandlerBuilder#dispatch_impl`'s own
+    # comment). `nil` for a dispatch with nothing to undo (a pure
+    # bookkeeping mark, or one whose own effect is superseded by a later
+    # command rather than needing its own compensation). Never nested
+    # further — a compensation is not itself compensable; no known
+    # corpus need, and ADR 0025's own "a word earns its place by being
+    # used" bar would refuse a second level speculatively.
+    DispatchSpec = Struct.new(:command_name, :with_spec, :compensates, keyword_init: true) do
       # A Struct already answers to_h; including the mixin puts the
       # DECLARED emission ahead of Struct's own in the ancestry, which
       # is what makes the shape data rather than a method body.
@@ -11,7 +20,8 @@ module Hecks
 
       emits_ir(
         command_name: -> { command_name.to_s },
-        with_spec:    -> { with_spec.map { |key, value| [key.to_s, Bluebook.render_value(value)] } }
+        with_spec:    -> { with_spec.map { |key, value| [key.to_s, Bluebook.render_value(value)] } },
+        compensates:  one(:compensates)
       )
     end
 
@@ -35,14 +45,31 @@ module Hecks
     # word — so here they are two objects, and a procedure either has a saga or
     # does not.
     #
-    # `undoes` is the ordered list of commands the compensation sends. Today that
-    # order is the AUTHOR's, written by hand in one `on :refused` leg, and the
-    # runtime does not know which legs actually completed. When compensation
-    # moves beside each dispatch — `reverses` on the step it reverses — this is
-    # where the completed ones, newest first, will live. The shape is already
-    # right for it; only the source of the order changes.
-    Saga = Struct.new(:trigger, :from_state, :to_state, :reversals, keyword_init: true) do
-      def undoes = reversals.map(&:command_name)
+    # `undoes` is the ordered list of commands the compensation sends — a
+    # STATIC PREVIEW, declaration order (`Behaviour::ProcessManager#saga`),
+    # not one instance's own runtime history. Per-dispatch compensation
+    # (`compensates`, on the step it compensates for) moved most of what
+    # a saga undoes off this leg's own hand-written body and onto
+    # whichever forward dispatch each one undoes — this reads every
+    # declared `compensates` across the WHOLE saga first, then whatever
+    # this leg's own hand-written body still lists, for compensation
+    # that isn't expressible as "undo command X." WHICH of a declared
+    # `compensates` actually fires for one instance, and in what order
+    # (newest-first, completed-legs-only), is `SagaInterpreter`'s own
+    # dynamic `completed_compensations` — a per-instance runtime fact
+    # this declaration-only object could never hold.
+    #
+    # NAMING COLLISION, ONCE FLAGGED, NOW RESOLVED — `command`'s own
+    # `corrects event, reverses: true` (docs/implemented/decisions/0036-
+    # corrects-is-an-appended-fact-not-a-rewrite.md) already claimed
+    # `reverses` for a different meaning: auto-deriving a command's OWN
+    # corrective mutation from a past EVENT, not a saga's own
+    # compensating leg from a past DISPATCH. This feature keeps
+    # `reverses` reserved for `corrects` and uses `compensates` for
+    # per-dispatch saga compensation instead — a deliberate choice, not
+    # an accidental collision.
+    Saga = Struct.new(:trigger, :from_state, :to_state, :compensations, keyword_init: true) do
+      def undoes = compensations.map(&:command_name)
 
       def to_s = "#{trigger} → #{to_state} (#{undoes.join(', ')})"
     end
@@ -63,7 +90,22 @@ module Hecks
 
       emits_ir(
         name:          :name,
-        correlates_by: -> { correlates_by.to_s },
+        # M11 — `&.`, not `.`: a DSL-built process manager always carries
+        # a real `correlates_by` (`ProcessManagerBuilder#build` refuses to
+        # mint one without it), but the IR class itself defaults it to
+        # `nil` and is what `Assembly::Build`'s `:identity` reader
+        # (`value&.to_sym`) round-trips against. A bare `.to_s` mapped
+        # that absent case to `""`, indistinguishable on the wire from a
+        # real empty name and read back as the wrong, non-nil `:""`
+        # instead of `nil` — the same nil-erasure S1 fixed for
+        # `render_value`, one field over. `correlates_by` is always a
+        # bare Symbol (`SagaInterpreter` hash-looks-up a payload by it),
+        # never a `Literal`-encoded polymorphic value, so this stays a
+        # local `&.` rather than routing through `Literal.render` — that
+        # would wrap a real value in a leading `:` and break both the
+        # `:identity` reader's plain `to_sym` and the pinned golden IR
+        # fixtures' bare-string spelling (`"reference.value"`).
+        correlates_by: -> { correlates_by&.to_s },
         starts_on:     :starts_on,
         ends_on:       :ends_on,
         states:        :states,

data/lib/hecks/bluebook/value_object.rb

@@ -30,7 +30,15 @@ module Hecks
         attributes: many(:attributes),
         invariants: -> { invariants.map { |rule| { description: rule.description, canonical: rule.canonical } } },
         closed_set: :closed_set?,
-        members:    -> { members.map { |member| member.map { |field, value| [field.to_s, value.to_s] } } }
+        # THE FIELD NAME IS STRINGIFIED, NEVER THE VALUE. A `member` row can
+        # hold any of the scalar types an attribute declares — `Integer 84`
+        # (`StatementFrequency#retention_months`, statements.bluebook), not
+        # only `String` — and `value.to_s` used to erase that on the way
+        # out, so `84` and `"84"` (a member some other row might
+        # legitimately spell as text) became indistinguishable once they
+        # reached `to_h`. The declared name still moves (`field.to_s`) —
+        # that half was never a Ruby object with a type to lose.
+        members:    -> { members.map { |member| member.map { |field, value| [field.to_s, value] } } }
       )
 
       class << self

data/lib/hecks/doc/reference.rb

@@ -257,7 +257,8 @@ module Hecks
           "guides"    => guide_index(root),
           "reference" => reference_index(root),
           "tools"     => tool_table(root),
-          "corpus"    => corpus_roster(root)
+          "corpus"    => corpus_roster(root),
+          "diagrams"  => diagram_showcase(root)
         }
       end
 
@@ -311,6 +312,26 @@ module Hecks
         text.length > 140 ? "#{text[0, 137]}..." : text
       end
 
+      # ONE REAL, COMMITTED FILE, READ FRESH — not re-derived from a boot
+      # (this module never requires `hecks/projections/diagrams`, and
+      # shouldn't just to draw one example). `docs/generated/diagrams/`
+      # is already held to the declaration by `spec/diagrams_spec.rb`'s
+      # own drift check; this just quotes its own output, so the two
+      # can't independently drift from each other either — a stale
+      # Order_lifecycle.mmd fails THAT spec long before this one runs.
+      def diagram_showcase(root)
+        lifecycle = File.read(File.join(root, "docs/generated/diagrams/pizzas/Order_lifecycle.mmd")).strip
+        <<~MARKDOWN.strip
+          `bin/project_diagrams` reads a booted domain's own declaration and draws it as Mermaid — nine kinds so far: `<Name>_lifecycle.mmd`, `relationships.mmd`, `dispatch.mmd`, `roles.mmd`, `ports.mmd`, `read_models.mmd`, `<Name>_surface.mmd` (what a command does, and what it writes), `<Name>_saga.mmd`, and `frameworks.mmd`. Nothing hand-drawn — the same reason a domain is data at all. Order's own lifecycle, straight off the bluebook above:
+
+          ```mermaid
+          #{lifecycle}
+          ```
+
+          The full set for every domain in this checkout — `examples/pizzas`, `examples/banking` — lives in [`docs/generated/diagrams/`](docs/generated/diagrams/), held to the declaration by `spec/diagrams_spec.rb` the same drift-refusing way this page is held to its own source.
+        MARKDOWN
+      end
+
       def corpus_roster(root)
         dirs = Dir.glob(File.join(root, "examples/*/")).sort
         lines = dirs.filter_map do |dir|

data/lib/hecks/facade/cli_door.rb

@@ -33,10 +33,13 @@ module Hecks
 
         pairs.each_with_object({}) do |pair, args|
           path, value = split(pair)
-          argument    = options[path] || options[expand(path, options)] ||
-                        raise(Runtime::NotFound, unknown(path, options.keys))
+          # key? first, never `||` — full names whichever spelling (the
+          # bare path, or its one-argument expansion) actually declares
+          # this option, and the lookup below must hold to that same
+          # decision rather than re-guessing which one exists.
+          full     = options.key?(path) ? path : expand(path, options)
+          argument = options.key?(full) ? options[full] : raise(Runtime::NotFound, unknown(path, options.keys))
 
-          full = options.key?(path) ? path : expand(path, options)
           next append(args, full.split("."), cast(value, argument[:type])) if argument[:list]
 
           bury(args, full.split("."), cast(value, argument[:type]))

data/lib/hecks/facade/json_door.rb

@@ -81,12 +81,24 @@ module Hecks
       end
 
       # A URL segment or a JSON body's "command" field, checked against what
-      # the aggregate actually declares. `klass.commands` is the same
-      # sorted, snake_cased list `AggregateDoor` built for its own door, so
-      # a name this accepts is a name a `Handle` can actually dispatch.
+      # a `Handle` can actually dispatch — NOT `klass.commands`, which is
+      # `AggregateDoor`'s own door-level list and includes the one creating
+      # command too (`aggregate_door.rb`'s `commands` singleton method maps
+      # every `ir.commands`, full stop). A `Handle` only ever defines
+      # singleton methods for the NON-creating ones
+      # (`Handle#define_verb_methods`, `@ir.commands.reject(&:creates?)`) —
+      # the creating command lives on the aggregate class itself, dispatched
+      # through `.creating_command` above, not through a `Handle` in hand.
+      # Accepting a creating-command name here let it past this gate clean,
+      # only to blow up as a raw `NoMethodError` the moment a caller tried
+      # `handle.public_send(name, **args)`, instead of the 404 this method
+      # promises. Filtering `reject(&:creates?)` here, the same filter
+      # `Handle` itself applies, is what keeps "accepted here" and
+      # "dispatchable there" the same set.
       def validate_command!(klass, name)
         wanted = name.to_s
-        return wanted if klass.commands.include?(wanted)
+        dispatchable = klass.ir.commands.reject(&:creates?).map { |command| "#{Naming.snake(command.hecks_name)}!" }
+        return wanted if dispatchable.include?(wanted)
 
         raise Runtime::NotFound, "#{klass.ir.hecks_name} declares no command named #{wanted.inspect}"
       end