hecks 1.2.0 → 1.4.0

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

@@ -11,6 +11,14 @@ module Hecks
         class << self
           attr_accessor :resolver
 
+          # Installs a resolver for the duration of a block, restoring the earlier one afterwards
+          # even if the block raises.
+          #
+          # @param resolver [#call] called with the missing constant's name as a Symbol; whatever
+          #   it returns is what the bare constant evaluates to
+          # @yield the DSL code whose undeclared constants the resolver should answer
+          # @yieldreturn [Object] any value; it becomes this method's result
+          # @return [Object] whatever the block returns
           def with(resolver)
             previous  = @resolver
             @resolver = resolver
@@ -19,45 +27,63 @@ module Hecks
             @resolver = previous
           end
 
+          # Reports whether a resolver is installed, meaning code is running inside a DSL block.
+          #
+          # @return [Boolean] true inside a `with` block, or after `resolver=` set one directly
           def active? = !@resolver.nil?
         end
 
-        # THE SCOPED-CONSTANT BRIDGE (ADR 0025, docs/dsl-work-slices.md's
+        # The scoped-constant bridge (ADR 0025, docs/dsl-work-slices.md's
         # S0b) — a Symbol cannot answer `::`, so `Account::Debit` and
         # `admits: Account::LedgerDirection` could never resolve past
-        # their FIRST segment while `Account` returned a bare Symbol
+        # their first segment while `Account` returned a bare Symbol
         # (`resolver = ->(const) { const }`, bluebook_builder.rb's own
-        # comment on why that was right for a BARE name): Ruby's `::`
+        # comment on why that was right for a bare name): Ruby's `::`
         # operator raises `TypeError` on the returned value before any
         # DSL code runs at all, unless that value is itself a Module.
         #
-        # A REAL `Module` subclass, not a decorated Symbol, for exactly
-        # that reason — nothing else answers `::`. Every existing
-        # consumer keeps working duck-typed, not because nothing
-        # changed: `Attribute#spell`'s `type.is_a?(Module)` branch now
-        # fires where it used to fall to `type.to_s`, and
-        # `Naming.demodulise` (`path.split("::").last`) gives the
-        # IDENTICAL string either way for a single segment — the two
-        # branches were already equivalent for a name with no `::` in
-        # it, which is every bareword before this.
+        # A real `Module` subclass, not a decorated Symbol, for exactly
+        # that reason — nothing else answers `::`. Every consumer of a
+        # bareword type keeps working duck-typed: `Attribute#spell`'s
+        # `type.is_a?(Module)` branch fires for one of these where a
+        # bare Symbol falls to `type.to_s`, and `Naming.demodulise`
+        # (`path.split("::").last`) gives the identical string either
+        # way for a single segment — the two branches are equivalent
+        # for a name with no `::` in it, which is every unscoped
+        # bareword.
         class ScopedConstant < Module
+          # Wraps a constant path, the form a `ConstShim` resolver hands back for a bareword.
+          #
+          # @param path [Symbol, String] one segment such as `:Account`, or a `::`-joined path
+          # @return [Bluebook::DSL::ConstShim::ScopedConstant] a module standing in for that path
           def self.for(path) = new(path.to_s)
 
+          # @param path [String] the constant path this module stands in for
           def initialize(path)
             super()
             @path = path
           end
 
-          # ONE MORE SEGMENT, the same way an unresolved const anywhere
+          # Extends the path by one segment, so `Account::Debit` resolves past `Account`.
+          #
+          # One more segment, the same way an unresolved const anywhere
           # else does — `Account::Debit::Anything` keeps chaining rather
           # than refusing, since nothing here knows how deep a reference
           # is meant to go; the DSL keyword that finally reads `.to_s`
           # is the one place that does.
+          #
+          # @param name [Symbol] the segment written after `::`
+          # @return [Bluebook::DSL::ConstShim::ScopedConstant] a new constant for the longer path
           def const_missing(name) = ScopedConstant.for("#{@path}::#{name}")
 
           def to_s     = @path
           def to_sym   = @path.to_sym
           def inspect  = @path
