hecks 0.3.0 → 1.0.1

data/lib/hecks/bluebook/dsl/entity_builder.rb

@@ -11,7 +11,8 @@ module Hecks
         include WordGate
 
         def initialize(name, owner_value_objects: [], owner_named_givens: {},
-                       identity_name_prefix: nil, identity_value_object_installer: nil)
+                       identity_name_prefix: nil, identity_value_object_installer: nil,
+                       aggregate_name: nil, chapter_entity_named_givens: {}, chapter_entity_pending_givens: [])
           @name         = name
           @commands     = []
           @queries      = []
@@ -30,6 +31,18 @@ module Hecks
           # reference reads from it via `CommandBuilder#
           # reference_named_given`.
           @owner_named_givens = owner_named_givens
+          # ONE LEVEL WIDER STILL — the CHAPTER-WIDE, ENTITY-SCOPED pool
+          # (the piece analogue of `AggregateBuilder#@chapter_named_givens`,
+          # one level down). `@aggregate_name` names THIS piece's own
+          # root, so the write-through below can key itself
+          # "AggregateName.EntityName" — the same dotted addressing
+          # convention `declared_by:` already uses chapter-wide, one
+          # level up. See `#given_impl`'s own comment for what this
+          # closes and `docs/implemented/resolution-rules/
+          # chapter-entity-given.md` for the full algorithm.
+          @aggregate_name = aggregate_name || Naming.demodulise(name)
+          @chapter_entity_named_givens   = chapter_entity_named_givens
+          @chapter_entity_pending_givens = chapter_entity_pending_givens
           # DEFERRED CONSTRUCTION — see `AggregateBuilder#drain_pending!`'s
           # own comment; the identical mechanism, one level down, so a
           # nested piece's own commands (Dispatch inside Handler) see
@@ -150,7 +163,40 @@ module Hecks
         # magic.
         # RENAMED FROM `given` — item #13's full metaprogrammed dispatch
         # (slice 4b), same reasoning as reference_to_impl above.
-        def given_impl(description, &predicate)
+        #
+        # BARE — NO BLOCK — REFERENCES ANOTHER PIECE'S OWN DECLARATION,
+        # ANYWHERE IN THE CHAPTER, not just a sibling under this same
+        # aggregate — one level wider than round 4's own cross-entity
+        # sharing, mirroring `AggregateBuilder#given_impl`'s own
+        # chapter-wide shape exactly one level down. Real, live corpus
+        # this closes: `Account::LedgerEntry` and `SafeDepositBox::Visit`
+        # — two pieces under two DIFFERENT aggregates — independently
+        # typed `given("customer is active") { parent.customer.status ==
+        # "active" }` byte for byte; neither the aggregate-level chapter
+        # pool (a DIFFERENT canonical — bare `customer.status`, the
+        # wrong scope for a piece's own command) nor the existing
+        # same-aggregate cross-entity pool (`@owner_named_givens`, scoped
+        # to ONE aggregate's own entity tree) could reach across the
+        # aggregate boundary. Resolved against `@chapter_entity_named_
+        # givens`, keyed "AggregateName.EntityName" — see
+        # `#reference_named_chapter_entity_given`'s own comment for the
+        # algorithm and `docs/implemented/resolution-rules/
+        # chapter-entity-given.md` for the full write-up.
+        #
+        # `declared_by:` is a PLAIN STRING ("Account.LedgerEntry"), not a
+        # constant — unlike `AggregateBuilder#given_impl`'s own
+        # `declared_by:`, which names a real aggregate constant. A piece
+        # has no first-class, independently-addressable reference
+        # anywhere in this language (only its owning aggregate does);
+        # inventing one to make this ONE argument spelling symmetrical
+        # with the aggregate-level word is a real, separate, unscoped
+        # feature this fix does not need — ships textual now, the same
+        # way `admits:` shipped textual before its own constant-bridge
+        # existed, revisited only if a genuine, separate need for
+        # constant-addressed pieces shows up later.
+        def given_impl(description, declared_by: nil, &predicate)
+          return reference_named_chapter_entity_given(description, declared_by: declared_by) unless predicate
+
           named = build_rule(Given, description, predicate, owner_name: @name, word: "given",
                               extraction_failure: "its source could not be read, so no other runtime could ever evaluate it")
           @named_givens[description] = named
