hecks 2.8.0 → 3.0.0

data/lib/hecks/bluebook/pattern_subset.rb

@@ -1,25 +1,7 @@
 module Hecks
   module Bluebook
-    # **Which regexes a bluebook may say**.
-    #
-    # A `pattern:` is a fact about a value, carried in a bluebook — declared
-    # data, not Ruby code, so it must not lean on what any one engine happens
-    # to accept. Regex engines disagree in two different ways :
-    #
-    #   only a backtracking engine can match it — lookahead, lookbehind,
-    #   backreferences, atomic groups, possessive quantifiers. None of these
-    #   can be matched in linear time, and linear-time engines refuse them
-    #   outright. Refused here for the same reason.
-    #
-    #   every engine parses it and they mean different things — the dangerous
-    #   half, because nothing errors. `\d` `\w` `\s` are ASCII in some engines
-    #   and Unicode in others ; `[:digit:]` and friends flip the same way in
-    #   the other direction. Both families are refused, and a domain spells
-    #   the range it means.
-    #
-    # What remains — explicit ranges, alternation, quantifiers, anchors,
-    # groups — reads identically everywhere, with `^` and `$` as line anchors
-    # (Ruby's reading). The evidence is spec/corpus/fixtures/patterns.json.
+    # Which regexes a bluebook `pattern:` may say: only what every engine reads the same way.
+    # Backtracking-only and ASCII/Unicode-dependent constructs are refused.
     module PatternSubset
       Rejection = Struct.new(:construct, :reason)
 
@@ -55,36 +37,19 @@ module Hecks
 
       module_function
 
-      # nil when the pattern is admitted, a Rejection when it is not.
+      # Returns nil when the pattern is admitted, a Rejection when it is not.
       #
-      # A character walk, deliberately plain : the subset is defined by this
-      # walk, and a cleverer spelling would hide what it admits. An escaped
-      # construct is a literal, not a violation — `\(\?=` is the three
-      # characters "(?=" and says nothing about lookahead — which is why this
-      # steps over each backslash pair rather than matching the pattern as a
-      # whole.
-      # One character walk is the subset's definition (see the method
-      # comment above): each construct-check is a branch in a single
-      # ordered pass sharing `index`/`in_class`/`class_start`. Splitting
-      # the branches into separate methods would force those three cursor
-      # variables to thread as parameters/return values between them,
-      # turning "the subset is this walk" into "the subset is these
-      # methods agreeing about a shared cursor" — exactly what the walk's
-      # own comment says a cleverer spelling would obscure.
+      # One ordered character walk defines the subset; an escaped construct is a literal,
+      # which is why each backslash pair is stepped over rather than matched as a whole.
       # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       #
       # @param pattern [String, Symbol, #to_s] the declared `pattern:` regex source
-      # @return [Rejection, nil] the reason the pattern is refused, or `nil` if it is
-      #   entirely within the portable subset
+      # @return [Rejection, nil] the reason the pattern is refused, or `nil` if admitted
       def validate(pattern)
         chars = pattern.to_s.chars
         index = 0
-        # A character-class interior is a different alphabet : inside `[...]`,
-        # `*`, `+`, `?`, `(`, `?` are literal characters, not quantifiers or
-        # group syntax — `[*+]` means "a literal asterisk or plus". `]` is
-        # only the class's close when it isn't the first character after `[`
-        # or `[^` (where it is itself a literal, per POSIX bracket-expression
-        # rules).
+        # Inside `[...]` quantifier characters are literals, and `]` closes the class unless
+        # it is the first character after `[` or `[^`.
         in_class = false
         class_start = nil
 
@@ -136,8 +101,45 @@ module Hecks
         nil
       end
 
