hecks 1.0.2 → 1.1.0

data/lib/hecks/adapters/driven/postgres.rb

@@ -9,6 +9,7 @@ require_relative "../../query_specification/common/order_by"
 require_relative "../../query_specification/field_path"
 require_relative "../../runtime/errors"
 require_relative "../../runtime/event"
+require_relative "postgres/outbox"
 require_relative "../../runtime/instance"
 
 module Hecks
@@ -44,6 +45,7 @@ module Hecks
       include SqlQueryBuilder
       include SchemaBuilder
       include Codec
+      include PostgresOutbox
 
       SQL_TYPES = { "Integer" => "bigint", "Float" => "double precision" }.freeze
 
@@ -84,9 +86,9 @@ module Hecks
         # boot after the first, not news.
         connection.exec("SET client_min_messages = warning")
         connection
-      rescue PG::Error => error
+      rescue PG::Error => e
         raise Runtime::WiringError,
-              "cannot bind Postgres at #{declared} for #{name}: #{error.message.strip}"
+              "cannot bind Postgres at #{declared} for #{name}: #{e.message.strip}"
       end
 
       def initialize(aggregate:, settings: {}, root: nil)
@@ -110,6 +112,7 @@ module Hecks
         create_entry_table!
         create_event_table!
         create_saga_table!
+        create_outbox_table!
       end
 
       def table = @aggregate.storage_name
@@ -128,7 +131,10 @@ module Hecks
         order_sql = "ORDER BY id"
         if order_by
           name = order_by.to_s.split(".").first
-          raise Runtime::WiringError, "#{@aggregate.name} has no attribute #{order_by.inspect} to order by" unless @aggregate.lifecycle&.field.to_s == name || @aggregate.attribute(name)
+          unless @aggregate.lifecycle&.field.to_s == name || @aggregate.attribute(name)
+            raise Runtime::WiringError,
+                  "#{@aggregate.name} has no attribute #{order_by.inspect} to order by"
+          end
 
           spec = QuerySpecification::Common::OrderBy.new(field: order_by, direction: direction)
           order_sql = "ORDER BY #{order_clause(spec, nil)}"
@@ -169,6 +175,8 @@ module Hecks
       # zero rows back means the conflict branch's WHERE excluded the row
       # entirely — the version had already moved — so `nil` is returned
       # for the caller (`AppendOnly#save`) to treat as "stale, no-op".
+      # rubocop:disable Metrics/AbcSize -- the CAS/plain upsert split is one
+      # protocol; splitting it would hide the version handshake.
       def project(entry, expected_version: nil)
         return @db.exec_params("DELETE FROM #{quoted_table} WHERE id = $1", [entry.id]) if entry.delete?
 
@@ -193,6 +201,7 @@ module Hecks
         instance.version = result[0]["hecks_version"].to_i
         instance
       end
+      # rubocop:enable Metrics/AbcSize
 
       def entries
         @db.exec("SELECT aggregate_id, operation, state, mirrors FROM #{quoted_entry_table} ORDER BY sequence").map do |row|
@@ -221,18 +230,15 @@ module Hecks
       # transaction lives here, the one caller that runs both together.
       def save(instance)
         entry = Ports::Persistence::Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
-        @db.transaction { append(entry); project(entry) }
+        transaction do
+          append(entry)
+          project(entry)
+        end
       end
 
-      # Classification, journal append and snapshot replacement are one
-      # Postgres transaction. A row lock cannot serialize two first writers —
-      # there is no row to lock yet — so a transaction-scoped advisory lock on
-      # schema/table + aggregate id owns that missing-row race as well. Once a
-      # writer acquires it, the preceding writer has committed and status can
-      # be read from the materialized table without a runtime-side find.
       def atomic_put(entry, insert_only: false)
         status = nil