+
+          # Exposes the raw path under a name no ordinary `Module` answers, so `==` can compare
+          # two scoped constants without going through `to_s`.
+          #
+          # @return [String] the `::`-joined path, such as `"Account::Debit"`
           def hecks_path = @path
 
           def ==(other) = other.is_a?(ScopedConstant) ? @path == other.hecks_path : @path.to_sym == other
@@ -65,15 +91,20 @@ module Hecks
           def hash = @path.hash
         end
 
-        # A SCOPED NAME IS WRITTEN AS TEXT, NOT AS A CONSTANT PATH — see the
+        # A scoped name is written as text, not as a constant path — see the
         # note on `admits:` in AttributeCollector. A resolver returning a
         # Module (so that `Vocabulary::QueryComparator` reaches a second
         # `const_missing`) was tried and cannot be made to hold : `Facade::
-        # Surface` installs EVERY aggregate name as a top-level constant, so
+        # Surface` installs every aggregate name as a top-level constant, so
         # once any facade is built, `Vocabulary` resolves to that real module
         # and never reaches this hook at all. A spelling that works only
         # before a facade exists is worse than one that always works.
         module Hook
+          # Answers an undeclared top-level constant from the active resolver, if there is one.
+          #
+          # @param name [Symbol] the missing constant's name
+          # @return [Object] whatever the active resolver returns for `name`
+          # @raise [NameError] if no resolver is installed, as Ruby raises for any unknown constant
           def const_missing(name)
             resolver = ConstShim.resolver
             resolver ? resolver.call(name) : super

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

@@ -14,21 +14,27 @@ module Hecks
 
         include WordGate
 
-        # `legacy_bare_port:` — ONLY `Hecks.port`'s own top-level method
+        # `legacy_bare_port:` — only `Hecks.port`'s own top-level method
         # (lib/hecks.rb) passes `true`. `PortBuilder#build` never refused
         # an empty build (no verb, no signal, nothing) — `Port.new(verb:
         # nil, signal: :reply)` is a real, allowed shape dsl_spec.rb's own
         # "a port" tests rely on (`signal`-only, no `verb` at all). The
-        # AGGREGATE-scoped (`BindingProxy#port`) and hecksagon-ROOT
-        # (`HecksagonBuilder#port_impl`) callers both reach this SAME
+        # aggregate-scoped (`BindingProxy#port`) and hecksagon-root
+        # (`HecksagonBuilder#port_impl`) callers both reach this same
         # class with `owner: nil` too when they're building the bare-verb
-        # shape (`port_impl`'s own root-level port can be EITHER shape,
+        # shape (`port_impl`'s own root-level port can be either shape,
         # decided only after `build` returns) — so `owner.nil?` cannot be
         # the discriminator between "old Hecks.port semantics" and "real
         # DomainPort semantics"; those two callers correctly want the
         # stricter "declares no verb and no operations" refusal `build`
         # already raises below, unchanged. Only the literal top-level
         # `.port` file caller wants the older, looser rule.
+        #
+        # @param name [String] the port's name
+        # @param owner [String, nil] name of the aggregate the port is declared on, handed to
+        #   each operation's builder; nil for a root-level or top-level port
+        # @param legacy_bare_port [Boolean] true only for `Hecks.port`: an empty body then builds
+        #   a verbless `Port` rather than being refused
         def initialize(name, owner: nil, legacy_bare_port: false)
           @name             = name
           @owner            = owner
@@ -38,40 +44,63 @@ module Hecks
           @legacy_bare_port = legacy_bare_port
         end
 
-        # WHAT THE OUTSIDE TELLS US — an external fact arriving, translated
-        # into this domain's own word for it. Spelled `operation` before it
-        # had a twin, and `operation` still works: the corpus is full of it,
-        # and renaming a word costs every chapter that uses it for no gain a
-        # reader can feel.
+        # Declares an inbound operation: a fact the outside world delivers to this domain.
+        #
+        # **What the outside tells us** — an external fact arriving, translated
+        # into this domain's own word for it. Spelled `operation` or `tells`;
+        # `operation` stays because the corpus is full of it, and renaming
+        # a word costs every chapter that uses it for no gain a reader can
+        # feel.
         #