@@ -163,6 +209,17 @@ module Hecks
           # by coincidence, same as an aggregate-level given already
           # tolerates today).
           @owner_named_givens[description] ||= named
+          # WRITE-THROUGH, PER OWNER — the chapter-wide analogue of the
+          # line above, keyed by [description, this piece's own dotted
+          # "Aggregate.Entity" name] rather than description alone, the
+          # identical reasoning `AggregateBuilder#given_impl`'s own
+          # chapter write-through gives: two DIFFERENT pieces (anywhere
+          # in the chapter) independently declaring the SAME description
+          # are two DISTINCT candidates a later bare reference chooses
+          # between (via `declared_by:` once there is more than one),
+          # never silently merged into one slot.
+          @chapter_entity_named_givens[description] ||= {}
+          @chapter_entity_named_givens[description]["#{@aggregate_name}.#{@name}"] ||= named
         end
 
         # A PIECE'S OWN SHAPE RULE (S10, ADR 0025's own "Rules" shape,
@@ -203,16 +260,81 @@ module Hecks
         end
 
         def self.build(name, owner_value_objects: [], owner_named_givens: {},
-                       identity_name_prefix: nil, identity_value_object_installer: nil, &block)
+                       identity_name_prefix: nil, identity_value_object_installer: nil,
+                       aggregate_name: nil, chapter_entity_named_givens: {}, chapter_entity_pending_givens: [], &block)
           builder = new(name, owner_value_objects: owner_value_objects, owner_named_givens: owner_named_givens,
                               identity_name_prefix: identity_name_prefix,
-                              identity_value_object_installer: identity_value_object_installer)
+                              identity_value_object_installer: identity_value_object_installer,
+                              aggregate_name: aggregate_name,
+                              chapter_entity_named_givens: chapter_entity_named_givens,
+                              chapter_entity_pending_givens: chapter_entity_pending_givens)
           builder.instance_eval(&block) if block
           builder.build
         end
 
         private
 
+        # PRIMITIVE 2 (RuleReference#resolve_owner_keyed) — the CHAPTER-
+        # WIDE, ENTITY-SCOPED analogue of `AggregateBuilder#
+        # reference_named_chapter_given`; the three branches below are
+        # this construct's OWN refusal wording, not shared, matching that
+        # method's own precedent (`declared_by:` only exists on `given`
+        # so far, at either scope). UNRESOLVED is deferred, not raised
+        # here — see `#pending_chapter_entity_given`, below.
+        #
+        # WRITES THROUGH TO `@owner_named_givens` TOO — not just
+        # `@named_givens` — or this piece resolving a description via the
+        # WIDER, chapter pool would leave the NARROWER, same-aggregate
+        # pool (`EntityBuilder#given_impl`'s own block-form write-through)
+        # never populated for this description, breaking any SIBLING
+        # piece's existing command-level bare reference
+        # (`CommandBuilder#reference_named_given`) that depends on it —
+        # real, live corpus: `SafeDepositBox::KeyIssuance.Return`'s own
+        # bare `given("customer is active")` resolves through
+        # `@owner_named_givens`, populated by `Visit`'s declaration
+        # whether `Visit` types the predicate itself OR (now) references
+        # `Account::LedgerEntry`'s instead — this write keeps that
+        # working unchanged either way, `||=` so nothing here overrides
+        # an actual local declaration if one is ever added later.
+        def reference_named_chapter_entity_given(description, declared_by:)
+          verify_resolves_via!("given", "Entity", "owner_keyed")
+          candidates = resolve_owner_keyed(@chapter_entity_named_givens, description)
+
+          named =
+            if declared_by
+              candidates[declared_by] || pending_chapter_entity_given(description, declared_by: declared_by)
+            elsif candidates.size == 1
+              candidates.values.first
+            elsif candidates.empty?
+              pending_chapter_entity_given(description, declared_by: nil)
+            else
+              raise(Malformed,
+                    "#{@aggregate_name}::#{@name}'s given #{description.inspect} is ambiguous " \
+                    "across the chapter's own pieces — #{candidates.keys.join(', ')} each declare " \
+                    "a DIFFERENT predicate under this same description; name which one with " \
+                    "declared_by: (e.g. given(#{description.inspect}, declared_by: " \
+                    "#{candidates.keys.first.inspect}))")
+            end
+
+          @named_givens[description] = named
+          @owner_named_givens[description] ||= named
+        end
+
+        # A CHAPTER MAY BE SPLIT ACROSS FILES — the identical reason
+        # `AggregateBuilder#pending_chapter_given` defers rather than
+        # raising the moment a bare reference outruns what's loaded so
+        # far. Hands back a PLACEHOLDER `Given`, embedded by Ruby object
+        # reference in this piece's own `preconditions`, and queues the
+        # request in `@chapter_entity_pending_givens` —
+        # `BluebookBuilder#resolve_pending_chapter_entity_givens!`
+        # mutates it in place once every file in the chapter has loaded.
+        def pending_chapter_entity_given(description, declared_by:)
+          placeholder = Given.new(description: description, canonical: nil, predicate: nil)
+          @chapter_entity_pending_givens << { entity: "#{@aggregate_name}.#{@name}", description: description,
+                                               declared_by: declared_by, placeholder: placeholder }
+          placeholder
+        end
+
         # A PIECE'S OWN `one_of` LANDS ON ITS AGGREGATE. A type-position
         # `one_of("never_moved", "moved")` on an entity attribute
         # synthesizes a closed-set value object — and until this, that
