hecks 2.8.0 → 2.9.0

data/lib/hecks/bluebook/aggregate.rb

@@ -3,32 +3,12 @@ require_relative "expression/ast_json"
 
 module Hecks
   module Bluebook
-    # A field read through a `reference_to`, held locally (S12, ADR 0025
-    # — "Consistency across aggregate boundaries") — `projects
-    # :customer_status, from: :"customer.status"` declares that this
-    # aggregate's own `:customer_status` is a copy of the target's own
-    # `:status`, kept fresh by a rebuild sweep rather than read live at
-    # rule-evaluation time. `reference` names the local reference
-    # attribute to walk through (`:customer`, minted by this
-    # aggregate's own `reference_to Customer`); `remote_field` names
-    # the scalar on the target aggregate to copy.
+    # A field copied from a `reference_to` target, kept fresh by a rebuild sweep (S12, ADR 0025).
+    # `reference` is the local reference attribute to walk; `remote_field` the target's scalar.
     ProjectedField = Struct.new(:name, :reference, :remote_field, keyword_init: true)
 
-    # A construct like every other: the aggregate carries its own identity
-    # and sits in the owner chain between its chapter (a Bluebook) and
-    # everything declared on it. The chain is model objects end to end —
-    # reference resolution and hecks_fqn both walk it.
-    #
-    # The holding half, and nothing else. Every line below restates what
-    # `language/bluebook/aggregate.bluebook` already declares — the field
-    # list, said again as readers, again as constructor keywords, and
-    # again as an emission. That triplication is what a generator removes;
-    # `Behaviour::Aggregate` carries everything that is not derivable from
-    # the declaration, so regenerating this file can never be lossy.
-    #
-    # Prototype: hand-written in the shape a generator would emit, to
-    # prove the seam before the generator exists. `bin/project_model`
-    # would own this file; behaviour/aggregate.rb stays hand-written.
+    # An aggregate: carries its own identity and sits in the owner chain below its chapter.
+    # The holding half only; `Behaviour::Aggregate` carries what the declaration cannot derive.
     class Aggregate
       include Construct
       include Hecks::IR
@@ -42,20 +22,10 @@ module Hecks
         value_objects:    many(:value_objects),
         commands:         many(:commands),
         invariants:       -> { invariants.map { |rule| Expression::AstJson.rule_row(rule) } },
-        # A precondition shared across commands, declared once (S10, ADR
-        # 0025) — the aggregate's own named `given`s, the declaration a
-        # referencing command's own (already-resolved) `givens` entry
-        # came from. Both sides of "declared once, referenced many"
-        # are real IR, the same shape a value object's type and an
-        # attribute's own reference to it both are.
+        # The named `given`s a referencing command's resolved `givens` entry came from.
         preconditions:    -> { preconditions.map { |rule| Expression::AstJson.rule_row(rule) } },
-        # S12, ADR 0025 — deliberately not folded into `attributes`:
-        # `EraGuard::ShapeDiff` only ever walks `attributes` to decide
-        # whether a new field leaves an existing record with something
-        # genuinely absent, and a projected field's own absence story
-        # is different — a record predating the `projects` declaration
-        # is expected to be missing it until the rebuild sweep runs,
-        # not a shape drift a translation needs to explain.
+        # Not folded into `attributes`: EraGuard::ShapeDiff walks those, and a record predating
+        # `projects` is expected to lack this field until the rebuild sweep runs.
         projected_fields: lambda {
           projected_fields.map do |field|
             { name: field.name.to_s, reference: field.reference.to_s, remote_field: field.remote_field.to_s }
@@ -64,11 +34,7 @@ module Hecks
         lifecycle:        one(:lifecycle),
         entities:         many(:entities),
         queries:          many(:queries),
-        # Additive — every domain that declares no port emits `ports: []`,
-        # the same "regenerate deliberately" wire-format change
-        # ir_golden_spec.rb's own header describes; no existing key
-        # moves. See docs/decisions (rust/project/ports.rb) for the
-        # first reader of this.
+        # Additive: domains that declare no port emit `ports: []`; no existing key moves.
         ports:            many(:ports),
         provenance:       :provenance
       )