-        # RENAMED FROM `tells` — item #13's full metaprogrammed dispatch
-        # (slice 4c). `operation`/`tells` are TWO separate Keyword rows
+        # Answers both words — item #13's full metaprogrammed dispatch
+        # (slice 4c). `operation`/`tells` are two separate Keyword rows
         # (a word admitting two forms) that both name `calls: "tells_impl"`
-        # — the routing between the two spellings now lives in the table,
+        # — the routing between the two spellings lives in the table,
         # not in a Ruby `alias`. Not bootstrap-reachable (checked
-        # directly), so no BOOTSTRAP_CALLS_FALLBACK entry needed.
+        # directly), so its `BOOTSTRAP_CALLS_FALLBACK` row is never consulted.
+        #
+        # @param name [String] the operation's name, such as `"PaymentSettled"`
+        # @param to [Symbol, String, Module, nil] the aggregate the operation routes to, written
+        #   as a bare constant; nil leaves routing to the operation's own attributes
+        # @yield the operation body (`attribute`, `emits`), evaluated against a
+        #   `PortOperationBuilder`
+        # @return [Array<Bluebook::PortOperation>] every operation declared so far, this one last
+        # @raise [Bluebook::DSL::Malformed] if the body declares no `emits`, or uses `answers` or
+        #   `refuses`, which belong to an `asks`
         def tells_impl(name, to: nil, &)
           @operations << PortOperationBuilder.build(name, to: to, owner: @owner, direction: :inbound, &)
         end
 
-        # WHAT WE ASK OF THE OUTSIDE — the direction this language did not
-        # have. Before this, a domain could be CALLED by an adapter and never
-        # call one. An `asks` is dispatched like any other port operation, so
+        # Declares an outbound operation: a question this domain puts to the outside world.
+        #
+        # **What we ask of the outside** — the direction that lets a domain
+        # call an adapter, not only be called by one. An `asks` is dispatched
+        # like any other port operation, so
         # a `policy` can trigger it off an event, and it comes back as one of
         # the two events it named — which is what makes the outside world
         # something the model can reason about rather than a place exceptions
         # come from.
         #
-        # RENAMED FROM `asks` — item #13's full metaprogrammed dispatch
-        # (slice 4c), same reasoning as tells_impl above.
+        # Answers the `asks` word through the table's `calls:` column — item
+        # #13's full metaprogrammed dispatch (slice 4c), same reasoning as
+        # `tells_impl` above.
+        #
+        # @param name [String] the operation's name
+        # @param to [Symbol, String, Module, nil] the aggregate the operation routes to, written
+        #   as a bare constant; nil leaves routing to the operation's own attributes
+        # @yield the operation body (`attribute`, `answers`, `refuses`), evaluated against a
+        #   `PortOperationBuilder`
+        # @return [Array<Bluebook::PortOperation>] every operation declared so far, this one last
+        # @raise [Bluebook::DSL::Malformed] if the body declares `emits`, or lacks either
+        #   `answers` or `refuses`
         def asks_impl(name, to: nil, &)
           @operations << PortOperationBuilder.build(name, to: to, owner: @owner, direction: :outbound, &)
         end
 
-        # THE DRIVEN HALF OF THE SAME WORD. `operation`/`emits` translates an
+        # The driven half of the same word. `operation`/`emits` translates an
         # inbound fact into this domain's own event vocabulary — there is no
         # channel back to a caller beyond the events it emits. `verb` is the
-        # opposite direction: the domain calling OUT to a swappable adapter
+        # opposite direction: the domain calling out to a swappable adapter
         # and getting a real value back (a checkout URL, a fetched document),
         # exactly what `Hecks.port "name" do verb "x" end` already builds —
         # this is that same `Port`, reached from the same `port` call
@@ -83,9 +112,12 @@ module Hecks
         # coerce-and-assign with nothing else, now executed by
         # `GenericDispatch`.
 
+        # Names the verb aggregates call this port by, which makes it a driven `Port` rather than
+        # a `DomainPort` of operations.
+        #
         # `Hecks.port "x" do verb "y"; signal :effect end`'s own two words,
         # reachable here too — a bare-verb `DomainPortBuilder.build` falls
