hecks 1.3.0 → 1.4.0

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

@@ -5,12 +5,12 @@ module Hecks
     # Command, ValueObject, Query, ...); see `Contract`'s own header
     # (contract.rb) for the struct format each entry below fills in.
     class Assembly
-      # ONE TABLE, WHERE THERE WERE FIVE HAND-WRITTEN MIRRORS OF IT.
+      # 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:
+      # and only those:
       #
       #   holder    which class holds it
       #   make      :declare for a construct that became a class, :new for an
@@ -19,17 +19,17 @@ module Hecks
       #   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
+      # 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. The judge used to carry one
+      # Why a table and not a method per category. The judge used to carry one
       # hand-written branch per category, and the price was fourteen verbs the
       # language declared and the walk never offered — every rule hanging off them
       # decoration, and nothing red, because a branch that does not exist cannot
       # fail. An assembler with a method per category is the same shape. So the
-      # table is checked AGAINST the language by spec/assembly_spec: a field the
+      # table is checked against the language by spec/assembly_spec: 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
@@ -47,7 +47,8 @@ module Hecks
             vision:            [:vision,         :plain],
             classification:    [:classification, :plain],
             formerly_known_as: [:formerly_known_as, :plain],
-            attaches_to:       [:attaches_to, :plain]
+            attaches_to:       [:attaches_to, :plain],
+            provides:          [:provides, :plain]
           },
           rows: { normalisations: :normalisation_table },
           derived: { normalisations: :elsewhere }
@@ -60,7 +61,7 @@ module Hecks
             description:      [:description,   :plain],
             identified_by:    [:identified_by, :plain],
             attributes:       [:attributes,    [:each, :attribute]],
-            # THE AGGREGATE BOUNDARY, and the precondition a command may
+            # 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,
@@ -101,7 +102,7 @@ module Hecks
             ensures:    [:ensures,    [:each, :given]],
             mutations:  [:mutations,  [:each, :mutation]],
             emits:      [:emits,      :plain],
-            # LIFECYCLE STATE AS A COMMAND GUARD (S10, ADR 0025) — a
+            # 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.
@@ -138,7 +139,7 @@ module Hecks
             wheres:         [:wheres,          [:each, :where_clause]],
             order_by:       [:order_by,        :order_by],
             limit:          [:limit,           :limit],
-            # Held by the language as an OPEN MAP, so every one of these reads the
+            # 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]],
             cursor:         [:cursor,          [:option, :cursor]],
