hecks 2.8.0 → 2.9.0

data/lib/hecks/bluebook/assembly/marks.rb

@@ -1,31 +1,13 @@
 module Hecks
   module Bluebook
     class Assembly
-      # The leaf shapes an assembly reads, and the encodings it undoes.
-      #
-      # `to_h` spells things as text so the export stands on its own, and every
-      # one of those spellings has to come back apart here. This is the same family
-      # of work `MetaValidator::Shapes` does for the reconstruction — the difference
-      # is that Shapes rebuilds hashes and this rebuilds objects, so it has to
-      # recover types rather than just strings.
-      #
-      # Encoding losses are the largest family of bug in this codebase, and every
-      # member has the same shape: reading an object where `to_h` holds a spelling.
-      # So each method below names the spelling it inverts.
+      # Reads the leaf shapes of an assembly's `to_h` export back into IR objects.
+      # Each method inverts one textual spelling, so types are recovered, not just strings.
       module Marks
         module_function
 
         # `Attribute#to_h` spells a type with `to_s`, so a reference arrives as
-        # "Reference<Customer>" and has to become an edge again. Everything else is
-        # a name and stays one.
-        #
-        # @param field [Hash{Symbol => Object}] one attribute's declared row, keyed
-        #   `:type` (String, a plain type name or `"Reference<Target>"`), `:name`
-        #   (String), `:list` and `:optional` (read as truthy), `:default` (Object,
-        #   nil), `:pattern` (String, nil), `:admits` (String, nil) and
-        #   `:relationship` (String, nil), each the raw declared value
-        # @return [Bluebook::Attribute] the attribute, with `type` resolved to a
-        #   `Bluebook::Reference` when the row spelled one
+        # "Reference<Customer>" and has to become an edge again.
         def attribute(field)
           type = field[:type].to_s
           target = type[/\AReference<(.+)>\z/, 1]
@@ -35,89 +17,39 @@ module Hecks
             type:         target ? Reference.new(target) : type,
             list:         field[:list] ? true : false,
             default:      field[:default],
-            # The last place optionality can be dropped, and the one that was
-            # dropping it. Every bluebook in the registry is the round-trip
-            # product — MetaValidator dispatches the declaration in and reads it
-            # back — so a fact this constructor does not carry is a fact the
-            # language cannot state about itself, however plainly the source
-            # wrote it.
+            # Every registry bluebook is a round-trip product, so a fact dropped
+            # here is a fact the language cannot state about itself.
             optional:     field[:optional] ? true : false,
             pattern:      field[:pattern],
-            # **The same lesson, one fact later**. `admits` is not on `to_h` — the
-            # wire does not carry it, on purpose — but it must still survive the
-            # round trip, because the grammar registry keeps the assembled graph
-            # and downstream projections read the link off that. Dropped here, the
-            # language could not say `admits` about itself no matter how plainly
-            # the source wrote it, which is word for word what the note above
-            # already learned about `optional`.
+            # Not on `to_h`, but the grammar registry keeps the assembled graph and
+            # downstream projections read the link off it, so it must survive.
             admits:       field[:admits],
             relationship: field[:relationship]
           )
         end
 
-        # The same shape. Two names because a head's field and a verb's argument are
-        # different things in the language even though the IR keeps one class for
-        # both — `Aggregate.Attribute` and `Command.Argument` are separate verbs.
-        #
-        # @param field [Hash{Symbol => Object}] see `attribute`
-        # @return [Bluebook::Attribute] see `attribute`
+        # A head's field and a verb's argument are separate verbs sharing one IR class.
         def shape_field(field) = attribute(field)
 
-        # One part of an identity. It goes in as a row so the language can hold an
-        # ordered list of them, and comes back out as the path it always was —
-        # a String, because `identity_paths` splits paths and never symbols.
-        #
-        # @param part [Hash{Symbol => Object}] one identity-path row, keyed `:value`
-        #   (Object, read via `to_s`)
-        # @return [String] the path segment
+        # One identity part, as the String path `identity_paths` splits.
         def identity_path(part) = part[:value].to_s
 
