hecks 3.10.0 → 3.11.0

data/lib/hecks/bluebook/capabilities.rb

@@ -1,8 +1,12 @@
+require_relative "capabilities/attribute_values"
+
 module Hecks
   module Bluebook
     # What a chapter may declare it provides — trusted in place of a literal
     # chapter-name check by role checks, adapters and the fuzzer.
     module Capabilities
+      extend AttributeValues
+
       AUTHORIZATION = "authorization".freeze
       # Who may sign in and with what role, resolved by declaration rather
       # than an env var naming the aggregate.
@@ -30,6 +34,31 @@ module Hecks
       # declaration rather than the literal name "PaymentConnection".
       PAYMENT_CONNECTION = "payment_connection".freeze
 
+      # The checkout boundary in front of a payment processor: how long a
+      # signed webhook stays fresh and how long a session holds its seat,
+      # recognised by declaration rather than the literal chapter name.
+      CHECKOUT = "checkout".freeze
+
+      # Marking a domain's attributes sensitive and reading the markings back, recognised by
+      # declaration rather than the literal chapter name "Privacy".
+      PRIVACY = "privacy".freeze
+
+      # A subject's key record, shredded to erase them, recognised by declaration rather than the
+      # literal names "Privacy" and "SubjectKey".
+      SUBJECT_KEYS = "subject_keys".freeze
+
+      # The kinds of contract entry a capability may name: `:command` and
+      # `:query` ("Aggregate.Name"), `:port_operation` ("Aggregate.Port.Operation")
+      # and `:mark` ("Aggregate.mark_name", the states of that aggregate's
+      # lifecycle mark) and `:duration` ("Aggregate.attribute", the whole-seconds
+      # `default:` of that attribute, ADR 0098). `:mark` and `:duration` entries are
+      # optional; every other entry is required.
+      #
+      # ADR 0099 adds two more optional kinds: `:text` ("Aggregate.attribute", the string
+      # `default:` of that attribute, a word the domain owns) and `:attribute`
+      # ("Aggregate.attribute", the attribute's own name, for the host to read a field by).
+      OPTIONAL_KINDS = %i[mark duration text attribute].freeze
+
       CONTRACTS = {
         AUTHORIZATION      => {
           # every assignment an actor holds, current or historical
@@ -57,13 +86,25 @@ module Hecks
         }.freeze,
         NEWSLETTER         => {
           # a guest signs up; the aggregate it names is the subscriber
-          subscribe:   :command,
+          subscribe:             :command,
           # attach a display name to an existing subscriber
-          add_name:    :command,
+          add_name:              :command,
           # a subscriber confirms their address from the emailed link
-          confirm:     :command,
+          confirm:               :command,
           # a subscriber leaves from the emailed link
-          unsubscribe: :command
+          unsubscribe:           :command,
+          # Optional: the subscriber states that await the emailed confirm
+          # link, spelled "Subscriber.awaiting_confirmation"
+          awaiting_confirmation: :mark,
+          # Optional: the subscriber states that receive each issue sent
+          receives_issues:       :mark,
+          # Optional: the subscriber states of someone who has left
+          left:                  :mark,
+          # Optional: how many seconds the emailed confirm link stays valid,
+          # spelled "Subscriber.confirm_window"
+          confirm_window:        :duration,
+          # Optional: how many seconds an emailed unsubscribe link stays valid
+          unsubscribe_window:    :duration
         }.freeze,
         NEWSLETTER_ISSUES  => {
           # mark an issue sent; the issue aggregate is the one it names
@@ -74,17 +115,31 @@ module Hecks
         }.freeze,
         PAYMENTS           => {
           # start a payment; the aggregate it names is the payment
-          initiate:  :command,
+          initiate:     :command,
           # the processor reports the money arrived
-          succeeded: :port_operation,
+          succeeded:    :port_operation,
           # the processor reports the payment failed or expired
-          failed:    :port_operation
+          failed:       :port_operation,
+          # Optional: the lifecycle states of the payment that hold a seat,
+          # spelled "Payment.holds_seat" (Aggregate.mark_name); resolves to the
+          # states of that aggregate's lifecycle `mark :holds_seat`
+          holds_seat:   :mark,
+          # Optional: the failure reason a lapsed checkout hold records, spelled
+          # "Payment.lapse_reason" (the string `default:` of that attribute)
+          lapse_reason: :text
         }.freeze,
         REGISTRATIONS      => {
           # schedule a session; the aggregate it names is the event
-          schedule: :command,
+          schedule:      :command,
           # a guest asks for a place; the aggregate it names is the registration
-          request:  :command
+          request:       :command,
+          # Optional: the registration attribute that stamps when it was asked for,
+          # spelled "Registration.requested_at"
+          registered_at: :attribute,
+          # Optional: the registration states that give a seat back, spelled
+          # "Registration.frees_seat" (Aggregate.mark_name); resolves to the
+          # states of that aggregate's lifecycle `mark :frees_seat`
+          frees_seat:    :mark
         }.freeze,
         PAYMENT_CONNECTION => {
           # link the processor account; the aggregate it names is the connection
@@ -101,8 +156,35 @@ module Hecks
           enable:     :command,
           # switch taking payments off
           disable:    :command
+        }.freeze,
+        PRIVACY            => {
+          # flag one attribute of a domain sensitive
+          mark_sensitive: :command,
+          # every marking of one domain, for masking a read
+          markings_for:   :query
+        }.freeze,
+        SUBJECT_KEYS       => {
+          # the key record of one subject, if any
+          key_for: :query,
+          # record the subject's key as destroyed
+          shred:   :command
+        }.freeze,
+        CHECKOUT           => {
+          # Optional: how many seconds either side of now a signed webhook's
+          # timestamp may sit, spelled "WebhookReceipt.tolerance"
+          webhook_tolerance: :duration,
+          # Optional: how many seconds a session holds its seat
+          session_hold:      :duration
         }.freeze
       }.freeze