@@ -77,39 +43,7 @@ module Hecks
                   :projected_fields, :identified_by, :identity_paths, :identity_heads, :lifecycle,
                   :entities, :queries, :policies, :ports, :reference_targets, :provenance
 
-      # Assigns what the language declares, then hands off to the
-      # behaviour's own `settle` — derived identity, name indexes and
-      # owner stamping, none of which the declaration states.
-      #
-      # @param name [String, Symbol] the aggregate's declared name
-      # @param description [String, nil] the aggregate's declared prose description
-      # @param attributes [Array<Bluebook::Attribute>] the aggregate's declared fields
-      # @param value_objects [Array<Class>] the value object classes (`Bluebook::ValueObject`
-      #   subclasses) declared on this aggregate
-      # @param commands [Array<Class>] the command classes (`Bluebook::Command` subclasses)
-      #   declared on this aggregate
-      # @param invariants [Array<Bluebook::Invariant>] the aggregate-level rules that must
-      #   always hold
-      # @param preconditions [Array<Bluebook::Given>] the aggregate's own named `given`s, a
-      #   referencing command's own resolved `givens` entry can point back at
-      # @param projected_fields [Array<Bluebook::ProjectedField>] the declared `projects`
-      #   fields, copied from another aggregate's own state by the rebuild sweep
-      # @param identified_by [String, Symbol, Array<String, Symbol>] the identity path(s)
-      #   this aggregate is addressed by
-      # @param lifecycle [Bluebook::Lifecycle, nil] the aggregate's declared state machine,
-      #   or `nil` if it declares none
-      # @param entities [Array<Class>] the entity classes (`Bluebook::Entity` subclasses)
-      #   nested directly under this aggregate
-      # @param queries [Array<Bluebook::Query>] the queries declared directly on this
-      #   aggregate
-      # @param policies [Array<Bluebook::Policy>] the reactions hoisted onto this aggregate
-      #   from the chapter that assembled it
-      # @param ports [Array<Bluebook::DomainPort>] the aggregate-scoped ports attached after
-      #   this aggregate was built
-      # @param reference_targets [Array<String>] the name of every aggregate this one points
-      #   at with an aggregate-level `reference_to`
-      # @param provenance [Object, nil] the aggregate's declared canonical source, captured
-      #   exactly as written, or `nil` if it declares none
+      # Assigns the declared fields, then `settle` derives identity, name indexes and owner stamps.
       def initialize(name:, description: nil, attributes: [], value_objects: [],
                      commands: [], invariants: [], preconditions: [], projected_fields: [], identified_by: [], lifecycle: nil,
                      entities: [], queries: [], policies: [], ports: [], reference_targets: [],

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

@@ -1,14 +1,7 @@
 module Hecks
   module Bluebook
     class Assembly
-      # One head, built from its declaration.
-      #
-      # The fields come from the contract like every other construct's. What is here
-      # is the part no field table can say: which construct holds which, and how a
-      # head's references become able to resolve.
-      #
-      # It decides nothing. Whether a declaration is admissible was settled on the
-      # way in, by the language.
+      # Builds one aggregate from its declaration: containment and reference resolution.
       class AggregateAssembly
         # @param row [Hash{Symbol => Object}] one declared aggregate's raw contract data,
         #   as `@declaration[:aggregates]` carries it
@@ -36,10 +29,7 @@ module Hecks
             entities:          entities,
             queries:           asks,
             lifecycle:         lifecycle_of(@row),
-            # A policy declared inside a head is hoisted onto the chapter by the
-            # builder, and `Aggregate#to_h` never carried it — so the language does
-            # not record which head a chapter-level policy was written in. The
-            # chapter holds them all, which is what `PolicyInterpreter` reads.
+            # Policies live on the chapter, which is what `PolicyInterpreter` reads.
             policies:          [],
             reference_targets: reference_targets(fields)
           )
