hecks 1.3.0 → 1.4.0

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

@@ -2,8 +2,8 @@ module Hecks
   module Bluebook
     module DSL
       class BluebookBuilder
-        # THE self.validate_*/self.correlation_*/self.event_*/self.walk_*
-        # CLUSTER — every whole-chapter, cross-aggregate check `#build`
+        # The self.validate_*/self.correlation_*/self.event_*/self.walk_*
+        # cluster — every whole-chapter, cross-aggregate check `#build`
         # runs once a chapter is fully assembled (reference targets, event
         # shapes, correlation keys, query hops, projected fields,
         # bidirectional-reference cycles), plus each one's own private
@@ -27,10 +27,10 @@ module Hecks
         # an instance method, matching what `def self.foo` already made
         # every one of these before the split.
         module Validation
-          # EVERY WHOLE-CHAPTER CHECK, IN ONE PLACE — the battery `#build`
+          # **Every whole-chapter check, in one place** — the battery `#build`
           # used to run inline, now a pure function of an assembled
           # `Bluebook::Chapter` so `MetaValidator.judge_deferred!` can run
-          # it too, once, on a chapter whose files have ALL loaded (see
+          # it too, once, on a chapter whose files have all loaded (see
           # `#build`'s own comment for why that split exists at all).
           # Public, not `private_class_method`'d, for exactly that second
           # caller — `MetaValidator` needs to reach this with no builder
@@ -49,12 +49,12 @@ module Hecks
 
             # Every hop AggregateBuilder#seal_query_field recognised and
             # deferred gets checked for real here — the earliest point a
-            # hop CAN be checked, for exactly the reason
+            # hop can be checked, for exactly the reason
             # validate_no_bidirectional_references! above already gives:
             # `Bluebook.new` just stamped `hecks_owner` on every
             # aggregate, so `Reference#resolve` finally has a chapter to
             # walk. Before this line every target in the file (including
-            # ones declared ABOVE the aggregate doing the asking) would
+            # ones declared above the aggregate doing the asking) would
             # have resolved to nil.
             infer_hop_query_arguments!(bluebook)
             validate_query_hops!(bluebook)
@@ -63,27 +63,64 @@ module Hecks
             # own reference cannot resolve until every aggregate in the
             # chapter is real and owner-stamped (S12, ADR 0025).
             validate_projected_fields!(bluebook)
+
+            validate_provisions!(bluebook)
+          end
+
+          # **What a declared capability must name**. A `provides` row is only
+          # worth trusting in place of a name check if it is checked: an
+          # unknown capability, a missing or extra key, or a verb that is
+          # not this chapter's own command/query of the right kind would
+          # otherwise wire a role check to nothing, in silence.
+          def validate_provisions!(bluebook)
+            bluebook.provides.group_by(&:capability).each do |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
+
+              keys = rows.map { |row| row.key.to_sym }
+              unless keys.sort == contract.keys.sort
+                raise Malformed, "#{bluebook.name} provides #{capability.inspect} with #{keys.join(', ')}, but " \
+                                 "#{capability} needs exactly #{contract.keys.join(', ')}"
+              end
+
+              rows.each { |row| validate_provided_verb!(bluebook, capability, row, contract.fetch(row.key.to_sym)) }
+            end
+          end
+
+          def validate_provided_verb!(bluebook, capability, row, kind)
+            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
+
+          def provided_member_names(aggregate, kind)
+            kind == :command ? aggregate.commands.map(&:hecks_name) : aggregate.queries.map(&:name)
           end
 
-          # AN ENTITY COMMAND MAY NOT NAME ITSELF AS ITS ROOT.
+          # An entity command may not name itself as its root.
           #
           # That is the whole of what is left here, and it needs saying plainly
           # because the sentence this used to raise — "references must target
           # aggregate heads" — was never what it checked.
           #
-          # `CommandBuilder#reference_to` sets `references` ONLY when the target's
+          # `CommandBuilder#reference_to` sets `references` only when the target's
           # bare name equals the owner's ; anything else becomes a reference
