hecks 1.0.2 → 1.2.0

data/lib/hecks/adapters.rb

@@ -1,4 +1,8 @@
 module Hecks
+  # Namespace for every driven-side adapter (Memory, Folder, SQLite,
+  # Postgres, Heki, ...) a `persisted_by`/port binding can resolve to;
+  # concrete adapters are required in below from adapters/driven and
+  # register themselves into this namespace as they load.
   module Adapters
   end
 end

data/lib/hecks/behaviors/dsl.rb

@@ -11,6 +11,10 @@ module Hecks
     # inside a boot, over a suite that was never going to be scoped.
     class Malformed < StandardError; end
 
+    # The `test "description" do ... end` block's own receiver — collects
+    # `tests`/`setup`/`input`/`expect` calls and builds a `TestCase` (ir.rb).
+    # `validate_expect!` (private, below) is where a malformed or empty
+    # `expect` is refused at build time rather than silently passing later.
     class TestCaseBuilder
       def initialize(description)
         @description   = description
@@ -76,6 +80,9 @@ module Hecks
       end
     end
 
+    # The top-level `Hecks.behaviors "Name" do ... end` receiver — collects
+    # `vision`/`loads`/`test` calls and builds a `BehaviorsSuite` (ir.rb),
+    # refusing to build one missing either `vision` or `loads` (`#build`).
     class BehaviorsBuilder
       def initialize(name, source_path:)
         @name        = name

data/lib/hecks/behaviors/expectations.rb

@@ -38,6 +38,8 @@ require_relative "../ports/persistence/binding_policy"
 #    always on and `emits:` is expected to see them.
 module Hecks
   module Behaviors
+    # See this file's own header above for what this module does and the
+    # two deliberate deviations from the prior port it's built from.
     module Expectations
       module_function
 
@@ -75,6 +77,10 @@ module Hecks
       # loop or a long rspec session actually relies on. `runtime:` lets
       # a caller that already holds a booted runtime (a spec, a REPL)
       # hand it in; it is reset the same way.
+      # NOT frozen — a real cache, mutated below (`RUNTIMES[key] ||=
+      # boot_and_guard(files)`) and by #reset!. False positive for
+      # Style/MutableConstant.
+      # rubocop:disable-next Style/MutableConstant
       RUNTIMES      = {}
       RUNTIMES_LOCK = Mutex.new
       private_constant :RUNTIMES, :RUNTIMES_LOCK
@@ -137,11 +143,17 @@ module Hecks
         before = runtime.registry.event_log.length
         result = dispatch_command(runtime, verb, test.input)
 
-        return fail_result(test, "expected refused: #{test.expect[:refused].inspect} but dispatch succeeded") if test.expect.key?(:refused)
+        if test.expect.key?(:refused)
+          return fail_result(test,
+                             "expected refused: #{test.expect[:refused].inspect} but dispatch succeeded")
+        end
 
         if (expected_emits = test.expect[:emits])
           actual = runtime.registry.event_log[before..].map(&:name)
-          return fail_result(test, "expected emits: #{expected_emits.inspect}, got #{actual.inspect}") unless actual == expected_emits
+          unless actual == expected_emits
+            return fail_result(test,
+                               "expected emits: #{expected_emits.inspect}, got #{actual.inspect}")
+          end
         end
 
         check_ok(test) || check_fields(test, settled_state(runtime, verb, result)) || pass_result(test)
@@ -205,7 +217,10 @@ module Hecks
       def run_query(test, runtime, verb)
         rows = runtime.query(verb, **test.input)
 
-        return fail_result(test, "expected refused: #{test.expect[:refused].inspect} but the query succeeded") if test.expect.key?(:refused)
+        if test.expect.key?(:refused)
+          return fail_result(test,
+                             "expected refused: #{test.expect[:refused].inspect} but the query succeeded")
+        end
 
         if (expected = test.expect[:count])
           count = if rows.is_a?(Array)