@@ -50,12 +40,7 @@ module Hecks
 
         private
 
-        # What this head points at with an aggregate-level `reference_to`. Not the
-        # self-references its verbs carry — the first version read
-        # `commands.filter_map(&:references)` and gave Pizza two targets of "Pizza",
-        # its own verbs pointing at itself, where the builder recorded none. An
-        # aggregate-level `reference_to X` leaves a reference attribute behind, so
-        # the attributes are where the answer is.
+        # Read from attributes, not commands: a command's self-references are not targets.
         def reference_targets(fields)
           fields.select(&:reference?).map { |field| field.type.target_name }
         end
@@ -64,12 +49,7 @@ module Hecks
           Build.call("ValueObject", row)
         end
 
-        # S17, ADR 0026 — recurses. "That is what `entity` is for, and
-        # `entity` is declared by the language and used zero times in it"
-        # — Dispatch, inside Handler, is the first use, so `row[:entities]`
-        # is built the same way `row` itself was reached: through this
-        # same method, one level deeper each time. Nothing here assumes
-        # it stops at one level of nesting.
+        # Recurses, so entities nest to any depth (ADR 0026).
         def entity(row)
           Build.call(
             "Entity", row,
@@ -80,10 +60,8 @@ module Hecks
           )
         end
 
-        # Every reference learns which head declares it, so it can reach the chapter
-        # and resolve. Deliberately across every list that can carry one — a
-        # reference the walk misses resolves to nil, and a nil target is skipped
-        # rather than refused, so the guarantee would go quiet instead of red.
+        # Must cover every list that can carry a reference: a missed one resolves to nil,
+        # and a nil target is skipped rather than refused.
         def stamp_references(aggregate)
           lists = [aggregate.attributes, *aggregate.commands.map(&:attributes), *aggregate.queries.map(&:attributes)]
           entity_reference_lists(aggregate.entities, lists)
@@ -91,8 +69,6 @@ module Hecks
           lists.flatten.select(&:reference?).each { |field| field.type.declared_in = aggregate }
         end
 
-        # S17, ADR 0026 — walks nested entities too (Dispatch, inside
-        # Handler), not only an aggregate's own direct ones.
         def entity_reference_lists(entities, lists)
           entities.each do |piece|
             lists << piece.attributes
@@ -102,9 +78,7 @@ module Hecks
           end
         end
 
-        # Three language fields, one IR object. `state_field`, `state_start` and
-        # `transitions` are separate declarations; the IR keeps one Lifecycle. The
-        # contract names them derived, and this is what derives them.
+        # Folds `state_field`, `state_start` and `transitions` into the IR's one Lifecycle.
         def lifecycle_of(row)
           declared = row[:lifecycle]
           return nil unless declared
@@ -116,11 +90,8 @@ module Hecks
           )
         end
 
-        # A lifecycle holds [command, StateTransition] pairs and `to_h` expands one
-        # pair whose `from` is a list into several rows. Grouped back by command and
-        # target, because one declared pair has exactly one target and may have many
-        # froms — grouping by command alone would fuse two declarations that move the
-        # same verb to different states.
+        # Regroups `to_h` rows by command and target; grouping by command alone would fuse
+        # declarations that move one verb to different states.
         def transitions(rows)
           rows.group_by { |move| [move[:command], move[:to_state]] }
               .map do |(command, target), moves|

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

@@ -1,18 +1,9 @@
 module Hecks
   module Bluebook
     class Assembly
-      # One way to build a construct, for every construct.
+      # Builds any construct from its declared row by reading its `Assembly.contract`.
       #
