hecks 5.0.0 → 6.0.0

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

@@ -1,34 +1,34 @@
 module Hecks
   module Bluebook
     module DSL
-      # The chapter-wide half of a bare `given` reference: resolves every reference the
-      # aggregates and entities deferred, once the chapter's files are loaded.
+      # The bluebook-wide half of a bare `given` reference: resolves every reference the
+      # aggregates and entities deferred, once the bluebook's files are loaded.
       class BluebookBuilder
-        # The other half of a chapter-wide `given` reference — resolves every reference
-        # `AggregateBuilder#pending_chapter_given` deferred, once the chapter's files are loaded.
+        # The other half of a bluebook-wide `given` reference — resolves every reference
+        # `AggregateBuilder#pending_bluebook_given` deferred, once the bluebook's files are loaded.
         #
         # Mutates each placeholder `Given` in place, since it's already embedded by Ruby
         # object reference in the referencing preconditions and commands.
         #
         # @return [void]
         # @raise [Bluebook::DSL::Malformed] if a pending reference's own `description` names no
-        #   precondition any aggregate in this chapter declares, is ambiguous across several
+        #   precondition any aggregate in this bluebook declares, is ambiguous across several
         #   aggregates with no `declared_by:` to disambiguate, or `declared_by:` names an
         #   aggregate that does not declare it
-        def resolve_pending_chapter_givens!
-          fill_pending(@chapter_pending_givens) { |entry| resolve_pending_chapter_given(entry) }
+        def resolve_pending_bluebook_givens!
+          fill_pending(@bluebook_pending_givens) { |entry| resolve_pending_bluebook_given(entry) }
         end
 
-        # The entity-scoped analogue of `#resolve_pending_chapter_givens!`, resolved
-        # against `@chapter_entity_named_givens` instead.
+        # The entity-scoped analogue of `#resolve_pending_bluebook_givens!`, resolved
+        # against `@bluebook_entity_named_givens` instead.
         #
         # @return [void]
         # @raise [Bluebook::DSL::Malformed] if a pending reference's own `description` names no
-        #   precondition any piece in this chapter declares, is ambiguous across several pieces
+        #   precondition any piece in this bluebook declares, is ambiguous across several pieces
         #   with no `declared_by:` to disambiguate, or `declared_by:` names a piece that does
         #   not declare it
-        def resolve_pending_chapter_entity_givens!
-          fill_pending(@chapter_entity_pending_givens) { |entry| resolve_pending_chapter_entity_given(entry) }
+        def resolve_pending_bluebook_entity_givens!
+          fill_pending(@bluebook_entity_pending_givens) { |entry| resolve_pending_bluebook_entity_given(entry) }
         end
 
         private
@@ -45,8 +45,8 @@ module Hecks
           entries.clear
         end
 
-        def resolve_pending_chapter_given(entry)
-          candidates = RuleReference.resolve_owner_keyed(@chapter_named_givens, entry[:description])
+        def resolve_pending_bluebook_given(entry)
+          candidates = RuleReference.resolve_owner_keyed(@bluebook_named_givens, entry[:description])
           declarer   = entry[:declared_by]
           return candidates[declarer] || raise(Malformed, undeclared_given_message(entry)) if declarer
           return candidates.values.first if candidates.size == 1
@@ -56,26 +56,26 @@ module Hecks
 
         def undeclared_given_message(entry)
           "#{entry[:aggregate]}'s given #{entry[:description].inspect} names no precondition " \
-            "#{entry[:declared_by]} declares in this chapter — #{entry[:declared_by]} " \
+            "#{entry[:declared_by]} declares in this bluebook — #{entry[:declared_by]} " \
             "either hasn't declared #{entry[:description].inspect}, or declared_by: named the " \
             "wrong aggregate"
         end
 
         def unknown_given_message(entry)
           "#{entry[:aggregate]}'s given #{entry[:description].inspect} names no precondition " \
-            "any aggregate in this chapter ever declares — declare it once with a block " \
+            "any aggregate in this bluebook ever declares — declare it once with a block " \
             "(some aggregate's own given(#{entry[:description].inspect}) { ... })"
         end
 
         def ambiguous_given_message(entry, candidates)
           "#{entry[:aggregate]}'s given #{entry[:description].inspect} is ambiguous in this " \
