hecks 1.3.0 → 1.5.0

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

@@ -3,11 +3,11 @@ module Hecks
   module Bluebook
     module DSL
       # Parses a `.hecksagon` file's top-level DSL block into a `Hecksagon`
-      # — a domain's own WIRING: which adapter binds to which verb
+      # — a domain's own wiring: which adapter binds to which verb
       # (`persisted_by`, `projected_by`, ...), which framework/vendored
       # bluebooks it attaches, which external events it subscribes to, and
       # its bare chapter-root port. Kept separate from the bluebook itself
-      # (the domain's own declared MODEL) because wiring is an operational
+      # (the domain's own declared model) because wiring is an operational
       # decision, not a fact the domain states about itself.
       class HecksagonBuilder
         GRAMMAR_CONTEXT = "Hecksagon".freeze
@@ -20,6 +20,7 @@ module Hecks
 
         attr_reader :binds, :subscriptions, :framework_members, :vendored_bluebooks
 
+        # @param domain [String] name of the domain whose wiring this hecksagon declares
         def initialize(domain)
           @domain             = domain
           @binds              = []
@@ -28,44 +29,65 @@ module Hecks
           @vendored_bluebooks = []
         end
 
-        # An event this hecksagon takes from OUTSIDE the domain's own
-        # bluebook.
+        # Subscribes this hecksagon to an event it takes from outside the domain's own bluebook.
+        #
+        # @param event [String, Symbol] the external event's name
+        # @return [Array<String>] every subscription declared so far, this one last
         def subscribe(event) = @subscriptions << event.to_s
 
+        # Attaches a framework member to this domain and loads it into the current registry.
+        #
         # A framework/ member this domain wants attached —
         # Governance, Identity, whatever else lands beside them.
-        # Attaching one is a WIRING decision, the same kind `persisted_by`/
+        # Attaching one is a wiring decision, the same kind `persisted_by`/
         # `projected_by` already are, so it lives here rather than as a
-        # fact stated in the domain's own bluebook. Recorded onto THIS
+        # fact stated in the domain's own bluebook. Recorded onto this
         # hecksagon, the same way `subscribe` records onto its own
         # `subscriptions` — and loads the member's bluebook then its own
         # hecksagon into whatever registry this one is loading into, see
         # `Framework.load!`.
+        #
+        # @param name [String, Symbol] the member's name, such as `"Governance"`
+        # @return [Boolean, nil] true when this call loaded the member's bluebook, nil when the
+        #   current registry already held it
+        # @raise [Runtime::WiringError] if no framework member has that name
         def uses_framework(name)
           @framework_members << name.to_s
           Hecks::Framework.load!(name)
         end
 
-        # A VENDORED, EXTERNAL bluebook this domain wants attached — same
+        # Attaches a vendored embryonaut bluebook to this domain and loads its files into the
+        # current registry.
+        #
+        # A vendored, external bluebook this domain wants attached — same
         # wiring-decision shape `uses_framework` already is, one level
         # further out: not a member shipped inside hecks's own lib/,
-        # but a separate package (embryonaut_bluebooks) vendored into THIS
+        # but a separate package (embryonaut_bluebooks) vendored into this
         # project's own checkout. See EmbryonautBluebook's own header for
-        # the full reasoning on why its ROOT can't be a fixed constant the
+        # the full reasoning on why its root can't be a fixed constant the
         # way Framework::ROOT is, and for the recovery provenance.
         #
-        # RECORDED ONTO @vendored_bluebooks, same shape `uses_framework`
-        # already gives @framework_members — a SEPARATE list on purpose:
+        # Recorded onto @vendored_bluebooks, same shape `uses_framework`
+        # already gives @framework_members — a separate list on purpose:
         # `framework_members` is load-bearing for `refuse_ungoverned_roles!`
-        # (below) and for Governance's own attachment check; conflating
-        # the two would make a vendored bluebook attachment satisfy a
-        # Governance check it has nothing to do with.
+        # (`Registry::Verification`) and for Governance's own attachment
+        # check; conflating the two would make a vendored bluebook attachment
+        # satisfy a Governance check it has nothing to do with.
+        #
+        # @param name [String, Symbol] the vendored package's directory name under
+        #   `vendor/embryonaut_bluebooks/`
+        # @return [Array<String>, nil] paths of the `.bluebook` files this call loaded, or nil
+        #   when the current registry already held the bluebook
+        # @raise [Runtime::WiringError] if the current registry has no root to vendor from, or
+        #   no vendored bluebook of that name exists under it
         def uses_embryonaut_bluebook(name)
           @vendored_bluebooks << name.to_s
           Hecks::EmbryonautBluebook.load!(name)
         end
 
