hecks 2.8.0 → 3.0.0

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

@@ -1,94 +1,26 @@
 module Hecks
   module Bluebook
-    # The rulebook translating between the language's own declarations and the
-    # IR objects `Build`/`Reconstruction` produce from them — the `Contract`
-    # struct format itself (this file) plus, reopened in contracts.rb, the
-    # `CONTRACTS` table of one `Contract` per construct category.
+    # Translates the language's declarations into the IR that `Build` and
+    # `Reconstruction` produce; `CONTRACTS` (contracts.rb) holds one per category.
     class Assembly
-      # What a construct needs that the language cannot say, and how a claim that a
-      # field needs no assembling is checked.
-      #
-      # Naming a field derived is a claim, and a claim needs a kind, not just a name
-      # in a list. A bare list of names is a promise with nobody holding it: the
-      # coverage gate only asks whether a field is accounted for, so `derived:
-      # %i[version]` would satisfy it while dropping a chapter's version in
-      # silence — the exact shape of every defect this arc has found.
-      #
-      #   :parent            the containment tree supplies it — a `*_id`, or one of
-      #                      the named pointers below. Checked against the name.
-      #   :children          it is assembled as child constructs. Checked against the
-      #                      language: a category must exist whose parent is this one.
-      #   [:computed, :m]    the holder works it out. Checked: it must answer to `m`.
-      #   [:folded, keys]    several language fields are one thing in the IR, or one
-      #                      is spread across several. Checked: every key must appear
-      #                      in a real reconstructed declaration.
-      #   :elsewhere         not a fact about this construct at all. Allow-listed one
-      #                      by one, because it is the kind with no other check.
-      #
-      # Every one of those can fail. That is the whole difference.
+      # A derived claim's kind is one of :parent, :children, [:computed, method],
+      # [:folded, keys], or :elsewhere — each checked structurally, not just named.
       Contract = Struct.new(:holder, :make, :fields, :derived, :rows, :reads, keyword_init: true) do
-        # How a declaration key is read back off a row. Absent means the default —
-        # `text(row[key])`, a single cell — which is most of them ; present names the
-        # shape, because a list needs a reader per element and a folded field is
-        # gathered rather than fetched. Same pattern as `rows`, in the other
-        # direction: declare the exceptions, default the rest.
-        #
-        # @param key [String, Symbol] the field's declaration key, as `fields` names it
-        # @return [Symbol, Array, nil] the reader named in `reads` for `key`, or `nil`
-        #   when the field reads through the default single-cell reader
+        # nil means the field reads through the default single-cell reader.
         def reader(key) = Hash(reads)[key.to_sym]
 
-        # How an appendable list becomes rows the walk can offer. A list absent from
-        # here reads straight off the node ; one that is present names the shaper,
-        # because the IR keeps a shape the language does not — a transition whose
-        # `from` is a list is several rows, an append binds several fields at once,
-        # an open map is one row per entry.
-        #
-        # @param list [String, Symbol] the appendable list's field name
-        # @return [Symbol, nil] the shaper method named in `rows` for `list`, or `nil`
-        #   when the list reads straight off the node instead
+        # nil means the list reads straight off the node.
         def shaper(list) = Hash(rows)[list.to_sym]
 
-        # Whether `field` is one this contract accounts for, stored or derived.
-        #
-        # @param field [Symbol] the field name to check
-        # @return [Boolean] whether `field` is a key of `fields` or of `derived`
         def declares?(field) = fields.key?(field) || derived.key?(field)
 
-        # Names the kind of derived claim `field` makes, if any.
-        #
-        # @param field [Symbol] the derived field name to check
-        # @return [Symbol, Array, nil] the kind `derived` names for `field` — `:parent`,
-        #   `:children`, `:elsewhere`, `:walk`, an `[:computed, method]` or `[:folded,
-        #   object, member]` pair — or `nil` when `field` is not derived
         def kind_of(field) = derived[field]
 