+
+      # The keys a capability's `provides` must name.
+      #
+      # @param capability [String] a `CONTRACTS` key
+      # @return [Array<Symbol>] the keys whose kind is not optional
+      def self.required_keys(capability)
+        CONTRACTS.fetch(capability).reject { |_, kind| OPTIONAL_KINDS.include?(kind) }.keys
+      end
     end
   end
 end

data/lib/hecks/bluebook/domain_port.rb

@@ -14,13 +14,22 @@ module Hecks
 
       attr_reader :hecks_name, :attributes, :emits, :direction, :answers, :refuses, :to
 
+      # Marks this operation as the one the hecksagon picks (`ask_via`) when its ask name is
+      # declared on more than one port of the aggregate.
+      #
+      # @return [true]
+      def choose! = @chosen = true
+
+      # @return [Boolean] whether the hecksagon picked this operation with `ask_via`
+      def chosen? = @chosen == true
+
       # `:inbound` (`tells`) is an external fact arriving as an event; it emits and nothing more.
       # `:outbound` (`asks`) is the domain wanting something from outside, naming both
       # `answers` and `refuses` so the failure is visible to the model.
       #
       # Every optional keyword and what it holds when the declaration omits it.
       FIELD_DEFAULTS = {
-        attributes: [], emits: [], direction: :inbound, answers: nil, refuses: nil, to: nil
+        attributes: [], emits: [], direction: :inbound, answers: nil, refuses: nil, to: nil, chosen: false
       }.freeze
 
       # @param name [String, Symbol] the operation's declared name
@@ -30,6 +39,7 @@ module Hecks
       # @param answers [String, nil] an outbound operation's event for the adapter's answer
       # @param refuses [String, nil] an outbound operation's event for the adapter's refusal
       # @param to [String, nil] the aggregate this operation routes to, if any
+      # @param chosen [Boolean] whether the hecksagon picked this operation with `ask_via`
       def initialize(name:, **given)
         fields = KeywordFields.fill(given, FIELD_DEFAULTS)
         @hecks_name = name.to_s
@@ -48,15 +58,17 @@ module Hecks
       # @return [Boolean] whether this operation is a `tells`/`operation`
       def inbound?  = @direction == :inbound
 
-      # `direction`/`answers`/`refuses`/`to` are merged in only when set: the Rust parser
-      # emits none of them, so an unconditional key would break parser_parity_spec.
+      # `direction`/`answers`/`refuses`/`to`/`chosen` are merged in only when set: the Rust parser
+      # emits none of them unprompted, so an unconditional key would break parser_parity_spec.
       #
       # @return [Hash] the declared emission, plus `direction`/`answers`/`refuses` for an
