hecks 1.1.0 → 1.2.0

data/lib/hecks/ports/persistence/plugins/era/postgres_era.rb

@@ -2,6 +2,7 @@ require "json"
 
 require_relative "../../../../adapters/driven/sql_query_builder"
 require_relative "../../../../adapters/driven/postgres/outbox"
+require_relative "../../../../adapters/driven/postgres/reconnect"
 require_relative "postgres_era/lineage"
 require_relative "postgres_era/lineage_manager"
 require_relative "../../../../ports/persistence/append_only"
@@ -42,10 +43,19 @@ module Hecks
     class PostgresEra
       include SqlQueryBuilder
       include Adapters::PostgresOutbox
+      include Adapters::PostgresReconnect
 
       attr_reader :aggregate
 
-      def persistence_capabilities = [:atomic_put]
+      # `:cross_process_lock` tells `Interpreting#run_dispatch_order_with_isolation`
+      # (runtime/interpreting.rb) this repository can hold a REAL
+      # cross-process lock for the whole dispatch order itself, via
+      # `with_write_lock` below — so it should use that instead of the
+      # in-process `AggregateLock` `Mutex` every other non-CAS repository
+      # falls back to. See ADR 0036: that in-process Mutex is invisible
+      # to `rust/host` dispatching against the same PostgresEra-bound
+      # tables from a separate OS process.
+      def persistence_capabilities = %i[atomic_put cross_process_lock]
 
       # The capability idiom: only PostgresEra answers true, and only
       # PostgresEra carries an era_check! for the boot gate to delegate to.
@@ -148,11 +158,35 @@ module Hecks
 
       def initialize(aggregate:, settings: {}, root: nil)
         @aggregate = aggregate
+        @settings  = settings
         @db = self.class.connect_for(aggregate.name, settings)
         # The domain names the journal (one journal per lineage). The
-        # factory injects it; a directly-instantiated adapter (specs,
-        # consoles) journals under the aggregate's own name.
-        @domain = self.class.setting(settings, :domain, default: aggregate.storage_name).to_s
+        # factory injects it as the owning bluebook's own declared name
+        # (`RepositoryFactory.build`'s own `domain` positional arg —
+        # `bluebook.name`, confirmed at `outbox.rb`'s own call site —
+        # never this default in real dispatch). This default exists only
+        # for a directly-instantiated adapter (specs, consoles) that
+        # skips the factory.
+        #
+        # When the aggregate DOES have an owning chapter (`hecks_owner`
+        # set — true for any aggregate sealed through a real bluebook,
+        # even if this adapter itself was built by hand), default to the
+        # chapter's own declared PascalCase name. That's the same string
+        # `rust/host`'s `pg_advisory_xact_lock` key derives from
+        # (`HECKS_DOMAIN`, deploy-time-set to `world.domain`) — the
+        # aggregate's own snake_case `storage_name` silently disagreed
+        # with it (`hashtext` is byte-sensitive: `"chess"` and `"Chess"`
+        # never collide), which is ADR 0036 Blocker 1.
+        #
+        # When there's no owning chapter at all (a bare
+        # `AggregateBuilder` fixture built outside any real bluebook —
+        # `hecks_owner` is only ever stamped by chapter construction, see
+        # `traits.rb`'s `hecks_owner = self`) there is no chapter name to
+        # match Rust against in the first place, so fall back to the
+        # aggregate's own name, same as before this ADR.
+        @domain = self.class.setting(
+          settings, :domain, default: aggregate.hecks_owner&.name || aggregate.storage_name
+        ).to_s
         @lineage = Lineage.new(@db, @domain)
         @lineage.ensure_base!
         # The era gate resolves which era this boot IS (an old checkout
@@ -274,6 +308,18 @@ module Hecks
         head_phase(declared, uncached, ids, args)
       end
 