-        # The fields the walk supplies — every `derived: { field => :walk }` claim.
-        # The language declares them (`attribute :position, Position`) so the
-        # judge can order siblings, but no constructor takes one. This is the one
-        # place that fact is stated ; `Specializer` and `Model::Deviations` read it
-        # here rather than each keeping their own `%i[position]`.
-        #
-        # @return [Array<Symbol>] every field name whose derived kind is `:walk`
+        # Every derived field the walk supplies; Specializer skips these.
         def walked = derived.select { |_field, kind| kind == :walk }.keys
 
-        # Where a folded field actually lives, as [object, member].
-        #
-        # `[:folded, :lifecycle, :field]` says the language's `state_field` is the
-        # `field` of the IR's one Lifecycle. `Readings` would otherwise have to state
-        # that fact a second time as `node.lifecycle&.field` — saying it once here
-        # drives both directions instead: the walk reads the member on the way in, and
-        # the reconstruction gathers the members back into the object on the way out.
-        #
-        # A nil member means the fold has no single member to name — `rows` is a
-        # count of what `closed_set` and `members` hold between them, and `options`
-        # spreads across eight keys. Those keep their own code, and the gate still
-        # checks the object they name is real.
-        #
-        # @param field [Symbol] the derived field name to check
-        # @return [Array(Symbol, Symbol), Array(Array<Symbol>, nil), nil] the `[object,
-        #   member]` pair the field folds into — `member` is `nil` when the fold has
-        #   no single member to name — or `nil` when `field` does not fold at all
+        # [object, member] a folded field lives at; member is nil when the fold
+        # has no single one to name (e.g. a count plus a list of rows).
         def folded(field)
           kind = derived[field]
           return nil unless kind.is_a?(Array) && kind.first == :folded
@@ -96,20 +28,8 @@ module Hecks
           [kind[1], kind[2]]
         end
 
-        # Computed means worked out, not merely answerable.
-        #
-        # Asking only whether the holder responds was too weak, and measurably so:
-        # `[:computed, :version]` passed, because `Bluebook` does answer to
-        # `version` — it just answers with what the constructor was handed. A field
-        # the constructor takes is stored, and calling it computed is how a chapter's
-        # version would have gone missing while the gate said yes.
-        #
-        # So a computed field is one the holder answers and the constructor does not
-        # accept. `query_name` qualifies (`Naming.snake(name)`) ; `version` cannot.
-        #
-        # @param method [Symbol] the field name to check
-        # @return [Boolean] whether `holder` answers `method` but its constructor does
-        #   not accept it as a keyword
+        # Computed means the holder answers but its constructor won't accept it —
+        # respond_to? alone would also count a stored field like `version`.
         def computes?(method)
           return false unless holder
           return false unless answers?(method)
@@ -117,22 +37,10 @@ module Hecks
           !accepts?(method)
         end
 
-        # Whether `holder` answers `method`, checked the way that fits how it is
-        # built: `respond_to?` for a `:declare` holder (a class, queried live) and
-        # `method_defined?` for a `:new` holder (an instance method, checked without
-        # building one).
-        #
-        # @param method [Symbol] the method name to check
-        # @return [Boolean] whether `holder` answers `method`
         def answers?(method)
           make == :declare ? holder.respond_to?(method) : holder.method_defined?(method)
         end
 
-        # Whether the holder's constructor takes `keyword` as a keyword argument.
-        #
-        # @param keyword [Symbol] the keyword to check
-        # @return [Boolean] whether the holder's constructor (`.declare` or
-        #   `#initialize`) accepts `keyword` as an optional or required keyword
         def accepts?(keyword)
           builder = make == :declare ? holder.method(:declare) : holder.instance_method(:initialize)
 
@@ -140,49 +48,20 @@ module Hecks
         end
       end
 