-      # Spelled out, not derived from the key : these strings are the refusal
-      # a caller reads.
+      # Rewrites the line anchors of a declared pattern into whole-string anchors.
+      #
+      # Ruby reads `^` and `$` as line anchors, so `"ok\n../evil"` satisfies `^[a-z]+$`; Rust's
+      # `regex` reads them as text anchors. Enforcement matches the rewritten source so both
+      # engines refuse the same values. Escaped characters and bracket classes are left alone.
+      #
+      # @param pattern [String, Symbol, #to_s] the declared `pattern:` regex source
+      # @return [String] the source with `^` as `\A` and `$` as `\z` outside classes
+      def whole_string(pattern)
+        chars = pattern.to_s.chars
+        in_class = false
+        class_start = nil
+        out = +""
+        index = 0
+        while index < chars.length
+          char = chars[index]
+          if char == "\\"
+            out << char << chars[index + 1].to_s
+            index += 2
+            next
+          end
+          if in_class
+            in_class = false if char == "]" && index != class_start
+          elsif char == "["
+            in_class = true
+            class_start = index + 1
+            class_start += 1 if chars[class_start] == "^"
+          elsif char == "^"
+            char = "\\A"
+          elsif char == "$"
+            char = "\\z"
+          end
+          out << char
+          index += 1
+        end
+        out
+      end
+
+      # Spelled out, not derived from the key: callers read these strings in refusals.
       CONSTRUCTS = {
         backreference:       "backreference",
         named_backreference: "named backreference",
@@ -149,17 +151,8 @@ module Hecks
         possessive:          "possessive quantifier"
       }.freeze
 
-      # Builds the rejection for one refused construct.
-      #
-      # @param key [Symbol] a key of `CONSTRUCTS`/`REASONS`, such as `:lookahead`
-      # @return [Rejection] the construct's name and the reason it is refused
       def refuse(key) = Rejection.new(CONSTRUCTS.fetch(key), REASONS.fetch(key))
 
-      # Says whether a POSIX bracket class (`[:digit:]` and friends) starts at `index`.
-      #
-      # @param chars [Array<String>] the pattern, split into characters
-      # @param index [Integer] the position to check
-      # @return [Boolean] whether a POSIX bracket class starts at `index`
       def posix_class_at?(chars, index)
         return false unless chars[index] == "[" && chars[index + 1] == ":"
 
@@ -168,14 +161,7 @@ module Hecks
         chars[cursor] == ":" && chars[cursor + 1] == "]"
       end
 
-      # A possessive quantifier is `*+`, `++`, `?+`, or a bounded `{n}`/{n,m}`
-      # immediately followed by `+` — only checked outside a character class,
-      # where `*`, `+`, `?`, `{`, `}` are quantifier syntax rather than
-      # literal characters.
-      #
-      # @param chars [Array<String>] the pattern, split into characters
-      # @param index [Integer] the position to check
-      # @return [Boolean] whether a possessive quantifier starts at `index`
+      # A possessive quantifier is `*+`, `++`, `?+` or a `{n,m}` bound followed by `+`.
       def possessive_at?(chars, index)
         return true if %w[* + ?].include?(chars[index]) && chars[index + 1] == "+"
         return false unless chars[index] == "{"
@@ -184,13 +170,7 @@ module Hecks
         !len.nil? && chars[index + len] == "+"
       end
 
-      # Length of a `{n}` / `{n,}` / `{n,m}` bound starting at `index`, or nil
-      # if what's there isn't one.
-      #
-      # @param chars [Array<String>] the pattern, split into characters
-      # @param index [Integer] the position the bound is expected to start at
-      # @return [Integer, nil] the bound's length in characters, or `nil` if `index`
-      #   does not start a `{n}`/`{n,}`/`{n,m}` bound
+      # Length of a `{n}` / `{n,}` / `{n,m}` bound at `index`, or nil if there is none.
       def bounded_quantifier_length(chars, index)
         cursor = index + 1
         digit_seen = false

data/lib/hecks/bluebook/process_manager.rb

@@ -3,19 +3,10 @@ require_relative "../ir"
 
 module Hecks
   module Bluebook
-    # `compensates` — a second `DispatchSpec`, shape-identical to this
-    # one, naming the command that undoes this dispatch specifically
-    # (see `ProcessManagerBuilder::HandlerBuilder#dispatch_impl`'s own
-    # comment). `nil` for a dispatch with nothing to undo (a pure
-    # bookkeeping mark, or one whose own effect is superseded by a later
-    # command rather than needing its own compensation). Never nested
-    # further — a compensation is not itself compensable; no known
-    # corpus need, and ADR 0025's own "a word earns its place by being
-    # used" bar would refuse a second level speculatively.
+    # `compensates` is a second `DispatchSpec` naming the command that undoes this one, or nil.
+    # Never nested; `reverses` stays reserved for `corrects`.
     DispatchSpec = Struct.new(:command_name, :with_spec, :compensates, keyword_init: true) do