@@ -162,20 +163,20 @@ module Hecks
           fields: {
             name:          [:name,          :plain],
             description:   [:description,   :plain],
-            # A LIST OF PATHS, exactly as an aggregate's is. The two used to differ
+            # A list of paths, exactly as an aggregate's is. The two used to differ
             # — a Symbol here and a String there, which byte equality with `to_h`
-            # COULD NOT SEE because both render as a string, so the assembled graph
+            # could not see because both render as a string, so the assembled graph
             # got a String and `element_of` looked up `args["sequence"]` in a
             # symbol-keyed payload and found nothing: "Reverse acts on one
             # LedgerEntry — pass sequence:", while passing sequence. There is one
             # spelling now, and no room left for that difference.
             identified_by: [:identified_by, :plain],
             attributes:    [:attributes,    [:each, :shape_field]],
-            # ADR 0028 — the SAME shape Aggregate's own `preconditions`
+            # 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.
             preconditions: [:preconditions, [:each, :given]],
-            # Round 7 — the SAME shape Aggregate's own `invariants`
+            # 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.
             invariants:    [:invariants,    [:each, :invariant]]
@@ -195,17 +196,18 @@ module Hecks
         "Policy"         => Contract.new(
           holder: Policy, make: :new,
           fields: {
-            name:            [:name,            :plain],
-            aggregate:       [:aggregate,       :plain],
-            on_event:        [:on_event,        :plain],
-            trigger_command: [:trigger_command, :plain],
-            target_domain:   [:target_domain,   :plain],
-            where:           [:where,           :plain],
-            for_each:        [:for_each,        :plain],
-            with_spec:       [:with_spec,       :bindings]
+            name:               [:name,            :plain],
+            aggregate:          [:aggregate,       :plain],
+            on_event:           [:on_event,        :plain],
+            trigger_command:    [:trigger_command, :plain],
+            target_domain:      [:target_domain,   :plain],
+            expect_undelivered: [:expect_undelivered, :plain],
+            where:              [:where,           :plain],
+            for_each:           [:for_each,        :plain],
+            with_spec:          [:with_spec,       :bindings]
           },
           rows: { with_spec: :with_spec_rows },
-          reads: { with_spec: [:from, :with_spec] },
+          reads: { with_spec: [:from, :with_spec], expect_undelivered: :expect_undelivered? },
           derived: { position: :walk }
         ),
 
@@ -213,7 +215,7 @@ module Hecks
           holder: ProcessManager, make: :new,
           fields: {
             name:          [:name,          :plain],
-            # A SYMBOL. `SagaInterpreter` does `event.payload[pm.correlates_by]` — a
+            # **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
@@ -224,7 +226,7 @@ module Hecks
             states:        [:states,        :plain]
           },
           reads: { states: :names },
-          # S17, ADR 0026 — `handlers` is a REAL feature of the LANGUAGE's
+          # 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
@@ -237,7 +239,7 @@ module Hecks
         # S17, ADR 0026 — Handler is a genuine entity now, nested under
         # ProcessManager (`entity "Handler"`, reaction.bluebook). Neither
         # `position` nor `handler` is a stored field any more: a saga
-        # answers each event ONCE, so `event_type` is Handler's own real,
+        # 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
@@ -251,7 +253,7 @@ module Hecks
           },
           # `dispatches` — same reason ProcessManager's own `handlers`
           # claim, above, is `:children` : a real feature of the
-          # LANGUAGE's own "Handler" declaration (`attribute :dispatches,
+          # 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.
@@ -261,7 +263,7 @@ module Hecks
         # 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 used to be Dispatch's own
+        # words). `command_name` alone used to be Dispatch's own
         # identity, until items #151/#152 (`process_manager.bluebook`'s
         # own `DispatchPosition` comment) found it collided the instant a
         # real handler fanned the same command out more than once —
@@ -270,22 +272,22 @@ module Hecks
         # 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
+        # `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
+        # 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
+        # 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
+        # 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.
@@ -372,7 +374,7 @@ module Hecks
             # 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).
+            # instead (fed the stringified meta-domain row).
             count:            [:count,            :plain],
             median_field:     [:median_field,     :plain],
             # A read model inherits every option an ask has, so it reads them the
@@ -392,12 +394,12 @@ module Hecks
           # `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
+          # 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
+          # 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
@@ -419,7 +421,7 @@ module Hecks
           }
         ),
 
-        # A member's pairs are an OPEN MAP, which is why Member is its own root in
+        # 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 now, nested under

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

@@ -6,10 +6,10 @@ module Hecks
       # `to_h` spells things as text so the export stands on its own, and every
       # one of those spellings has to come back apart here. This is the same family
       # of work `MetaValidator::Shapes` does for the reconstruction — the difference
-      # is that Shapes rebuilds HASHES and this rebuilds OBJECTS, so it has to
+      # is that Shapes rebuilds hashes and this rebuilds objects, so it has to
       # recover types rather than just strings.
       #
-      # ENCODING LOSSES ARE THE LARGEST FAMILY OF BUG IN THIS CODEBASE, and every
+      # Encoding losses are the LARGEST family of bug in this codebase, and every
       # member has the same shape: reading an object where `to_h` holds a spelling.
       # So each method below names the spelling it inverts.
       module Marks
@@ -27,7 +27,7 @@ module Hecks
             type:         target ? Reference.new(target) : type,
             list:         field[:list] ? true : false,
             default:      field[:default],