-        @db.transaction do
+        transaction do
           @db.exec_params(
             "SELECT pg_advisory_xact_lock(" \
             "hashtext(current_schema() || ':' || $1), hashtext($2))",
@@ -255,7 +261,10 @@ module Hecks
 
       def delete(id)
         entry = Ports::Persistence::Entry.new(operation: "delete", id: id.to_s, state: nil)
-        @db.transaction { append(entry); project(entry) }
+        transaction do
+          append(entry)
+          project(entry)
+        end
         true
       end
 
@@ -288,7 +297,8 @@ module Hecks
           "ON CONFLICT (domain, process_manager, correlation) DO UPDATE " \
           "SET state = EXCLUDED.state, memory = EXCLUDED.memory, " \
           "completed_compensations = EXCLUDED.completed_compensations, updated_at = now()",
-          [@domain, process_manager.to_s, correlation.to_s, state.to_s, JSON.generate(memory), JSON.generate(completed_compensations)]
+          [@domain, process_manager.to_s, correlation.to_s, state.to_s, JSON.generate(memory),
+           JSON.generate(completed_compensations)]
         )
       end
 
@@ -303,7 +313,8 @@ module Hecks
         return enum_for(:each_saga) unless block_given?
 
         @db.exec_params(
-          "SELECT process_manager, correlation, state, memory, completed_compensations FROM hecks_saga_instances WHERE domain = $1",
+          "SELECT process_manager, correlation, state, memory, completed_compensations " \
+          "FROM hecks_saga_instances WHERE domain = $1",
           [@domain]
         ).each do |row|
           yield row["process_manager"], row["correlation"], row["state"],

data/lib/hecks/adapters/driven/prism.rb

@@ -5,7 +5,18 @@ module Hecks
   module Adapters
     class NotExtractable < StandardError; end
 
+    # Extracts a `given`/`ensures`/invariant block's own source text back out
+    # of the `.rb` file it was defined in (via `block.source_location`),
+    # parses it with the `prism` gem, and canonicalises it — how a rule's
+    # predicate becomes readable, comparable text (era diffing, docs) rather
+    # than an opaque compiled Proc. Per-process `TREES` cache keyed by file
+    # path; `forget`/`forget_all` exist for a caller that reloads an edited
+    # file in-process (see their own comment).
     module Prism
+      # NOT frozen — a real cache, keyed by file path and mutated by
+      # #tree_for below (`TREES[file] ||= ...`) and #forget/#forget_all.
+      # False positive for Style/MutableConstant.
+      # rubocop:disable-next Style/MutableConstant
       TREES = {}
 
       module_function

data/lib/hecks/adapters/driven/sql_query_builder.rb

@@ -34,24 +34,11 @@ module Hecks
       }.freeze
 
       def query(declared, args = {}, context: {})
-        sql = +"SELECT #{select_list} FROM #{from_relation}"
-        clauses = []
+        sql = "SELECT #{select_list} FROM #{from_relation}"
         binds = []
-        declared.wheres.each do |clause|
-          value = query_value(clause.value, args)
-          expression = query_expression(clause.field, value: value)
-          if (null_predicate = QuerySpecification::Common::NullPolicy.sql_predicate(expression, clause.op, value))
-            clauses << null_predicate.first
-            next
-          end
-          clauses << where_clause(clause.op.to_s, expression, value, binds, field: clause.field)
-        end
+        clauses = where_clauses(declared, args, binds)
         sql << " WHERE #{clauses.join(' AND ')}" unless clauses.empty?
-        sql << if declared.order_by
-                 " ORDER BY #{order_clause(declared.order_by, declared.null_semantics)}"
-               else
-                 " ORDER BY id"
-               end
+        sql << order_by_sql(declared)
         sql << " LIMIT #{placeholder(binds, query_value(declared.limit.value, args).to_i)}" if declared.limit
         # An offset with no declared limit — SQLite refuses a bare OFFSET
         # outright (LIMIT -1 is its unbounded idiom) while Postgres accepts
@@ -65,10 +52,34 @@ module Hecks
 
       private
 