-        # THE PRIMARY PORT, BARE AT THE ROOT — belongs to the CHAPTER as a
+        # Declares a port at the hecksagon's root and attaches it to the registered bluebook.
+        #
+        # The primary port, bare at the root — belongs to the chapter as a
         # whole, not one aggregate. `BindingProxy#port` is the aggregate-
         # scoped sibling (`Payments::Payment.port("Gateway") do ... end`);
         # this is what's left when a port isn't about any one record. The
@@ -73,14 +95,24 @@ module Hecks
         # loads after its bluebook, and this attaches to that real, final
         # object directly rather than building a second copy MetaValidator
         # would have to know how to reconstruct.
-        # RENAMED FROM `port` — item #13's full metaprogrammed dispatch
-        # (slice 5). Not bootstrap-reachable (checked directly — no
-        # core/attached chapter declares a Hecksagon of its own). Reached
-        # through `WordGate#method_missing`'s new `word_gate_dispatch`,
-        # called explicitly below since `HecksagonBuilder`'s own
-        # class-level `method_missing` (the open-verb catch-all beneath
-        # this) always wins over the module's — see `word_gate.rb`'s own
-        # header for the full mechanism.
+        #
+        # Answers the `port` word through the table's `calls:` column —
+        # item #13's full metaprogrammed dispatch (slice 5). Not
+        # bootstrap-reachable (checked directly — no core/attached chapter
+        # declares a Hecksagon of its own). Reached through `WordGate`'s
+        # `word_gate_dispatch`, called explicitly below since
+        # `HecksagonBuilder`'s own class-level `method_missing` (the
+        # open-verb catch-all beneath this) always wins over the module's —
+        # see `word_gate.rb`'s own header for the full mechanism.
+        #
+        # @param name [String] the port's name
+        # @yield the port body, evaluated against a `DomainPortBuilder`: either `verb`/`signal`
+        #   or `operation`/`tells`/`asks` blocks
+        # @return [Bluebook::Port, Bluebook::DomainPort] the built port: a verb-shaped `Port`
+        #   registered on the current registry, or a `DomainPort` attached to the bluebook
+        # @raise [Bluebook::DSL::Malformed] if the current registry holds no bluebook for this
+        #   domain, or the body declares both a verb and operations, neither, or an operation
+        #   the port grammar refuses
         def port_impl(name, &block)
           bluebook_ir = Hecks.current_registry.bluebook(@domain) or
             raise Malformed, "#{@domain} declares no such bluebook — a port needs one to belong to"
@@ -103,26 +135,74 @@ module Hecks
           bluebook_ir.add_port(built)
         end
 