+      # ADR 0036's actual fix — see `persistence_capabilities` above.
+      # Wraps the WHOLE dispatch order (hydrate through save), not just
+      # `append`'s own transaction below: `lock_writes!` has to be held
+      # before hydrate even starts, or two cross-process writers can
+      # both hydrate unlocked and race for the write, each blind to the
+      # other. `transaction` (via `include Adapters::PostgresOutbox`) is
+      # already re-entrant — `append`/`atomic_put`'s own inner
+      # `transaction do ... end`, deep inside the block below, joins
+      # this SAME transaction instead of opening/committing its own, so
+      # the advisory lock stays held until this whole block returns.
+      def with_write_lock(&block) = transaction { lock_writes!; block.call } # rubocop:disable Style/Semicolon
+
       # HELD FOR THE WHOLE TRANSACTION, not just around the INSERT — the
       # ordinal is assigned by the column's own `nextval()` default, inside
       # this same statement, so the lock has to already be held before that
@@ -290,7 +336,10 @@ module Hecks
       # still runs, cheaply, during AppendOnly#recover!'s full replay on
       # every boot (see `project` below), and a second write there would
       # make that replay pay real DB cost for a snapshot that's already
-      # correct.
+      # correct. When `with_write_lock` above already drove this whole
+      # dispatch, `lock_writes!` here is a harmless re-acquire of the
+      # same already-held (per-session-reentrant) advisory lock; a bare
+      # `repository.save` outside a full dispatch still takes it fresh.
       def append(entry)
         transaction do
           lock_writes!

data/lib/hecks/projections/glossary.rb