-        # A member's fields — an open map, which is why Member is its own root in
-        # the language and why the pairs arrive as a list rather than a value object.
-        #
-        # The values are unmarked, because `ValueObject#to_h` spells them with `to_s`
-        # and the language stores them as text: `member code: "JPY", minor_units: 0`
-        # came back with a minor_units of "0", and a closed set that admits the string
-        # would refuse the number the caller passes.
-        #
-        # @param pairs [Array<Array(String, Object)>] one member's own field pairs,
-        #   each `[field_name, raw_value]` as declared
-        # @return [Hash{Symbol => Object}] the member's fields, keyed by field name,
-        #   each value read back to its native type through `unmark_scalar`
+        # A member's fields, an open map, so the pairs arrive as a list.
+        # Values are unmarked because `ValueObject#to_h` spells them with `to_s`.
         def member(pairs)
           pairs.to_h { |key, value| [key.to_sym, unmark_scalar(value)] }
         end
 
-        # A read model's gathered head. The keys must be symbols whichever way the
-        # declaration arrived, and `as` must be one too: it names the reader the
-        # projection answers to, and `ReadModel#to_h` spells it `to_s`.
-        #
-        # @param row [Hash{Symbol => Object}] one aggregate-head row, keyed
-        #   `:aggregate` (String), `:as` (String, the reader name) and `:many`
-        #   (Boolean)
-        # @return [Hash{Symbol => Object}] the head, with every key a Symbol and
-        #   `:as` read back to a Symbol
+        # A read model's gathered head; `as` is a Symbol because `ReadModel#to_h` spells it `to_s`.
         def head(row)
           row.to_h { |key, value| [key.to_sym, key.to_sym == :as ? value.to_sym : value] }
         end
 
-        # A group_by field's own name — the builder's native shape is already
-        # `{field: :symbol}`, so this matches it rather than leaving `field`
-        # as the String `Shapes#group_by_field` reads back.
-        #
-        # @param row [Hash{Symbol => String}] one group-by row, keyed `:field`
-        # @return [Hash{field: Symbol}] the row with `:field` read back to a Symbol
+        # Matches the builder's native `{field: :symbol}` shape.
         def group_by_field(row) = { field: row[:field].to_sym }
 
-        # A scalar that was written as itself rather than inspected — a member's
-        # value, where the language holds text and the type has to be read back from
-        # the shape of it. Unlike `read`, a bare word stays a String here, because
-        # a closed set admits words far more often than symbols.
-        #
-        # @param value [Object] the raw declared scalar, read via `to_s`
-        # @return [true, false, Integer, Float, String] `true`/`false` for those
-        #   literal words, a number when the text matches a bare integer or decimal
-        #   pattern, or the string itself otherwise
+        # Reads a member's scalar back from text. Unlike `read`, a bare word stays a
+        # String, because a closed set admits words far more often than symbols.
         def unmark_scalar(value)
           text = value.to_s
           return true       if text == "true"
@@ -128,74 +60,34 @@ module Hecks
           text
         end
 
-        # A saga's argument bindings. Each value rides Literal's spelling, which
-        # marks a Symbol with a leading colon — lose it and an argument reads as a
-        # string of the same name.
-        #
-        # @param with [Array<Array(String, String)>, nil] the declared bindings,
-        #   each `[argument_name, literal_spelling]` pair, or `nil` for none
-        # @return [Hash{Symbol => Object}] the bindings, keyed by argument name,
-        #   each value read back through `Literal.read`
+        # A saga's argument bindings; Literal marks a Symbol with a leading colon.
         def bindings(with) = Array(with).to_h { |key, value| [key.to_sym, read(value)] }
 
         # Builds one aggregate or value object invariant from its declared row.
-        #
-        # @param rule [Hash{Symbol => String}] one invariant's declared row, keyed
-        #   `:description` and `:canonical` (the canonical-form rendering of the
-        #   rule's expression)
-        # @return [Bluebook::Invariant] the invariant, with `predicate`/`ast` left
-        #   `nil` — `Expression::Evaluator` parses `canonical` on demand when
-        #   neither is set
+        # `Expression::Evaluator` parses `canonical` on demand.
         def invariant(rule)
           Invariant.new(description: rule[:description], canonical: rule[:canonical])
         end
 
         # Builds one command precondition from its declared row.
