hecks 0.2.0 → 0.3.0

data/lib/hecks/bluebook/project_register.rb

@@ -0,0 +1,82 @@
+module Hecks
+  module Bluebook
+    # The callable catalogue for a discovered project. It knows how Bluebook
+    # declarations become public FQNs, but never searches or boots folders.
+    class ProjectRegister
+      Entry = Struct.new(:fqn, :source_directory, :dispatcher, :declared_verb, :domain_version, keyword_init: true) do
+        def command? = fqn.command?
+        def query?   = fqn.query?
+      end
+
+      class DuplicateFqn < StandardError; end
+      class MissingRealm < StandardError; end
+      class LatestMismatch < StandardError; end
+
+      attr_reader :entries
+
+      def initialize
+        @entries = {}
+      end
+
+      def fetch(address) = entries.fetch(address.to_s)
+      def include?(address) = entries.key?(address.to_s)
+      def commands = entries.values.select(&:command?)
+      def queries  = entries.values.select(&:query?)
+
+      def register(bluebooks, registry, dispatcher, directory)
+        bluebooks.each do |bluebook|
+          world = registry.world(bluebook.name)
+          realm = world&.realm
+          raise MissingRealm, "#{bluebook.name} in #{directory} has no world realm" if realm.to_s.empty?
+          if world.latest && bluebook.version && world.latest != bluebook.version
+            raise LatestMismatch,
+                  "#{bluebook.name} in #{directory} declares latest #{world.latest.inspect}, not #{bluebook.version.inspect}"
+          end
+
+          bluebook.aggregates.each do |aggregate|
+            aggregate.commands.each do |command|
+              add(Fqn.command(realm: realm, domain: bluebook.name, version: bluebook.version,
+                              aggregate: aggregate.hecks_name, command: command.hecks_name), directory, dispatcher, command.hecks_name, bluebook.version) if bluebook.version
+              add(Fqn.command(realm: realm, domain: bluebook.name, aggregate: aggregate.hecks_name,
+                              command: command.hecks_name), directory, dispatcher, command.hecks_name, bluebook.version) if current?(
+                                bluebook, world
+                              )
+            end
+            aggregate.queries.each do |query|
+              name = Naming.snake(query.name)
+              add(Fqn.query(realm: realm, domain: bluebook.name, version: bluebook.version,
+                            aggregate: aggregate.hecks_name, query: name), directory, dispatcher, query.name, bluebook.version) if bluebook.version
+              add(Fqn.query(realm: realm, domain: bluebook.name, aggregate: aggregate.hecks_name,
+                            query: name), directory, dispatcher, query.name, bluebook.version) if current?(bluebook, world)
+            end
+          end
+          bluebook.read_models.each do |model|
+            add(Fqn.query(realm: realm, domain: bluebook.name, version: bluebook.version,
+                          query: model.query_name), directory, dispatcher, model.query_name, bluebook.version) if bluebook.version
+            add(Fqn.query(realm: realm, domain: bluebook.name, query: model.query_name),
+                directory, dispatcher, model.query_name, bluebook.version) if current?(bluebook, world)
+          end
+        end
+        self
+      end
+
+      private
+
+      def current?(bluebook, world)
+        bluebook.version.nil? || world.latest == bluebook.version
+      end
+
+      def add(fqn, directory, dispatcher, declared_verb, domain_version)
+        existing = entries[fqn.to_s]
+        if existing
+          raise DuplicateFqn, "#{fqn} is declared in both #{existing.source_directory} and #{directory}"
+        end
+
+        entries[fqn.to_s] = Entry.new(
+          fqn: fqn, source_directory: directory, dispatcher: dispatcher,
+          declared_verb: declared_verb, domain_version: domain_version
+        )
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/query.rb