-      #   outbound operation and `to` when a routing target is declared
+      #   outbound operation, `to` when a routing target is declared, and `chosen` when the
+      #   hecksagon picked it with `ask_via`
       def to_h
         shape = super
         shape = shape.merge(direction: @direction.to_s, answers: @answers, refuses: @refuses) unless inbound?
         shape = shape.merge(to: @to) if @to
+        shape = shape.merge(chosen: true) if chosen?
         shape
       end
     end

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

@@ -8,13 +8,17 @@ module Hecks
       class AdapterBuilder
         GRAMMAR_CONTEXT = "Adapter".freeze
 
+        # Marks a field that gives no `default:`; `nil` and `false` are defaults too.
+        NO_DEFAULT = Object.new.freeze
+
         include WordGate
 
         # @param name [String] the adapter's name, as written after `Hecks.adapter`
         def initialize(name)
-          @name    = name
-          @fields  = []
-          @secrets = []
+          @name = name
+          @fields   = []
+          @secrets  = []
+          @defaults = {}
         end
 
         # Names the port this adapter implements; a repeated call replaces the earlier name.
@@ -26,8 +30,13 @@ module Hecks
         # Declares one plain setting a `.world` file may supply for this adapter.
         #
         # @param name [Symbol, String] the setting's name, such as `:database`
+        # @param default [Object] the value used when the world gives none; a string may hold
+        #   `{name}` or `{storage_name}`, filled from the aggregate the adapter is built for
         # @return [Array<Symbol>] every field declared so far, this one last
-        def field(name) = @fields << name.to_sym
+        def field(name, default: NO_DEFAULT)
+          @defaults[name.to_sym] = default unless default.equal?(NO_DEFAULT)
+          @fields << name.to_sym
+        end
 
         # Declares one setting whose value is a secret, such as an API token.
         #
@@ -35,12 +44,15 @@ module Hecks
         # @return [Array<Symbol>] every secret declared so far, this one last
         def secret(name) = @secrets << name.to_sym
 
-        # Assembles the collected port, fields and secrets, judged by the adapter language.
+        # Assembles the collected port, fields, defaults and secrets, judged by the adapter
+        # language.
         #
         # @return [Bluebook::Adapter] the adapter, returned once the language accepts it
         # @raise [Bluebook::DSL::Malformed] if the adapter language refuses the declaration
         def build
-          MetaValidator.call_adapter(Adapter.new(name: @name, port: @port, fields: @fields, secrets: @secrets))
+          MetaValidator.call_adapter(
+            Adapter.new(name: @name, port: @port, fields: @fields, secrets: @secrets, defaults: @defaults)
+          )
         end
 
         # Evaluates an `Hecks.adapter` block against a fresh builder and returns what it built.

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

@@ -29,6 +29,18 @@ module Hecks
           self
         end
 
+        # Picks which port answers an ask this aggregate declares on more than one port.
+        #
+        # @param name [String, Symbol] the ask's declared name, such as `"Probe"`
+        # @param port [String, Symbol] the port whose `asks` of that name is the one policies reach
+        # @return [BindingProxy] self
+        # @raise [Bluebook::DSL::Malformed] if no such aggregate, port or ask is declared yet
+        def ask_via(name, port:)
+          domain, aggregate_name = @fqn.split("::")
+          AskResolution.pick!(Hecks.current_registry.bluebook(domain), aggregate_name, name, port)
+          self
+        end
+
         def method_missing(verb, *args, **kwargs, &block)
           # A bare call (no args/kwargs/block) starts a Privacy marking chain instead
           # of a Bind — no real `.hecksagon` bind is ever called with zero arguments,
@@ -68,6 +80,7 @@ module Hecks
             operation.attributes.select(&:reference?).each { |attribute| attribute.type.declared_in = aggregate_ir }
           end
           aggregate_ir.add_port(built)
+          AskResolution.bind_resolved(Hecks.current_registry.bluebook(@fqn.split("::").first))
         end
       end
 

data/lib/hecks/bluebook/dsl/bluebook_builder/validation/computed_sources.rb