-      def where_clause(op, expression, value, binds, field: nil)
-        case op
+      # Every declared `where` clause, compiled in declaration order — a
+      # null-policy predicate short-circuits the ordinary comparator path
+      # per clause, same as it did inline. `binds` is populated in place
+      # (the same array `query` goes on to push LIMIT/OFFSET placeholders
+      # into afterward), so pulling this loop out changes nothing about
+      # bind-parameter order.
+      def where_clauses(declared, args, binds)
+        declared.wheres.each_with_object([]) do |clause, clauses|
+          value = query_value(clause.value, args)
+          expression = query_expression(clause.field, value: value)
+          if (null_predicate = QuerySpecification::Common::NullPolicy.sql_predicate(expression, clause.op, value))
+            clauses << null_predicate.first
+            next
+          end
+          clauses << where_clause(clause.op.to_s, expression, value, binds, field: clause.field)
+        end
+      end
+
+      def order_by_sql(declared)
+        return " ORDER BY #{order_clause(declared.order_by, declared.null_semantics)}" if declared.order_by
+
+        " ORDER BY id"
+      end
+
+      def where_clause(oper, expression, value, binds, field: nil)
+        case oper
         when "eq", "ne", "gt", "gte", "lt", "lte"
-          "#{comparable_expression(expression, value)} #{COMPARATORS.fetch(op)} #{placeholder(binds, value)}"
+          "#{comparable_expression(expression, value)} #{COMPARATORS.fetch(oper)} #{placeholder(binds, value)}"
         when "contains"
           member = field && list_member(field)
           if member
@@ -97,7 +108,7 @@ module Hecks
           # which Postgres overrides to cast numerics.
           "CAST(#{expression} AS TEXT) IN (#{members.map { |member| placeholder(binds, member) }.join(', ')})"
         else
-          raise ArgumentError, "#{dialect_name} query adapter does not support #{op.inspect}"
+          raise ArgumentError, "#{dialect_name} query adapter does not support #{oper.inspect}"
         end
       end
 
@@ -137,6 +148,16 @@ module Hecks
       # path that can never match. Measured, not assumed: a `where` on a
       # has_one/belongs_to/reference_to field returned zero rows against
       # real data until that exclusion was removed.
+      # `member` resolves through two ORDERED fallback tiers — the bound
+      # value's own numeric field first, then the declared value object's
+      # numeric-or-sole attribute — each documented above as fixing a
+      # real, measured bug (a reference field matching nothing, a
+      # single-attribute VO silently falling to the wrong convention).
+      # Splitting the tiers apart would separate two writes to the same
+      # `member` local across method boundaries, hiding the fallback
+      # order that makes them correct together.
+      # rubocop:disable-next Metrics/CyclomaticComplexity
+      # rubocop:disable-next Metrics/PerceivedComplexity
       def query_expression(field, value: nil)
         name, *path = field.to_s.split(".")
         attribute = @aggregate.attribute(name)
@@ -147,6 +168,10 @@ module Hecks
         member = if path.empty? && value
                    hash = value.is_a?(Runtime::Value) ? value.to_h : value
                    numeric = hash.is_a?(Hash) && hash.find { |_key, item| item.is_a?(Numeric) }
+                   # NOT &.-able: `numeric` can be `false` (hash.is_a?(Hash) came
+                   # back false) as well as nil (.find came back empty) — `&.`
+                   # only guards nil, so `false.first` raises. False positive.
+                   # rubocop:disable-next Style/SafeNavigation
                    numeric ? numeric.first : nil
                  end
         member ||= if path.empty? && attribute && value_object?(attribute)

data/lib/hecks/adapters/driven/sqlite/codec.rb

@@ -13,7 +13,9 @@ module Hecks
             { name: attribute.name, attribute: attribute, sql_type: sql_type(attribute) }
           end
           lifecycle = @aggregate.lifecycle
