hecks 2.8.0 → 3.0.0

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

@@ -2,12 +2,8 @@ require_relative "word_gate"
 module Hecks
   module Bluebook
     module DSL
-      # Parses a `policy "Name" do ... end` block into a `Policy` — a
-      # reaction wired at chapter scope: `on` the event it watches, an
-      # optional `where` guard evaluated against the event's own payload, an
-      # optional `for_each` fan-out query, and the `trigger` command it
-      # dispatches (`with:` projecting the event's payload onto the
-      # command's own arguments when the two shapes differ).
+      # Parses a `policy "Name" do ... end` block into a `Policy`: the event it reacts to (`on`),
+      # an optional `where` guard, an optional `for_each` fan-out, and the `trigger` it dispatches.
       class PolicyBuilder
         GRAMMAR_CONTEXT = "Policy".freeze
 
@@ -20,20 +16,8 @@ module Hecks
 
         # 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
-        # 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
-        # the way command references are, so both `on "Account.
-        # AccountFrozen"` (quoted) and `on Account::AccountFrozen`
-        # (bare) stay admitted until a full migration lands.
-        #
-        # 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.
+        # Reached through `calls: "on_impl"` because `on` admits both a bare constant
+        # (`on Account::AccountFrozen`) 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
@@ -42,45 +26,16 @@ module Hecks
           @on_event = Naming.event_ref(event_ref)
         end
 
-        # 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
-        # on the triggering event, anything else is a literal the policy
-        # 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
-        # every field the event happens to carry, whether it reads them
-        # or not.
-        # 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.
-        # 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).
+        # Records the command this policy dispatches and how the event payload projects onto it.
         #
-        # Legacy under shadow-parsing (S0a's own bridge) — frozen era
-        # text still writes the quoted form.
+        # With `with:`, a Symbol value names a field on the triggering event and anything else is
+        # a literal. Omitted, the whole payload forwards.
+        # In `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK`.
         #
-        # `["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
+        # @param command_ref [Symbol, String, Module] the command, as a bare constant or, under
+        #   shadow-parsing, quoted text
+        # @param with [Hash{Symbol => Object}, nil] event payload to command arguments;
+        #   `nil` forwards the whole payload
         # @return [void]
         # @raise [Bluebook::DSL::Malformed] if `command_ref` is quoted text outside shadow-parsing
         def trigger_impl(command_ref, with: nil)
@@ -97,13 +52,8 @@ module Hecks
 
         # 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.
+        # `expect_undelivered: true` declares that the target is expected never to be reached
+        # (no such domain, on purpose); `ModelCheck` holds it to that in both directions.
         #
         # @param domain [String, Symbol] the target domain's name
         # @param expect_undelivered [Boolean] whether this domain expects `across`'s target to
@@ -117,20 +67,8 @@ module Hecks
         # 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
-        # through). No description argument the way given/ensures each
-        # carry one : a given's description becomes a GivenNotMet message,
-        # and a where that does not hold refuses nothing — it just means
-        # 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
-        # stored record — a policy reacts to what just happened, and has no
-        # aggregate instance of its own to read state from.
+        # The block's source is extracted and never called; a `where` that does not hold refuses
+        # nothing, so unlike `given` it takes no description. It sees the event's payload only.
         #
         # @yield the guard predicate, extracted as source text and evaluated later by
         #   `Runtime::PolicyInterpreter` against the triggering event's payload; never called here
@@ -147,22 +85,12 @@ module Hecks
                   "could not be read, so no other runtime could ever evaluate it"
           end
 
-          # C3.6 — the same PatternSubset check every rule site gets.
           ast = Expression::AstJson.emit_predicate(canonical)
           Expression::AstJson.refuse_unshared_patterns!(ast, owner: @name, word: "where")
           Expression::AstJson.refuse_unresolvable_lookups!(ast, owner: @name, word: "where")
           @where = canonical
         end
 
-        # **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
-        # named query against the triggering event's own payload and fires
-        # `trigger` once per row, instead of once for the event.
-        # `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`,

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

@@ -38,12 +38,8 @@ module Hecks
 
         # 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.
+        # Repeatable, like `AdapterBuilder#field`; `verify!` checks each name with `respond_to?`
+        # at boot so a dispatch never meets a bare `NoMethodError`.
         #
         # @param name [Symbol, String] the method name, such as `:ask`
         # @return [Array<Symbol>] every method declared so far, this one last

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

@@ -2,40 +2,17 @@ require_relative "word_gate"
 module Hecks
   module Bluebook
     module DSL
