hecks 1.3.0 → 1.4.0

data/lib/hecks/bluebook/capabilities.rb

@@ -0,0 +1,27 @@
+module Hecks
+  module Bluebook
+    # What a chapter may declare it provides, and what each capability
+    # must name. A chapter that `provides "authorization"` is trusted in
+    # place of a check for the literal name "Governance" — by the role
+    # check at dispatch, the ungoverned-role refusal at boot, the
+    # authorization adapter and the fuzzer — so the declaration has to be
+    # complete and point at real verbs. `BluebookBuilder::Validation
+    # #validate_provisions!` holds every `provides` to this table.
+    #
+    #   key => :command | :query   the kind of verb that key must name
+    module Capabilities
+      AUTHORIZATION = "authorization".freeze
+
+      CONTRACTS = {
+        AUTHORIZATION => {
+          # every assignment an actor holds, current or historical
+          assignments: :query,
+          # the command that grants an actor a role
+          grant:       :command,
+          # every grant of one role acting as another
+          transitions: :query
+        }.freeze
+      }.freeze
+    end
+  end
+end

data/lib/hecks/bluebook/chapter.rb

@@ -1,29 +1,30 @@
 require_relative "behaviour/chapter"
+require_relative "capabilities"
 require_relative "../ir"
 
 module Hecks
   module Bluebook
-    # THE CHAPTER, and no longer the namespace it lives in.
+    # The chapter, and no longer the namespace it lives in.
     #
-    # `Hecks::Bluebook` was briefly a CLASS, because dropping the
+    # `Hecks::Bluebook` was briefly a class, because dropping the
     # old `IR::` segment would otherwise have produced
     # `Bluebook::Bluebook` — a class shadowing its own enclosing module.
     # Naming the construct what the code already called it everywhere
     # (a chapter; this file was already chapter.rb) removes the clash
     # at the source, so the namespace goes back to being a module.
     #
-    # Measured before changing: `Bluebook` was used AS a class in five
+    # Measured before changing: `Bluebook` was used as a class in five
     # places and as a namespace in seventy-seven files.
     class Chapter
       include Construct
       include Behaviour::Chapter
       include Hecks::IR
 
-      # THE SCHEMA'S OWN VERSION — not a domain's `version:` (Banking's
-      # "v1", a business fact the AUTHOR chose), but the shape `to_h`
+      # **The schema's own version** — not a domain's `version:` (Banking's
+      # "v1", a business fact the author chose), but the shape `to_h`
       # itself emits. A consumer reading exported IR with no Ruby DSL to
       # cross-check against (a build-time generator, a stored snapshot)
-      # needs to know WHICH shape it's holding before it can safely
+      # needs to know which shape it's holding before it can safely
       # interpret any of the rest of it. Bump this when `to_h`'s own
       # shape changes in a way a consumer would need to know about —
       # not when a domain's own declarations change.
@@ -40,7 +41,7 @@ module Hecks
         # `bluebook.formerly_known_as` off the live Ruby object) and the
         # meta-validator's cache key is `SHA256(JSON(bluebook.to_h))` — so
         # a fact this method didn't spell was a fact two chapters
-        # differing ONLY by their old name could hash identically on,
+        # differing only by their old name could hash identically on,
         # same as read-model filters before them. Spelled here for the
         # same reason `version`/`vision` are: a plain field, present
         # (possibly nil) rather than silently absent.
@@ -50,15 +51,32 @@ module Hecks
         policies:          many(:policies),
         process_managers:  many(:process_managers),
         attaches_to:       :attaches_to,
+        # A capability this chapter answers (`provides "authorization",
+        # grant: "RoleAssignment.Assign", ...`), one row per key, in the
+        # order written. Present (possibly empty) on every chapter, the
+        # same reading `attaches_to` beside it gives.
+        provides:          -> { provides.map(&:to_h) },
         canonical_form:    -> { Expression::CanonicalForm.table }
       )
 
+      # **One row of a declared capability** — `verb` is chapter-local
+      # ("RoleAssignment.Assign"); `Behaviour::Chapter#provided_verb`
+      # qualifies it with the chapter's own name.
+      Provision = Struct.new(:capability, :key, :verb, keyword_init: true) do
+        def self.from(row)
+          return row if row.is_a?(self)
+
+          fields = row.to_h.transform_keys(&:to_sym)
+          new(capability: fields[:capability].to_s, key: fields[:key].to_s, verb: fields[:verb].to_s)
+        end
+      end
+
       attr_reader :name, :version, :vision, :aggregates, :policies, :process_managers,