-        #
-        # @param rule [Hash{Symbol => String}] one given's declared row, keyed
-        #   `:description` and `:canonical` (the canonical-form rendering of the
-        #   rule's expression)
-        # @return [Bluebook::Given] the given, with `predicate`/`ast` left `nil` —
-        #   `Expression::Evaluator` parses `canonical` on demand when neither is set
         def given(rule)
           Given.new(description: rule[:description], canonical: rule[:canonical])
         end
 
-        # S12, ADR 0025 — `projects :name, from: :"reference.remote_field"`.
-        # All three fields are identifiers, unlike Invariant/Given's own
-        # free text, so — like `attribute`'s own `name`/`type` below —
-        # they come back as Symbols.
-        #
-        # @param row [Hash{Symbol => String}] one projected-field's declared row,
-        #   keyed `:name`, `:reference` and `:remote_field` (each an identifier)
-        # @return [Bluebook::ProjectedField] the projected field, with each
-        #   identifier read back to a Symbol
+        # All three fields are identifiers, unlike Invariant/Given's free text, so they
+        # come back as Symbols.
         def projected_field(row)
           ProjectedField.new(name: row[:name].to_sym, reference: row[:reference].to_sym,
                              remote_field: row[:remote_field].to_sym)
         end
 
         # `Mutation#to_h` branches on the operation, so this does too.
-        #
-        # An append binds several fields at once, each either an argument (a
-        # Symbol, wearing its colon) or a literal — the distinction that is the
-        # whole reason `append: { direction: "out" }` was once indistinguishable
-        # from an argument named `out`.
-        #
-        # @param change [Hash{Symbol => Object}] one mutation's declared row, keyed
-        #   `:target` (String), `:op` (String, such as `"set"`, `"append"`,
-        #   `"delegate"` or `"corrects"`), `:fields` (Array, for the append-shaped
-        #   ops) and `:source` (Hash, for any other op)
-        # @return [Bluebook::Mutation] the mutation, with `source` a
-        #   `Hash{Symbol => Object}` of field bindings for an append-shaped op, or
-        #   `classified`'s own result for any other
+        # An append binds several fields, each an argument (a Symbol) or a literal.
         def mutation(change)
           target = change[:target].to_sym
           op     = change[:op].to_sym
 
-          # `:delegate`/`:corrects` (CommandBuilder#delegates_to's and
-          # #corrects_impl's own comments) ride the same multi-binding
-          # shape `:append` does.
+          # `:delegate` and `:corrects` ride the same multi-binding shape as `:append`.
           return Mutation.new(target: target, op: op, source: appended(change[:fields])) if [:append, :delegate,
                                                                                              :corrects].include?(op)
 
@@ -203,26 +95,11 @@ module Hecks
         end
 
         # Reads an append mutation's field bindings back off their declared rows.
-        #
-        # @param fields [Array<Array(String, String)>, nil] the append's declared
-        #   field bindings, each `[field_name, literal_spelling]` pair, or `nil`
-        #   for none
-        # @return [Hash{Symbol => Object}] the bindings, keyed by field name, each
-        #   value read back through `Literal.read`
         def appended(fields)
           Array(fields).to_h { |field, source| [field.to_sym, read(source)] }
         end
 
-        # A set reads one thing, and `classified_source` said which: an argument by
-        # name, or a literal by value.
-        #
-        # @param source [Hash{Symbol => Object}, nil] the mutation's declared
-        #   source, keyed `:kind` (String, `"argument"`, `"state"` or a literal
-        #   kind) plus `:name` (String, for `"argument"`/`"state"`) or `:value`
-        #   (Object, for a literal), or `nil` for no source
-        # @return [Symbol, Hecks::StateRef, Object, nil] the command argument name,
-        #   a state self-reference, the literal value, or `nil` when `source` is
-        #   `nil`
+        # A set reads one thing: an argument by name, or a literal by value.
         def classified(source)
           return nil if source.nil?
 