-            "chapter — #{candidates.keys.join(", ")} each declare a DIFFERENT predicate " \
+            "bluebook — #{candidates.keys.join(", ")} each declare a DIFFERENT predicate " \
             "under this same description; name which one with declared_by: (e.g. " \
             "given(#{entry[:description].inspect}, declared_by: #{candidates.keys.first}))"
         end
 
-        def resolve_pending_chapter_entity_given(entry)
-          candidates = RuleReference.resolve_owner_keyed(@chapter_entity_named_givens, entry[:description])
+        def resolve_pending_bluebook_entity_given(entry)
+          candidates = RuleReference.resolve_owner_keyed(@bluebook_entity_named_givens, entry[:description])
           declarer   = entry[:declared_by]
           return candidates[declarer] || raise(Malformed, undeclared_entity_given_message(entry)) if declarer
           return candidates.values.first if candidates.size == 1
@@ -86,20 +86,20 @@ module Hecks
 
         def undeclared_entity_given_message(entry)
           "#{entry[:entity]}'s given #{entry[:description].inspect} names no precondition " \
-            "#{entry[:declared_by]} declares in this chapter — #{entry[:declared_by]} " \
+            "#{entry[:declared_by]} declares in this bluebook — #{entry[:declared_by]} " \
             "either hasn't declared #{entry[:description].inspect}, or declared_by: named the " \
             "wrong piece"
         end
 
         def unknown_entity_given_message(entry)
           "#{entry[:entity]}'s given #{entry[:description].inspect} names no precondition " \
-            "any piece in this chapter ever declares — declare it once with a block " \
+            "any piece in this bluebook ever declares — declare it once with a block " \
             "(some piece's own given(#{entry[:description].inspect}) { ... })"
         end
 
         def ambiguous_entity_given_message(entry, candidates)
           "#{entry[:entity]}'s given #{entry[:description].inspect} is ambiguous across the " \
-            "chapter's own pieces — #{candidates.keys.join(", ")} each declare a DIFFERENT " \
+            "bluebook's own pieces — #{candidates.keys.join(", ")} each declare a DIFFERENT " \
             "predicate under this same description; name which one with declared_by: (e.g. " \
             "given(#{entry[:description].inspect}, declared_by: #{candidates.keys.first.inspect}))"
         end

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

@@ -4,7 +4,7 @@ module Hecks
       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.
+          # every aggregate and value object in the bluebook exists.
           module ComputedSources
             private
 
@@ -26,8 +26,27 @@ module Hecks
             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)
+            # bluebook's value objects by name.
+            PathCheck = Struct.new(:aggregate, :command, :mutation, :value_objects) do
+              # @param name [String] a path's first segment
+              # @return [Bluebook::Attribute, nil] the command's argument by that name, else the
+              #   owner's field, else `nil`
+              def operand_head(name)
+                command.attributes.find { |attr| attr.name.to_s == name } ||
+                  aggregate.attributes.find { |attr| attr.name.to_s == name }
+              end
+
+              # A lifecycle or projected field is a plain scalar of the record.
+              #
+              # @param name [String] a path's first segment
+              # @return [Boolean] whether `name` is the owner's lifecycle or a projected field
+              def stored_scalar?(name)
+                aggregate.lifecycle_field.to_s == name || aggregate.projected_fields.any? { |f| f.name.to_s == name }
+              end
+
+              # @return [String] how a refusal names the source: `Owner.Command's sets :target`
+              def site = "#{aggregate.hecks_name}.#{command.hecks_name}'s sets :#{mutation.target}"
+            end
             private_constant :PathCheck
 
             def operand_paths(node)
@@ -39,25 +58,14 @@ module Hecks
 
             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)
+              attribute = check.operand_head(head)
+              return if attribute.nil? && segments.empty? && check.stored_scalar?(head)
 
-              refuse_operand!(check, path, "names no argument or field of #{check.aggregate.hecks_name}") unless attribute
+              owner = check.aggregate
+              refuse_operand!(check, path, "names no argument or field of #{owner.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?
@@ -86,9 +94,7 @@ module Hecks
             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}"
+              raise Malformed, "#{check.site} reads #{path}, which #{reason}"
             end
           end
         end

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

@@ -40,11 +40,9 @@ module Hecks
             end
 
             def reacted_events(process_manager)