-          fields << { name: lifecycle.field, attribute: nil, sql_type: "TEXT" } if lifecycle && !fields.any? { |field| field[:name] == lifecycle.field }
+          fields << { name: lifecycle.field, attribute: nil, sql_type: "TEXT" } if lifecycle && fields.none? do |field|
+            field[:name] == lifecycle.field
+          end
           # `projects` FIELDS (S12, ADR 0025) ARE A LOCAL COLUMN TOO —
           # `CommandInterpreter#seed_projected_fields`/`RebuildSweep`
           # both write one straight into `Instance#state` the same as

data/lib/hecks/adapters/driven/sqlite/projection.rb

@@ -140,8 +140,15 @@ module Hecks
       end
 
       def decode_for(aggregate, row)
+        decode_fields(fields_for(aggregate), aggregate, row)
+      end
+
+      # The field list a row decodes against: every declared attribute,
+      # plus the lifecycle field and any `projects` fields not already
+      # among them (both read back raw — see `decode_fields`).
+      def fields_for(aggregate)
         fields = aggregate.attributes.map { |attribute| [attribute.name, attribute] }
-        if (lifecycle = aggregate.lifecycle) && !fields.any? { |name, _| name == lifecycle.field }
+        if (lifecycle = aggregate.lifecycle) && fields.none? { |name, _| name == lifecycle.field }
           fields << [lifecycle.field, nil]
         end
         # `projects` FIELDS (S12, ADR 0025) NEED READING BACK TOO — `project`
@@ -154,8 +161,16 @@ module Hecks
         aggregate.projected_fields.each do |field|
           fields << [field.name, nil] unless fields.any? { |name, _| name == field.name }
         end
+        fields
+      end
+
+      def decode_fields(fields, aggregate, row)
         fields.each_with_object({}) do |(name, attribute), state|
           raw = row[name.to_s]
+          # rubocop:disable Lint/DuplicateBranch -- the nil-attribute and
+          # reference-id branches both just answer `raw`, coincidentally, for
+          # two unrelated reasons (see each branch's own comment); merging
+          # them would blur that distinction.
           state[name] =
             if attribute.nil?
               raw
@@ -165,6 +180,7 @@ module Hecks
               # A reference is a scalar id — see Codec#decode.
               raw
             end
+          # rubocop:enable Lint/DuplicateBranch
         end
       end
     end

data/lib/hecks/adapters/driven/sqlite/schema_builder.rb

@@ -10,7 +10,7 @@ module Hecks
         def create_aggregate_table!
           columns = persisted_fields.map { |field| "#{quote_ident(field[:name])} #{field[:sql_type]}" }
           @db.execute(
-            "CREATE TABLE IF NOT EXISTS #{quoted_table} (id TEXT PRIMARY KEY#{columns.empty? ? '' : ', '}#{columns.join(', ')})"
+            "CREATE TABLE IF NOT EXISTS #{quoted_table} (id TEXT PRIMARY KEY#{', ' unless columns.empty?}#{columns.join(', ')})"
           )
           # RIGHT HERE, NOT AS A SEPARATE STEP IN `Sqlite#initialize` —
           # `create_aggregate_table!` is the one piece of DDL `D1`
@@ -96,6 +96,28 @@ module Hecks
           raise unless e.message.include?("duplicate column name")
         end
 
+        def create_outbox_table!
+          @db.execute(<<~SQL)
+            CREATE TABLE IF NOT EXISTS hecks_outbox (
+              id           INTEGER PRIMARY KEY AUTOINCREMENT,
+              delivery_id  TEXT NOT NULL UNIQUE,
+              event_uid    TEXT NOT NULL,
+              aggregate    TEXT NOT NULL,
+              domain       TEXT NOT NULL,
+              kind         TEXT NOT NULL,
+              consumer     TEXT NOT NULL,
+              event        TEXT NOT NULL,
+              status       TEXT NOT NULL DEFAULT 'pending',
+              attempts     INTEGER NOT NULL DEFAULT 0,
+              error        TEXT,
+              enqueued_at  TEXT NOT NULL,
+              claimed_at   TEXT,
+              settled_at   TEXT
+            )
+          SQL
+          @db.execute("CREATE INDEX IF NOT EXISTS idx_hecks_outbox_status ON hecks_outbox(aggregate, status)")
+        end
+
         def sql_type(attr)
           return "TEXT" if attr.list?
 

