hecks 0.2.0 → 1.0.0

data/lib/hecks/bluebook/dsl/rule_reference.rb

@@ -0,0 +1,173 @@
+module Hecks
+  module Bluebook
+    module DSL
+      # THE THREE RESOLUTION PRIMITIVES the S10 given/invariant family's
+      # own "declared once, referenced by name" mechanism (ADR 0025)
+      # reduces to, at every scope this language has grown one so far
+      # (a command referencing its owner or a sibling piece's entity-wide
+      # pool; an aggregate referencing another aggregate chapter-wide; a
+      # value object referencing a sibling value object on the same
+      # aggregate) — extracted here, once, so the NEXT scope this family
+      # widens to (there will be one — see docs/resolution-rules/
+      # chapter-given.md's own "Known limitations" for two already named)
+      # reuses one of these three shapes instead of a fourth hand-written
+      # near-duplicate resolver.
+      #
+      # NOT ONE UNIFIED ALGORITHM — a real design question this file
+      # answers directly: the THREE existing resolvers are not
+      # superficially different, they are STRUCTURALLY different (a
+      # multi-pool fallback CHAIN; ONE pool keyed by declaring OWNER,
+      # needing disambiguation; a LIVE SCAN over already-built sibling
+      # objects with no separate pool at all) — forcing them into one
+      # shape would be a real behavior change (see `#lookup`, below, for
+      # which construct uses which), not the pure internal refactor this
+      # module is. `build_rule` is the one piece that WAS genuinely
+      # identical across all 7 declaring methods (`given`×3,
+      # `invariant`×3, `ensures`×1) before this file existed — extract
+      # predicate source, refuse if extraction failed, build the struct.
+      #
+      # `#lookup`/`#verify_resolves_via!` read WHICH construct uses which
+      # primitive off the self-hosted grammar table itself
+      # (`Keyword#resolves_via`, `syntax.bluebook`) — not a Ruby-only
+      # Hash cross-checked afterward (this file's OWN earlier shape, one
+      # round ago) — so a real domain's own boot, not just `bundle exec
+      # rspec`, fails loudly the moment the table and this file's own
+      # hand-written resolution methods disagree.
+      module RuleReference
+        module_function
+
+        # `struct_class` is `Given` or `Invariant` (both `Struct.new(
+        # :description, :canonical, :predicate, keyword_init: true)` —
+        # `Given` lives in command.rb, `Invariant` in value_object.rb).
+        # `owner_name`/`word` are ONLY for the refusal message's own
+        # wording. `extraction_failure` is the tail of that same
+        # message, and stays a REQUIRED parameter rather than one
+        # hardcoded string on purpose — `given` ("its source could not
+        # be read, so no other runtime could ever evaluate it"),
+        # `invariant` ("it would be a rule the IR cannot carry"), and
+        # `ensures` ("a postcondition is carried as text, and this one
+        # has none") each already had their OWN exact wording before
+        # this method existed; unifying them into one generic sentence
+        # would be a real (if small) behavior change this refactor is
+        # not making.
+        def build_rule(struct_class, description, predicate, owner_name:, word:, extraction_failure:)
+          canonical = Ports::Extraction.canonical(predicate)
+
+          if canonical.to_s.empty?
+            raise Malformed,
+                  "#{owner_name}'s #{word} #{description.inspect} did not survive " \
+                  "extraction — #{extraction_failure}"
+          end
+
+          struct_class.new(description: description, canonical: canonical, predicate: predicate)
+        end
+
+        # PRIMITIVE 1 — an ORDERED CHAIN of flat `Hash[description] =>
+        # Rule` pools, first match wins. `CommandBuilder#given`'s own
+        # two-pool shape (its OWN owner's `named_givens`, then a sibling
+        # piece's entity-wide pool) is this with a 2-element chain — a
+        # future single-pool bare reference is the same primitive with a
+        # 1-element chain, not a separate "just look in one hash" method.
+        def resolve_hash_chain(pools, description)
+          pools.each { |pool| return pool[description] if pool.key?(description) }
+          nil
+        end
+
+        # PRIMITIVE 2 — ONE pool keyed BY DECLARING OWNER,
+        # `Hash[description][owner] => Rule` — `AggregateBuilder#given`'s
+        # own chapter-wide shape, the only construct so far where the
+        # SAME description can mean two genuinely different predicates
+        # (docs/implemented/resolution-rules/chapter-given.md). Returns the full
+        # candidates Hash (0, 1, or many entries) — deliberately NOT
+        # raising here, so each caller keeps its own exact refusal
+        # wording for "none," "ambiguous," and "declared_by: named the
+        # wrong owner" rather than one generic message papering over all
+        # three.
+        def resolve_owner_keyed(pool, description)
+          pool[description] || {}
+        end
+
+        # PRIMITIVE 3 — a LIVE SCAN over already-built SIBLING OBJECTS'
+        # own collections, not a separately-maintained pool at all —
+        # `ValueObjectBuilder#invariant`'s own shape: every sibling value
+        # object on the same aggregate has ALREADY been built by the time
+        # a later one references back (declaration order, the same
+        # constraint every scope in this family carries), so there is
+        # nothing to write through — just read their own already-declared
+        # rules directly. `reader` is the method name to call on each
+        # sibling (`:invariants` today; kept a parameter, not hardcoded,
+        # since a future sibling-scan scope might reference a different
+        # collection).
+        def resolve_sibling_scan(siblings, description, reader:)
+          siblings.flat_map { |sibling| sibling.public_send(reader) }
+                  .find { |rule| rule.description == description }
+        end
+
+        # WHICH CONSTRUCT USES WHICH PRIMITIVE — no longer a Ruby-only
+        # Hash (that WAS this constant's own shape, one round ago): the
+        # user's own correction — "my goal is that if they read the same
+        # table they behave identically" — means a table only Ruby ever
+        # reads cannot deliver that, no matter how faithfully it is
+        # cross-checked afterward. `Keyword#resolves_via`/`#disambiguator`
+        # (self-hosted, `syntax.bluebook`) is the REAL table now — the
+        # SAME generated data `rust/parser/src/keywords.rs` is generated
+        # from (`bin/project_parser_table`). `#lookup` reads it live.
+        #
+        # THE ONE UNAVOIDABLE EXCEPTION: the meta-domain's own bootstrap
+        # (`MetaValidator.load_grammar_into`) dispatches `given`/
+        # `invariant` on ITSELF 61 times while building the very grammar
+        # table that would answer "how does given/Aggregate resolve" —
+        # `MetaValidator.grammar_registry`/`SyntaxBoot.call` are not
+        # ready yet, and cannot be made ready without ALREADY having
+        # resolved a `given` somewhere upstream. `MetaValidator.
+        # bootstrapping?` is the SAME guard `MetaValidator.call` (the
+        # judge) already uses to skip self-judging during this exact
+        # window — `#lookup` uses it too, falling back to
+        # `BOOTSTRAP_FALLBACK` (below) ONLY while it's true. Every REAL
+        # domain (banking, pizzas, compliance, any future one) boots
+        # AFTER `grammar_registry` is fully built and memoized, so reads
+        # the real table, every time, no exception.
+        BOOTSTRAP_FALLBACK = {
+          %w[given Aggregate]       => { resolves_via: "owner_keyed", disambiguator: "declared_by" },
+          %w[given Entity]          => { resolves_via: "owner_keyed", disambiguator: "declared_by" },
+          %w[given Command]         => { resolves_via: "hash_chain" },
+          %w[invariant ValueObject] => { resolves_via: "sibling_scan" }
+        }.freeze
+
+        def lookup(word, context)
+          if MetaValidator.bootstrapping?
+            BOOTSTRAP_FALLBACK[[word, context]] || {}
+          else
+            row = MetaValidator::SyntaxBoot.call[:keywords]
+                                           .find { |r| r[:word] == word && r[:context] == context }
+            return {} unless row
+
+            { resolves_via: row[:resolves_via], disambiguator: row[:disambiguator] }
+              .transform_values { |value| value.to_s.empty? ? nil : value }
+          end
+        end
+
+        # A LIVE CROSS-CHECK, not a spec-only one — every REAL domain's
+        # own boot (not just `bundle exec rspec`) now genuinely fails
+        # loudly if a construct's own hand-written resolution method
+        # ever disagrees with what the self-hosted grammar table claims
+        # for it. Each of the three `reference_named_*` methods below
+        # calls this FIRST, naming the primitive it is ABOUT to use —
+        # if `syntax.bluebook`'s own `resolves_via` for this exact
+        # (word, context) pair ever names something else, this is a
+        # real drift between the language's own self-description and
+        # its own implementation, caught at the next boot of ANYTHING,
+        # not just the next `rspec` run.
+        def verify_resolves_via!(word, context, expected_primitive)
+          actual = lookup(word, context)[:resolves_via]
+          return if actual == expected_primitive
+
+          raise "internal: syntax.bluebook says #{word}/#{context} resolves via " \
+                "#{actual.inspect}, but #{word}'s own Ruby builder is about to use " \
+                "#{expected_primitive.inspect} — the grammar table and the " \
+                "implementation have drifted"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/dsl/translation_builder.rb

