hecks 1.0.2 → 1.1.0

data/lib/hecks/bluebook/aggregate.rb

@@ -1,4 +1,5 @@
 require_relative "behaviour/aggregate"
+require_relative "expression/ast_json"
 
 module Hecks
   module Bluebook
@@ -40,14 +41,14 @@ module Hecks
         attributes:       many(:attributes),
         value_objects:    many(:value_objects),
         commands:         many(:commands),
-        invariants:       -> { invariants.map { |rule| { description: rule.description, canonical: rule.canonical } } },
+        invariants:       -> { invariants.map { |rule| Expression::AstJson.rule_row(rule) } },
         # A PRECONDITION SHARED ACROSS COMMANDS, DECLARED ONCE (S10, ADR
         # 0025) — the aggregate's OWN named `given`s, the declaration a
         # referencing command's own (already-resolved) `givens` entry
         # came from. Both sides of "declared once, referenced many"
         # are real IR, the same shape a value object's TYPE and an
         # attribute's own reference to it both are.
-        preconditions:    -> { preconditions.map { |rule| { description: rule.description, canonical: rule.canonical } } },
+        preconditions:    -> { preconditions.map { |rule| Expression::AstJson.rule_row(rule) } },
         # S12, ADR 0025 — deliberately NOT folded into `attributes`:
         # `EraGuard::ShapeDiff` only ever walks `attributes` to decide
         # whether a NEW field leaves an existing record with something
@@ -55,10 +56,10 @@ module Hecks
         # is different — a record predating the `projects` declaration
         # is expected to be missing it until the rebuild sweep runs,
         # not a shape drift a translation needs to explain.