-              ([process_manager.starts_on, process_manager.ends_on] + process_manager.handlers.map(&:event_type))
-                .compact
-                .reject { |event| event == ProcessManager::REFUSED }
-                .map { |event| event.to_s.split("::").last }
-                .uniq
+              events = [process_manager.starts_on, process_manager.ends_on] + process_manager.handlers.map(&:event_type)
+              answered = events.compact.reject { |event| event == ProcessManager::REFUSED }
+              answered.map { |event| Naming.demodulise(event) }.uniq
             end
 
             def emitting_commands(events, aggregates)

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

@@ -3,7 +3,7 @@ module Hecks
     module DSL
       class BluebookBuilder
         module Validation
-          # The commands of a chapter and the events they emit: every command that emits an event
+          # The commands of a bluebook and the events they emit: every command that emits an event
           # must agree on its shape, and the shapes and identities are looked up by event name.
           module EventShapes
             private
@@ -29,7 +29,7 @@ module Hecks
                     "an event is one fact, and every command that emits it must declare the same fields"
             end
 
-            # Yields every command the chapter declares with its owner's name
+            # Yields every command the bluebook declares with its owner's name
             # ("Aggregate.Entity" for entities).
             def each_command(aggregates)
               return enum_for(:each_command, aggregates) unless block_given?
@@ -42,7 +42,7 @@ module Hecks
               end
             end
 
-            # Not memoised: a chapter split across files is validated once per file, and a
+            # Not memoised: a bluebook split across files is validated once per file, and a
             # cached index would miss the commands later files add.
             def event_emitters(aggregates)
               each_command(aggregates).with_object(Hash.new { |h, k| h[k] = [] }) do |(owner, command), index|
@@ -108,7 +108,8 @@ module Hecks
             end
 
             def piece_named(aggregate, owner_name)
-              owner_name.to_s.split(".").drop(1).reduce(aggregate) do |owner, name|
+              path = owner_name.to_s.split(".")
+              path.drop(1).reduce(aggregate) do |owner, name|
                 owner&.entities&.find { |e| e.hecks_name == name }
               end
             end

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

@@ -10,14 +10,14 @@ module Hecks
 
             # 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,
+            # trigger addresses a row by. Nil when the query's aggregate is not in this bluebook,
             # 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_name = Naming.split_dotted(policy.for_each).first
               aggregate = aggregates.find { |candidate| candidate.hecks_name == aggregate_name }
               return nil unless aggregate
 
@@ -27,7 +27,7 @@ module Hecks
             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
+              aggregate.lifecycle ? names << aggregate.lifecycle_field.to_sym : names
             end
 
             def row_key_names(target, aggregate_name)

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

@@ -8,6 +8,13 @@ module Hecks
           HopSite = Struct.new(:aggregate, :query, :clause, :target) do
             # @return [String] how a refusal names the asking query: `Aggregate.Query`
             def label = "#{aggregate.hecks_name}.#{query.hecks_name}"
+
+            # @return [String, Symbol] the hopped field the clause asks about, as written
+            def asked_field = clause.field
+
+            # @param name [String] an attribute name
+            # @return [Bluebook::Attribute, nil] the hop target's attribute by that name, or `nil`
+            def target_attribute(name) = target.attributes.find { |candidate| candidate.name.to_s == name }
           end
           private_constant :HopSite
 
@@ -20,21 +27,21 @@ module Hecks
             # nothing), asked of the hop's target.
             def validate_hop_tail!(site, tail)
               name, *nested = tail.to_s.split(".")
-              attribute = site.target.attributes.find { |candidate| candidate.name.to_s == name }
+              attribute = site.target_attribute(name)
               return validate_hop_comparator!(site, attribute, nested) if hop_tail_scalar?(site.target, attribute, name, nested)
 
               refuse_hop_tail!(site, attribute, tail, nested)
             end
 
             def hop_tail_scalar?(target, attribute, name, nested)
-              return attribute || target.lifecycle&.field.to_s == name if nested.empty?
+              return attribute || target.lifecycle_field.to_s == name if nested.empty?
 
               attribute && QuerySpecification::FieldPath.scalar_leaf?(attribute, nested) { |type| target.value_object(type) }
             end
 
             def refuse_hop_tail!(site, attribute, tail, nested)
               target = site.target
-              asks = "#{site.label} asks about #{site.clause.field}, which hops to #{target.hecks_name} " \
+              asks = "#{site.label} asks about #{site.asked_field}, which hops to #{target.hecks_name} " \
                      "and then asks about #{tail}, which"
               raise Malformed, "#{asks} #{hop_tail_fault(target, attribute, nested)}"
             end