-        # NO ungoverned-role check here anymore — see
-        # Registry::Verification#refuse_ungoverned_roles!. Moved out of
-        # per-block `build`, recovered alongside `environment:`
+        # A TRANSLATION BOUNDARY, NOT A BUSINESS RULE — `translates "Name"
+        # do on Foreign::Domain::SomeEvent; trigger Local.Command; end`
+        # builds the EXACT SAME `Policy` a `policy` block inside this
+        # domain's own `.bluebook` would (same `on_impl`/`trigger_impl`,
+        # same `PolicyInterpreter` runtime — reusing `PolicyBuilder`
+        # directly, zero new runtime semantics). What's new is only WHERE
+        # it can be written: a cross-domain reaction is a wiring/context-
+        # mapping decision (this chapter conforming to a foreign chapter's
+        # published event), the same kind of decision `port`/
+        # `uses_framework` already are — not a fact this domain's own
+        # model states about itself, which `policy` (inside the bluebook)
+        # remains the right word for.
+        #
+        # MUST BE A BLOCK, not `translates Event, into: Command` — a flat
+        # call's arguments are evaluated eagerly, under THIS builder's own
+        # `ConstShim` resolver (`BindingProxy.namespace`, set up by
+        # `self.build` below), which mints a `BindingProxy` INSTANCE per
+        # segment and cannot answer a further `::` (it is not a Module) —
+        # a multi-segment reference like `Deploy::Tenant::TenantProvisioned`
+        # would raise before this method ever ran. `port_impl`'s own
+        # `ConstShim.with(->(const) { const })` swap only works because
+        # its own callers never pass a multi-segment bare constant as an
+        # eagerly-evaluated argument — everything of that shape lives
+        # inside ITS block, evaluated later, under the swapped resolver.
+        # A block defers evaluation the same way; a flat call cannot.
+        def translates(name, &block)
+          bluebook_ir = Hecks.current_registry.bluebook(@domain) or
+            raise Malformed, "#{@domain} declares no such bluebook — translates needs one to attach its reaction to"
+
+          # SAME RESOLVER BluebookBuilder ITSELF uses for a `policy`
+          # block's own `on`/`trigger` (bluebook_builder.rb) — a
+          # `ScopedConstant`, not the bare passthrough `port_impl` swaps
+          # to, because `on`/`trigger` here take genuinely multi-segment
+          # references (`Deploy::Tenant::TenantProvisioned`), not a
+          # single-segment type name.
+          resolver = ->(const) { ConstShim::ScopedConstant.for(const) }
+          built = ConstShim.with(resolver) { PolicyBuilder.build(name, &block) }
+
+          bluebook_ir.add_policy(built)
+        end
+
+        # Assembles the collected binds, subscriptions and attachments into a `Hecksagon`.
+        #
+        # No ungoverned-role check here — see
+        # Registry::Verification#refuse_ungoverned_roles!. It lives outside
+        # per-block `build`, alongside `environment:`
         # (Runtime::Loader.boot's comment has the provenance): a domain
         # split across multiple hecksagon blocks (base + an
         # `environments/<name>.hecksagon` overlay) would have every
         # block but the one declaring `uses_framework "Governance"`
-        # refused HERE, even though `Registry#add_hecksagon` merges them
+        # refused here, even though `Registry#add_hecksagon` merges them
         # into one Hecksagon before anything ever dispatches against it.
-        # Checking the MERGED result once, at verify! time — after every
+        # Checking the merged result once, at verify! time — after every
         # file for this domain has loaded — is both more permissive (no
         # need to repeat `uses_framework` in every file) and strictly
         # more correct (a check against an incomplete, not-yet-merged
         # hecksagon can never see the real final shape).
+        #
+        # @return [Bluebook::Hecksagon] this block's wiring, which `Registry#add_hecksagon` merges
+        #   with any other block declared for the same domain
         def build
           Hecksagon.new(domain: @domain, binds: @binds, subscriptions: @subscriptions,
                         framework_members: @framework_members, vendored_bluebooks: @vendored_bluebooks)
         end
 
-        # DOMAIN-LEVEL DEFAULT BINDS — `persisted_by "Heki"` bare, at the top
+        # Records any verb the grammar does not own as a domain-wide bind to the named adapter.
+        #
+        # **Domain-level default binds** — `persisted_by "Heki"` bare, at the top
         # of a hecksagon block, applies to every aggregate in this domain
         # that doesn't declare its own override. Mirrors `BindingProxy`'s own
         # `method_missing` one level down (`aggregate:` filled in there,
@@ -130,12 +210,22 @@ module Hecks
         # `persisted_by`/`projected_by` specifically, so any future verb
         # gets a domain-level default for free too. See `Hecksagon#bind_for`
         # for the fallback lookup this feeds.
+        #
+        # @param verb [Symbol] the word called, such as `:persisted_by`
+        # @param args [Array<Object>] positional arguments; the first names the adapter
+        # @param kwargs [Hash{Symbol => Object}] keyword arguments; `:role` is kept on the bind
+        # @yield an optional block, called once after the bind is recorded
+        # @return [Object] this builder after recording a bind, or the grammar word's own result
+        #   when `verb` is one the `Hecksagon` grammar admits
+        # @raise [NoMethodError] if `verb` is no grammar word and names no adapter
+        # @raise [Bluebook::DSL::Malformed] if the grammar admits `verb` only in another context,
+        #   or admits it here and its implementation refuses the declaration
         def method_missing(verb, *args, **kwargs, &block)
           # A closed-set grammar word (`port`, today) gets first refusal
           # — item #13's full metaprogrammed dispatch (slice 5); see
           # `WordGate#word_gate_dispatch`'s own header for why this class
           # needs to call it explicitly rather than including it the