-      # A Struct already answers to_h; including the mixin puts the
-      # declared emission ahead of Struct's own in the ancestry, which
-      # is what makes the shape data rather than a method body.
+      # Struct already answers to_h; the mixin puts the declared emission ahead of it.
       include Hecks::IR
 
       emits_ir(
@@ -37,62 +28,19 @@ module Hecks
       )
     end
 
-    # The compensation half of a procedure, as its own thing.
-    #
-    # A process manager coordinates: legs, states, an opinion about who goes
-    # next. A saga undoes: what makes the world good again when a leg it
-    # dispatched is refused. Two concepts, and the industry slurs them into one
-    # word — so here they are two objects, and a procedure either has a saga or
-    # does not.
-    #
-    # `undoes` is the ordered list of commands the compensation sends — a
-    # static preview, declaration order (`Behaviour::ProcessManager#saga`),
-    # not one instance's own runtime history. Per-dispatch compensation
-    # (`compensates`, on the step it compensates for) moved most of what
-    # a saga undoes off this leg's own hand-written body and onto
-    # whichever forward dispatch each one undoes — this reads every
-    # declared `compensates` across the whole saga first, then whatever
-    # this leg's own hand-written body still lists, for compensation
-    # that isn't expressible as "undo command X." which of a declared
-    # `compensates` actually fires for one instance, and in what order
-    # (newest-first, completed-legs-only), is `SagaInterpreter`'s own
-    # dynamic `completed_compensations` — a per-instance runtime fact
-    # this declaration-only object could never hold.
-    #
-    # **Naming collision, once flagged, now resolved** — `command`'s own
-    # `corrects event, reverses: true` (docs/implemented/decisions/0036-
-    # corrects-is-an-appended-fact-not-a-rewrite.md) already claimed
-    # `reverses` for a different meaning: auto-deriving a command's own
-    # corrective mutation from a past event, not a saga's own
-    # compensating leg from a past dispatch. This feature keeps
-    # `reverses` reserved for `corrects` and uses `compensates` for
-    # per-dispatch saga compensation instead — a deliberate choice, not
-    # an accidental collision.
+    # The compensation half of a procedure: the commands sent to undo a refused leg.
+    # `undoes` is a static declaration-order preview; per-instance order is the runtime's.
     Saga = Struct.new(:trigger, :from_state, :to_state, :compensations, keyword_init: true) do
-      # Lists the commands this saga sends to undo a refused leg.
-      #
-      # @return [Array<String>] the name of each compensating command, in the order
-      #   `compensations` lists them
       def undoes = compensations.map(&:command_name)
 
       def to_s = "#{trigger} → #{to_state} (#{undoes.join(', ')})"
     end
 
-    # The built form of a `process_manager "Name" do ... end` block,
-    # produced by `DSL::ProcessManagerBuilder` — its start/end events,
-    # correlation field, derived states, and handler rows. Its
-    # compensation half (`saga`, `Behaviour::ProcessManager#saga`) is
-    # derived from the handler answering `REFUSED`, below, not declared as
-    # its own construct.
+    # The built form of a `process_manager "Name" do ... end` block, made by
+    # `DSL::ProcessManagerBuilder`.
     class ProcessManager
-      # The bluebook's name for this construct, asked the same way of a class
-      # that has crossed over and of an IR object that has not. Collapses into
-      # Construct when this one crosses.
-      # The trigger of a compensating leg. Not an event name — no aggregate
-      # announces that a leg the procedure dispatched was declined — so it lives
-      # here beside the thing it triggers rather than in the runtime that
-      # notices it. Declared in the language's Trigger vocabulary, which
-      # spec/vocabulary_conformance_spec holds to this constant.
+      # The trigger of a compensating leg. Not an event name: no aggregate announces a declined
+      # leg. Held to the language's Trigger vocabulary by spec/vocabulary_conformance_spec.
       REFUSED = Hecks::Vocabulary.fetch("Trigger").first
 
       include Hecks::IR