@@ -0,0 +1,243 @@
+require_relative "word_gate"
+module Hecks
+  module Bluebook
+    module DSL
+      class TranslationAggregateBuilder
+        GRAMMAR_CONTEXT = "TranslationAggregate"
+
+        include WordGate
+
+        def initialize(name, was: nil)
+          raise Malformed, "an aggregate translation needs a name" if name.to_s.empty?
+
+          @name      = name
+          @was       = was
+          @renames   = {}
+          @moves     = []
+          @converts  = []
+          @drops     = []
+          @retypes   = []
+          @computes  = []
+          @rekeys    = []
+          @backfills = []
+        end
+
+        # RENAMED FROM `rename`/`move`/`convert`/`retype`/`compute`/
+        # `rekey`/`backfill` (all seven below) — item #13's full
+        # metaprogrammed dispatch (slice 4c). Not bootstrap-reachable
+        # (translation.bluebook describes ITS OWN structure with
+        # aggregate/entity/attribute, never with these — they're
+        # words for real, user-authored `.translation` files only,
+        # loaded after the grammar table exists), so none need a
+        # BOOTSTRAP_CALLS_FALLBACK entry.
+        def rename_impl(old_name, to:)
+          raise Malformed, "a rename needs a source name" if old_name.to_s.empty?
+          raise Malformed, "a rename needs a destination name (to:)" if to.to_s.empty?
+
+          @renames[old_name.to_sym] = to.to_sym
+        end
+
+        def move_impl(old_path, to:)
+          raise Malformed, "a move needs a destination path (to:)" if to.to_s.empty?
+          raise Malformed, "a move needs a source path" if old_path.to_s.empty?
+
+          @moves << TranslationMove.new(old_path.to_s, to.to_s)
+        end
+
+        # A value with nothing structural in common with its replacement
+        # — declared as an exhaustive table, not computed, so every value
+        # that can appear in old data has a named destination. Paths
+        # follow `move`'s convention: dotted reaches a value-object member.
+        def convert_impl(old_path, to:, values:)
+          raise Malformed, "a convert needs a destination path (to:)" if to.to_s.empty?
+          raise Malformed, "a convert needs a source path" if old_path.to_s.empty?
+          raise Malformed, "a convert needs a values: table" if values.nil? || values.empty?
+
+          @converts << TranslationConvert.new(old_path.to_s, to.to_s, values)
+        end
+
+        # `drop` — item #13's full metaprogrammed dispatch, slice 2
+        # (whole-project table-unification survey): a declared,
+        # deliberate acknowledgment that an attribute's data does not
+        # survive the rename — the honest alternative to letting it
+        # vanish because nothing named it. A blank-guarded, kind-driven
+        # coerce-and-append with nothing else, now executed by
+        # `GenericDispatch`.
+
+        # A value object's or entity's own type name changed, member
+        # structure unchanged. The stored data never carries the type
+        # name, so nothing moves — this declares that the pair of names
+        # means the same shape, which is what lets the era diff accept it.
+        def retype_impl(old_type, to:)
+          raise Malformed, "a retype needs a source type name" if old_type.to_s.empty?
+          raise Malformed, "a retype needs a destination type name (to:)" if to.to_s.empty?
+
+          @retypes << TranslationRetype.new(old_type.to_s, to.to_s)
+        end
+
+        # A computed transform whose only implementation is the SQL
+        # expression itself — Postgres-only by construction. The scaffold
+        # never proposes one; a human writes it, and the audit's
+        # human-sampled review is its only verification.
+        def compute_impl(old_path, to:, sql:)
+          raise Malformed, "a compute needs a destination path (to:)" if to.to_s.empty?
+          raise Malformed, "a compute needs a source path" if old_path.to_s.empty?
+          raise Malformed, "a compute needs its sql: expression" if sql.to_s.empty?
+
+          @computes << TranslationCompute.new(old_path.to_s, to.to_s, sql.to_s)
+        end
+
+        # THE AGGREGATE'S OWN IDENTITY, changing what it's computed from —
+        # not a field crossing a boundary (`move`), not a value's own
+        # transform (`compute`): the record's key. No path arguments,
+        # unlike every rule above — nothing is consumed from or moved into
+        # `state`, only what identifies the record is recomputed. Same
+        # SQL-only, Postgres-only, human-reviewed-sample-is-the-only-
+        # verification shape `compute` already has, and for the same
+        # reason: there is nothing in-process to check this against.
+        def rekey_impl(sql:)
+          raise Malformed, "a rekey needs its sql: expression" if sql.to_s.empty?
+
+          @rekeys << TranslationRekey.new(sql.to_s)
+        end
+
+        # A NEWLY ADDED, required attribute — the addition-side sibling of
+        # `drop`. Nothing to rename, move, or convert FROM, since old data
+        # never held this field at all; `default` is what an existing
+        # record reads until the next command against it writes a real
+        # value. Adapter-agnostic, unlike `compute` — applied the same
+        # in-process way rename/move/drop already are
+        # (`Lineage#translate`), because there is nothing to compute here,
+        # only a value to declare. This is what
+        # `EraGuard.refuse_unsafe_addition!` asks for when a non-optional
+        # attribute with no default: could leave an existing record with
+        # the field genuinely absent.
+        def backfill_impl(name, default:)
+          raise Malformed, "a backfill needs a name" if name.to_s.empty?
+          raise Malformed, "a backfill needs a default: value" if default.nil?
+
+          @backfills << TranslationBackfill.new(name.to_sym, default)
+        end
+
+        # The scaffold writes this where it cannot decide; a file carrying
+        # one can only boot into this refusal — never a guess.
+        #
+        # RENAMED FROM `unresolved` — item #13's full metaprogrammed
+        # dispatch (slice 4). Builds its own message with real branching
+        # (empty vs. named candidates, a special :identity case), not a
+        # fixed string a boolean `refuses:` flag could express — reached
+        # through `calls:` instead, like `attribute`/`role`. NOT
+        # bootstrap-reachable: translation.bluebook (loaded during
+        # bootstrap, to describe the translation DSL itself) never
+        # writes `unresolved` — that word is only ever used by real,
+        # user-authored `.translation` files, loaded well after the
+        # grammar table exists — so no BOOTSTRAP_CALLS_FALLBACK entry is
+        # needed here (checked directly, not assumed).
+        def unresolved_impl(name, candidates: [])
+          raise Malformed, unresolved_message(name, candidates)
+        end
+
+        # `method_missing`/`respond_to_missing?` used to be hand-written
+        # here, giving a hand-typed "must be rename, move, convert, ..."
+        # list on every genuinely undefined call — WordGate (`include`d
+        # above) now answers the same question off the self-hosted
+        # grammar table instead, the exact "hardcoded legal-word list"
+        # this whole arc's item #13 exists to close. A word admitted
+        # elsewhere in the grammar but not in this context still gets a
+        # richer, table-driven refusal than the old generic one did.
+
+        def build
+          TranslationAggregate.new(
+            name: @name, was: @was, renames: @renames, moves: @moves, converts: @converts,
+            drops: @drops, retypes: @retypes, computes: @computes, rekeys: @rekeys, backfills: @backfills
+          )
+        end
+
+        private
+
+        def unresolved_message(name, candidates)
+          return identity_unresolved_message if name.to_sym == :identity
+
+          rendered = Array(candidates).map { |candidate| render_path(candidate) }
+          if rendered.empty?
+            "#{@name}'s translation leaves #{render_path(name)} unresolved (no candidate matched — " \
+              "consider drop, or compute on Postgres) — replace unresolved with a real rule before booting."
+          else
+            "#{@name}'s translation leaves #{render_path(name)} unresolved (candidates: #{rendered.join(', ')}) — " \
+              "replace unresolved with a rename, move, convert, or drop before booting."
+          end
+        end
+
+        def render_path(path)
+          path.to_s.include?(".") ? path.to_s.inspect : ":#{path}"
+        end
+
+        # THE SCAFFOLD'S OWN HINT for the one drift it can detect but never
+        # resolve on its own — an aggregate's `identified_by` changed. Not
+        # a field to rename/move/drop, so none of the ordinary hints fit;
+        # `coverage_check.rb#check_identity_unchanged!` is the real gate,
+        # this only names the one rule that gets a legitimate mint through it.
+        def identity_unresolved_message
+          "#{@name}'s translation leaves its identity unresolved — identified_by changed since the held era. " \
+            "Declare a rekey rule (a rename/move/drop cannot fix this) before booting."
+        end
+      end
+
+      class TranslationBuilder
+        GRAMMAR_CONTEXT = "Translation"
+
+        include WordGate
+
+        def initialize(domain, from:, to:)
+          raise Malformed, "a translation names no domain" if domain.to_s.empty?
+          raise Malformed, "#{domain}'s translation says nothing about its origin era (from:)" if from.to_s.empty?
+          raise Malformed, "#{domain}'s translation says nothing about its destination era (to:)" if to.to_s.empty?
+
+          @domain     = domain
+          @from       = from
+          @to         = to
+          @aggregates = []
+          @retired    = []
+        end
+
+        # RENAMED FROM `aggregate` — item #13's full metaprogrammed
+        # dispatch (slice 4c). Not bootstrap-reachable — this "Translation"
+        # -context `aggregate` (opens a TranslationAggregateBuilder) is a
+        # different (context, word) pair than "Bluebook"-context
+        # `aggregate` (the one translation.bluebook itself is described
+        # with), so it's never used to describe the language's own
+        # translation chapter.
+        def aggregate_impl(name, was: nil, &block)
+          builder = TranslationAggregateBuilder.new(name, was: was)
+          builder.instance_eval(&block) if block
+          @aggregates << builder.build
+        end
+
+        # `retired` — item #13's full metaprogrammed dispatch, slice 2
+        # (whole-project table-unification survey): an aggregate that is
+        # gone outright — not renamed. The deliberate alternative to a
+        # bogus `was:` claim on an unrelated aggregate. Same shape
+        # `TranslationAggregateBuilder#drop` is, now executed by
+        # `GenericDispatch`.
+
+        # `method_missing`/`respond_to_missing?` — same removal as
+        # TranslationAggregateBuilder's own, one level up: WordGate
+        # (`include`d above) answers off the self-hosted grammar table
+        # now instead of a hand-typed "it declares aggregate blocks and
+        # retired aggregates" message.
+
+        def build
+          MetaValidator.call_translation(
+            Translation.new(domain: @domain, from: @from, to: @to, aggregates: @aggregates, retired: @retired)
+          )
+        end
+
+        def self.build(domain, from:, to:, &block)
+          builder = new(domain, from: from, to: to)
+          builder.instance_eval(&block) if block
+          builder.build
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/dsl/value_object_builder.rb