@@ -233,44 +110,13 @@ module Hecks
           end
         end
 
-        # Every literal field on the wire, read back — one spelling, one reader.
-        #
-        # A where-clause value, a saga's argument bindings, an append binding, a
-        # limit: all of them ride Literal's self-describing form, so all of them
-        # come back through this one reader, never a second one that might
-        # disagree about a quoted string or a number.
-        #
-        # An object literal is the one that bites hardest. A saga leg binds
-        # `narrative: { text: "transfer out" }` — a value object's fields written
-        # inline — and reading it as a plain string rather than through `Literal`
-        # would reach the runtime as `"{:text=>\"transfer out\"}"`, which coercion
-        # refuses: the debit leg is never delivered, and the whole settlement wire
-        # stops — banking emits TransferRequested five times and TransferDebited
-        # never. A whole-history replay gate is what catches this, because a saga
-        # that silently does nothing looks exactly like a saga with nothing to do.
-        #
-        # @param value [String, Object] wire spelling produced by `Literal.render`,
-        #   or a bare word
-        # @return [nil, true, false, Integer, Float, Symbol, Hecks::StateRef,
-        #   String, Hash, Array] the value read back — see `Literal.read`
+        # Reads every literal field on the wire through `Literal`, so no second reader
+        # can disagree about quoting. An object literal read as a plain string reaches
+        # the runtime as inspect text, which coercion refuses, and the saga leg stalls.
         def read(value) = Literal.read(value)
 
