hecks 0.3.0 → 1.0.0

data/lib/hecks/adapters/driven/postgres_era.adapter

@@ -1,3 +1,14 @@
+# ADR 0033 — the `PostgresEra` Ruby CLASS moved into the loadable era
+# persistence plugin (`lib/hecks/ports/persistence/plugins/era/`); this
+# declaration stays here, unmoved. `Adapters::Folder#load_library` globs
+# `.adapter` files by DIRECTORY, not by require path, on every boot,
+# regardless of which adapters a given domain actually binds — the same
+# reason every other adapter's own `.adapter` file lives beside this one.
+# Pure metadata (which port, which fields) — no era-specific code, and
+# harmless for a domain that never binds `persisted_by "PostgresEra"`.
+# `registry.adapter_class("PostgresEra")` is only ever resolved for a
+# domain that actually binds to it, at which point the plugin must
+# already be `require`d for the class to exist.
 Hecks.adapter "PostgresEra" do
   port  "persistence"
   field :database

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

@@ -14,6 +14,23 @@ module Hecks
           end
           lifecycle = @aggregate.lifecycle
           fields << { name: lifecycle.field, attribute: nil, sql_type: "TEXT" } if lifecycle && !fields.any? { |field| field[:name] == lifecycle.field }
+          # `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
+          # any other field, so a column has to exist to hold it or
+          # `save`'s own `columns =`/`values =` build (this file, not
+          # here) silently drops it on every write. No `attribute` of
+          # their own to carry (`ProjectedField` is a bare name/
+          # reference/remote_field triple, not a typed attribute) —
+          # treated as a raw scalar, same as the lifecycle field just
+          # above: every real corpus use projects a status/lifecycle
+          # string, and `encode_field`/`decode` both already pass a
+          # `attribute: nil` field through untouched, not JSON-encoded.
+          @aggregate.projected_fields.each do |field|
+            next if fields.any? { |f| f[:name] == field.name }
+
+            fields << { name: field.name, attribute: nil, sql_type: "TEXT" }
+          end
           fields
         end
 

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

@@ -1,5 +1,8 @@
 require_relative "../../../runtime/instance"
 require_relative "../../../runtime/value"
+require_relative "../../../runtime/errors"
+require_relative "../../../runtime/refusal_wording"
+require_relative "../../../rendering"
 require_relative "../../../ports/query/in_memory"
 
 # The subclass needs its parent — and sqlite.rb requires this file at
@@ -29,6 +32,34 @@ module Hecks
       # Execute a declared read model against the projected aggregate-head
       # tables. The report shape is assembled from SQL-selected rows, rather
       # than scanning repositories and matching references in Ruby.
+      #
+      # M19 (docs/audits/2026-08-10-main-bug-audit.md,
+      # docs/audits/2026-08-11-bug-triage.md) — this used to diverge from
+      # `Runtime::ReadModelInterpreter#project` (the in-process path) on
+      # two counts, both fixed here to agree with it:
+      #
+      # MISSING ROOT: the in-process path's own `fetch` refuses with
+      # `NotFound` when the reference argument names no record —
+      # `query_read_model` used to answer a silent `{root: nil, ...}`
+      # instead, the one path a caller could dispatch a read model
+      # against a record that never existed and get back something that
+      # LOOKS like an empty report rather than the refusal every other
+      # path gives.
+      #
+      # CHAINED-INCLUDE JOIN SCOPE: a non-root head was always matched
+      # against the ROOT's own id, regardless of what it actually
+      # references — correct for a head that references the root
+      # directly, silently EMPTY for one that references another
+      # included head instead (`Leaf` -> `Mid` -> `Root`, `Leaf` itself
+      # has no attribute referencing `Root` at all, so `references`
+      # was always `[]`). The in-process path's own root-first fix
+      # (`ReadModelInterpreter#project`'s "ROOT FIRST, ALWAYS" comment)
+      # already matches a head against ANY already-projected source, not
+      # only the root — `select_related` now does the same: each head is
+      # matched against every source resolved so far (root first, then
+      # declared order — the same one-level-of-declaration-order
+      # dependency the in-process path itself still has, documented
+      # there as L2, not a gap introduced here).
       def query_read_model(_domain, model, args, bluebook = nil)
         raise ArgumentError, "projection query needs its domain bluebook" unless bluebook
 