@@ -0,0 +1,178 @@
+require_relative "word_gate"
+module Hecks
+  module Bluebook
+    module DSL
+      class ValueObjectBuilder
+        GRAMMAR_CONTEXT = "ValueObject"
+
+        include AttributeCollector
+        include RuleReference
+        include WordGate
+
+        def initialize(name, owner_value_objects: [])
+          @name       = name
+          @invariants = []
+          @members    = []
+          @owner_value_objects = owner_value_objects
+        end
+
+        # THE WRAPPER BLOCK IS GONE (ADR 0025, "Attributes" — "closed sets
+        # lose the wrapper block"). `member` lines are bare now, written
+        # directly in the `value_object` body with no `one_of do ... end`
+        # around them — `build`'s own `closed_set: @closed_set ||
+        # !@members.empty?` already treats a non-empty `@members` as closed,
+        # so nothing else has to change for that to work. A single-field set
+        # has an even shorter spelling: `attribute`'s own `one_of:` keyword
+        # (`AttributeCollector#install_inline_closed_set`, overridden below).
+        #
+        # This also removes a real, documented landmine: the block form
+        # collided with `AttributeCollector#one_of`'s own type-position
+        # method (`one_of("a", "b")`, different arity) the moment both were
+        # mixed into the same builder — a value_object could never actually
+        # use the inline form on one of its own attributes. One `one_of`
+        # method now, not two.
+        #
+        # LEGACY UNDER SHADOW-PARSING (S0a's own bridge) — frozen era text
+        # still writes the block form (2 locations in
+        # `examples/banking/data/eras/banking/1.bluebook`, duplicated once
+        # more in that era's own archive copy), so `EraGuard.shadow_parse`
+        # still needs to read it. `block_given?` is what tells the two
+        # calling shapes apart: the type-position form
+        # (`one_of("a", "b")`) never passes a block, only the wrapper does.
+        # RENAMED FROM `one_of` — item #13's full metaprogrammed dispatch
+        # (slice 5). SAME NAME as `AttributeCollector#one_of_impl`'s own
+        # — required for the `super(*values)` call below to keep
+        # resolving; see that method's own comment. Reached directly
+        # through its own "ValueObject"-context Keyword row (the
+        # block-wrapper form has its own row, distinct from "Type"'s),
+        # not through the Type-position fallback this word's OTHER
+        # context uses.
+        def one_of_impl(*values, &block)
+          unless block
+            # NO VALUES, NO BLOCK is the SCALAR spelling — nonsensical, not
+            # merely inert: it names a closed set with nothing in it. The
+            # original block form caught this by a side effect (`@closed_set
+            # = true` ran unconditionally, before the `if block`), and this
+            # keeps the same refusal rather than letting the call fall
+            # through and silently do nothing.
+            if values.empty?
+              raise Malformed,
+                    "#{@name}'s one_of names no values — one_of(\"a\", \"b\") takes at least one, or " \
+                    "give the attribute its own one_of: [...] for a named closed set"
+            end
+
+            # AttributeCollector's own `one_of(*values)` — Ruby's normal
+            # `super` reaches the included module's method from here.
+            return super(*values)
+          end
+
+          unless MetaValidator.shadow_parsing?
+            raise Malformed,
+                  "#{@name}'s one_of do ... end wrapper is gone — give the single attribute its " \
+                  "own one_of: [...], or write bare member lines with no wrapper for a multi-field set"
+          end
+
+          @closed_set = true
+          instance_eval(&block)
+        end
+
+        # RENAMED FROM `member` — item #13's full metaprogrammed dispatch
+        # (slice 4c). Bootstrap-reachable, in
+        # GenericDispatch::BOOTSTRAP_CALLS_FALLBACK.
+        def member_impl(**fields)
+          raise Malformed, "#{@name} declared an empty member" if fields.empty?
+
+          @members << fields
+        end
+
+        # NO BLOCK is a REFERENCE, not a fresh declaration — the same
+        # move S10 already made for `CommandBuilder#given` (ADR 0025,
+        # "a precondition shared across commands is declared once... a
+        # command references it by name"), one level over: a rule
+        # shared across SIBLING value objects on the same aggregate,
+        # declared once, on the first one to need it. Real, live
+        # redundancy this closes: `Account`'s own `Money`/`PositiveMoney`
+        # both declared `invariant("a currency is a three-letter code")
+        # { currency.to_s.size == 3 }`, byte for byte. Declare it before
+        # the value objects that reference it — resolution happens at
+        # the referencing value object's own build time, against
+        # whatever sibling value objects the aggregate has already
+        # built, the same ordering rule `given` carries.
+        # RENAMED FROM `invariant` — item #13's full metaprogrammed
+        # dispatch (slice 4b). Bootstrap-reachable, in
+        # GenericDispatch::BOOTSTRAP_CALLS_FALLBACK.
+        def invariant_impl(description, &predicate)
+          return reference_named_invariant(description) unless predicate
+
+          # moved to the language: given "a rule says what it means", on Shape.Assert
+
+          @invariants << build_rule(Invariant, description, predicate, owner_name: @name, word: "invariant",
+                                     extraction_failure: "it would be a rule the IR cannot carry")
+        end
+
+        private
+
+        # PRIMITIVE 3 (RuleReference#resolve_sibling_scan) — see that
+        # method's own comment for why this is a live scan, not a pool.
+        def reference_named_invariant(description)
+          verify_resolves_via!("invariant", "ValueObject", "sibling_scan")
+          named = resolve_sibling_scan(@owner_value_objects, description, reader: :invariants) ||
+                  raise(Malformed,
+                        "#{@name}'s invariant #{description.inspect} names no rule a sibling value " \
+                        "object on this aggregate declares — declare it once with a block, on the " \
+                        "value object that needs it first, before the ones that reference it back")
+
+          @invariants << named
+        end
+
+        public
+
+        def build
+          if @inline_closed_set_field && attributes.size > 1
+            raise Malformed,
+                  "#{@name}'s one_of: on :#{@inline_closed_set_field} only works when it is the " \
+                  "value object's only attribute — #{attributes.size} declared here; write bare " \
+                  "member lines instead for a multi-field set"
+          end
+
+          ValueObject.declare(
+            name: @name, attributes: attributes,
+            invariants: @invariants, members: @members,
+            closed_set: @closed_set || !@members.empty?
+          )
+        end
+
+        def self.build(name, owner_value_objects: [], &block)
+          builder = new(name, owner_value_objects: owner_value_objects)
+          builder.instance_eval(&block) if block
+          builder.build
+        end
+
+        private
+
+        # THE NEW SPELLING — `attribute :name, String, one_of: %w[...]`,
+        # overriding `AttributeCollector`'s own refusal (every OTHER
+        # includer has no meaningful use for this). PRIVATE, like the
+        # module's own version it overrides — it is a callback `attribute`
+        # invokes on itself, never a word a bluebook author calls by name.
+        # Refuses a SECOND attribute naming one_of: on the same value
+        # object outright — a single-field set names exactly one field, by
+        # construction; two would be structurally ambiguous about which
+        # field each member line belongs to. `build` refuses the OTHER
+        # half of that same rule (this attribute coexisting with unrelated
+        # ones on a multi-field object).
+        def install_inline_closed_set(field, values)
+          if @inline_closed_set_field && @inline_closed_set_field != field
+            raise Malformed,
+                  "#{@name} declares one_of: on more than one attribute (:#{@inline_closed_set_field} " \
+                  "and :#{field}) — a single-field closed set names exactly one"
+          end
+
+          @inline_closed_set_field = field
+          @closed_set = true
+          values.each { |value| member_impl(field => value.to_s) }
+        end
+      end
+    end
+  end
+end