-        # `target:` (ADR 0055) — read straight off the wire, unconverted:
-        # it's already the bare aggregate-name string `WhereClause#to_h`/
-        # `OrderBy#to_h`/`LimitSpec#to_h` wrote (`resolve_target`'s own
-        # `Naming.demodulise` already ran once, at DSL-build time; this is
-        # the replay path every real boot actually goes through, reading
-        # that same wire shape back — see this class's own header). Absent
-        # from `clause`/`declared` entirely on older wire data that never
-        # declared `on:` — `clause[:target]`/`declared[:target]` reads
-        # `nil` for a missing key exactly like an explicit `nil` would,
-        # so this is additive, not a migration.
-        #
-        # @param clause [Hash{Symbol => Object}] one where-clause's declared row,
-        #   keyed `:field` (String), `:op` (String, a comparator name), `:value`
-        #   (String, Literal's spelling) and `:target` (String, `nil` when absent)
-        # @return [QuerySpecification::Common::WhereClause] the clause, with `op`
-        #   read to a Symbol and `value` read back through `Literal.read`
+        # `target:` is read straight off the wire, unconverted. A missing key reads
+        # `nil` like an explicit `nil`, so older wire data needs no migration.
         def where_clause(clause)
           QuerySpecification::Common::WhereClause.new(
             field: clause[:field], op: clause[:op].to_sym, value: read(clause[:value]), target: clause[:target]
@@ -278,12 +124,6 @@ module Hecks
         end
 
         # Builds a query's declared ordering, if it declares one.
-        #
-        # @param declared [Hash{Symbol => Object}, nil] the declared order-by row,
-        #   keyed `:field` (String), `:direction` (String) and `:target` (String,
-        #   `nil` when absent), or `nil` when the construct declares no ordering
-        # @return [QuerySpecification::Common::OrderBy, nil] the order-by, with
-        #   `direction` read to a Symbol, or `nil` when `declared` is `nil`
         def order_by(declared)
           return nil unless declared
 
@@ -293,25 +133,14 @@ module Hecks
         end
 
         # Builds a query's declared limit, if it declares one.
-        #
-        # @param declared [Hash{Symbol => Object}, nil] the declared limit row,
-        #   keyed `:value` (String, Literal's spelling) and `:target` (String,
-        #   `nil` when absent), or `nil` when the construct declares no limit
-        # @return [QuerySpecification::Common::LimitSpec, nil] the limit, with
-        #   `value` read back through `Literal.read`, or `nil` when `declared` is
-        #   `nil`
         def limit(declared)
           return nil unless declared
 
           QuerySpecification::Common::LimitSpec.new(value: read(declared[:value]), target: declared[:target])
         end
 
-        # Every other specification option, from one table.
-        #
-        # Each entry names the struct and which of its members carry a value that
-        # rode Literal's spelling rather than plain text. A
-        # ninth option is one row here and nothing else — the language already holds
-        # it, because it holds options as an open map rather than a field each.
+        # Every other specification option, from one table: the struct, and which of
+        # its members carry a value that rode Literal's spelling.
         OPTIONS = {
           offset:         [QuerySpecification::Common::OffsetSpec,        %i[value]],
           cursor:         [QuerySpecification::Common::CursorSpec,        %i[value]],
@@ -320,24 +149,11 @@ module Hecks
           inspection:     [QuerySpecification::Common::InspectionSpec,    []]
         }.freeze
 
-        # `mode` and `policy` are read as symbols because the DSL declares them that
-        # way — `nulls :last`, `authorize :customer_access` — and `to_h` spells them
-        # with `to_s`, so the colon is not there to strip.
+        # The DSL declares these as symbols (`nulls :last`) and `to_h` spells them with
+        # `to_s`, so they are converted back.
         SYMBOLIC = %i[mode policy tenant].freeze
 
         # Builds one query specification option from its declared row and `OPTIONS`.
-        #
-        # @param name [Symbol] the option's name, a key of `OPTIONS` (`:offset`,
-        #   `:cursor`, `:null_semantics`, `:authorization` or `:inspection`)
-        # @param declared [Hash{Symbol => Object}, nil] the option's declared row,
-        #   or `nil` when the construct does not declare this option
-        # @return [QuerySpecification::Common::OffsetSpec,
-        #   QuerySpecification::Common::CursorSpec,
-        #   QuerySpecification::Common::NullSemantics,
-        #   QuerySpecification::Common::AuthorizationSpec,
-        #   QuerySpecification::Common::InspectionSpec, nil] the option built
-        #   through the holder `OPTIONS` names for `name`, or `nil` when `declared`
-        #   is `nil`
         # @raise [KeyError] if `name` is not a key of `OPTIONS`
         def option(name, declared)
           return nil if declared.nil?
@@ -347,14 +163,6 @@ module Hecks
         end
 
         # Reads one option member's declared value back to its native type.
-        #
-        # @param key [Symbol] the option member's name being read
-        # @param value [Object, nil] the declared value for that member
-        # @param marked [Array<Symbol>] the members of this option that ride
-        #   Literal's spelling, from `OPTIONS`
-        # @return [Object, nil] `value` read back through `Literal.read` when
-        #   `key` is marked, a Symbol when `key` is one of `SYMBOLIC`, the raw
-        #   `value` otherwise, or `nil` when `value` is `nil`
         def option_value(key, value, marked)
           return nil               if value.nil?
           return read(value)       if marked.include?(key)

data/lib/hecks/bluebook/assembly/specializer.rb

@@ -1,49 +1,18 @@
 module Hecks
   module Bluebook
     class Assembly
-      # **The first specializer** — a projection of `contracts.rb`'s `fields:` table,
-      # derived from the language's own description of a category instead of
-      # hand-written beside it.
-      #
-      # `Plan` already reads `grammar_registry` to build the judge's walk ; this
-      # reads the same chapter to build the other table this arc's own header
-      # names as duplication — "spelled as the IR spells them," field for field,
-      # for every category simple enough to say so.
-      #
-      # One case, proven, not the whole table. A field this can speak for is
-      # scalar and not a reference — every other field (a list, a reference, a
-      # fold like Lifecycle) is exactly what `contracts.rb`'s `reads:`/`derived:`
-      # exist to say, and stays hand-written until a later projection learns to
-      # derive readers and folds too. Restricting the claim to what can be
-      # proven correct — checked in spec/specializer_spec.rb against two
-      # independent categories — is the same discipline `derived:` itself
-      # enforces : a claim needs a kind, and this one's kind is "plain, checked."
+      # Projects `contracts.rb`'s `fields:` table from the language's own grammar,
+      # for fields simple enough to derive: scalar, non-reference, non-walked.
       module Specializer
         module_function
 
-        # S17, ADR 0026 — `Handler` is a genuine entity, nested under
-        # `ProcessManager`, so `.aggregate` alone does not find it —
-        # it hangs off some aggregate's own `.entities` instead
-        # (searched recursively, the same reason `Value::Coercion#find_
-        # entity` does: a nested entity, like `Dispatch` inside
-        # `Handler`, is not a direct child of any aggregate either).
-        #
-        # @param chapter [Bluebook::Chapter] the chapter to search
-        # @param name [String, Symbol] the construct's declared name
-        # @return [Bluebook::Aggregate, Class, nil] the aggregate, or the entity class
-        #   (a `Bluebook::Entity` subclass) nested anywhere under one, or `nil` if
-        #   `chapter` declares no construct by that name
+        # Finds a construct by name — an aggregate, or an entity nested anywhere
+        # under one (recursively, since an entity like Dispatch nests two deep).
         def construct_for(chapter, name)
           chapter.aggregate(name) || chapter.aggregates.filter_map { |a| find_entity(a, name) }.first
         end
 
         # Searches a construct's own entities, recursively, for one by name.
-        #
-        # @param construct [Bluebook::Aggregate, Class] the aggregate, or entity class,
-        #   to search under
-        # @param name [String, Symbol] the entity's declared name
-        # @return [Class, nil] the entity class (a `Bluebook::Entity` subclass), or `nil`
-        #   if none of `construct`'s nested entities has that name
         def find_entity(construct, name)
           construct.entities.each do |candidate|
             return candidate if candidate.hecks_name == name
@@ -54,23 +23,8 @@ module Hecks
           nil
         end
 
-        # `position` is the first fold this runs into : a category declares
-        # `attribute :position, Position` — for the judge's own walk,
-        # `order_by :position` on its `DeclaredIn` ask — but no `*`
-        # constructor takes it as an argument. `contracts.rb` already says so,
-        # in the language every other derived field speaks :
-        # `derived: { position: :walk }`. The language says a category has a
-        # position ; it does not say a category's own constructor is handed
-        # one, and that second fact is exactly what `fields:` needs to answer.
-        # So the skip reads the category's own walk claims (`Contract#walked`)
-        # rather than restating `position` here — Handler, which has no
-        # walk-minted position, skips nothing.
-        #
-        # @param category [String, Symbol] the construct category's name, such as
-        #   `"Aggregate"` or `"Command"`
-        # @return [Hash{Symbol => Array(Symbol, Symbol)}] a `contracts.rb`-shaped
-        #   `fields:` table, one `field => [field, :plain]` entry per scalar,
-        #   non-reference, non-walked attribute the language declares for `category`
+        # Builds `category`'s own `fields:` entries from the language's scalar,
+        # non-reference attributes, skipping any the contract already derives.
         def fields_for(category)
           language = construct_for(MetaValidator.grammar_registry.bluebook("Bluebook"), category.to_s)
           walked   = Assembly.contract(category).walked

data/lib/hecks/bluebook/assembly.rb

@@ -1,38 +1,7 @@
 module Hecks
   module Bluebook
-    # A graph built from declarations, rather than from DSL calls.
-    #
-    # This is the half that lets the language orchestrate. `Reconstruction` reads a
-    # chapter back out of the meta-domain, in declaration order, as plain
-    # declarations — the same shape `to_h` spells. This turns those declarations
-    # into the graph the runtime runs: IR aggregates with their verbs, value
-    # objects, entities and asks, owned by the chapter that declares them.
-    #
-    # ## Why a hash, not a runtime
-    #
-    # It takes a hash, not a runtime, on purpose. That makes it a pure inverse of
-    # `to_h` and testable without the meta-domain in the picture at all:
-    #
-    #     Assembly.call(built.to_h).to_h == built.to_h
-    #
-    # which is the check `spec/assembly_spec` makes for every chapter in the tree.
-    # Feed it the reconstruction instead and the same code assembles what the
-    # language holds — the only difference being where the declarations came from.
-    #
-    # ## One table, not a method per category
-    #
-    # Every field is read from one table. There is no method per category here:
-    # `Contracts` names what the language cannot say about a construct, `Build`
-    # reads it, and the coverage gate holds the table to the language. A method
-    # per category can decorate a verb the language declares without ever
-    # offering it; the table cannot, because `spec/assembly_spec` checks every
-    # field the language declares against it.
-    #
-    # ## What stays hand-written
-    #
-    # The containment — which construct holds which — stays hand-written; it is
-    # not a field table. The runtime surface is not built here at all — the
-    # door is a per-boot projection, facade/surface.rb.
+    # Builds the runtime graph (aggregates, read models, process managers) from
+    # a chapter's declared hash — the pure inverse of `Chapter#to_h`.
     class Assembly
       # Builds the graph the runtime runs from one chapter's declared hash.
       #
@@ -67,10 +36,8 @@ module Hecks
 
       private
 
-      # Every reaction the chapter holds, and each one also handed back to the head
-      # that declared it — the builder keeps a policy in both places, hoisting it onto
-      # the chapter where the runtime reads it while the head keeps its own list. The
-      # language records which head, so the assembly can put it back.
+      # Hoists each reaction onto the chapter (for the runtime) and also back onto
+      # the aggregate head that declared it, per the language's own record of which.
       def reactions(aggregates)
         Array(@declaration[:policies]).map { |row| Build.call("Policy", row) }.each do |reaction|
           next if reaction.aggregate.to_s.empty?
@@ -90,14 +57,8 @@ module Hecks
                    dispatches: Array(row[:dispatches]).map { |leg| dispatch(leg) })
       end
 
