hecks 2.8.0 → 2.9.0

data/lib/hecks/bluebook/meta_validator/plan.rb

@@ -1,44 +1,11 @@
 module Hecks
   module Bluebook
     module MetaValidator
-      # What the language says about itself, read back as something walkable.
-      #
-      # ## Why a plan, not a hand-written branch per category
-      #
-      # "Which append command belongs to which list is not derivable from a
-      # name" sounds like a reason to hand-write one branch per category —
-      # and is beside the point. It is derivable from the language's own IR,
-      # because every append command declares its target:
-      #
-      #     command "Argument" do
-      #       reference_to Command
-      #       then_set :arguments, append: { name: :name, type: :type, ... }
-      #     end
-      #
-      # That one line says both things a walk needs: `Command.Argument` is the
-      # appender for the `arguments` list, and the map binds each value-object
-      # field to the command argument that fills it. Nothing is matched by name.
-      #
-      # The same reading recovers the containment tree. A command with no
-      # self-reference is the creating one, and the `*_id` argument it carries
-      # names the parent — so Bluebook -> Aggregate -> Command / ValueObject /
-      # Query / Entity, ValueObject -> Member, ProcessManager -> Handler ->
-      # Dispatch all fall out of the declarations rather than being restated here.
-      #
-      # ## Usage
-      #
-      #     plan = Plan.for(MetaValidator.grammar_registry)
-      #     plan.category("Command").parent            # => "Aggregate"
-      #     plan.category("Command").appends["rules"]  # => Append(verb: "Rule", map: {...})
-      #     plan.verbs                                 # every Bluebook:: verb declared
-      #
-      # This reads the language. It does not read a bluebook and it dispatches
-      # nothing — that is the judge's job.
+      # The language's own self-description, read back as a walkable structure:
+      # which command appends to which list, and how the containment tree nests.
       class Plan
         # One append command: the verb, and the value-object-field -> argument map.
-        # `:map` shadows Enumerable#map on purpose — `spec/plan_spec.rb`
-        # itself asserts `appends["emits"].map` reads the field (a Hash),
-        # not an Enumerable#map result. Verified before disabling this cop.
+        # `:map` shadows Enumerable#map on purpose; spec/plan_spec.rb asserts on it.
         # rubocop:disable-next Lint/StructNewOverride
         Append = Struct.new(:verb, :map, keyword_init: true)
 
@@ -50,9 +17,8 @@ module Hecks
                               :appends, :alternates, :setters, :sealers, :references,
                               :identity_paths, :entity_owned,
                               keyword_init: true) do
-          # Every verb this category declares, in declaration order. `alternates`
-          # matters here: two commands can append to one list, and a verb missing
-          # from this is a verb the coverage gate stops watching.
+          # Every verb this category declares, in declaration order; a verb missing
+          # here is one the coverage gate stops watching.
           #
           # @return [Array<String>] every command name this category declares
           #   (the creating command, every setter, appender, alternate
@@ -62,10 +28,7 @@ module Hecks
              *alternates.map(&:verb), *sealers].compact
           end
 
-          # Does this argument carry an ID? A reference is the id of a head, and
-          # an id is a scalar — so the judge offers it bare, where every other
-          # field goes as a one-field value object. The language answers this
-          # about itself, so declaring a new reference needs no change here.
+          # Whether `argument` on `verb` carries an ID rather than a value.
           #
           # @param verb [String] the command name declaring `argument`
           # @param argument [String] the argument name to check
@@ -74,11 +37,7 @@ module Hecks
             Array(references[verb.to_s]).include?(argument.to_s)
           end
 
-          # Reports whether this category is the root of the containment
-          # tree.
-          #
-          # @return [Boolean] whether this category has no parent — the root
-          #   of the containment tree
+          # Whether this category has no parent — the root of the containment tree.
           def root? = parent.nil?
         end
 