-            # The LAST place optionality can be dropped, and the one that was
+            # The last place optionality can be dropped, and the one that was
             # dropping it. Every bluebook in the registry is the round-trip
             # product — MetaValidator dispatches the declaration in and reads it
             # back — so a fact this constructor does not carry is a fact the
@@ -35,9 +35,9 @@ module Hecks
             # wrote it.
             optional:     field[:optional] ? true : false,
             pattern:      field[:pattern],
-            # THE SAME LESSON, ONE FACT LATER. `admits` is not on `to_h` — the
+            # **The same lesson, one fact later**. `admits` is not on `to_h` — the
             # wire does not carry it, on purpose — but it must still survive the
-            # round trip, because the grammar registry keeps the ASSEMBLED graph
+            # round trip, because the grammar registry keeps the assembled graph
             # and downstream projections read the link off that. Dropped here, the
             # language could not say `admits` about itself no matter how plainly
             # the source wrote it, which is word for word what the note above
@@ -52,15 +52,15 @@ module Hecks
         # both — `Aggregate.Attribute` and `Command.Argument` are separate verbs.
         def shape_field(field) = attribute(field)
 
-        # ONE PART OF AN IDENTITY. It goes in as a row so the language can hold an
+        # One part of an identity. It goes in as a row so the language can hold an
         # ordered list of them, and comes back out as the path it always was —
         # a String, because `identity_paths` splits paths and never symbols.
         def identity_path(part) = part[:value].to_s
 
-        # A member's fields — an OPEN MAP, which is why Member is its own root in
+        # A member's fields — an open map, which is why Member is its own root in
         # the language and why the pairs arrive as a list rather than a value object.
         #
-        # The values are UNMARKED, because `ValueObject#to_h` spells them with `to_s`
+        # The values are unmarked, because `ValueObject#to_h` spells them with `to_s`
         # and the language stores them as text: `member code: "JPY", minor_units: 0`
         # came back with a minor_units of "0", and a closed set that admits the string
         # would refuse the number the caller passes.
@@ -69,7 +69,7 @@ module Hecks
         end
 
         # A read model's gathered head. The keys must be symbols whichever way the
-        # declaration arrived, and `as` must be one too: it NAMES the reader the
+        # declaration arrived, and `as` must be one too: it names the reader the
         # projection answers to, and `ReadModel#to_h` spells it `to_s`.
         def head(row)
           row.to_h { |key, value| [key.to_sym, key.to_sym == :as ? value.to_sym : value] }
@@ -118,8 +118,8 @@ module Hecks
 
         # `Mutation#to_h` branches on the operation, so this does too.
         #
-        # An APPEND binds several fields at once, each either an ARGUMENT (a
-        # Symbol, wearing its colon) or a LITERAL — the distinction that is the
+        # An append binds several fields at once, each either an argument (a
+        # Symbol, wearing its colon) or a literal — the distinction that is the
         # whole reason `append: { direction: "out" }` was once indistinguishable
         # from an argument named `out`.
         def mutation(change)
@@ -127,7 +127,7 @@ module Hecks
           op     = change[:op].to_sym
 
           # `:delegate`/`:corrects` (CommandBuilder#delegates_to's and
-          # #corrects_impl's own comments) ride the SAME multi-binding
+          # #corrects_impl's own comments) ride the same multi-binding
           # shape `:append` does.
           return Mutation.new(target: target, op: op, source: appended(change[:fields])) if [:append, :delegate,
                                                                                              :corrects].include?(op)
@@ -139,7 +139,7 @@ module Hecks
           Array(fields).to_h { |field, source| [field.to_sym, read(source)] }
         end
 
-        # A SET reads one thing, and `classified_source` said which: an argument by
+        # A set reads one thing, and `classified_source` said which: an argument by
         # name, or a literal by value.
         def classified(source)
           return nil if source.nil?