@@ -37,15 +68,27 @@ module Hecks
         # declared as a path and followed.
         reference_id = args.fetch(model.reference_name).to_s
         eligible = model.filtered_head_name
+
+        # ROOT FIRST, ALWAYS — see this method's own header. Mirrors
+        # `ReadModelInterpreter#project`'s identical partition, for the
+        # identical reason: a later head's own join has to be able to
+        # match against a root (or another head) already resolved.
+        root_heads, other_heads = model.aggregate_heads.partition { |head| head[:aggregate] == model.reference_target }
+        projected = []
         reports = {}
-        model.aggregate_heads.each do |head|
+        (root_heads + other_heads).each do |head|
           aggregate = bluebook.aggregate(head[:aggregate])
           rows = if head[:aggregate] == model.reference_target
-                   [select_projected(aggregate, reference_id)].compact
+                   [select_projected(aggregate, reference_id) ||
+                     raise(Runtime::NotFound,
+                           Runtime::RefusalWording.render("NotFound", "read_model_reference_missing",
+                                                          aggregate: head[:aggregate],
+                                                          offered:   Hecks::Rendering.describe(reference_id)))]
                  else
-                   select_related(aggregate, model.reference_target, reference_id)
+                   select_related(aggregate, projected)
                  end
           rows = Ports::Query::InMemory.execute(rows, model, args) if head[:as] == eligible
+          projected << { aggregate: head[:aggregate], rows: rows }
           reports[head[:as]] = if head[:many]
                                  rows.map { |row| Runtime::Value.materialize(row.to_h) }
                                else
@@ -62,18 +105,32 @@ module Hecks
         row && projected_instance(aggregate, row)
       end
 
-      def select_related(aggregate, target, id)
-        references = aggregate.attributes.select do |attribute|
-          attribute.reference? && attribute.type.target_name == target.to_s
+      # Matched against EVERY source already projected (root first, then
+      # declared order — see this class's own `query_read_model` header),
+      # not only the root — a head whose own reference points at another
+      # included head rather than the root directly used to match nothing
+      # at all, since its reference attribute was compared against a
+      # target (the root) it never names.
+      def select_related(aggregate, projected)
+        matches = projected.flat_map do |source|
+          references = aggregate.attributes.select do |attribute|
+            attribute.reference? && attribute.type.target_name == source[:aggregate].to_s
+          end
+          next [] if references.empty?
+
+          ids = source[:rows].map { |row| row.id.to_s }
+          next [] if ids.empty?
+
+          references.product(ids)
         end
-        return [] if references.empty?
+        return [] if matches.empty?
 
         # A REFERENCE COLUMN HOLDS THE ID, so it compares as itself. The
         # `json_extract(col,'$.value') = ? OR col = ?` this replaced was
         # reading both shapes because both existed — one written by the
         # command path, one by older journals. There is one shape now.
-        clauses = references.map { |attribute| "#{quote_ident(attribute.name)} = ?" }
-        bind = references.map { id.to_s }
+        clauses = matches.map { |attribute, _id| "#{quote_ident(attribute.name)} = ?" }
+        bind = matches.map { |_attribute, id| id }
         @db.execute("SELECT * FROM #{quote_ident(aggregate.storage_name)} WHERE #{clauses.join(' OR ')} ORDER BY id", bind)
            .map { |row| projected_instance(aggregate, row) }
       end
@@ -87,6 +144,16 @@ module Hecks
         if (lifecycle = aggregate.lifecycle) && !fields.any? { |name, _| name == lifecycle.field }
           fields << [lifecycle.field, nil]
         end
+        # `projects` FIELDS (S12, ADR 0025) NEED READING BACK TOO — `project`
+        # (above) already writes one into its own column via `persisted_fields`
+        # (`Codec#persisted_fields`, this class's own superclass module), but
+        # this method built its own independent field list that never
+        # consulted it — a column `project` populated correctly, silently
+        # dropped on every read back out. Same raw-passthrough treatment as
+        # the lifecycle field just above: `attribute: nil` down in the loop.
+        aggregate.projected_fields.each do |field|
+          fields << [field.name, nil] unless fields.any? { |name, _| name == field.name }
+        end
         fields.each_with_object({}) do |(name, attribute), state|
           raw = row[name.to_s]
           state[name] =

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

