hecks 2.7.0 → 2.9.0

data/lib/hecks/bluebook/read_model.rb

@@ -2,13 +2,8 @@ require_relative "behaviour/read_model"
 
 module Hecks
   module Bluebook
-    # A read model — an ask that gathers heads from more than one aggregate.
-    #
-    # Like a query it crosses over as an instance, and for the same reason: its
-    # body is inherited from `QuerySpecification::ReadModel::Specification`, whose
-    # readers the runtime and the SQLite adapter both call on the object. It gains
-    # an identity and an owner ; it keeps the name it always had, because only a
-    # class ever had a competing answer for `name`.
+    # A read model: an ask that gathers heads from more than one aggregate.
+    # Crosses over as an instance, like a query.
     class ReadModel < QuerySpecification::ReadModel::Specification
       include Construct
 
@@ -27,31 +22,25 @@ module Hecks
       )
 
       attr_reader :name, :description, :reference_name, :reference_target, :aggregate_heads, :group_by,
-                  :count, :median_field
+                  :count, :median_field, :sum_field, :avg_field, :min_field, :max_field,
+                  :percentile_field, :percentile_at, :any_field, :all_field
 
-      # `reference_name:`/`reference_target:` are nil for a rootless read
-      # model (no `reference_to` declared) — `&.` throughout, rather than
-      # calling `.to_s`/`.to_sym` unconditionally, so
-      # `reference_target.nil?` stays a real, checkable fact for the
-      # interpreter instead of silently becoming `""`.
+      # Nil `reference_name`/`reference_target` mean a rootless read model, so `&.` keeps
+      # them nil. `count` through `all_field` are `Behaviour::ReadModel::REDUCTION_FIELDS`,
+      # one keyword per wire field: `Assembly::Build`/`Reconstruction` construct this
+      # generically off the contract's own flat field list (contracts.rb), so grouping
+      # them into a nested object would break that reflection.
       #
       # @param name [String, Symbol] the read model's declared name
-      # @param description [String, nil] the read model's declared prose description
-      # @param reference_name [Symbol, String, nil] the local reference attribute this
-      #   read model roots at, or `nil` for a rootless read model
-      # @param reference_target [String, Symbol, nil] the rooted aggregate's name, or
-      #   `nil` for a rootless read model
-      # @param aggregate_heads [Array<Hash{Symbol => Object}>] the included aggregates, each
-      #   a row with `:aggregate` (the aggregate's name), `:as` (the output field name) and
-      #   `:many` (whether this head is a many-side join)
-      # @param group_by [Array<Hash{field: Symbol}>] the declared group-by fields, one row
-      #   per field
-      # @param count [Boolean, nil] whether this read model reduces to a row count; `nil`
-      #   when undeclared
-      # @param median_field [Symbol, nil] the field this read model reduces to the median
-      #   of, or `nil` when undeclared
+      # @param reference_name [Symbol, String, nil] the local reference attribute it roots at
+      # @param reference_target [String, Symbol, nil] the rooted aggregate's name
+      # @param aggregate_heads [Array<Hash{Symbol => Object}>] rows of `:aggregate`, `:as`, `:many`
+      # @param group_by [Array<Hash{field: Symbol}>] the declared group-by fields, one row each
+      # rubocop:disable-next Metrics/ParameterLists
       def initialize(name:, description: nil, reference_name: nil, reference_target: nil, aggregate_heads: [],
-                     group_by: [], count: nil, median_field: nil, **)
+                     group_by: [], count: nil, median_field: nil, sum_field: nil, avg_field: nil,
+                     min_field: nil, max_field: nil, percentile_field: nil, percentile_at: nil,
+                     any_field: nil, all_field: nil, **)
         super(joins: aggregate_heads, **)
         @name             = name.to_s
         @hecks_name       = @name
@@ -59,71 +48,58 @@ module Hecks
         @reference_name   = reference_name&.to_sym
         @reference_target = reference_target&.to_s
         @aggregate_heads  = aggregate_heads
-        # Hash rows (`{field: :agg}`), same shape as `aggregate_heads` —
-        # `group_by_fields` is the convenience reader everything but
-        # `to_h`/the Judge's own generic walk actually wants.
+        # Rows are `{field: :agg}` hashes, the same shape as `aggregate_heads`.
         @group_by         = group_by