@@ -0,0 +1,374 @@
+require_relative "../projector"
+
+module Hecks
+  module Projections
+    # A CHAPTER, PROJECTED AS ITS UBIQUITOUS LANGUAGE — one glossary
+    # entry per term the business actually uses: the Domain itself, and
+    # every Aggregate, Entity, Value Object, Command (a verb), Query (a
+    # question), Read Model, Event, Role, Lifecycle, Saga, and Policy it
+    # declares — every BUSINESS-domain construct the language's own §30
+    # reference distinguishes. Deliberately not the deployment/wiring
+    # half (World, Hecksagon, Port, Adapter, Translation): Evans'
+    # Ubiquitous Language is the business model, not the plumbing that
+    # runs it.
+    #
+    # GROUPED UNDER THE AGGREGATE EACH TERM BELONGS TO — a reader thinks
+    # "what does Account mean" before they think "what starts with A",
+    # so a term's home is the aggregate that declares it (an Entity's
+    # own Commands/Queries/Lifecycle nest under ITS aggregate, not
+    # listed as their own peer); an Event or a Policy that reacts to one
+    # nests under the aggregate whose command actually raises it — the
+    # same "who does this" a reader would ask by hand. Only what
+    # genuinely belongs to no single aggregate (a Role, issued across
+    # several; a Read Model, joined across several) gets its own
+    # trailing section. Within a section, still one short sentence per
+    # term, dictionary-plain — this is not `DocsProjector` re-sorted
+    # (verbs, refusals, wire shapes, walked for a caller); it is what
+    # each term MEANS, walked for a domain expert.
+    #
+    # WHAT IT DELIBERATELY DOES NOT DO: invent, same discipline as
+    # `DocsProjector`. A term with no declared prose (most value objects;
+    # every event and role, which the language only ever spells as bare
+    # strings — a command's `emits:`/`role:`) gets a definition DERIVED
+    # from the graph around it — what it's shaped like, what emits it,
+    # who issues it — never a restated name standing in for a sentence
+    # nobody wrote.
+    #
+    #   Projector.call(:glossary, bluebook: <the Bluebook chapter>)
+    module Glossary
+      extend Projector::Target
+
+      projects_as :glossary
+
+      Entry = Struct.new(:term, :kind, :definition, :within, :section, keyword_init: true)
+
+      # DISPLAY ORDER WITHIN A SECTION — the aggregate's own row first
+      # (what it IS), then the shapes it can be in and hold, then what
+      # you can ask of it, then what happens on its own.
+      KIND_RANK = {
+        "Aggregate" => 0, "Lifecycle" => 1, "Entity" => 2, "Value Object" => 3,
+        "Command" => 4, "Query" => 5, "Event" => 6, "Policy" => 7, "Saga" => 8
+      }.freeze
+
+      ROLES_SECTION       = "Roles".freeze
+      READ_MODELS_SECTION = "Read Models".freeze
+
+      module_function
+
+      def call(bluebook:, options: {}) = render(bluebook)
+
+      # ── gathering ─────────────────────────────────────────────────────
+
+      # AN ENTITY CAN CARRY ITS OWN COMMANDS, QUERIES, AND VALUE OBJECTS
+      # TOO — walked the same one level down `DocsProjector` and
+      # `Projections::Diagrams` already walk it, so a domain's entity
+      # gaining any of these needs no change here either.
+      def holders(bluebook)
+        bluebook.aggregates.flat_map { |aggregate| [aggregate, *aggregate.entities] }
+      end
+
+      # EVERY HOLDER'S OWN AGGREGATE, ONE HOP OR ZERO — an aggregate
+      # maps to itself, an entity to whichever aggregate declared it.
+      # This is the single fact the whole grouping is built on: a
+      # Command/Query/Lifecycle's `within` already names its holder, so
+      # looking that name up here is enough to find its SECTION even
+      # when the holder is an entity two levels down from the chapter.
+      def holder_aggregate(bluebook)
+        bluebook.aggregates.each_with_object({}) do |aggregate, map|
+          map[aggregate.hecks_name] = aggregate.hecks_name
+          aggregate.entities.each { |entity| map[entity.hecks_name] = aggregate.hecks_name }
+        end
+      end
+
+      # EVERY EVENT'S OWN AGGREGATE — an event is never declared, only
+      # emitted, so its home is whichever aggregate the FIRST command
+      # that raises it belongs to. A policy or saga reacting to that
+      # event inherits the same home, the same way a reader tracing the
+      # reaction by hand would: "what raises this, and whose is that."
+      def event_aggregate(bluebook, holder_aggregate)
+        map = {}
+        holders(bluebook).each do |holder|
+          home = holder_aggregate[holder.hecks_name]
+          holder.commands.each { |command| command.emits.each { |event| map[event] ||= home } }
+        end
+        map
+      end
+
+      def entries(bluebook)
+        holder_agg = holder_aggregate(bluebook)
+        event_agg  = event_aggregate(bluebook, holder_agg)
+
+        entries = []
+        entries += domain_entries(bluebook)
+        entries += aggregate_entries(bluebook)
+        entries += entity_entries(bluebook, holder_agg)
+        entries += value_object_entries(bluebook, holder_agg)
+        entries += command_entries(bluebook, holder_agg)
+        entries += query_entries(bluebook, holder_agg)
+        entries += read_model_entries(bluebook)
+        entries += event_entries(bluebook, event_agg)
+        entries += role_entries(bluebook)
+        entries += lifecycle_entries(bluebook, holder_agg)
+        entries += saga_entries(bluebook, event_agg)
+        entries += policy_entries(bluebook, event_agg)
+        entries
+      end
+
+      # THE CHAPTER ITSELF, AS A TERM — the one construct every other
+      # entry here lives inside (`Hecks.bluebook "Banking" do ... end`),
+      # and the one place `vision` — the single sentence written for a
+      # reader who doesn't know the domain yet — actually lives. Given
+      # no `section` (rendered once, at the very top, above every
+      # aggregate) since it is the one term that belongs to no aggregate
+      # by being the thing that holds them all.
+      def domain_entries(bluebook)
+        [Entry.new(term: bluebook.name, kind: "Domain", definition: bluebook.vision)]
+      end
+
+      def aggregate_entries(bluebook)
+        bluebook.aggregates.map do |aggregate|
+          Entry.new(term: aggregate.hecks_name, kind: "Aggregate", definition: aggregate.description,
+                    section: aggregate.hecks_name)
+        end
+      end
+
+      def entity_entries(bluebook, holder_agg)
+        bluebook.aggregates.flat_map do |aggregate|
+          aggregate.entities.map do |entity|
+            Entry.new(term: entity.hecks_name, kind: "Entity", within: aggregate.hecks_name,
+                      section: holder_agg[aggregate.hecks_name], definition: entity.description)
+          end
+        end
+      end
+
+      # A VALUE OBJECT CARRIES NO `description` — the language never gave
+      # it one (`Bluebook::ValueObject` declares `attributes`,
+      # `invariants`, `members`, `closed_set`, nothing else). Its
+      # definition is derived from its own shape instead: a closed set
+      # states its members, an open one its fields — the same
+      # distinction `DocsProjector#shape_of` draws.
+      #
+      # AGGREGATES ONLY, not `holders` — unlike commands and queries, an
+      # entity declares no value objects of its own (`Bluebook::Entity`
+      # deliberately does not answer `value_objects`; its argument types
+      # live on the aggregate above it, same as `DocsProjector#value_object_for`
+      # already has to account for).
+      def value_object_entries(bluebook, holder_agg)
+        bluebook.aggregates.flat_map do |aggregate|
+          aggregate.value_objects.map do |vo|
+            Entry.new(term: vo.hecks_name, kind: "Value Object", within: aggregate.hecks_name,
+                      section: holder_agg[aggregate.hecks_name], definition: value_object_definition(vo))
+          end
+        end
+      end
+
+      # THE SHAPE, THEN THE RULES — a value object's own `invariant`
+      # bodies are real authored prose ("a currency is a three-letter
+      # code"), not derived the way the shape above is, and were
+      # sitting unread by this projector until now: `to_h`'s own
+      # `invariants` field already carries them, one `description` per
+      # `Bluebook::Invariant`.
+      def value_object_definition(value_object)
+        sentence = value_object_shape(value_object)
+        rules = value_object.invariants.map(&:description)
+        sentence += " Must satisfy: #{rules.join('; ')}." unless rules.empty?
+        sentence
+      end
+
+      # A CLOSED SET'S ROWS, not just their first field — the same
+      # correction `Projections::Vocabulary` already had to make
+      # (`StatementFrequency` names retention months and a paper fee
+      # alongside its cadence; flattening every field into one list
+      # produces well-formed nonsense, same as it did there).
+      def value_object_shape(value_object)
+        if value_object.closed_set?
+          if value_object.members.first && value_object.members.first.size > 1
+            rows = value_object.members.map { |row| "{ #{row.map { |f, v| "#{f}: #{v.inspect}" }.join(', ')} }" }
+            "One of: #{rows.join('; ')}."
+          else
+            "One of #{value_object.members.flat_map(&:values).uniq.map { |m| "`#{m}`" }.join(', ')}."
+          end
+        elsif value_object.attributes.empty?
+          "A marker with no fields of its own."
+        else
+          "{ #{value_object.attributes.map { |f| "#{f.name}: #{f.type}" }.join(', ')} }"
+        end
+      end
+
+      def command_entries(bluebook, holder_agg)
+        holders(bluebook).flat_map do |holder|
+          holder.commands.map do |command|
+            Entry.new(term: command.hecks_name, kind: "Command", within: holder.hecks_name,
+                      section: holder_agg[holder.hecks_name], definition: command.goal)
+          end
+        end
+      end
+
+      def query_entries(bluebook, holder_agg)
+        holders(bluebook).flat_map do |holder|
+          holder.queries.map do |query|
+            Entry.new(term: query.hecks_name, kind: "Query", within: holder.hecks_name,
+                      section: holder_agg[holder.hecks_name], definition: query.description)
+          end
+        end
+      end
+
+      # CROSS-AGGREGATE, ON PURPOSE — a read model joins heads from more
+      # than one aggregate (`ReadModel`'s own header: "an ask that
+      # gathers heads from more than one aggregate"), so it belongs to
+      # no single one and gets its own trailing section instead.
+      def read_model_entries(bluebook)
+        bluebook.read_models.map do |read_model|
+          Entry.new(term: read_model.name, kind: "Read Model", section: READ_MODELS_SECTION,
+                    definition: read_model.description)
+        end
+      end
+
+      # AN EVENT IS NEVER ITS OWN DECLARATION — the language only ever
+      # spells one as a bare string in a command's `emits:`. So it earns
+      # a glossary entry by appearing there, and its "definition" is the
+      # one fact the graph actually holds about it: which verb(s) raise
+      # it, and — the other half nothing raises without a reader
+      # crossing over to check `bluebook.policies` by hand — which
+      # policy (if any) reacts to it. That is derived, not invented —
+      # nobody wrote a sentence this restates.
+      def event_entries(bluebook, event_agg)
+        by_event = Hash.new { |h, k| h[k] = [] }
+        holders(bluebook).each do |holder|
+          holder.commands.each do |command|
+            command.emits.each { |event| by_event[event] << command.hecks_name }
+          end
+        end
+        by_event.map do |event, commands|
+          sentence = "Raised by #{commands.uniq.map { |c| "`#{c}`" }.join(', ')}."
+          reactions = policies_on(bluebook, event)
+          sentence += " #{reactions.join(' ')}" unless reactions.empty?
+          Entry.new(term: event, kind: "Event", section: event_agg[event], definition: sentence)
+        end
+      end
+
+      # A POLICY NAMES ITS EVENT QUALIFIED (`"Account.AccountFrozen"`) —
+      # `bare` strips the aggregate a policy's own `on_event`/
+      # `trigger_command` always carries but an event's own glossary
+      # term (keyed off `emits:`, which is never qualified) never does.
+      def bare(qualified) = qualified.to_s.split(".").last
+
+      def policies_on(bluebook, event)
+        bluebook.policies.select { |policy| bare(policy.on_event) == event }.map do |policy|
+          domain = " in #{policy.target_domain}" if policy.target_domain
+          "Triggers policy `#{policy.name}` → `#{policy.trigger_command}`#{domain}."
+        end
+      end
+
+      # A ROLE IS THE SAME SHAPE OF FACT AS AN EVENT — free text on a
+      # command's `role:`, never declared on its own — so it gets the
+      # same treatment: who it is, told by what it does. CROSS-CUTTING
+      # BY NATURE (`System`/`Customer` issue commands across half the
+      # aggregates in this corpus), so — like a Read Model — it belongs
+      # to no single aggregate.
+      def role_entries(bluebook)
+        by_role = Hash.new { |h, k| h[k] = [] }
+        holders(bluebook).each do |holder|
+          holder.commands.select(&:role).each { |command| by_role[command.role] << command.hecks_name }
+        end
+        by_role.map do |role, commands|
+          Entry.new(term: role, kind: "Role", section: ROLES_SECTION,
+                    definition: "Issues #{commands.uniq.map { |c| "`#{c}`" }.join(', ')}.")
+        end
+      end
+
+      # A LIFECYCLE HAS NO NAME OF ITS OWN — it is a body nested inside
+      # the aggregate or entity it governs (`lifecycle :status do ...
+      # end`), so it earns a glossary entry under ITS HOLDER's term,
+      # the same way `Command`/`Query` do — a reader who looks up
+      # `Account` and a reader who looks up what states an Account can
+      # hold are asking two different questions of the same name.
+      def lifecycle_entries(bluebook, holder_agg)
+        holders(bluebook).select(&:lifecycle).map do |holder|
+          lifecycle = holder.lifecycle
+          states = ([lifecycle.default] + lifecycle.transitions.map { |_name, transition| transition.target }).uniq
+          Entry.new(term: holder.hecks_name, kind: "Lifecycle", section: holder_agg[holder.hecks_name],
+                    definition: "Starts at `#{lifecycle.default}`. States: #{states.map { |s| "`#{s}`" }.join(', ')}.")
+        end
+      end
+
+      # A SAGA'S OWN HANDLERS/DISPATCHES ARE NAMELESS TOO — the same
+      # shape as a Lifecycle's transitions, one level up: a sequence of
+      # states no individual step is worth its own glossary row for.
+      # `states`, from the builder's own precomputed leg order
+      # (`Behaviour::ProcessManager#saga`, the same field
+      # `DocsProjector#closing` already reads), says what a Lifecycle
+      # entry says for an aggregate — the shape of the whole journey,
+      # not just where it starts and ends. HOMED ON ITS STARTING EVENT —
+      # a saga usually ends somewhere else entirely (that is most of
+      # what makes it a saga), so "where it begins" is the only single
+      # aggregate honestly its own.
+      def saga_entries(bluebook, event_agg)
+        bluebook.process_managers.map do |saga|
+          shape = saga.to_h
+          sentence = "Starts on `#{shape[:starts_on]}`, ends on `#{shape[:ends_on]}`."
+          states = Array(shape[:states])
+          sentence += " States: #{states.map { |s| "`#{s}`" }.join(' → ')}." unless states.empty?
+          Entry.new(term: shape[:name], kind: "Saga", section: event_agg[bare(shape[:starts_on])],
+                    definition: sentence)
+        end
+      end
+
+      # A POLICY IS A NAMED CONSTRUCT TOO (`policy "ReviewOnFreeze" do
+      # ... end`), the same as a Saga — so it earns its own glossary
+      # entry rather than surfacing only as a parenthetical on the
+      # event that triggers it. HOMED ON THE EVENT IT REACTS TO, not
+      # what it dispatches — `on_event` is always local to this
+      # bluebook, `trigger_command` sometimes is not (a cross-domain
+      # policy's own `across`). `for_each`, when declared, fans the
+      # dispatch out over more than one record; stated here because a
+      # reader who only sees "dispatches X" would otherwise assume one.
+      def policy_entries(bluebook, event_agg)
+        bluebook.policies.map do |policy|
+          sentence = "On `#{bare(policy.on_event)}`, dispatches `#{policy.trigger_command}`"
+          sentence += " in #{policy.target_domain}" if policy.target_domain
+          sentence += ", once per `#{policy.for_each}` row" if policy.for_each
+          Entry.new(term: policy.name, kind: "Policy", section: event_agg[bare(policy.on_event)],
+                    definition: "#{sentence}.")
+        end
+      end
+
+      # ── rendering ─────────────────────────────────────────────────────
+
+      def render(bluebook)
+        all = entries(bluebook)
+        grouped = all.reject { |entry| entry.kind == "Domain" }.group_by { |entry| entry.section || "Cross-Domain Reactions" }
+
+        out = [chapter_header(bluebook)]
+        bluebook.aggregates.map(&:hecks_name).sort.each { |name| out << section(name, grouped[name]) if grouped[name] }
+        [ROLES_SECTION, READ_MODELS_SECTION, "Cross-Domain Reactions"].each do |name|
+          out << section(name, grouped[name]) if grouped[name]
+        end
+
+        "#{out.compact.join("\n\n")}\n"
+      end
+
+      def chapter_header(bluebook)
+        out = ["# #{bluebook.name} — Glossary", ""]
+        out += ["> #{bluebook.vision}", ""] if bluebook.vision
+        out << "The ubiquitous language: every term #{bluebook.name} declares, grouped under the aggregate " \
+               "it belongs to, in the domain's own words. Generated from `#{bluebook.name}`'s bluebook — a " \
+               "term missing here is a term the bluebook does not yet declare, and a definition missing here " \
+               "is a sentence nobody has written yet."
+        out.join("\n")
+      end
+
+      def section(title, rows)
+        return nil unless rows
+
+        sorted = rows.sort_by { |entry| [KIND_RANK[entry.kind] || 99, entry.term.downcase] }
+        "## #{title}\n\n| Term | Kind | Definition |\n|---|---|---|\n#{sorted.map { |entry| entry_row(entry) }.join("\n")}"
+      end
+
+      def entry_row(entry)
+        term = entry.within ? "**#{entry.term}** *(#{entry.within})*" : "**#{entry.term}**"
+        "| #{term} | #{entry.kind} | #{entry.definition || '—'} |"
+      end
+    end
+  end
+end

data/lib/hecks/projections.rb

@@ -30,3 +30,4 @@ require_relative "projections/reference"
 require_relative "projections/model"
 require_relative "projections/diagrams"
 require_relative "projections/statements"
+require_relative "projections/glossary"

data/lib/hecks/projector/cli_projector.rb

@@ -156,6 +156,33 @@ module Hecks
          entity ? "#{entity.hecks_name}." : "", verb.hecks_name].join
       end
 