-          # ordinary way. Only once THAT says "not admitted" does the
+          # ordinary way. Only once that says "not admitted" does the
           # genuinely open-ended `persisted_by "Heki"`-style bind
           # vocabulary below get a turn.
           result = word_gate_dispatch(verb, args, kwargs, block)
@@ -150,6 +240,16 @@ module Hecks
 
         def respond_to_missing?(_name, _include_private = false) = true
 
+        # Evaluates a `Hecks.hecksagon` block with bare `Domain::Aggregate` constants resolving to
+        # bind-collecting proxies, and returns the wiring it declared.
+        #
+        # @param domain [String] name of the domain being wired
+        # @yield the hecksagon body, evaluated with the builder as `self`; may be omitted
+        # @return [Bluebook::Hecksagon] the declared wiring
+        # @raise [Bluebook::DSL::Malformed] if a `port` names no registered bluebook or aggregate,
+        #   or declares a shape the port grammar refuses
+        # @raise [Runtime::WiringError] if `uses_framework` or `uses_embryonaut_bluebook` names
+        #   something that cannot be found
         def self.build(domain, &block)
           builder  = new(domain)
           resolver = ->(name) { BindingProxy.namespace(name, builder.binds) }

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

@@ -1,28 +1,31 @@
 module Hecks
   module Bluebook
     module DSL
-      # `identified_by` — SHARED by AggregateBuilder and EntityBuilder
+      # `identified_by` — shared by AggregateBuilder and EntityBuilder
       # only (S9, ADR 0025 — "EntityBuilder's duplicate identified_by and
       # resolve_pending_identity! go"): a piece's own identity cannot
       # spell differently from its aggregate's, and until this slice it
       # was hand-duplicated onto both rather than shared.
       #
-      # A SEPARATE MODULE from AttributeCollector on purpose — every
+      # A separate module from AttributeCollector on purpose — every
       # `attribute()`-taking builder (Command, Query, PortOperation,
-      # ValueObject, ...) `include`s that one too, and none of THEM
+      # ValueObject, ...) `include`s that one too, and none of them
       # declares an identity of its own ; folding `identified_by` in
       # there made it answer for six builders that never earned the
       # word (`syntax_conformance_spec.rb` catches exactly this — a
       # builder answering a method the grammar never grants it).
       #
-      # Requires its includer to ALSO `include AttributeCollector`
+      # Requires its includer to also `include AttributeCollector`
       # (for `attributes`/`resolve_identity_field!`/`resolve_identity_
-      # type!`, still declared there since every includer of THAT
+      # type!`, still declared there since every includer of that
       # module needs them) and to supply `identity_pool` (private) —
       # the value-object list a bare field's own type resolves
       # against: AggregateBuilder's own `@value_objects + closed_sets`,
-      # or EntityBuilder's OWNER's, since a piece mints none of its own.
+      # or EntityBuilder's owner's, since a piece mints none of its own.
       module IdentityDeclaration
+        # Records which of the three live `identified_by` forms a builder declared, deferring
+        # resolution until build time.
+        #
         # There are three live forms, deliberately distinguishable at the
         # declaration site:
         #
@@ -33,12 +36,12 @@ module Hecks
         # One symbol is retired: it cannot say whether the author means a
         # value concept or a field-shaped database key. Frozen source still
         # reaches the old interpretation through `legacy_identified_by`.
-        # RENAMED FROM `identified_by` — item #13's full metaprogrammed
-        # dispatch (slice 4c), same shared-mixin shape `attribute_impl`
-        # already proved in slice 3: ONE renamed method, both Aggregate
-        # and Entity Keyword rows name it in `calls:`. Bootstrap-
-        # reachable (every self-hosted aggregate/entity declares an
-        # identity), so in BOOTSTRAP_CALLS_FALLBACK for both contexts.
+        # Both `AggregateBuilder` and `EntityBuilder` name this method in their Keyword rows'
+        # `calls:` column, so `GenericDispatch` forwards `identified_by` here unchanged, both
+        # after boot (reading the live grammar table) and during it
+        # (`GenericDispatch::BOOTSTRAP_CALLS_FALLBACK`, which carries every `calls:`-routed row
+        # unconditionally, not a hand-picked bootstrap-reachable subset — though this one is
+        # exercised during boot too, since every self-hosted aggregate/entity declares an identity).
         # Dispatches across the three live forms documented above (value-
         # object + block, single type target, single/compound field
         # target), each an early return that sets exactly one pending