-      # Parses one `operation`/`tells`/`asks` block inside a `domain_port`
-      # into a `PortOperation` — its own attributes (the external fact's
-      # payload) plus either the events it `emits` (inbound) or the
-      # `answers`/`refuses` pair naming its two possible outcomes (outbound).
-      # `to:` records which aggregate the operation routes to as dispatch
-      # metadata, never as an attribute — see `to:`'s own comment below.
+      # Parses one `operation`/`tells`/`asks` block into a `PortOperation`: its attributes plus
+      # either the events it `emits` (inbound) or its `answers`/`refuses` pair (outbound).
       class PortOperationBuilder
         GRAMMAR_CONTEXT = "PortOperation".freeze
 
         include AttributeCollector
         include WordGate
 
-        # `to:` — the sanctioned replacement for `reference_to` inside an
-        # operation body: `reference_to_impl`'s own refusal message tells
-        # authors to "pass the receiving aggregate in to:", and this is
-        # the argument DomainPort's own grammar (domain_port.bluebook)
-        # gives operation/tells/asks to receive it.
-        #
-        # **Genuine routing metadata, not an attribute** — matching
-        # rust/parser/src/parse/domain_port.rs's own header comment ("The
-        # receiving aggregate is routing metadata supplied by to:, not an
-        # operation attribute"), which anticipated this shape before either
-        # side actually built it. Stored separately (below, threaded to
-        # PortOperation as `to:`) rather than reusing reference_to_impl's
-        # own attribute-adding path — Dispatcher#port_invocation
-        # (lib/hecks/runtime/dispatcher.rb) is the one place that resolves
-        # routing at dispatch time; it gained a second, purely additive
-        # branch for this (falls back to a plain attribute named for the
-        # owning aggregate's own identified_by field, the same "declare
-        # only external facts with attribute" the refusal message
-        # describes) rather than folding `to:` into identity_attribute's
-        # existing Reference-attribute scan, which every operation already
-        # in the corpus (Banking, pizzas, a client site's own vendored
-        # PaymentGateway) still relies on unchanged.
+        # `to:` is the sanctioned replacement for `reference_to` inside an operation body —
+        # genuine routing metadata, not an attribute, resolved at dispatch time by
+        # `Dispatcher#port_invocation` rather than folded into the ordinary attribute scan.
         #
         # @param name [String] the operation's name
         # @param to [Symbol, String, Module, nil] the aggregate the operation routes to; stored
@@ -50,33 +27,13 @@ module Hecks
           @emits     = []
         end
 
-        # Refuses `reference_to` inside an operation body, except while shadow-parsing, where it
-        # adds the reference attribute frozen era text declared.
-        #
-        # Always an attribute, never the self-reference `CommandBuilder`
-        # spells — a port operation has no `creates?`/`acts_on` distinction
-        # to protect, so there is nothing for the self-reference branch to be
-        # for here. `reference_to Payment, as: :payment_id` reads the same
-        # even though the target happens to equal the owning aggregate.
-        # Answers the `reference_to` word through the table's `calls:`
-        # column — item #13's full metaprogrammed dispatch (slice 4b).
-        # Bootstrap-reachable, in `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK`.
-        #
-        # Disabled, #335 — kept only for MetaValidator's own shadow-parsing
-        # pass (the self-hosted grammar's own KeywordSeed/ArgumentSeed rows
-        # for "reference_to" in this context are themselves declared using
-        # this construct, one level up — deleting the Ruby method would
-        # break the language describing itself, not just old domain
-        # authors). Every real domain author reaches `to:` instead, above —
-        # a genuinely different mechanism now, not a relocated spelling of
-        # this one (see `to:`'s own comment).
+        # Refuses `reference_to` inside an operation body; a port operation has no self-reference
+        # to protect the way `CommandBuilder`'s does. Kept only for MetaValidator's own
+        # shadow-parsing pass, which still declares itself using this construct — every real
+        # domain author reaches `to:` instead (see its own comment above).
         #
-        # @param type [Symbol, String, Module] the referenced aggregate, written as a bare constant
-        # @param as [Symbol, nil] the attribute's name; nil derives it from the target, as in
-        #   `:payment_id` under shadow-parsing
-        # @return [nil] nothing useful; the reference lands in `attributes`
-        # @raise [Bluebook::DSL::Malformed] always outside shadow-parsing, since routing belongs
-        #   in `to:`; under shadow-parsing, if the attribute name is already declared
+        # @raise [Bluebook::DSL::Malformed] always outside shadow-parsing; under shadow-parsing,
+        #   if the attribute name is already declared
         def reference_to_impl(type, as: nil)
           unless MetaValidator.shadow_parsing?
             raise Malformed,
