hecks 1.4.0 → 1.5.0

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

@@ -135,6 +135,47 @@ module Hecks
           bluebook_ir.add_port(built)
         end
 
+        # 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

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

@@ -23,6 +23,9 @@ module Hecks
       # against: AggregateBuilder's own `@value_objects + closed_sets`,
       # 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?

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

@@ -13,10 +13,13 @@ 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
 
+        # 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
@@ -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
 
+        # 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,
-        # which is what every policy did before this existed.
+        # 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
@@ -53,21 +61,28 @@ module Hecks
         # 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
         # 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,17 +95,28 @@ module Hecks
           @projection_declared = !with.nil?
         end
 
+        # 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:` since it gained the named flag — the generic single-fill
-        # coercion takes no keyword arguments.
+        # `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
 
+        # 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
@@ -105,6 +131,12 @@ module Hecks
         # 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)
 
@@ -129,6 +161,10 @@ 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,
@@ -142,6 +178,11 @@ module Hecks
           ).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

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

@@ -16,11 +16,14 @@ module Hecks
 
         include WordGate
 
+        # @param name [String] the process manager's own name, as written after `process_manager`
         def initialize(name)
           @name     = name
           @handlers = []
         end
 
+        # Records the event that begins a fresh instance of this process manager.
+        #
         # `starts_on Transfer::TransferRequested` — bare constant
         # accepted (ADR 0025, S6 — "events first-class"), resolved
         # through `ConstShim` the same way `on_impl`/`transition_impl`
@@ -31,11 +34,21 @@ module Hecks
         # a "." qualified one). A plain String still passes through
         # unchanged, both for `shadow_parse` and for any corpus site a
         # future pass hasn't migrated yet.
+        #
+        # @param event_ref [Symbol, String, Module] the event, as a bare constant (a
+        #   `ScopedConstant` module `ConstShim` resolves) or quoted text
+        # @return [void]
         def starts_on_impl(event_ref)
           @starts_on = Naming.event_name_ref(event_ref)
         end
 
+        # Records the event this process manager expects to close out its instance on.
+        #
         # `ends_on` — same reasoning as `starts_on_impl`, above.
+        #
+        # @param event_ref [Symbol, String, Module] the event, as a bare constant (a
+        #   `ScopedConstant` module `ConstShim` resolves) or quoted text
+        # @return [void]
         def ends_on_impl(event_ref)
           @ends_on = Naming.event_name_ref(event_ref)
         end
@@ -45,15 +58,18 @@ module Hecks
         # kind-driven coerce-and-assign with nothing else, executed by
         # `GenericDispatch`.
         #
-        # `starts_on`/`ends_on` used to be table-driven the same way,
-        # until ADR 0025 S6 gave each a second, `kind: "constant"`
-        # ArgumentSeed row (`starts_on Transfer::TransferRequested`) —
-        # `GenericDispatch::COERCE_BY_KIND` only knows `"text"`/
-        # `"symbol"`, and `shape_for` refuses to pick a `single_fill`
-        # shape at all once two Argument rows share a `fills:` target
-        # (`arguments.size == 1` below), so both words are hand-written
-        # again, `calls:`-routed like `transition` already is.
-
+        # `starts_on`/`ends_on` are hand-written rather than table-driven
+        # the same way, because ADR 0025 S6 gives each a second,
+        # `kind: "constant"` ArgumentSeed row (`starts_on
+        # Transfer::TransferRequested`) — `GenericDispatch::COERCE_BY_KIND`
+        # only knows `"text"`/`"symbol"`, and `shape_for` refuses to pick a
+        # `single_fill` shape at all once two Argument rows share a
+        # `fills:` target (`arguments.size == 1` below), so both words are
+        # `calls:`-routed like `transition` already is.
+
+        # Records one leg of this process manager's state machine: the event that takes it, the
+        # state(s) it applies from, and the dispatches (and optional compensation) it fires.
+        #
         # One state-machine vocabulary (S7, ADR 0025 — "events and
         # reactions"): the same word `Lifecycle#transition` already
         # carries, one level over — `transition "AccountDebited" =>