@@ -0,0 +1,98 @@
+module Hecks
+  module Bluebook
+    module DSL
+      class BluebookBuilder
+        module Validation
+          # Checks that every name and dotted path a computed `sets` source reads resolves, once
+          # every aggregate and value object in the chapter exists.
+          module ComputedSources
+            private
+
+            # Refuses a computed source whose operand path names nothing declared, runs through
+            # a list or a reference, or ends on a value object with more than one field.
+            def validate_computed_sources!(bluebook)
+              value_objects = bluebook.aggregates.flat_map(&:value_objects).to_h { |vo| [vo.hecks_name.to_s, vo] }
+              bluebook.aggregates.each do |aggregate|
+                aggregate.commands.each { |command| check_computed_command!(aggregate, command, value_objects) }
+              end
+            end
+
+            def check_computed_command!(aggregate, command, value_objects)
+              command.mutations.select { |mutation| mutation.source.is_a?(Computed) }.each do |mutation|
+                operand_paths(Expression::Resolver.parse(mutation.source.text)).each do |path|
+                  check_operand_path!(PathCheck.new(aggregate, command, mutation, value_objects), path)
+                end
+              end
+            end
+
+            # Where a path is read: the aggregate and command it belongs to, the mutation, and the
+            # chapter's value objects by name.
+            PathCheck = Struct.new(:aggregate, :command, :mutation, :value_objects)
+            private_constant :PathCheck
+
+            def operand_paths(node)
+              return [node.path] if node.is_a?(Expression::Resolver::Lookup)
+              return [] unless node.is_a?(Struct)
+
+              node.members.flat_map { |member| operand_paths(node[member]) }
+            end
+
+            def check_operand_path!(check, path)
+              head, *segments = path.split(".")
+              attribute = operand_head(check, head)
+              return if attribute.nil? && segments.empty? && stored_scalar?(check, head)
+
+              refuse_operand!(check, path, "names no argument or field of #{check.aggregate.hecks_name}") unless attribute
+              walk_operand_path!(check, path, attribute, segments)
+            end
+
+            # The command's argument, else the owner's field.
+            def operand_head(check, name)
+              check.command.attributes.find { |attr| attr.name.to_s == name } ||
+                check.aggregate.attributes.find { |attr| attr.name.to_s == name }
+            end
+
+            # A lifecycle or projected field is a plain scalar of the record, so a name that stops
+            # there needs no further check.
+            def stored_scalar?(check, name)
+              check.aggregate.lifecycle&.field.to_s == name || check.aggregate.projected_fields.any? { |f| f.name.to_s == name }
+            end
+
+            def walk_operand_path!(check, path, attribute, segments)
+              segments.each do |segment|
+                refuse_operand!(check, path, "runs through #{attribute.name}, which is a list") if attribute.list?
+                refuse_operand!(check, path, "runs through #{attribute.name}, which is a reference") if attribute.reference?
+                attribute = field_of(check, path, attribute, segment)
+              end
+              refuse_operand!(check, path, "is a list") if attribute.list?
+              refuse_operand!(check, path, "is a reference") if attribute.reference?
+              refuse_multi_field!(check, path, attribute)
+            end
+
+            def field_of(check, path, attribute, segment)
+              holder = check.value_objects[attribute.type.to_s]
+              refuse_operand!(check, path, "runs through #{attribute.name}, which is not a value object") unless holder
+              holder.attributes.find { |field| field.name.to_s == segment } ||
+                refuse_operand!(check, path, "names #{segment}, which #{holder.hecks_name} does not declare")
+            end
+
+            # A name that stops on a value object reads as its one field, so it needs exactly one.
+            def refuse_multi_field!(check, path, attribute)
+              holder = check.value_objects[attribute.type.to_s]
+              return unless holder && holder.attributes.size > 1
+
+              example = "#{path}.#{holder.attributes.first.name}"
+              refuse_operand!(check, path, "is a #{holder.hecks_name} with several fields — name one, as #{example}")
+            end
+
+            def refuse_operand!(check, path, reason)
+              raise Malformed,
+                    "#{check.aggregate.hecks_name}.#{check.command.hecks_name}'s sets :#{check.mutation.target} reads " \
+                    "#{path}, which #{reason}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/dsl/bluebook_builder/validation/fan_out_rows.rb