-          # ATTRIBUTE. So on an aggregate command `references` is always a copy of
+          # attribute. So on an aggregate command `references` is always a copy of
           # that aggregate's own name, and looking it up in an index of aggregates
-          # is a TAUTOLOGY — that branch never refused anything and structurally
+          # is a tautology — that branch never refused anything and structurally
           # could not. Verified across all eight golden chapters before deleting it.
           #
-          # On a PIECE's command the owner is the entity, and an entity is not a
+          # On a piece's command the owner is the entity, and an entity is not a
           # head, so what this actually refuses is `reference_to <its own name>`
-          # written inside `entity do … end`. A piece is reached THROUGH its
+          # written inside `entity do … end`. A piece is reached through its
           # aggregate ; a command on one addresses the aggregate, never the piece.
           #
-          # Reference ATTRIBUTES are the language's business now — offered as the
+          # Reference attributes are the language's business now — offered as the
           # head's own id and resolved as references, so `Aggregate.Reference` and
           # `Command.Reference` refuse an undeclared head with no predicate at all.
           def validate_reference_value_objects!(aggregates)
@@ -106,19 +143,19 @@ module Hecks
                   "an entity command is addressed through its aggregate; #{violations.uniq.join('; ')}"
           end
 
-          # EVENTS ARE FIRST-CLASS BY CONVENTION, NOT BY DECLARATION (ADR
+          # Events are first-class by convention, not by declaration (ADR
           # 0025, "events and reactions" — "a domain event is a value
           # object with its own attributes, not a label"). No new `event
           # do ... end` construct exists to hand-author and keep in step
           # with every emitting command by hand — an event's own known
-          # shape IS whichever command(s) declare `emits` for its name, and
-          # this is the ONE thing that has to hold for that convention to
+          # shape is whichever command(s) declare `emits` for its name, and
+          # this is the one thing that has to hold for that convention to
           # mean anything: every command that emits a given name has to
           # agree on what it carries. An event is one fact; a fact does not
           # carry two different truths depending on who is telling it.
           #
-          # STRUCTURAL fields only (name/type/list/optional) — `pattern:`/
-          # `admits:`/`default:` are refinements ON a field, not a second
+          # Structural fields only (name/type/list/optional) — `pattern:`/
+          # `admits:`/`default:` are refinements on a field, not a second
           # claim about what the payload holds, so two emitting commands
           # are free to differ there without actually disagreeing about
           # the event's own shape.
@@ -136,26 +173,26 @@ module Hecks
             end
           end
 
-          # THE "EXPENSIVE HALF" the ADR names: "with: { account: :account }
+          # The "expensive half" the ADR names: "with: { account: :account }
           # projecting into a reaction that has no declared contract ...
           # breaks at dispatch rather than at load." Checked here, now that
           # `validate_event_shapes!` (above) guarantees at most one real
           # shape per event name, and command references being first-class
-          # (`Naming.command_ref`) means the TARGET side is a real
+          # (`Naming.command_ref`) means the target side is a real
           # resolvable command, not a string that might be a typo.
           #
-          # SAME-CHAPTER ONLY, ON PURPOSE — a `with:` whose source event or
+          # **Same-chapter only, on purpose** — a `with:` whose source event or
           # target command lives outside this chapter (an `across` policy
           # reacting to another domain's event entirely) is silently left
           # unchecked rather than refused: there is nothing here yet to
           # check it against, and "unresolvable" is not the same claim as
           # "wrong."
           #
-          # A FOR_EACH POLICY'S SOURCE ISN'T THE EVENT AT ALL — a fan-out
-          # `with:`'s symbols read the QUERY ROW `for_each` answers
+          # A FOR_EACH policy's source isn't the event at all — a fan-out
+          # `with:`'s symbols read the query row `for_each` answers
           # (FreezeAccountsOnSuspension's own comment: "`account` is the
           # key the fan-out merges for each row"), which this has no shape