@@ -151,7 +151,7 @@ module Hecks
           end
         end
 
-        # EVERY LITERAL FIELD ON THE WIRE, read back — one spelling, one reader.
+        # Every literal field on the wire, read back — one spelling, one reader.
         #
         # A where-clause value, a saga's argument bindings, an append binding, a
         # limit: all of them ride Literal's self-describing form, so all of them
@@ -159,7 +159,7 @@ module Hecks
         # that disagreed about quoted strings and numbers, and which one a call
         # site got was a coin toss the comments had to keep apologising for.
         #
-        # AN OBJECT LITERAL is the one that bit. A saga leg binds `narrative: {
+        # An object literal is the one that bit. A saga leg binds `narrative: {
         # text: "transfer out" }` — a value object's fields written inline — and
         # `to_s` on a Hash used to be its inspect form, so it came back as text.
         # Read as a string it reached the runtime as `"{:text=>\"transfer out\"}"`,
@@ -171,10 +171,10 @@ module Hecks
         def read(value) = Literal.read(value)
 
         # `target:` (ADR 0055) — read straight off the wire, unconverted:
-        # it's already the bare aggregate-name STRING `WhereClause#to_h`/
+        # it's already the bare aggregate-name string `WhereClause#to_h`/
         # `OrderBy#to_h`/`LimitSpec#to_h` wrote (`resolve_target`'s own
         # `Naming.demodulise` already ran once, at DSL-build time; this is
-        # the REPLAY path every real boot actually goes through, reading
+        # the replay path every real boot actually goes through, reading
         # that same wire shape back — see this class's own header). Absent
         # from `clause`/`declared` entirely on older wire data that never
         # declared `on:` — `clause[:target]`/`declared[:target]` reads
@@ -200,7 +200,7 @@ module Hecks
           QuerySpecification::Common::LimitSpec.new(value: read(declared[:value]), target: declared[:target])
         end
 
-        # EVERY OTHER SPECIFICATION OPTION, from one table.
+        # Every other specification option, from one table.
         #
         # Each entry names the struct and which of its members carry a value that
         # rode Literal's spelling rather than plain text. A

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

@@ -1,45 +1,31 @@
 module Hecks
   module Bluebook
     class Assembly
-      # THE FIRST SPECIALIZER — a projection of `contracts.rb`'s `fields:` table,
+      # **The first specializer** — a projection of `contracts.rb`'s `fields:` table,
       # derived from the language's own description of a category instead of
       # hand-written beside it.
       #
       # `Plan` already reads `grammar_registry` to build the judge's walk ; this
-      # reads the same chapter to build the OTHER table this arc's own header
-      # names as duplication — "SPELLED AS THE IR SPELLS THEM," field for field,
+      # reads the same chapter to build the other table this arc's own header
+      # names as duplication — "spelled as the IR spells them," field for field,
       # for every category simple enough to say so.
       #
-      # ONE CASE, PROVEN, NOT THE WHOLE TABLE. A field this can speak for is
+      # One case, proven, not the whole table. A field this can speak for is
       # scalar and not a reference — every other field (a list, a reference, a
       # fold like Lifecycle) is exactly what `contracts.rb`'s `reads:`/`derived:`
       # exist to say, and stays hand-written until a later projection learns to
       # derive readers and folds too. Restricting the claim to what can be
-      # PROVEN CORRECT — checked in spec/specializer_spec.rb against two
+      # proven correct — checked in spec/specializer_spec.rb against two
       # independent categories — is the same discipline `derived:` itself
       # enforces : a claim needs a kind, and this one's kind is "plain, checked."
       module Specializer
         module_function
 
