hecks 1.3.0 → 1.4.0

data/lib/hecks/bluebook/process_manager.rb

@@ -3,8 +3,8 @@ require_relative "../ir"
 
 module Hecks
   module Bluebook
-    # `compensates` — a SECOND `DispatchSpec`, shape-identical to this
-    # one, naming the command that undoes THIS dispatch specifically
+    # `compensates` — a second `DispatchSpec`, shape-identical to this
+    # one, naming the command that undoes this dispatch specifically
     # (see `ProcessManagerBuilder::HandlerBuilder#dispatch_impl`'s own
     # comment). `nil` for a dispatch with nothing to undo (a pure
     # bookkeeping mark, or one whose own effect is superseded by a later
@@ -14,7 +14,7 @@ module Hecks
     # used" bar would refuse a second level speculatively.
     DispatchSpec = Struct.new(:command_name, :with_spec, :compensates, keyword_init: true) do
       # A Struct already answers to_h; including the mixin puts the
-      # DECLARED emission ahead of Struct's own in the ancestry, which
+      # declared emission ahead of Struct's own in the ancestry, which
       # is what makes the shape data rather than a method body.
       include Hecks::IR
 
@@ -39,32 +39,32 @@ module Hecks
 
     # The compensation half of a procedure, as its own thing.
     #
-    # A PROCESS MANAGER coordinates: legs, states, an opinion about who goes
-    # next. A SAGA undoes: what makes the world good again when a leg it
+    # A process manager coordinates: legs, states, an opinion about who goes
+    # next. A saga undoes: what makes the world good again when a leg it
     # dispatched is refused. Two concepts, and the industry slurs them into one
     # word — so here they are two objects, and a procedure either has a saga or
     # does not.
     #
     # `undoes` is the ordered list of commands the compensation sends — a
-    # STATIC PREVIEW, declaration order (`Behaviour::ProcessManager#saga`),
+    # static preview, declaration order (`Behaviour::ProcessManager#saga`),
     # not one instance's own runtime history. Per-dispatch compensation
     # (`compensates`, on the step it compensates for) moved most of what
     # a saga undoes off this leg's own hand-written body and onto
     # whichever forward dispatch each one undoes — this reads every
-    # declared `compensates` across the WHOLE saga first, then whatever
+    # declared `compensates` across the whole saga first, then whatever
     # this leg's own hand-written body still lists, for compensation
-    # that isn't expressible as "undo command X." WHICH of a declared
+    # that isn't expressible as "undo command X." which of a declared
     # `compensates` actually fires for one instance, and in what order
     # (newest-first, completed-legs-only), is `SagaInterpreter`'s own
     # dynamic `completed_compensations` — a per-instance runtime fact
     # this declaration-only object could never hold.
     #
-    # NAMING COLLISION, ONCE FLAGGED, NOW RESOLVED — `command`'s own
+    # **Naming collision, once flagged, now resolved** — `command`'s own
     # `corrects event, reverses: true` (docs/implemented/decisions/0036-
     # corrects-is-an-appended-fact-not-a-rewrite.md) already claimed
-    # `reverses` for a different meaning: auto-deriving a command's OWN
-    # corrective mutation from a past EVENT, not a saga's own
-    # compensating leg from a past DISPATCH. This feature keeps
+    # `reverses` for a different meaning: auto-deriving a command's own
+    # corrective mutation from a past event, not a saga's own
+    # compensating leg from a past dispatch. This feature keeps
     # `reverses` reserved for `corrects` and uses `compensates` for
     # per-dispatch saga compensation instead — a deliberate choice, not
     # an accidental collision.
@@ -78,10 +78,10 @@ module Hecks
     # produced by `DSL::ProcessManagerBuilder` — its start/end events,
     # correlation field, derived states, and handler rows. Its
     # compensation half (`saga`, `Behaviour::ProcessManager#saga`) is
-    # DERIVED from the handler answering `REFUSED`, below, not declared as
+    # derived from the handler answering `REFUSED`, below, not declared as
     # its own construct.
     class ProcessManager
-      # The BLUEBOOK's name for this construct, asked the same way of a class
+      # The bluebook's name for this construct, asked the same way of a class
       # that has crossed over and of an IR object that has not. Collapses into
       # Construct when this one crosses.
       # The trigger of a compensating leg. Not an event name — no aggregate