@@ -46,6 +49,20 @@ module Hecks
         # with-nil semantics and the shared `@name`/`identity_pool`
         # threaded back out as parameters, for no gain beyond what the
         # three-forms comment above already documents.
+        #
+        # @param targets [Array<Symbol, Module>] zero or more identity targets: a value-object
+        #   type (a bareword, resolved by `ConstShim` to a `Module`), one or more attribute-name
+        #   symbols for a field or compound key, or empty when `definition` is given
+        # @param as [Symbol, nil] the field name to mint for a value-object-type target; not
+        #   accepted with a field or compound-key target
+        # @yield a bespoke value-object body, `instance_eval`'d by `ValueObjectBuilder.build` to
+        #   mint the identity's own anonymous value object
+        # @return [Array<Symbol>, Array<String>, nil] `targets` when a compound key is declared,
+        #   the resolved identity paths from `legacy_identified_by` in shadow-parsing mode, or
+        #   `nil` otherwise; callers reach this through `GenericDispatch`, which discards it
+        # @raise [Bluebook::DSL::Malformed] if `identified_by` was already called, combines a
+        #   block with targets, names no identity, mixes a value-object type with field names,
+        #   passes `as:` with a field or compound key, or the block declares no attributes
         # rubocop:disable-next Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
         def identified_by_impl(*targets, as: nil, &definition)
           return legacy_identified_by(*targets, as: as, &definition) if MetaValidator.shadow_parsing?
@@ -67,15 +84,15 @@ module Hecks
                   &definition
                 )
               rescue NameError => e
-                # A REMOVED SPELLING MUST REFUSE LOUDLY, not degrade into a raw
+                # A removed spelling must refuse loudly, not degrade into a raw
                 # Ruby error — the one contract `EraGuard.shadow_parse` leans
                 # on to know a normal parse genuinely could not read this text
                 # (only `Malformed` triggers its shadow-mode retry, era_guard.rb's
-                # own comment). The OLD `identified_by { name.value }` — a block
-                # whose text was NEVER CALLED, only extracted (legacy_
+                # own comment). The old `identified_by { name.value }` — a block
+                # whose text was never called, only extracted (legacy_
                 # identified_by, below) — is exactly this shape: read under the
-                # CURRENT grammar it is instead instance_eval'd as a value-object
-                # DEFINITION, and a bare identifier like `name` inside it resolves
+                # current grammar it is instead instance_eval'd as a value-object
+                # definition, and a bare identifier like `name` inside it resolves
                 # to nothing WordGate#method_missing recognizes, so Ruby itself
                 # raises NameError. Left uncaught, that NameError skipped
                 # shadow_parse's rescue entirely and reached callers as a raw
@@ -124,9 +141,9 @@ module Hecks
 
         private
 
-        # RESOLVES whichever of the three `identified_by` shapes is
+        # Resolves whichever of the three `identified_by` shapes is
         # pending, against `identity_pool` — the includer's own private
-        # hook. Called at BUILD time, not at `identified_by`'s own call
+        # hook. Called at build time, not at `identified_by`'s own call
         # time — see `AttributeCollector#resolve_identity_field!`'s own
         # comment on why.
         def resolve_pending_identity!
@@ -161,8 +178,8 @@ module Hecks
           raise Malformed, "#{@name} declares identified_by more than once"
         end
 
-        # LEGACY — the two removed spellings (a value object + as:, and the
-        # multi-line block), kept alive ONLY for `EraGuard.shadow_parse`
+        # Legacy — the two removed spellings (a value object + as:, and the
+        # multi-line block), kept alive only for `EraGuard.shadow_parse`
         # (S0a, ADR 0025) to still make sense of frozen era text that used
         # them; unreachable outside `MetaValidator.shadow_parsing?`.
         def legacy_identified_by(*targets, as:, &path)

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

@@ -12,16 +12,26 @@ module Hecks
 
         include WordGate
 