@@ -57,13 +64,14 @@ module Hecks
             # `AggregateBuilder#seal_ordered_comparator` deferred.
             def validate_hop_comparator!(site, attribute, nested)
               clause = site.clause
+              target = site.target
               return unless AggregateBuilder::ORDERED_COMPARATORS.include?(clause.op.to_s.to_sym)
-              return if attribute && numeric_hop_leaf?(site.target, attribute, nested)
+              return if attribute && numeric_hop_leaf?(target, attribute, nested)
 
               held = attribute ? "holds no number" : "is the lifecycle field, which holds text"
               raise Malformed,
                     "#{site.label} compares #{clause.field} with " \
-                    "#{clause.op} after hopping to #{site.target.hecks_name}, but the field it lands " \
+                    "#{clause.op} after hopping to #{target.hecks_name}, but the field it lands " \
                     "on #{held} — an ordered comparison needs a numeric field, and over " \
                     "anything else the adapters answer differently or not at all"
             end

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

@@ -4,7 +4,7 @@ module Hecks
       class BluebookBuilder
         module Validation
           # Checks that each `projects` reference resolves to an aggregate declaring the remote
-          # field as a scalar or single-field value object, once every aggregate in the chapter
+          # field as a scalar or single-field value object, once every aggregate in the bluebook
           # exists.
           module ProjectedFields
             private
@@ -43,14 +43,14 @@ module Hecks
             # `projected_fields` is separate from `attributes`, and a projected value is always a
             # scalar by construction, so a name match is enough there too.
             def implicit_projection_target?(target, tail)
-              target.lifecycle&.field.to_s == tail || target.projected_fields.any? { |f| f.name.to_s == tail }
+              target.lifecycle_field.to_s == tail || target.projected_fields.any? { |f| f.name.to_s == tail }
             end
 
             def refuse_unresolvable_projection!(aggregate, field, plan)
               raise Malformed,
                     "#{aggregate.hecks_name}.projects :#{field.name} reads through :#{field.reference}, " \
-                    "which hops to #{plan.hops.last.target_name}, which this chapter never declares — " \
-                    "a projection through an aggregate this chapter cannot see resolves to nothing"
+                    "which hops to #{plan.hops.last.target_name}, which this bluebook never declares — " \
+                    "a projection through an aggregate this bluebook cannot see resolves to nothing"
             end
 
             def refuse_undeclared_projection!(aggregate, field, target, plan)

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

@@ -3,121 +3,75 @@ module Hecks
     module DSL
       class BluebookBuilder
         module Validation