@@ -0,0 +1,61 @@
+require_relative "behaviour/query"
+
+module Hecks
+  module Bluebook
+    def self.render_value(value) = Literal.render(value)
+
+    # A query — an ASK, declared on an aggregate or on one of its entities.
+    #
+    # It crosses over as an INSTANCE rather than a class, and the reason is worth
+    # stating because it is the boundary of the pattern. A query inherits its
+    # whole body from `QuerySpecification::Common::Options` — `wheres`,
+    # `order_by`, `limit`, `offset`, `cursor`,
+    # `authorization`, `null_semantics`, `inspection` — and those
+    # are INSTANCE methods that the runtime and the SQLite adapter both read.
+    # Hoisting the declaration onto a metaclass would put the identity and the
+    # specification on opposite sides of the object.
+    #
+    # And nothing is lost, because `Class#name` was the only reason a construct
+    # ever needed a second word for its own name. An instance answers `name`
+    # truthfully. So a query gains an owner and an identity — which is what the
+    # graph is for — and keeps the name it always had.
+    class Query < QuerySpecification::Common::Options
+      include Construct
+
+      include Hecks::IR
+      include Behaviour::Query
+
+      emits_ir(
+        name:        :name,
+        description: :description,
+        attributes:  many(:attributes),
+        wheres:      many(:wheres),
+        order_by:    one(:order_by),
+        limit:       one(:limit)
+      )
+
+      attr_reader :name, :description, :attributes
+
+      def initialize(name:, description: nil, attributes: [], wheres: [],
+                     order_by: nil, limit: nil, offset: nil, cursor: nil,
+                     authorization: nil, null_semantics: nil,
+                     inspection: nil)
+        null_semantics ||= QuerySpecification::Common::NullSemantics.default
+        super(wheres: wheres, order_by: order_by, limit: limit, offset: offset, cursor: cursor,
+              authorization: authorization,
+              null_semantics: null_semantics, inspection: inspection)
+        @name        = name.to_s
+        @hecks_name  = @name
+        @description = description
+        @attributes  = attributes
+      end
+
+      # A query's shape is NOT fixed — `extra_options_to_h` carries
+      # whatever options the specification layer grew (count, median,
+      # group_by, scope_to). Declared emission covers the settled part
+      # and `super` hands it over; the tail stays dynamic, which is the
+      # honest description of it.
+      def to_h = super.merge(extra_options_to_h)
+    end
+  end
+end

data/lib/hecks/bluebook/read_model.rb

@@ -0,0 +1,109 @@
+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`.
+    class ReadModel < QuerySpecification::ReadModel::Specification
+      include Construct
+
+      include Hecks::IR
+      include Behaviour::ReadModel
+
+      emits_ir(
+        name:             :name,
+        description:      :description,
+        reference_name:   :reference_name,
+        reference_target: :reference_target,
+        query_name:       :query_name,
+        wheres:           many(:wheres),
+        order_by:         one(:order_by),
+        limit:            one(:limit)
+      )
+
+      attr_reader :name, :description, :reference_name, :reference_target, :aggregate_heads, :group_by,
+                  :count, :median_field
+
+      # `reference_name:`/`reference_target:` are nil for a ROOTLESS read
+      # model (no `reference_to` declared) — `&.` throughout, rather than
+      # the `.to_s`/`.to_sym` this used to require unconditionally, so
+      # `reference_target.nil?` stays a real, checkable fact for the
+      # interpreter instead of silently becoming `""`.
+      def initialize(name:, description: nil, reference_name: nil, reference_target: nil, aggregate_heads: [],
+                     group_by: [], count: nil, median_field: nil, **options)
+        super(joins: aggregate_heads, **options)
+        @name             = name.to_s
+        @hecks_name       = @name
+        @description      = description
+        @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.
+        @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
+      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.
+      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(extra_options_to_h)
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/reference.rb

@@ -0,0 +1,74 @@
+module Hecks
+  module Bluebook
+    # An attribute that points at another aggregate's head.
+    #
+    # This used to be the STRING `"Reference<Customer>"`, minted by
+    # `AggregateBuilder#reference_to` and `CommandBuilder#cross_reference` from
+    # a real constant that had just been handed in, and then parsed back apart
+    # by a regex in the command interpreter, by string equality in the read-model
+    # interpreter and the SQLite adapter, and by `delete_prefix` in the bluebook
+    # builder. Five readers of a spelling one writer invented.
+    #
+    # It holds the TARGET instead, and answers `resolve` with the target's
+    # Aggregate. 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.
+    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.
+      attr_accessor :declared_in
+
+      def initialize(target_name)
+        @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.
+      def resolve
+        unless declared_in
+          raise DSL::Malformed,
+                "#{self} cannot say which aggregate declares it, so it cannot " \
+                "resolve — a reference that resolves to nothing is checked " \
+                "against nothing"
+        end
+
+        declared_in.hecks_owner&.aggregate(@target_name)
+      end
+
+      # The IR spelling, the one the export carries.
+      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.
+      def ==(other) = other.is_a?(Reference) && target_name == other.target_name
+      alias eql? ==
+      def hash = [self.class, target_name].hash
+    end
+  end
+end