+        # @param field [Symbol, String] the attribute the state machine lives on, such as `:status`
+        # @param default [String, Symbol] the state a new record starts in
         def initialize(field, default:)
           @field       = field
           @default     = default
           @transitions = []
         end
 
-        # RENAMED FROM `transition` — item #13's full metaprogrammed
+        # Records one transition row per command in `mapping`, all sharing its `from:` guard.
+        #
+        # Answers the `transition` word, which the grammar table routes here
+        # through its `calls:` column — item #13's full metaprogrammed
         # dispatch (slice 4c). Bootstrap-reachable (syntax.bluebook's
         # own Keyword/Argument entities describe their `status`
-        # lifecycle with it), so in BOOTSTRAP_CALLS_FALLBACK.
+        # lifecycle with it), so in `BOOTSTRAP_CALLS_FALLBACK`.
+        #
+        # @param mapping [Hash{String, Symbol => String, Symbol, Array<String>}] command name to
+        #   target state, as in `"Purchase" => "sold"`; the optional `:from` key holds the
+        #   state, or Array of states, the transition applies from, and nil or absent means any
+        # @return [Hash] the command-to-target pairs just recorded, `:from` removed
         def transition_impl(mapping)
           mapping = mapping.dup
           from    = mapping.delete(:from)
@@ -34,11 +44,24 @@ module Hecks
           end
         end
 
+        # Assembles the declared transitions into a `Lifecycle`, refusing an ambiguous table.
+        #
+        # @return [Bluebook::Lifecycle] the state machine: its field, default and transitions
+        # @raise [Bluebook::DSL::Malformed] if two transitions for one command could both apply
+        #   from the same state (C5.3); skipped while shadow-parsing frozen era text
         def build
           refuse_ambiguity!
           Lifecycle.new(field: @field, default: @default, transitions: @transitions)
         end
 
+        # Evaluates a `lifecycle` block against a fresh builder and returns what it built.
+        #
+        # @param field [Symbol, String] the attribute the state machine lives on
+        # @param default [String, Symbol] the state a new record starts in
+        # @yield the lifecycle body of `transition` rows, evaluated with the builder as `self`
+        # @return [Bluebook::Lifecycle] the built state machine
+        # @raise [Bluebook::DSL::Malformed] if two transitions for one command overlap, or the
+        #   block uses a word the `Lifecycle` grammar does not admit
         def self.build(field, default:, &block)
           builder = new(field, default: default)
           builder.instance_eval(&block) if block
@@ -51,9 +74,9 @@ module Hecks
         # one command whose `from:` sets overlap (or where either has no
         # `from:` at all) were silently first-wins; refused where the state
         # machine can be read whole. Two transitions for one command from
-        # DISJOINT states are the legitimate shape (`match_transition`
+        # disjoint states are the legitimate shape (`match_transition`
         # picks by the current state) and stay. A `from:` naming a state
-        # nothing declares is NOT refused here: it is a reachability
+        # nothing declares is not refused here: it is a reachability
         # finding `bin/model_check` already reports (unreachable state,
         # dead transition), and a bluebook may declare it on purpose.
         def refuse_ambiguity!

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

@@ -13,14 +13,17 @@ module Hecks
 
         include WordGate
 
+        # @param name [String] the policy's own name, as given to `policy "Name" do ... end`
         def initialize(name)
           @name = name
         end
 
-        # `on Account::AccountFrozen` — A BARE CONSTANT ACCEPTED (ADR
+        # Records the event this policy reacts to.
+        #
+        # `on Account::AccountFrozen` — a bare constant accepted (ADR
         # 0025, S6 — "events first-class"), resolved through `ConstShim`
         # the same way `trigger`/`dispatch` already resolve a command
-        # reference (`Naming.event_ref`, that method's own header). NOT
+        # reference (`Naming.event_ref`, that method's own header). Not
         # a required spelling yet, unlike `trigger`'s own quoted-text
         # refusal — see `policy.bluebook`'s own KeywordSeed comment for
         # why: event names aren't 100% migrated across the live corpus
@@ -28,17 +31,22 @@ module Hecks
         # AccountFrozen"` (quoted) and `on Account::AccountFrozen`
         # (bare) stay admitted until a full migration lands.
         #