@@ -257,6 +379,9 @@ module Hecks
                                       owner_named_givens:              @owner_named_givens,
                                       identity_name_prefix:            "#{@identity_name_prefix}#{Naming.demodulise(name)}",
                                       identity_value_object_installer: @identity_value_object_installer,
+                                      aggregate_name:                  @aggregate_name,
+                                      chapter_entity_named_givens:     @chapter_entity_named_givens,
+                                      chapter_entity_pending_givens:   @chapter_entity_pending_givens,
                                 &block)
           end
 

data/lib/hecks/bluebook/dsl/policy_builder.rb

@@ -11,9 +11,24 @@ module Hecks
           @name = name
         end
 
-        # `on` — item #13's full metaprogrammed dispatch, slice 1
-        # (whole-project table-unification survey): a bare, kind-driven
-        # coerce-and-assign, now executed by `GenericDispatch`.
+        # `on Account::AccountFrozen` — A BARE CONSTANT ACCEPTED (ADR
+        # 0025, S6 — "events first-class"), resolved through `ConstShim`
+        # the same way `trigger`/`dispatch` already resolve a command
+        # reference (`Naming.event_ref`, that method's own header). NOT
+        # a required spelling yet, unlike `trigger`'s own quoted-text
+        # refusal — see `policy.bluebook`'s own KeywordSeed comment for
+        # why: event names aren't 100% migrated across the live corpus
+        # the way command references are, so both `on "Account.
+        # AccountFrozen"` (quoted) and `on Account::AccountFrozen`
+        # (bare) stay admitted until a full migration lands.
+        #
+        # RENAMED FROM the generic single-fill coercion — item #13's
+        # full metaprogrammed dispatch, slice 1 (whole-project
+        # table-unification survey), now overridden here the same way
+        # `trigger_impl` overrides its own generic default.
+        def on_impl(event_ref)
+          @on_event = Naming.event_ref(event_ref)
+        end
 
         # `with:` — WHAT THE TRIGGER IS GIVEN, when the event's own shape
         # is not it. Omitted, the whole event payload forwards verbatim,

data/lib/hecks/bluebook/dsl/port_builder.rb

@@ -8,15 +8,24 @@ module Hecks
         include WordGate
 
         def initialize(name)
-          @name   = name
-          @signal = :reply
+          @name    = name
+          @signal  = :reply
+          @answers = []
         end
 
         def verb(value)   = @verb = value.to_s
         def signal(value) = @signal = value.to_sym
 
+        # THE METHOD CONTRACT — the fact a `.port` file's `verb`/`signal`
+        # never carried: what an adapter must actually RESPOND TO for a
+        # dispatch to reach it without a bare `NoMethodError`. Declared the
+        # same repeatable way `AdapterBuilder#field`/`#secret` already are,
+        # so `verify!` can check it with `respond_to?` at boot instead of
+        # the runtime discovering it live.
+        def answers(name) = @answers << name.to_sym
+
         def build
-          MetaValidator.call_port(Port.new(name: @name, verb: @verb, signal: @signal))
+          MetaValidator.call_port(Port.new(name: @name, verb: @verb, signal: @signal, answers: @answers))
         end
 
         def self.build(name, &block)