-                  :classification, :read_models, :ports, :formerly_known_as, :attaches_to
+                  :classification, :read_models, :ports, :formerly_known_as, :attaches_to, :provides
 
       def initialize(name:, version: nil, vision: nil, aggregates: [], policies: [],
                      process_managers: [], classification: nil, read_models: [], formerly_known_as: nil,
-                     attaches_to: [])
+                     attaches_to: [], provides: [])
         @policies         = policies
         @process_managers = process_managers
         @name       = name.to_s
@@ -71,6 +89,7 @@ module Hecks
         @classification = classification&.to_s
         @formerly_known_as = formerly_known_as&.to_s
         @attaches_to = Array(attaches_to).map(&:to_s)
+        @provides    = Array(provides).map { |row| Provision.from(row) }
         settle
       end
     end

data/lib/hecks/bluebook/command.rb

@@ -12,12 +12,12 @@ module Hecks
 
       # `sign:` — item #5 of the whole-project table-unification survey.
       # `increment`/`decrement`'s own +1/-1 used to be re-derived from the
-      # op NAME by two independent Rust codegen scripts (rust/project/
+      # op name by two independent Rust codegen scripts (rust/project/
       # mutations.rb, rust/codegen/src/mutations.rs — a ternary on
       # `op == "increment"` in each), even though the fact was already
       # table-driven on the Ruby runtime side
-      # (Runtime::CommandRules::Arithmetic::MUTATION_OPS, held equal to
-      # Vocabulary::MutationOp by spec/vocabulary_conformance_spec.rb).
+      # (Runtime::CommandRules::Arithmetic::MUTATION_OPS, itself read off
+      # the same generated Vocabulary::MutationOp table).
       # Reads `Vocabulary::MutationOp` directly (plain data, no framework
       # dependency — safe during parsing, same reason `RuleReference`'s
       # own bootstrap concerns don't apply here) rather than requiring
@@ -31,8 +31,8 @@ module Hecks
 
       emits_ir(target: :target, op: :op, sign: -> { Mutation.sign_for(op) })
 
-      # THE ONE GENUINELY BRANCHING EMISSION in the model: an append (or a
-      # DELEGATE — `CommandBuilder#delegates_to`'s own comment gives the
+      # The one genuinely branching emission in the model: an append (or a
+      # delegate — `CommandBuilder#delegates_to`'s own comment gives the
       # full reasoning for reusing this exact wire shape rather than
       # inventing a parallel one) binds several fields at once and carries
       # `fields:`, everything else carries a single `source:`. Declared
@@ -46,9 +46,9 @@ module Hecks
       end
     end
 
-    # A command, as a RUBY CLASS.
+    # A command, as a Ruby class.
     #
-    # NOT nested as a constant, and that is a finding rather than a shortcut. A
+    # Not nested as a constant, and that is a finding rather than a shortcut. A
     # command and a value object may legitimately share a name inside one
     # aggregate — the language does it six times, and means it: the command
     # `Argument` is the verb that appends to the `arguments` list whose element
@@ -56,10 +56,10 @@ module Hecks
     # So `Bluebook::Command::Argument` cannot be both, and a single constant
     # namespace cannot index a kind-ambiguous name. The same follows for
     # `hecks_fqn` : `Bluebook::Command.Argument` names both, which is why the judge's
-    # ids only work per-category, each in its own repository. IDENTITY IS
-    # (KIND, FQN), not fqn.
+    # ids only work per-category, each in its own repository. Identity is
+    # (kind, FQN), not fqn.
     #
-    # It is a declaration holder anyway, because that is where the EDGES live.
+    # It is a declaration holder anyway, because that is where the edges live.
     # `acts_on` answers with the owning construct itself — the Aggregate,
     # or the entity holder for a piece's verb — rather than the name of one.
     # The invocation door (`pizza.add_topping`) is the facade's business, a
@@ -79,8 +79,8 @@ module Hecks
         ensures:    -> { ensures.map { |rule| Expression::AstJson.rule_row(rule) } },
         mutations:  many(:mutations),
         emits:      :emits,