data/lib/hecks/bluebook/project_register.rb

@@ -86,15 +86,15 @@ module Hecks
         end
       end
 
-      # THE ACTUAL "more than one tenant" MOMENT — Runtime::TenantCheck's
+      # The actual "more than one tenant" moment — Runtime::TenantCheck's
       # own header names this table as the one place real multitenancy
-      # happens: the SAME on-disk directory (one domain, one
-      # `persisted_by` binding) registering a SECOND time, under a
-      # different realm, into this SAME shared route table. A directory's
-      # FIRST registration is never refused here — nothing shares its
+      # happens: the same on-disk directory (one domain, one
+      # `persisted_by` binding) registering a second time, under a
+      # different realm, into this same shared route table. A directory's
+      # first registration is never refused here — nothing shares its
       # data yet, so a plain single-tenant deployment on an ordinary
       # adapter (Postgres, no schema story) still boots exactly as
-      # before. Only the SECOND (and any later) registration of that
+      # before. Only the second (and any later) registration of that
       # same directory is refused, and refused before this call adds its
       # routes to the table — so a leaking tenant's requests never
       # become reachable through `Router#resolve` in the first place.

data/lib/hecks/bluebook/query.rb

@@ -8,14 +8,14 @@ module Hecks
   module Bluebook
     def self.render_value(value) = Literal.render(value)
 
-    # A query — an ASK, declared on an aggregate or on one of its entities.
+    # A query — an ask, declared on an aggregate or on one of its entities.
     #
-    # It crosses over as an INSTANCE rather than a class, and the reason is worth
+    # It crosses over as an instance rather than a class, and the reason is worth
     # stating because it is the boundary of the pattern. A query inherits its
     # whole body from `QuerySpecification::Common::Options` — `wheres`,
     # `order_by`, `limit`, `offset`, `cursor`,
     # `authorization`, `null_semantics`, `inspection` — and those
-    # are INSTANCE methods that the runtime and the SQLite adapter both read.
+    # are instance methods that the runtime and the SQLite adapter both read.
     # Hoisting the declaration onto a metaclass would put the identity and the
     # specification on opposite sides of the object.
     #
@@ -54,7 +54,7 @@ module Hecks
         @attributes  = attributes
       end
 
-      # A query's shape is NOT fixed — `extra_options_to_h` carries
+      # A query's shape is not fixed — `extra_options_to_h` carries
       # whatever options the specification layer grew (count, median,
       # group_by, scope_to). Declared emission covers the settled part
       # and `super` hands it over; the tail stays dynamic, which is the

data/lib/hecks/bluebook/read_model.rb

@@ -4,11 +4,11 @@ module Hecks
   module Bluebook
     # A read model — an ask that gathers heads from more than one aggregate.
     #
-    # Like a query it crosses over as an INSTANCE, and for the same reason: its
+    # Like a query it crosses over as an instance, and for the same reason: its
     # body is inherited from `QuerySpecification::ReadModel::Specification`, whose
     # readers the runtime and the SQLite adapter both call on the object. It gains
     # an identity and an owner ; it keeps the name it always had, because only a
-    # CLASS ever had a competing answer for `name`.
+    # class ever had a competing answer for `name`.
     class ReadModel < QuerySpecification::ReadModel::Specification
       include Construct
 
@@ -29,7 +29,7 @@ module Hecks
       attr_reader :name, :description, :reference_name, :reference_target, :aggregate_heads, :group_by,
                   :count, :median_field
 
-      # `reference_name:`/`reference_target:` are nil for a ROOTLESS read
+      # `reference_name:`/`reference_target:` are nil for a rootless read
       # model (no `reference_to` declared) — `&.` throughout, rather than
       # the `.to_s`/`.to_sym` this used to require unconditionally, so
       # `reference_target.nil?` stays a real, checkable fact for the
@@ -47,11 +47,11 @@ module Hecks
         # `group_by_fields` is the convenience reader everything but
         # `to_h`/the Judge's own generic walk actually wants.
         @group_by         = group_by
-        # ABSENT IS NOT FALSE. `@count` stays nil rather than becoming
+        # **Absent is not false**. `@count` stays nil rather than becoming
         # `false` when undeclared — the same "if you declare it, declare
         # something" reading `Lifecycle`'s own optional fields rely on
         # (MetaValidator::Judge#setters skips a setter whose every