-          # for; the SOURCE half is skipped for those, the TARGET half
+          # for; the source half is skipped for those, the target half
           # (does the dispatched command actually declare the field) still
           # runs, since that half is true regardless of where the value
           # came from.
@@ -184,11 +221,11 @@ module Hecks
           end
 
           # `process_manager:` is present only for a process manager's own dispatch — a
-          # saga leg's source symbol resolves against the CURRENT triggering
+          # saga leg's source symbol resolves against the current triggering
           # event first, same as a policy, but falls all the way back to the
-          # saga's own MEMORY when the current event does not carry it
+          # saga's own memory when the current event does not carry it
           # (`SagaInterpreter#dispatch_args`, its own last `else`) — and
-          # memory starts as the OPENING event's payload
+          # memory starts as the opening event's payload
           # (`SagaInterpreter#instance = { ..., memory: event.payload }`,
           # never updated after), never the leg's own. Settlement's own
           # comment names exactly this: "the credit leg reads a destination
@@ -211,7 +248,7 @@ module Hecks
             source_shape  = event_name && event_shape_for(event_name, aggregates)
             memory_shape  = process_manager && event_shape_for(process_manager.starts_on, aggregates)
             correlation   = process_manager&.correlates_by && process_manager.correlation_head
-            # A POLICY'S SOURCE ALSO CARRIES THE EMITTER'S OWN IDENTITY —
+            # A policy's source also carries the emitter's own identity —
             # `PolicyInterpreter#emitter_identity`, the runtime half of this.
             # An entity command's event never declares its aggregate's
             # identity (it arrives through `reference_to`, not an
@@ -243,15 +280,15 @@ module Hecks
             end
           end
 
-          # A command's OWN `reference_to` (bare, no `as:`) never lands in
+          # A command's own `reference_to` (bare, no `as:`) never lands in
           # `attributes` — `CommandBuilder#reference_to`'s self-reference
           # branch sets `command.references` instead (S2), and mints no new
-          # field at all. What addresses it is not one name but the SAME
-          # SET `CommandInterpreter::ArgumentGate#refuse_unknown_arguments`
+          # field at all. What addresses it is not one name but the same
+          # set `CommandInterpreter::ArgumentGate#refuse_unknown_arguments`
           # already accepts at dispatch time — `:id`, the owning aggregate's
           # own `identity_heads` (real corpus proof — `Account.Debit`
           # dispatched everywhere as `number: ...`, `Account`'s own
-          # `identified_by`), AND `Naming.reference_key(command.references)`
+          # `identified_by`), and `Naming.reference_key(command.references)`
           # (real corpus proof — `FreezeAccountsOnSuspension`'s `for_each`
           # fan-out, whose own comment reads "`account` is the key the
           # fan-out merges for each row it answers"). Both are simultaneously
@@ -271,9 +308,9 @@ module Hecks
             referenced.identity_heads.include?(field) || Naming.reference_key(command.references) == field
           end
 
-          # THE FOURTH addressing key `ArgumentGate#refuse_unknown_arguments`
+          # The fourth addressing key `ArgumentGate#refuse_unknown_arguments`
           # accepts, alongside `:id`/`identity_heads`/`reference_key` — every
-          # saga in THIS domain's own `correlates_by` head, carried through
+          # saga in this domain's own `correlates_by` head, carried through
           # every dispatch as pure passthrough (Settlement's own comment:
           # "`reference:` carries the correlation forward... this is pure
           # passthrough, not an addressing key"). A command declaring none of
@@ -283,7 +320,7 @@ module Hecks
             process_managers.filter_map { |pm| pm.correlates_by && pm.correlation_head }
           end
 
-          # Every command this chapter declares, an aggregate's own AND
+          # Every command this chapter declares, an aggregate's own and
           # every entity nested inside one, paired with a name for what
           # declares it — shared by `validate_event_shapes!` and
           # `validate_with_projections!`'s own command lookup, the same
@@ -299,9 +336,9 @@ module Hecks
             end
           end
 
