hecks 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e2957772a5d25ada566a632461d6aa1829b6fb8016d4b563377ba7c856c1ed7d
-  data.tar.gz: 0e92b2b30420c37c8b92c087e26873223e47cdadcf88d7cbed1583b4a39729ee
+  metadata.gz: 0d66cdbdb775a92f3cfcf3f626637cffd6fb81915d7edbcccfe21e1b7c980606
+  data.tar.gz: a43786075ea299d26d6d1f23075cf2176fdad15b7efa235234c4a6e321ec15f3
 SHA512:
-  metadata.gz: 7a9641aeac769fa7e43131942276f8d5acf121daa2adc5b9d9e1375d5f509588ed3a5bd09b6995bb4c1214dd074dfe27666e8490a44e53f7042131a22f3fd8cd
-  data.tar.gz: 6cfb8e4e7852d8cbeaf417cf20ae952a94df5d3c12acf79cb8f4c4a0e454ca01a1e04d17956fa2de4f359776f3b6c3b66b199a0fa6eb8fcf7b4389bcdfc834d8
+  metadata.gz: ac3883e9e6ebeef723718dfa39785d2dcdd0e57e613f6ca21a9519040eb11278f22eedbe597965d1b28e3dfa08b98ac2d0a989686cd7b8aec0d8d97dd476acec
+  data.tar.gz: f610074205ca1a39121169ef02109445b60ca66bf517c1a8351e8c761a1863fccfe0f9b41075fa00cc8225c017c82eefdb47c38566469fe378d0879aec115860

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

@@ -20,11 +20,14 @@ module Hecks
         return yield unless @db.transaction_status == PG::PQTRANS_IDLE
 
         @db.transaction(&)
+      rescue PG::ConnectionBad
+        reconnect!
+        raise
       end
 
       def outbox_enqueue(rows)
         rows.filter_map do |row|