-        # THE LIFECYCLE STATE THIS COMMAND IS ADMISSIBLE FROM (S10, ADR
-        # 0025 — "lifecycle state becomes a command guard") — a GUARD,
+        # The lifecycle state this command is admissible from (S10, ADR
+        # 0025 — "lifecycle state becomes a command guard") — a guard,
         # not a transition: `command "Debit", from: "open"` replaces
         # `given("account is open") { status == "open" }`, checked
         # against the owning construct's own lifecycle field the same

data/lib/hecks/bluebook/domain_port.rb

@@ -2,8 +2,8 @@ require_relative "behaviour/domain_port"
 
 module Hecks
   module Bluebook
-    # THE PRIMARY/DRIVING HALF OF HEXAGONAL ARCHITECTURE (Cockburn) — called
-    # BY an adapter living outside the bluebook entirely, never by the
+    # The primary/driving half of hexagonal architecture (Cockburn) — called
+    # by an adapter living outside the bluebook entirely, never by the
     # domain calling out. That is already `Hecks.port` (persistence,
     # projection, extraction, loading) plus `Ports::*` : the secondary/
     # driven half, unchanged by this.
@@ -21,7 +21,7 @@ module Hecks
 
       attr_reader :hecks_name, :attributes, :emits, :direction, :answers, :refuses, :to
 
-      # TWO DIRECTIONS THROUGH ONE DOOR.
+      # Two directions through one door.
       #
       # `:inbound` is what this class has always been — `tells`, spelled
       # `operation` before it had a twin: an external fact arriving, turned
@@ -29,7 +29,7 @@ module Hecks
       # channel back to whoever called.
       #
       # `:outbound` is `asks` — the domain wanting something from outside
-      # and having to live with either answer. It names BOTH: `answers` for
+      # and having to live with either answer. It names both: `answers` for
       # what the adapter came back with, `refuses` for what it said instead.
       # Naming only the happy one would put the failure somewhere the model
       # cannot see, which is the whole reason a boundary is worth modelling.
@@ -48,15 +48,15 @@ module Hecks
       def inbound?  = @direction == :inbound
 
       # No root reference of its own — unlike a command, every attribute
-      # EQUALLY describes the payload, including whichever one identifies
+      # equally describes the payload, including whichever one identifies
       # the record its emitted event belongs to. Kept only so
       # CommandInterpreter::ArgumentGate's `reference_key` can ask for it
       # without learning this isn't a command.
 
-      # `direction`/`answers`/`refuses` are deliberately OUTSIDE `emits_ir`'s
+      # `direction`/`answers`/`refuses` are deliberately outside `emits_ir`'s
       # declared shape and added here only for an outbound operation — an
       # ordinary inbound one (`tells`, still spelled `operation` everywhere
-      # in the existing corpus) keeps the EXACT prior IR shape, byte for
+      # in the existing corpus) keeps the exact prior IR shape, byte for
       # byte. Pizzas' `PaymentGateway` port is inbound-only and is checked
       # against `hecks-parse`'s own Rust output for byte-identity
       # (parser_parity_spec.rb) — the Rust side has no notion of `asks` yet,
@@ -64,12 +64,12 @@ module Hecks
       # domain that never asked for the feature. Only a chapter that
       # actually declares `asks` (this extraction's own QualityControl
       # ledger, not yet in any Rust-parity corpus) pays for it.
-      # `to` — SAME "deliberately outside emits_ir, merged in only when
+      # `to` — same "deliberately outside emits_ir, merged in only when
       # present" treatment as direction/answers/refuses just above, and
       # for the identical reason: an operation still spelled the old way
       # (`reference_to` inside the block, shadow-parsing only — see
       # reference_to_impl's own comment) or one that simply hasn't
-      # migrated yet keeps the EXACT prior IR shape, byte for byte,
+      # migrated yet keeps the exact prior IR shape, byte for byte,
       # instead of an unconditional new key breaking parser_parity_spec
       # for every domain that never touched this.
       def to_h

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

@@ -10,22 +10,46 @@ module Hecks
 
         include WordGate
 
+        # @param name [String] the adapter's name, as written after `Hecks.adapter`
         def initialize(name)
           @name    = name
           @fields  = []
           @secrets = []
         end
 
+        # Names the port this adapter implements; a repeated call replaces the earlier name.
+        #
+        # @param value [String, Symbol] the port's name, such as `"CI"` or `"agent"`
+        # @return [String] the port name as stored
         def port(value) = @port = value.to_s
 