@@ -89,10 +105,18 @@ module Hecks
         # persistence/rehydration) needs no change at all: what changed
         # is how the declaration reaches that same shape, not the shape
         # a real run ever sees or persists.
-        # Renamed from `transition` — item #13's full metaprogrammed
-        # dispatch (slice 4c). Not bootstrap-reachable (checked
-        # directly — no core/attached chapter declares a ProcessManager
-        # of its own).
+        # Reached through `calls: "transition_impl"`. Not exercised during boot itself — checked
+        # directly, no core/attached chapter declares a `ProcessManager` of its own — though the
+        # (context, word) pair is still carried in `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK`
+        # unconditionally, along with every other `calls:`-routed row.
+        #
+        # @param mapping [Hash] one `event => target_state` pair plus a required `from:` key
+        #   naming the source state(s) (`String`, `Symbol`, or `Array<String, Symbol>`) this
+        #   transition applies from
+        # @yield the transition's dispatch body, `instance_eval`'d against a fresh `HandlerBuilder`
+        # @return [void]
+        # @raise [Bluebook::DSL::ProcessManagerBuilder::InvalidProcessManager] if `mapping` names
+        #   no `from:`
         def transition_impl(mapping, &block)
           mapping = mapping.dup
           from    = mapping.delete(:from)
@@ -142,6 +166,14 @@ module Hecks
           end
         end
 
+        # Assembles the declared transitions into a `ProcessManager`, after validating them.
+        #
+        # @return [Bluebook::ProcessManager] the built process manager, with its own `states`
+        #   derived from the declared transitions
+        # @raise [Bluebook::DSL::ProcessManagerBuilder::InvalidProcessManager] if `correlates_by`
+        #   is undeclared or names a whole field rather than one scalar, if `starts_on` is
+        #   undeclared, if no transition was declared, or if two transitions answer the same event
+        #   from the same source state
         def build
           validate!
 
@@ -155,6 +187,13 @@ module Hecks
           )
         end
 
+        # Evaluates a `process_manager` block against a fresh builder and returns what it built.
+        #
+        # @param name [String] the process manager's own name
+        # @yield the process manager's body, `instance_eval`'d against a new builder; may be
+        #   omitted
+        # @return [Bluebook::ProcessManager] the built process manager
+        # @raise [Bluebook::DSL::ProcessManagerBuilder::InvalidProcessManager] see `#build`
         def self.build(name, &block)
           builder = new(name)
           builder.instance_eval(&block) if block
@@ -264,16 +303,19 @@ module Hecks
 
           include WordGate
 
+          # Starts this handler's own dispatch list empty.
           def initialize = @dispatches = []
 
+          # Records one command this transition dispatches, and, if given a block, the
+          # compensation that reverses it.
+          #
           # The command itself (ADR 0025, "events and reactions" — command
           # references become first-class), same shape and same reasons
           # as `PolicyBuilder#trigger`'s own header — bare constant live,
           # quoted text only under shadow-parsing (S0a's bridge; frozen
           # era text still writes `dispatch "Banking::Account.Debit"`).
           #
-          # Renamed from `dispatch` — item #13's full metaprogrammed
-          # dispatch (slice 4), same reasoning as trigger_impl above.
+          # Reached through `calls: "dispatch_impl"`.
           #
           # An optional block opens `compensates` on this dispatch
           # specifically — per-dispatch saga compensation, replacing a
@@ -287,6 +329,17 @@ module Hecks
           # (`SagaInterpreter`'s own `completed_compensations`) and
           # compensates only those, newest first, instead of trusting an
           # author's static list to be complete and correctly ordered.
+          #
+          # @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 onto the command's own
+          #   arguments, the same `key => value` shape a policy's own `trigger ..., with:` takes;
+          #   `nil` forwards the triggering context verbatim
+          # @yield the dispatch's own `compensates` body, `instance_eval`'d against a
+          #   `DispatchBuilder`
+          # @return [Bluebook::DispatchSpec] the dispatch just recorded
+          # @raise [Bluebook::DSL::ProcessManagerBuilder::InvalidProcessManager] if `command_ref`
+          #   is quoted text outside shadow-parsing
           def dispatch_impl(command_ref, with: nil, &block)
             if command_ref.is_a?(::String) && !MetaValidator.shadow_parsing?
               raise InvalidProcessManager,