-          # NOT MEMOISED — this used to be `@event_emitters ||=` on the
+          # **Not memoised** — this used to be `@event_emitters ||=` on the
           # builder instance, which is safe for a one-file chapter but
-          # wrong for one split across several: the FIRST file's build()
+          # wrong for one split across several: the first file's build()
           # call would compute and cache it from whatever `@aggregates`
           # held at that moment, and every later file's own validation
           # would keep reading that same stale snapshot, silently missing
@@ -314,26 +351,26 @@ module Hecks
             end
           end
 
-          # STRUCTURAL, NOT NOMINAL. Two commands on two different
+          # **Structural, not nominal**. Two commands on two different
           # aggregates that both `emits "SameEvent"` are free to type a
-          # field through two DIFFERENT, locally-scoped wrapper value
+          # field through two different, locally-scoped wrapper value
           # objects (e.g. one aggregate's own `value: SomeText` vs
           # another's `value: OtherText`, exactly the per-aggregate "own
           # text VO" convention every aggregate in this grammar already
           # follows for everything from `RuleText` to `FieldRef`) without
           # actually disagreeing about the event's shape — comparing
-          # `a.type` by NAME would flag that as a violation for no real
+          # `a.type` by name would flag that as a violation for no real
           # reason: an event is one fact, and two isomorphic wrapper types
           # tell an identical one. So a value-object type is unwrapped to
-          # its OWN attribute shape (recursively — a wrapper could itself
+          # its own attribute shape (recursively — a wrapper could itself
           # wrap another) before comparing, and only a primitive type
           # (nothing left to unwrap) or two VOs that truly differ once
           # unwrapped still counts as a real mismatch. `owner` carries the
           # type's `value_object` lookup — a command's own attributes only
-          # know their type's NAME, never the aggregate that declared it,
+          # know their type's name, never the aggregate that declared it,
           # and two sibling aggregates in one chapter each keep a
           # same-named VO private to themselves, so the unwrap has to ask
-          # the SAME aggregate the field's own command belongs to, never a
+          # the same aggregate the field's own command belongs to, never a
           # neighbor's.
           def event_shape(command, owner)
             command.attributes.map { |a| [a.name, unwrap_shape(owner, a.type.to_s), a.list?, a.optional?] }.sort
@@ -351,10 +388,10 @@ module Hecks
             shape.attributes.map { |a| [a.name, unwrap_shape(owner, a.type.to_s, seen + [type_name]), a.list?, a.optional?] }.sort
           end
 
-          # `owner` (from `each_command`) is a plain STRING — the aggregate's
+          # `owner` (from `each_command`) is a plain string — the aggregate's
           # `hecks_name` alone, or `"Aggregate.Entity"` for an entity's own
-          # command. Either way the VALUE OBJECTS a command's fields can be
-          # typed with are the AGGREGATE's own (`Entity` carries no
+          # command. Either way the value objects a command's fields can be
+          # typed with are the aggregate's own (`Entity` carries no
           # `value_object` lookup of its own — the whole rest of this file
           # already resolves hop/type lookups only at the aggregate level,
           # e.g. `validate_hop_tail!`'s `target.value_object(type)`), so only
@@ -372,7 +409,7 @@ module Hecks
           end
 
           # The identity heads of the aggregate that emits `event_name` — an
-          # entity's event is stamped with its OWNING aggregate's identity
+          # entity's event is stamped with its owning aggregate's identity
           # (`Event#id` is the parent's), so an owner spelled "Game.Knight"
           # answers Game's heads.
           def event_identity_heads_for(event_name, aggregates)
@@ -384,7 +421,7 @@ module Hecks
             return [] unless aggregate
 
             heads = aggregate.identity_heads.map(&:to_sym)
-            # AN ENTITY'S EVENT ALSO CARRIES THE PIECE'S OWN IDENTITY — the
+            # An entity's event also carries the piece's own identity — the
             # args a piece was addressed by are the args its event announces
             # (`Emission#emit`: `payload: args`), so `id`-shaped heads are
             # genuinely there at runtime even though no `attribute` line on