-        # **Absent is not false**. `@count` stays nil rather than becoming
-        # `false` when undeclared — the same "if you declare it, declare
-        # something" reading `Lifecycle`'s own optional fields rely on
-        # (MetaValidator::Judge#setters skips a setter whose every
-        # source is `nil`, so an always-false `@count` would dispatch
-        # `ReadModel.Count` on every read model that never wrote the
-        # word at all). `!!count` collapses a truthy DSL `true` (or a
-        # reconstructed `true`) to the same `true`/`nil` pair either path
-        # produces — never `false`.
-        @count            = count ? true : nil
-        @median_field     = median_field&.to_sym
+        assign_reductions(count: count, median_field: median_field, sum_field: sum_field, avg_field: avg_field,
+                          min_field: min_field, max_field: max_field, percentile_field: percentile_field,
+                          percentile_at: percentile_at, any_field: any_field, all_field: all_field)
       end
 
-      # `.to_sym` regardless of source — the direct builder path stores
-      # symbols, but `Reconstruction::Shapes#group_by_field` (the
-      # replayed-from-the-meta-domain path every real boot actually
-      # goes through) reads the field back as a String, the same way
-      # `aggregate_heads`' own `:as` does. Row hash keys built by
-      # `Value.materialize_unwrapped` are symbols (`attr.name`), so
-      # this has to be too, or `row[field]` in `nest` silently misses.
-
-      # `wheres`/`order_by`/`limit` are spelled explicitly here, the same
-      # mechanism `Query#to_h` already uses (query.rb, read directly
-      # before this was written) — always present, `wheres` a (possibly
-      # empty) array and `order_by`/`limit` nil when undeclared, exactly
-      # like a Query's. `extra_options_to_h` still excludes these three by
-      # name (options.rb), so nothing here double-spells them; the two
-      # constructs now share one encoding for the same three words rather
-      # than a reader needing to learn a second one. See this file's own
-      # `filtered_head_name` and language/bluebook/syntax.bluebook's
-      # `ReadModel` `where`/`order_by`/`limit` member rows for the history
-      # of why this was narrower, and 2026-08-11's read-model where/
-      # order_by/limit task for why it stopped being.
-      # Same dynamic tail as a Query's, plus two collections whose
-      # rows are plain hashes rather than constructs — they are
-      # normalised here rather than by `many`, which recurses through
-      # `to_h` and would have nothing to call.
-      # `count`/`median_field` are absent (no key at all), not `nil`,
-      # when undeclared — unlike `group_by` (always a `[]`, never
-      # missing) they are the first fields this construct has ever
-      # added that no older real corpus member could possibly carry, so
-      # merging them unconditionally would have put a `null` onto every
-      # existing read model's own wire shape (banking's
-      # `ComplianceDashboard`/`CustomerPortfolio`, the language's own
-      # `WholeBluebook`, ...) for a fact nothing about them changed —
-      # the exact `extra_options_to_h` reads for `cursor`/`offset`/etc,
-      # applied here for the same reason.
+      # Every reduction is omitted from the export, not nil, when undeclared, so
+      # existing read models keep their wire shape.
       #
       # @return [Hash] the declared emission, with `aggregate_heads`/`group_by` rows
-      #   stringified, `count`/`median_field` merged in only when declared, and
+      #   stringified, each reduction merged in only when declared, and
       #   `extra_options_to_h`'s own dynamic tail merged last
       def to_h
-        reductions = {}
-        reductions[:count] = true if @count
-        reductions[:median_field] = @median_field.to_s if @median_field
         super
           .merge(aggregate_heads: @aggregate_heads.map { |head| head.merge(as: head[:as].to_s) })
           .merge(group_by: @group_by.map { |row| row.merge(field: row[:field].to_s) })
-          .merge(reductions)
+          .merge(reduction_pairs)
           .merge(extra_options_to_h)
       end