@@ -74,14 +74,26 @@ module Hecks
         def create_saga_table!
           @db.execute(<<~SQL)
             CREATE TABLE IF NOT EXISTS hecks_saga_instances (
-              domain          TEXT NOT NULL,
-              process_manager TEXT NOT NULL,
-              correlation     TEXT NOT NULL,
-              state           TEXT NOT NULL,
-              memory          TEXT NOT NULL,
+              domain               TEXT NOT NULL,
+              process_manager      TEXT NOT NULL,
+              correlation          TEXT NOT NULL,
+              state                TEXT NOT NULL,
+              memory               TEXT NOT NULL,
+              completed_compensations  TEXT NOT NULL DEFAULT '[]',
               PRIMARY KEY (domain, process_manager, correlation)
             )
           SQL
+          # `CREATE TABLE IF NOT EXISTS` above is a no-op against a table
+          # this same domain already created before this column existed
+          # — the same reason Postgres's own `create_saga_table!` needs
+          # its own `ADD COLUMN IF NOT EXISTS`. SQLite/D1's own `ALTER
+          # TABLE ... ADD COLUMN` has no `IF NOT EXISTS` guard on every
+          # version this adapter supports, so a duplicate-column error
+          # is caught and treated as "already there" rather than relied
+          # on to never happen.
+          @db.execute("ALTER TABLE hecks_saga_instances ADD COLUMN completed_compensations TEXT NOT NULL DEFAULT '[]'")
+        rescue StandardError => e
+          raise unless e.message.include?("duplicate column name")
         end
 
         def sql_type(attr)

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

@@ -40,7 +40,15 @@ module Hecks
         # (§2/§4) — falls back to the aggregate's own name for a
         # directly-instantiated adapter (specs), same fallback shape
         # Postgres's own @domain already uses.
-        @domain    = (settings[:domain] || settings["domain"] || aggregate.name).to_s
+        @domain    = (
+          if settings.key?(:domain)
+            settings[:domain]
+          elsif settings.key?("domain")
+            settings["domain"]
+          else
+            aggregate.name
+          end
+        ).to_s
 
         FileUtils.mkdir_p(File.dirname(@path))
         @db = SQLite3::Database.new(@path)
@@ -89,7 +97,12 @@ module Hecks
       def append(entry)
         @db.execute(
           "INSERT INTO #{quoted_entry_table} (aggregate_id, operation, state, mirrors) VALUES (?, ?, ?, ?)",
-          [entry.id, entry.operation, JSON.generate(entry.state), JSON.generate(entry.mirrors)]
+          # `mirrors` (unlike `state`) is a NULLABLE column — an absent
+          # mirrors hash must bind a real SQL NULL, not the four-character
+          # JSON text `"null"` (`JSON.generate(nil)`), or a future `IS NULL`
+          # check against it would never match. Same guard `postgres_era.rb`
+          # already uses for its own journal's `mirrors` column.
+          [entry.id, entry.operation, JSON.generate(entry.state), entry.mirrors && JSON.generate(entry.mirrors)]
         )
         entry
       end
@@ -189,11 +202,11 @@ 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.
-      def save_saga(process_manager:, correlation:, state:, memory:)
+      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) " \
-          "VALUES (?, ?, ?, ?, ?)",
-          [@domain, process_manager.to_s, correlation.to_s, state.to_s, JSON.generate(memory)]
+          "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
 
@@ -208,11 +221,12 @@ module Hecks
         return enum_for(:each_saga) unless block_given?
 
         @db.execute(
-          "SELECT process_manager, correlation, state, memory 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"],
-                JSON.parse(row["memory"], symbolize_names: true)
+                JSON.parse(row["memory"], symbolize_names: true),
+                JSON.parse(row["completed_compensations"] || "[]", symbolize_names: true)
         end
       end
 
@@ -269,7 +283,14 @@ module Hecks
       def quoted_entry_table = quote_ident(entry_table)
 
       def resolve_path(settings, root)