-        # RENAMED FROM the generic single-fill coercion — item #13's
-        # full metaprogrammed dispatch, slice 1 (whole-project
-        # table-unification survey), now overridden here the same way
-        # `trigger_impl` overrides its own generic default.
+        # Reached through `calls: "on_impl"` rather than `GenericDispatch`'s generic single-fill
+        # coercion, the same way `trigger_impl` below overrides its own generic default — `on`
+        # admits both a bare constant and quoted text, not one single argument kind.
+        #
+        # @param event_ref [Symbol, String, Module] the event, as a bare constant (a
+        #   `ScopedConstant` module `ConstShim` resolves) or quoted text
+        # @return [void]
         def on_impl(event_ref)
           @on_event = Naming.event_ref(event_ref)
         end
 
-        # `with:` — WHAT THE TRIGGER IS GIVEN, when the event's own shape
-        # is not it. Omitted, the whole event payload forwards verbatim,
-        # which is what every policy did before this existed.
+        # Records the command this policy dispatches and, optionally, how the event's payload
+        # projects onto it.
+        #
+        # `with:` — what the trigger is given, when the event's own shape
+        # is not it. Omitted, the whole event payload forwards verbatim.
         #
         # Same `key => value` shape a saga's own `dispatch ..., with:`
         # takes, and read the same way at runtime: a Symbol names a field
@@ -46,28 +54,35 @@ module Hecks
         # supplies itself. The reason it exists is the reason a saga's
         # does — a reaction crosses an aggregate boundary, and the event
         # on one side is under no obligation to be shaped like the
-        # command on the other. Without it the target has to DECLARE
+        # command on the other. Without it the target has to declare
         # every field the event happens to carry, whether it reads them
         # or not.
-        # THE COMMAND ITSELF, NOT ITS NAME (ADR 0025, "events and
+        # The command itself, not its name (ADR 0025, "events and
         # reactions" — command references become first-class): `trigger
         # Account::Debit`, a bare constant `ConstShim` resolves the same
         # way `reference_to Account` always has, not a quoted verb string.
-        # Collapses the qualified/unqualified split this word and a
-        # saga's own `dispatch` used to disagree about — see
-        # `Naming.command_ref`'s own header for how the `::`/`.` rewrite
-        # works, and `SagaInterpreter#qualified` for why an unqualified
-        # form has always been enough (same-domain is the fallback, so
-        # `Account::Debit` and `Banking::Account::Debit` mean the same
-        # thing here).
+        # Matches the qualified-or-not shape a saga's own `dispatch`
+        # command name takes — see `Naming.command_ref`'s own header for
+        # how the `::`/`.` rewrite works, and `SagaInterpreter#qualified`
+        # for why an unqualified form is always enough (same-domain is
+        # the fallback, so `Account::Debit` and `Banking::Account::Debit`
+        # mean the same thing here).
         #
-        # LEGACY UNDER SHADOW-PARSING (S0a's own bridge) — frozen era
+        # Legacy under shadow-parsing (S0a's own bridge) — frozen era
         # text still writes the quoted form.
         #
-        # RENAMED FROM `trigger` — item #13's full metaprogrammed
-        # dispatch (slice 4), same reasoning as has_many_impl above: not
-        # bootstrap-reachable, reached through calls: with no fallback
-        # needed.
+        # `["Policy", "trigger"] => :trigger_impl` is in
+        # `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK`, which carries every `calls:`-routed row
+        # unconditionally — this one is also exercised during boot itself, since every
+        # self-hosted policy declares a trigger.
+        #
+        # @param command_ref [Symbol, String, Module] the command, as a bare constant (a
+        #   `ScopedConstant` module `ConstShim` resolves) or, under shadow-parsing, quoted text
+        # @param with [Hash{Symbol => Object}, nil] a projection from the triggering event's payload
+        #   onto the command's own arguments; a Symbol value names an event field, anything else is
+        #   a literal; `nil` forwards the whole event payload verbatim
+        # @return [void]
+        # @raise [Bluebook::DSL::Malformed] if `command_ref` is quoted text outside shadow-parsing
         def trigger_impl(command_ref, with: nil)
           if command_ref.is_a?(::String) && !MetaValidator.shadow_parsing?
             raise Malformed,
@@ -80,11 +95,30 @@ module Hecks
           @projection_declared = !with.nil?
         end
 