-      # Not a method per category — `value_object(row)`, `command(row)`,
-      # `policy(row)`, each gathering the same keywords the contract already
-      # names. This reads the contract instead, so adding a field to the
-      # language and forgetting to assemble it is caught by the coverage gate
-      # rather than by nobody.
-      #
-      # `make` is the only branch, and it is a real one: a construct that became a
-      # class is `.declare`d, an instance is `.new`ed. That is the boundary
-      # `Query` sits on, and it is a fact about Ruby rather than about the
-      # domain.
+      # A construct that is a class is `.declare`d; an instance is `.new`ed.
       module Build
         module_function
 
@@ -42,8 +33,7 @@ module Hecks
           contract.holder or raise ArgumentError, "#{contract} holds nothing that can be built"
         end
 
-        # A reader is a Marks method, a list of them, or one of three spellings that
-        # need no decoding at all.
+        # Reads one value through a contract reader.
         #
         # @param reader [Symbol, Array, nil] the contract field's reader: `:plain`,
         #   `:identity`, `:flag`, `[:each, marks_method]`, `[:option, name]`, or a bare
@@ -56,8 +46,7 @@ module Hecks
           when :identity then value&.to_sym
           when :flag     then value ? true : false
           when Array
-            # [:each, reader] maps a list ; [:option, name] reads one named option,
-            # which needs its name as well as its value.
+            # `[:option, name]` needs its name as well as its value.
             if reader.first == :each
               Array(value).map { |held| Marks.public_send(reader.last, held) }
             else

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

@@ -1,94 +1,26 @@
 module Hecks
   module Bluebook
-    # The rulebook translating between the language's own declarations and the
-    # IR objects `Build`/`Reconstruction` produce from them — the `Contract`
-    # struct format itself (this file) plus, reopened in contracts.rb, the
-    # `CONTRACTS` table of one `Contract` per construct category.
+    # Translates the language's declarations into the IR that `Build` and
+    # `Reconstruction` produce; `CONTRACTS` (contracts.rb) holds one per category.
     class Assembly
-      # What a construct needs that the language cannot say, and how a claim that a
-      # field needs no assembling is checked.
-      #
-      # Naming a field derived is a claim, and a claim needs a kind, not just a name
-      # in a list. A bare list of names is a promise with nobody holding it: the
-      # coverage gate only asks whether a field is accounted for, so `derived:
-      # %i[version]` would satisfy it while dropping a chapter's version in
-      # silence — the exact shape of every defect this arc has found.
-      #
-      #   :parent            the containment tree supplies it — a `*_id`, or one of
-      #                      the named pointers below. Checked against the name.
-      #   :children          it is assembled as child constructs. Checked against the
-      #                      language: a category must exist whose parent is this one.
-      #   [:computed, :m]    the holder works it out. Checked: it must answer to `m`.
-      #   [:folded, keys]    several language fields are one thing in the IR, or one
-      #                      is spread across several. Checked: every key must appear
-      #                      in a real reconstructed declaration.
-      #   :elsewhere         not a fact about this construct at all. Allow-listed one
-      #                      by one, because it is the kind with no other check.
-      #
-      # Every one of those can fail. That is the whole difference.
+      # A derived claim's kind is one of :parent, :children, [:computed, method],
+      # [:folded, keys], or :elsewhere — each checked structurally, not just named.
       Contract = Struct.new(:holder, :make, :fields, :derived, :rows, :reads, keyword_init: true) do
-        # How a declaration key is read back off a row. Absent means the default —
-        # `text(row[key])`, a single cell — which is most of them ; present names the
-        # shape, because a list needs a reader per element and a folded field is
-        # gathered rather than fetched. Same pattern as `rows`, in the other
-        # direction: declare the exceptions, default the rest.
-        #
-        # @param key [String, Symbol] the field's declaration key, as `fields` names it
-        # @return [Symbol, Array, nil] the reader named in `reads` for `key`, or `nil`
-        #   when the field reads through the default single-cell reader
+        # nil means the field reads through the default single-cell reader.
         def reader(key) = Hash(reads)[key.to_sym]
 