-        declared = settings[:database] || settings["database"] || "data/#{table}.db"
+        declared =
+          if settings.key?(:database)
+            settings[:database]
+          elsif settings.key?("database")
+            settings["database"]
+          else
+            "data/#{table}.db"
+          end
         return declared if declared.start_with?("/")
 
         File.join(root || Dir.pwd, declared)

data/lib/hecks/adapters/driven.rb

@@ -11,7 +11,25 @@ end
 require_relative "driven/memory"
 require_relative "driven/sqlite"
 require_relative "driven/postgres"
-require_relative "driven/postgres_era"
+# `PostgresEra` is NOT `require_relative`d here — ADR 0033 moved it, and
+# the rest of the era/lineage/translation subsystem, behind a loadable
+# persistence plugin (`hecks/ports/persistence/plugins/era`) rather than
+# requiring every app to carry it whether or not anything ever binds
+# `persisted_by "PostgresEra"`. `Module#autoload` is the one-line seam
+# that makes that genuinely load-nothing-until-asked instead of pushing
+# an explicit `require` onto every one of the ~15 generic `bin/*` tools
+# that boot an arbitrary checked-in domain (several of which — pizzas,
+# compliance, chess, roster — bind PostgresEra): the FIRST real
+# `Adapters.const_get("PostgresEra")` (`registry/verification.rb`'s own
+# adapter resolution, unchanged) transparently `require`s the plugin
+# entry point, which defines the constant AND calls `register_plugin`
+# as its own side effect (`plugins/era.rb`'s last line) — the exact
+# same effect an explicit `require "hecks/ports/persistence/plugins/
+# era"` has, just deferred to the moment something is actually asked
+# for `PostgresEra` rather than sprinkled across every caller that
+# might. A domain that never binds it never triggers the autoload, so
+# never loads a line of era code — unchanged from ADR 0033's own goal.
+Hecks::Adapters.autoload(:PostgresEra, "hecks/ports/persistence/plugins/era")
 require_relative "driven/lambda"
 require_relative "driven/heki"
 require_relative "driven/prism"

data/lib/hecks/behaviors/dsl.rb

@@ -41,10 +41,39 @@ module Hecks
                            "say which command or query this example exercises"
         end
 
+        validate_expect!
+
         TestCase.new(description: @description, tests_command: @tests_command,
                      on_aggregate: @on_aggregate, kind: @kind,
                      setups: @setups, input: @input, expect: @expect)
       end
+
+      private
+
+      # Closes the silent-pass paths a free-form `expect(**kwargs)` merge
+      # otherwise leaves open: a test with no `expect` at all asserts
+      # nothing and passes whenever dispatch doesn't raise; `count:` on a
+      # command and `emits:` on a query are each read by neither runner
+      # (Expectations#run_command/#run_query), so they're accepted here
+      # and then silently ignored at run time. Checking both at BUILD
+      # time, not in the runners, makes them errors on the file that
+      # wrote them rather than green checks nobody questions.
+      def validate_expect!
+        if @expect.empty?
+          raise Malformed, "test #{@description.inspect} has no `expect` — say what this " \
+                           "example proves (ok:, refused:, emits:, count:, or a field name)"
+        end
+
+        if @kind == :command && @expect.key?(:count)
+          raise Malformed, "test #{@description.inspect}: `expect count:` only applies to " \
+                           "queries — a command has no row count to check"
+        end
+
+        if @kind == :query && @expect.key?(:emits)
+          raise Malformed, "test #{@description.inspect}: `expect emits:` only applies to " \
+                           "commands — a query never dispatches, so it never emits"
+        end
+      end
     end
 
     class BehaviorsBuilder

data/lib/hecks/behaviors/expectations.rb

@@ -3,6 +3,7 @@ require_relative "../runtime/loader"
 require_relative "../runtime/errors"
 require_relative "../runtime/value"
 require_relative "../runtime/reaction_invocation"
+require_relative "../ports/persistence/binding_policy"
 
 # Hecks::Behaviors::Expectations
 #
@@ -83,7 +84,40 @@ module Hecks
         key   = files.map { |file| [file, File.exist?(file) ? File.mtime(file).to_f : nil] }
 
         RUNTIMES_LOCK.synchronize do