data/lib/hecks/bluebook/dsl/process_manager_builder.rb

@@ -14,10 +14,38 @@ module Hecks
           @handlers = []
         end
 
-        # `correlates_by`/`starts_on`/`ends_on` — item #13's full
-        # metaprogrammed dispatch, slice 1 (whole-project table-
-        # unification survey): each a bare, kind-driven coerce-and-
-        # assign with nothing else, now executed by `GenericDispatch`.
+        # `starts_on Transfer::TransferRequested` — BARE CONSTANT
+        # ACCEPTED (ADR 0025, S6 — "events first-class"), resolved
+        # through `ConstShim` the same way `on_impl`/`transition_impl`
+        # resolve an event reference — but through `Naming.
+        # event_name_ref`, NOT `Naming.event_ref` (that method's own
+        # header has the full account: `SagaInterpreter` matches
+        # `pm.starts_on`/`pm.ends_on` against a BARE `event.name`, never
+        # a "." qualified one). A plain String still passes through
+        # unchanged, both for `shadow_parse` and for any corpus site a
+        # future pass hasn't migrated yet.
+        def starts_on_impl(event_ref)
+          @starts_on = Naming.event_name_ref(event_ref)
+        end
+
+        # `ends_on` — same reasoning as `starts_on_impl`, above.
+        def ends_on_impl(event_ref)
+          @ends_on = Naming.event_name_ref(event_ref)
+        end
+
+        # `correlates_by` — item #13's full metaprogrammed dispatch,
+        # slice 1 (whole-project table-unification survey): a bare,
+        # kind-driven coerce-and-assign with nothing else, executed by
+        # `GenericDispatch`.
+        #
+        # `starts_on`/`ends_on` USED TO be table-driven the same way,
+        # until ADR 0025 S6 gave each a second, `kind: "constant"`
+        # ArgumentSeed row (`starts_on Transfer::TransferRequested`) —
+        # `GenericDispatch::COERCE_BY_KIND` only knows `"text"`/
+        # `"symbol"`, and `shape_for` refuses to pick a `single_fill`
+        # shape at all once two Argument rows share a `fills:` target
+        # (`arguments.size == 1` below), so both words are hand-written
+        # again, `calls:`-routed like `transition` already is.
 
         # ONE STATE-MACHINE VOCABULARY (S7, ADR 0025 — "events and
         # reactions"): the SAME word `Lifecycle#transition` already
@@ -85,8 +113,25 @@ module Hecks
           handler.instance_eval(&block) if block
 
           mapping.each do |event_type, target|
+            # BARE CONSTANT ACCEPTED (ADR 0025, S6 — "events first-
+            # class"), `transition Account::AccountDebited => "state"` —
+            # `Naming.event_name_ref`, NOT the DOTTED `Naming.event_ref`
+            # transform `PolicyBuilder#on_impl` uses (that method's own
+            # header has the full account, found live wiring a real
+            # migrated corpus site into `bin/model_check` for the first
+            # time: `SagaInterpreter#advance_saga` matches `handler.
+            # event_type` against a BARE `event.name`, never a "."
+            # qualified one — a policy's own cross-aggregate match
+            # works differently, splitting the qualifier apart from the
+            # name rather than comparing the whole string). Writing the
+            # qualifier is still worth it (the same provenance `trigger
+            # Account::Debit` gives a reader) — `event_name_ref` keeps
+            # only the final segment, so `Account::AccountDebited` and a
+            # bare `AccountDebited` store identically. A plain String
+            # still passes through unchanged, both for `shadow_parse`
+            # and for every corpus site this pass didn't migrate.
             state_transition = StateTransition.new(target: target, from: from)
-            expand(event_type.to_s, state_transition, handler.dispatches).each { |row| @handlers << row }
+            expand(Naming.event_name_ref(event_type), state_transition, handler.dispatches).each { |row| @handlers << row }
           end
         end
 
@@ -185,19 +230,73 @@ module Hecks
           #
           # RENAMED FROM `dispatch` — item #13's full metaprogrammed
           # dispatch (slice 4), same reasoning as trigger_impl above.