@@ -0,0 +1,42 @@
+module Hecks
+  module Bluebook
+    module DSL
+      class BluebookBuilder
+        module Validation
+          # The names a `for_each` policy's `with:` may read off a fan-out row, mirroring what
+          # `PolicyInterpreter::Arguments#trigger_args` offers a projection at runtime.
+          module FanOutRows
+            private
+
+            # The names a row of the policy's `for_each` query carries: the row's id, the
+            # aggregate's attributes, lifecycle field and projected fields, and the key the
+            # trigger addresses a row by. Nil when the query's aggregate is not in this chapter,
+            # which leaves the source unchecked.
+            #
+            # @return [Array<Symbol>, nil]
+            def fan_out_row_names(policy, aggregates, target)
+              return nil if policy.for_each.to_s.empty? || policy.for_each.to_s.include?("::")
+
+              aggregate_name = policy.for_each.to_s.split(".", 2).first
+              aggregate = aggregates.find { |candidate| candidate.hecks_name == aggregate_name }
+              return nil unless aggregate
+
+              [:id, *row_field_names(aggregate), *row_key_names(target, aggregate_name)]
+            end
+
+            def row_field_names(aggregate)
+              names = aggregate.attributes.map(&:name) + aggregate.projected_fields.map(&:name)
+              names += aggregate.identity_heads.map(&:to_sym)
+              aggregate.lifecycle ? names << aggregate.lifecycle.field.to_sym : names
+            end
+
+            def row_key_names(target, aggregate_name)
+              key = target&.addressing_key_for(aggregate_name)
+              key ? [key.to_sym] : []
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/dsl/bluebook_builder/validation/projected_fields.rb

@@ -4,7 +4,8 @@ module Hecks
       class BluebookBuilder
         module Validation
           # Checks that each `projects` reference resolves to an aggregate declaring the remote
-          # field as a scalar, once every aggregate in the chapter exists.
+          # field as a scalar or single-field value object, once every aggregate in the chapter
+          # exists.
           module ProjectedFields
             private
 
@@ -65,8 +66,19 @@ module Hecks
                     "value, never a reference, a value object, or a list"
             end
 
+            # A scalar, or a single-field value object, which a projection unwraps to its one
+            # scalar (ADR 0025 addendum); a multi-field value object, a reference and a list are
+            # not.
             def projectable_scalar?(target, attribute)
-              !attribute.list? && !attribute.reference? && target.value_object(attribute.type).nil?
+              return false if attribute.list? || attribute.reference?
+
+              value_object = target.value_object(attribute.type)
+              value_object.nil? || single_scalar_field?(value_object)
+            end
+
+            def single_scalar_field?(value_object)
+              sole = value_object.sole_attribute
+              !sole.nil? && !sole.list? && !sole.reference?
             end
           end
         end

data/lib/hecks/bluebook/dsl/bluebook_builder/validation/provisions.rb

@@ -5,6 +5,15 @@ module Hecks
         module Validation
           # Checks every `provides` row of a chapter against `Capabilities::CONTRACTS`.
           module Provisions
+            # The checks for the kinds whose verb is not a command or a query.
+            SPECIAL_KIND_CHECKS = {
+              port_operation: :validate_provided_port_operation!,
+              mark:           :validate_provided_mark!,
+              duration:       :validate_provided_duration!,
+              text:           :validate_provided_text!,
+              attribute:      :validate_provided_attribute!
+            }.freeze
+
             private
 
             # Checks every `provides` row against `Capabilities::CONTRACTS`.
@@ -26,14 +35,26 @@ module Hecks
 
             def refuse_wrong_provision_keys!(bluebook, capability, rows, contract)
               keys = rows.map { |row| row.key.to_sym }
-              return if keys.sort == contract.keys.sort
+              required = Capabilities.required_keys(capability)
+              return if provision_keys_valid?(keys, required, contract.keys)
 
               raise Malformed, "#{bluebook.name} provides #{capability.inspect} with #{keys.join(", ")}, but " \