-        # `position` IS THE FIRST FOLD THIS RUNS INTO, and it is a universal
-        # one : every category declares `attribute :position, Position` — for
-        # the JUDGE's own walk, `order_by :position` on its `DeclaredIn` ask —
-        # but no `*` constructor takes it as an argument. `contracts.rb`
-        # already says so, in the language every other derived field speaks :
-        # `derived: { position: :walk }`. The language says a category HAS a
-        # position ; it does not say a category's OWN constructor is handed
-        # one, and that second fact is exactly what `fields:` needs to answer.
-        # So this is not silently special-cased — it is the one fold named
-        # here because it is the one fold that is not a lucky accident of
-        # Policy or Handler, but a fact true of every category this arc will
-        # ever reach.
-        DERIVED_EVERYWHERE = %i[position].freeze
-
         # S17, ADR 0026 — `Handler` is a genuine entity now, nested under
         # `ProcessManager`, so `.aggregate` alone no longer finds it —
         # it hangs off some aggregate's own `.entities` instead
         # (searched recursively, the same reason `Value::Coercion#find_
-        # entity` does: a NESTED entity, like `Dispatch` inside
+        # entity` does: a nested entity, like `Dispatch` inside
         # `Handler`, is not a direct child of any aggregate either).
         def construct_for(chapter, name)
           chapter.aggregate(name) || chapter.aggregates.filter_map { |a| find_entity(a, name) }.first
@@ -55,11 +41,23 @@ module Hecks
           nil
         end
 
+        # `position` is the first fold this runs into : a category declares
+        # `attribute :position, Position` — for the judge's own walk,
+        # `order_by :position` on its `DeclaredIn` ask — but no `*`
+        # constructor takes it as an argument. `contracts.rb` already says so,
+        # in the language every other derived field speaks :
+        # `derived: { position: :walk }`. The language says a category has a
+        # position ; it does not say a category's own constructor is handed
+        # one, and that second fact is exactly what `fields:` needs to answer.
+        # So the skip reads the category's own walk claims (`Contract#walked`)
+        # rather than restating `position` here — Handler, which has no
+        # walk-minted position, skips nothing.
         def fields_for(category)
           language = construct_for(MetaValidator.grammar_registry.bluebook("Bluebook"), category.to_s)
+          walked   = Assembly.contract(category).walked
           language.attributes.each_with_object({}) do |attribute, fields|
             next if attribute.list? || attribute.reference?
-            next if DERIVED_EVERYWHERE.include?(attribute.name)
+            next if walked.include?(attribute.name)
 
             fields[attribute.name] = [attribute.name, :plain]
           end

data/lib/hecks/bluebook/assembly.rb

@@ -1,6 +1,6 @@
 module Hecks
   module Bluebook
-    # A GRAPH BUILT FROM DECLARATIONS, rather than from DSL calls.
+    # A graph built from declarations, rather than from DSL calls.
     #
     # This is the half that lets the language orchestrate. `Reconstruction` reads a
     # chapter back out of the meta-domain, in declaration order, as plain
@@ -8,24 +8,24 @@ module Hecks
     # into the graph the runtime runs: IR aggregates with their verbs, value
     # objects, entities and asks, owned by the chapter that declares them.
     #
-    # It takes a HASH, not a runtime, on purpose. That makes it a pure inverse of
+    # It takes a hash, not a runtime, on purpose. That makes it a pure inverse of
     # `to_h` and testable without the meta-domain in the picture at all:
     #
     #     Assembly.call(built.to_h).to_h == built.to_h
     #
     # which is the check `spec/assembly_spec` makes for every chapter in the tree.
     # Feed it the reconstruction instead and the same code assembles what the
-    # LANGUAGE holds — the only difference being where the declarations came from.
+    # language holds — the only difference being where the declarations came from.
     #
-    # EVERY FIELD IS READ FROM ONE TABLE. There is no method per category here:
+    # Every field is read from one table. There is no method per category here:
     # `Contracts` names what the language cannot say about a construct, `Build`
     # reads it, and the coverage gate holds the table to the language. The first
     # draft of this file did have a method each, which is the shape the judge used
     # to have — and the price of that shape was fourteen verbs the language declared
     # and nothing ever offered.
     #
