hecks 0.2.0 → 1.0.0

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

@@ -0,0 +1,306 @@
+require_relative "word_gate"
+module Hecks
+  module Bluebook
+    module DSL
+      class ProcessManagerBuilder
+        GRAMMAR_CONTEXT = "ProcessManager"
+
+        class InvalidProcessManager < StandardError; end
+
+        include WordGate
+
+        def initialize(name)
+          @name     = name
+          @handlers = []
+        end
+
+        # `starts_on Transfer::TransferRequested` — BARE CONSTANT
+        # ACCEPTED (ADR 0025, S6 — "events first-class"), resolved
+        # through `ConstShim` the same way `on_impl`/`transition_impl`
+        # resolve an event reference — but through `Naming.
+        # event_name_ref`, NOT `Naming.event_ref` (that method's own
+        # header has the full account: `SagaInterpreter` matches
+        # `pm.starts_on`/`pm.ends_on` against a BARE `event.name`, never
+        # a "." qualified one). A plain String still passes through
+        # unchanged, both for `shadow_parse` and for any corpus site a
+        # future pass hasn't migrated yet.
+        def starts_on_impl(event_ref)
+          @starts_on = Naming.event_name_ref(event_ref)
+        end
+
+        # `ends_on` — same reasoning as `starts_on_impl`, above.
+        def ends_on_impl(event_ref)
+          @ends_on = Naming.event_name_ref(event_ref)
+        end
+
+        # `correlates_by` — item #13's full metaprogrammed dispatch,
+        # slice 1 (whole-project table-unification survey): a bare,
+        # kind-driven coerce-and-assign with nothing else, executed by
+        # `GenericDispatch`.
+        #
+        # `starts_on`/`ends_on` USED TO be table-driven the same way,
+        # until ADR 0025 S6 gave each a second, `kind: "constant"`
+        # ArgumentSeed row (`starts_on Transfer::TransferRequested`) —
+        # `GenericDispatch::COERCE_BY_KIND` only knows `"text"`/
+        # `"symbol"`, and `shape_for` refuses to pick a `single_fill`
+        # shape at all once two Argument rows share a `fills:` target
+        # (`arguments.size == 1` below), so both words are hand-written
+        # again, `calls:`-routed like `transition` already is.
+
+        # ONE STATE-MACHINE VOCABULARY (S7, ADR 0025 — "events and
+        # reactions"): the SAME word `Lifecycle#transition` already
+        # carries, one level over — `transition "AccountDebited" =>
+        # "awaiting_credit", from: "requested" do ... end` replaces `on
+        # "AccountDebited", transition: { "requested" => "awaiting_
+        # credit" } do ... end`. Same bare rocket-pair argument shape
+        # (not a NAMED `transition:` kwarg wrapping a second Hash), same
+        # `from:` — including the array form Lifecycle's own commands
+        # could already take and a process manager's own events could
+        # not — and the states a procedure runs on are DERIVED from the
+        # transitions that name them, the same way `Behaviour::Lifecycle
+        # #states` already derives an aggregate's ; `state "x"` lines
+        # duplicated exactly what the transition list already said,
+        # and could drift from it (`validate!`'s own "undeclared state"
+        # check existed only because they could).
+        #
+        # `starts_on`/`ends_on` are NOT unified into this — verified
+        # against the real corpus rather than assumed: Settlement's own
+        # `ends_on "TransferSettled"` names an event NONE of its own
+        # transitions ever handle (`Transfer.Settle`'s own emission, a
+        # full step downstream of the transition that dispatches it),
+        # so "the terminal state's own event" is not a fact the
+        # transition graph carries — deriving it would either be wrong
+        # for this exact corpus member or need a second new word to
+        # cover the case, which is not less vocabulary than keeping the
+        # one that already says it correctly.
+        #
+        # EXPANDS IMMEDIATELY, unlike `Lifecycle#transition` (which
+        # defers to `Behaviour::Lifecycle#expand`, called at emission
+        # time) — `ProcessManager`'s own IR constructor takes `states:`/
+        # `handlers:` exactly as it always has, so the runtime
+        # (`Behaviour::ProcessManager`, `SagaInterpreter`, saga
+        # persistence/rehydration) needs no change at all: what changed
+        # is how the DECLARATION reaches that same shape, not the shape
+        # a real run ever sees or persists.
+        # RENAMED FROM `transition` — item #13's full metaprogrammed
+        # dispatch (slice 4c). Not bootstrap-reachable (checked
+        # directly — no core/attached chapter declares a ProcessManager
+        # of its own).
+        def transition_impl(mapping, &block)
+          mapping = mapping.dup
+          from    = mapping.delete(:from)
+
+          # ALWAYS REQUIRED, unlike `Lifecycle#transition`'s own `from:`
+          # — an aggregate's unconstrained transition is admitted from
+          # ANY current state (`Behaviour::Lifecycle#applies_from?`
+          # returns true for a nil `from`), a reading `SagaInterpreter#
+          # advance_saga`'s own admission check does not share: it tests
+          # `instance[:state] == handler.from_state` by plain equality,
+          # nothing softer. Leaving that check unchanged (this slice's
+          # own scope decision — see the class-level comment on why the
+          # runtime stays untouched) means an unconstrained PM
+          # transition would build cleanly and then match no instance
+          # ever, silently — refused here instead, at the one point that
+          # can still see the mistake.
+          if from.nil?
+            raise InvalidProcessManager,
+                  "#{@name}'s transition #{mapping.inspect} names no from: — a process manager's own " \
+                  "admission checks a saga instance's CURRENT state exactly, so a transition with no " \
+                  "from: would match no instance ever, silently"
+          end
+
+          handler = HandlerBuilder.new
+          handler.instance_eval(&block) if block
+
+          mapping.each do |event_type, target|
+            # BARE CONSTANT ACCEPTED (ADR 0025, S6 — "events first-
+            # class"), `transition Account::AccountDebited => "state"` —
+            # `Naming.event_name_ref`, NOT the DOTTED `Naming.event_ref`
+            # transform `PolicyBuilder#on_impl` uses (that method's own
+            # header has the full account, found live wiring a real
+            # migrated corpus site into `bin/model_check` for the first
+            # time: `SagaInterpreter#advance_saga` matches `handler.
+            # event_type` against a BARE `event.name`, never a "."
+            # qualified one — a policy's own cross-aggregate match
+            # works differently, splitting the qualifier apart from the
+            # name rather than comparing the whole string). Writing the
+            # qualifier is still worth it (the same provenance `trigger
+            # Account::Debit` gives a reader) — `event_name_ref` keeps
+            # only the final segment, so `Account::AccountDebited` and a
+            # bare `AccountDebited` store identically. A plain String
+            # still passes through unchanged, both for `shadow_parse`
+            # and for every corpus site this pass didn't migrate.
+            state_transition = StateTransition.new(target: target, from: from)
+            expand(Naming.event_name_ref(event_type), state_transition, handler.dispatches).each { |row| @handlers << row }
+          end
+        end
+
+        def build
+          validate!
+
+          ProcessManager.new(
+            name:          @name,
+            correlates_by: @correlates_by,
+            starts_on:     @starts_on,
+            ends_on:       @ends_on,
+            states:        derived_states,
+            handlers:      @handlers
+          )
+        end
+
+        def self.build(name, &block)
+          builder = new(name)
+          builder.instance_eval(&block) if block
+          builder.build
+        end
+
+        private
+
+        # ONE DECLARED TRANSITION IS SEVERAL ROWS when `from` names more
+        # than one source state — `Behaviour::Lifecycle#expand`'s own
+        # comment, the identical fan-out, one level over: a
+        # `ProcessManagerHandler` only ever carries a single `from_state`,
+        # so a `from: [...]` transition mints one row per source, each
+        # carrying the SAME dispatches.
+        def expand(event_type, transition, dispatches)
+          sources = transition.from.nil? ? [nil] : Array(transition.from)
+
+          sources.map do |source|
+            ProcessManagerHandler.new(
+              event_type: event_type,
+              from_state: source.to_s,
+              to_state:   transition.target,
+              dispatches: dispatches
+            )
+          end
+        end
+
+        # DERIVED, not declared (S7) — every state this procedure ever
+        # runs on is already named by some transition's own `from_state`
+        # or `to_state`; a state nothing transitions into or out of is
+        # not a state this procedure has, the same reading
+        # `Behaviour::Lifecycle#states` already gives an aggregate's own
+        # field. FIRST-SEEN ORDER, walking declaration order — `begin_
+        # saga`'s own `pm.states.first` is what a fresh instance starts
+        # in, so the order has to survive the derivation, not just the
+        # membership.
+        def derived_states
+          @handlers.flat_map { |h| [h.from_state, h.to_state] }.reject(&:empty?).uniq
+        end
+
+        def validate!
+          raise InvalidProcessManager, "#{@name} declares no correlates_by — " \
+                                       "nothing would tie its events to one instance" unless @correlates_by
+
+          # THE FIELD, NAMED — never the value object that carries it. A bare
+          # `correlates_by :end_to_end` reads whatever the payload holds under
+          # that key AS the correlation key, and what a non-scalar key even
+          # is stays open (the object itself? its serialised text?).
+          # Requiring the dotted spelling —
+          # `:"end_to_end.value"` — makes every correlates_by name a scalar
+          # by construction, the same discipline `identified_by` already
+          # holds a head to. This is a syntactic check, not a type check: it
+          # does not know or care whether the field IS a value object, only
+          # that the declaration cannot leave that question open.
+          raise InvalidProcessManager, "#{@name} correlates_by #{@correlates_by.inspect}, which names a whole " \
+                                       "field rather than one of its scalars — say which one, e.g. " \
+                                       "#{@correlates_by}.value" unless @correlates_by.to_s.include?(".")
+
+          raise InvalidProcessManager, "#{@name} declares no starts_on — " \
+                                       "nothing would ever begin it" if @starts_on.to_s.empty?
+
+          raise InvalidProcessManager, "#{@name} declares no transitions — " \
+                                       "it would start and then ignore every event" if @handlers.empty?
+        end
+
+        class HandlerBuilder
+          GRAMMAR_CONTEXT = "Handler"
+
+          attr_reader :dispatches
+
+          include WordGate
+
+          def initialize = @dispatches = []
+
+          # THE COMMAND ITSELF (ADR 0025, "events and reactions" — command
+          # references become first-class), same shape and same reasons
+          # as `PolicyBuilder#trigger`'s own header — bare constant live,
+          # quoted text only under shadow-parsing (S0a's bridge; frozen
+          # era text still writes `dispatch "Banking::Account.Debit"`).
+          #
+          # RENAMED FROM `dispatch` — item #13's full metaprogrammed
+          # dispatch (slice 4), same reasoning as trigger_impl above.
+          #
+          # AN OPTIONAL BLOCK OPENS `compensates` ON THIS DISPATCH
+          # SPECIFICALLY — per-dispatch saga compensation, replacing a
+          # hand-written list at the saga's own `on :refused` leg. Real,
+          # live bug this closes: `examples/banking/bluebook/transfers_
+          # and_payments.bluebook`'s own `Settlement` saga wrote a
+          # compensating reversal by hand that depended on an event only
+          # fired if someone dispatched it manually — "the reversal was
+          # written and never armed" (that file's own comment). The
+          # runtime now tracks which legs actually completed
+          # (`SagaInterpreter`'s own `completed_compensations`) and
+          # compensates only those, newest first, instead of trusting an
+          # author's static list to be complete and correctly ordered.
+          def dispatch_impl(command_ref, with: nil, &block)
+            if command_ref.is_a?(::String) && !MetaValidator.shadow_parsing?
+              raise InvalidProcessManager,
+                    "dispatch #{command_ref.inspect} is quoted text — give the bare command constant " \
+                    "instead, e.g. dispatch Account::Debit"
+            end
+
+            spec = DispatchSpec.new(
+              command_name: Naming.command_ref(command_ref),
+              with_spec:    (with || {}).to_a
+            )
+            spec.instance_variable_set(:@projection_declared, !with.nil?)
+
+            if block
+              builder = DispatchBuilder.new
+              builder.instance_eval(&block)
+              # `instance_variable_get`, not a public `compensates_spec`
+              # reader — a public one would be a method the grammar
+              # never declares, exactly what `spec/syntax_conformance_
+              # spec.rb`'s "answers only words the language declares"
+              # check exists to catch.
+              spec.compensates = builder.instance_variable_get(:@compensates_spec)
+            end
+
+            @dispatches << spec
+            spec
+          end
+
+          # THE NESTED SCOPE `dispatch ... do ... end` OPENS — one word
+          # only (`compensates`), the compensating half of the dispatch it
+          # sits inside. Its own `compensates_impl` builds a SECOND
+          # `DispatchSpec`, shape-identical to `HandlerBuilder#dispatch_
+          # impl`'s own — a compensation takes the exact same two
+          # arguments (a bare command constant, an optional `with:`)
+          # because it resolves through the identical scope (current
+          # event payload, opening event memory, correlation binding)
+          # any saga dispatch already does
+          # (`SagaInterpreter#dispatch_args`).
+          class DispatchBuilder
+            GRAMMAR_CONTEXT = "Dispatch"
+
+            include WordGate
+
+            def compensates_impl(command_ref, with: nil)
+              if command_ref.is_a?(::String) && !MetaValidator.shadow_parsing?
+                raise InvalidProcessManager,
+                      "compensates #{command_ref.inspect} is quoted text — give the bare command constant " \
+                      "instead, e.g. compensates Account::Credit"
+              end
+
+              @compensates_spec = DispatchSpec.new(
+                command_name: Naming.command_ref(command_ref),
+                with_spec:    (with || {}).to_a
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,113 @@
+require_relative "word_gate"
+module Hecks
+  module Bluebook
+    module DSL
+      class QueryBuilder
+        GRAMMAR_CONTEXT = "Query"
+
+        include AttributeCollector
+        include QuerySpecification::Common::DSL
+        include WordGate
+
+        def initialize(name)
+          @name   = name
+          @wheres = []
+        end
+
+        def description(value) = @description = value
+
+        # A query parameter naming another aggregate's own identity
+        # (Card.Active's own `Board`, filtering to one board's cards) —
+        # just a plain attribute typed as a reference,
+        # AttributeCollector#attribute already handling an Reference
+        # exactly like any other. No "acts on itself" case to
+        # distinguish here the way a command's own reference_to has —
+        # a query has no root of its own to act on, only parameters.
+        # RENAMED FROM `reference_to` — item #13's full metaprogrammed
+        # dispatch (slice 4b). Bootstrap-reachable, in
+        # GenericDispatch::BOOTSTRAP_CALLS_FALLBACK.
+        def reference_to_impl(type, as: nil, optional: false)
+          target = Naming.demodulise(type)
+          attribute_impl(as || default_reference_name(target), Reference.new(target), optional: optional)
+        end
+
+        def build
+          seal_cursor
+          Query.new(
+            name:           @name,
+            description:    @description,
+            attributes:     attributes,
+            wheres:         @wheres,
+            order_by:       @order_by,
+            limit:          @limit,
+            offset:         @offset,
+            cursor:         @cursor,
+            authorization:  @authorization,
+            null_semantics: @null_semantics,
+            inspection:     @inspection
+          )
+        end
+
+        def self.build(name, owner_attributes: [], &block)
+          builder = new(name)
+          builder.instance_eval(&block) if block
+          # `send`, not a public call — this isn't a bluebook DSL word (no
+          # author ever writes `derive_from_owner!` inside a query block),
+          # just internal wiring between this class method and the instance
+          # it just built. Kept private below so syntax_conformance_spec's
+          # own "every word QueryBuilder answers is declared" check doesn't
+          # mistake it for one.
+          builder.send(:derive_from_owner!, owner_attributes, block) if block
+          builder.build
+        end
+
+        private
+
+        # A block parameter names one of the OWNER's (the aggregate or entity
+        # this query is declared on) own already-declared attributes —
+        # `query "ForDecision" do |decision| where decision: :decision end`
+        # on Submission, whose own `attribute :decision, DecisionRef` already
+        # says what `decision` is. Restating `attribute :decision, DecisionRef`
+        # a second time inside the query was pure duplication; this derives
+        # the same type from the owner instead. Only fills in a name the block
+        # body did NOT already declare explicitly (checked AFTER instance_eval
+        # runs, so an existing bluebook still spelling it out both ways keeps
+        # working unchanged — this only removes the need to, never refuses
+        # the choice to). A block parameter matching nothing on the owner is
+        # left alone; MetaValidator's own unresolved-attribute check names it,
+        # the same way a typo in a hand-written `attribute` call already does.
+        def derive_from_owner!(owner_attributes, block)
+          block.parameters.each do |kind, param_name|
+            next unless %i[req opt].include?(kind)
+            next if attributes.any? { |a| a.name == param_name }
+
+            owner_attr = owner_attributes.find { |a| a.name == param_name }
+            next unless owner_attr
+
+            # `Attribute.new` DIRECTLY, not the public `attribute(...)` DSL
+            # entry — `owner_attr.type` is already SPELLED (a demodulised
+            # String, `Attribute#spell`'s own doing), not a bareword the
+            # bluebook author typed, so it must not run through
+            # `AttributeCollector#attribute`'s quoted-type refusal (ADR
+            # 0025, "Attributes") — that refusal exists for DSL source
+            # text, not for a type already resolved elsewhere and copied.
+            attributes << Attribute.new(name: param_name, type: owner_attr.type, optional: owner_attr.optional?)
+          end
+        end
+
+        # `cursor` parses, round-trips through the IR, and is read by nothing —
+        # no interpreter (Memory, Sqlite, Postgres) ever applies it. Refusing
+        # it here, rather than deleting the word, keeps the declared syntax
+        # honest (the language still knows the shape) while refusing to let a
+        # bluebook author believe cursor-based pagination actually happens.
+        def seal_cursor
+          return unless @cursor
+
+          raise Malformed,
+                "#{@name} declares cursor, but no interpreter implements cursor " \
+                "pagination — use limit/offset instead"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,233 @@
+require_relative "word_gate"
+module Hecks
+  module Bluebook
+    module DSL
+      class ReadModelBuilder
+        GRAMMAR_CONTEXT = "ReadModel"
+
+        include QuerySpecification::Common::DSL
+        include WordGate
+
+        def initialize(name)
+          @name = name
+        end
+
+        def description(value)
+          # moved to the language: ProjectionText / purpose, on Projection.Declare
+          @description = value
+        end
+
+        # RENAMED FROM `reference_to` — item #13's full metaprogrammed
+        # dispatch (slice 4b). Bootstrap-reachable, in
+        # GenericDispatch::BOOTSTRAP_CALLS_FALLBACK.
+        def reference_to_impl(type, as: nil)
+          raise Malformed, "#{@name} already has a projection reference" if @reference_target
+
+          @reference_target = Naming.demodulise(type)
+          @reference_name   = (as || Naming.snake(@reference_target)).to_sym
+        end
+
+        # Order-independent. `many:` is decided by comparing the included type
+        # against the reference target, so this used to REFUSE an include
+        # declared before the reference — a rule guarding an implementation
+        # limitation rather than a truth about read models. The includes are
+        # collected raw and resolved at build, when the reference is known, so
+        # there is no rule left to enforce.
+        # RENAMED FROM `include`/`group_by` — item #13's full
+        # metaprogrammed dispatch (slice 4c). `include` IS bootstrap-
+        # reachable (every core chapter's own `read_model` names which
+        # aggregates it includes with it — a first grep dismissed this
+        # as `Module#include` noise and was wrong; the cold-boot test
+        # after this rename caught it directly), so it's in
+        # BOOTSTRAP_CALLS_FALLBACK; `group_by` is not (no core read_model
+        # groups). The class-level `include WordGate` this file's own
+        # class body uses is `Module#include`, a different receiver,
+        # unaffected by renaming this INSTANCE method either way.
+        def include_impl(type, as: nil)
+          @includes ||= []
+          @includes << [Naming.demodulise(type), as]
+        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
+        # reached it). The same "exactly one many-side head" rule
+        # `seal_query_options` already enforces for where/order_by/etc
+        # applies here too (`seal_group_by`) — grouping is a question
+        # about ONE collection's own rows, same as those are.
+        def group_by_impl(*fields)
+          # Hash rows, `{field:}`, not bare symbols — same shape
+          # `aggregate_heads` already uses for exactly the reason it
+          # does: the language's own self-hosted grammar (`projection
+          # .bluebook`'s `GroupByField`) has to have SOMETHING to read a
+          # `field:` off of when `Judge` walks this list generically: a
+          # bare `Symbol` has no attribute of its own to read.
+          @group_by = fields.map { |field| { field: field.to_sym } }
+        end
+
+        # `count` -- a bare row count over the eligible many-side head's
+        # own rows (after `where`/`order_by`/`limit`/`offset` apply, the
+        # same rows `group_by` itself would nest) -- ANSWERS "how many
+        # match", not "which ones". A sibling REDUCTION to `group_by`,
+        # not a filter: `seal_aggregation` refuses combining it with
+        # `group_by` or with `median`, the same "exactly one many-side
+        # head" rule `seal_group_by` already enforces for the same
+        # reason -- a bare marker, so `@count` is left unset (nil, not
+        # false) rather than defaulted, matching the "ABSENT is not
+        # EMPTY" reading `Lifecycle`'s own optional fields already rely
+        # on for the Judge's setter dispatch (Behaviour::ReadModel#
+        # count?, ReadModelInterpreter#aggregation_target).
+        # `count` — item #13's full metaprogrammed dispatch, slice 1
+        # (whole-project table-unification survey): the ONLY Keyword row
+        # filling `count` — a bare marker, now stored as literal `true`
+        # by `GenericDispatch` off that same table fact.
+
+        # `median(field)` -- the median VALUE of one numeric field
+        # across the eligible many-side head's own rows. EVEN COUNT: the
+        # average of its two middle values (the standard definition,
+        # not "the lower of the two") -- see
+        # Runtime::ReadModelInterpreter#median for where that lands and
+        # is documented for a caller. `field` must name a numeric
+        # attribute (a bare numeric primitive, or a value object
+        # carrying one) -- checked once, at read time, by
+        # ReadModelInterpreter#aggregation_target, the same place
+        # `group_by`'s own field names are checked.
+        # `median` — item #13's full metaprogrammed dispatch, slice 1:
+        # same shape as `count`, above (a bare, kind-driven coerce-and-
+        # assign).
+
+        # `reference_to` is now OPTIONAL — a read model with no root is a
+        # BULK one: every `include`d head reads its own aggregate whole
+        # (no FK match against a root that doesn't exist), and dispatch
+        # takes no id argument at all. This used to be REQUIRED, on the
+        # assumption a read model was always "one root record's own
+        # cross-aggregate view" — true of every real corpus report so
+        # far, but not a truth about read models themselves: `group_by`'s
+        # own real use (nesting an aggregate's OWN whole table by its own
+        # field values) has no root to speak of. Still needs to describe
+        # SOMETHING — zero includes AND no reference is refused.
+        def build
+          raise Malformed,
+                "#{@name} needs an aggregate-head reference or at least one include" if !@reference_target && Array(@includes).empty?
+
+          Array(@includes).each do |target, as|
+            add_aggregate_head(target, as, many: target != @reference_target)
+          end
+          seal_query_options
+          seal_group_by
+          seal_aggregation
+          seal_cursor
+          ReadModel.new(name: @name, description: @description, reference_name: @reference_name,
+                        reference_target: @reference_target, aggregate_heads: @aggregate_heads || [],
+                        wheres: @wheres || [], order_by: @order_by, limit: @limit, offset: @offset,
+                        cursor: @cursor,
+                        authorization: @authorization, null_semantics: @null_semantics,
+                        inspection: @inspection, group_by: @group_by || [],
+                        count: @count, median_field: @median_field)
+        end
+
+        def self.build(name, &block)
+          builder = new(name)
+          builder.instance_eval(&block) if block
+          builder.build
+        end
+
+        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.
+        def seal_query_options
+          declared = @wheres&.any? || @order_by || @limit || @offset || @authorization&.tenant
+          return unless declared
+
+          many = Array(@aggregate_heads).count { |head| head[:many] }
+          return if many == 1
+
+          raise Malformed,
+                "#{@name} declares where/order_by/limit/offset but includes #{many} many-side " \
+                "aggregates, not exactly one — these options apply to a single collection; " \
+                "name which one by including only it, or drop the options"
+        end
+
+        # Same shape as `seal_query_options`, same reason — `group_by`
+        # answers a question about ONE collection's own rows, so zero or
+        # several many-side heads leaves it with no unambiguous target.
+        def seal_group_by
+          return unless @group_by&.any?
+
+          many = Array(@aggregate_heads).count { |head| head[:many] }
+          return if many == 1
+
+          raise Malformed,
+                "#{@name} declares group_by but includes #{many} many-side " \
+                "aggregates, not exactly one — group_by nests a single collection's " \
+                "own rows; name which one by including only it"
+        end
+
+        # `count`/`median` are the OTHER two reductions a read model may
+        # declare over its one eligible collection — same "exactly one
+        # many-side head" rule as `seal_group_by`, plus a rule
+        # `seal_group_by` doesn't need: a read model reports ONE shape,
+        # so `count` and `median` cannot both be declared, and neither
+        # may combine with `group_by` (nesting rows and reducing them to
+        # a scalar are answers to different questions ; a caller asking
+        # "how many, nested by state" is not a shape this read model
+        # produces today — a real, deliberate scope limit, not an
+        # oversight, the same discipline the rootless model's own
+        # "each head reads independently" limit already documents).
+        def seal_aggregation
+          return unless @count || @median_field
+
+          if @count && @median_field
+            raise Malformed,
+                  "#{@name} declares both count and median — a read model reports " \
+                  "one shape; choose one"
+          end
+          if @group_by&.any?
+            raise Malformed,
+                  "#{@name} declares count/median together with group_by — a read " \
+                  "model reports one shape; choose one"
+          end
+
+          many = Array(@aggregate_heads).count { |head| head[:many] }
+          return if many == 1
+
+          raise Malformed,
+                "#{@name} declares count/median but includes #{many} many-side " \
+                "aggregates, not exactly one — count/median reduce a single " \
+                "collection's own rows; name which one by including only it"
+        end
+
+        # `cursor` parses, round-trips through the IR, and is read by nothing —
+        # no interpreter (Memory, Sqlite, Postgres) ever applies it. Refusing
+        # it here, rather than deleting the word, keeps the declared syntax
+        # honest (the language still knows the shape) while refusing to let a
+        # bluebook author believe cursor-based pagination actually happens.
+        def seal_cursor
+          return unless @cursor
+
+          raise Malformed,
+                "#{@name} declares cursor, but no interpreter implements cursor " \
+                "pagination — use limit/offset instead"
+        end
+
+        def add_aggregate_head(type, name, many:)
+          @aggregate_heads ||= []
+          target = Naming.demodulise(type)
+          output = (name || (many ? Naming.plural(Naming.snake(target)) : Naming.snake(target))).to_sym
+          raise Malformed, "#{@name} already projects #{output}" if @aggregate_heads.any? { |head| head[:as] == output }
+
+          @aggregate_heads << { aggregate: target, as: output, many: many }
+        end
+      end
+    end
+  end
+end