@@ -330,6 +383,17 @@ module Hecks
 
             include WordGate
 
+            # Records the command that reverses the dispatch this `compensates` block sits inside.
+            #
+            # @param command_ref [Symbol, String, Module] the compensating command, as a bare
+            #   constant (a `ScopedConstant` module `ConstShim` resolves) or, under shadow-parsing,
+            #   quoted text
+            # @param with [Hash{Symbol => Object}, nil] a projection onto the command's own
+            #   arguments, the same shape `HandlerBuilder#dispatch_impl`'s own `with:` takes; `nil`
+            #   forwards the triggering context verbatim
+            # @return [Bluebook::DispatchSpec] the compensating dispatch just recorded
+            # @raise [Bluebook::DSL::ProcessManagerBuilder::InvalidProcessManager] if `command_ref`
+            #   is quoted text outside shadow-parsing
             def compensates_impl(command_ref, with: nil)
               if command_ref.is_a?(::String) && !MetaValidator.shadow_parsing?
                 raise InvalidProcessManager,

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

@@ -15,28 +15,48 @@ module Hecks
         include QuerySpecification::Common::DSL
         include WordGate
 
+        # @param name [String] the query's name, as written after `query`
         def initialize(name)
           @name   = name
           @wheres = []
         end
 
+        # Sets the human-readable description shown for this query.
+        #
+        # @param value [String] the description text
+        # @return [String] the description as stored
         def description(value) = @description = value
 
+        # Declares a query parameter that names another aggregate's identity.
+        #
         # A query parameter naming another aggregate's own identity
         # (Card.Active's own `Board`, filtering to one board's cards) —
         # just a plain attribute typed as a reference,
-        # AttributeCollector#attribute already handling an Reference
+        # `AttributeCollector#attribute_impl` already handling a Reference
         # exactly like any other. No "acts on itself" case to
         # distinguish here the way a command's own reference_to has —
         # a query has no root of its own to act on, only parameters.
-        # Renamed from `reference_to` — item #13's full metaprogrammed
-        # dispatch (slice 4b). Bootstrap-reachable, in
-        # GenericDispatch::BOOTSTRAP_CALLS_FALLBACK.
+        #
+        # 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`.
+        #
+        # @param type [Module, Symbol, String] the referenced aggregate, written as a bare
+        #   constant
+        # @param as [Symbol, nil] the parameter's name; nil derives it from the target
+        # @param optional [Boolean] whether the parameter may be omitted when the query runs
+        # @return [void]
+        # @raise [Bluebook::DSL::Malformed] if `as` (or the derived name) is already declared
         def reference_to_impl(type, as: nil, optional: false)
           target = Naming.demodulise(type)
           attribute_impl(as || default_reference_name(target), Reference.new(target), optional: optional)
         end
 
+        # Assembles the declared parameters and filtering into a `Query`.
+        #
+        # @return [Bluebook::Query] the built query
+        # @raise [Bluebook::DSL::Malformed] if the body declares `cursor`, which no interpreter
+        #   implements
         def build
           seal_cursor
           Query.new(
@@ -54,6 +74,15 @@ module Hecks
           )
         end
 
+        # Evaluates a `query` block against a fresh builder, then fills in owner-derived types.
+        #
+        # @param name [String] the query's name
+        # @param owner_attributes [Array<Bluebook::Attribute>] the enclosing aggregate or
+        #   entity's own attributes, matched against the block's own parameter names
+        # @yield the query body, evaluated with the builder as `self`; may be omitted
+        # @return [Bluebook::Query] the built query
+        # @raise [Bluebook::DSL::Malformed] if the body declares `cursor`, a duplicate attribute,
+        #   or a filtering clause the query language refuses
         def self.build(name, owner_attributes: [], &block)
           builder = new(name)
           builder.instance_eval(&block) if block