-          def dispatch_impl(command_ref, with: nil)
+          #
+          # AN OPTIONAL BLOCK OPENS `compensates` ON THIS DISPATCH
+          # SPECIFICALLY — per-dispatch saga compensation, replacing a
+          # hand-written list at the saga's own `on :refused` leg. Real,
+          # live bug this closes: `examples/banking/bluebook/transfers_
+          # and_payments.bluebook`'s own `Settlement` saga wrote a
+          # compensating reversal by hand that depended on an event only
+          # fired if someone dispatched it manually — "the reversal was
+          # written and never armed" (that file's own comment). The
+          # runtime now tracks which legs actually completed
+          # (`SagaInterpreter`'s own `completed_compensations`) and
+          # compensates only those, newest first, instead of trusting an
+          # author's static list to be complete and correctly ordered.
+          def dispatch_impl(command_ref, with: nil, &block)
             if command_ref.is_a?(::String) && !MetaValidator.shadow_parsing?
               raise InvalidProcessManager,
                     "dispatch #{command_ref.inspect} is quoted text — give the bare command constant " \
                     "instead, e.g. dispatch Account::Debit"
             end
 
-            DispatchSpec.new(
+            spec = DispatchSpec.new(
               command_name: Naming.command_ref(command_ref),
               with_spec:    (with || {}).to_a
-            ).tap do |dispatch|
-              dispatch.instance_variable_set(:@projection_declared, !with.nil?)
-              @dispatches << dispatch
+            )
+            spec.instance_variable_set(:@projection_declared, !with.nil?)
+
+            if block
+              builder = DispatchBuilder.new
+              builder.instance_eval(&block)
+              # `instance_variable_get`, not a public `compensates_spec`
+              # reader — a public one would be a method the grammar
+              # never declares, exactly what `spec/syntax_conformance_
+              # spec.rb`'s "answers only words the language declares"
+              # check exists to catch.
+              spec.compensates = builder.instance_variable_get(:@compensates_spec)
+            end
+
+            @dispatches << spec
+            spec
+          end
+
+          # THE NESTED SCOPE `dispatch ... do ... end` OPENS — one word
+          # only (`compensates`), the compensating half of the dispatch it
+          # sits inside. Its own `compensates_impl` builds a SECOND
+          # `DispatchSpec`, shape-identical to `HandlerBuilder#dispatch_
+          # impl`'s own — a compensation takes the exact same two
+          # arguments (a bare command constant, an optional `with:`)
+          # because it resolves through the identical scope (current
+          # event payload, opening event memory, correlation binding)
+          # any saga dispatch already does
+          # (`SagaInterpreter#dispatch_args`).
+          class DispatchBuilder
+            GRAMMAR_CONTEXT = "Dispatch"
+
+            include WordGate
+
+            def compensates_impl(command_ref, with: nil)
+              if command_ref.is_a?(::String) && !MetaValidator.shadow_parsing?
+                raise InvalidProcessManager,
+                      "compensates #{command_ref.inspect} is quoted text — give the bare command constant " \
+                      "instead, e.g. compensates Account::Credit"
+              end
+
+              @compensates_spec = DispatchSpec.new(
+                command_name: Naming.command_ref(command_ref),
+                with_spec:    (with || {}).to_a
+              )
             end
           end
         end

data/lib/hecks/bluebook/dsl/rule_reference.rb

@@ -129,6 +129,7 @@ module Hecks
         # the real table, every time, no exception.
         BOOTSTRAP_FALLBACK = {
           %w[given Aggregate]       => { resolves_via: "owner_keyed", disambiguator: "declared_by" },
+          %w[given Entity]          => { resolves_via: "owner_keyed", disambiguator: "declared_by" },
           %w[given Command]         => { resolves_via: "hash_chain" },
           %w[invariant ValueObject] => { resolves_via: "sibling_scan" }
         }.freeze

data/lib/hecks/bluebook/dsl/word_gate.rb

@@ -110,8 +110,15 @@ module Hecks
             # below checks them in, for the same reason: `list_of`/
             # `one_of` used in an attribute's own type position never
             # arrive with `self.class::GRAMMAR_CONTEXT == "Type"`.