@@ -105,38 +64,12 @@ module Hecks
 
             @categories[aggregate.hecks_name] = read(aggregate)
 
-            # S17, ADR 0026 — Member/Handler/Dispatch are entities now
-            # (`entity "Member" do ... end`, nested under `ValueObject`/
-            # `ProcessManager`/`Handler`), not their own top-level
-            # aggregates — so `meta.aggregates` alone does not find
-            # them the way it always found a standalone `aggregate
-            # "Member"`. Each still needs its own named category here:
-            # `Assembly::Contracts` keeps a bespoke entry for each
-            # (Member's own open-map `pairs`, Dispatch's own open-map
-            # `with_spec`), distinct from the single generic "Entity"
-            # category every ordinary real-corpus entity (LedgerEntry,
-            # Withdrawal, ...) is described through instead. Safe to
-            # walk every meta-domain aggregate's own `.entities`
-            # unconditionally — `Plan` only ever reads the meta-
-            # domain's own self-description (`Plan.for(MetaValidator.
-            # grammar_registry)`), which never declares a generic,
-            # nameless entity of its own the way a real domain's
-            # `LedgerEntry` is; the only entities the meta-domain
-            # itself ever declares are exactly the three this ADR
-            # names. `entity_owned: true` records why this is a
-            # category at all — the real runtime has no top-level
-            # aggregate named "Member" to dispatch a bare verb into,
-            # so the judge has to build a dotted one instead
-            # (see `Judge#verb_for`).
-            #
-            # Recurses — `Dispatch` nests inside `Handler`, which nests
-            # inside `ProcessManager`, two levels deep, not one. Each
-            # nested entity's own `parent` names the direct owner it was
-            # actually found under (Dispatch's is "Handler", not
-            # "ProcessManager") — `read`'s own `owner:` argument already
-            # takes whichever name is passed, so walking one level deeper
-            # each recursive call is the whole change; nothing about
-            # `read` itself needed to know how deep it was called from.
+            # Member, Handler and Dispatch are entities nested under their
+            # owning aggregate (ADR 0026), so `meta.aggregates` alone never
+            # finds them; `add_nested_entities` walks each aggregate's own
+            # `.entities`, recursing (Dispatch nests inside Handler inside
+            # ProcessManager), with `entity_owned: true` marking that this
+            # category has no top-level aggregate a bare verb can dispatch into.
             add_nested_entities(aggregate)
           end
           @categories.freeze
@@ -156,16 +89,7 @@ module Hecks
         def names          = @categories.keys
 
         # Every verb the language declares, spelled as the judge would
-        # dispatch it. S17, ADR 0026 — an entity-owned category (its
-        # own `entity_owned` flag) has no real top-level aggregate the
-        # runtime can route a bare verb into, so it is
-        # spelled dotted here too — `Bluebook::ValueObject.Member.
-        # Declare`, `Bluebook::ProcessManager.Handler.Dispatch.Bind` —
-        # matching `Judge#verb_for`/`#dotted_prefix`'s own build
-        # exactly (recursing the same way, for the same reason: an
-        # entity-owned category's own parent may itself be entity-
-        # owned), so this stays what it already is: the judge's own
-        # coverage promise, not a second guess at it.
+        # dispatch it — entity-owned categories dotted to match `Judge#verb_for`.
         #
         # @return [Array<String>] every verb the language declares, dotted
         #   and prefixed with `"Bluebook::"`, such as `"Bluebook::Aggregate.
@@ -178,13 +102,8 @@ module Hecks
 
         private
 
-        # Walks one construct's own `.entities`, recursing into each
-        # found entity's own `.entities` in turn — S17, ADR 0026's
-        # two-level chain (`Dispatch`, inside `Handler`, inside
-        # `ProcessManager`). `owner` is passed down explicitly rather
-        # than re-derived, because it names whichever construct this
-        # call actually found the entity under — the direct parent, not
-        # the root.
+        # Recurses to handle ADR 0026's two-level entity chain (Dispatch inside
+        # Handler inside ProcessManager).
         def add_nested_entities(owner)
           owner.entities.each do |entity|
             next if entity.commands.empty?