+        # Declares one plain setting a `.world` file may supply for this adapter.
+        #
+        # @param name [Symbol, String] the setting's name, such as `:database`
+        # @return [Array<Symbol>] every field declared so far, this one last
         def field(name) = @fields << name.to_sym
 
+        # Declares one setting whose value is a secret, such as an API token.
+        #
+        # @param name [Symbol, String] the secret's name, such as `:api_token`
+        # @return [Array<Symbol>] every secret declared so far, this one last
         def secret(name) = @secrets << name.to_sym
 
+        # Assembles the collected port, fields and secrets, judged by the adapter language.
+        #
+        # @return [Bluebook::Adapter] the adapter, returned once the language accepts it
+        # @raise [Bluebook::DSL::Malformed] if the adapter language refuses the declaration
         def build
           MetaValidator.call_adapter(Adapter.new(name: @name, port: @port, fields: @fields, secrets: @secrets))
         end
 
+        # Evaluates an `Hecks.adapter` block against a fresh builder and returns what it built.
+        #
+        # @param name [String] the adapter's name
+        # @yield the adapter body, evaluated with the builder as `self`; may be omitted
+        # @return [Bluebook::Adapter] the judged adapter
+        # @raise [Bluebook::DSL::Malformed] if the adapter language refuses the declaration, or
+        #   the block uses a word the `Adapter` grammar does not admit
         def self.build(name, &block)
           builder = new(name)
           builder.instance_eval(&block) if block

data/lib/hecks/bluebook/dsl/aggregate_builder/sealing.rb

@@ -2,17 +2,17 @@ module Hecks
   module Bluebook
     module DSL
       class AggregateBuilder
-        # THE "SEAL_*" PASS — everything `#build` runs once every
+        # **The "SEAL_*" pass** — everything `#build` runs once every
         # declaration (attributes, entities, commands, queries, the
         # lifecycle) is otherwise in place, checking that what a command,
-        # query, or default NAMES actually exists elsewhere on the
+        # query, or default names actually exists elsewhere on the
         # aggregate. Split out of aggregate_builder.rb (which keeps the
         # DSL surface itself — attribute/command/query/policy declaration
         # — and the smaller drain_pending!/identity bookkeeping) because
         # this cluster is one cohesive concern: cross-field validation
         # that can only run after every declaration is real, the same
         # relationship BluebookBuilder's own `self.validate_*` cluster has
-        # to ITS chapter (see that file's own header for the parallel).
+        # to its chapter (see that file's own header for the parallel).
         # `include`d back into AggregateBuilder, same pattern as
         # `Runtime::Registry`'s own `include Verification` /
         # `include SagaPersistence` — same class, its private instance
@@ -23,10 +23,10 @@ module Hecks
           # Every reference is told which Aggregate declares it, so it can
           # find the chapter and resolve its target.
           #
-          # Stamped HERE, at build, rather than at `reference_to`, because a command
+          # Stamped here, at build, rather than at `reference_to`, because a command
           # builder does not hold the aggregate and should not learn to. And
           # deliberately across every list that can carry one — a reference the walk
-          # missed would resolve to nil, and `resolve_references` SKIPS a nil target,
+          # missed would resolve to nil, and `resolve_references` skips a nil target,
           # so the guarantee would go quiet instead of going red. That is the exact
           # shape of the bug that let an Account belong to an unregistered customer
           # fourteen times over.
@@ -34,8 +34,8 @@ module Hecks
             reference_bearing_attributes.each { |attribute| attribute.type.declared_in = aggregate }
           end
 
-          # AN OWNED PIECE'S OWN `reference_to` IS AN EDGE THIS AGGREGATE
-          # POINTS ACROSS TOO (S9, ADR 0025 — "entity/aggregate shared
+          # An owned piece's own `reference_to` is an edge this aggregate
+          # points across too (S9, ADR 0025 — "entity/aggregate shared
           # vocabulary") — a ring closing through a contained piece (Board
           # -> Board::Card -> Product -> Board) is the same "no boundary
           # anyone can reason about alone" `validate_no_bidirectional_
@@ -43,7 +43,7 @@ module Hecks
           # aggregate ring; it was invisible before this because only
           # `AggregateBuilder#reference_to` ever fed `@reference_targets`,
           # never `EntityBuilder#reference_to`. Command/query reference