-      # `compensates` — a plain hash on the declaration (`Reconstruction#
-      # dispatch`'s own comment for why), built into the real
-      # `DispatchSpec` its own field actually is by recursing through
-      # this same method, one level in — the identical move `handler`
-      # itself takes into `dispatches`, one level up. `nil` when there
-      # is nothing to compensate; `Build.call` never sees a
-      # `compensates:` key it does not know how to read either way, the
-      # same reason `compensates` never joined `Contract#fields` at all.
+      # `compensates` recurses through this same method (as `handler` does for
+      # `dispatches`) since it's itself a nested `DispatchSpec`-shaped hash.
       def dispatch(row)
         compensates = row[:compensates] && dispatch(row[:compensates])
         Build.call("Dispatch", row, compensates: compensates)

data/lib/hecks/bluebook/attribute.rb

@@ -5,12 +5,8 @@ require_relative "../naming"
 
 module Hecks
   module Bluebook
-    # One declared field on a construct — name, type (a primitive, a
-    # Reference, or another construct's name, always spelled via `#spell`),
-    # whether it's a list, its default/optional/pattern, and the closed set
-    # it `admits`. What `attribute :x, Type` (or `identified_by`,
-    # `reference_to`, etc.) actually mints, on an Aggregate, Entity, Command,
-    # ValueObject, Query or PortOperation alike.
+    # One declared field on a construct: name, type, list, default, optional, pattern
+    # and the closed set it `admits`.
     class Attribute
       include Hecks::IR
       include Behaviour::Attribute