data/lib/hecks/adapters/driven/sqlite.rb

@@ -9,6 +9,7 @@ require_relative "../../query_specification/common/null_policy"
 require_relative "../../query_specification/common/order_by"
 require_relative "../../runtime/errors"
 require_relative "../../runtime/event"
+require_relative "../../runtime/outbox"
 require_relative "../../runtime/instance"
 
 module Hecks
@@ -63,6 +64,17 @@ module Hecks
         ensure_entry_mirrors_column!
         create_event_table!
         create_saga_table!
+        create_outbox_table!
+      end
+
+      # RE-ENTRANT ON PURPOSE — `atomic_put` opens its own transaction
+      # and `Interpreting#run_dispatch_order` opens one around the whole
+      # save+emit pair; SQLite3 refuses a BEGIN inside a BEGIN, so the
+      # inner call joins the outer one instead. Same shape Postgres uses.
+      def transaction(&)
+        return yield if @db.transaction_active?
+
+        @db.transaction(&)
       end
 
       def table = @aggregate.storage_name
@@ -81,7 +93,10 @@ module Hecks
         order_sql = "ORDER BY id"
         if order_by
           name = order_by.to_s.split(".").first
-          raise Runtime::WiringError, "#{@aggregate.name} has no attribute #{order_by.inspect} to order by" unless @aggregate.lifecycle&.field.to_s == name || @aggregate.attribute(name)
+          unless @aggregate.lifecycle&.field.to_s == name || @aggregate.attribute(name)
+            raise Runtime::WiringError,
+                  "#{@aggregate.name} has no attribute #{order_by.inspect} to order by"
+          end
 
           spec = QuerySpecification::Common::OrderBy.new(field: order_by, direction: direction)
           order_sql = "ORDER BY #{order_clause(spec, nil)}"
@@ -142,8 +157,10 @@ module Hecks
 
       def save(instance)
         entry = Ports::Persistence::Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
-        append(entry)
-        project(entry)
+        transaction do
+          append(entry)
+          project(entry)
+        end
       end
 
       # The outcome lookup, journal append and snapshot replacement share one
@@ -151,7 +168,7 @@ module Hecks
       # adapter-native operation owns both concurrency and outcome reporting.
       def atomic_put(entry, insert_only: false)
         status = nil
-        @db.transaction do
+        transaction do
           exists = !@db.get_first_value("SELECT 1 FROM #{quoted_table} WHERE id = ?", [entry.id.to_s]).nil?
           if insert_only && exists
             status = :conflicted
@@ -202,11 +219,63 @@ module Hecks
       # either way; a domain that wants an obviously-named saga store
       # already gets one by sharing `database` across its aggregates,
       # the recommended, common case.