-          result = @db.exec_params(
+          result = pg_exec_params(
             "INSERT INTO hecks_outbox (delivery_id, event_uid, aggregate, domain, kind, consumer, event, status, attempts) " \
             "VALUES ($1, $2, $3, $4, $5, $6, $7, 'pending', 0) ON CONFLICT (delivery_id) DO NOTHING RETURNING id",
             [row.delivery_id, row.event_uid, row.aggregate, row.domain, row.kind, row.consumer, JSON.generate(row.event)]
@@ -38,7 +41,7 @@ module Hecks
       end
 
       def outbox_claim(id) # rubocop:disable Naming/PredicateMethod
-        @db.exec_params(
+        pg_exec_params(
           "UPDATE hecks_outbox SET status = 'claimed', attempts = attempts + 1, claimed_at = now() " \
           "WHERE id = $1 AND status = 'pending'",
           [id]
@@ -46,7 +49,7 @@ module Hecks
       end
 
       def outbox_settle(id, status:, error: nil) # rubocop:disable Naming/PredicateMethod
-        @db.exec_params(
+        pg_exec_params(
           "UPDATE hecks_outbox SET status = $2, error = $3, settled_at = now() WHERE id = $1",
           [id, status.to_s, error]
         ).cmd_tuples == 1
@@ -59,7 +62,7 @@ module Hecks
           sql << " AND status = $2"
           binds << status.to_s
         end
-        @db.exec_params("#{sql} ORDER BY id", binds).map do |row|
+        pg_exec_params("#{sql} ORDER BY id", binds).map do |row|
           Runtime::Outbox::Row.new(
             id: row["id"].to_i, delivery_id: row["delivery_id"], event_uid: row["event_uid"], aggregate: row["aggregate"],
             domain: row["domain"], kind: row["kind"], consumer: row["consumer"],

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

@@ -0,0 +1,57 @@
+module Hecks
+  module Adapters
+    # SELF-HEALING CONNECTION — shared verbatim by `Postgres` and the era
+    # plugin's `PostgresEra`, the same way `PostgresOutbox` (outbox.rb) is:
+    # nothing here is lineage-specific, and `PostgresOutbox`'s own
+    # `@db.exec*` calls route through this module's `pg_exec`/
+    # `pg_exec_params` too, since both classes mix it in. Needs `@db` (a
+    # `PG::Connection`), `@aggregate`, and `@settings` from the including
+    # class — the same three `self.class.connect_for(@aggregate.name,
+    # @settings)` already needs to build one in the first place.
+    #
+    # A backend killed out from under an adapter (a DBA's own
+    # `pg_terminate_backend`, a load balancer's failover, a restart) —
+    # chaos-tested against the plain `Postgres` adapter: `PG::ConnectionBad`
+    # on the query that hit it, and PERMANENTLY on every query after,
+    # since nothing ever replaced `@db` with a live connection.
+    # `pg_exec`/`pg_exec_params` are the two primitives every other method
+    # in either class funnels through — wrapping them here, once,
+    # self-heals `@db` for the NEXT caller. THE CURRENT CALL STILL
+    # RAISES — reconnecting cannot tell a caller whether ITS OWN write
+    # reached the server before the connection died, so silently
+    # retrying it here could silently double it; that ambiguity is
+    # exactly why `Runtime::SagaInterpreter`'s own defect-retry exists
+    # ONE LAYER UP, where a dispatch is retried as a whole (fresh
+    # hydrate, fresh `given`s), not as a lone SQL statement.
+    module PostgresReconnect
+      def pg_exec(sql)
+        @db.exec(sql)
+      rescue PG::ConnectionBad
+        reconnect!
+        raise
+      end
+
+      def pg_exec_params(sql, binds)
+        @db.exec_params(sql, binds)
+      rescue PG::ConnectionBad
+        reconnect!
+        raise
+      end
+
+      private
+
+      # BEST-EFFORT — a reconnect attempt that itself fails (the server
+      # is actually down, not just this one backend) leaves `@db`
+      # unchanged; the `PG::ConnectionBad` already being re-raised by
+      # `pg_exec`/`pg_exec_params` above still reaches the caller either
+      # way, so swallowing a failed RECONNECT attempt here loses no
+      # information — it only avoids masking the original error with a
+      # second one.
+      def reconnect!
+        @db = self.class.connect_for(@aggregate.name, @settings)
+      rescue PG::Error
+        nil
+      end
+    end
+  end
+end

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

@@ -28,6 +28,25 @@ module Hecks
           # `persisted_fields` (Codec), so it never appears in `decode`'s
           # domain-state hash or `Instance#to_h`.
           @db.exec("ALTER TABLE #{quoted_table} ADD COLUMN IF NOT EXISTS hecks_version bigint NOT NULL DEFAULT 1")
+          # SAME SELF-HEALING SHAPE, FOR DOMAIN ATTRIBUTES THEMSELVES —
+          # `hecks_version` above only heals the adapter's own bookkeeping
+          # column; a bluebook attribute added (or, via `translations/`,
+          # renamed) after this table already exists is not bookkeeping,
+          # but the identical gap applies: `CREATE TABLE IF NOT EXISTS`
+          # is a no-op against the existing table, so without this a new
+          # attribute boots clean and then dies `PG::UndefinedColumn` on
+          # the first `project` — discovered chaos-testing a live rename
+          # against this adapter (no era, no translation prompt; those
+          # live in `PostgresEra` — this is the plain adapter's own,
+          # simpler contract: "the table always has every column the
+          # bluebook currently declares"). No `NOT NULL`, no `DEFAULT` —
+          # existing rows get SQL NULL for a column they never had a
+          # value for, exactly what a fresh row would get for an unset
+          # optional attribute (`encode_field`'s own nil handling).
+          persisted_fields.each do |field|
+            @db.exec("ALTER TABLE #{quoted_table} ADD COLUMN IF NOT EXISTS " \
+                     "#{quote_ident(field[:name])} #{field[:sql_type]}")
+          end
           # RIGHT HERE, NOT A SEPARATE STEP IN `Postgres#initialize` —
           # same idiom Sqlite::SchemaBuilder's own `create_aggregate_table!`
           # uses: index creation runs unconditionally, right after the

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

@@ -10,6 +10,7 @@ require_relative "../../query_specification/field_path"
 require_relative "../../runtime/errors"
 require_relative "../../runtime/event"
 require_relative "postgres/outbox"
+require_relative "postgres/reconnect"
 require_relative "../../runtime/instance"
 
 module Hecks
@@ -46,6 +47,7 @@ module Hecks
       include SchemaBuilder
       include Codec
       include PostgresOutbox
+      include PostgresReconnect
 
       SQL_TYPES = { "Integer" => "bigint", "Float" => "double precision" }.freeze
 
@@ -93,6 +95,7 @@ module Hecks
 
       def initialize(aggregate:, settings: {}, root: nil)
         @aggregate = aggregate
+        @settings  = settings
         @db = self.class.connect_for(aggregate.name, settings)
         # THE OPTIONAL saga-persistence capability's own scoping column
         # (§2/§4) — falls back to the aggregate's own storage name for a
@@ -118,7 +121,7 @@ module Hecks
       def table = @aggregate.storage_name
 
       def find(id)
-        result = @db.exec_params("SELECT * FROM #{quoted_table} WHERE id = $1", [id.to_s])
+        result = pg_exec_params("SELECT * FROM #{quoted_table} WHERE id = $1", [id.to_s])
         return nil if result.ntuples.zero?
 
         instance_from_row(result[0])
@@ -140,13 +143,13 @@ module Hecks
           order_sql = "ORDER BY #{order_clause(spec, nil)}"
         end
 
-        @db.exec("SELECT * FROM #{quoted_table} #{order_sql}").map { |row| instance_from_row(row) }
+        pg_exec("SELECT * FROM #{quoted_table} #{order_sql}").map { |row| instance_from_row(row) }
       end
 
-      def count = @db.exec("SELECT COUNT(*) FROM #{quoted_table}")[0]["count"].to_i
+      def count = pg_exec("SELECT COUNT(*) FROM #{quoted_table}")[0]["count"].to_i
 
       def append(entry)
-        @db.exec_params(
+        pg_exec_params(
           "INSERT INTO #{quoted_entry_table} (aggregate_id, operation, state, mirrors) VALUES ($1, $2, $3, $4)",
           # `mirrors` (unlike `state`) is a NULLABLE column — an absent
           # mirrors hash must bind a real SQL NULL, not the four-character
@@ -178,7 +181,7 @@ module Hecks
       # 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?
+        return pg_exec_params("DELETE FROM #{quoted_table} WHERE id = $1", [entry.id]) if entry.delete?
 
         instance = Runtime::Instance.new(aggregate: @aggregate, id: entry.id, state: entry.state)
         columns  = (["id"] + persisted_fields.map { |field| field[:name].to_s } + ["hecks_version"])
@@ -195,7 +198,7 @@ module Hecks
         end
         sql += " RETURNING hecks_version"
 
-        result = @db.exec_params(sql, values)
+        result = pg_exec_params(sql, values)
         return nil if result.ntuples.zero?
 
         instance.version = result[0]["hecks_version"].to_i
@@ -204,7 +207,7 @@ module Hecks
       # rubocop:enable Metrics/AbcSize
 
       def entries
-        @db.exec("SELECT aggregate_id, operation, state, mirrors FROM #{quoted_entry_table} ORDER BY sequence").map do |row|
+        pg_exec("SELECT aggregate_id, operation, state, mirrors FROM #{quoted_entry_table} ORDER BY sequence").map do |row|
           state = JSON.parse(row["state"])
           Ports::Persistence::Entry.new(
             operation: row["operation"] || "save",
@@ -216,8 +219,8 @@ module Hecks
       end
 
       def reset!
-        @db.exec("DELETE FROM #{quoted_table}")
-        @db.exec("DELETE FROM #{quoted_entry_table}")
+        pg_exec("DELETE FROM #{quoted_table}")
+        pg_exec("DELETE FROM #{quoted_entry_table}")
         self
       end
 
@@ -239,12 +242,12 @@ module Hecks
       def atomic_put(entry, insert_only: false)
         status = nil
         transaction do
-          @db.exec_params(
+          pg_exec_params(
             "SELECT pg_advisory_xact_lock(" \
             "hashtext(current_schema() || ':' || $1), hashtext($2))",
             [table, entry.id.to_s]
           )
-          exists = !@db.exec_params(
+          exists = !pg_exec_params(
             "SELECT 1 FROM #{quoted_table} WHERE id = $1",
             [entry.id.to_s]
           ).ntuples.zero?
@@ -269,14 +272,14 @@ module Hecks
       end
 
       def record_event(event)
-        @db.exec_params(
+        pg_exec_params(
           "INSERT INTO events (name, aggregate, aggregate_id, payload, occurred_at) VALUES ($1, $2, $3, $4, $5)",
           [event.name, event.aggregate, event.id.to_s, JSON.generate(event.payload), event.occurred_at]
         )
       end
 
       def events
-        @db.exec("SELECT * FROM events ORDER BY id").map do |row|
+        pg_exec("SELECT * FROM events ORDER BY id").map do |row|
           Runtime::Event.new(
             name:        row["name"],
             aggregate:   row["aggregate"],
@@ -291,7 +294,7 @@ module Hecks
       # shape as PostgresEra's own (postgres_era.rb), not lineage-
       # specific, copied verbatim.
       def save_saga(process_manager:, correlation:, state:, memory:, completed_compensations: [])
-        @db.exec_params(
+        pg_exec_params(
           "INSERT INTO hecks_saga_instances (domain, process_manager, correlation, state, memory, completed_compensations) " \
           "VALUES ($1, $2, $3, $4, $5, $6) " \
           "ON CONFLICT (domain, process_manager, correlation) DO UPDATE " \
@@ -303,7 +306,7 @@ module Hecks
       end
 
       def delete_saga(process_manager:, correlation:)
-        @db.exec_params(
+        pg_exec_params(
           "DELETE FROM hecks_saga_instances WHERE domain = $1 AND process_manager = $2 AND correlation = $3",
           [@domain, process_manager.to_s, correlation.to_s]
         )
@@ -312,7 +315,7 @@ module Hecks
       def each_saga
         return enum_for(:each_saga) unless block_given?
 
-        @db.exec_params(
+        pg_exec_params(
           "SELECT process_manager, correlation, state, memory, completed_compensations " \
           "FROM hecks_saga_instances WHERE domain = $1",
           [@domain]
@@ -381,7 +384,7 @@ module Hecks
       end
 
       def execute_query(sql, binds)
-        @db.exec_params(sql, binds).map { |row| instance_from_row(row) }
+        pg_exec_params(sql, binds).map { |row| instance_from_row(row) }
       end
 
       # Stamps `.version` (adapter bookkeeping, never domain state — see

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

@@ -67,7 +67,10 @@ module Hecks
         # reads it — not the identity unwrap, which is gone : an identity is
         # declared as a path and followed.
         reference_id = args.fetch(model.reference_name).to_s
-        eligible = model.filtered_head_name
+        # Plural (ADR 0055) — `on:` lets `where`/`order_by`/`limit`/`offset`
+        # each name a different many-side head, so more than one can be
+        # eligible in the same read model now.
+        eligible = model.filtered_head_names
 
         # ROOT FIRST, ALWAYS — see this method's own header. Mirrors
         # `ReadModelInterpreter#project`'s identical partition, for the
@@ -87,7 +90,7 @@ module Hecks
                  else
                    select_related(aggregate, projected)
                  end
-          rows = Ports::Query::InMemory.execute(rows, model, args) if head[:as] == eligible
+          rows = Ports::Query::InMemory.execute(rows, model.options_for(head[:as]), args) if eligible.include?(head[:as])
           projected << { aggregate: head[:aggregate], rows: rows }
           reports[head[:as]] = if head[:many]
                                  rows.map { |row| Runtime::Value.materialize(row.to_h) }

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

@@ -170,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
 
@@ -180,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/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/dsl/aggregate_builder.rb

@@ -88,13 +88,18 @@ module Hecks
         end
 
         # `optional:` — matching `CommandBuilder#reference_to`'s own
-        # signature, which already had it; this one never forwarded it
-        # to `attribute_impl()` even though `attribute_impl()` itself
-        # already accepts it. A real gap: an aggregate that can point at
-        # ONE OF several targets (Item's own `personal_list_id`/
+        # signature, which already had it; this one used to never
+        # forward it to `attribute_impl()`/`relationship_attribute`
+        # even though those already accept it — closed in the same
+        # commit that added this comment (`optional: optional`, below).
+        # It was a real gap because an aggregate that can point at ONE
+        # OF several targets (Item's own `personal_list_id`/
         # `camping_list_id`, never both) needs each reference optional
         # on the aggregate's own persisted schema, not just as a
-        # command's input.
+        # command's input — real corpus use:
+        # `spec/fixtures/hop_chain.bluebook`'s own `Proposal` aggregate
+        # declares `reference_to Engagement, optional: true` at the
+        # aggregate head.
         # RENAMED FROM `reference_to` — item #13's full metaprogrammed
         # dispatch (slice 4b). Bootstrap-reachable (every core/attached
         # grammar chapter uses reference_to to describe itself), so also

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

@@ -54,6 +54,72 @@ module Hecks
           @includes << [Naming.demodulise(type), as]
         end
 
+        # `on:` (ADR 0055) — OVERRIDES of `QuerySpecification::Common::DSL`'s
+        # shared `where_impl`/`order_by_impl`/`limit_impl`/`offset_impl`,
+        # scoped to `ReadModelBuilder` alone rather than added to the shared
+        # module `Query` also mixes in: a plain `query` has no
+        # `aggregate_heads` at all, so `on:` there would be a silently-
+        # ignored no-op rather than a real answer. Overriding only here
+        # means a `Query`'s own `where(..., on: X)` gets Ruby's own loud
+        # `unknown keyword: :on` instead of quietly doing nothing.
+        #
+        # `on:` names the target by TYPE (`on: Character`), resolved the
+        # same way `reference_to`/`include` already resolve their own type
+        # argument (`Naming.demodulise`) — not by the include's own `as:`
+        # alias. A read model that `include`s the SAME type twice under two
+        # different `as:` has no way to say which one `on:` means today; no
+        # real corpus read model does this, so it's a real, deliberate scope
+        # limit (see ADR 0055), not an oversight.
+        #
+        # `*positional, on:, **rest` rather than a plain `(clauses, on: nil)`
+        # — found necessary, not stylistic, by reproducing the failure
+        # directly: `where(status: "disputed")` reaches here with its
+        # `status: "disputed"` captured as `**kwargs` (GenericDispatch's own
+        # `builder.send(calls, *args, **kwargs, &block)`), and Ruby stops
+        # auto-converting a bare `**hash` call into a plain positional Hash
+        # THE MOMENT a method declares any real keyword parameter — so a
+        # `(clauses, on: nil)` signature raised "wrong number of arguments
+        # (given 0, expected 1)" on every ordinary `where(field: value)`
+        # call, never reaching `on:` at all. `**rest` sidesteps this: Ruby
+        # still auto-splits `on:` into the declared keyword and gathers
+        # every OTHER key into `rest` regardless of how the caller wrote it.
+        #
+        # `QuerySpecification::Common::WhereClause` etc — FULLY QUALIFIED,
+        # not the bare names `dsl.rb`'s own shared `where_impl` gets away
+        # with. That file is lexically nested inside `Common` itself, so
+        # `WhereClause` resolves directly; this class is nested inside
+        # `Bluebook::DSL`, which has no lexical or ancestor path to
+        # `QuerySpecification::Common` at all — a bare `WhereClause` here
+        # falls through to `const_missing` and, mid-bluebook-load, that's
+        # `ConstShim`, which resolves it against the self-hosted grammar
+        # domain's OWN unrelated `WhereClause` construct instead (a `Module`,
+        # not this `Struct`) — found directly by reproducing "undefined
+        # method `new' for module WhereClause" against a real corpus load,
+        # not guessed.
+        def where_impl(*positional, on: nil, **rest)
+          raise ArgumentError, "wrong number of arguments (given #{positional.size}, expected 1)" if positional.size > 1
+
+          @wheres ||= []
+          target = resolve_target(on)
+          clauses = (positional.first || {}).merge(rest)
+          clauses.each do |field, value|
+            op, operand = split_comparator(value)
+            @wheres << QuerySpecification::Common::WhereClause.new(field: field, op: op, value: operand, target: target)
+          end
+        end
+
+        def order_by_impl(field, direction = :asc, on: nil)
+          @order_by = QuerySpecification::Common::OrderBy.new(field: field, direction: direction, target: resolve_target(on))
+        end
+
+        def limit_impl(value, on: nil)
+          @limit = QuerySpecification::Common::LimitSpec.new(value: value, target: resolve_target(on))
+        end
+
+        def offset_impl(value, on: nil)
+          @offset = QuerySpecification::Common::OffsetSpec.new(value: value, target: resolve_target(on))
+        end
+
         # NAMES which of the eligible head's own fields to nest its rows
         # under — one level per field, the leaf being that row with the
         # named fields removed (they're already spent, as the keys that
@@ -142,27 +208,70 @@ module Hecks
 
         private
 
-        # where/order_by/limit/offset/authorize's tenant all apply to exactly
-        # one collection — the single `include`d aggregate whose head is
-        # "many" (the "one" side, the reference target itself, is a single
-        # row; ordering, paging, or tenant-scoping one row means nothing). A
-        # read model with zero many-heads has nothing for them to filter ;
-        # one with several has no way to say WHICH of several unrelated
-        # collections a caller meant — so both refuse here rather than
-        # silently applying to an arbitrary one. `authorize`'s tenant counts
-        # here too — TenantScope enforces it against this same head, so an
-        # ambiguous target is exactly as unusable as it is for the others.
+        # where/order_by/limit/offset/authorize's tenant all apply to
+        # collections — the `include`d aggregates whose heads are "many"
+        # (the "one" side, the reference target itself, is a single row;
+        # ordering, paging, or tenant-scoping one row means nothing). ADR
+        # 0055 gave `where`/`order_by`/`limit`/`offset` an `on:` to name
+        # WHICH many-side collection they mean, so this asks two questions
+        # now instead of one:
+        #
+        #   1. Does every declared `on:` actually name a many-side included
+        #      aggregate? Checked regardless of how many many-side heads
+        #      exist — a typo refuses immediately, not only once ambiguity
+        #      would otherwise bite.
+        #   2. Is there still an UNTARGETED option declared (including
+        #      `authorize`'s own `tenant:`, which has no `on:` of its own —
+        #      a real, deliberate scope limit, see ADR 0055)? An untargeted
+        #      option still needs exactly one many-side head to mean
+        #      anything unambiguous — the ORIGINAL rule, unchanged, and
+        #      still worded the same way (`spec/runtime/
+        #      read_model_interpreter_spec.rb`'s existing refusal regex
+        #      still matches).
+        #
+        # A read model with several many-side heads is legal precisely when
+        # every declared option names one; a read model with a single
+        # many-side head is unaffected either way, `on:` or not.
         def seal_query_options
-          declared = @wheres&.any? || @order_by || @limit || @offset || @authorization&.tenant
-          return unless declared
+          many = Array(@aggregate_heads).select { |head| head[:many] }
 
-          many = Array(@aggregate_heads).count { |head| head[:many] }
-          return if many == 1
+          validate_declared_targets!(many)
+          return unless untargeted_option_declared?
+          return if many.size == 1
 
           raise Malformed,
-                "#{@name} declares where/order_by/limit/offset but includes #{many} many-side " \
+                "#{@name} declares where/order_by/limit/offset but includes #{many.size} many-side " \
                 "aggregates, not exactly one — these options apply to a single collection; " \
-                "name which one by including only it, or drop the options"
+                "name which one with `on:` (e.g. `where(field: value, on: Character)`), or drop the options"
+        end
+
+        # Question 1 of `seal_query_options`'s own two, split out to keep
+        # both under the same "one job per method" shape every OTHER seal in
+        # this file already holds to (each raises its own one Malformed, for
+        # its own one reason).
+        def validate_declared_targets!(many)
+          many_by_aggregate = many.to_h { |head| [head[:aggregate], head] }
+          declared_targets = Array(@wheres).map(&:target) + [@order_by&.target, @limit&.target, @offset&.target]
+
+          declared_targets.compact.uniq.each do |target|
+            next if many_by_aggregate.key?(target)
+
+            raise Malformed,
+                  "#{@name}'s `on: #{target}` doesn't name one of its own many-side included " \
+                  "aggregates (it includes #{many.map { |head| head[:aggregate] }.join(', ')} as " \
+                  "many-side heads)"
+          end
+        end
+
+        # Question 2 of `seal_query_options`'s own two — see that method's
+        # header. `authorize`'s own `tenant:` has no `on:` at all (ADR 0055's
+        # own documented scope limit), so it always counts as untargeted.
+        def untargeted_option_declared?
+          Array(@wheres).any? { |where| where.target.nil? } ||
+            (@order_by && @order_by.target.nil?) ||
+            (@limit && @limit.target.nil?) ||
+            (@offset && @offset.target.nil?) ||
+            @authorization&.tenant
         end
 
         # Same shape as `seal_query_options`, same reason — `group_by`
@@ -227,6 +336,12 @@ module Hecks
                 "pagination — use limit/offset instead"
         end
 
+        # `on:`'s own resolution (ADR 0055) — same demodulise `reference_to`/
+        # `include` already use for their own type argument. `nil` when `on:`
+        # is omitted, matching every other optional field's "absent, not
+        # false" reading in this file.
+        def resolve_target(on) = on && Naming.demodulise(on)
+
         def add_aggregate_head(type, name, many:)
           @aggregate_heads ||= []
           target = Naming.demodulise(type)

data/lib/hecks/ports/persistence/append_only.rb

@@ -147,6 +147,17 @@ module Hecks
           yield
         end
 
+        # ONLY an adapter advertising `:cross_process_lock` (PostgresEra —
+        # see ADR 0036) implements this; `run_dispatch_order_with_isolation`
+        # (runtime/interpreting.rb) checks `capabilities` before ever
+        # calling it, so the plain `yield` fallback here only guards
+        # against a stray direct call, not the real dispatch path.
+        def with_write_lock(&)
+          return @adapter.with_write_lock(&) if @adapter.respond_to?(:with_write_lock)
+
+          yield
+        end
+
         # THE OUTBOX CONTRACT — four optional adapter methods, probed
         # together the way `save_saga`/`delete_saga`/`each_saga` are
         # (`Registry::SagaPersistence`): an adapter either has an outbox