-          RUNTIMES[key] ||= Hecks::Runtime::Loader.boot_files(files, install_facade: false)
+          RUNTIMES[key] ||= boot_and_guard(files)
+        end
+      end
+
+      # `reset_runtime_state!` only drops repository OBJECTS between
+      # tests (registry.rb) — sufficient isolation for `Memory`, whose
+      # `@records` is a plain per-instance ivar, so a fresh object really
+      # is a fresh store. Against anything else (Sqlite, Postgres) the
+      # rows themselves stay put: tests leak into each other, and a
+      # suite booted against a domain's REAL hecksagon writes to a real
+      # database. Refusing that wiring here, at boot, is the same shape
+      # of guard `BindingPolicy` already applies to a missing bind — the
+      # project's identity is refusing bad wiring up front, not
+      # discovering it mid-suite.
+      def boot_and_guard(files)
+        runtime = Hecks::Runtime::Loader.boot_files(files, install_facade: false)
+        guard_memory_only!(runtime)
+        runtime
+      end
+
+      def guard_memory_only!(runtime)
+        runtime.registry.bluebooks.each_value do |bluebook|
+          bluebook.aggregates.each do |aggregate|
+            bind = Ports::Persistence::BindingPolicy.resolve(runtime.registry, bluebook.name, aggregate)
+            next if bind.adapter == Ports::Persistence::DEFAULT_ADAPTER
+
+            raise Malformed,
+                  "#{bluebook.name}::#{aggregate.hecks_name} is persisted_by " \
+                  "#{bind.adapter.inspect}, not #{Ports::Persistence::DEFAULT_ADAPTER.inspect} — " \
+                  "a behaviors suite's `loads` must resolve every aggregate to an in-memory " \
+                  "binding, or tests leak state into each other and write to a real database. " \
+                  "Load a Memory-bound sibling hecksagon instead of the domain's real one — see " \
+                  "examples/pizzas/bluebook/pizzas.behaviors's own `loads` comment for the pattern."
+          end
         end
       end
 
@@ -182,7 +216,33 @@ module Hecks
           return fail_result(test, "expected count: #{expected}, got #{count}") if count != expected
         end
 
-        check_ok(test) || pass_result(test)
+        return check_ok(test) || pass_result(test) unless field_expectations?(test)
+
+        row = query_row(test, rows)
+        return row if row.is_a?(Result)
+
+        check_ok(test) || check_fields(test, row) || pass_result(test)
+      end
+
+      def field_expectations?(test)
+        test.expect.keys.any? { |key| !SPECIAL_KEYS.include?(key) }
+      end
+
+      # A field expectation on a query names one row's shape, so it only
+      # makes sense once the query has settled on exactly one — the same
+      # reason `expect status: "sold"` on a multi-row answer would be
+      # ambiguous about which row it's describing. `check_fields` itself
+      # stays row-shaped (it already is, for `run_command`'s settled
+      # state); this picks which row it reads.
+      def query_row(test, rows)
+        return rows unless rows.is_a?(Array)
+
+        case rows.size
+        when 1 then rows.first
+        when 0 then fail_result(test, "expect names a field, but the query returned no rows")
+        else fail_result(test, "expect names a field, but the query returned #{rows.size} rows — " \
+                               "narrow it with `input`/`expect count: 1` first")
+        end
       end
 
       def check_ok(test)

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

@@ -255,20 +255,49 @@ module Hecks
         ),
 
         # S17, ADR 0026 — Dispatch is a genuine entity now, nested under