-      # The fields that point at a parent without being spelled `*_id` — the one list,
-      # read by the assembly gate (a `:parent` claim), the model generator and
-      # QueryIR (a declared field the model composes instead of storing).
-      #
-      #   aggregate, bluebook   the bare parent link a creating command mints
-      #                         (ADR 0025) — exactly the `parent_key`s `Plan` reads
-      #                         off the language
-      #   owner                 Entity's own text twin of that link, which is why
-      #                         Entity's contract claims `owner: :parent`
-      #
-      # `shape` and `handler` are not on this list — S17 (ADR 0026) made Member and
-      # Dispatch nested entities, so neither is a parent field the way
-      # `owner` is. `spec/assembly_spec` derives this set from `Plan` and the
-      # contracts directly and fails on any drift, rather than trusting this list to
-      # stay in sync with a second hand-written copy kept by the model generator.
+      # Parent-pointer fields that don't end in `_id` (ADR 0025).
+      # spec/assembly_spec derives this set independently and fails on drift.
       PARENT_POINTERS = %i[aggregate bluebook owner].freeze
 
-      # Whether `field` is a parent pointer that does not end in `_id`.
-      #
-      # @param field [String, Symbol] the field name to check
-      # @return [Boolean] whether `field` ends with `_id`, or is one of
-      #   `PARENT_POINTERS`
       def self.parent_pointer?(field)
         field.to_s.end_with?("_id") || PARENT_POINTERS.include?(field.to_sym)
       end
 
-      # The only fields allowed to claim they describe something other than the
-      # construct they hang off, each with the reason spelled out.
-      #
-      #   normalisations   the canonical-form table belongs to the expression grammar.
-      #                    A chapter's rules are canonicalised on the way in, so the
-      #                    language models the table — but no chapter stores one, and
-      #                    `Bluebook#to_h` splices it in from Expression.
+      # Fields allowed to describe something other than their own construct.
+      # `Bluebook.normalisations` belongs to the expression grammar; `to_h` splices it in.
       ELSEWHERE = {
         Bluebook: %i[normalisations]
       }.freeze
 
-      # Whether `field` is allow-listed as describing something other than
-      # `category`'s own construct — see `ELSEWHERE`.
-      #
-      # @param category [String, Symbol] the construct category name
-      # @param field [Symbol] the field name to check
-      # @return [Boolean] whether `field` is on `category`'s `ELSEWHERE` entry
       def self.elsewhere?(category, field)
         Array(ELSEWHERE[category.to_sym]).include?(field)
       end

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

@@ -1,46 +1,11 @@
 module Hecks
   module Bluebook
-    # Reopened here for `CONTRACTS`/`.contract(category)` — the one table of
-    # every construct category's own `Contract` (Bluebook, Aggregate,
-    # Command, ValueObject, Query, ...); see `Contract`'s own header
-    # (contract.rb) for the struct format each entry below fills in.
+    # Reopened for `CONTRACTS`, the table of each category's own `Contract`;
+    # see contract.rb for the struct format each entry below fills in.
     class Assembly
-      # One table, where there were five hand-written mirrors of it.
-      #
-      # `bluebook.bluebook` already declares what every construct is made of, and
-      # `Plan` already reads it — parent, fields, lists, setters. What the language
-      # cannot say is the three things Ruby needs to rebuild one, so those are here
-      # and only those:
-      #
-      #   holder    which class holds it
-      #   make      :declare for a construct that became a class, :new for an
-      #             instance — the boundary `Query` sits on, since its body is
-      #             inherited instance methods
-      #   fields    each keyword the constructor takes, as
-      #             keyword => [key in the declaration, how to read it]
-      #
-      # A reader is a symbol naming a method on Marks, or :plain for a value that
-      # needs no decoding, or [:each, reader] for a list. Nothing here is a rule
-      # about whether a declaration is admissible — the language settled that on the
-      # way in. This is only how a spelling becomes an object again.
-      #
-      # Why a table and not a method per category: a hand-written branch per
-      # category can decorate a verb the language declares without the walk ever
-      # offering it, and nothing goes red, because a branch that does not exist
-      # cannot fail. An assembler with a method per category is the same shape.
-      # The table avoids it because spec/assembly_spec checks it against the
-      # language: a field the language declares that no contract consumes is a
-      # failure, not a silence.
-      #
-      # The `derived` list is how a field says it needs no assembling — a parent
-      # pointer the containment tree already knows, or something computed from what
-      # is here (`query_name` is `Naming.snake(name)`, `creates?` is whether a verb
-      # names a root). Naming one is a claim, and the coverage gate holds it.
-      #
-      # @param category [String, Symbol] the construct category name, such as
-      #   `"Aggregate"` or `:Command`
-      # @return [Bluebook::Assembly::Contract] the category's field contract
-      # @raise [KeyError] if no contract is registered for `category`
+      # One table of what each category needs beyond what the language states:
+      # holder, make (:declare vs :new), and fields. spec/assembly_spec checks
+      # it against the language, so an unconsumed declared field fails loudly.
       def self.contract(category) = CONTRACTS.fetch(category.to_s)
 
       CONTRACTS = {
@@ -52,6 +17,7 @@ module Hecks
             vision:            [:vision,         :plain],
             classification:    [:classification, :plain],
             formerly_known_as: [:formerly_known_as, :plain],
+            namespace:         [:namespace, :plain],
             attaches_to:       [:attaches_to, :plain],
             provides:          [:provides, :plain]
           },
