hecks 0.2.0 → 0.3.0

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

@@ -0,0 +1,191 @@
+module Hecks
+  module Bluebook
+    module DSL
+      # `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
+      # `attribute()`-taking builder (Command, Query, PortOperation,
+      # 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`
+      # (for `attributes`/`resolve_identity_field!`/`resolve_identity_
+      # 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.
+      module IdentityDeclaration
+        # There are three live forms, deliberately distinguishable at the
+        # declaration site:
+        #
+        #   identified_by AccountNumber, as: :number # one identity concept
+        #   identified_by do ... end                 # a bespoke concept
+        #   identified_by :branch, :number           # an existing compound key
+        #
+        # 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.
+        def identified_by_impl(*targets, as: nil, &definition)
+          return legacy_identified_by(*targets, as: as, &definition) if MetaValidator.shadow_parsing?
+
+          refuse_second_identity!
+
+          if definition
+            raise Malformed,
+                  "#{@name}.identified_by cannot combine a value-object type with a block" unless targets.empty?
+
+            type_name = identity_value_object_name
+            value_object =
+              begin
+                ValueObjectBuilder.build(
+                  type_name,
+                  owner_value_objects: identity_pool,
+                  &definition
+                )
+              rescue NameError => error
+                # 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_
+                # 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
+                # 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
+                # crash instead of the frozen-era fallback that exists for
+                # precisely this text.
+                raise Malformed,
+                      "#{@name}.identified_by do ... end could not be read as a value-object " \
+                      "definition: #{error.message}"
+              end
+            if value_object.attributes.empty?
+              raise Malformed, "#{@name}.identified_by do declares no identity attributes"
+            end
+
+            install_identity_value_object!(value_object)
+            @identity_type_pending = [value_object, as || :identity, attributes.size]
+            return
+          end
+
+          raise Malformed, "#{@name}.identified_by names no identity" if targets.empty?
+
+          if targets.one? && identity_type?(targets.first)
+            @identity_type_pending = [targets.first, as, attributes.size]
+            return
+          end
+
+          if targets.one?
+            field = targets.first
+            raise Malformed,
+                  "#{@name}.identified_by takes no as: — name the declared field itself" if as
+            # Transitional compatibility: the self-hosted language and live
+            # corpus still contain this form. Keep it readable until their
+            # exemplar-led migration is complete; the final lifecycle cutover
+            # replaces this assignment with the targeted refusal.
+            @identity_field_pending = field
+            return
+          end
+
+          unless targets.all? { |target| !identity_type?(target) }
+            raise Malformed,
+                  "#{@name}.identified_by takes one value-object type or two or more attribute names, not both"
+          end
+          raise Malformed, "#{@name}.identified_by compound keys take no as:" if as
+
+          @identity_fields_pending = targets
+        end
+
+        private
+
+        # 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
+        # time — see `AttributeCollector#resolve_identity_field!`'s own
+        # comment on why.
+        def resolve_pending_identity!
+          if @identity_type_pending
+            type, as, insert_at = @identity_type_pending
+            @identity_paths = resolve_identity_type!(type, as, insert_at, identity_pool, @name)
+          elsif @identity_field_pending
+            @identity_paths = resolve_identity_field!(@identity_field_pending, identity_pool, @name)
+          elsif @identity_fields_pending
+            @identity_paths = @identity_fields_pending.flat_map do |field|
+              resolve_identity_field!(field, identity_pool, @name)
+            end
+          end
+        end
+
+        def identity_type?(target) = target.to_s.match?(/\A[A-Z]/)
+
+        def refuse_second_identity!
+          # During the staged migration a transitional one-symbol declaration
+          # may be replaced by the new declaration later in the same builder.
+          # This keeps existing builder fixtures/source readable while their
+          # exemplar is migrated. Once one-symbol identity is retired this
+          # compatibility branch disappears with it.
+          if @identity_field_pending && !@identity_type_pending && !@identity_fields_pending
+            @identity_field_pending = nil
+            return
+          end
+
+          return unless @identity_type_pending || @identity_field_pending || @identity_fields_pending ||
+                        (@identity_paths && !@identity_paths.empty?)
+
+          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`
+        # (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)
+          target = targets.first
+          if target
+            raise Malformed, "#{@name}.identified_by takes a field name/value object or a block, not both" if path
+
+            if targets.size > 1
+              raise Malformed, "#{@name}.identified_by takes no as: with a compound key" if as
+
+              @identity_fields_pending = targets
+              return
+            end
+
+            if identity_type?(target)
+              @identity_type_pending = [target, as, attributes.size]
+            else
+              raise Malformed,
+                    "#{@name}.identified_by :#{target} takes no as: — as: only applies to identified_by ValueObject" if as
+
+              @identity_field_pending = target
+            end
+            return
+          end
+
+          raise Malformed, "#{@name}.identified_by names no field" unless path
+
+          paths = Ports::Extraction.canonical(path).to_s.split(" ").reject(&:empty?)
+          raise Malformed, "#{@name}.identified_by names no field" if paths.empty?
+
+          @identity_paths = paths
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+require_relative "word_gate"
+module Hecks
+  module Bluebook
+    module DSL
+      class LifecycleBuilder
+        GRAMMAR_CONTEXT = "Lifecycle"
+
+        include WordGate
+
+        def initialize(field, default:)
+          @field       = field
+          @default     = default
+          @transitions = []
+        end
+
+        # RENAMED FROM `transition` — 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.
+        def transition_impl(mapping)
+          mapping = mapping.dup
+          from    = mapping.delete(:from)
+
+          mapping.each do |command, target|
+            @transitions << [
+              command.to_s,
+              StateTransition.new(target: target, from: from)
+            ]
+          end
+        end
+
+        def build
+          Lifecycle.new(field: @field, default: @default, transitions: @transitions)
+        end
+
+        def self.build(field, default:, &block)
+          builder = new(field, default: default)
+          builder.instance_eval(&block) if block
+          builder.build
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,7 @@
+module Hecks
+  module Bluebook
+    module DSL
+      class Malformed < StandardError; end
+    end
+  end
+end

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

@@ -0,0 +1,120 @@
+require_relative "word_gate"
+module Hecks
+  module Bluebook
+    module DSL
+      class PolicyBuilder
+        GRAMMAR_CONTEXT = "Policy"
+
+        include WordGate
+
+        def initialize(name)
+          @name = name
+        end
+
+        # `on` — item #13's full metaprogrammed dispatch, slice 1
+        # (whole-project table-unification survey): a bare, kind-driven
+        # coerce-and-assign, now executed by `GenericDispatch`.
+
+        # `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.
+        #
+        # 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.
+        # 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).
+        #
+        # 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.
+        def trigger_impl(command_ref, with: nil)
+          if command_ref.is_a?(::String) && !MetaValidator.shadow_parsing?
+            raise Malformed,
+                  "#{@name}'s trigger #{command_ref.inspect} is quoted text — give the bare command " \
+                  "constant instead, e.g. trigger Account::Debit"
+          end
+
+          @trigger_command = Naming.command_ref(command_ref)
+          @with_spec = (with || {}).to_a
+          @projection_declared = !with.nil?
+        end
+
+        # `across` — item #13's full metaprogrammed dispatch, slice 1:
+        # same shape as `on`, above.
+
+        # 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.
+        def where(&predicate)
+          canonical = Ports::Extraction.canonical(predicate)
+
+          if canonical.to_s.empty?
+            raise Malformed,
+                  "#{@name}'s where did not survive extraction — its source " \
+                  "could not be read, so no other runtime could ever evaluate it"
+          end
+
+          @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.
+
+        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 || []
+          ).tap { |policy| policy.instance_variable_set(:@projection_declared, !!@projection_declared) }
+        end
+
+        def self.build(name, &block)
+          builder = new(name)
+          builder.instance_eval(&block) if block
+          builder.build
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+require_relative "word_gate"
+module Hecks
+  module Bluebook
+    module DSL
+      class PortBuilder
+        GRAMMAR_CONTEXT = "Port"
+
+        include WordGate
+
+        def initialize(name)
+          @name   = name
+          @signal = :reply
+        end
+
+        def verb(value)   = @verb = value.to_s
+        def signal(value) = @signal = value.to_sym
+
+        def build
+          MetaValidator.call_port(Port.new(name: @name, verb: @verb, signal: @signal))
+        end
+
+        def self.build(name, &block)
+          builder = new(name)
+          builder.instance_eval(&block) if block
+          builder.build
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,142 @@
+require_relative "word_gate"
+module Hecks
+  module Bluebook
+    module DSL
+      class PortOperationBuilder
+        GRAMMAR_CONTEXT = "PortOperation"
+
+        include AttributeCollector
+        include WordGate
+
+        # `to:` — THE SANCTIONED REPLACEMENT for `reference_to` inside an
+        # operation body, added here rather than left as a documented-but-
+        # unbuilt promise: reference_to_impl's own refusal message has told
+        # authors to "pass the receiving aggregate in to:" since #335, but
+        # no `to:` argument existed anywhere in DomainPort's own grammar
+        # (domain_port.bluebook) for operation/tells/asks to receive it —
+        # confirmed by grep across every lib/hecks/language file, not
+        # assumed.
+        #
+        # 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, lifeadelics' own vendored
+        # PaymentGateway) still relies on unchanged.
+        def initialize(name, to: nil, owner: nil, direction: :inbound)
+          @name      = name
+          @to        = to && Naming.demodulise(to)
+          @owner     = owner
+          @direction = direction
+          @emits     = []
+        end
+
+        # 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.
+        # RENAMED FROM `reference_to` — 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).
+        def reference_to_impl(type, as: nil)
+          unless MetaValidator.shadow_parsing?
+            raise Malformed,
+                  "#{@name}.reference_to is behavioral routing, not retained domain state — " \
+                  "pass the receiving aggregate in to: and declare only external facts with attribute"
+          end
+
+          add_reference!(type, as: as)
+        end
+
+        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`.
+
+        def build
+          outbound = @direction == :outbound
+          refuse_wrong_words!(outbound)
+
+          operation = PortOperation.new(
+            name: @name, attributes: attributes, emits: @emits,
+            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.
+          raise Malformed,
+                "#{@name} declares no emits — an operation with nothing to say " \
+                "afterward is a call into nothing" if !outbound && @emits.empty?
+
+          operation
+        end
+
+        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.
+        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.
+        def refuse_wrong_words!(outbound)
+          if outbound
+            raise Malformed, "#{@name} is an asks and declares emits — name its two endings with " \
+                             "answers and refuses instead" unless @emits.empty?
+            raise Malformed, "#{@name} declares no answers — an ask with no word for what came " \
+                             "back cannot be reacted to" unless @answers
+            raise Malformed, "#{@name} declares no refuses — an ask that cannot fail is a call " \
+                             "into a system you do not control, pretending otherwise" unless @refuses
+          else
+            raise Malformed, "#{@name} is a tells and declares #{@answers ? 'answers' : 'refuses'} — " \
+                             "an inbound fact has no channel back to whoever sent it" if @answers || @refuses
+          end
+        end
+
+        def self.build(name, to: nil, owner: nil, direction: :inbound, &block)
+          builder = new(name, to: to, owner: owner, direction: direction)
+          builder.instance_eval(&block) if block
+          builder.build
+        end
+      end
+    end
+  end
+end