-          # ARGUMENTS are deliberately excluded — they are data flowing
+          # arguments are deliberately excluded — they are data flowing
           # through a dispatch, not persisted state the graph a cycle
           # means anything over.
           def entity_reference_targets
@@ -61,12 +61,12 @@ module Hecks
             lists.flatten.select(&:reference?)
           end
 
-          # A mutation must name a field the aggregate actually HAS.
+          # A mutation must name a field the aggregate actually has.
           #
-          # NOT moved to the language, and deliberately so. The language says only
+          # Not moved to the language, and deliberately so. The language says only
           # `given("a mutation names a target") { !target.value.to_s.empty? }` —
           # non-emptiness — because saying more means reaching a list that lives on
-          # a DIFFERENT root : a command's changes hang off Command, the fields they
+          # a different root : a command's changes hang off Command, the fields they
           # name hang off Aggregate, and a given is a closed predicate over its own
           # state. Aggregate.Seal is the right shape and cannot see commands ; the
           # reference trick that rescued "attributes use value-object types" needs a
@@ -78,10 +78,10 @@ module Hecks
           # So it lives here, at build, where every declaration is present. Found by
           # writing `then_set :disputed_by` on CardPayment before the field existed :
           # it wrote into nothing, refused nothing, and every check stayed green.
-          # A DEFAULT FILLS THE SHAPE IT IS DECLARED ON, or it fills nothing.
+          # A default fills the shape it is declared on, or it fills nothing.
           #
           # `attribute :cover, one_of("covered", "open"), default: "open"` builds
-          # cleanly and then refuses EVERY create at dispatch — "cover is a Cover,
+          # cleanly and then refuses every create at dispatch — "cover is a Cover,
           # pass its fields as an object" — because the value object wants its
           # fields and got a bare string. The bluebook is wrong at the line where
           # it is written and says so nowhere near it.
@@ -91,12 +91,12 @@ module Hecks
           # consistency about nothing. `till.bluebook` has always had the right shape
           # — `default: { cents: 0 }`.
           #
-          # A PRIMITIVE takes a scalar and a VALUE OBJECT takes its fields, so the
+          # A primitive takes a scalar and a value object takes its fields, so the
           # test is simply which one the type names. Nothing here guesses at the
           # keys: a default that is a Hash is left to `Value.for_attribute`, which
-          # is where a wrong FIELD belongs.
+          # is where a wrong field belongs.
           def seal_defaults
-            # `closed_sets` TOO, not only `@value_objects` — the exact gap
+            # `closed_sets` too, not only `@value_objects` — the exact gap
             # this method's own comment names: an inline `one_of(...)`
             # synthesises its value object through `closed_sets`
             # (AttributeCollector#synthesise_closed_set), never installed
@@ -120,7 +120,7 @@ module Hecks
           end
 
           # A command's `from:` guard needs a lifecycle field to check
-          # against — declared at BUILD time (S10, ADR 0025), the same
+          # against — declared at build time (S10, ADR 0025), the same
           # point every other "does this actually resolve" check in this
           # file runs, rather than left to crash `enforce_lifecycle_
           # guard` the first time such a command is ever dispatched.
@@ -137,12 +137,12 @@ module Hecks
             end
           end
 
-          # `projects`'s OWN half of "does this actually resolve" (S12,
-          # ADR 0025) — the LOCAL half only: `reference` must name a real
+          # `projects`'s own half of "does this actually resolve" (S12,
+          # ADR 0025) — the local half only: `reference` must name a real
           # reference-typed attribute this aggregate declares, and
           # `name` must not collide with an attribute already declared
           # (a projected field is its own kind of field, never a second
-          # spelling of one that already exists). The TARGET aggregate's
+          # spelling of one that already exists). The target aggregate's
           # own field is checked separately, once every aggregate in the
           # chapter is real — see BluebookBuilder#validate_projected_
           # fields!'s own comment for why that half cannot happen here.
@@ -173,23 +173,23 @@ module Hecks
             @commands.each do |command|
               command.mutations.each do |mutation|
                 # `:delegate` — CommandBuilder#delegates_to's own comment —
-                # targets no field of THIS aggregate at all; its `target`
+                # targets no field of this aggregate at all; its `target`
                 # names an "Entity.Command" pair instead, checked when the
                 # command builds (`delegates_to`'s own `rpartition` guard)
                 # and again at dispatch time (`CommandInterpreter
                 # #step_delegate_to_entity`, which refuses a real one that