-        # `across` — item #13's full metaprogrammed dispatch, slice 1:
-        # same shape as `on`, above.
+        # Records the domain this policy's trigger reaches into.
+        #
+        # `across "Notifications"` names the domain a trigger reaches into.
+        # `expect_undelivered: true` declares that this domain expects that
+        # target never to be reached (no such domain, on purpose), which
+        # `ModelCheck` holds it to in both directions. Reached through
+        # `calls: "across_impl"` rather than the generic single-fill
+        # coercion, because `expect_undelivered:` is a keyword argument the
+        # generic coercion cannot take.
+        #
+        # @param domain [String, Symbol] the target domain's name
+        # @param expect_undelivered [Boolean] whether this domain expects `across`'s target to
+        #   name no real domain; `ModelCheck` holds it to that in both directions
+        # @return [void]
+        def across_impl(domain, expect_undelivered: false)
+          @target_domain = domain.to_s
+          @expect_undelivered = expect_undelivered == true
+        end
 
-        # THE GUARD — same extraction CommandBuilder#given/#ensures already
-        # use (Ports::Extraction reads the block's SOURCE ; the block itself
+        # Records the guard predicate that decides whether this policy applies to a triggering
+        # event.
+        #
+        # **The guard** — same extraction CommandBuilder#given/#ensures already
+        # use (Ports::Extraction reads the block's source ; the block itself
         # is never called, here or at runtime — Runtime::PolicyInterpreter
         # evaluates the extracted text through the same
         # Bluebook::Expression::Evaluator a command's own given/ensures run
@@ -94,9 +128,15 @@ module Hecks
         # this policy does not apply to this event, exactly like an
         # `event_qualifier` miss, which carries no message either.
         #
-        # Evaluated against the triggering EVENT's OWN PAYLOAD, not a
+        # Evaluated against the triggering event's own payload, not a
         # stored record — a policy reacts to what just happened, and has no
         # aggregate instance of its own to read state from.
+        #
+        # @yield the guard predicate, extracted as source text and evaluated later by
+        #   `Runtime::PolicyInterpreter` against the triggering event's payload; never called here
+        # @return [void]
+        # @raise [Bluebook::DSL::Malformed] if the block's source could not be extracted, or if it
+        #   references a pattern `Expression::AstJson.refuse_unshared_patterns!` does not share
         def where(&predicate)
           canonical = Ports::Extraction.canonical(predicate)
 
@@ -112,7 +152,7 @@ module Hecks
           @where = canonical
         end
 
-        # THE FAN-OUT SOURCE — a query verb, "Aggregate.query_name" or
+        # **The fan-out source** — a query verb, "Aggregate.query_name" or
         # "Domain::Aggregate.query_name", the same qualified-or-not shape a
         # saga's own `dispatch` command name already takes
         # (SagaInterpreter#qualified). Runtime::PolicyInterpreter runs the
@@ -121,18 +161,28 @@ module Hecks
         # `for_each` — item #13's full metaprogrammed dispatch, slice 1:
         # same shape as `on`, above.
 
+        # Builds the `Policy` this builder has accumulated.
+        #
+        # @return [Bluebook::Policy] the built policy, carrying every field set by `on`,
+        #   `trigger`, `across`, `where`, `for_each`, and `with:`
         def build
           Policy.new(
-            name:            @name,
-            on_event:        @on_event,
-            trigger_command: @trigger_command,
-            target_domain:   @target_domain,
-            where:           @where,
-            for_each:        @for_each,
-            with_spec:       @with_spec || []
+            name:               @name,
+            on_event:           @on_event,
+            trigger_command:    @trigger_command,
+            target_domain:      @target_domain,
+            expect_undelivered: @expect_undelivered || false,
+            where:              @where,
+            for_each:           @for_each,
+            with_spec:          @with_spec || []
           ).tap { |policy| policy.instance_variable_set(:@projection_declared, !!@projection_declared) }
         end
 
+        # Builds a `Policy` from a `policy "Name" do ... end` block.
+        #
+        # @param name [String] the policy's own name
+        # @yield the policy's body, `instance_eval`'d against a new builder
+        # @return [Bluebook::Policy] the built policy
         def self.build(name, &block)
           builder = new(name)
           builder.instance_eval(&block) if block