@@ -194,12 +113,7 @@ module Hecks
           end
         end
 
-        # The full dotted prefix a category's own verbs hang off —
-        # mirrors `Judge#dotted_prefix` exactly (S17, ADR 0026): the
-        # plain name for an ordinary category, or its parent's own
-        # prefix with this category's name appended, for an entity-
-        # owned one, recursing because the parent may itself be
-        # entity-owned.
+        # Mirrors `Judge#dotted_prefix` exactly; must agree for entity-owned categories.
         def dotted_prefix(name)
           found = category(name)
           return name unless found&.entity_owned
@@ -207,30 +121,11 @@ module Hecks
           "#{dotted_prefix(found.parent)}.#{name}"
         end
 
-        # `owner:`/`entity_owned:` — S17, ADR 0026. An aggregate-level
-        # creating command carries its own parent as a `reference_to`
-        # argument (read via `parent_reference_of` below), the same
-        # way it always has. An entity-level one never does — `entity
-        # "Member" do ... end`'s own creating command reaches its
-        # parent through the dotted call itself (`ValueObject.Member.
-        # Declare`), the same reason an ordinary entity's own commands
-        # never declare `reference_to` either (entity.md's own
-        # reference page states this). So the owning aggregate's name
-        # is passed in directly here, by the caller who already knows
-        # it (the same `.entities` walk that found this node), rather
-        # than derived from an argument that was never going to be
-        # there.
+        # `owner` is passed in explicitly: an entity's own creating command
+        # never carries a `reference_to` argument to derive it from.
         def read(aggregate, owner: nil, entity_owned: false)
-          # An entity-owned category has no creating command of its own to find.
-          # `creating_command` tests `command.references.nil?` — the same test
-          # a real entity's own commands pass too, since `entity "Member" do
-          # command "Pair" ... end end` never writes `reference_to` (an
-          # entity's commands never do — banking's own LedgerEntry.Amend
-          # doesn't either). Calling it here would have it seize on Member's
-          # own "Pair" and call that the creating command, which it is not:
-          # a Member is created by `ValueObject.Member`, its owner's own bare
-          # append command, the same way a real LedgerEntry is created by
-          # `Account.LogEntry`, never by a dotted verb of its own.
+          # entity_owned skips declaration_command: an entity's own commands
+          # never carry `reference_to`, so it would misidentify one as creating.
           declare    = entity_owned ? nil : declaration_command(aggregate)
           parent     = parent_relationship_of(aggregate)
           parent_key = owner ? "aggregate" : parent&.name&.to_s
@@ -249,19 +144,14 @@ module Hecks
             # Every command, not `rest` — the creating command carries the parent
             # link, which is the most common reference of all.
             references:     references_in(aggregate.commands),
-            # How the category names its records, read from the language rather
-            # than restated. The judge has to know a record's id before it
-            # dispatches, because the children it walks next carry it as their
-            # parent — so it derives the same join the runtime will, off the same
-            # declaration: a hand-written branch per category, disagreeing with
-            # the runtime by even one separator, would be a broken reference.
+            # Read from the language, not restated: a hand-written join here
+            # could disagree with the runtime's own by even one separator.
             identity_paths: aggregate.identity_paths,
             entity_owned:   entity_owned
           )
         end
 
-        # Which arguments of which verbs carry an ID rather than a value, read
-        # straight from the language's own IR.
+        # Which arguments of which verbs carry an ID, read straight off the IR.
         def references_in(commands)
           commands.each_with_object({}) do |command, found|
             named = command.attributes.select(&:reference?).map { |attribute| attribute.name.to_s }
@@ -269,12 +159,7 @@ module Hecks
           end
         end
 