-                # names no such entity or command). Sealing THIS check
+                # names no such entity or command). Sealing this check
                 # against it would refuse every delegating command outright.
                 # `:corrects` — CommandBuilder#corrects_impl's own comment —
-                # targets an EVENT name, not a field either; checked instead
+                # targets an event name, not a field either; checked instead
                 # by `seal_correction_targets`, below.
                 next if [:delegate, :corrects].include?(mutation.op)
 
                 # C5.3 (docs/semantics/bluebook-semantics.md) — the
-                # lifecycle field moves ONLY by transition; a `sets` on it
+                # lifecycle field moves only by transition; a `sets` on it
                 # would be overwritten by any transition and bypass the
                 # state machine otherwise. Refused at build — except for
-                # FROZEN ERA TEXT (`MetaValidator.shadow_parsing?`), which
+                # frozen era text (`MetaValidator.shadow_parsing?`), which
                 # is history and must keep parsing as the language tightens.
                 if @lifecycle && mutation.target.to_sym == @lifecycle.field.to_sym && !MetaValidator.shadow_parsing?
                   raise Malformed,
@@ -212,26 +212,26 @@ module Hecks
           # itself — a command cannot see its own siblings' `emits` while
           # it is still being built). Two things are checked:
           #
-          # 1. The named event must be something a SIBLING command here
+          # 1. The named event must be something a sibling command here
           #    actually `emits` — naming an event nothing in this aggregate
           #    ever announces is a build-time authoring error. (Whether
-          #    THIS record has actually emitted it YET is the dispatch-time
+          #    this record has actually emitted it yet is the dispatch-time
           #    half — CommandRules::Admissibility#enforce_correction_target.)
           #
           # 2. `reverses: true` derives the corrective `sets` from the
-          #    ORIGINAL command's own mutations, rather than the author
+          #    original command's own mutations, rather than the author
           #    writing them — but only when every one of those mutations is
-          #    STRUCTURALLY invertible with no runtime data: increment/
+          #    structurally invertible with no runtime data: increment/
           #    decrement, same argument, opposite verb (`sign_for`'s own
           #    +1/-1 pair — CommandRules::Arithmetic applies `current +
-          #    sign * amount`, so the SAME source with the OPPOSITE sign
+          #    sign * amount`, so the same source with the opposite sign
           #    undoes it exactly). Nothing else qualifies today: `set` has
-          #    no such rule at all — inverting it needs the SPECIFIC prior
+          #    no such rule at all — inverting it needs the specific prior
           #    value at the moment the original fired, which is per-
           #    instance runtime data no build-time derivation can have;
           #    `multiply`/`clamp` are lossy by design (a clamped value's
           #    own pre-clamp magnitude is not recoverable from the mutation
-          #    at all); `append`/`remove` LOOK symmetric but are not
+          #    at all); `append`/`remove` look symmetric but are not
           #    reliably so — `append`'s source is a per-field binding hash
           #    (`append: { name: :name, amount: :amount }`), `remove`'s is
           #    a single resolved value to match by equality
@@ -243,9 +243,9 @@ module Hecks
           #    — see docs/decisions/ for the ADR that draws this exact
           #    line.
           # One closed cluster of `corrects`/`reverses: true` rules, run
-          # in sequence against ONE command at a time (emission exists,
+          # in sequence against one command at a time (emission exists,
           # reverses/own-sets conflict, invertibility, then the actual
-          # derivation) — each `raise` gates the next check for THAT
+          # derivation) — each `raise` gates the next check for that
           # command, and `inverse_op`/`emitted_by` are shared read-only
           # lookups built once up front. Splitting the per-command body
           # out would still need all of `command`/`event`/`sources`/
@@ -299,11 +299,11 @@ module Hecks
             end
           end
 
-          # A query must ask about a field the aggregate actually HAS — the same
+          # A query must ask about a field the aggregate actually has — the same
           # seal `then_set` gets, closing the same silence: a where over a field
           # nothing declares matches nothing and refuses nothing, forever, on
           # every adapter. Three more silences close with it. A dotted path may
-          # reach through the value-object graph but must LAND on a scalar
+          # reach through the value-object graph but must land on a scalar
           # member (QuerySpecification::FieldPath is the one walk every engine
           # now shares) — landing on a value object hands SQL a JSON object
           # where the reference interpreter unwraps a hash. An ordered