-          # Checks every `provides` row of a chapter against `Capabilities::CONTRACTS`.
+          # Checks every `provides` row of a bluebook: against `Capabilities::CONTRACTS` for a
+          # capability the language defines, and against the bluebook itself for one its package
+          # declares.
           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`.
+            # Checks every `provides` row, grouped by the capability it provides.
             def validate_provisions!(bluebook)
               bluebook.provides.group_by(&:capability).each do |capability, rows|
-                validate_provision!(bluebook, capability, rows)
+                refuse_repeated_provision_keys!(bluebook, capability, rows)
+                if Capabilities.language_defined?(capability)
+                  validate_defined_provision!(bluebook, capability, rows)
+                else
+                  rows.each { |row| validate_package_provision!(bluebook, capability, row) }
+                end
               end
             end
 
-            def validate_provision!(bluebook, capability, rows)
-              contract = Capabilities::CONTRACTS.fetch(capability) do
-                raise Malformed, "#{bluebook.name} provides #{capability.inspect}, which is no capability the " \
-                                 "language knows — known: #{Capabilities::CONTRACTS.keys.sort.join(", ")}"
-              end
+            def refuse_repeated_provision_keys!(bluebook, capability, rows)
+              repeated = repeated_keys(rows)
+              return if repeated.empty?
 
-              refuse_wrong_provision_keys!(bluebook, capability, rows, contract)
-              rows.each { |row| validate_provided_verb!(bluebook, capability, row, contract.fetch(row.key.to_sym)) }
+              raise Malformed, "#{bluebook.name} provides #{capability.inspect} with #{repeated.join(", ")} " \
+                               "more than once"
             end
 
-            def refuse_wrong_provision_keys!(bluebook, capability, rows, contract)
-              keys = rows.map { |row| row.key.to_sym }
-              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 #{provision_keys_phrase(required, contract.keys - required)}"
+            def repeated_keys(rows)
+              counts = rows.map(&:key).tally
+              counts.select { |_, count| count > 1 }.keys
             end
 
-            def provision_keys_valid?(keys, required, allowed)
-              (keys - allowed).empty? && (required - keys).empty? && keys.uniq.size == keys.size
+            def validate_defined_provision!(bluebook, capability, rows)
+              contract = Capabilities::CONTRACTS.fetch(capability)
+              refuse_wrong_provision_keys!(bluebook, capability, rows.map { |row| row.key.to_sym }, contract.keys)
+              rows.each { |row| validate_provided_verb!(bluebook, capability, row, contract.fetch(row.key.to_sym)) }
             end
 
-            def provision_keys_phrase(required, optional)
-              return "exactly #{required.join(", ")}" if optional.empty?
+            def refuse_wrong_provision_keys!(bluebook, capability, keys, needed)
+              return if keys.sort == needed.sort
 
-              "#{required.join(", ")} and may add #{optional.join(", ")}"
+              raise Malformed, "#{bluebook.name} provides #{capability.inspect} with #{keys.join(", ")}, but " \
+                               "#{capability} needs exactly #{needed.join(", ")}"
             end
 
             def validate_provided_verb!(bluebook, capability, row, kind)
-              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)
               return if aggregate && member && provided_member_names(aggregate, kind).include?(member)
 
               raise Malformed, "#{bluebook.name} provides #{capability.inspect} #{row.key}: #{row.verb.inspect}, " \
-                               "which names no #{kind} this chapter declares (spelled \"Aggregate.#{kind.capitalize}\")"
-            end
-
-            # Only the verb's shape and aggregate are checkable here: the port is declared
-            # in the hecksagon, which attaches after the chapter is built. `Registry#verify!`
-            # checks the operation.
-            def validate_provided_port_operation!(bluebook, capability, row)
-              aggregate_name, port, operation = row.verb.split(".", 3)
-              return if bluebook.aggregate(aggregate_name) && port && operation && !operation.include?(".")
-
-              raise Malformed, "#{bluebook.name} provides #{capability.inspect} #{row.key}: #{row.verb.inspect}, " \
-                               "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)"
+                               "which names no #{kind} this bluebook declares (spelled \"Aggregate.#{kind.capitalize}\")"
             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)
+            # A package-declared key must name exactly one thing the bluebook declares; which kind
+            # it
+            # names is what the reader of the capability is handed (`Capabilities.resolved_value`).
+            def validate_package_provision!(bluebook, capability, row)
+              kinds = Capabilities.kinds_of(bluebook, row.verb)
+              return if kinds.one?
 
               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)"
+                               "which #{package_provision_problem(kinds)}"
             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)
+            def package_provision_problem(kinds)
+              return "names #{kinds.join(" and ")} at once; rename one" if kinds.any?
 
-              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\")"
+              "names nothing this bluebook declares (spelled \"Aggregate.Command\", \"Aggregate.Query\", " \
+                "\"Aggregate.Port.Operation\", \"Aggregate.mark_name\" or \"Aggregate.attribute\")"
             end
 
             def provided_member_names(aggregate, kind)

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

@@ -6,7 +6,7 @@ module Hecks
       class BluebookBuilder
         module Validation
           # Resolves and checks the `where` hops that `AggregateBuilder` could only recognise at
-          # seal time: a hop needs the other aggregates, which exist once the chapter is assembled.
+          # seal time: a hop needs the other aggregates, which exist once the bluebook is assembled.
           module QueryHops
             include HopTails
 
@@ -58,7 +58,7 @@ module Hecks
             def inferred_hop_leaf(name, plan)
               target = plan.hops.last.target
               head, *nested = plan.tail.to_s.split(".")
-              return Attribute.new(name: name, type: String) if nested.empty? && target.lifecycle&.field.to_s == head
+              return Attribute.new(name: name, type: String) if nested.empty? && target.lifecycle_field.to_s == head
 
               found = hop_leaf(target, head, nested)
               found && Attribute.new(name: name, type: found.type, list: found.list?)
@@ -92,7 +92,7 @@ module Hecks
             end
 
             def refuse_hop_plan!(site, plan)