@@ -66,19 +32,10 @@ module Hecks
             description:      [:description,   :plain],
             identified_by:    [:identified_by, :plain],
             attributes:       [:attributes,    [:each, :attribute]],
-            # The aggregate boundary, and the precondition a command may
-            # reference by name (S10, ADR 0025 — "Rules"). Same reader
-            # shapes ValueObject's own `invariants`/Command's own
-            # `givens` already use — `invariant` builds an Invariant,
-            # `given` a Given, the same struct AggregateBuilder#given
-            # hands a referencing command's own resolved list.
+            # Aggregate's own precondition, referenced by name from a command (ADR 0025).
             invariants:       [:invariants,    [:each, :invariant]],
             preconditions:    [:preconditions, [:each, :given]],
-            # S12, ADR 0025 — the local half of "projects :name, from:
-            # :\"reference.remote_field\"", read the same way
-            # invariants/preconditions above are: a synthetic command
-            # (Aggregate.Projects) the judge dispatches once per
-            # declaration, folded into a list on the owning aggregate.
+            # The local half of `projects :name, from: "reference.remote_field"` (ADR 0025).
             projected_fields: [:projected_fields, [:each, :projected_field]],
             provenance:       [:provenance, :plain]
           },
@@ -107,10 +64,7 @@ module Hecks
             ensures:    [:ensures,    [:each, :given]],
             mutations:  [:mutations,  [:each, :mutation]],
             emits:      [:emits,      :plain],
-            # Lifecycle state as a command guard (S10, ADR 0025) — a
-            # literal the same way `provenance`/`default:` already are;
-            # one state or an array of them, or nil for a command with
-            # no such guard.
+            # Lifecycle state as a command guard: one state, an array, or nil (ADR 0025).
             from:       [:from,       :plain],
             provenance: [:provenance, :plain]
           },
@@ -144,6 +98,7 @@ module Hecks
             wheres:         [:wheres,          [:each, :where_clause]],
             order_by:       [:order_by,        :order_by],
             limit:          [:limit,           :limit],
+            returns:        [:returns,         :plain],
             # Held by the language as an open map, so every one of these reads the
             # same way and a ninth option needs no new field on either side.
             offset:         [:offset,          [:option, :offset]],
@@ -168,22 +123,15 @@ module Hecks
           fields: {
             name:          [:name,          :plain],
             description:   [:description,   :plain],
-            # A list of paths, exactly as an aggregate's is, with no room left for
-            # the two to differ. A Symbol here and a String there would look
-            # identical to `to_h`'s byte-equality check, since both render as a
-            # string, while diverging at runtime: the assembled graph would carry a
-            # String, and `element_of`'s lookup of `args["sequence"]` in a
-            # symbol-keyed payload would find nothing — refusing "Reverse acts on
-            # one LedgerEntry — pass sequence:" while sequence was in fact passed.
+            # A list of paths, like Aggregate's. Must be Symbols: a String looks
+            # identical here but a symbol-keyed args lookup downstream would find
+            # nothing, silently rejecting a value that was in fact passed.
             identified_by: [:identified_by, :plain],
             attributes:    [:attributes,    [:each, :shape_field]],
-            # ADR 0028 — the same shape Aggregate's own `preconditions`
-            # already carries, one level down: a piece's own named
-            # `given`, referenced back by one of its own commands.
+            # Same shape as Aggregate's own `preconditions`, one level down (ADR 0028).
             preconditions: [:preconditions, [:each, :given]],
-            # Round 7 — the same shape Aggregate's own `invariants`
-            # already carries, one level down: checked against every
-            # instance of this piece, not the aggregate's own flat state.
+            # Same shape as Aggregate's own `invariants`, checked per instance of
+            # this entity rather than the aggregate's flat state.
             invariants:    [:invariants,    [:each, :invariant]]
           },
           rows: { transitions: :transition_rows, identified_by: :identity_rows },