@@ -88,25 +45,14 @@ module Hecks
         end
 
         # Names one event an inbound operation records once the external fact has arrived.
-        #
-        # @param event_name [String, Symbol] the event's name, such as `"PaymentSettled"`
-        # @return [Array<String>] every event named so far, this one last
         def emits(event_name) = @emits << event_name.to_s
 
-        # The two halves of an `asks`. An outbound call has exactly two
-        # endings and the chapter names both — `answers` for what came back,
-        # `refuses` for what the outside said instead. They are separate words
-        # rather than two `emits` because a reader has to be able to tell them
-        # apart without reading the adapter: one is the thing you wanted, the
-        # other is the thing you have to handle.
-        # `answers`/`refuses` — item #13's full metaprogrammed dispatch,
-        # slice 1 (whole-project table-unification survey): both a bare,
-        # kind-driven coerce-and-assign with nothing else, now executed
-        # by `GenericDispatch`.
+        # `answers`/`refuses`, the two halves of an `asks` — separate words rather than two
+        # `emits` so a reader can tell what came back from what the outside refused, without
+        # reading the adapter.
 
         # Assembles the operation, refusing words that belong to the other direction.
         #
-        # @return [Bluebook::PortOperation] the operation with its attributes, events and routing
         # @raise [Bluebook::DSL::Malformed] if an inbound operation declares no `emits` or
         #   declares `answers`/`refuses`, or an outbound one declares `emits` or lacks either
         #   `answers` or `refuses`
@@ -119,9 +65,8 @@ module Hecks
             direction: @direction, answers: @answers, refuses: @refuses, to: @to
           )
 
-          # An inbound operation still has to say something. Only inbound: an
-          # `asks` says it with `answers`/`refuses` instead, and
-          # `refuse_wrong_words!` above has already insisted on both.
+          # Only inbound: an `asks` says it with `answers`/`refuses` instead, already enforced
+          # above.
           if !outbound && @emits.empty?
             raise Malformed,
                   "#{@name} declares no emits — an operation with nothing to say " \
@@ -133,21 +78,15 @@ module Hecks
 
         private
 
-        # The one place a reference attribute actually gets added — both
-        # `to:` (initialize, above) and reference_to_impl's own shadow-
-        # parsing branch call this, so there is exactly one real
-        # implementation of "carry a Reference-typed external fact,"
-        # not two that could drift.
+        # The one real implementation of "carry a Reference-typed external fact" — both `to:` and
+        # `reference_to_impl`'s shadow-parsing branch call this, so there is nothing to drift.
         def add_reference!(type, as: nil)
           target = Naming.demodulise(type)
           attribute_impl(as || default_reference_name(target), Reference.new(target))
         end
 
-        # **Each direction refuses the other's words**. `emits` on an `asks` looks
-        # right and is not: it would name one ending and leave the other
-        # nowhere. `answers` on a `tells` is worse — there is no channel back
-        # to an inbound caller at all, so it would read as a promise the
-        # runtime cannot keep.
+        # Each direction refuses the other's words: `emits` on an `asks` names one ending and
+        # leaves the other nowhere; `answers` on a `tells` promises a channel that never exists.
         def refuse_wrong_words!(outbound)
           if outbound
             unless @emits.empty?
@@ -170,21 +109,8 @@ module Hecks
           end
         end
 
-        # Evaluates one operation block against a fresh builder and returns what it built.
-        #
-        # `private` above (scoping the instance methods between it and here)
-        # doesn't reach a singleton method — correctly so: `.build` is this
-        # builder's real public entry point (DomainPortBuilder calls it),
-        # never meant to be private.
-        #
-        # @param name [String] the operation's name
-        # @param to [Symbol, String, Module, nil] the aggregate the operation routes to, or nil
-        # @param owner [String, nil] name of the aggregate the enclosing port is declared on
-        # @param direction [Symbol] `:inbound` for `operation`/`tells`, `:outbound` for `asks`
-        # @yield the operation body, evaluated with the builder as `self`; may be omitted
-        # @return [Bluebook::PortOperation] the built operation
-        # @raise [Bluebook::DSL::Malformed] if the body uses the other direction's words, omits
-        #   the ones its own direction requires, or uses a word the grammar does not admit
+        # Evaluates one operation block against a fresh builder and returns what it built;
+        # `private` above doesn't reach this singleton method, since `.build` is the real entry.
         # rubocop:disable-next Lint/IneffectiveAccessModifier
         def self.build(name, to: nil, owner: nil, direction: :inbound, &block)
           builder = new(name, to: to, owner: owner, direction: direction)