+      # THE OUTBOX — see `Runtime::Outbox`. Rows land in the SAME
+      # database as this aggregate (the only way the enqueue shares the
+      # save's transaction), keyed by the aggregate's storage name so an
+      # adapter instance only ever reads back its own rows even when
+      # several aggregates share one file. `INSERT OR IGNORE` on the
+      # UNIQUE delivery_id makes a re-enqueue of the same (event,
+      # consumer) a no-op; `outbox_claim`'s `WHERE status = 'pending'`
+      # is the compare-and-set that lets exactly one relay win a row.
+      def outbox_enqueue(rows)
+        rows.filter_map do |row|
+          @db.execute(
+            "INSERT OR IGNORE INTO hecks_outbox (delivery_id, event_uid, aggregate, domain, kind, consumer, event, " \
+            "status, attempts, enqueued_at) VALUES (?, ?, ?, ?, ?, ?, ?, 'pending', 0, ?)",
+            [row.delivery_id, row.event_uid, row.aggregate, row.domain, row.kind, row.consumer,
+             JSON.generate(row.event), Time.now.utc.iso8601]
+          )
+          next nil if @db.changes.zero?
+
+          row.id = @db.last_insert_row_id
+          row.status = "pending"
+          row
+        end
+      end
+
+      def outbox_claim(id)
+        @db.execute(
+          "UPDATE hecks_outbox SET status = 'claimed', attempts = attempts + 1, claimed_at = ? " \
+          "WHERE id = ? AND status = 'pending'",
+          [Time.now.utc.iso8601, id]
+        )
+        @db.changes == 1
+      end
+
+      def outbox_settle(id, status:, error: nil)
+        @db.execute(
+          "UPDATE hecks_outbox SET status = ?, error = ?, settled_at = ? WHERE id = ?",
+          [status.to_s, error, Time.now.utc.iso8601, id]
+        )
+        @db.changes == 1
+      end
+
+      def outbox_rows(status: nil)
+        sql   = "SELECT * FROM hecks_outbox WHERE aggregate = ?"
+        binds = [table]
+        if status
+          sql << " AND status = ?"
+          binds << status.to_s
+        end
+        @db.execute("#{sql} ORDER BY id", binds).map { |row| outbox_row(row) }
+      end
+
       def save_saga(process_manager:, correlation:, state:, memory:, completed_compensations: [])
         @db.execute(
-          "INSERT OR REPLACE INTO hecks_saga_instances (domain, process_manager, correlation, state, memory, completed_compensations) " \
-          "VALUES (?, ?, ?, ?, ?, ?)",
-          [@domain, process_manager.to_s, correlation.to_s, state.to_s, JSON.generate(memory), JSON.generate(completed_compensations)]
+          "INSERT OR REPLACE INTO hecks_saga_instances (domain, process_manager, correlation, state, memory, " \
+          "completed_compensations) VALUES (?, ?, ?, ?, ?, ?)",
+          [@domain, process_manager.to_s, correlation.to_s, state.to_s, JSON.generate(memory),
+           JSON.generate(completed_compensations)]
         )
       end
 
@@ -221,7 +290,8 @@ module Hecks
         return enum_for(:each_saga) unless block_given?
 
         @db.execute(
-          "SELECT process_manager, correlation, state, memory, completed_compensations FROM hecks_saga_instances WHERE domain = ?",
+          "SELECT process_manager, correlation, state, memory, completed_compensations " \
+          "FROM hecks_saga_instances WHERE domain = ?",
           [@domain]
         ).each do |row|
           yield row["process_manager"], row["correlation"], row["state"],
@@ -234,6 +304,15 @@ module Hecks
 
       # ── SqlQueryBuilder's dialect hooks ─────────────────────────────
 
+      def outbox_row(row)
+        Runtime::Outbox::Row.new(
+          id: row["id"], delivery_id: row["delivery_id"], event_uid: row["event_uid"], aggregate: row["aggregate"],
+          domain: row["domain"], kind: row["kind"], consumer: row["consumer"],
+          event: JSON.parse(row["event"], symbolize_names: true), status: row["status"],
+          attempts: row["attempts"].to_i, error: row["error"]
+        )
+      end
+
       def select_list = "*"
       def from_relation = quoted_table
       def dialect_name = "SQLite"

data/lib/hecks/adapters/driven.rb

@@ -1,4 +1,7 @@
 module Hecks
+  # Reopened here purely to require in every driven adapter under
+  # adapters/driven/ below (see the comment inside for what "driven side"
+  # means) — the actual namespace is declared in adapters.rb.
   module Adapters
     # The driven side — every store or reader an adapter declaration can
     # bind. A small adapter is one file beside this one; sqlite, postgres
@@ -32,6 +35,7 @@ require_relative "driven/postgres"
 Hecks::Adapters.autoload(:PostgresEra, "hecks/ports/persistence/plugins/era")
 require_relative "driven/lambda"
 require_relative "driven/heki"
+require_relative "driven/local_storage"
 require_relative "driven/prism"
 require_relative "driven/folder"
 require_relative "driven/d1"

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)