-    # What stays hand-written is the CONTAINMENT: which construct holds which.
-    # That is not a field table. (The runtime SURFACE is no longer built here at
+    # What stays hand-written is the containment: which construct holds which.
+    # That is not a field table. (The runtime surface is no longer built here at
     # all — the door is a per-boot projection, facade/surface.rb.)
     class Assembly
       def self.call(declaration) = new(declaration).bluebook
@@ -50,7 +50,7 @@ module Hecks
       private
 
       # Every reaction the chapter holds, and each one also handed back to the head
-      # that declared it — the builder keeps a policy in BOTH places, hoisting it onto
+      # that declared it — the builder keeps a policy in both places, hoisting it onto
       # the chapter where the runtime reads it while the head keeps its own list. The
       # language records which head, so the assembly can put it back.
       def reactions(aggregates)
@@ -72,10 +72,10 @@ module Hecks
                    dispatches: Array(row[:dispatches]).map { |leg| dispatch(leg) })
       end
 
-      # `compensates` — a PLAIN HASH on the declaration (`Reconstruction#
+      # `compensates` — a plain hash on the declaration (`Reconstruction#
       # dispatch`'s own comment for why), built into the real
       # `DispatchSpec` its own field actually is by recursing through
-      # THIS SAME method, one level in — the identical move `handler`
+      # this same method, one level in — the identical move `handler`
       # itself takes into `dispatches`, one level up. `nil` when there
       # is nothing to compensate; `Build.call` never sees a
       # `compensates:` key it does not know how to read either way, the

data/lib/hecks/bluebook/attribute.rb

@@ -28,15 +28,15 @@ module Hecks
 
       attr_reader :name, :type, :default, :pattern, :admits, :relationship
 
-      # A Reference is kept AS ITSELF. Every other type is still a name, and
+      # A Reference is kept as itself. Every other type is still a name, and
       # crosses over as its construct does.
       #
-      # `admits` names an ALREADY-DECLARED closed set the value must belong
+      # `admits` names an already-declared closed set the value must belong
       # to — `Vocabulary::QueryComparator` — spelled aggregate-qualified
-      # because the set is a value object INSIDE an aggregate, and the
+      # because the set is a value object inside an aggregate, and the
       # aggregate is the only thing `reference_to` can reach.
       #
-      # ON THE WIRE, because it is a RULE and not only a typing hint.
+      # On the wire, because it is a rule and not only a typing hint.
       #
       # It began as neither. The link existed so a generator could type
       # `WhereClause.op` as `WhereOp` — a typing convenience, not worth
@@ -48,7 +48,7 @@ module Hecks
       # refused "burnt" through one reading and emitted the event through
       # another.
       #