@@ -220,35 +168,23 @@ module Hecks
           holder: ProcessManager, make: :new,
           fields: {
             name:          [:name,          :plain],
-            # **A symbol**. `SagaInterpreter` does `event.payload[pm.correlates_by]` — a
-            # hash lookup on a symbol-keyed payload — and `value == pm.correlates_by`
-            # when resolving a leg s bindings. A String there finds nothing and
-            # resolves to nothing, so the wire never advanced and a drawer that
-            # should have held 2500 held 0. to_h could not show it: it stringifies.
+            # Must be a Symbol: SagaInterpreter looks it up as a symbol-keyed hash
+            # key. A String silently matches nothing, and the saga never advances.
             correlates_by: [:correlates_by, :identity],
             starts_on:     [:starts_on,     :plain],
             ends_on:       [:ends_on,       :plain],
             states:        [:states,        :plain]
           },
           reads: { states: :names },
-          # S17, ADR 0026 — `handlers` is a real feature of the language's
-          # own "ProcessManager" declaration now (`attribute :handlers,
-          # list_of(Handler)`, reaction.bluebook), consumed by the judge
-          # walking `Plan`'s own containment tree (`Handler`'s own
-          # `.parent == "ProcessManager"`) rather than by any field this
-          # contract itself reads — the same `:children` shape Aggregate's
-          # own `value_objects` claim already uses, one level in.
+          # `handlers` comes from the judge walking the containment tree
+          # (`Handler.parent == "ProcessManager"`), the same as Aggregate's
+          # own `value_objects` — not from any field this contract reads.
           derived: { position: :walk, handlers: :children }
         ),
 
-        # S17, ADR 0026 — Handler is a genuine entity now, nested under
-        # ProcessManager (`entity "Handler"`, reaction.bluebook). Neither
-        # `position` nor `handler` is a stored field: a saga
-        # answers each event once, so `event_type` is Handler's own real,
-        # non-positional identity (no walk-minted `position` to derive),
-        # and the process manager it belongs to is structural now — which
-        # list this element sits in, not a stored field to fold a parent
-        # pointer out of.
+        # Handler is nested under ProcessManager. `event_type` is its real
+        # identity (a saga answers each event once), so unlike other entities
+        # it has no walk-minted `position` to derive.
         "Handler"        => Contract.new(
           holder: ProcessManagerHandler, make: :new,
           fields: {
@@ -256,46 +192,14 @@ module Hecks
             from_state: [:from_state, :plain],
             to_state:   [:to_state,   :plain]
           },
-          # `dispatches` — same reason ProcessManager's own `handlers`
-          # claim, above, is `:children` : a real feature of the
-          # language's own "Handler" declaration (`attribute :dispatches,
-          # list_of(Dispatch)`), consumed by the judge walking `Plan`'s
-          # own containment tree rather than by any field this contract
-          # reads.
+          # `dispatches` comes from the containment walk, like ProcessManager's
+          # own `handlers` above — not from a field this contract reads.
           derived: { dispatches: :children }
         ),
 