-        # Handler (`entity "Dispatch"`, reaction.bluebook) — two levels
-        # deep, "no life outside its Handler" (the ADR's own words).
-        # `command_name` is Dispatch's own real, non-positional identity
-        # — neither `position` nor `handler` is a stored field any more,
-        # the same reason Handler's own contract, above, dropped them.
+        # Handler (`entity "Dispatch"`, process_manager.bluebook) — two
+        # levels deep, "no life outside its Handler" (the ADR's own
+        # words). `command_name` ALONE used to be Dispatch's own
+        # identity, until items #151/#152 (`process_manager.bluebook`'s
+        # own `DispatchPosition` comment) found it collided the instant a
+        # real handler fanned the same command out more than once —
+        # `position` now joins it, walk-minted the same way every other
+        # category's own `position` is (`derived: { position: :walk }`,
+        # the same entry ProcessManager's own contract carries above) —
+        # never a stored field on `DispatchSpec` itself, exactly like
+        # `handler` before it.
+        # `compensates_command_name`/`compensates_with_spec` — FOLDED,
+        # the SAME kind `Lifecycle`'s own `state_field`/`default` claim
+        # (one IR OBJECT, `DispatchSpec#compensates`, feeding two
+        # separate language fields): `Readings#field_value`'s own
+        # `contract.folded` branch reads
+        # `node.compensates.to_h[:command_name]` / `[:with_spec]` for
+        # the JUDGE'S offering side, nil-safe when there is no
+        # compensation at all (`through`'s own `return nil unless
+        # held`). `compensates_with_spec` ALSO needs its own row shaper
+        # (`compensates_with_spec_rows`, readings.rb) for the JUDGE'S
+        # list-offering side — the with_spec pairs still need one
+        # "BindCompensation" append per pair, the same reason
+        # `with_spec` itself needs `with_spec_rows`, one level deeper.
+        # `Reconstruction#dispatch` reads the two flat fields back off
+        # the row and assembles the nested `DispatchSpec` by hand — a
+        # nested OBJECT is not one of the shapes `declaration()`'s own
+        # generic per-field hash-build can produce, the identical reason
+        # `handler`/`process_manager` pass a `:children` list through
+        # `extra:` instead.
         "Dispatch"       => Contract.new(
           holder: DispatchSpec, make: :new,
           fields: {
             command_name: [:command_name, :plain],
             with_spec:    [:with_spec,    :bindings]
           },
-          rows: { with_spec: :with_spec_rows },
+          rows: { with_spec: :with_spec_rows, compensates_with_spec: :compensates_with_spec_rows },
           reads: { with_spec: [:from, :with_spec] },
-          derived: {}
+          derived: {
+            position:                 :walk,
+            compensates_command_name: [:folded, :compensates, :command_name],
+            compensates_with_spec:    [:folded, :compensates, :with_spec]
+          }
         ),
 
         # S14, ADR 0026 — Syntax/Keyword/Argument are never built via

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

@@ -126,9 +126,10 @@ module Hecks
           target = change[:target].to_sym
           op     = change[:op].to_sym
 
-          # `:delegate` (CommandBuilder#delegates_to's own comment) rides
-          # the SAME multi-binding shape `:append` does.
-          return Mutation.new(target: target, op: op, source: appended(change[:fields])) if [:append, :delegate].include?(op)
+          # `: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)
 
           Mutation.new(target: target, op: op, source: classified(change[:source]))
         end

data/lib/hecks/bluebook/assembly.rb

@@ -71,7 +71,20 @@ module Hecks
 
       def handler(row)
         Build.call("Handler", row,
-                   dispatches: Array(row[:dispatches]).map { |leg| Build.call("Dispatch", leg) })
+                   dispatches: Array(row[:dispatches]).map { |leg| dispatch(leg) })
+      end
+
+      # `compensates` — a PLAIN HASH on the declaration (`Reconstruction#
+      # dispatch`'s own comment for why), built into the real
+      # `DispatchSpec` its own field actually is by recursing through
+      # THIS SAME method, one level in — the identical move `handler`
+      # itself takes into `dispatches`, one level up. `nil` when there
+      # is nothing to compensate; `Build.call` never sees a
+      # `compensates:` key it does not know how to read either way, the
+      # same reason `compensates` never joined `Contract#fields` at all.
+      def dispatch(row)
+        compensates = row[:compensates] && dispatch(row[:compensates])
+        Build.call("Dispatch", row, compensates: compensates)
       end
     end
   end

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

@@ -37,7 +37,24 @@ module Hecks
           return nil if matches.empty?
           return matches.first unless current_state
 