-            target = fallback[[self.class::GRAMMAR_CONTEXT, word.to_s]] || fallback[["Type", word.to_s]]
-            return send(target, *args, **kwargs, &block) if target
+            own_key  = [self.class::GRAMMAR_CONTEXT, word.to_s]
+            type_key = ["Type", word.to_s]
+            # key? first, never `||` — a target method name is never
+            # actually stored as `false`, but the fallback lookup itself
+            # must not silently prefer "Type" over this class's own
+            # context on the strength of a falsy-looking value.
+            found  = fallback.key?(own_key) || fallback.key?(type_key)
+            target = fallback.key?(own_key) ? fallback[own_key] : fallback[type_key]
+            return send(target, *args, **kwargs, &block) if found
 
             return super
           end

data/lib/hecks/bluebook/dsl/world_builder.rb

@@ -14,6 +14,30 @@ module Hecks
         def to_h = @values
       end
 
+      # THE AGGREGATE-QUALIFIED MIRROR (#143) — a `.world` file's own
+      # `Pizzas::Order.charged_by("Stripe") do ... end` visually mirrors the
+      # SAME bind line the sibling `.hecksagon` file already writes
+      # (`HecksagonBuilder`'s own `BindingProxy`), but `IR::World#for_verb`/
+      # `#for_binding` key purely by verb and adapter name — the aggregate
+      # qualifier is never read back out, it exists only for that visual
+      # mirroring. So unlike `BindingProxy`, nothing here needs to hold onto
+      # the resolved constant chain at all: every verb call, qualified or
+      # not, has to land in the exact same `@settings` write path
+      # (`WorldBuilder#record_binding`).
+      class WorldConstProxy
+        def self.namespace(builder)
+          Module.new do
+            define_singleton_method(:const_missing) { |_aggregate| WorldConstProxy.new(builder) }
+          end
+        end
+
+        def initialize(builder) = @builder = builder
+
+        def method_missing(verb, *args, **kwargs, &block) = @builder.record_binding(verb, args, kwargs, block)
+
+        def respond_to_missing?(_name, _include_private = false) = true
+      end
+
       class WorldBuilder
         GRAMMAR_CONTEXT = "World"
 
@@ -44,6 +68,17 @@ module Hecks
           result = word_gate_dispatch(verb, args, kwargs, block)
           return result unless result.equal?(WordGate::NOT_ADMITTED)
 
+          record_binding(verb, args, kwargs, block)
+        end
+
+        def respond_to_missing?(_name, _include_private = false) = true
+
+        # EXTRACTED from the old `method_missing` body (#143) so
+        # `WorldConstProxy`'s own aggregate-qualified verb calls
+        # (`Pizzas::Order.charged_by(...)`) write into the exact same
+        # place the bare top-level spelling (`charged_by(...)`) already
+        # does — one write path, two spellings.
+        def record_binding(verb, args, kwargs, block)
           collector = SettingsCollector.new
           collector.instance_eval(&block) if block
           value = { adapter: args.first.to_s }.merge(kwargs).merge(collector.to_h)
@@ -51,17 +86,22 @@ module Hecks
           @settings["#{verb}:#{args.first.to_s.downcase}"] = value
         end
 
-        def respond_to_missing?(_name, _include_private = false) = true
-
         def build
           MetaValidator.call_world(
             World.new(domain: @domain, realm: @realm, latest: @latest, settings: @settings)
           )
         end
 
+        # `ConstShim`'s resolver, the same bridge `HecksagonBuilder`/
+        # `BluebookBuilder` already wrap their own `instance_eval` in
+        # (#143) — without it, `Pizzas::Order.charged_by(...)` raised
+        # `NameError: uninitialized constant Pizzas` for every `.world`
+        # file using the aggregate-qualified mirror form, since a bare
+        # `Pizzas` has no real constant to resolve to.
         def self.build(domain, &block)
-          builder = new(domain)
-          builder.instance_eval(&block) if block
+          builder  = new(domain)
+          resolver = ->(_domain) { WorldConstProxy.namespace(builder) }
+          ConstShim.with(resolver) { builder.instance_eval(&block) } if block
           builder.build
         end
 

data/lib/hecks/bluebook/expression/ast_json.rb