-        # source is `nil`, so an ALWAYS-false `@count` would dispatch
+        # source is `nil`, so an always-false `@count` would dispatch
         # `ReadModel.Count` on every read model that never wrote the
         # word at all). `!!count` collapses a truthy DSL `true` (or a
         # reconstructed `true`) to the same `true`/`nil` pair either path
@@ -60,15 +60,15 @@ module Hecks
         @median_field     = median_field&.to_sym
       end
 
-      # `.to_sym` regardless of source — the DIRECT builder path stores
+      # `.to_sym` regardless of source — the direct builder path stores
       # symbols, but `Reconstruction::Shapes#group_by_field` (the
-      # replayed-from-the-meta-domain path every REAL boot actually
+      # replayed-from-the-meta-domain path every real boot actually
       # goes through) reads the field back as a String, the same way
-      # `aggregate_heads`' own `:as` does. Row hash KEYS built by
+      # `aggregate_heads`' own `:as` does. Row hash keys built by
       # `Value.materialize_unwrapped` are symbols (`attr.name`), so
       # this has to be too, or `row[field]` in `nest` silently misses.
 
-      # `wheres`/`order_by`/`limit` are spelled explicitly here, the SAME
+      # `wheres`/`order_by`/`limit` are spelled explicitly here, the same
       # mechanism `Query#to_h` already uses (query.rb, read directly
       # before this was written) — always present, `wheres` a (possibly
       # empty) array and `order_by`/`limit` nil when undeclared, exactly
@@ -78,16 +78,16 @@ module Hecks
       # than a reader needing to learn a second one. See this file's own
       # `filtered_head_name` and language/bluebook/syntax.bluebook's
       # `ReadModel` `where`/`order_by`/`limit` member rows for the history
-      # of why this WAS narrower, and 2026-08-11's read-model where/
+      # of why this was narrower, and 2026-08-11's read-model where/
       # order_by/limit task for why it stopped being.
       # Same dynamic tail as a Query's, plus two collections whose
-      # ROWS are plain hashes rather than constructs — they are
+      # rows are plain hashes rather than constructs — they are
       # normalised here rather than by `many`, which recurses through
       # `to_h` and would have nothing to call.
-      # `count`/`median_field` are ABSENT (no key at all), not `nil`,
+      # `count`/`median_field` are absent (no key at all), not `nil`,
       # when undeclared — unlike `group_by` (always a `[]`, never
-      # missing) they are the FIRST fields this construct has ever
-      # added that no OLDER real corpus member could possibly carry, so
+      # missing) they are the first fields this construct has ever
+      # added that no older real corpus member could possibly carry, so
       # merging them unconditionally would have put a `null` onto every
       # existing read model's own wire shape (banking's
       # `ComplianceDashboard`/`CustomerPortfolio`, the language's own

data/lib/hecks/bluebook/reference.rb

@@ -2,15 +2,15 @@ module Hecks
   module Bluebook
     # An attribute that points at another aggregate's head.
     #
-    # This used to be the STRING `"Reference<Customer>"`, minted by
+    # This used to be the string `"Reference<Customer>"`, minted by
     # `AggregateBuilder#reference_to` and `CommandBuilder#cross_reference` from
     # a real constant that had just been handed in, and then parsed back apart
     # by a regex in the command interpreter, by string equality in the read-model
     # interpreter and the SQLite adapter, and by `delete_prefix` in the bluebook
     # builder. Five readers of a spelling one writer invented.
     #
-    # It holds the TARGET instead, and answers `resolve` with the target's
-    # Aggregate. Resolution is LAZY and deliberately so: `reference_to
+    # It holds the target instead, and answers `resolve` with the target's
+    # Aggregate. Resolution is lazy and deliberately so: `reference_to
     # Customer` may name an aggregate declared lower in the file — banking's
     # Account points at Customer and survives only because Customer happens to
     # be written above — so the edge cannot be resolved at declaration time.
@@ -34,7 +34,7 @@ module Hecks
       end
 
       # The Aggregate this points at, or nil when the target belongs to
-      # ANOTHER domain — a cross-domain target may legitimately not be loaded,
+      # another domain — a cross-domain target may legitimately not be loaded,
       # the same reading `across` policies get.
       def resolve
         unless declared_in