-          matches.find { |t| applies_from?(t, current_state) } || matches.first
+          # NOT `|| matches.first` — that used to silently hand back an
+          # ARBITRARY declared transition for `command` whenever none of
+          # them actually admitted `current_state`, picking a `target`
+          # that command dispatch would in fact have refused (that
+          # refusal is `CommandRules::Admissibility#admissible_transition`'s
+          # own job, which raises `LifecycleRefused` for exactly this
+          # case rather than guessing — this module has no state subject
+          # to build that refusal message from, only the two bare
+          # values callers passed in). Zero production callers reach
+          # this branch today (both real dispatch paths that check a
+          # transition go through `admissible_transition`, not
+          # `target_for`/`match_transition`), so this raise is a
+          # backstop, not a live behaviour change — same shape as
+          # `CommandRules::Arithmetic#sign_of`'s own fix.
+          matches.find { |t| applies_from?(t, current_state) } ||
+            raise(Runtime::WiringError,
+                  "no transition for #{command.inspect} admits state #{current_state.inspect} " \
+                  "— add a from: covering it, or check admissibility before calling #target_for")
         end
 
         def applies_from?(transition, current)

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

@@ -27,8 +27,21 @@ module Hecks
           leg = handler_for(Bluebook::ProcessManager::REFUSED)
           return nil unless leg
 
+          # `compensations` — a STATIC PREVIEW, declaration order, not
+          # one instance's own runtime history (which legs a given
+          # instance actually completed is per-instance state,
+          # `SagaInterpreter`'s own `completed_compensations`, not a
+          # fact `Saga` — a pure declaration reading — could ever hold).
+          # Every `compensates` ANY handler's own dispatch declares,
+          # forward declaration order, THEN whatever this leg's own
+          # hand-written body still lists — coexistence, not replacement
+          # (`ProcessManagerBuilder::HandlerBuilder#dispatch_impl`'s own
+          # comment): a saga can derive some of its compensation and
+          # still hand-write the rest for what isn't expressible as
+          # "undo command X".
+          derived = handlers.flat_map { |handler| handler.dispatches.filter_map(&:compensates) }
           Bluebook::Saga.new(trigger: Bluebook::ProcessManager::REFUSED, from_state: leg.from_state,
-                             to_state: leg.to_state, reversals: leg.dispatches)
+                             to_state: leg.to_state, compensations: derived + leg.dispatches)
         end
 
         def saga? = !saga.nil?

data/lib/hecks/bluebook/chapter.rb

@@ -30,17 +30,27 @@ module Hecks
       IR_VERSION = 1
 
       emits_ir(
-        ir_version:       -> { IR_VERSION },
-        name:             :name,
-        version:          :version,
-        vision:           :vision,
-        classification:   :classification,
-        aggregates:       many(:aggregates),
-        read_models:      many(:read_models),
-        policies:         many(:policies),
-        process_managers: many(:process_managers),
-        attaches_to:      :attaches_to,
-        canonical_form:   -> { Expression::CanonicalForm.table }
+        ir_version:        -> { IR_VERSION },
+        name:              :name,
+        version:           :version,
+        vision:            :vision,
+        classification:    :classification,
+        # M10 — a domain rename (`formerly_known_as "OldName"`) drives a
+        # real Postgres schema rename at boot (EraResolver reads
+        # `bluebook.formerly_known_as` off the live Ruby object) and the
+        # meta-validator's cache key is `SHA256(JSON(bluebook.to_h))` — so
+        # a fact this method didn't spell was a fact two chapters
+        # differing ONLY by their old name could hash identically on,
+        # same as read-model filters before them. Spelled here for the
+        # same reason `version`/`vision` are: a plain field, present
+        # (possibly nil) rather than silently absent.
+        formerly_known_as: :formerly_known_as,
+        aggregates:        many(:aggregates),
+        read_models:       many(:read_models),
+        policies:          many(:policies),
+        process_managers:  many(:process_managers),
+        attaches_to:       :attaches_to,
+        canonical_form:    -> { Expression::CanonicalForm.table }
       )
 
       attr_reader :name, :version, :vision, :aggregates, :policies, :process_managers,

data/lib/hecks/bluebook/command.rb

@@ -39,7 +39,7 @@ module Hecks
       # the tail, which is why a construct with a variable shape needs no
       # new mixin API.
       def to_h
-        return super.merge(fields: appended_fields) if [:append, :delegate].include?(op)
+        return super.merge(fields: appended_fields) if [:append, :delegate, :corrects].include?(op)
 
         super.merge(source: classified_source)
       end