@@ -307,6 +322,14 @@ module Hecks
       def qualify(command, on_aggregate, bluebooks, kind:)
         return command.to_s if command.to_s.include?(".")
 
+        candidates = qualify_candidates(command, on_aggregate, bluebooks, kind)
+        disambiguate_qualified_name(candidates, command, kind, bluebooks)
+      end
+
+      # THE SEARCH — every (bluebook, aggregate) pair that declares a
+      # command/query named `command`, narrowed to `on_aggregate` by name
+      # when given.
+      def qualify_candidates(command, on_aggregate, bluebooks, kind)
         members = kind == :query ? :queries : :commands
         pairs =
           if on_aggregate
@@ -314,8 +337,13 @@ module Hecks
           else
             bluebooks.flat_map { |bb| bb.aggregates.map { |agg| [bb, agg] } }
           end
-        candidates = pairs.select { |_, agg| agg.public_send(members).any? { |m| m.hecks_name == command.to_s } }
+        pairs.select { |_, agg| agg.public_send(members).any? { |m| m.hecks_name == command.to_s } }
+      end
 
+      # THE REPORT — zero candidates and more-than-one candidates both
+      # refuse (with a different message); exactly one resolves to its
+      # dotted FQN.
+      def disambiguate_qualified_name(candidates, command, kind, bluebooks)
         case candidates.size
         when 0
           raise ArgumentError, "no aggregate among #{bluebooks.map(&:name).inspect} declares a #{kind} " \

data/lib/hecks/behaviors/rspec.rb

@@ -16,6 +16,8 @@ require_relative "../behaviors"
 #   end
 module Hecks
   module Behaviors
+    # See this file's own header above for what `describe_file` does and
+    # how a consumer wires it into their own `bundle exec rspec` run.
     module RSpec
       module_function
 

data/lib/hecks/behaviors/runner.rb

@@ -6,6 +6,10 @@ require_relative "expectations"
 # that actually touches a live runtime; this file finds `.behaviors`
 # files, loads them, and maps their tests through it.
 module Hecks
+  # See this file's own header above for `.run`/`.run_all`/`.parse` — the
+  # discovery-and-aggregation half of the `.behaviors` authoring surface;
+  # `Expectations` (expectations.rb) is the impure edge that actually runs
+  # one test against a live runtime.
   module Behaviors
     FileResult = Struct.new(:path, :parse_error, :runs, keyword_init: true)
     SweepResult = Struct.new(:root, :files_swept, :files, :summary, keyword_init: true)

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
@@ -169,9 +170,19 @@ module Hecks
         # a saga with nothing to do.
         def read(value) = Literal.read(value)
 
+        # `target:` (ADR 0055) — read straight off the wire, unconverted:
+        # it's already the bare aggregate-name STRING `WhereClause#to_h`/
+        # `OrderBy#to_h`/`LimitSpec#to_h` wrote (`resolve_target`'s own
+        # `Naming.demodulise` already ran once, at DSL-build time; this is
+        # the REPLAY path every real boot actually goes through, reading
+        # that same wire shape back — see this class's own header). Absent
+        # from `clause`/`declared` entirely on older wire data that never
+        # declared `on:` — `clause[:target]`/`declared[:target]` reads
+        # `nil` for a missing key exactly like an explicit `nil` would,
+        # so this is additive, not a migration.
         def where_clause(clause)
           QuerySpecification::Common::WhereClause.new(
-            field: clause[:field], op: clause[:op].to_sym, value: read(clause[:value])
+            field: clause[:field], op: clause[:op].to_sym, value: read(clause[:value]), target: clause[:target]
           )
         end
 
@@ -179,14 +190,14 @@ module Hecks
           return nil unless declared
 
           QuerySpecification::Common::OrderBy.new(
-            field: declared[:field], direction: declared[:direction].to_sym
+            field: declared[:field], direction: declared[:direction].to_sym, target: declared[:target]
           )
         end
 
         def limit(declared)
           return nil unless declared
 