+      # THE ARGUMENTS A RECEIVER ADDS, BEFORE ANY VERB-SPECIFIC ONE. Shared by
+      # `command_spec` and `port_spec` — a port operation always addresses an
+      # aggregate record (`port_spec` passes `receiver: :aggregate`, never
+      # `:entity` or `nil`, because a port is declared on an aggregate, never
+      # an entity), and this is exactly the same "how do I name the record"
+      # question a command with a receiver already answers, so it is answered
+      # once, here, rather than duplicated.
+      #
+      # `nil` — a creating command — takes none: there is no existing record
+      # yet for `to=` to name.
+      def receiver_options(receiver, aggregate, entity)
+        case receiver
+        when :entity
+          [
+            { path: "to.aggregate", type: "String", required: true,
+              note: "id of the #{aggregate.hecks_name} holding the #{entity.hecks_name}" },
+            { path: "to.entity", type: "String", required: true,
+              note: "id of the #{entity.hecks_name} to act on" }
+          ]
+        when :aggregate
+          [{ path: "to", type: "String", required: true,
+             note: "id of the #{aggregate.hecks_name} to act on" }]
+        else
+          []
+        end
+      end
+
       # ── one verb ──────────────────────────────────────────────────────
 
       def command_spec(bluebook, aggregate, entity, command)