data/lib/hecks/bluebook/smoke_test.rb

@@ -0,0 +1,166 @@
+require_relative "synthesizer"
+require "tmpdir"
+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.
+    #
+    # 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.
+    module SmokeTest
+      Failure = Struct.new(:domain, :aggregate, :command, :error, keyword_init: true) do
+        def to_s = "#{domain}::#{aggregate}.#{command}: #{error}"
+      end
+
+      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.
+      def call(dir)
+        Dir.mktmpdir("hecks-smoke-") do |scratch|
+          isolate!(dir, scratch)
+          dispatcher = Hecks.boot(scratch, install_facade: false)
+          domain     = dispatcher.registry.bluebooks.keys.first
+          next [] unless domain
+
+          smoke_domain(dispatcher, domain)
+        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.
+      def isolate!(dir, scratch)
+        source = Adapters::Folder.new.bluebook_directory(dir)
+        target = File.join(scratch, "bluebook")
+        FileUtils.mkdir_p(target)
+        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.
+      def smoke_domain(dispatcher, domain)
+        chapter = dispatcher.registry.bluebook(domain)
+        return [] unless chapter
+
+        created  = {}
+        failures = []
+
+        chapter.aggregates.each do |aggregate|
+          creating, noncreating = aggregate.commands.partition(&:creates?)
+
+          creating.each do |command|
+            args = Synthesizer.args_for(chapter, aggregate, command, created)
+            begin
+              result = dispatcher.dispatch("#{domain}::#{aggregate.name}.#{command.hecks_name}", **args)
+              created[aggregate.name] = result.instance.id
+            rescue StandardError => e
+              failures << Failure.new(domain: domain, aggregate: aggregate.name, command: command.hecks_name,
+                                      error: "#{e.class}: #{e.message}")
+              next
+            end
+
+            noncreating.each do |nc_command|
+              nc_args = Synthesizer.args_for(chapter, aggregate, nc_command, created).merge(id: created[aggregate.name])
+              dispatcher.dispatch("#{domain}::#{aggregate.name}.#{nc_command.hecks_name}", **nc_args)
+            rescue StandardError => e
+              failures << Failure.new(domain: domain, aggregate: aggregate.name, command: nc_command.hecks_name,
+                                      error: "#{e.class}: #{e.message}")
+            end
+          end
+        end
+
+        chapter.read_models.each do |model|
+          root_id = created[model.reference_target]
+          next unless root_id # nothing was created for this root — nothing to smoke-test yet, not a failure
+
+          dispatcher.query("#{domain}.#{model.query_name}", model.reference_name => root_id)
+        rescue StandardError => e
+          failures << Failure.new(domain: domain, aggregate: model.name, command: "report(#{model.name})",
+                                  error: "#{e.class}: #{e.message}")
+        end
+
+        failures
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/synthesizer.rb

@@ -0,0 +1,95 @@
+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.
+    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.
+      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.
+      def args_for(chapter, aggregate, command, created = {})
+        command.attributes.to_h do |attribute|
+          if attribute.reference?
+            [attribute.name, created.fetch(attribute.type.target_name, "smoke-test-id")]
+          else
+            [attribute.name, value_for(chapter, aggregate, attribute.type)]
+          end
+        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.
+      def value_for(chapter, aggregate, type_name)
+        value_object = aggregate.value_object(type_name) ||
+                       chapter.aggregates.filter_map { |a| a.value_object(type_name) }.first
+        return "smoke-test" unless value_object
+
+        return value_object.members.first.to_h if value_object.respond_to?(:closed_set?) && value_object.closed_set? && value_object.members.any?
+
+        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).
+      def field_value_for(chapter, aggregate, type_name)
+        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.
+      def scalar_for(primitive)
+        case primitive.to_s
+        when "Integer" then 0
+        when "Float" then 0.0
+        when "TrueClass", "FalseClass" then false
+        else "smoke-test"
+        end
+      end
+    end
+  end
+end