@@ -51,13 +51,13 @@ module Hecks
       def to_s = "Reference<#{@target_name}>"
       def inspect = "#<Reference #{@target_name}>"
 
-      # VALUE EQUALITY, not identity — without this, two references to
-      # the SAME target, parsed from two SEPARATE bluebook reads (era
+      # Value equality, not identity — without this, two references to
+      # the same target, parsed from two separate bluebook reads (era
       # N's own boot and a held era's own shadow reconstruction,
       # coverage_check.rb's own comparison), are different objects and
       # compare unequal by Ruby's default `==`. `EraGuard::ShapeDiff
       # #diff_type`'s `held_type != current_type` check then reads as
-      # true for EVERY reference_to attribute on EVERY mint, regardless
+      # true for every reference_to attribute on every mint, regardless
       # of whether the reference actually changed — a real refusal for
       # attributes nothing about. `declared_in` (which aggregate carries
       # this reference) is deliberately excluded: the same reference
@@ -65,7 +65,7 @@ module Hecks
       # from separately-parsed bluebooks with structurally different
       # (if same-shaped) owning aggregates, and `declared_in` is a
       # cross-reference for `resolve`, not part of what this attribute
-      # itself IS.
+      # itself is.
       def ==(other) = other.is_a?(Reference) && target_name == other.target_name
       alias eql? ==
       def hash = [self.class, target_name].hash

data/lib/hecks/bluebook/smoke_test.rb

@@ -4,10 +4,10 @@ require "fileutils"
 
 module Hecks
   module Bluebook
-    # BOOTS A REAL BLUEBOOK AND ACTUALLY DISPATCHES AGAINST IT — the
+    # Boots a real bluebook and actually dispatches against it — the
     # sibling `bin/model_check` never had: that tool proves a bluebook
-    # is STRUCTURALLY sound (no dead states, no unreachable transitions)
-    # without ever running a single command; this proves it WORKS,
+    # is structurally sound (no dead states, no unreachable transitions)
+    # without ever running a single command; this proves it works,
     # catching exactly the class of bug static analysis structurally
     # cannot see. Built and proved inside `bin/interview`'s own `smoke`
     # command, where it first found two real bugs — a lifecycle field
@@ -15,20 +15,20 @@ module Hecks
     # missing `Command.ActsOn` — that reloaded clean, checked clean,
     # and only broke once something actually dispatched against them.
     #
-    # SYNTHESIZED ARGS, NEVER RANDOM (`Synthesizer`) — a String becomes
+    # Synthesized args, never random (`Synthesizer`) — a String becomes
     # a fixed marker, a closed set uses its own first admitted member, a
     # reference reuses whatever this same run already minted for that
-    # target. ONE call per declared command, ONE call per declared
+    # target. One call per declared command, one call per declared
     # report, per created root; every failure is collected and reported
     # together rather than stopping at the first.
     #
-    # WHAT THIS CANNOT CATCH: a call that dispatches cleanly but answers
-    # WRONG — the read-model join bug this exact tool's own first user
+    # **What this cannot catch**: a call that dispatches cleanly but answers
+    # wrong — the read-model join bug this exact tool's own first user
     # hit is the textbook case, a query that silently returned an empty
     # array rather than raising. Smoke-testing proves nothing crashes;
     # it does not prove the answer is the right one.
     #
-    # A FAILURE HERE IS NOT NECESSARILY A DOMAIN BUG, either — it may
+    # A failure here is not necessarily a domain bug, either — it may
     # just be `Synthesizer`'s own naive values (0, an empty list,
     # "smoke-test") not satisfying a real invariant this simple
     # generator was never built to reason about (a positive amount, a
@@ -54,11 +54,11 @@ module Hecks
       # per-domain realm resolution requires and a plain boot never
       # did. Reports are reachable the identical way regardless of
       # boot path — `dispatcher.query("Domain.report_name", **args)`
-      # is the SAME `Dispatcher#query` either boot hands back; Router
-      # was never actually required for this, only its OWN namespace
-      # SUGAR (`Domain.report_name(...)` as a bare method call) was.
+      # is the same `Dispatcher#query` either boot hands back; Router
+      # was never actually required for this, only its own namespace
+      # sugar (`Domain.report_name(...)` as a bare method call) was.
       #