-      # The wire carries the NAME, not the members. A reader resolves it
+      # The wire carries the name, not the members. A reader resolves it
       # against the IR it holds, so the members are declared once and
       # copied nowhere — which is the same reason `admits` exists at all.
       def initialize(name:, type:, list: false, default: nil, optional: false, pattern: nil,
@@ -63,13 +63,13 @@ module Hecks
         @relationship = relationship&.to_s
       end
 
-      # A BARE CONSTANT IN A BLUEBOOK IS A NAME, EVEN WHEN RUBY HAS HEARD OF IT.
+      # A bare constant in a bluebook is a name, even when Ruby has heard of it.
       #
       # `BluebookBuilder.build` says exactly this and installs a `const_missing`
       # resolver that hands back the symbol — `attribute :target, Target` becomes
       # the name "Target" and nothing looks Target up. That works only while the
-      # lookup FAILS, and `Facade::Surface` installs every aggregate name as a
-      # TOP-LEVEL constant (its own comment, and `ConstShim`'s, both say so).
+      # lookup fails, and `Facade::Surface` installs every aggregate name as a
+      # top-level constant (its own comment, and `ConstShim`'s, both say so).
       #
       # So in one process: boot a domain with an aggregate named `Target`, then
       # load a chapter whose own value object is called `Target`, and Ruby
@@ -81,7 +81,7 @@ module Hecks
       # `QualityControl::Target` are both "Target". A plain class stays itself —
       # `String` demodulises to "String" — so the ordinary case is untouched.
       # This does not undo the constant leak; it makes the leak unable to change
-      # what a chapter MEANS, which is the part that has to hold.
+      # what a chapter means, which is the part that has to hold.
       def spell(type)
         return type if type.is_a?(Reference)
         return Naming.demodulise(type) if type.is_a?(Module)

data/lib/hecks/bluebook/behaviour/aggregate.rb

@@ -3,14 +3,14 @@ require_relative "traits"
 module Hecks
   module Bluebook
     module Behaviour
-      # WHAT AN AGGREGATE DOES, as opposed to what it holds.
+      # What an aggregate does, as opposed to what it holds.
       #
       # The holding half — the field list, the readers, the emission — is
       # the same list the language already declares in
       # `language/bluebook/aggregate.bluebook`, said a second and third
       # time in Ruby. This half is not: derived identity, the name
       # indexes, the owner stamping and the finders are decisions about
-      # HOW the declared shape is used, and no grammar states them.
+      # how the declared shape is used, and no grammar states them.
       #
       # Split so the holding half can be generated from the language
       # without any of this being in the blast radius of a regeneration.
@@ -24,11 +24,11 @@ module Hecks
         include Indexed
         include Owns
 
-        # An aggregate is a MEMBER of its chapter's namespace — "Pizzas::Pizza" —
-        # where everything else is declared ON its owner and joins with ".".
+        # An aggregate is a member of its chapter's namespace — "Pizzas::Pizza" —
+        # where everything else is declared on its owner and joins with ".".
         def hecks_separator = "::"
 
-        # THE HOOK THE GENERATED CONSTRUCTOR CALLS once every declared
+        # The hook the generated constructor calls once every declared
         # field is assigned. Nothing here is derivable from the
         # declaration, which is exactly why it is not generated.
         def settle
@@ -46,7 +46,7 @@ module Hecks
           @commands_by_name      = index_by_hecks_name(@commands)
           @queries_by_name       = index_by_hecks_name(@queries)
           @ports_by_name         = @ports.to_h { |port| [port.name, port] }
-          # S12, ADR 0025 — keyed by SYMBOL, the same convention
+          # S12, ADR 0025 — keyed by symbol, the same convention
           # `Indexed#attribute` already uses; `GuardState` asks for one
           # by name at every dispatch, the rebuild sweep walks all of
           # them once per pass.
@@ -55,18 +55,18 @@ module Hecks
 
         def projected_field(named) = @projected_fields_by_name[named.to_sym]
 
-        # A value object is a CLASS now, so `name` is Ruby's answer (the constant
+        # A value object is a class now, so `name` is Ruby's answer (the constant
         # path) and the declared name is `hecks_name`. This finder is on its way
-        # out — once an attribute's type IS the class there is nothing to find —
+        # out — once an attribute's type is the class there is nothing to find —
         # but every consumer still asks by type string, so it stays until they
         # stop.
         def value_object(named) = @value_objects_by_name[named.to_s]
         def port(named)         = @ports_by_name[named.to_s]
 
-        # A PORT IS DECLARED IN THE HECKSAGON, NOT THE BLUEBOOK — the
+        # A port is declared in the hecksagon, not the bluebook — the
         # boundary between the domain and its adapters, in hexagonal terms,
-        # is exactly what a `.hecksagon` file already IS for every other
-        # port (persistence, projection, ...). So this attaches AFTER the
+        # is exactly what a `.hecksagon` file already is for every other
+        # port (persistence, projection, ...). So this attaches after the
         # aggregate already exists and is registered — `HecksagonBuilder`
         # calls it once per `port` declaration, having already stamped each
         # operation's reference attributes with `declared_in = self`, since