-        # How an appendable list becomes rows the walk can offer. A list absent from
-        # here reads straight off the node ; one that is present names the shaper,
-        # because the IR keeps a shape the language does not — a transition whose
-        # `from` is a list is several rows, an append binds several fields at once,
-        # an open map is one row per entry.
-        #
-        # @param list [String, Symbol] the appendable list's field name
-        # @return [Symbol, nil] the shaper method named in `rows` for `list`, or `nil`
-        #   when the list reads straight off the node instead
+        # nil means the list reads straight off the node.
         def shaper(list) = Hash(rows)[list.to_sym]
 
-        # Whether `field` is one this contract accounts for, stored or derived.
-        #
-        # @param field [Symbol] the field name to check
-        # @return [Boolean] whether `field` is a key of `fields` or of `derived`
         def declares?(field) = fields.key?(field) || derived.key?(field)
 
-        # Names the kind of derived claim `field` makes, if any.
-        #
-        # @param field [Symbol] the derived field name to check
-        # @return [Symbol, Array, nil] the kind `derived` names for `field` — `:parent`,
-        #   `:children`, `:elsewhere`, `:walk`, an `[:computed, method]` or `[:folded,
-        #   object, member]` pair — or `nil` when `field` is not derived
         def kind_of(field) = derived[field]
 
-        # The fields the walk supplies — every `derived: { field => :walk }` claim.
-        # The language declares them (`attribute :position, Position`) so the
-        # judge can order siblings, but no constructor takes one. This is the one
-        # place that fact is stated ; `Specializer` and `Model::Deviations` read it
-        # here rather than each keeping their own `%i[position]`.
-        #
-        # @return [Array<Symbol>] every field name whose derived kind is `:walk`
+        # Every derived field the walk supplies; Specializer skips these.
         def walked = derived.select { |_field, kind| kind == :walk }.keys
 
-        # Where a folded field actually lives, as [object, member].
-        #
-        # `[:folded, :lifecycle, :field]` says the language's `state_field` is the
-        # `field` of the IR's one Lifecycle. `Readings` would otherwise have to state
-        # that fact a second time as `node.lifecycle&.field` — saying it once here
-        # drives both directions instead: the walk reads the member on the way in, and
-        # the reconstruction gathers the members back into the object on the way out.
-        #
-        # A nil member means the fold has no single member to name — `rows` is a
-        # count of what `closed_set` and `members` hold between them, and `options`
-        # spreads across eight keys. Those keep their own code, and the gate still
-        # checks the object they name is real.
-        #
-        # @param field [Symbol] the derived field name to check
-        # @return [Array(Symbol, Symbol), Array(Array<Symbol>, nil), nil] the `[object,
-        #   member]` pair the field folds into — `member` is `nil` when the fold has
-        #   no single member to name — or `nil` when `field` does not fold at all
+        # [object, member] a folded field lives at; member is nil when the fold
+        # has no single one to name (e.g. a count plus a list of rows).
         def folded(field)
           kind = derived[field]
           return nil unless kind.is_a?(Array) && kind.first == :folded
@@ -96,20 +28,8 @@ module Hecks
           [kind[1], kind[2]]
         end
 
-        # Computed means worked out, not merely answerable.
-        #
-        # Asking only whether the holder responds was too weak, and measurably so:
-        # `[:computed, :version]` passed, because `Bluebook` does answer to
-        # `version` — it just answers with what the constructor was handed. A field
-        # the constructor takes is stored, and calling it computed is how a chapter's
-        # version would have gone missing while the gate said yes.
-        #
-        # So a computed field is one the holder answers and the constructor does not
-        # accept. `query_name` qualifies (`Naming.snake(name)`) ; `version` cannot.
-        #
-        # @param method [Symbol] the field name to check
-        # @return [Boolean] whether `holder` answers `method` but its constructor does
-        #   not accept it as a keyword
+        # Computed means the holder answers but its constructor won't accept it —
+        # respond_to? alone would also count a stored field like `version`.
         def computes?(method)
           return false unless holder
           return false unless answers?(method)