+
+      private
+
+      # Stays nil (never false) when undeclared: the Judge skips setters whose source is nil.
+      def assign_reductions(count:, median_field:, sum_field:, avg_field:, min_field:, max_field:,
+                            percentile_field:, percentile_at:, any_field:, all_field:)
+        @count            = count ? true : nil
+        @median_field     = median_field&.to_sym
+        @sum_field        = sum_field&.to_sym
+        @avg_field        = avg_field&.to_sym
+        @min_field        = min_field&.to_sym
+        @max_field        = max_field&.to_sym
+        @percentile_field = percentile_field&.to_sym
+        @percentile_at    = percentile_at&.to_f
+        @any_field        = any_field&.to_sym
+        @all_field        = all_field&.to_sym
+      end
+
+      def reduction_pairs
+        pairs = {}
+        pairs[:count] = true if @count
+        pairs[:median_field] = @median_field.to_s if @median_field
+        pairs[:sum_field] = @sum_field.to_s if @sum_field
+        pairs[:avg_field] = @avg_field.to_s if @avg_field
+        pairs[:min_field] = @min_field.to_s if @min_field
+        pairs[:max_field] = @max_field.to_s if @max_field
+        pairs[:percentile_field] = @percentile_field.to_s if @percentile_field
+        pairs[:percentile_at] = @percentile_at if @percentile_field
+        pairs[:any_field] = @any_field.to_s if @any_field
+        pairs[:all_field] = @all_field.to_s if @all_field
+        pairs
+      end
     end
   end
 end

data/lib/hecks/bluebook/reference.rb

@@ -2,32 +2,13 @@ module Hecks
   module Bluebook
     # An attribute that points at another aggregate's head.
     #
-    # Holds the target directly, and answers `resolve` with the target's
-    # Aggregate, rather than being spelled as the string `"Reference<Customer>"`
-    # that `AggregateBuilder#reference_to` and `CommandBuilder#cross_reference`
-    # would otherwise mint from the real constant just handed in. That string
-    # would need five separate readers to parse back apart — a regex in the
-    # command interpreter, string equality in the read-model interpreter and
-    # the SQLite adapter, and `delete_prefix` in the bluebook builder — one
-    # writer inventing a spelling, five readers reparsing it.
-    #
-    # Resolution is lazy and deliberately so: `reference_to
-    # Customer` may name an aggregate declared lower in the file — banking's
-    # Account points at Customer and survives only because Customer happens to
-    # be written above — so the edge cannot be resolved at declaration time.
-    # It resolves through the chapter's own IR (`Bluebook#aggregate`),
-    # which is scoped by construction : the lookup cannot walk anywhere but
-    # this chapter's declared heads, so a same-named aggregate in another
-    # loaded domain is unreachable rather than defended against.
-    #
-    # `to_s` still spells `"Reference<Customer>"`, because `Attribute#to_h` is
-    # part of the pinned byte-for-byte export contract. IR objects in
-    # the graph, strings in the export.
+    # Holds the target name and resolves lazily through the chapter's own IR, since
+    # `reference_to` may name an aggregate declared later in the file.
+    # `to_s` spells `"Reference<Customer>"`, which the export contract pins.
     class Reference
       attr_reader :target_name
 
-      # The Aggregate whose declaration carries this reference — the way
-      # up to the chapter, stamped once every sibling has been read.
+      # The Aggregate whose declaration carries this reference, stamped once siblings are read.
       attr_accessor :declared_in
 
       # @param target_name [Module, String, Symbol] the aggregate constant this
@@ -36,9 +17,7 @@ module Hecks
         @target_name = Naming.demodulise(target_name).to_s
       end
 
-      # The Aggregate this points at, or nil when the target belongs to
-      # another domain — a cross-domain target may legitimately not be loaded,
-      # the same reading `across` policies get.
+      # The Aggregate this points at, or nil when the target belongs to another domain.
       #
       # @return [Bluebook::Aggregate, nil] the target aggregate, or `nil` when
       #   `declared_in`'s own chapter does not declare one by this name
@@ -61,21 +40,8 @@ module Hecks
       def to_s = "Reference<#{@target_name}>"
       def inspect = "#<Reference #{@target_name}>"
 