-        # back to the SAME `Port` object `PortBuilder` produces (`build`,
+        # back to the same `Port` object `PortBuilder` produces (`build`,
         # below), so any `.port` file can migrate to being parsed by this
         # builder with zero change to its own text, or to any caller that
         # reads `.verb`/`.signal` off the `Port` it gets back. Ordinary
@@ -93,20 +125,40 @@ module Hecks
         # header is explicit that a word answered this way never reaches
         # its `method_missing`, so no new self-hosted grammar row is
         # needed for either word under this context.
+        #
+        # @param value [String, Symbol] the verb, such as `"charged_by"`
+        # @return [String] the verb as stored
         def verb(value)   = @verb = value.to_s
+
+        # Sets whether a verb-shaped port hands a value back; one left unset signals `:reply`.
+        #
+        # @param value [Symbol, String] `:reply` when the adapter answers with a value,
+        #   `:effect` when it is called only for its effect
+        # @return [Symbol] the signal as stored
         def signal(value) = @signal = value.to_sym
 
-        # THE METHOD CONTRACT — `PortBuilder#answers`'s own twin, added
-        # here after the fact: a `.port` file migrated to parse through
-        # this builder (the repoint `lib/hecks.rb#port`'s own comment
-        # describes) can still declare one (`extraction.port`'s own
+        # Declares one method an adapter bound to a verb-shaped port must respond to.
+        #
+        # **The method contract** — `PortBuilder#answers`'s own twin: a
+        # `.port` file parsed through this builder (the repoint
+        # `lib/hecks.rb#port`'s own comment describes) can declare one
+        # (`extraction.port`'s own
         # `answers :canonical`, real, live corpus text) — this builder's
         # bare-verb fallback needs to carry it through to the same `Port`
         # object `PortBuilder` itself would have built, or the migration
         # would silently drop a method-contract check for any `.port`
         # file that uses this word.
+        #
+        # @param name [Symbol, String] the method name, such as `:canonical`
+        # @return [Array<Symbol>] every method declared so far, this one last
         def answers(name) = @answers << name.to_sym
 
+        # Assembles whichever of the two port shapes the body declared.
+        #
+        # @return [Bluebook::Port, Bluebook::DomainPort] a `Port` when the body named a `verb`
+        #   (or was empty under `legacy_bare_port:`), otherwise a `DomainPort` of its operations
+        # @raise [Bluebook::DSL::Malformed] if the body declares both a verb and operations,
+        #   declares neither without `legacy_bare_port:`, or the port language refuses the `Port`
         def build
           if @verb && !@operations.empty?
             raise Malformed,
@@ -123,6 +175,19 @@ module Hecks
           DomainPort.new(name: @name, operations: @operations)
         end
 
+        # Evaluates a `port` block against a fresh builder and returns whichever shape it declared.
+        #
+        # @param name [String] the port's name
+        # @param owner [String, nil] name of the aggregate the port is declared on, or nil for a
+        #   root-level or top-level port
+        # @param legacy_bare_port [Boolean] true only for `Hecks.port`, which lets an empty body
+        #   build a verbless `Port`
+        # @yield the port body, evaluated with the builder as `self`; may be omitted
+        # @return [Bluebook::Port, Bluebook::DomainPort] a verb-shaped `Port`, or a `DomainPort`
+        #   holding the declared operations
+        # @raise [Bluebook::DSL::Malformed] if the body declares both shapes, declares neither
+        #   without `legacy_bare_port:`, holds an operation its builder refuses, or uses a word
+        #   the `DomainPort` grammar does not admit
         def self.build(name, owner: nil, legacy_bare_port: false, &block)
           builder = new(name, owner: owner, legacy_bare_port: legacy_bare_port)
           builder.instance_eval(&block) if block

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

@@ -30,18 +30,18 @@ module Hecks
           @owner_value_objects = owner_value_objects
           @identity_name_prefix = identity_name_prefix || Naming.demodulise(name)
           @identity_value_object_installer = identity_value_object_installer