@@ -28,44 +24,17 @@ module Hecks
 
       attr_reader :name, :type, :default, :pattern, :admits, :relationship
 
-      # A Reference is kept as itself. Every other type is still a name, and
-      # crosses over as its construct does.
-      #
-      # `admits` names an already-declared closed set the value must belong
-      # to — `Vocabulary::QueryComparator` — spelled aggregate-qualified
-      # because the set is a value object inside an aggregate, and the
-      # aggregate is the only thing `reference_to` can reach.
-      #
-      # On the wire, because it is a rule and not only a typing hint.
-      #
-      # It began as neither. The link existed so a generator could type
-      # `WhereClause.op` as `WhereOp` — a typing convenience, not worth
-      # moving 710 attribute records across eight goldens for. Then `admits`
-      # grew teeth (coercion refuses a non-member) and the argument
-      # inverted: a rule the wire does not carry is one a reader of the IR
-      # cannot enforce, and a bluebook whose meaning depends on the reader
-      # means two things. Proved rather than assumed — the same domain
-      # refused "burnt" through one reading and emitted the event through
-      # another.
-      #
-      # The wire carries the name, not the members. A reader resolves it
-      # against the IR it holds, so the members are declared once and
-      # copied nowhere — which is the same reason `admits` exists at all.
+      # A Reference is kept as itself; every other type is a name.
       #
       # @param name [Symbol, String] the attribute's name