-      # NEVER BOOTS `dir`'S OWN REAL BINDINGS — measured, not a
+      # Never boots `dir`'s own real bindings — measured, not a
       # precaution taken on spec: pointed at `examples/pizzas` (a real,
       # persistent store carrying real accumulated records), a
       # synthesized `CreatePizza` collided with an actual pre-existing
@@ -73,7 +73,7 @@ module Hecks
       # `install_facade: false` — this only ever dispatches by FQN string
       # (below), so it never needs the `Widget::Item.Add(...)` Ruby
       # sugar `Hecks.boot` installs by default. Skipping it matters
-      # here specifically: that sugar lands as a BARE global constant on
+      # here specifically: that sugar lands as a bare global constant on
       # `Object` per domain and per aggregate name, with no scoping and
       # no cleanup — and this tool boots throwaway domains under
       # whatever generic names the caller's `.bluebook` happens to use
@@ -93,9 +93,9 @@ module Hecks
         end
       end
 
-      # ONLY THE `.bluebook`, NEVER `.world` EITHER — a real world's own
+      # Only the `.bluebook`, never `.world` either — a real world's own
       # settings (`persisted_by("Heki") { dir "..." }`) are keyed to the
-      # REAL adapter it names, not to Memory; copied verbatim, they
+      # real adapter it names, not to Memory; copied verbatim, they
       # apply to the wrong binding and refuse with a `WiringError`
       # ("Memory does not declare :dir") — measured, not assumed, the
       # first time this ran against Banking. A plain `Hecks.boot`
@@ -112,8 +112,8 @@ module Hecks
         Dir.glob(File.join(source, "*.bluebook")).each { |file| FileUtils.cp(file, target) }
       end
 
-      # AGGREGATES WALKED IN DECLARATION ORDER, on purpose — so whatever
-      # a LATER aggregate's own shape needs from an EARLIER one (a
+      # Aggregates walked in declaration order, on purpose — so whatever
+      # a later aggregate's own shape needs from an earlier one (a
       # `TripItem` needing a real `PackingItem`, say) already exists by
       # the time that aggregate's own turn comes, the same reason
       # `Synthesizer#args_for`'s `created` map is threaded through in
@@ -136,7 +136,7 @@ module Hecks
           creating.each do |command|
             args = Synthesizer.args_for(chapter, aggregate, command, created)
             begin