-          # THE AGGREGATE-WIDE cross-entity given pool — ONE hash, the
-          # SAME object, threaded unchanged through every piece nested
+          # The aggregate-wide cross-entity given pool — one hash, the
+          # same object, threaded unchanged through every piece nested
           # under one aggregate however deep (the identical shape
           # `@owner_value_objects` already threads — see this class'
           # own `entity` comment). `given`'s own block form writes
-          # through to it; a SIBLING piece's bare command-level
+          # through to it; a sibling piece's bare command-level
           # reference reads from it via `CommandBuilder#
           # reference_named_given`.
           @owner_named_givens = owner_named_givens
-          # ONE LEVEL WIDER STILL — the CHAPTER-WIDE, ENTITY-SCOPED pool
+          # **One level wider still** — the chapter-wide, entity-scoped pool
           # (the piece analogue of `AggregateBuilder#@chapter_named_givens`,
-          # one level down). `@aggregate_name` names THIS piece's own
+          # one level down). `@aggregate_name` names this piece's own
           # root, so the write-through below can key itself
           # "AggregateName.EntityName" — the same dotted addressing
           # convention `declared_by:` already uses chapter-wide, one
@@ -51,10 +51,10 @@ module Hecks
           @aggregate_name = aggregate_name || Naming.demodulise(name)
           @chapter_entity_named_givens   = chapter_entity_named_givens
           @chapter_entity_pending_givens = chapter_entity_pending_givens
-          # DEFERRED CONSTRUCTION — see `AggregateBuilder#drain_pending!`'s
+          # **Deferred construction** — see `AggregateBuilder#drain_pending!`'s
           # own comment; the identical mechanism, one level down, so a
           # nested piece's own commands (Dispatch inside Handler) see
-          # every SIBLING entity/command/query this piece goes on to
+          # every sibling entity/command/query this piece goes on to
           # declare, not just whatever came before it textually.
           @pending_entities = []
           @pending_commands = []
@@ -63,12 +63,12 @@ module Hecks
 
         def description(value) = @description = value
 
-        # THE SAME FIELD AggregateBuilder's OWN reference_to BUILDS — a
+        # The same field AggregateBuilder's own reference_to builds — a
         # piece can hold a reference to another root exactly the way its
         # own head can (Card.assignee_id, a Team's own id), just never
-        # to another PIECE, since there's no cross-piece addressing
+        # to another piece, since there's no cross-piece addressing
         # anywhere in this language to resolve one against.
-        # RENAMED FROM `reference_to` — item #13's full metaprogrammed
+        # Renamed from `reference_to` — item #13's full metaprogrammed
         # dispatch (slice 4b). Bootstrap-reachable, in
         # GenericDispatch::BOOTSTRAP_CALLS_FALLBACK.
         def reference_to_impl(type, as: nil, optional: false)
@@ -108,8 +108,8 @@ module Hecks
           relationship_attribute(target, :belongs_to, as || Naming.snake(target).to_sym, optional: optional)
         end
 
-        # A PIECE is known by a field, not by a whole value object.
-        # `identified_by :sequence` names the SCALAR inside it, which is
+        # A piece is known by a field, not by a whole value object.
+        # `identified_by :sequence` names the scalar inside it, which is
         # what an id actually is — a LedgerEntry is entry 3, not entry
         # {"value":3}. `identified_by` itself is AttributeCollector's own
         # shared method (S9) — the two constructs cannot drift apart in
@@ -118,10 +118,10 @@ module Hecks
         # declare for the same reason a head may.
 
         # `from:` — see `AggregateBuilder#command`'s own comment; the
-        # SAME guard, checked against this PIECE's own lifecycle field
+        # same guard, checked against this piece's own lifecycle field
         # (S10, ADR 0025 — a piece's own state machine is checkable the
         # same way a head's is).
-        # RENAMED FROM `command`/`query`/`entity`/`lifecycle` (all below)
+        # Renamed from `command`/`query`/`entity`/`lifecycle` (all below)
         # — item #13's full metaprogrammed dispatch (slice 4c), same
         # reasoning as AggregateBuilder's own siblings: bootstrap-
         # reachable, in BOOTSTRAP_CALLS_FALLBACK.
@@ -133,14 +133,14 @@ module Hecks
           @pending_queries << [name, block]
         end
 