-        projected_fields: -> {
-          projected_fields.map { |field|
+        projected_fields: lambda {
+          projected_fields.map do |field|
             { name: field.name.to_s, reference: field.reference.to_s, remote_field: field.remote_field.to_s }
-          }
+          end
         },
         lifecycle:        one(:lifecycle),
         entities:         many(:entities),

data/lib/hecks/bluebook/assembly/aggregate_assembly.rb

@@ -77,11 +77,11 @@ module Hecks
         # and resolve. Deliberately across every list that can carry one — a
         # reference the walk misses resolves to nil, and a nil target is SKIPPED
         # rather than refused, so the guarantee would go quiet instead of red.
-        def stamp_references(ir)
-          lists = [ir.attributes, *ir.commands.map(&:attributes), *ir.queries.map(&:attributes)]
-          entity_reference_lists(ir.entities, lists)
+        def stamp_references(aggregate)
+          lists = [aggregate.attributes, *aggregate.commands.map(&:attributes), *aggregate.queries.map(&:attributes)]
+          entity_reference_lists(aggregate.entities, lists)
 
-          lists.flatten.select(&:reference?).each { |field| field.type.declared_in = ir }
+          lists.flatten.select(&:reference?).each { |field| field.type.declared_in = aggregate }
         end
 
         # S17, ADR 0026 — walks NESTED entities too (Dispatch, inside

data/lib/hecks/bluebook/assembly/build.rb

@@ -20,7 +20,7 @@ module Hecks
           contract = Assembly.contract(category)
           keywords = contract.fields.to_h { |keyword, (key, reader)| [keyword, read(reader, row[key])] }
 
-          holder(contract).public_send(contract.make, **keywords.merge(extra))
+          holder(contract).public_send(contract.make, **keywords, **extra)
         end
 
         def holder(contract)
@@ -37,8 +37,11 @@ module Hecks
           when Array
             # [:each, reader] maps a list ; [:option, name] reads one named option,
             # which needs its name as well as its value.
-            reader.first == :each ? Array(value).map { |held| Marks.public_send(reader.last, held) }
-                                  : Marks.option(reader.last, value)
+            if reader.first == :each
+              Array(value).map { |held| Marks.public_send(reader.last, held) }
+            else
+              Marks.option(reader.last, value)
+            end
           else Marks.public_send(reader, value)
           end
         end

data/lib/hecks/bluebook/assembly/contract.rb

@@ -1,5 +1,9 @@
 module Hecks
   module Bluebook
+    # The rulebook translating between the language's own declarations and the
+    # IR objects `Build`/`Reconstruction` produce from them — the `Contract`
+    # struct format itself (this file) plus, reopened in contracts.rb, the
+    # `CONTRACTS` table of one `Contract` per construct category.
     class Assembly
       # WHAT A CONSTRUCT NEEDS THAT THE LANGUAGE CANNOT SAY, and how a claim that a
       # field needs no assembling is CHECKED.
@@ -78,7 +82,7 @@ module Hecks
         end
 
         def answers?(method)
-          make == :declare ? holder.respond_to?(method) : holder.instance_methods.include?(method)
+          make == :declare ? holder.respond_to?(method) : holder.method_defined?(method)
         end
 
         def accepts?(keyword)

data/lib/hecks/bluebook/assembly/contracts.rb

@@ -1,5 +1,9 @@
 module Hecks
   module Bluebook
+    # Reopened here for `CONTRACTS`/`.contract(category)` — the one table of
+    # every construct category's own `Contract` (Bluebook, Aggregate,
+    # Command, ValueObject, Query, ...); see `Contract`'s own header
+    # (contract.rb) for the struct format each entry below fills in.
     class Assembly
       # ONE TABLE, WHERE THERE WERE FIVE HAND-WRITTEN MIRRORS OF IT.
       #

data/lib/hecks/bluebook/assembly/marks.rb

@@ -129,7 +129,8 @@ module Hecks
           # `:delegate`/`:corrects` (CommandBuilder#delegates_to's and
           # #corrects_impl's own comments) ride the SAME multi-binding
           # shape `:append` does.
-          return Mutation.new(target: target, op: op, source: appended(change[:fields])) if [:append, :delegate, :corrects].include?(op)
+          return Mutation.new(target: target, op: op, source: appended(change[:fields])) if [:append, :delegate,
+                                                                                             :corrects].include?(op)
 
           Mutation.new(target: target, op: op, source: classified(change[:source]))
         end

data/lib/hecks/bluebook/assembly.rb

@@ -38,15 +38,13 @@ module Hecks
         aggregates = Array(@declaration[:aggregates]).map { |row| AggregateAssembly.new(row).aggregate }
         models     = Array(@declaration[:read_models]).map { |row| Build.call("ReadModel", row) }
 
-        chapter = Build.call(
+        Build.call(
           "Bluebook", @declaration,
           aggregates:       aggregates,
           read_models:      models,
           policies:         reactions(aggregates),
           process_managers: Array(@declaration[:process_managers]).map { |row| process_manager(row) }
         )
-
-        chapter
       end
 
       private

data/lib/hecks/bluebook/attribute.rb

@@ -5,6 +5,12 @@ require_relative "../naming"
 
 module Hecks
   module Bluebook
+    # One declared field on a construct — name, type (a primitive, a
+    # Reference, or another construct's name, always spelled via `#spell`),
+    # whether it's a list, its default/optional/pattern, and the closed set
+    # it `admits`. What `attribute :x, Type` (or `identified_by`,
+    # `reference_to`, etc.) actually mints, on an Aggregate, Entity, Command,
+    # ValueObject, Query or PortOperation alike.
     class Attribute
       include Hecks::IR
       include Behaviour::Attribute

data/lib/hecks/bluebook/behaviour/policy.rb

@@ -24,6 +24,24 @@ module Hecks
         # event's own payload.
         def guarded? = !@where.to_s.empty?
 
+        # THE STRUCTURED FORM OF `where`, derived once — the same tree
+        # `AstJson.emit_predicate` spells for every rule row, memoized
+        # here because a policy is consulted once per event, not once per
+        # boot. Nil when there is no `where`, exactly as the wire carries
+        # it.
+        def where_ast
+          if defined?(@where_ast)
+            @where_ast
+          else
+            (@where_ast = guarded? ? Expression::AstJson.emit_predicate(@where) : nil)
+          end
+        end
+
+        # The rule-shaped reading of the guard, for `Evaluator.call_rule`
+        # — a policy's `where` has no description (nothing refuses with
+        # it; an unmet where is a silent skip).
+        def where_rule = @where_rule ||= Given.new(description: nil, canonical: @where, ast: where_ast)
+
         # THE FAN-OUT QUERY'S ROUTE, split the way the runtime runs it:
         # `[query_domain, aggregate_name, query_name]`. The query runs
         # against the triggering event's OWN domain unless `for_each`

data/lib/hecks/bluebook/behaviour/process_manager.rb

@@ -7,7 +7,23 @@ module Hecks
       module ProcessManager
         def hecks_name = @name
 
-        def handler_for(event) = @handlers.find { |h| h.event_type == event.to_s }
+        # THE LEG THAT ANSWERS — selected by (event, current state), C10.3
+        # (docs/semantics/bluebook-semantics.md). Two legs may answer the
+        # same event from different states; which one runs is decided by
+        # the state the instance is in, never by declaration order. With
+        # no `state` the reading is declarative — "does any leg answer this
+        # event, and what is it" — for callers that ask about the
+        # procedure rather than an instance (`saga`, the outbox's consumer
+        # selection). Build refuses two legs on one (event, state) pair
+        # (`ProcessManagerBuilder#validate!`), so a stated lookup is
+        # unambiguous by construction.
+        def handler_for(event, state = nil)
+          @handlers.find { |h| h.event_type == event.to_s && (state.nil? || h.from_state == state.to_s) }
+        end
+
+        def handlers_for(event) = @handlers.select { |h| h.event_type == event.to_s }
+
+        def handles?(event) = @handlers.any? { |h| h.event_type == event.to_s }
 
         # WHETHER A STATE IS ONE THIS PROCEDURE DECLARES — asked of a value
         # a real run left a saga instance holding (its live or rehydrated

data/lib/hecks/bluebook/behaviour/traits.rb

@@ -29,7 +29,7 @@ module Hecks
       # readers that need all of them ask for `identity_heads`.
       module Identified
         def derive_identity
-          @identity_paths = Array(@identified_by).map { |path| path.to_s }.reject(&:empty?)
+          @identity_paths = Array(@identified_by).map(&:to_s).reject(&:empty?)
           @identity_heads = @identity_paths.map { |path| path.split(".").first.to_sym }.uniq
           @identified_by  = @identity_heads.size == 1 ? @identity_heads.first : nil
         end

data/lib/hecks/bluebook/command.rb

@@ -1,9 +1,10 @@
 require_relative "behaviour/command"
 require_relative "../vocabulary"
+require_relative "expression/ast_json"
 
 module Hecks
   module Bluebook
-    Given = Struct.new(:description, :canonical, :predicate, keyword_init: true)
+    Given = Struct.new(:description, :canonical, :predicate, :ast, keyword_init: true)
 
     Mutation = Struct.new(:target, :op, :source, keyword_init: true) do
       include Hecks::IR
@@ -24,8 +25,8 @@ module Hecks
       # real layering inversion (runtime depends on bluebook, not the
       # reverse). "" (not nil) for ops with no sign, matching every other
       # optional IR text field's own absent-is-empty-string convention.
-      def self.sign_for(op)
-        Hecks::Vocabulary.rows("MutationOp").find { |row| row["name"] == op.to_s }&.fetch("sign", "") || ""
+      def self.sign_for(oper)
+        Hecks::Vocabulary.rows("MutationOp").find { |row| row["name"] == oper.to_s }&.fetch("sign", "") || ""
       end
 
       emits_ir(target: :target, op: :op, sign: -> { Mutation.sign_for(op) })
@@ -74,8 +75,8 @@ module Hecks
         goal:       :goal,
         references: :references,
         attributes: many(:attributes),
-        givens:     -> { givens.map { |rule| { description: rule.description, canonical: rule.canonical } } },
-        ensures:    -> { ensures.map { |rule| { description: rule.description, canonical: rule.canonical } } },
+        givens:     -> { givens.map { |rule| Expression::AstJson.rule_row(rule) } },
+        ensures:    -> { ensures.map { |rule| Expression::AstJson.rule_row(rule) } },
         mutations:  many(:mutations),
         emits:      :emits,
         # THE LIFECYCLE STATE THIS COMMAND IS ADMISSIBLE FROM (S10, ADR

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

@@ -2,8 +2,11 @@ require_relative "word_gate"
 module Hecks
   module Bluebook
     module DSL
+      # The `Hecks.adapter "Name" do port ...; field ...; secret ... end`
+      # receiver — collects the port it implements plus its own settings
+      # fields and secrets, then builds and judges an `Adapter` construct.
       class AdapterBuilder
-        GRAMMAR_CONTEXT = "Adapter"
+        GRAMMAR_CONTEXT = "Adapter".freeze
 
         include WordGate