-      # Value equality, not identity — without this, two references to
-      # the same target, parsed from two separate bluebook reads (era
-      # N's own boot and a held era's own shadow reconstruction,
-      # coverage_check.rb's own comparison), are different objects and
-      # compare unequal by Ruby's default `==`. `EraGuard::ShapeDiff
-      # #diff_type`'s `held_type != current_type` check then reads as
-      # true for every reference_to attribute on every mint, regardless
-      # of whether the reference actually changed — a real refusal for
-      # attributes nothing about. `declared_in` (which aggregate carries
-      # this reference) is deliberately excluded: the same reference
-      # attribute exists once, but its `held_type`/`current_type` come
-      # from separately-parsed bluebooks with structurally different
-      # (if same-shaped) owning aggregates, and `declared_in` is a
-      # cross-reference for `resolve`, not part of what this attribute
-      # itself is.
+      # Value equality on the target; `declared_in` is excluded so references parsed from
+      # separate reads compare equal (EraGuard's shape diff depends on it).
       #
       # @param other [Object] the value to compare against
       # @return [Boolean] whether `other` is a `Reference` to the same target

data/lib/hecks/bluebook/smoke_test.rb

@@ -4,43 +4,8 @@ require "fileutils"
 
 module Hecks
   module Bluebook
-    # Boots a real bluebook and actually dispatches against it — the
-    # sibling `bin/model_check` never had: that tool proves a bluebook
-    # is structurally sound (no dead states, no unreachable transitions)
-    # without ever running a single command; this proves it works,
-    # catching exactly the class of bug static analysis structurally
-    # cannot see. Built and proved inside `bin/interview`'s own `smoke`
-    # command, where it first found two real bugs — a lifecycle field
-    # colliding with an explicit attribute, and a non-creating command
-    # missing `Command.ActsOn` — that reloaded clean, checked clean,
-    # and only broke once something actually dispatched against them.
-    #
-    # Synthesized args, never random (`Synthesizer`) — a String becomes
-    # a fixed marker, a closed set uses its own first admitted member, a
-    # reference reuses whatever this same run already minted for that
-    # target. One call per declared command, one call per declared
-    # report, per created root; every failure is collected and reported
-    # together rather than stopping at the first.
-    #
-    # ## What this cannot catch
-    #
-    # A call that dispatches cleanly but answers wrong — the read-model join
-    # bug this exact tool's own first user hit is the textbook case, a query
-    # that silently returned an empty array rather than raising.
-    # Smoke-testing proves nothing crashes; it does not prove the answer is
-    # the right one.
-    #
-    # ## False positives from a naive synthesizer
-    #
-    # A failure here is not necessarily a domain bug, either — it may
-    # just be `Synthesizer`'s own naive values (0, an empty list,
-    # "smoke-test") not satisfying a real invariant this simple
-    # generator was never built to reason about (a positive amount, a
-    # non-empty topping list, an email pattern). Confirmed against
-    # Banking and Pizzas: both real domains, both showing exactly that
-    # class of failure, neither one an actual bug. Building a
-    # synthesizer that respects arbitrary declared invariants is real
-    # constraint-aware generation — a separate, larger tool than this.
+    # Boots a bluebook and dispatches synthesized calls against it, collecting every failure.
+    # Catches what static checks miss, but not wrong answers, and naive values may trip invariants.
     module SmokeTest
       Failure = Struct.new(:domain, :aggregate, :command, :error, keyword_init: true) do
         def to_s = "#{domain}::#{aggregate}.#{command}: #{error}"
@@ -48,44 +13,8 @@ module Hecks
 
       module_function
 