-        # S17, ADR 0026 — A PIECE NESTED INSIDE A PIECE. "A `Dispatch`
+        # S17, ADR 0026 — a piece nested inside a piece. "A `Dispatch`
         # [has] no life outside its `Handler`" (the ADR's own words) —
         # the same reason `Member` nests inside `ValueObject`, one level
         # further in. `owner_value_objects` passes straight through
         # unchanged, not re-derived from this entity's own attributes —
         # a piece mints no value objects of its own at any depth, so a
-        # NESTED piece's bare `identified_by :field` still resolves
-        # against the SAME root aggregate's value objects an outer
+        # nested piece's bare `identified_by :field` still resolves
+        # against the same root aggregate's value objects an outer
         # piece's already does (`AggregateBuilder#entity`'s own comment
         # names this pool ; there is exactly one of them, however deep
         # the nesting goes).
@@ -152,15 +152,15 @@ module Hecks
           @lifecycle = LifecycleBuilder.build(field, default: default, &)
         end
 
-        # A PRECONDITION SHARED ACROSS THIS PIECE'S OWN COMMANDS, DECLARED
-        # ONCE — the same move `AggregateBuilder#given` already makes,
+        # A precondition shared across this piece's own commands, declared
+        # once — the same move `AggregateBuilder#given` already makes,
         # one level down. Real, live redundancy this closes: banking's
         # own `LedgerEntry.Amend`/`LedgerEntry.Reverse` each repeated
         # `given("customer is active") { parent.customer.status ==
         # "active" }` and `given("account is open") { parent.status ==
         # "open" }`, byte for byte, because a piece had no way to declare
-        # either once and reference it back — only the AGGREGATE could.
-        # DECLARE BEFORE THE COMMANDS THAT REFERENCE IT, the same
+        # either once and reference it back — only the aggregate could.
+        # Declare before the commands that reference it, the same
         # ordering `AggregateBuilder#given`'s own comment names — though
         # since ADR 0028, `command` only queues a descriptor and actually
         # builds at `#drain_pending!` time, well after this whole block
@@ -168,36 +168,36 @@ module Hecks
         # order within the block no longer actually matters here; named
         # for the reader anyway, since `given`'s own resolution logic
         # (`CommandBuilder#reference_named_given`) still reads whatever
-        # `@named_givens` holds AT THE COMMAND'S OWN BUILD TIME, not by
+        # `@named_givens` holds at the command's own build time, not by
         # magic.
-        # RENAMED FROM `given` — item #13's full metaprogrammed dispatch
+        # Renamed from `given` — item #13's full metaprogrammed dispatch
         # (slice 4b), same reasoning as reference_to_impl above.
         #
-        # BARE — NO BLOCK — REFERENCES ANOTHER PIECE'S OWN DECLARATION,
-        # ANYWHERE IN THE CHAPTER, not just a sibling under this same
+        # Bare — no block — references another piece's own declaration,
+        # anywhere in the chapter, not just a sibling under this same
         # aggregate — one level wider than round 4's own cross-entity
         # sharing, mirroring `AggregateBuilder#given_impl`'s own
         # chapter-wide shape exactly one level down. Real, live corpus
         # this closes: `Account::LedgerEntry` and `SafeDepositBox::Visit`
-        # — two pieces under two DIFFERENT aggregates — independently
+        # — two pieces under two different aggregates — independently
         # typed `given("customer is active") { parent.customer.status ==
         # "active" }` byte for byte; neither the aggregate-level chapter
-        # pool (a DIFFERENT canonical — bare `customer.status`, the
+        # pool (a different canonical — bare `customer.status`, the
         # wrong scope for a piece's own command) nor the existing
         # same-aggregate cross-entity pool (`@owner_named_givens`, scoped
-        # to ONE aggregate's own entity tree) could reach across the
+        # to one aggregate's own entity tree) could reach across the
         # aggregate boundary. Resolved against `@chapter_entity_named_
         # givens`, keyed "AggregateName.EntityName" — see
         # `#reference_named_chapter_entity_given`'s own comment for the
         # algorithm and `docs/implemented/resolution-rules/
         # chapter-entity-given.md` for the full write-up.
         #