@@ -117,22 +37,10 @@ module Hecks
           !accepts?(method)
         end
 
-        # Whether `holder` answers `method`, checked the way that fits how it is
-        # built: `respond_to?` for a `:declare` holder (a class, queried live) and
-        # `method_defined?` for a `:new` holder (an instance method, checked without
-        # building one).
-        #
-        # @param method [Symbol] the method name to check
-        # @return [Boolean] whether `holder` answers `method`
         def answers?(method)
           make == :declare ? holder.respond_to?(method) : holder.method_defined?(method)
         end
 
-        # Whether the holder's constructor takes `keyword` as a keyword argument.
-        #
-        # @param keyword [Symbol] the keyword to check
-        # @return [Boolean] whether the holder's constructor (`.declare` or
-        #   `#initialize`) accepts `keyword` as an optional or required keyword
         def accepts?(keyword)
           builder = make == :declare ? holder.method(:declare) : holder.instance_method(:initialize)
 
@@ -140,49 +48,20 @@ module Hecks
         end
       end
 
-      # The fields that point at a parent without being spelled `*_id` — the one list,
-      # read by the assembly gate (a `:parent` claim), the model generator and
-      # QueryIR (a declared field the model composes instead of storing).
-      #
-      #   aggregate, bluebook   the bare parent link a creating command mints
-      #                         (ADR 0025) — exactly the `parent_key`s `Plan` reads
-      #                         off the language
-      #   owner                 Entity's own text twin of that link, which is why
-      #                         Entity's contract claims `owner: :parent`
-      #
-      # `shape` and `handler` are not on this list — S17 (ADR 0026) made Member and
-      # Dispatch nested entities, so neither is a parent field the way
-      # `owner` is. `spec/assembly_spec` derives this set from `Plan` and the
-      # contracts directly and fails on any drift, rather than trusting this list to
-      # stay in sync with a second hand-written copy kept by the model generator.
+      # Parent-pointer fields that don't end in `_id` (ADR 0025).
+      # spec/assembly_spec derives this set independently and fails on drift.
       PARENT_POINTERS = %i[aggregate bluebook owner].freeze
 
-      # Whether `field` is a parent pointer that does not end in `_id`.
-      #
-      # @param field [String, Symbol] the field name to check
-      # @return [Boolean] whether `field` ends with `_id`, or is one of
-      #   `PARENT_POINTERS`
       def self.parent_pointer?(field)
         field.to_s.end_with?("_id") || PARENT_POINTERS.include?(field.to_sym)
       end
 
-      # The only fields allowed to claim they describe something other than the
-      # construct they hang off, each with the reason spelled out.
-      #
-      #   normalisations   the canonical-form table belongs to the expression grammar.
-      #                    A chapter's rules are canonicalised on the way in, so the
-      #                    language models the table — but no chapter stores one, and
-      #                    `Bluebook#to_h` splices it in from Expression.
+      # Fields allowed to describe something other than their own construct.
+      # `Bluebook.normalisations` belongs to the expression grammar; `to_h` splices it in.
       ELSEWHERE = {
         Bluebook: %i[normalisations]
       }.freeze
 
-      # Whether `field` is allow-listed as describing something other than
-      # `category`'s own construct — see `ELSEWHERE`.
-      #
-      # @param category [String, Symbol] the construct category name
-      # @param field [Symbol] the field name to check
-      # @return [Boolean] whether `field` is on `category`'s `ELSEWHERE` entry
       def self.elsewhere?(category, field)
         Array(ELSEWHERE[category.to_sym]).include?(field)
       end