@@ -166,7 +193,6 @@ module Hecks
                     else
                       (command.creates? ? nil : :aggregate)
                     end
-        legacy_arguments = []
 
         # THE RECEIVER IS NOT A COMMAND ARGUMENT. An aggregate command names
         # its record through to; an entity command needs both the aggregate
@@ -178,18 +204,8 @@ module Hecks
         # Existing aggregate scripts may still spell the receiver id=... .
         # That alias is deliberately hidden from help and recorded separately
         # as legacy_arguments; new help and examples teach only to=... .
-        if entity
-          arguments = [
-            { path: "to.aggregate", type: "String", required: true,
-              note: "id of the #{aggregate.hecks_name} holding the #{entity.hecks_name}" },
-            { path: "to.entity", type: "String", required: true,
-              note: "id of the #{entity.hecks_name} to act on" }
-          ] + arguments
-        elsif receiver == :aggregate
-          arguments = [{ path: "to", type: "String", required: true,
-                         note: "id of the #{aggregate.hecks_name} to act on" }] + arguments
-          legacy_arguments = [{ path: "id", type: "String", required: true }]
-        end
+        arguments = receiver_options(receiver, aggregate, entity) + arguments
+        legacy_arguments = receiver == :aggregate ? [{ path: "id", type: "String", required: true }] : []
 
         { verb: fqn(bluebook, aggregate, command, entity), kind: :command,
           summary: command.goal, role: command.role, role_gated: !command.role.to_s.empty?,

data/lib/hecks/projector/exporter.rb

@@ -54,6 +54,30 @@ module Hecks
         { capable_aggregates: capable.map { |aggregate| { name: aggregate.name, storage_name: aggregate.storage_name } } }
       end
 
+      # A BINDING fact, same shape/reasoning as `lineage` above: every
+      # aggregate's DECLARED persistence adapter name (`persisted_by`),
+      # not part of the canonical bluebook shape `call` exports (ADR
+      # 0001 — the IR describes what's declared, never which adapter a
+      # deployment binds it to). Unlike `lineage`, this needs no era
+      # plugin — `BindingPolicy` is core, always loaded — and covers
+      # EVERY aggregate, not just lineage-capable ones: `rust/host`
+      # (`ir.rs`'s own `refuse_unsupported_persistence_adapters`) reads
+      # this to refuse loudly, at boot, against a domain bound to an
+      # adapter it has no backend for (Heki, Memory, Sqlite, D1,
+      # LocalStorage — `rust/host` understands only Postgres/PostgresEra
+      # today), rather than silently building up a second, disjoint
+      # history nothing but Rust ever reads while the real state stays
+      # wherever its own adapter actually wrote it.
+      def persistence(registry, domain_name)
+        bluebook = registry.bluebooks.fetch(domain_name)
+        aggregates = bluebook.aggregates.map do |aggregate|
+          adapter = Ports::Persistence::BindingPolicy.resolve(registry, domain_name, aggregate).adapter
+          { name: aggregate.name, storage_name: aggregate.storage_name, adapter: adapter }
+        end
+
+        { aggregates: aggregates }
+      end
+
       # Translation IR, always as an array, WITH each aggregate's
       # precompiled SQL attached (`compiled_translation_aggregate`) —
       # this is the export a consumer embeds (`ir.json`'s `translations`

data/lib/hecks/query_specification/common/limit_spec.rb

@@ -1,8 +1,15 @@
 module Hecks
   module QuerySpecification
     module Common
-      LimitSpec = Struct.new(:value, keyword_init: true) do
-        def to_h = { value: QuerySpecification.render_value(value) }
+      # `target` — see `WhereClause`'s own header (ADR 0055): which
+      # many-side `include`d aggregate this `limit` applies to, on a
+      # `read_model` declaring more than one. `nil` for a plain `Query`,
+      # and for a `read_model` with a single many-side head.
+      LimitSpec = Struct.new(:value, :target, keyword_init: true) do
+        def to_h
+          base = { value: QuerySpecification.render_value(value) }
+          target ? base.merge(target: target.to_s) : base
+        end
       end
     end
   end

data/lib/hecks/query_specification/common/offset_spec.rb

@@ -1,8 +1,15 @@
 module Hecks
   module QuerySpecification
     module Common
-      OffsetSpec = Struct.new(:value, keyword_init: true) do
-        def to_h = { value: QuerySpecification.render_value(value) }
+      # `target` — see `WhereClause`'s own header (ADR 0055): which
+      # many-side `include`d aggregate this `offset` applies to, on a
+      # `read_model` declaring more than one. `nil` for a plain `Query`,
+      # and for a `read_model` with a single many-side head.
+      OffsetSpec = Struct.new(:value, :target, keyword_init: true) do
+        def to_h
+          base = { value: QuerySpecification.render_value(value) }
+          target ? base.merge(target: target.to_s) : base
+        end
       end
     end
   end

data/lib/hecks/query_specification/common/order_by.rb

@@ -1,8 +1,15 @@
 module Hecks
   module QuerySpecification
     module Common
-      OrderBy = Struct.new(:field, :direction, keyword_init: true) do
-        def to_h = { field: field.to_s, direction: direction.to_s }
+      # `target` — see `WhereClause`'s own header (ADR 0055): which
+      # many-side `include`d aggregate this `order_by` applies to, on a
+      # `read_model` declaring more than one. `nil` for a plain `Query`,
+      # and for a `read_model` with a single many-side head.
+      OrderBy = Struct.new(:field, :direction, :target, keyword_init: true) do
+        def to_h
+          base = { field: field.to_s, direction: direction.to_s }
+          target ? base.merge(target: target.to_s) : base
+        end
       end
     end
   end

data/lib/hecks/query_specification/common/where_clause.rb

@@ -1,8 +1,21 @@
 module Hecks
   module QuerySpecification
     module Common
-      WhereClause = Struct.new(:field, :op, :value, keyword_init: true) do
-        def to_h = { field: field.to_s, op: op.to_s, value: QuerySpecification.render_value(value) }
+      # `target` — which many-side `include`d aggregate this clause applies
+      # to on a `read_model` with more than one (ADR 0055's own `on:`,
+      # `ReadModelBuilder#where_impl`). Always `nil` for a plain `Query`'s
+      # own `where` (that builder never overrides `where_impl` to accept
+      # `on:`), and `nil` for a `read_model` with a single many-side head,
+      # where naming one is unnecessary. `to_h` omits the key entirely
+      # rather than emitting `target: nil` — the same "absent, not null"
+      # convention `count`/`median_field` already established
+      # (`lib/hecks/bluebook/read_model.rb`), so every read model that
+      # never uses `on:` keeps its existing wire shape byte-identical.
+      WhereClause = Struct.new(:field, :op, :value, :target, keyword_init: true) do
+        def to_h
+          base = { field: field.to_s, op: op.to_s, value: QuerySpecification.render_value(value) }
+          target ? base.merge(target: target.to_s) : base
+        end
       end
     end
   end