-        # `declared_by:` is a PLAIN STRING ("Account.LedgerEntry"), not a
+        # `declared_by:` is a plain string ("Account.LedgerEntry"), not a
         # constant — unlike `AggregateBuilder#given_impl`'s own
         # `declared_by:`, which names a real aggregate constant. A piece
         # has no first-class, independently-addressable reference
         # anywhere in this language (only its owning aggregate does);
-        # inventing one to make this ONE argument spelling symmetrical
+        # inventing one to make this one argument spelling symmetrical
         # with the aggregate-level word is a real, separate, unscoped
         # feature this fix does not need — ships textual now, the same
         # way `admits:` shipped textual before its own constant-bridge
@@ -209,40 +209,40 @@ module Hecks
           named = build_rule(Given, description, predicate, owner_name: @name, word: "given",
                               extraction_failure: "its source could not be read, so no other runtime could ever evaluate it")
           @named_givens[description] = named
-          # WRITE-THROUGH, first-declared-wins (`||=`) — a SECOND piece
+          # Write-through, first-declared-wins (`||=`) — a second piece
           # under the same aggregate independently declaring the exact
           # same description stays purely local to itself (no silent
           # overwrite of whatever the first piece already shared;
           # real, live case a fuzzer or a future codemod could easily
-          # surface: two pieces phrasing an UNRELATED rule identically
+          # surface: two pieces phrasing an unrelated rule identically
           # by coincidence, same as an aggregate-level given already
           # tolerates today).
           @owner_named_givens[description] ||= named
-          # WRITE-THROUGH, PER OWNER — the chapter-wide analogue of the
+          # **Write-through, per owner** — the chapter-wide analogue of the
           # line above, keyed by [description, this piece's own dotted
           # "Aggregate.Entity" name] rather than description alone, the
           # identical reasoning `AggregateBuilder#given_impl`'s own
-          # chapter write-through gives: two DIFFERENT pieces (anywhere
-          # in the chapter) independently declaring the SAME description
-          # are two DISTINCT candidates a later bare reference chooses
+          # chapter write-through gives: two different pieces (anywhere
+          # in the chapter) independently declaring the same description
+          # are two distinct candidates a later bare reference chooses
           # between (via `declared_by:` once there is more than one),
           # never silently merged into one slot.
           @chapter_entity_named_givens[description] ||= {}
           @chapter_entity_named_givens[description]["#{@aggregate_name}.#{@name}"] ||= named
         end
 
-        # A PIECE'S OWN SHAPE RULE (S10, ADR 0025's own "Rules" shape,
+        # A piece's own shape rule (S10, ADR 0025's own "Rules" shape,
         # one level down from `ValueObjectBuilder#invariant`, whose
         # extraction/error pattern this mirrors) — checked against
-        # EVERY INSTANCE of this piece the aggregate holds, not once
+        # every instance of this piece the aggregate holds, not once
         # against the aggregate's own flat state
         # (`Admissibility#enforce_invariants`'s own recursive walk).
         # No reference-by-name form (unlike `given`) — no known corpus
-        # need for a piece's own invariant to be shared with a SIBLING
+        # need for a piece's own invariant to be shared with a sibling
         # piece yet; if that need shows up, it is `given`'s own
         # cross-entity write-through pattern to extend, not a reason to
         # invent a second one here speculatively.