@@ -339,13 +339,13 @@ module Hecks
               @entities.map { |entity| ["#{@name}::#{entity.hecks_name}", entity.attributes, entity.lifecycle, entity.queries] }
           end
 
-          # `/` CROSSES INTO ANOTHER RECORD, `.` WALKS FIELDS INSIDE THIS
-          # ONE (ADR 0025, "References") — the operator answers which
+          # `/` crosses into another record, `.` walks fields inside this
+          # one (ADR 0025, "References") — the operator answers which
           # kind of path this is now, not a name collision to arbitrate,
           # so a hop is routed to its own method before any `.`-splitting
           # runs at all; `seal_query_hop` below never sees a field this
           # one would also have tried to resolve as a local dotted walk.
-          # A closed decision tree over where ONE field can resolve —
+          # A closed decision tree over where one field can resolve —
           # hop, local scalar, lifecycle field, value object (refused),
           # or nothing (refused) — see the doc comment above (and the
           # method-level comments on the hop/ordering split) for why each
@@ -378,18 +378,18 @@ module Hecks
                   "matches nothing and refuses nothing"
           end
 
-          # ORDER BY refuses a hop OUTRIGHT, right here — unlike a WHERE
+          # ORDER BY refuses a hop outright, right here — unlike a WHERE
           # hop (deferred below), this doesn't need the target's shape to
           # answer: an ask is ordered by what its own answering rows
           # hold, and a hop answers with a candidate set, not a sort key
           # (see Runtime::ReferenceHop).
           #
-          # A WHERE hop is only RECOGNISED here, and CHECKED LATER. The
+          # A where hop is only recognised here, and checked later. The
           # head names one of this aggregate's own references, which is
           # answerable now — a Reference knows its own target_name at
-          # declaration. What it points AT is not: stamp_references has
+          # declaration. What it points at is not: stamp_references has
           # already run by this point, but the chapter (Bluebook, and the
-          # owning aggregate's OWN place in it) does not exist yet, so
+          # owning aggregate's own place in it) does not exist yet, so
           # Reference#resolve would answer nil for every target in the
           # file, including ones declared above this one. The tail, and
           # whether the target even exists, are BluebookBuilder's
@@ -416,14 +416,14 @@ module Hecks
           def seal_ordered_comparator(owner, query, fields, clause)
             return unless ORDERED_COMPARATORS.include?(clause.op.to_s.to_sym)
 
-            # A WHERE clause hopping through a reference with an ordered
+            # A where clause hopping through a reference with an ordered
             # comparator is legitimate ("client whose balance > 500") —
             # unlike ORDER BY (refused outright in seal_query_field, see
             # its own comment), a where-clause hop answers a real
             # candidate set either way, ordered or not. Deferred for the
             # same reason any other hop is: whether the tail is even
             # numeric is BluebookBuilder#validate_query_hops!'s question
-            # to ask of the TARGET's shape, not this aggregate's own.
+            # to ask of the target's shape, not this aggregate's own.
             return if clause.field.to_s.include?("/") && QuerySpecification::HopPath.hop_head?(clause.field, fields)
 
             name, *nested = clause.field.to_s.split(".")
@@ -473,17 +473,17 @@ module Hecks
             query.attributes << leaf if leaf
           end
 
-          # A BARE FIELD NAMING A VALUE OBJECT HAS TO SAY WHICH MEMBER IT
-          # MEANS, when more than one could answer. The dotted case above
+          # A bare field naming a value object has to say which member it
+          # means, when more than one could answer. The dotted case above
           # already refuses a path that lands on a value object rather than
           # a scalar; a bare name was returning unconditionally, so
           # `where(frequency: ...)` against a StatementFrequency
           # (cadence, retention_months, paper_fee_cents) compiled — and the
           # engines then disagreed about which member it meant, one taking
-          # the FIRST numeric and another declining to unwrap at all.
+          # the first numeric and another declining to unwrap at all.
           #
           # Unambiguous is: exactly one member, whatever its type, or
-          # exactly one NUMERIC member among several (Money's `cents`
+          # exactly one numeric member among several (Money's `cents`
           # beside its `currency` — the reading every engine already
           # shared, and what the corpus relies on). Anything else names
           # its member with a dotted path, which already works.