@@ -400,9 +437,9 @@ module Hecks
             end
           end
 
-          # A REFERENCE RING IS NOT A MODELLING CHOICE, IT IS A MISSING ONE
+          # A reference ring is not a modelling choice, it is a missing one
           # — a DDD aggregate is a consistency boundary precisely because
-          # something outside it can only ever point IN, by id, never the
+          # something outside it can only ever point in, by id, never the
           # other way. A caller must be able to reason about one aggregate
           # alone ; a ring back to where it started means no aggregate in
           # it is a boundary anyone can reason about without the rest of
@@ -414,11 +451,11 @@ module Hecks
           # aggregate finishes building long before it can know whether
           # some later aggregate in the same file points back at it.
           #
-          # ACYCLIC WITHIN A CHAPTER (ADR 0025, "References") — widened
+          # Acyclic within a chapter (ADR 0025, "References") — widened
           # from the direct pair (A -> B -> A) this used to catch alone to
           # any ring, however long (A -> B -> C -> A), the same DFS
           # coloring a reference graph needs for any cycle. A cross-chapter
-          # reference is UNREACHABLE here rather than unchecked:
+          # reference is unreachable here rather than unchecked:
           # `Reference#resolve` is scoped to its own chapter by
           # construction, so a target this chapter never declares is a
           # dangling name, not an edge — `edges.key?` below is what keeps
@@ -443,7 +480,7 @@ module Hecks
           end
 
           # Plain DFS with a visiting/done coloring, over the reference
-          # graph THIS chapter's own aggregates declare. Returns the ring
+          # graph this chapter's own aggregates declare. Returns the ring
           # itself (in the order it closes), or nil.
           def find_reference_cycle(edges)
             state = {}
@@ -475,10 +512,10 @@ module Hecks
             nil
           end
 
-          # THE OTHER HALF OF A HOP — AggregateBuilder#seal_query_field
-          # recognised the HEAD of a dotted where-field that names one of
+          # **The other half of a hop** — AggregateBuilder#seal_query_field
+          # recognised the head of a dotted where-field that names one of
           # its own references and deferred it here, unable to check
-          # further: it cannot yet resolve what the reference points AT.
+          # further: it cannot yet resolve what the reference points at.
           # This runs once every aggregate exists in one chapter, so it
           # can.
           #
@@ -486,11 +523,11 @@ module Hecks
           # refused outright, immediately, back in seal_query_field
           # itself (that answer never needed the target's shape).
           #
-          # AN ENTITY'S OWN QUERIES DID reach `EntityBuilder#reference_to`
+          # An entity's own queries did reach `EntityBuilder#reference_to`
           # (added after this comment first claimed otherwise — S9, ADR
-          # 0025) without ever reaching HERE: tier-1 sealing
+          # 0025) without ever reaching here: tier-1 sealing
           # (`AggregateBuilder#query_surfaces`) already recognises a hop
-          # on an entity's own field and DEFERS it exactly like an
+          # on an entity's own field and defers it exactly like an
           # aggregate's, but nothing ever walked entity queries at tier 2
           # to check the deferral — a bad hop, or even a well-formed one,
           # built silently and then matched nothing at runtime
@@ -540,7 +577,7 @@ module Hecks
             end
           end
 
-          # THE LEAF `infer_hop_query_arguments!` INFERS for one resolved
+          # The leaf `infer_hop_query_arguments!` infers for one resolved
           # hop plan — a pure function of `plan` and the symbolic `name`
           # it is naming, pulled out because it is a self-contained
           # computation with no dependency on the enclosing loop's own
@@ -602,10 +639,10 @@ module Hecks
             validate_hop_tail!(aggregate, query, clause, target, plan.tail)
           end
 
-          # The same three-way answer seal_query_field gives for its OWN
+          # The same three-way answer seal_query_field gives for its own
           # aggregate's fields — landing on a real scalar (fine), landing
           # on a value object (refused by name), or naming nothing at all