-        # RENAMED FROM `invariant` — item #13's full metaprogrammed
+        # Renamed from `invariant` — item #13's full metaprogrammed
         # dispatch (slice 4b), same reasoning as given_impl above.
         def invariant_impl(description, &predicate)
           @invariants << build_rule(Invariant, description, predicate, owner_name: @name, word: "invariant",
@@ -283,25 +283,25 @@ module Hecks
 
         private
 
-        # PRIMITIVE 2 (RuleReference#resolve_owner_keyed) — the CHAPTER-
-        # WIDE, ENTITY-SCOPED analogue of `AggregateBuilder#
+        # Primitive 2 (RuleReference#resolve_owner_keyed) — the chapter-
+        # wide, entity-scoped analogue of `AggregateBuilder#
         # reference_named_chapter_given`; the three branches below are
-        # this construct's OWN refusal wording, not shared, matching that
+        # this construct's own refusal wording, not shared, matching that
         # method's own precedent (`declared_by:` only exists on `given`
-        # so far, at either scope). UNRESOLVED is deferred, not raised
+        # so far, at either scope). Unresolved is deferred, not raised
         # here — see `#pending_chapter_entity_given`, below.
         #
-        # WRITES THROUGH TO `@owner_named_givens` TOO — not just
+        # **Writes through to `@owner_named_givens` too** — not just
         # `@named_givens` — or this piece resolving a description via the
-        # WIDER, chapter pool would leave the NARROWER, same-aggregate
+        # wider, chapter pool would leave the narrower, same-aggregate
         # pool (`EntityBuilder#given_impl`'s own block-form write-through)
-        # never populated for this description, breaking any SIBLING
+        # never populated for this description, breaking any sibling
         # piece's existing command-level bare reference
         # (`CommandBuilder#reference_named_given`) that depends on it —
         # real, live corpus: `SafeDepositBox::KeyIssuance.Return`'s own
         # bare `given("customer is active")` resolves through
         # `@owner_named_givens`, populated by `Visit`'s declaration
-        # whether `Visit` types the predicate itself OR (now) references
+        # whether `Visit` types the predicate itself or (now) references
         # `Account::LedgerEntry`'s instead — this write keeps that
         # working unchanged either way, `||=` so nothing here overrides
         # an actual local declaration if one is ever added later.
@@ -329,10 +329,10 @@ module Hecks
           @owner_named_givens[description] ||= named
         end
 
-        # A CHAPTER MAY BE SPLIT ACROSS FILES — the identical reason
+        # A chapter may be split across files — the identical reason
         # `AggregateBuilder#pending_chapter_given` defers rather than
         # raising the moment a bare reference outruns what's loaded so
-        # far. Hands back a PLACEHOLDER `Given`, embedded by Ruby object
+        # far. Hands back a placeholder `Given`, embedded by Ruby object
         # reference in this piece's own `preconditions`, and queues the
         # request in `@chapter_entity_pending_givens` —
         # `BluebookBuilder#resolve_pending_chapter_entity_givens!`
@@ -344,22 +344,22 @@ module Hecks
           placeholder
         end
 
-        # A PIECE'S OWN `one_of` LANDS ON ITS AGGREGATE. A type-position
+        # A piece's own `one_of` lands on its aggregate. A type-position
         # `one_of("never_moved", "moved")` on an entity attribute
         # synthesizes a closed-set value object — and until this, that
-        # object was built and then DROPPED: `Entity.declare` carries no
+        # object was built and then dropped: `Entity.declare` carries no
         # value objects, so the synthesized set existed nowhere in the
         # finished graph. The attribute stayed typed "Moved" with nothing
         # to resolve it: runtime admission had no closed set to enforce
         # (the one_of was decorative), and the fuzzer's ValueGenerator
         # crashed every run on the first domain to declare one — a chess
         # King/Rook's own castling flag — with `does not know primitive
-        # type "Moved"`. Installed through the SAME hook an entity's own
+        # type "Moved"`. Installed through the same hook an entity's own
         # identity value object already rides to the aggregate
         # (`identity_value_object_installer`, threaded unchanged through
         # nested pieces). Two sibling pieces synthesizing the same set
-        # (King's and Rook's own `moved`) install it once; the same NAME
-        # with a DIFFERENT member list is refused as the collision it is,
+        # (King's and Rook's own `moved`) install it once; the same name
+        # with a different member list is refused as the collision it is,
         # never first-wins silently.
         def install_closed_sets!
           return unless @identity_value_object_installer
@@ -435,7 +435,7 @@ module Hecks
 
         # `identified_by`'s own resolution pool (AttributeCollector#resolve_
         # pending_identity!'s hook, S9) — a piece mints no value objects of
-        # its own, so a bare field's own type resolves against its OWNER
+        # its own, so a bare field's own type resolves against its owner
         # aggregate's, passed in at declaration (`AggregateBuilder#entity`).
         def identity_pool = @owner_value_objects