-      # `dir` is any real, bootable hecks app directory — a saved
-      # domain, or a throwaway one a caller rendered into a temp dir
-      # for exactly this purpose. Plain `Hecks.boot`, not
-      # `Router.boot` — proven all night, and it works against a
-      # domain with framework-attached chapters (`uses_framework
-      # "Governance"`, say) that `Router.boot` refuses outright: those
-      # chapters carry no `.world` of their own, which `Router`'s
-      # per-domain realm resolution requires and a plain boot never
-      # did. Reports are reachable the identical way regardless of
-      # boot path — `dispatcher.query("Domain.report_name", **args)`
-      # is the same `Dispatcher#query` either boot hands back; Router
-      # was never actually required for this, only its own namespace
-      # sugar (`Domain.report_name(...)` as a bare method call) was.
-      #
-      # Never boots `dir`'s own real bindings — measured, not a
-      # precaution taken on spec: pointed at `examples/pizzas` (a real,
-      # persistent store carrying real accumulated records), a
-      # synthesized `CreatePizza` collided with an actual pre-existing
-      # record literally named "smoke-test" — a coincidence this time,
-      # data pollution the next. `isolate!` copies only the `.bluebook`
-      # (and `.world`, for its realm) into a throwaway directory and
-      # deliberately leaves the real `.hecksagon` behind — with none
-      # present, `Ports::Persistence::BindingPolicy.default_binding`
-      # binds every aggregate to Memory on its own, no settings needed.
-      # Whatever `dir` is really bound to in production is never
-      # touched.
-      # `install_facade: false` — this only ever dispatches by FQN string
-      # (below), so it never needs the `Widget::Item.Add(...)` Ruby
-      # sugar `Hecks.boot` installs by default. Skipping it matters
-      # here specifically: that sugar lands as a bare global constant on
-      # `Object` per domain and per aggregate name, with no scoping and
-      # no cleanup — and this tool boots throwaway domains under
-      # whatever generic names the caller's `.bluebook` happens to use
-      # ("Widget", "Item", "Tag" in this tool's own specs). Installing
-      # the facade would leak those names into the rest of the process —
-      # measured, not hypothetical: it once left a stale `Widget` constant
-      # that corrupted an unrelated spec's own unrelated use of the same
-      # bare name.
+      # Boots an isolated copy of `dir` on Memory bindings, so real stores are never touched.
+      # Skips the facade: its bare global constants would leak into the rest of the process.
       #
       # @param dir [String] path to a bootable hecks app directory — a saved
       #   domain, or a throwaway one rendered into a temp dir for this purpose
@@ -102,18 +31,8 @@ module Hecks
         end
       end
 
-      # Only the `.bluebook`, never `.world` either — a real world's own
-      # settings (`persisted_by("Heki") { dir "..." }`) are keyed to the
-      # real adapter it names, not to Memory; copied verbatim, they
-      # apply to the wrong binding and refuse with a `WiringError`
-      # ("Memory does not declare :dir") — measured, not assumed, the
-      # first time this ran against Banking. A plain `Hecks.boot`
-      # needs no realm to address anything (unlike `Router.boot`), so
-      # leaving the world out entirely is the correct minimal isolation,
-      # not a workaround. `translations/*.bluebook` also deliberately
-      # excluded — those are earlier, superseded versions of the same
-      # domain; smoke-testing the current declaration is the point, not
-      # its whole history.
+      # Copies only the `.bluebook` files: a real `.world` carries settings keyed to its own
+      # adapter and refuses under Memory.
       #
       # @param dir [String] path to the source hecks app directory to isolate
       # @param scratch [String] path to the throwaway directory to copy the
@@ -126,16 +45,7 @@ module Hecks
         Dir.glob(File.join(source, "*.bluebook")).each { |file| FileUtils.cp(file, target) }
       end
 
-      # Aggregates walked in declaration order, on purpose — so whatever
-      # a later aggregate's own shape needs from an earlier one (a
-      # `TripItem` needing a real `PackingItem`, say) already exists by
-      # the time that aggregate's own turn comes, the same reason
-      # `Synthesizer#args_for`'s `created` map is threaded through in
-      # this same order.
-      # `created` and `failures` thread through both the aggregate loop and the
-      # read_models loop below in the declaration order the comment above already
-      # documents; splitting would turn that ordering into an implicit contract on
-      # parameter/return passing instead of one visible sequence.
+      # Walks aggregates in declaration order so later ones can reference earlier `created` ids.
       # rubocop:disable-next Metrics/AbcSize
       #
       # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the
@@ -178,7 +88,7 @@ module Hecks
 
         chapter.read_models.each do |model|
           root_id = created[model.reference_target]
-          # Nothing was created for this root — nothing to smoke-test yet, not a failure.
+          # No root was created, so there is nothing to query yet.
           next unless root_id
 
           dispatcher.query("#{domain}.#{model.query_name}", model.reference_name => root_id)

data/lib/hecks/bluebook/synthesizer.rb

@@ -1,58 +1,21 @@
 module Hecks
   module Bluebook