-          # (refused by name) — asked instead of the hop's TARGET aggregate,
+          # (refused by name) — asked instead of the hop's target aggregate,
           # since that is whose shape the tail actually has to answer for.
           def validate_hop_tail!(aggregate, query, clause, target, tail)
             name, *nested = tail.to_s.split(".")
@@ -632,11 +669,11 @@ module Hecks
                   "not exist matches nothing and refuses nothing"
           end
 
-          # A WHERE hop with an ordered comparator is legitimate ("client
+          # A where hop with an ordered comparator is legitimate ("client
           # whose balance > 500") — AggregateBuilder#seal_ordered_comparator
           # already deferred this exact check for the same reason every
           # other hop check is deferred, and this is where it gets asked,
-          # against the hop's TARGET instead of the querying aggregate.
+          # against the hop's target instead of the querying aggregate.
           def validate_hop_comparator!(aggregate, query, clause, target, attribute, nested)
             return unless AggregateBuilder::ORDERED_COMPARATORS.include?(clause.op.to_s.to_sym)
             return if attribute &&
@@ -650,10 +687,10 @@ module Hecks
                   "anything else the adapters answer differently or not at all"
           end
 
-          # THE TARGET HALF of `projects` validation (S12, ADR 0025) —
+          # The target half of `projects` validation (S12, ADR 0025) —
           # `AggregateBuilder#seal_projected_fields` already checked the
-          # LOCAL half at declare time (the reference names a real
-          # `reference_to` on THIS aggregate); this checks the reference
+          # local half at declare time (the reference names a real
+          # `reference_to` on this aggregate); this checks the reference
           # actually resolves to a real aggregate in this chapter, and
           # that aggregate really declares `remote_field` as a scalar.
           #
@@ -671,7 +708,7 @@ module Hecks
             end
           end
 
-          # A linear decision tree of validation rules over ONE resolved
+          # A linear decision tree of validation rules over one resolved
           # hop plan, each already explained by its own comment above
           # (the lifecycle fallback, the chained-projection fallback, the
           # final scalar check) — a fixed, closed sequence "resolve, then
@@ -693,17 +730,17 @@ module Hecks
             target = plan.hops.last.target
             remote_attribute = target.attributes.find { |candidate| candidate.name.to_s == plan.tail }
 
-            # THE WORKED EXAMPLE ITSELF (ADR 0025) reads through a
-            # LIFECYCLE field — banking's Customer.status is `lifecycle
+            # The worked example itself (ADR 0025) reads through a
+            # lifecycle field — banking's Customer.status is `lifecycle
             # :status`, never a plain `attribute` — the same fallback
             # validate_hop_tail! already gives a query's own hop tail. A
             # lifecycle field is always a plain string by construction ;
             # nothing further to check once it matches by name.
             return if remote_attribute.nil? && target.lifecycle&.field.to_s == plan.tail
 
-            # A PROJECTION MAY CHAIN THROUGH ANOTHER PROJECTION (S12, ADR
+            # A projection may chain through another projection (S12, ADR
             # 0025's own boundary rule, followed through) — `target`'s
-            # OWN projected fields live in `projected_fields`, a
+            # own projected fields live in `projected_fields`, a
             # separate list from `attributes`, so a match there is
             # invisible to the check above even though it names a real,
             # always-current, stored field. `Transfer.projects
@@ -737,10 +774,10 @@ module Hecks
             !attribute.list? && !attribute.reference? && target.value_object(attribute.type).nil?
           end
 
-          # `correlates_by` NAMES A SCALAR, NOW CHECKED RATHER THAN TRUSTED.
+          # `correlates_by` names a scalar, now checked rather than trusted.
           #
           # ProcessManagerBuilder#validate! already refuses a bare, undotted
-          # spelling — a SYNTACTIC guarantee that the declaration cannot leave
+          # spelling — a syntactic guarantee that the declaration cannot leave
           # the question open. It cannot go further: a process manager is built
           # in isolation, before this chapter's aggregates exist to check
           # against. Here, with the whole document assembled, the dotted path