-        # S17, ADR 0026 — Dispatch is a genuine entity now, nested under
-        # Handler (`entity "Dispatch"`, process_manager.bluebook) — two
-        # levels deep, "no life outside its Handler" (the ADR's own
-        # words). `command_name` alone is not Dispatch's own identity —
-        # items #151/#152 (`process_manager.bluebook`'s own
-        # `DispatchPosition` comment) found it collides the instant a
-        # real handler fans the same command out more than once, so
-        # `position` joins it, walk-minted the same way every other
-        # category's own `position` is (`derived: { position: :walk }`,
-        # the same entry ProcessManager's own contract carries above) —
-        # never a stored field on `DispatchSpec` itself, exactly like
-        # `handler` before it.
-        # `compensates_command_name`/`compensates_with_spec` — folded,
-        # the same kind `Lifecycle`'s own `state_field`/`default` claim
-        # (one IR object, `DispatchSpec#compensates`, feeding two
-        # separate language fields): `Readings#field_value`'s own
-        # `contract.folded` branch reads
-        # `node.compensates.to_h[:command_name]` / `[:with_spec]` for
-        # the judge's offering side, nil-safe when there is no
-        # compensation at all (`through`'s own `return nil unless
-        # held`). `compensates_with_spec` also needs its own row shaper
-        # (`compensates_with_spec_rows`, readings.rb) for the judge's
-        # list-offering side — the with_spec pairs still need one
-        # "BindCompensation" append per pair, the same reason
-        # `with_spec` itself needs `with_spec_rows`, one level deeper.
-        # `Reconstruction#dispatch` reads the two flat fields back off
-        # the row and assembles the nested `DispatchSpec` by hand — a
-        # nested object is not one of the shapes `declaration()`'s own
-        # generic per-field hash-build can produce, the identical reason
-        # `handler`/`process_manager` pass a `:children` list through
-        # `extra:` instead.
+        # Dispatch is nested under Handler, two levels deep. `command_name` alone
+        # is not identity — a handler can fan the same command out more than
+        # once, so `position` (walk-minted) disambiguates.
         "Dispatch"       => Contract.new(
           holder: DispatchSpec, make: :new,
           fields: {
@@ -304,6 +208,7 @@ module Hecks
           },
           rows: { with_spec: :with_spec_rows, compensates_with_spec: :compensates_with_spec_rows },
           reads: { with_spec: [:from, :with_spec] },
+          # compensates_* fold one IR object (`DispatchSpec#compensates`) into two fields.
           derived: {
             position:                 :walk,
             compensates_command_name: [:folded, :compensates, :command_name],
@@ -311,15 +216,9 @@ module Hecks
           }
         ),
 
-        # S14, ADR 0026 — Syntax/Keyword/Argument are never built via
-        # `Build`/`Reconstruction`'s own generic path — their own data
-        # lives in a dedicated repository `SyntaxBoot` (meta_validator/
-        # syntax_boot.rb) reads directly, never through the meta-
-        # domain's own reconstruction, the same reason `Member`'s own
-        # entry (above) carries `holder: nil, make: nil` too. These
-        # entries exist purely so the introspection specs
-        # (assembly_spec.rb) can hold them to the same "every field
-        # claimed" discipline every other category answers to.
+        # Syntax/Keyword/Argument bypass Build/Reconstruction entirely (ADR 0026) —
+        # SyntaxBoot reads them directly. These entries exist only so assembly_spec
+        # can hold them to the same "every field claimed" discipline as the rest.
         "Syntax"         => Contract.new(
           holder: nil, make: nil,
           fields: { name: [:name, :plain] },
@@ -374,14 +273,18 @@ module Hecks
             reference_target: [:reference_target, :plain],
             aggregate_heads:  [:aggregate_heads,  [:each, :head]],
             group_by:         [:group_by,         [:each, :group_by_field]],
-            # `count`/`median_field` are `group_by`'s own two siblings —
-            # scalars, not lists, so no `[:each, ...]` shape ; `:plain`
-            # is what `Assembly::Build` needs (fed the native `to_h`
-            # value directly, already `true`/`nil`/a String), and the
-            # `reads:` entry below is what `Reconstruction` needs
-            # instead (fed the stringified meta-domain row).
+            # Scalars, not lists: `:plain` is for Build (native to_h value);
+            # the `reads:` entry below is for Reconstruction (stringified row).
             count:            [:count,            :plain],
             median_field:     [:median_field,     :plain],
+            sum_field:        [:sum_field,        :plain],
+            avg_field:        [:avg_field,        :plain],
+            min_field:        [:min_field,        :plain],
+            max_field:        [:max_field,        :plain],
+            percentile_field: [:percentile_field, :plain],
+            percentile_at:    [:percentile_at,    :plain],
+            any_field:        [:any_field,        :plain],
+            all_field:        [:all_field,        :plain],
             # A read model inherits every option an ask has, so it reads them the
             # same way — see Query.
             wheres:           [:wheres,           [:each, :where_clause]],
@@ -394,31 +297,18 @@ module Hecks
             inspection:       [:inspection,       [:option, :inspection]]
           },
           rows: { options: :read_model_option_rows },