-                               "#{capability} needs exactly #{contract.keys.join(", ")}"
+                               "#{capability} needs #{provision_keys_phrase(required, contract.keys - required)}"
+            end
+
+            def provision_keys_valid?(keys, required, allowed)
+              (keys - allowed).empty? && (required - keys).empty? && keys.uniq.size == keys.size
+            end
+
+            def provision_keys_phrase(required, optional)
+              return "exactly #{required.join(", ")}" if optional.empty?
+
+              "#{required.join(", ")} and may add #{optional.join(", ")}"
             end
 
             def validate_provided_verb!(bluebook, capability, row, kind)
-              return validate_provided_port_operation!(bluebook, capability, row) if kind == :port_operation
+              special = SPECIAL_KIND_CHECKS[kind]
+              return send(special, bluebook, capability, row) if special
 
               aggregate_name, member = row.verb.split(".", 2)
               aggregate = bluebook.aggregate(aggregate_name)
@@ -54,6 +75,51 @@ module Hecks
                                "which is not spelled \"Aggregate.Port.Operation\" over an aggregate this chapter declares"
             end
 
+            # A mark verb is spelled "Aggregate.mark_name" and must name a mark declared on that
+            # aggregate's lifecycle.
+            def validate_provided_mark!(bluebook, capability, row)
+              aggregate_name, mark = row.verb.split(".", 2)
+              aggregate = bluebook.aggregate(aggregate_name)
+              return if aggregate && mark && aggregate.lifecycle&.marked(mark)
+
+              raise Malformed, "#{bluebook.name} provides #{capability.inspect} #{row.key}: #{row.verb.inspect}, " \
+                               "which names no lifecycle mark this chapter declares (spelled " \
+                               "\"Aggregate.mark_name\", with `mark :mark_name, ...` in that aggregate's lifecycle)"
+            end
+
+            # A duration verb is spelled "Aggregate.attribute" and must name an attribute of
+            # that aggregate whose `default:` is a whole, positive number of seconds (a bare
+            # integer, or the `{ value: N }` fill of a one-field value object).
+            def validate_provided_duration!(bluebook, capability, row)
+              return if Capabilities.duration_of(bluebook, row.verb)
+
+              raise Malformed, "#{bluebook.name} provides #{capability.inspect} #{row.key}: #{row.verb.inspect}, " \
+                               "which names no attribute with a whole-seconds default this chapter declares " \
+                               "(spelled \"Aggregate.attribute\", with `attribute :attribute, Seconds, " \
+                               "default: { value: 1800 }` in that aggregate)"
+            end
+
+            # A text verb is spelled "Aggregate.attribute" and must name an attribute of that
+            # aggregate whose `default:` is a non-empty string (bare, or a one-field value object's
+            # `{ value: "..." }` fill).
+            def validate_provided_text!(bluebook, capability, row)
+              return if Capabilities.text_of(bluebook, row.verb)
+
+              raise Malformed, "#{bluebook.name} provides #{capability.inspect} #{row.key}: #{row.verb.inspect}, " \
+                               "which names no attribute with a text default this chapter declares " \
+                               "(spelled \"Aggregate.attribute\", with `attribute :attribute, Reason, " \
+                               "default: { value: \"word\" }` in that aggregate)"
+            end
+
+            # An attribute verb is spelled "Aggregate.attribute" and must name an attribute of that
+            # aggregate.
+            def validate_provided_attribute!(bluebook, capability, row)
+              return if Capabilities.attribute_of(bluebook, row.verb)
+
+              raise Malformed, "#{bluebook.name} provides #{capability.inspect} #{row.key}: #{row.verb.inspect}, " \
+                               "which names no attribute this chapter declares (spelled \"Aggregate.attribute\")"
+            end
+
             def provided_member_names(aggregate, kind)
               kind == :command ? aggregate.commands.map(&:hecks_name) : aggregate.queries.map(&:name)
             end

data/lib/hecks/bluebook/dsl/bluebook_builder/validation/with_projections.rb

@@ -11,18 +11,20 @@ module Hecks
             WithContext = Struct.new(:lookup, :aggregates, :correlation_heads)
             # One `with:` to check: the command it targets, the event it reads from, the spec
             # itself, how a refusal names it, and the process manager when it is a saga leg.
-            WithSpec = Struct.new(:command_ref, :event_name, :with_spec, :label, :process_manager)
+            WithSpec = Struct.new(:command_ref, :event_name, :with_spec, :label, :process_manager, :row_names)
             # What a `with:` source may read: the correlation key, the emitter's identity heads and