-      # @param type [Module, Bluebook::Reference, String, Symbol] the bare constant naming
-      #   a primitive or a value object, a `reference_to`-built Reference, or already-spelled
-      #   text
+      # @param type [Module, Bluebook::Reference, String, Symbol] a bare constant, a Reference,
+      #   or already-spelled text
       # @param list [Boolean] whether this attribute holds a list of values rather than one
       # @param default [Object, nil] the value a new record starts with when none is given
       # @param optional [Boolean] whether a command may omit this attribute
-      # @param pattern [String, nil] a regex source the value must match; shared-engine
-      #   subset only (`PatternSubset`)
-      # @param admits [String, nil] an already-declared closed set's aggregate-qualified
-      #   name, such as `"Vocabulary::QueryComparator"`, that the value must belong to
-      # @param relationship [Symbol, nil] the DSL word that minted this attribute
-      #   (`:reference_to`, `:has_many`, `:has_one` or `:belongs_to`), or `nil` for an
-      #   ordinary attribute
+      # @param pattern [String, nil] a regex source the value must match (`PatternSubset`)
+      # @param admits [String, nil] an aggregate-qualified closed-set name for the value
+      # @param relationship [Symbol, nil] the DSL word that minted this attribute, or `nil`
       def initialize(name:, type:, list: false, default: nil, optional: false, pattern: nil,
                      admits: nil, relationship: nil)
         @name     = name.to_sym
@@ -80,23 +49,9 @@ module Hecks
 
       # A bare constant in a bluebook is a name, even when Ruby has heard of it.
       #
-      # `BluebookBuilder.build` says exactly this and installs a `const_missing`
-      # resolver that hands back the symbol — `attribute :target, Target` becomes
-      # the name "Target" and nothing looks Target up. That works only while the
-      # lookup fails, and `Facade::Surface` installs every aggregate name as a
-      # top-level constant (its own comment, and `ConstShim`'s, both say so).
-      #
-      # So in one process: boot a domain with an aggregate named `Target`, then
-      # load a chapter whose own value object is called `Target`, and Ruby
-      # resolves the constant before the hook is ever asked. The chapter is then
-      # built against somebody else's aggregate — silently, with no refusal —
-      # and the attribute stops meaning what the file plainly says.
-      #
-      # Demodulised, so both paths spell it the same: `:Target` and
-      # `QualityControl::Target` are both "Target". A plain class stays itself —
-      # `String` demodulises to "String" — so the ordinary case is untouched.
-      # This does not undo the constant leak; it makes the leak unable to change
-      # what a chapter means, which is the part that has to hold.
+      # `Facade::Surface` installs aggregate names as top-level constants, which would win
+      # over the `const_missing` resolver and silently rebind the attribute. Demodulising
+      # spells `:Target` and `QualityControl::Target` the same.
       def spell(type)
         return type if type.is_a?(Reference)
         return Naming.demodulise(type) if type.is_a?(Module)
@@ -105,12 +60,8 @@ module Hecks
       end
       private :spell
 
-      # Held because a declared vocabulary pins it — spec/vocabulary_conformance
-      # holds `Primitive`'s members to this list.
+      # Pinned by spec/vocabulary_conformance, which holds `Primitive`'s members to this list.
       PRIMITIVES = Hecks::Vocabulary.fetch("Primitive")
-
-      # `type` is spelled, never handed over. A Reference renders as
-      # "Reference<Customer>" here because that is the export's pinned spelling.
     end
   end
 end