@@ -100,21 +48,8 @@ module Hecks
 
       emits_ir(
         name:          :name,
-        # M11 — `&.`, not `.`: a DSL-built process manager always carries
-        # a real `correlates_by` (`ProcessManagerBuilder#build` refuses to
-        # mint one without it), but the IR class itself defaults it to
-        # `nil` and is what `Assembly::Build`'s `:identity` reader
-        # (`value&.to_sym`) round-trips against. A bare `.to_s` mapped
-        # that absent case to `""`, indistinguishable on the wire from a
-        # real empty name and read back as the wrong, non-nil `:""`
-        # instead of `nil` — the same nil-erasure S1 fixed for
-        # `render_value`, one field over. `correlates_by` is always a
-        # bare Symbol (`SagaInterpreter` hash-looks-up a payload by it),
-        # never a `Literal`-encoded polymorphic value, so this stays a
-        # local `&.` rather than routing through `Literal.render` — that
-        # would wrap a real value in a leading `:` and break both the
-        # `:identity` reader's plain `to_sym` and the pinned golden IR
-        # fixtures' bare-string spelling (`"reference.value"`).
+        # `&.` because the IR class defaults `correlates_by` to nil; `.to_s` reads back as `""`.
+        # A bare Symbol string, not `Literal.render`, to match the golden IR fixtures.
         correlates_by: -> { correlates_by&.to_s },
         starts_on:     :starts_on,
         ends_on:       :ends_on,
@@ -124,15 +59,10 @@ module Hecks
 
       attr_reader :name, :correlates_by, :starts_on, :ends_on, :states, :handlers
 
-      # @param name [String, Symbol] the process manager's declared name
-      # @param correlates_by [Symbol, nil] the payload field a triggering event's
-      #   instances are correlated by
+      # @param correlates_by [Symbol, nil] the payload field that correlates a triggering
+      #   event to an instance
       # @param starts_on [String, nil] the event that starts a new instance
       # @param ends_on [String, nil] the event that ends an instance
-      # @param states [Array<String>] the declared states this procedure's instances pass
-      #   through
-      # @param handlers [Array<Bluebook::ProcessManagerHandler>] the declared handler rows,
-      #   one per (event, state) leg
       def initialize(name:, correlates_by: nil, starts_on: nil, ends_on: nil,
                      states: [], handlers: [])
         @name          = name.to_s

data/lib/hecks/bluebook/project_loader.rb

@@ -3,9 +3,8 @@ require_relative "project_register"
 
 module Hecks
   module Bluebook
-    # Boots each discovered directory and feeds its declarations into the
-    # deterministic project register. Discovery and FQN registration live in
-    # their own objects so either can be used without executing domains.
+    # Boots each discovered directory and feeds its declarations into the project register.
+    # Discovery and FQN registration are separate objects so either works without booting domains.
     class ProjectLoader
       Entry          = ProjectRegister::Entry
       DuplicateFqn   = ProjectRegister::DuplicateFqn
@@ -14,31 +13,15 @@ module Hecks
 
       attr_reader :root, :discovery, :register
 
-      # Discovers and loads every domain under `root` in one call.
-      #
-      # @param root [String] the directory to search under
-      # @return [Bluebook::ProjectLoader] the loader, with every discovered domain
-      #   booted and registered
       def self.load(root) = new(root).load
 
-      # @param root [String] the directory to search under
-      # @param discovery [Bluebook::ProjectDiscovery] the discovery this loader walks
-      #   `root` with
-      # @param register [Bluebook::ProjectRegister] the register booted domains are
-      #   fed into
       def initialize(root, discovery: ProjectDiscovery.new(root), register: ProjectRegister.new)
         @root      = File.expand_path(root)
         @discovery = discovery
         @register  = register
       end
 
-      # Boots every domain `discovery` finds under `root` and registers its declarations.
-      #
-      # @return [Bluebook::ProjectLoader] self
-      # @raise [Bluebook::ProjectRegister::MissingRealm] see `ProjectRegister#register`
-      # @raise [Bluebook::ProjectRegister::LatestMismatch] see `ProjectRegister#register`
-      # @raise [Bluebook::ProjectRegister::DuplicateFqn] see `ProjectRegister#register`
-      # @raise [Runtime::WiringError] see `ProjectRegister#register`
+      # Errors raised by `ProjectRegister#register` propagate.
       def load
         discovery.bluebook_directories.each do |directory|
           runtime = Runtime.boot(directory)
@@ -47,33 +30,14 @@ module Hecks
         self
       end
 
-      # Lists every registered entry.
-      #
-      # @return [Hash{String => Bluebook::ProjectRegister::Entry}] every registered
-      #   entry, keyed by its FQN
       def entries = register.entries
 
-      # Finds a registered entry by its fully-qualified verb.
-      #
-      # @param address [String, #to_s] the FQN to look up
-      # @return [Bluebook::ProjectRegister::Entry] the entry registered under `address`
-      # @raise [KeyError] if no entry is registered under `address`
       def fetch(address) = register.fetch(address)
 
-      # Says whether an entry is registered under an address.
-      #
-      # @param address [String, #to_s] the FQN to check
-      # @return [Boolean] whether an entry is registered under `address`
       def include?(address) = register.include?(address)
 
-      # Lists every registered command entry.
-      #
-      # @return [Array<Bluebook::ProjectRegister::Entry>] every registered command entry
       def commands = register.commands
 
-      # Lists every registered query entry.
-      #
-      # @return [Array<Bluebook::ProjectRegister::Entry>] every registered query entry
       def queries  = register.queries
     end
   end

data/lib/hecks/bluebook/project_register.rb

@@ -4,14 +4,8 @@ module Hecks
     # declarations become public FQNs, but never searches or boots folders.
     class ProjectRegister
       Entry = Struct.new(:fqn, :source_directory, :dispatcher, :declared_verb, :domain_version, keyword_init: true) do
-        # Says whether this entry addresses a command.
-        #
-        # @return [Boolean] whether this entry's `fqn` addresses a command
         def command? = fqn.command?
 
-        # Says whether this entry addresses a query.
-        #
-        # @return [Boolean] whether this entry's `fqn` addresses a query
         def query?   = fqn.query?
       end
 
@@ -21,53 +15,31 @@ module Hecks
 
       attr_reader :entries
 
-      # Starts an empty register, with no domains loaded yet.
       def initialize
         @entries = {}
         @tenant_directories = Hash.new { |hash, key| hash[key] = [] }
       end
 
-      # Finds a registered entry by its fully-qualified verb.
+      # Finds an entry by FQN, such as `"Pizzas.Pizza.Order"`.
       #
-      # @param address [String, #to_s] the FQN to look up, such as `"Pizzas.Pizza.Order"`
-      # @return [Bluebook::ProjectRegister::Entry] the entry registered under `address`
       # @raise [KeyError] if no entry is registered under `address`
       def fetch(address) = entries.fetch(address.to_s)
 
-      # Says whether an entry is registered under an address.
-      #
-      # @param address [String, #to_s] the FQN to check
-      # @return [Boolean] whether an entry is registered under `address`
       def include?(address) = entries.key?(address.to_s)
 
-      # Lists every registered command entry.
-      #
-      # @return [Array<Bluebook::ProjectRegister::Entry>] every registered command entry
       def commands = entries.values.select(&:command?)
 
-      # Lists every registered query entry.
-      #
-      # @return [Array<Bluebook::ProjectRegister::Entry>] every registered query entry
-      def queries  = entries.values.select(&:query?)
+      def queries = entries.values.select(&:query?)
 
-      # Registers every aggregate command/query and read model query a booted chapter
-      # declares, under its versioned and (if current) unversioned FQNs.
+      # Registers every aggregate command/query and read model query of each chapter, under
+      # its versioned and (if current) unversioned FQNs.
       #
-      # @param bluebooks [Array<Bluebook::Chapter>] the booted chapters to register
-      # @param registry [Runtime::Registry] the registry `bluebooks` booted into
-      # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted
-      #   dispatcher entries dispatch through
-      # @param directory [String] the source directory `bluebooks` was discovered under
       # @return [Bluebook::ProjectRegister] self
-      # @raise [Bluebook::ProjectRegister::MissingRealm] if a bluebook's world declares no
-      #   realm
-      # @raise [Bluebook::ProjectRegister::LatestMismatch] if a world's `latest` disagrees
-      #   with its bluebook's own version
-      # @raise [Bluebook::ProjectRegister::DuplicateFqn] if an FQN this call would register
-      #   is already registered
-      # @raise [Runtime::WiringError] if a second tenant registers the same on-disk
-      #   directory while any of its aggregates binds to an adapter that is not
-      #   `tenant_capable?`
+      # @raise [MissingRealm] if a bluebook's world declares no realm
+      # @raise [LatestMismatch] if a world's `latest` disagrees with its bluebook's version
+      # @raise [DuplicateFqn] if an FQN this call would register is already registered
+      # @raise [Runtime::WiringError] if a second tenant registers the same directory while
+      #   an aggregate binds to an adapter that is not `tenant_capable?`
       def register(bluebooks, registry, dispatcher, directory)
         bluebooks.each do |bluebook|
           refuse_unless_safe_for_second_tenant!(bluebook, registry, directory)
@@ -87,10 +59,6 @@ module Hecks
 
       private
 
-      # Split out of `register` per-aggregate: same versioned-then-current
-      # registration shape as `register_read_model!`, just applied to a
-      # command/query pair instead of a single report. No state threads
-      # back to `register` — each `add` call is independent.
       def register_aggregate!(aggregate, bluebook, world, realm, directory, dispatcher)
         aggregate.commands.each do |command|
           if bluebook.version
@@ -116,9 +84,6 @@ module Hecks
         end
       end
 
-      # Split out of `register` per-read-model: registers the versioned FQN
-      # (if this bluebook declares a version) and the current/unversioned
-      # FQN (if this bluebook is the world's latest) for one report.
       def register_read_model!(model, bluebook, world, realm, directory, dispatcher)
         if bluebook.version
           add(Fqn.query(realm: realm, domain: bluebook.name, version: bluebook.version,
@@ -130,22 +95,9 @@ module Hecks
         end
       end
 
-      # The actual "more than one tenant" moment — Runtime::TenantCheck's
-      # own header names this table as the one place real multitenancy
-      # happens: the same on-disk directory (one domain, one
-      # `persisted_by` binding) registering a second time, under a
-      # different realm, into this same shared route table. A directory's
-      # first registration is never refused here — nothing shares its
-      # data yet, so a plain single-tenant deployment on an ordinary
-      # adapter (Postgres, no schema story) still boots exactly as
-      # before. Only the second (and any later) registration of that
-      # same directory is refused, and refused before this call adds its
-      # routes to the table — so a leaking tenant's requests never
-      # become reachable through `Router#resolve` in the first place.
-      #
-      # Keyed on `directory` + `bluebook.name` only, not realm or
-      # `dispatcher` — two tenants share the identical on-disk domain,
-      # differing only by which realm/environment overlay booted it.
+      # A directory's first registration is never refused; only a second one (another tenant
+      # sharing the on-disk domain) is, before its routes reach the table. Keyed on
+      # `directory` + name, not realm or dispatcher.
       def refuse_unless_safe_for_second_tenant!(bluebook, registry, directory)
         key = [directory, bluebook.name]
         seen_before = @tenant_directories.key?(key) && @tenant_directories[key].any?

data/lib/hecks/bluebook/query.rb

@@ -1,33 +1,15 @@
 require_relative "behaviour/query"
 
 module Hecks
-  # Reopened here only to add `render_value` below — the pinned
-  # wire-literal rendering (`Literal.render`) the `emits_ir` Procs
-  # throughout this chapter reach for. See lib/hecks/bluebook.rb's own
-  # header for what `Bluebook` is as a whole.
+  # Reopened to add `render_value`, the wire-literal rendering `emits_ir` procs use.
   module Bluebook
-    # Renders a captured Ruby value to its self-describing wire spelling.
-    #
-    # @param value [Object] any value an `emits_ir` field carries, such as a Symbol,
-    #   String, Hash, Array, or literal
-    # @return [String] the value rendered through `Hecks::Literal.render`
+    # Renders a captured value to its wire spelling through `Hecks::Literal.render`.
     def self.render_value(value) = Literal.render(value)
 
     # A query — an ask, declared on an aggregate or on one of its entities.
     #
-    # It crosses over as an instance rather than a class, and the reason is worth
-    # stating because it is the boundary of the pattern. A query inherits its
-    # whole body from `QuerySpecification::Common::Options` — `wheres`,
-    # `order_by`, `limit`, `offset`, `cursor`,
-    # `authorization`, `null_semantics`, `inspection` — and those
-    # are instance methods that the runtime and the SQLite adapter both read.
-    # Hoisting the declaration onto a metaclass would put the identity and the
-    # specification on opposite sides of the object.
-    #
-    # And nothing is lost, because `Class#name` was the only reason a construct
-    # ever needed a second word for its own name. An instance answers `name`
-    # truthfully. So a query gains an owner and an identity — which is what the
-    # graph is for — and keeps the name it always had.
+    # It crosses over as an instance, not a class: its body comes from
+    # `QuerySpecification::Common::Options`, whose instance methods the runtime reads.
     class Query < QuerySpecification::Common::Options
       include Construct
 
@@ -43,31 +25,14 @@ module Hecks
         limit:       one(:limit)
       )
 
-      attr_reader :name, :description, :attributes
+      attr_reader :name, :description, :attributes, :returns
 
-      # @param name [String, Symbol] the query's declared name
-      # @param description [String, nil] the query's declared prose description
-      # @param attributes [Array<Bluebook::Attribute>] the query's declared result fields
-      # @param wheres [Array<QuerySpecification::Common::WhereClause>] the declared filter
-      #   conditions
-      # @param order_by [QuerySpecification::Common::OrderBy, nil] the declared sort field
-      #   and direction, or `nil` for no explicit ordering
-      # @param limit [QuerySpecification::Common::LimitSpec, nil] the declared row limit,
-      #   or `nil` for none
-      # @param offset [QuerySpecification::Common::OffsetSpec, nil] the declared row offset,
-      #   or `nil` for none
-      # @param cursor [QuerySpecification::Common::CursorSpec, nil] the declared pagination
-      #   cursor, or `nil` for none
-      # @param authorization [QuerySpecification::Common::AuthorizationSpec, nil] the declared
-      #   authorization policy, or `nil` for none
-      # @param null_semantics [QuerySpecification::Common::NullSemantics, nil] how this query
-      #   orders `nil` values; defaults to `NullSemantics.default` when omitted
-      # @param inspection [QuerySpecification::Common::InspectionSpec, nil] the declared
-      #   inspection mode, or `nil` for none
+      # @param null_semantics [QuerySpecification::Common::NullSemantics, nil] defaults to
+      #   `NullSemantics.default`
       def initialize(name:, description: nil, attributes: [], wheres: [],
                      order_by: nil, limit: nil, offset: nil, cursor: nil,
                      authorization: nil, null_semantics: nil,
-                     inspection: nil)
+                     inspection: nil, returns: nil)
         null_semantics ||= QuerySpecification::Common::NullSemantics.default
         super(wheres: wheres, order_by: order_by, limit: limit, offset: offset, cursor: cursor,
               authorization: authorization,
@@ -76,17 +41,28 @@ module Hecks
         @hecks_name  = @name
         @description = description
         @attributes  = attributes
+        @returns     = returns&.to_s
       end
 
-      # A query's shape is not fixed — `extra_options_to_h` carries
-      # whatever options the specification layer grew (count, median,
-      # group_by, scope_to). Declared emission covers the settled part
-      # and `super` hands it over; the tail stays dynamic, which is the
-      # honest description of it.
+      # The value object a `returns` names, without the `list_of(...)` wrapper.
+      #
+      # @return [String, nil] the value object's name, or `nil` when the query returns nothing
+      def returns_name = @returns&.sub(/\Alist_of\((.*)\)\z/, '\1')
+
+      # Says whether the answer is many rows of the returned value object.
       #
-      # @return [Hash] the declared emission, merged with whatever `extra_options_to_h`
-      #   the specification layer currently carries
-      def to_h = super.merge(extra_options_to_h)
+      # @return [Boolean] true for `returns list_of(Name)`
+      def returns_list? = !@returns.nil? && @returns.start_with?("list_of(")
+
+      # `extra_options_to_h` (count, median, group_by, scope_to) stays dynamic; `super` covers the
+      # declared emission. `returns` follows, only when the query declares one, so a query that
+      # returns nothing keeps its wire shape.
+      #
+      # @return [Hash] the declared emission merged with `extra_options_to_h`, then `returns`
+      def to_h
+        shape = super.merge(extra_options_to_h)
+        @returns ? shape.merge(returns: @returns) : shape
+      end
     end
   end
 end