-              result = dispatcher.dispatch("#{domain}::#{aggregate.name}.#{command.hecks_name}", **args)
+              result = dispatcher.dispatch_flat("#{domain}::#{aggregate.name}.#{command.hecks_name}", args)
               created[aggregate.name] = result.instance.id
             rescue StandardError => e
               failures << Failure.new(domain: domain, aggregate: aggregate.name, command: command.hecks_name,
@@ -146,7 +146,7 @@ module Hecks
 
             noncreating.each do |nc_command|
               nc_args = Synthesizer.args_for(chapter, aggregate, nc_command, created).merge(id: created[aggregate.name])
-              dispatcher.dispatch("#{domain}::#{aggregate.name}.#{nc_command.hecks_name}", **nc_args)
+              dispatcher.dispatch_flat("#{domain}::#{aggregate.name}.#{nc_command.hecks_name}", nc_args)
             rescue StandardError => e
               failures << Failure.new(domain: domain, aggregate: aggregate.name, command: nc_command.hecks_name,
                                       error: "#{e.class}: #{e.message}")

data/lib/hecks/bluebook/synthesizer.rb

@@ -1,12 +1,12 @@
 module Hecks
   module Bluebook
-    # ONE SYNTHESIZED ARGUMENT PER DECLARED ATTRIBUTE — never a random
+    # **One synthesized argument per declared attribute** — never a random
     # guess. Reads only real `IR` (`Aggregate`, `Command`,
-    # `Attribute`, `ValueObject`), so it works against ANY
+    # `Attribute`, `ValueObject`), so it works against any
     # loaded bluebook, not one particular domain: a String becomes a
-    # fixed marker; an Integer becomes 0; a closed set uses ITS OWN
+    # fixed marker; an Integer becomes 0; a closed set uses its own
     # first admitted member (never a value a real `one_of` would
-    # legitimately refuse); a reference uses whatever id the CALLER
+    # legitimately refuse); a reference uses whatever id the caller
     # already knows for that target (`created`), so a command whose
     # own shape depends on an earlier-created record — a `TripItem`
     # needing a real `PackingItem`, say — gets something real to work
@@ -16,8 +16,8 @@ module Hecks
     # got built and proved — the logic never actually knew anything
     # about the Interview domain or any one app; it only ever read IR.
     module Synthesizer
-      # THE ONLY TYPE NAMES THAT ARE EVER TRULY SCALAR — anything else
-      # a value object's own field names is ANOTHER value object,
+      # The only type names that are ever truly scalar — anything else
+      # a value object's own field names is another value object,
       # nested (`Pizza.price_cents: Price`, itself wrapping `cents:
       # Integer` — a real, ordinary shape, not an edge case). Missing
       # this the first time round meant a nested field silently
@@ -26,7 +26,7 @@ module Hecks
       # only by testing against Pizzas instead of re-testing against
       # the one simpler domain this was first built for, where every
       # value object happened to be single-field and primitive-typed.
-      # THE SAME LIST `Attribute::PRIMITIVES` holds, referenced rather
+      # The same list `Attribute::PRIMITIVES` holds, referenced rather
       # than repeated. It was a second, byte-identical copy — and only
       # the Attribute one is held to `vocabulary.bluebook` by
       # spec/vocabulary_conformance_spec, so this copy could drift from
@@ -38,7 +38,7 @@ module Hecks
       # `chapter`/`aggregate` are the real `Bluebook`/`Aggregate`
       # the command belongs to — needed to resolve a value object type
       # name back to its own declared shape. `created` maps an
-      # aggregate NAME to a real id already minted for it earlier in
+      # aggregate name to a real id already minted for it earlier in
       # the same run; a reference whose target isn't in there yet gets
       # a placeholder instead of failing outright, since the caller may
       # not care about that particular argument's real value.
@@ -52,13 +52,13 @@ module Hecks
         end
       end
 
-      # A value object's OWN synthesized value — its first admitted
+      # A value object's own synthesized value — its first admitted
       # member if it's a closed set (the one value guaranteed not to be
       # refused), otherwise one synthesized scalar per declared field.
       # Falls back to searching every aggregate in the chapter, the
       # same tolerance `bin/interview shape`'s own lookup already
       # needed: a value object referenced by name doesn't have to be
-      # declared on the SAME aggregate using it.
+      # declared on the same aggregate using it.
       def value_for(chapter, aggregate, type_name)
         value_object = aggregate.value_object(type_name) ||
                        chapter.aggregates.filter_map { |a| a.value_object(type_name) }.first
@@ -72,7 +72,7 @@ module Hecks
 
       # A single field's own synthesized value — a plain scalar if its
       # type is one of the true primitives, otherwise that type names
-      # ANOTHER value object, resolved the identical way `value_for`
+      # another value object, resolved the identical way `value_for`
       # resolves any other one (its own closed set or its own nested
       # fields, however deep that nesting actually goes).
       def field_value_for(chapter, aggregate, type_name)
@@ -80,7 +80,7 @@ module Hecks
       end
 
       # A bare primitive's own synthesized value. Never used for a
-      # closed set's OWN field (that's `value_for`'s job, reading the
+      # closed set's own field (that's `value_for`'s job, reading the
       # set's real first member) — only for a plain scalar field with
       # no declared vocabulary to respect.
       def scalar_for(primitive)

data/lib/hecks/bluebook/translation.rb

@@ -5,7 +5,7 @@ module Hecks
     # Paths are dotted ("price.cents") for a VO member, bare otherwise.
     TranslationMove = Struct.new(:from, :to)
 
-    # One field whose VALUE, not just its name or position, changed —
+    # One field whose value, not just its name or position, changed —
     # an old value has nothing in common with a new one, so the only
     # honest way to bridge it is a declared, exhaustive lookup table.
     # Paths follow `TranslationMove`'s convention (dotted reaches a VO
@@ -16,7 +16,7 @@ module Hecks
     # rubocop:disable-next Lint/StructNewOverride
     TranslationConvert = Struct.new(:from, :to, :values)
 
-    # A value object's or entity's own TYPE NAME changed with its member
+    # A value object's or entity's own type name changed with its member
     # structure unchanged — the one drift `rename`/`move` cannot express,
     # because the attribute kept its name and only the type it points at
     # was renamed. Mirrors `was:` one level deeper.
@@ -29,7 +29,7 @@ module Hecks
     # every other adapter.
     TranslationCompute = Struct.new(:from, :to, :sql)
 
-    # The aggregate's own IDENTITY changed what it's computed from — not
+    # The aggregate's own identity changed what it's computed from — not
     # a field crossing a boundary (that's `move`), a value objects's type
     # name (`retype`), or a value transform (`compute`): the record's own
     # key. No `from:`/`to:` path, unlike every other rule here, because
@@ -41,7 +41,7 @@ module Hecks
     TranslationRekey = Struct.new(:sql)
 
     # A newly added, required attribute with no source in old data at
-    # all — not a rename, move, or convert, all of which need a FROM
+    # all — not a rename, move, or convert, all of which need a from
     # path in the old shape. `default` is the value an existing record
     # reads until the next command against it writes a real one; unlike
     # `compute`, this is adapter-agnostic — applied in-process by

data/lib/hecks/bluebook/value_object.rb

@@ -5,7 +5,7 @@ module Hecks
   module Bluebook
     Invariant = Struct.new(:description, :canonical, :predicate, :ast, keyword_init: true)
 
-    # A value object — a DECLARATION HOLDER, never instantiated.
+    # A value object — a declaration holder, never instantiated.
     #
     # `ValueObjectBuilder` returns an anonymous subclass whose singleton
     # carries the declaration : attributes, invariants, members. Nothing ever
@@ -16,11 +16,11 @@ module Hecks
     #
     # `to_h` does not move. It is a byte-for-byte contract pinned by the
     # golden fixtures, so it keeps spelling the short declared name, which
-    # is what `hecks_name` carries. DECLARATIONS IN THE GRAPH, STRINGS IN THE
-    # EXPORT.
+    # is what `hecks_name` carries. Declarations in the graph, strings in the
+    # export.
     class ValueObject
       extend Construct
-      # EXTENDED, not included — this construct is a class, so its
+      # Extended, not included — this construct is a class, so its
       # emission is a class method. See Hecks::IR's own note on
       # the two shapes.
       extend Hecks::IR
@@ -29,7 +29,7 @@ module Hecks
       emits_ir(
         name:       :hecks_name,
         attributes: many(:attributes),
-        # `ast:` — a JSON-serializable rendering of the SAME predicate
+        # `ast:` — a JSON-serializable rendering of the same predicate
         # `canonical` already spells as text, alongside it rather than
         # replacing it (`canonical` stays the human-facing/doctest-facing
         # form; parsing it back would just re-derive what `ast` already
@@ -39,7 +39,7 @@ module Hecks
         # has no kernel crate to parse `canonical` with.
         invariants: -> { invariants.map { |rule| Expression::AstJson.rule_row(rule) } },
         closed_set: :closed_set?,
-        # THE FIELD NAME IS STRINGIFIED, NEVER THE VALUE. A `member` row can
+        # The field name is stringified, never the value. A `member` row can
         # hold any of the scalar types an attribute declares — `Integer 84`
         # (`StatementFrequency#retention_months`, statements.bluebook), not
         # only `String` — and `value.to_s` used to erase that on the way

data/lib/hecks/bluebook.rb

@@ -13,7 +13,7 @@
 # the meta-validator that its builders call at build time.
 
 module Hecks
-  # Declared as a CLASS, not a module — `Hecks::Bluebook` IS a
+  # Declared as a class, not a module — `Hecks::Bluebook` is a
   # chapter (bluebook/chapter.rb carries its body). Everything a chapter
   # declares nests under it, as do the ways to build one (`DSL`) and to
   # judge one (`MetaValidator`). Reopening this anywhere must say `class`.
@@ -29,7 +29,7 @@ require_relative "literal"
 require_relative "query_specification"
 
 require_relative "bluebook/expression"
-# THE MODEL ITSELF — the chapter class's own body first, then everything
+# **The model itself** — the chapter class's own body first, then everything
 # a chapter declares. Order matters only for reading: each is a bag of
 # declarations with no load-time cross-references.
 require_relative "bluebook/chapter"