hecks 0.3.0 → 1.0.0

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/canonical_form.rb

@@ -37,7 +37,7 @@ module Hecks
 
         def step(text, rule)
           case rule.strategy
-          when "collapse_whitespace" then text.gsub(/\s+/, " ")
+          when "collapse_whitespace" then map_outside_strings(text) { |segment| segment.gsub(/\s+/, " ") }
           when "replace"             then replace(text, rule)
           else
             raise ArgumentError, "#{rule.strategy.inspect} is not a linked normalisation strategy"
@@ -45,9 +45,77 @@ module Hecks
         end
 
         def replace(text, rule)
-          return text.gsub(rule.source_token, rule.replacement) if rule.boundary == "none"
+          map_outside_strings(text) do |segment|
+            if rule.boundary == "none"
+              segment.gsub(rule.source_token, rule.replacement)
+            else
+              segment.gsub(/#{Regexp.escape(rule.source_token)}(?![[:alnum:]_])/, rule.replacement)
+            end
+          end
+        end
+
+        # Applies a normalisation rule to the text OUTSIDE quoted string
+        # literals only, copying every quoted run through byte-for-byte.
+        # Every rule here (collapse_whitespace, the `.length`→`.size` fold)
+        # used to run quote-blind — `"a  b"` collapsed to `"a b"` and
+        # `"a.length"` folded to `"a.size"` just as readily as the real
+        # source outside the quotes, silently rewriting what a predicate
+        # compares a string attribute against, not merely how the
+        # predicate itself is spelled. A canonical string literal's
+        # CONTENTS are data, never syntax to normalise.
+        #
+        # Handles both `"` and `'` delimiters (this grammar's own
+        # `Resolver.quoted?` admits either), quote-aware exactly the way
+        # `Evaluator.top_level_index`/`Resolver.array_elements` already are
+        # elsewhere in this sublanguage. An unterminated quote (malformed
+        # input) is passed through raw rather than risk mangling it further.
+        def map_outside_strings(text)
+          result = +""
+          buffer = +""
+          quote = nil
+
+          text.each_char do |char|
+            if quote
+              buffer << char
+              if char == quote
+                result << buffer
+                buffer = +""
+                quote = nil
+              end
+            elsif ['"', "'"].include?(char)
+              result << yield(buffer)
+              # `char.dup`, not `char.to_s` (a no-op on a String — always
+              # returns self, never a copy) and not `+char` either
+              # (`String#+@` only dups a FROZEN receiver; `each_char`'s
+              # yielded strings aren't frozen, so `+char` is just as
+              # much a no-op here). Without a REAL copy, `buffer` and
+              # `quote` alias the same mutable object: the very next
+              # `buffer << char` grows `quote` right along with it, so
+              # `char == quote` can only ever compare a single character
+              # against an ever-lengthening string and never closes the
+              # literal — everything after a predicate's first quoted
+              # string silently skipped normalisation for the rest of
+              # the text, undetected because passing text through
+              # unnormalised is silent. MASKED by every existing spec
+              # here, which only checks that quoted CONTENTS survive
+              # untouched (the M7 fix this method exists for) — that
+              # still holds by accident once the bug makes the "outside"
+              # branch unreachable. Found live: a multi-line `given`/
+              # `ensures` block whose ONLY quoted literal closes before a
+              # later line — the newline and that later line's own
+              # indentation went uncollapsed, diverging from
+              # `hecks-parse`'s own (correct) single-space join.
+              # `spec/parser_parity_spec.rb`, roster's "a front-row seat
+              # takes a member of age".
+              buffer = char.dup
+              quote = char.dup
+            else
+              buffer << char
+            end
+          end
 
-          text.gsub(/#{Regexp.escape(rule.source_token)}(?![[:alnum:]_])/, rule.replacement)
+          result << (quote ? buffer : yield(buffer))
+          result
         end
       end
     end

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

@@ -67,6 +67,23 @@ module Hecks
           left, right = split_top_level(expr, "&&")
           return And.new(left: parse(left), right: parse(right)) if left
 
+          # Tried BEFORE `.include?`/comparisons, not after — `!` negates
+          # the WHOLE boolean expression that follows it (`!names.include?(x)`
+          # means `!(names.include?(x))`, never "call .include? on the negated
+          # receiver"), so the leading marker has to be stripped and the
+          # remainder re-parsed before anything downstream gets a chance to
+          # mis-scan across it. It used to sit after `match_include`, whose
+          # naive `rindex(".include?(")` has no concept of a leading `!` —
+          # for `!names.include?(x)` it swallowed the `!` straight into the
+          # haystack text ("!names"), which `Resolver.parse` cannot resolve,
+          # so every spelling of negated membership raised instead of
+          # evaluating. Moving the check here fixes both the bare prefix
+          # (`!names.include?(x)`) and the parenthesized form
+          # (`!(names.include?(x))`) — the recursive `parse` call sees the
+          # clean remainder and correctly finds the `.include?` (or `&&`/`||`)
+          # inside it.
+          return Not.new(node: parse(Regexp.last_match(1))) if expr =~ /\A!(.+)\z/
+
           membership = match_include(expr)
           return Include.new(haystack: Resolver.parse(membership[0]), needle: Resolver.parse(membership[1])) if membership
 
@@ -75,8 +92,6 @@ module Hecks
             return Compare.new(operator: op, left: Resolver.parse(left), right: Resolver.parse(right)) if left
           end
 
-          return Not.new(node: parse(Regexp.last_match(1))) if expr =~ /\A!(.+)\z/
-
           Resolve.new(expr: Resolver.parse(expr))
         end
 
@@ -145,11 +160,28 @@ module Hecks
           value.nil? ? "nil" : value.class.name
         end
 
+        # THE SAME MIS-SPLIT `Resolver.match_call` had (its own comment
+        # has the full story), found here too by the same generator: a
+        # `.include?` needle can itself be — or contain — ANOTHER
+        # `.include?` call (`"".include?(arr.all? { |el| "".include?("")
+        # }.to_s)`, a String built via `.to_s` off a block predicate
+        # whose own body happens to include one) — `rindex` finds the
+        # INNERMOST occurrence, not the outermost this split actually
+        # needs. Fixed identically: try each occurrence left to right,
+        # keep the first whose own balanced-paren match reaches the
+        # string's last character — `Resolver.matching_paren` is reused
+        # directly rather than duplicated, the same depth-tracking rule
+        # either grammar layer needs here.
         def match_include(expr)
-          index = expr.rindex(".include?(")
-          return nil unless index && expr.end_with?(")")
+          start = 0
+          marker = ".include?("
+          while (index = expr.index(marker, start))
+            close = Resolver.matching_paren(expr, index + marker.length)
+            return [expr[0...index], expr[(index + marker.length)...close]] if close == expr.length - 1
 
-          [expr[0...index], expr[(index + ".include?(".length)...-1]]
+            start = index + 1
+          end
+          nil
         end
 
         # Declared the same way in Vocabulary::IncludeHaystack
@@ -243,9 +275,20 @@ module Hecks
             # built to close. `{`/`}` cannot legitimately appear inside
             # a quoted literal either, so this sits beside the existing
             # paren-depth branch, not instead of it.
-            elsif char == "(" || char == "{"
+            #
+            # `[`/`]` -- the identical lesson a THIRD time (found live via
+            # the type-directed bounded-exhaustive expression generator,
+            # Phase 7 of the equivalence-gap plan): `Resolver::ArrayLiteral`
+            # (`[a, b]`) can appear as a general sub-expression, not only
+            # as `.include?`'s own haystack, the moment an array-typed
+            # attribute or a synthesized literal is embedded anywhere else
+            # -- and an element containing a top-level `+`/comparison of
+            # its own (`[0, 0 + 0]`) used to read as a split point for
+            # THIS expression's own boolean/comparison grammar, exactly
+            # the way an un-tracked `{`/`}` once did for block predicates.
+            elsif char == "(" || char == "{" || char == "["
               depth += 1
-            elsif char == ")" || char == "}"
+            elsif char == ")" || char == "}" || char == "]"
               depth -= 1
             elsif depth.zero? && expr[index, operator.length] == operator
               return index if !block_given? || yield(index)

data/lib/hecks/bluebook/expression/projection.json

@@ -149,6 +149,54 @@
       "category": "enumeration",
       "precedence": 10,
       "arity": 2
+    },
+    {
+      "symbol": ".match?",
+      "category": "pattern_match",
+      "precedence": 7,
+      "arity": 2
+    },
+    {
+      "symbol": ".present?",
+      "category": "presence",
+      "precedence": 7,
+      "arity": 1
+    },
+    {
+      "symbol": ".blank?",
+      "category": "presence",
+      "precedence": 7,
+      "arity": 1
+    },
+    {
+      "symbol": ".split",
+      "category": "text",
+      "precedence": 7,
+      "arity": 2
+    },
+    {
+      "symbol": ".start_with?",
+      "category": "text",
+      "precedence": 7,
+      "arity": 2
+    },
+    {
+      "symbol": ".end_with?",
+      "category": "text",
+      "precedence": 7,
+      "arity": 2
+    },
+    {
+      "symbol": ".first",
+      "category": "positional",
+      "precedence": 7,
+      "arity": 1
+    },
+    {
+      "symbol": ".last",
+      "category": "positional",
+      "precedence": 7,
+      "arity": 1
     }
   ],
   "normalisations": [