-    # **One synthesized argument per declared attribute** — never a random
-    # guess. Reads only real `IR` (`Aggregate`, `Command`,
-    # `Attribute`, `ValueObject`), so it works against any
-    # loaded bluebook, not one particular domain: a String becomes a
-    # fixed marker; an Integer becomes 0; a closed set uses its own
-    # first admitted member (never a value a real `one_of` would
-    # legitimately refuse); a reference uses whatever id the caller
-    # already knows for that target (`created`), so a command whose
-    # own shape depends on an earlier-created record — a `TripItem`
-    # needing a real `PackingItem`, say — gets something real to work
-    # with instead of a guess that would only ever fail.
-    #
-    # Extracted from `bin/interview`'s own smoke test, where this first
-    # got built and proved — the logic never actually knew anything
-    # about the Interview domain or any one app; it only ever read IR.
+    # Synthesizes one argument per declared attribute from the IR: fixed markers for scalars,
+    # a closed set's first member, and a known `created` id for references. Never random.
     module Synthesizer
-      # The only type names that are ever truly scalar — anything else
-      # a value object's own field names is another value object,
-      # nested (`Pizza.price_cents: Price`, itself wrapping `cents:
-      # Integer` — a real, ordinary shape, not an edge case). Missing
-      # this the first time round meant a nested field silently
-      # synthesized as the bare string `"smoke-test"` instead of the
-      # real nested structure a command actually declares — caught
-      # only by testing against Pizzas instead of re-testing against
-      # the one simpler domain this was first built for, where every
-      # value object happened to be single-field and primitive-typed.
-      # The same list `Attribute::PRIMITIVES` holds, referenced rather
-      # than repeated. It was a second, byte-identical copy — and only
-      # the Attribute one is held to `vocabulary.bluebook` by
-      # spec/vocabulary_conformance_spec, so this copy could drift from
-      # the language and nothing would say so.
+      # Shared with `Attribute::PRIMITIVES` so the two lists cannot drift.
       PRIMITIVES = Attribute::PRIMITIVES
 
       module_function
 
-      # `chapter`/`aggregate` are the real `Bluebook`/`Aggregate`
-      # the command belongs to — needed to resolve a value object type
-      # name back to its own declared shape. `created` maps an
-      # aggregate name to a real id already minted for it earlier in
-      # the same run; a reference whose target isn't in there yet gets
-      # a placeholder instead of failing outright, since the caller may
-      # not care about that particular argument's real value.
+      # Synthesizes arguments for `command`. A reference whose target is not in `created`
+      # gets a placeholder id.
       #
-      # @param chapter [Bluebook::Chapter] the chapter the command's aggregate
-      #   belongs to, needed to resolve a value object type name back to its
-      #   own declared shape
+      # @param chapter [Bluebook::Chapter] resolves value object type names to their shapes
       # @param aggregate [Bluebook::Aggregate] the aggregate `command` belongs to
-      # @param command [Class] the command class (a `Bluebook::Command`
-      #   subclass) to synthesize arguments for
-      # @param created [Hash{String => Object}] aggregate name mapped to a real
-      #   id already minted for it earlier in this same run
-      # @return [Hash{Symbol => Object}] one synthesized value per declared
-      #   attribute, keyed by attribute name
+      # @param command [Class] the `Bluebook::Command` subclass to synthesize arguments for
+      # @param created [Hash{String => Object}] aggregate name mapped to an id minted earlier
+      # @return [Hash{Symbol => Object}] one synthesized value per declared attribute
       def args_for(chapter, aggregate, command, created = {})
         command.attributes.to_h do |attribute|
           if attribute.reference?
@@ -63,13 +26,8 @@ module Hecks
         end
       end
 
-      # A value object's own synthesized value — its first admitted
-      # member if it's a closed set (the one value guaranteed not to be
-      # refused), otherwise one synthesized scalar per declared field.
-      # Falls back to searching every aggregate in the chapter, the
-      # same tolerance `bin/interview shape`'s own lookup already
-      # needed: a value object referenced by name doesn't have to be
-      # declared on the same aggregate using it.
+      # Synthesizes a value object: its first member if a closed set, else one value per field.
+      # Falls back to searching every aggregate, since a value object need not be local.
       #
       # @param chapter [Bluebook::Chapter] the chapter to search when
       #   `type_name` is not declared on `aggregate` itself