-          QuerySpecification::Common::LimitSpec.new(value: read(declared[:value]))
+          QuerySpecification::Common::LimitSpec.new(value: read(declared[:value]), target: declared[:target])
         end
 
         # EVERY OTHER SPECIFICATION OPTION, from one table.

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

@@ -14,14 +14,59 @@ module Hecks
 
         def query_name = Naming.snake(@name)
 
-        # WHICH GATHERED HEAD THE FILTERING APPLIES TO, so the read-model
-        # interpreter can ask this directly rather than re-deriving or
-        # re-checking it.
-        def filtered_head_name
-          return nil unless wheres.any? || order_by || limit || offset || authorization&.tenant ||
-                            @group_by.any? || count? || @median_field
-
-          @aggregate_heads.find { |head| head[:many] }&.fetch(:as)
+        # WHICH GATHERED HEADS THE FILTERING APPLIES TO (ADR 0055) — plural,
+        # since `where`/`order_by`/`limit`/`offset` can now each independently
+        # name a many-side head via `on:` once there's more than one. A read
+        # model with a single many-side head keeps the old reading: every
+        # UNTARGETED option (plus `group_by`/`count`/`median`, still
+        # single-head-only — ADR 0055) applies to it, same as before `on:`
+        # existed. With several many-side heads, only the ones actually named
+        # by a targeted option are eligible.
+        def filtered_head_names
+          many = @aggregate_heads.select { |head| head[:many] }
+          return [] if many.empty?
+
+          return single_filtered_head_name(many) if many.one?
+
+          targets = (wheres.map(&:target) + [order_by&.target, limit&.target, offset&.target]).compact.uniq
+          targets.filter_map { |target| many.find { |head| head[:aggregate] == target.to_s } }.map { |head| head[:as] }
+        end
+
+        # The pre-`on:` reading (ADR 0055), unchanged: with exactly one
+        # many-side head, every UNTARGETED option (plus `group_by`/`count`/
+        # `median`, still single-head-only) applies to it — split out only
+        # to keep `filtered_head_names` itself under this file's own
+        # complexity budget, not because the two questions differ in kind.
+        def single_filtered_head_name(many)
+          declared = wheres.any? || order_by || limit || offset || authorization&.tenant ||
+                     @group_by.any? || count? || @median_field
+          declared ? [many.first[:as]] : []
+        end
+
+        # THE where/order_by/limit/offset THAT APPLY TO ONE ELIGIBLE HEAD
+        # (ADR 0055) — a small view `Ports::Query::InMemory.execute` reads
+        # exactly the way it already reads a whole `Query`/`ReadModel`
+        # (`.wheres`/`.order_by`/`.limit`/`.offset`/`.null_semantics`), scoped
+        # to `head_as`'s own aggregate: an UNTARGETED option applies when
+        # `head_as` is the read model's ONE many-side head (the pre-`on:`
+        # reading, unchanged) ; a TARGETED one applies when its `target`
+        # resolves to `head_as`'s own aggregate.
+        FilteredOptions = Struct.new(:wheres, :order_by, :limit, :offset, :null_semantics)
+
+        def options_for(head_as)
+          many = @aggregate_heads.select { |head| head[:many] }
+          aggregate_name = @aggregate_heads.find { |head| head[:as] == head_as }&.fetch(:aggregate)
+          applies = lambda do |target|
+            target.nil? ? many.one? : target.to_s == aggregate_name
+          end
+
+          FilteredOptions.new(
+            wheres.select { |where| applies.call(where.target) },
+            order_by && applies.call(order_by.target) ? order_by : nil,
+            limit && applies.call(limit.target) ? limit : nil,
+            offset && applies.call(offset.target) ? offset : nil,
+            null_semantics
+          )
         end
       end
     end

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