@@ -0,0 +1,149 @@
+require_relative "evaluator"
+require_relative "resolver"
+
+module Hecks
+  module Bluebook
+    module Expression
+      # ── AST → JSON — walks the REAL Evaluator/Resolver AST (the same
+      # objects a live dispatch parses `given`/`ensures`/invariant text
+      # into — see docs/implemented/guides/running-a-runtime.md's "The
+      # expression grammar") and emits plain, JSON-serializable Ruby
+      # Hashes, tagged by `"op"`.
+      #
+      # THE SAME TWO-METHOD WALK `rust/project/expr_emitter.rb`'s own
+      # `emit_bool`/`emit_resolver` already do, over the SAME AST — that
+      # file's own methods build RUST SOURCE-CODE STRINGS for `rust/
+      # project`'s codegen (`rust/src/kernel::expr::Expr` literals, baked
+      # into a generated domain's own compiled binary); this builds DATA
+      # instead, for a genuinely different consumer with a genuinely
+      # different constraint: `rust/host` can never link the `rust`
+      # (kernel) crate at all (a real, load-bearing build constraint —
+      # `reference_validate.rs`'s own header has the full reasoning: one
+      # path dependency would statically bake every domain's generated
+      # dispatch code into every Lambda binary), so a value object's own
+      # `invariant` predicate has to travel as something `rust/host` can
+      # deserialize and interpret itself, at RUNTIME, from `ir.json` — the
+      # exact same relationship `rust/project`'s own `Expr` literals
+      # already have to the compiled kernel, one layer further out.
+      #
+      # LIVES IN CORE `lib/hecks`, NOT `rust/project/` — `rust/project.rb`
+      # is a separate, downstream toolchain
+      # (`lib/hecks/projector.rb`'s own header: "a whole separate Ruby
+      # program"), never `require`d by core `lib/hecks/bluebook/*.rb`
+      # files (confirmed: no core file does). `value_object.rb`'s own
+      # `invariants:` IR emission needs this for EVERY domain's ordinary
+      # `to_h`/`ir.json` export — golden fixtures, `hecks-parse`'s parity
+      # comparisons, and any deploy artifact, not only a `bin/project_rust`
+      # run — so it belongs beside `Evaluator`/`Resolver` themselves, not
+      # bolted onto a tool that only sometimes runs.
+      #
+      # COMPLETE, not corpus-scoped: every node this grammar admits gets
+      # a real arm, the identical "raise, don't silently drop" discipline
+      # `expr_emitter.rb`'s own `emit_bool`/`emit_resolver` already hold
+      # to — even though, as of this writing, no real corpus VALUE OBJECT
+      # invariant exercises `Include`/`Modulo`/`BlockPredicate`/`Find`/
+      # `Array`/`MatchesRegex`/`Presence`/`Split`/`StartsWith`/`EndsWith`/
+      # `First`/`Last` (only `given`/`ensures` clauses do, elsewhere in
+      # the corpus — a different consumer of this same grammar).
+      # `rust/host/src/expr_json.rs`'s own header names exactly which of
+      # these its interpreter evaluates for real today versus refuses
+      # cleanly — a narrower, deliberate, documented boundary on the
+      # INTERPRETING side, not on this EMITTING side: an author is free
+      # to write ANY real expression in a value object's own `invariant`,
+      # and this always emits it faithfully; whether `rust/host` can yet
+      # CHECK it at mint time is that file's own question to answer, not
+      # this one's to pre-empt by refusing to even try.
+      module AstJson
+        module_function
+
+        def emit_predicate(canonical)
+          emit_bool(Evaluator.parse(canonical))
+        end
+
+        def emit_bool(node)
+          case node
+          when Evaluator::Or  then { "op" => "or", "left" => emit_bool(node.left), "right" => emit_bool(node.right) }
+          when Evaluator::And then { "op" => "and", "left" => emit_bool(node.left), "right" => emit_bool(node.right) }
+          when Evaluator::Not then { "op" => "not", "expr" => emit_bool(node.node) }
+          when Evaluator::Compare
+            { "op" => "compare", "cmp" => emit_comparison(node.operator),
+              "left" => emit_resolver(node.left), "right" => emit_resolver(node.right) }
+          when Evaluator::Include
+            emit_include(node)
+          when Evaluator::Resolve
+            emit_resolver(node.expr)
+          else
+            raise "unhandled evaluator node #{node.class} — no JSON rendering exists for it (lib/hecks/bluebook/expression/ast_json.rb#emit_bool)"
+          end
+        end
+
+        def emit_comparison(op)
+          { "less_than" => op.compares_less_than, "equal" => op.compares_equal, "negated" => op.negated }
+        end
+
+        # The JSON-target sibling of `expr_emitter.rb`'s own
+        # `emit_include` — see that method's own comment for the full
+        # reasoning (a LITERAL array haystack has no `Expr::Include`-
+        # representable shape on EITHER target, kernel or host, so both
+        # rewrite it identically into an OR-of-equalities at emission
+        # time rather than carrying a shape neither interpreter could
+        # evaluate). A non-literal haystack still emits `include`
+        # unchanged.
+        EQ = Evaluator::OPERATORS.find { |op| op.symbol == "==" }
+        private_constant :EQ
+
+        def emit_include(node)
+          return { "op" => "include", "haystack" => emit_resolver(node.haystack), "needle" => emit_resolver(node.needle) } \
+            unless node.haystack.is_a?(Resolver::ArrayLiteral)
+
+          return { "op" => "bool", "value" => false } if node.haystack.elements.empty?
+
+          equalities = node.haystack.elements.map do |element|
+            { "op" => "compare", "cmp" => emit_comparison(EQ), "left" => emit_resolver(node.needle), "right" => emit_resolver(element) }
+          end
+          equalities.reduce { |left, right| { "op" => "or", "left" => left, "right" => right } }
+        end
+
+        def emit_resolver(node)
+          case node
+          when Resolver::IntegerLiteral then { "op" => "int", "value" => node.value }
+          when Resolver::FloatLiteral   then { "op" => "float", "value" => node.value }
+          when Resolver::StringLiteral  then { "op" => "str", "value" => node.value }
+          when Resolver::BoolLiteral    then { "op" => "bool", "value" => node.value }
+          when Resolver::NilLiteral     then { "op" => "nil" }
+          when Resolver::Lookup         then { "op" => "lookup", "path" => node.path }
+          when Resolver::Addition       then { "op" => "add", "left" => emit_resolver(node.left), "right" => emit_resolver(node.right) }
+          when Resolver::SignTest
+            { "op" => "sign_test", "cmp" => emit_comparison(node.operator), "receiver" => emit_resolver(node.receiver) }
+          when Resolver::Empty  then { "op" => "empty", "receiver" => emit_resolver(node.receiver) }
+          when Resolver::ToS    then { "op" => "to_s", "receiver" => emit_resolver(node.receiver) }
+          when Resolver::Modulo then { "op" => "modulo", "receiver" => emit_resolver(node.receiver), "divisor" => emit_resolver(node.divisor) }
+          when Resolver::Size   then { "op" => "size", "receiver" => emit_resolver(node.receiver) }
+          when Resolver::BlockPredicate
+            { "op" => "block_predicate", "mode" => node.mode.to_s, "receiver" => emit_resolver(node.receiver),
+              "param" => node.param.to_s, "predicate" => emit_bool(node.predicate) }
+          when Resolver::Find
+            { "op" => "find", "receiver" => emit_resolver(node.receiver), "param" => node.param.to_s,
+              "predicate" => emit_bool(node.predicate), "path" => node.path.map(&:to_s) }
+          when Resolver::ArrayLiteral
+            { "op" => "array", "elements" => node.elements.map { |element| emit_resolver(element) } }
+          when Resolver::MatchesRegex
+            { "op" => "matches_regex", "receiver" => emit_resolver(node.receiver), "pattern" => node.pattern, "flags" => node.flags }
+          when Resolver::Presence
+            { "op" => "presence", "receiver" => emit_resolver(node.receiver), "negated" => node.negated }
+          when Resolver::Split
+            { "op" => "split", "receiver" => emit_resolver(node.receiver), "separator" => node.separator }
+          when Resolver::StartsWith
+            { "op" => "starts_with", "receiver" => emit_resolver(node.receiver), "substring" => node.substring }
+          when Resolver::EndsWith
+            { "op" => "ends_with", "receiver" => emit_resolver(node.receiver), "substring" => node.substring }
+          when Resolver::First then { "op" => "first", "receiver" => emit_resolver(node.receiver) }
+          when Resolver::Last  then { "op" => "last", "receiver" => emit_resolver(node.receiver) }
+          else
+            raise "unhandled resolver node #{node.class} — no JSON rendering exists for it (lib/hecks/bluebook/expression/ast_json.rb#emit_resolver)"
+          end
+        end
+      end
+    end
+  end
+end