@@ -91,11 +49,7 @@ module Hecks
         value_object.attributes.to_h { |field| [field.name, field_value_for(chapter, aggregate, field.type)] }
       end
 
-      # A single field's own synthesized value — a plain scalar if its
-      # type is one of the true primitives, otherwise that type names
-      # another value object, resolved the identical way `value_for`
-      # resolves any other one (its own closed set or its own nested
-      # fields, however deep that nesting actually goes).
+      # A field's value: a scalar for a primitive type, otherwise the nested value object.
       #
       # @param chapter [Bluebook::Chapter] see `value_for`
       # @param aggregate [Bluebook::Aggregate] see `value_for`
@@ -107,10 +61,7 @@ module Hecks
         PRIMITIVES.include?(type_name.to_s) ? scalar_for(type_name) : value_for(chapter, aggregate, type_name)
       end
 
-      # A bare primitive's own synthesized value. Never used for a
-      # closed set's own field (that's `value_for`'s job, reading the
-      # set's real first member) — only for a plain scalar field with
-      # no declared vocabulary to respect.
+      # A primitive's synthesized value; closed-set fields are handled by `value_for`.
       #
       # @param primitive [String, Symbol] the primitive type name, such as
       #   `"Integer"` or `"String"`

data/lib/hecks/bluebook/translation.rb

@@ -1,79 +1,47 @@
 module Hecks
   module Bluebook
-    # One field crossing a value-object boundary: a scalar becoming a VO
-    # member, a VO member becoming a scalar, or a rename across the move.
+    # One field crossing a value-object boundary, or carried under a new name.
     # Paths are dotted ("price.cents") for a VO member, bare otherwise.
     TranslationMove = Struct.new(:from, :to)
 
-    # One field whose value, not just its name or position, changed —
-    # an old value has nothing in common with a new one, so the only
-    # honest way to bridge it is a declared, exhaustive lookup table.
-    # Paths follow `TranslationMove`'s convention (dotted reaches a VO
-    # member); `values` maps every old-era value that can appear to its
-    # new-era replacement.
-    # `:values` shadows Struct#values on purpose (same reasoning as
-    # AttributeCollector::OneOf) — no caller reads the built-in behavior.
+    # One field whose value changed, bridged by an exhaustive lookup table.
+    # Paths follow `TranslationMove`; `values` maps each old-era value to its new-era one.
+    # `:values` shadows Struct#values on purpose; no caller reads the built-in.
     # rubocop:disable-next Lint/StructNewOverride
     TranslationConvert = Struct.new(:from, :to, :values)
 
-    # A value object's or entity's own type name changed with its member
-    # structure unchanged — the one drift `rename`/`move` cannot express,
-    # because the attribute kept its name and only the type it points at
-    # changed name. Mirrors `was:` one level deeper.
+    # A value object's or entity's type name changed with its members unchanged.
+    # The attribute kept its name, so `rename`/`move` cannot express it.
     TranslationRetype = Struct.new(:from, :to)
 
-    # A computed transform — rescale, reformat, split, merge — whose only
-    # implementation is the SQL expression itself, evaluated exclusively
-    # inside the compiled Postgres head. No in-process reference exists
-    # to check it against; any aggregate carrying one refuses to boot on
-    # every other adapter.
+    # A computed transform whose only implementation is a SQL expression run inside
+    # the compiled Postgres head; an aggregate carrying one refuses to boot elsewhere.
     TranslationCompute = Struct.new(:from, :to, :sql)
 
-    # The aggregate's own identity changed what it's computed from — not
-    # a field crossing a boundary (that's `move`), a value objects's type
-    # name (`retype`), or a value transform (`compute`): the record's own
-    # key. No `from:`/`to:` path, unlike every other rule here, because
-    # nothing is being consumed from or moved into `state` — the state
-    # a record already holds is untouched; only what identifies it is
-    # recomputed. Same SQL-only, Postgres-only, no-in-process-reference
-    # shape `compute` already has, and for the same reason: there is
-    # nothing to check this against outside the compiled head.
+    # The aggregate's own key is recomputed by a SQL expression; stored state is untouched.
+    # Postgres-only like `compute`, and it has no `from:`/`to:` path.
     TranslationRekey = Struct.new(:sql)
 