-            # the event shapes whose fields are legal.
-            Readable = Struct.new(:correlation, :identity, :shapes)
+            # the event shapes whose fields are legal, and a fan-out row's names (empty off a
+            # fan-out).
+            Readable = Struct.new(:correlation, :identity, :shapes, :row)
             private_constant :WithContext, :WithSpec, :Readable
 
             private
 
             # Checks `with:` projections against the source event's shape and the target's fields.
             # Same-chapter only: an unresolvable cross-chapter source or target is skipped.
-            # A for_each policy's source is a query row with no known shape, so only its target
-            # is checked.
+            # A for_each policy's source is the event plus a query row; the row's names are known
+            # only when the query's aggregate is in this chapter, otherwise only the target is
+            # checked.
             def validate_with_projections!(policies, process_managers, aggregates)
               context = WithContext.new(command_lookup(aggregates), aggregates, correlation_heads(process_managers))
 
@@ -37,9 +39,13 @@ module Hecks
             def check_policy_with!(policy, context)
               return if policy.with_spec.to_a.empty?
 
-              source_event = policy.for_each.to_s.empty? ? policy.on_event : nil
-              check_with_spec!(WithSpec.new(policy.trigger_command, source_event, policy.with_spec,
-                                            "#{policy.name}'s trigger", nil), context)
+              check_with_spec!(policy_with_spec(policy, context), context)
+            end
+
+            def policy_with_spec(policy, context)
+              row = fan_out_row_names(policy, context.aggregates, context.lookup[policy.trigger_command])
+              source_event = policy.for_each.to_s.empty? || row ? policy.on_event : nil
+              WithSpec.new(policy.trigger_command, source_event, policy.with_spec, "#{policy.name}'s trigger", nil, row)
             end
 
             def check_dispatch_with!(process_manager, handler, dispatch, context)
@@ -47,7 +53,7 @@ module Hecks
 
               label = "#{process_manager.name}'s dispatch #{dispatch.command_name}"
               check_with_spec!(WithSpec.new(dispatch.command_name, handler.event_type, dispatch.with_spec,
-                                            label, process_manager), context)
+                                            label, process_manager, nil), context)
             end
 
             # Checks one `with:` spec: each key must be a field the target command accepts,
@@ -73,7 +79,7 @@ module Hecks
               identity = pm.nil? && event_name ? event_identity_heads_for(event_name, aggregates) : []
               shapes = [event_name && event_shape_for(event_name, aggregates),
                         pm && event_shape_for(pm.starts_on, aggregates)].compact
-              Readable.new(pm&.correlates_by && pm.correlation_head, identity, shapes)
+              Readable.new(pm&.correlates_by && pm.correlation_head, identity, shapes, spec.row_names.to_a)
             end
 
             def refuse_undeclared_with_field!(spec, field)
@@ -84,6 +90,7 @@ module Hecks
             def refuse_unreadable_with_source!(spec, source, readable)
               return unless source.is_a?(::Symbol)
               return if source == readable.correlation || readable.identity.include?(source)
+              return if readable.row.include?(source)
               return if readable.shapes.empty? || shape_reads?(readable.shapes, source)
 
               raise Malformed,

data/lib/hecks/bluebook/dsl/bluebook_builder/validation.rb

@@ -1,9 +1,11 @@
 require_relative "validation/provisions"
 require_relative "validation/references"
 require_relative "validation/event_shapes"
+require_relative "validation/fan_out_rows"
 require_relative "validation/with_projections"
 require_relative "validation/query_hops"
 require_relative "validation/projected_fields"
+require_relative "validation/computed_sources"
 require_relative "validation/correlation_keys"
 
 module Hecks
@@ -17,9 +19,11 @@ module Hecks
           include Provisions
           include References
           include EventShapes
+          include FanOutRows
           include WithProjections
           include QueryHops
           include ProjectedFields
+          include ComputedSources
           include CorrelationKeys
 
           # Runs every whole-chapter check against one assembled chapter.
@@ -58,6 +62,7 @@ module Hecks
             infer_hop_query_arguments!(bluebook)
             validate_query_hops!(bluebook)
             validate_projected_fields!(bluebook)
+            validate_computed_sources!(bluebook)
           end
         end
       end