-              asks = "#{site.label} asks about #{site.clause.field}"
+              asks = "#{site.label} asks about #{site.asked_field}"
               case plan.refusal
               when :unresolvable then refuse_unresolvable_hop!(asks, plan)
               when :too_deep     then refuse_too_deep_hop!(asks)
@@ -103,8 +103,8 @@ module Hecks
             # is always there.
             def refuse_unresolvable_hop!(asks, plan)
               raise Malformed,
-                    "#{asks}, which hops to #{plan.hops.last.target_name}, which this chapter never " \
-                    "declares — a hop into an aggregate this chapter cannot see resolves to " \
+                    "#{asks}, which hops to #{plan.hops.last.target_name}, which this bluebook never " \
+                    "declares — a hop into an aggregate this bluebook cannot see resolves to " \
                     "nothing, and a where that resolves to nothing matches nothing and " \
                     "refuses nothing"
             end

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

@@ -3,18 +3,18 @@ module Hecks
     module DSL
       class BluebookBuilder
         module Validation
-          # Checks of how a chapter's aggregates point at each other: the chapter's own namespace,
+          # Checks of how a bluebook's aggregates point at each other: the bluebook's own namespace,
           # entity commands that root on themselves, and reference rings.
           module References
             private
 
-            # A chapter's constants install under its name, or its `namespace`; landing in the
+            # A bluebook's constants install under its name, or its `namespace`; landing in the
             # gem's own `Hecks` module would shadow the gem's modules (ADR 0080), so it refuses.
             def validate_not_the_gem_module!(bluebook)
               return unless (bluebook.namespace || bluebook.name) == "Hecks"
 
               raise Malformed, "#{bluebook.name}'s constants would install in the gem's own Hecks module — " \
-                               "declare a namespace, such as namespace \"Hecks::Domain\", or rename the chapter"
+                               "declare a namespace, such as namespace \"Hecks::Domain\", or rename the bluebook"
             end
 
             # Refuses an entity command that names its own entity as its root.
@@ -41,8 +41,8 @@ module Hecks
             end
 
             # A reference ring means no aggregate in it is a consistency boundary. Checked at
-            # chapter level because seeing a cycle needs every end declared (ADR 0025). Catches
-            # any ring length; self-reference stays legal, and a cross-chapter target is a
+            # bluebook level because seeing a cycle needs every end declared (ADR 0025). Catches
+            # any ring length; self-reference stays legal, and a cross-bluebook target is a
             # dangling name, not an edge.
             def validate_no_bidirectional_references!(aggregates)
               cycle = find_reference_cycle(reference_edges(aggregates))
@@ -95,7 +95,7 @@ module Hecks
 
             def first_cycle_through(targets, edges, state, path)
               targets.each do |target|
-                # a name this chapter never declares is dangling, not an edge
+                # a name this bluebook never declares is dangling, not an edge
                 next unless edges.key?(target)
 
                 found = reference_cycle_from(target, edges, state, path)

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

@@ -6,7 +6,7 @@ module Hecks
           # Checks `with:` projections of policies and saga legs against the source event's shape
           # and the target command's fields.
           module WithProjections
-            # What every `with:` check shares: the chapter's commands by "Owner.Command", its
+            # What every `with:` check shares: the bluebook's commands by "Owner.Command", its
             # aggregates, and the sagas' correlation heads.
             WithContext = Struct.new(:lookup, :aggregates, :correlation_heads)
             # One `with:` to check: the command it targets, the event it reads from, the spec
@@ -21,9 +21,9 @@ module Hecks
             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.
+            # Same-bluebook only: an unresolvable cross-bluebook source or target is skipped.
             # 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
+            # only when the query's aggregate is in this bluebook, 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))
@@ -73,10 +73,10 @@ module Hecks
             def readable_sources(spec, aggregates)
               pm = spec.process_manager
               event_name = spec.event_name
-              # A policy's source also carries the emitter's identity
-              # (`PolicyInterpreter#emitter_identity`); a saga leg's source
+              # A policy's source also carries the emitter's identity, under each head and as `:id`
+              # (`PolicyInterpreter#emitter_identity`, `#emitter_id`); a saga leg's source
               # (`SagaInterpreter#dispatch_args`) merges no such thing.
-              identity = pm.nil? && event_name ? event_identity_heads_for(event_name, aggregates) : []
+              identity = pm.nil? && event_name ? [*event_identity_heads_for(event_name, aggregates), :id] : []
               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, spec.row_names.to_a)