-    # A newly added, required attribute with no source in old data at
-    # all — not a rename, move, or convert, all of which need a from
-    # path in the old shape. `default` is the value an existing record
-    # reads until the next command against it writes a real one; unlike
-    # `compute`, this is adapter-agnostic — applied in-process by
-    # `Lineage#translate`, the same as rename/move/drop, because there is
-    # nothing to compute, only a value to declare.
+    # A newly added, required attribute with no source in old data.
+    # `default` is what an existing record reads until a command writes a real value;
+    # applied in-process by `Lineage#translate` on every adapter.
     TranslationBackfill = Struct.new(:name, :default)
 
-    # One aggregate's part of a translation: which attributes were
-    # renamed, moved, converted, or deliberately dropped on the way from
-    # the old era to the new one. `drops` exists so data loss is a
-    # declared decision, not a field that quietly stopped being
-    # explained.
+    # One aggregate's part of a translation between eras.
+    # `drops` makes data loss a declared decision.
     class TranslationAggregate
       attr_reader :name, :was, :renames, :moves, :converts, :drops, :retypes, :computes, :rekeys, :backfills
 
       # @param name [String, Symbol] the aggregate's name in the destination era
-      # @param was [String, Symbol, nil] the aggregate's name in the origin era, or `nil`
-      #   if it was not renamed
-      # @param renames [Hash{Symbol => Symbol}] each renamed field, old name to new name
-      # @param moves [Array<Bluebook::TranslationMove>] fields crossing a value-object
-      #   boundary
-      # @param converts [Array<Bluebook::TranslationConvert>] fields whose value is
-      #   remapped through a declared lookup table
+      # @param was [String, Symbol, nil] its name in the origin era, or `nil` if unchanged
+      # @param renames [Hash{Symbol => Symbol}] old field name to new field name
+      # @param moves [Array<Bluebook::TranslationMove>] fields crossing a value-object boundary
+      # @param converts [Array<Bluebook::TranslationConvert>] fields remapped via a lookup table
       # @param drops [Array<Symbol>] fields deliberately not carried forward
-      # @param retypes [Array<Bluebook::TranslationRetype>] value object or entity type
-      #   renames with their member structure unchanged
-      # @param computes [Array<Bluebook::TranslationCompute>] fields computed by a SQL
-      #   expression evaluated only inside the compiled Postgres head
-      # @param rekeys [Array<Bluebook::TranslationRekey>] SQL expressions that recompute
-      #   the aggregate's own identity
-      # @param backfills [Array<Bluebook::TranslationBackfill>] newly added required
-      #   fields with no source in old data
+      # @param retypes [Array<Bluebook::TranslationRetype>] value object or entity type changes
+      # @param computes [Array<Bluebook::TranslationCompute>] fields computed by Postgres-only SQL
+      # @param rekeys [Array<Bluebook::TranslationRekey>] SQL recomputing the aggregate's identity
+      # @param backfills [Array<Bluebook::TranslationBackfill>] new required fields, no old source
       def initialize(name:, was: nil, renames: {}, moves: [], converts: [], drops: [], retypes: [],
                      computes: [], rekeys: [], backfills: [])
         @name      = name.to_s
@@ -89,12 +57,8 @@ module Hecks
       end
     end
 
-    # A declared map from one era of a domain's storage shape to the
-    # next. Renames and moves — the smallest slice that proves the
-    # concept: old records are translated when they are replayed, never
-    # rewritten. `retired` acknowledges aggregates that are gone
-    # outright — not renamed — so their disappearance is a decision,
-    # not an accident.
+    # A declared map from one era of a domain's storage shape to the next.
+    # Old records are translated on replay, never rewritten; `retired` names aggregates removed.
     class Translation
       attr_reader :domain, :from, :to, :aggregates, :retired
 
@@ -104,7 +68,7 @@ module Hecks
       # @param aggregates [Array<Bluebook::TranslationAggregate>] each aggregate's own
       #   translation rules
       # @param retired [Array<String>] the names of aggregates gone outright in the
-      #   destination era, rather than renamed
+      #   destination era
       def initialize(domain:, from:, to:, aggregates: [], retired: [])
         @domain     = domain.to_s
         @from       = from