hecks 1.3.0 → 1.4.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,33 @@ 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:`
+        # 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 +169,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 +199,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,27 +1,27 @@
 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
         # There are three live forms, deliberately distinguishable at the
         # declaration site:
@@ -33,9 +33,9 @@ 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
+        # 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
+        # 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.
@@ -67,15 +67,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 +124,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 +161,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

@@ -17,10 +17,10 @@ module Hecks
           @name = name
         end
 
-        # `on Account::AccountFrozen` — A BARE CONSTANT ACCEPTED (ADR
+        # `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,7 +28,7 @@ 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
+        # 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.
@@ -36,7 +36,7 @@ module Hecks
           @on_event = Naming.event_ref(event_ref)
         end
 
-        # `with:` — WHAT THE TRIGGER IS GIVEN, when the event's own shape
+        # `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.
         #
@@ -46,10 +46,10 @@ 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.
@@ -61,10 +61,10 @@ module Hecks
         # `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
+        # 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.
@@ -80,11 +80,19 @@ module Hecks
           @projection_declared = !with.nil?
         end
 
-        # `across` — item #13's full metaprogrammed dispatch, slice 1:
-        # same shape as `on`, above.
+        # `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:` since it gained the named flag — the generic single-fill
+        # coercion takes no keyword arguments.
+        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
+        # **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,7 +102,7 @@ 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.
         def where(&predicate)
@@ -112,7 +120,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
@@ -123,13 +131,14 @@ module Hecks
 
         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
 

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

@@ -2,37 +2,68 @@ require_relative "word_gate"
 module Hecks
   module Bluebook
     module DSL
-      # Parses a top-level `.port` file's `Hecks.port "Name" do verb "x";
-      # signal :effect end` body into a `Port` — the adapter-facing shape (one
-      # verb, one signal, an optional method contract in `answers`) a domain
-      # calls OUT through, as opposed to `DomainPortBuilder`'s own inbound/
-      # outbound operations.
+      # Parses a `verb "x"; signal :effect` port body into a `Port` — the
+      # adapter-facing shape (one verb, one signal, an optional method
+      # contract in `answers`) a domain calls out through, as opposed to
+      # `DomainPortBuilder`'s own inbound/outbound operations.
+      #
+      # `Hecks.port` (lib/hecks.rb) parses a top-level `.port` file through
+      # `DomainPortBuilder`, whose bare-verb branch builds the identical
+      # `Port`; this builder is the reference shape `spec/dsl_spec.rb` holds
+      # that branch to.
       class PortBuilder
         GRAMMAR_CONTEXT = "Port".freeze
 
         include WordGate
 
+        # @param name [String] the port's name, as written after `Hecks.port`
         def initialize(name)
           @name    = name
           @signal  = :reply
           @answers = []
         end
 
+        # Names the verb a domain's aggregates call this port by when a hecksagon binds it.
+        #
+        # @param value [String, Symbol] the verb, such as `"asked_by"` or `"persisted_by"`
+        # @return [String] the verb as stored
         def verb(value)   = @verb = value.to_s
+
+        # Sets whether the domain waits for a value back; a port 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 — the fact a `.port` file's `verb`/`signal`
-        # never carried: what an adapter must actually RESPOND TO for a
+        # Declares one method an adapter bound to this port must respond to.
+        #
+        # **The method contract** — the fact a `.port` file's `verb`/`signal`
+        # never carried: what an adapter must actually respond to for a
         # dispatch to reach it without a bare `NoMethodError`. Declared the
         # same repeatable way `AdapterBuilder#field`/`#secret` already are,
         # so `verify!` can check it with `respond_to?` at boot instead of
         # the runtime discovering it live.
+        #
+        # @param name [Symbol, String] the method name, such as `:ask`
+        # @return [Array<Symbol>] every method declared so far, this one last
         def answers(name) = @answers << name.to_sym
 
+        # Assembles the collected verb, signal and method contract, judged by the port language.
+        #
+        # @return [Bluebook::Port] the port, returned once the language accepts it
+        # @raise [Bluebook::DSL::Malformed] if the port language refuses the declaration
         def build
           MetaValidator.call_port(Port.new(name: @name, verb: @verb, signal: @signal, answers: @answers))
         end
 
+        # Evaluates a port block against a fresh builder and returns what it built.
+        #
+        # @param name [String] the port's name
+        # @yield the port body, evaluated with the builder as `self`; may be omitted
+        # @return [Bluebook::Port] the judged port
+        # @raise [Bluebook::DSL::Malformed] if the port language refuses the declaration, or
+        #   the block uses a word the `Port` grammar does not admit
         def self.build(name, &block)
           builder = new(name)
           builder.instance_eval(&block) if block