-          # `wheres` needs its own reader for the same reason Query's does — a
-          # list defaults to `[]`, not the generic `text(row[key])` cell reader's
-          # `nil` — even though a read model's row never carries `wheres` as a
-          # native field the way Query's does (`[:each, :where_clause]` over an
-          # absent `row[:wheres]` is `Array(nil).map { ... }`, i.e. `[]`, always).
-          # The real values, when a read model declares any, arrive through
-          # `options_of(row)`'s merge in `read_model` below (dispatched as
-          # generic Option rows, `read_model_option_rows`/`filter_options` — not
-          # as dedicated where-clause rows), which overrides this default. Until
-          # `ReadModel#to_h` spelled `wheres`/`order_by`/`limit`
-          # unconditionally, `round_trip_spec`'s own "source keys only" +compare
-          # never asked about this key at all, so the `nil`-vs-`[]` gap between
-          # this contract's default and `to_h`'s own `[]` default went unnoticed.
-          # `order_by`/`limit` need no matching entry — the generic reader's
-          # `nil` already agrees with `to_h`'s own nil-when-undeclared default
-          # for those two. `group_by` needs its own reader the same way — a
-          # rootless read model's grouping keys, added independently on main.
+          # `wheres` needs its own reader so an undeclared list defaults to `[]`,
+          # not the generic reader's `nil`; real values arrive via the options
+          # merge in `read_model` below, which overrides this default.
           reads: { reference_name: :symbol, aggregate_heads: [:each, :head],
                   group_by: [:each, :group_by_field], wheres: [:each, :where_clause],
-                  # `count` needs the boolean coercion `Shapes#read_model_count`
-                  # gives it (a stringified "true"/absent on the wire, a real
-                  # `true`/`nil` in `to_h`) — `median_field` needs none: the
-                  # default `text(row[key])` cell reader already returns the
-                  # same String-or-nil `ReadModel#to_h`'s own `&.to_s` does.
-                  count: :read_model_count },
+                  # `count` needs boolean coercion (stringified on the wire);
+                  # `median_field` needs none — the default reader already
+                  # matches `to_h`'s String-or-nil.
+                  count: :read_model_count,
+                  # `percentile_at` needs Float coercion; every other reduction field
+                  # is a Symbol-like name the default text reader already matches.
+                  percentile_at: :read_model_percentile_at },
           derived: {
             position:   :walk,
             query_name: [:computed, :query_name],
@@ -426,17 +316,9 @@ module Hecks
           }
         ),
 
-        # A member's pairs are an open map, which is why Member is its own root in
-        # the language. The IR keeps them as a plain hash on the value object, so
-        # they are assembled with their shape rather than as a construct.
-        # S17, ADR 0026 — Member is a genuine entity, nested under
-        # ValueObject (`entity "Member"`, shape.bluebook). It holds no
-        # `shape` field at all (a free-text, un-parsed spelling would suit
-        # only a standalone root ; an entity's element is
-        # never serialized as text) — only `position` (walk-minted, see
-        # `entity_own_identity`, judge.rb) and `pairs` (still an open map,
-        # still one row per entry, still why a value object cannot hold it
-        # directly).
+        # Member is nested under ValueObject. Its pairs are an open map, so it
+        # holds no `shape` field — only walk-minted `position` and `pairs`
+        # (still one row per entry, still an open map).
         "Member"         => Contract.new(
           holder: nil, make: nil,
           fields: {},