-        # The declaration command establishes the record's declared identity.
-        # Receiver references never carried that meaning; entity-owned categories
-        # prove it because every one of their commands lacks such a marker. The
-        # identity-write rule is structural and remains true after routing moves
-        # entirely into `to:`. `owner_id` is traversal context rather than stored
-        # state, so the declaration establishes every remaining identity head.
+        # `owner_id` is excluded: it's traversal context, not stored identity state.
         def declaration_command(aggregate)
           required = aggregate.identity_heads.map(&:to_sym) - [:owner_id]
           candidates = aggregate.commands.select do |command|
@@ -289,19 +174,13 @@ module Hecks
                 "its identity fields #{required.join(', ')} — found #{candidates.map(&:hecks_name).join(', ')}"
         end
 
-        # Containment belongs to stored aggregate structure. The first declared
-        # structural relationship is the traversal parent; command arguments may
-        # carry its identity as an ordinary value object, but do not define it.
+        # The first declared reference attribute is the traversal parent.
         def parent_relationship_of(aggregate)
           aggregate.attributes.find(&:reference?)
         end
 
-        # What the creating command sets directly. Every reference
-        # argument is dropped, not just the parent link: a reference is
-        # not a field. Command.Declare carries `entity_id` as well as
-        # the parent `aggregate` reference, because an entity declares
-        # commands too, and offering either as a field would have the
-        # walk hand it a name instead of a head.
+        # Every reference argument is dropped, not just the parent link:
+        # a reference is not a field.
         def declared_fields(declare)
           return [] unless declare
 
@@ -314,21 +193,15 @@ module Hecks
             Array(command.mutations).each do |mutation|
               next unless mutation.op == :append
 
-              # First wins, not last. Two commands can append to the same list —
-              # Aggregate.Attribute and Aggregate.Reference both extend `attributes`,
-              # because a reference's type is not a value object and cannot go
-              # through the same verb. Overwriting would have let the one declared
-              # later silently displace the other, and the walk would have offered
-              # every ordinary attribute as a reference.
+              # First wins, not last: Aggregate.Attribute and Aggregate.Reference
+              # both extend `attributes`; overwriting would displace one silently.
               found[mutation.target.to_s] ||= Append.new(verb: command.hecks_name, map: mutation.source)
             end
           end
         end
 
-        # The appenders displaced by first-wins — Aggregate.Reference behind
-        # Aggregate.Attribute. The walk reaches them by reading the row, not the
-        # plan, but they are still verbs the language declares and the coverage
-        # gate has to see them.
+        # The appenders displaced by first-wins in `appends_in`; still verbs
+        # the coverage gate must see.
         def alternates_in(commands)
           claimed = {}
           commands.flat_map do |command|
@@ -359,9 +232,7 @@ module Hecks
           end
         end
 
-        # Commands that change nothing — they exist to be refused. Aggregate.Seal is
-        # the whole-document check: dispatched once everything is declared, carrying
-        # only givens. A category with no sealer simply has no such rule.
+        # Commands that change nothing — they exist only to be refused.
         def sealers_in(commands)
           commands.select { |command| Array(command.mutations).empty? }.map(&:hecks_name)
         end

data/lib/hecks/bluebook/meta_validator/port_judge.rb

@@ -1,13 +1,8 @@
 module Hecks
   module Bluebook
     module MetaValidator
-      # Offers a built .port to the language that describes ports.
-      #
-      # A port is a sibling of a bluebook, the same shape WorldJudge already
-      # is one level over — its own file, its own door, judged through its
-      # own self-hosted language (port.bluebook) rather than left as a plain
-      # Ruby struct nothing checks. Whole-project table-unification survey,
-      # item #13's remaining builders.
+      # Offers a built .port to the self-hosted port language (port.bluebook).
+      # Refusals are collected in `refusals`.
       class PortJudge
         attr_reader :refusals