hecks 4.0.0 → 6.0.0

data/lib/hecks/bluebook/model_check/reference_checks.rb

@@ -7,10 +7,19 @@ module Hecks
         # Types that name no aggregate's identity, however many aggregates declare one of them.
         PRIMITIVE_TYPES = %w[String Integer Float Boolean Date DateTime Time Symbol JSON Hash Array].freeze
 
+        # Every check over how aggregates relate: a link copied by value, a reference that outlives
+        # the record it names (OrphanChecks), and a branch on a tagged reference (OneOfChecks).
+        #
+        # @param bluebook [Bluebook::Declaration] the assembled bluebook to check
+        # @return [Array<Finding>] the three checks' findings, in that order
+        def reference_findings(bluebook)
+          [*key_by_value_findings(bluebook), *orphan_findings(bluebook), *one_of_branch_findings(bluebook)]
+        end
+
         # Flags each scalar attribute whose type is the identity type of another aggregate in
         # this domain and that is not itself a reference: the link exists only by convention.
         #
-        # @param bluebook [Bluebook::Chapter] the assembled chapter to check
+        # @param bluebook [Bluebook::Declaration] the assembled bluebook to check
         # @return [Array<Finding>] one :key_by_value warning per such attribute
         def key_by_value_findings(bluebook)
           owners = identity_type_owners(bluebook)
@@ -58,6 +67,7 @@ module Hecks
 
           target = (owners.fetch(attribute.type.to_s, []) - [aggregate.hecks_name]).first
           return unless target
+          return if Acknowledgements.held?(aggregate, :key_by_value, subject: attribute.name)
 
           Finding.new(kind: :key_by_value, severity: :warning,
                       subject: "#{aggregate.hecks_name}.#{attribute.name}",

data/lib/hecks/bluebook/model_check/saga_checks.rb

@@ -89,8 +89,9 @@ module Hecks
           return [] if process_manager.saga?
 
           handler.dispatches.select(&:compensates).map do |dispatch|
+            compensated = dispatch.compensates
             Finding.new(kind: :unarmed_compensation, severity: :error, subject: process_manager.name,
-                        message: "#{dispatch.command_name} compensates #{dispatch.compensates.command_name}, " \
+                        message: "#{dispatch.command_name} compensates #{compensated.command_name}, " \
                                  "but no handler anywhere in this saga answers a refusal — the " \
                                  "compensation is declared and can never fire")
           end
@@ -98,10 +99,14 @@ module Hecks
 
         # Checks whether a saga's own compensation leaves an unreachable state.
         def dead_compensation_findings(process_manager, reached)
-          return [] unless process_manager.saga? && !reached.include?(process_manager.saga.from_state)
+          return [] unless process_manager.saga?
+
+          saga = process_manager.saga
+          left = saga.from_state
+          return [] if reached.include?(left)
 
           [Finding.new(kind: :dead_compensation, severity: :error, subject: process_manager.name,
-                       message: "the compensation leaves #{process_manager.saga.from_state.inspect}, which no " \
+                       message: "the compensation leaves #{left.inspect}, which no " \
                                 "handler chain ever reaches — a refusal here can never fire it")]
         end
 

data/lib/hecks/bluebook/model_check/verbs.rb

@@ -6,16 +6,16 @@ module Hecks
         # Every bare event name this domain's commands and port operations emit,
         # answer, or refuse — an outbound `asks` port operation has no `.emits`.
         #
-        # @param bluebook [Bluebook::Chapter] the assembled chapter to enumerate
+        # @param bluebook [Bluebook::Declaration] the assembled bluebook to enumerate
         # @return [Array<String>] every bare event name emitted, answered, or refused
         #   across this domain, unique
         def emitted_events(bluebook)
           aggregate_emits = bluebook.aggregates.flat_map do |aggregate|
             command_emits(aggregate) + port_operation_events(aggregate.ports)
           end
-          chapter_emits = port_operation_events(bluebook.ports)
+          bluebook_emits = port_operation_events(bluebook.ports)
 
-          (aggregate_emits + chapter_emits).flatten.compact.uniq
+          (aggregate_emits + bluebook_emits).flatten.compact.uniq
         end
 
         # @return [Array] what each command of the aggregate and of its entities emits
@@ -44,7 +44,7 @@ module Hecks
 
         # Every aggregate-owned port operation's own fully-qualified verb — only an
         # aggregate's own ports are in scope; a policy trigger never names a
-        # chapter-level port directly.
+        # bluebook-level port directly.
         def port_verbs_of(bluebook)
           bluebook.aggregates.flat_map do |aggregate|
             aggregate.ports.flat_map do |port|

data/lib/hecks/bluebook/model_check.rb

@@ -4,8 +4,13 @@ require_relative "model_check/client_profile"
 require_relative "model_check/lifecycle_checks"
 require_relative "model_check/saga_checks"
 require_relative "model_check/policy_checks"
+require_relative "model_check/context_checks"
+require_relative "model_check/context_map_checks"
 require_relative "model_check/ask_checks"
 require_relative "model_check/reference_checks"
+require_relative "model_check/orphan_checks"
+require_relative "model_check/one_of_checks"
+require_relative "model_check/aggregate_checks"
 require_relative "model_check/verbs"
 
 module Hecks
@@ -26,30 +31,34 @@ module Hecks
       # The profiles `call` accepts; `nil` is the default, unprofiled run.
       PROFILES = %i[client].freeze
 
-      # What `call` takes from one corpus scan besides the chapter, and each key's default.
+      # What `call` takes from one corpus scan besides the bluebook, and each key's default.
       CONTEXT_DEFAULTS = {
-        hecksagon: nil, known_domains: nil, global_emitted_events: nil, rust_target: false, strict: false
+        hecksagon: nil, known_domains: nil, global_emitted_events: nil, aggregate_owners: nil,
+        rust_target: false, strict: false
       }.freeze
 
-      extend LifecycleChecks
       extend SagaChecks
       extend PolicyChecks
+      extend ContextChecks
       extend AskChecks
       extend ReferenceChecks
+      extend OrphanChecks
+      extend OneOfChecks
+      extend AggregateChecks
       extend Verbs
 
       module_function
 
       # Runs every static model check over `bluebook` and returns what it finds.
       #
-      # @param bluebook [Bluebook::Chapter] the assembled chapter to check
+      # @param bluebook [Bluebook::Declaration] the assembled bluebook to check
       # @param profile [Symbol, nil] :client adds ClientProfile's error findings
       # @param context [Hash] the rest of what one corpus scan knows, each key optional:
       #   `hecksagon` (this bluebook's own sibling wiring file, if the caller loaded one),
-      #   `known_domains` (every bluebook/hecksagon name booted anywhere in this corpus scan,
-      #   checked to catch a typo'd across/attaches target), `global_emitted_events` (every
-      #   event emitted anywhere in the corpus, checked as a fallback so a translates reaction
-      #   isn't flagged deaf), `rust_target` and `strict` (see `rust_reserved_name_findings`)
+      #   `known_domains` (every bluebook/hecksagon name in the scan, to catch a typo'd across or
+      #   attaches target), `global_emitted_events` (every event emitted in the corpus, so a
+      #   translates reaction isn't flagged deaf), `aggregate_owners` (each aggregate name to the
+      #   contexts declaring it, to find what a translates listens to), `rust_target` and `strict`
       # @return [Array<Finding>] every finding this bluebook triggers
       # @raise [ArgumentError] if profile is neither nil nor :client, or a context key is unknown
       def call(bluebook, profile: nil, **context)
@@ -63,17 +72,27 @@ module Hecks
         findings
       end
 
-      # Lifecycles, sagas, policies and references: what the model says about itself.
+      # Lifecycles, sagas, policies, references and aggregate size: what the model says about
+      # itself.
       def modelled_findings(bluebook, options)
         [
           *bluebook.aggregates.flat_map { |aggregate| aggregate_lifecycle_findings(aggregate) },
-          *key_by_value_findings(bluebook),
+          *reference_findings(bluebook),
+          *large_aggregate_findings(bluebook),
           *bluebook.process_managers.flat_map { |process_manager| saga_findings(bluebook, process_manager) },
+          *reaction_findings(bluebook, options),
+          *unused_ask_findings(bluebook)
+        ]
+      end
+
+      # Each policy's own checks, then the context a translates listens to.
+      def reaction_findings(bluebook, options)
+        [
           *bluebook.policies.flat_map do |policy|
             policy_findings(bluebook, policy, options[:hecksagon], options[:known_domains],
                             options[:global_emitted_events])
           end,
-          *unused_ask_findings(bluebook)
+          *translates_source_findings(bluebook, options[:hecksagon], options[:aggregate_owners])
         ]
       end
 
@@ -96,7 +115,8 @@ module Hecks
       # Flags a query the hecksagon binds to a port's adapter. Only the Ruby runtime asks an
       # adapter for an answer; a Rust host would find nothing behind the query.
       #
-      # @param bluebook [Bluebook::Chapter] the assembled chapter, its hecksagon's ports attached
+      # @param bluebook [Bluebook::Declaration] the assembled bluebook, its hecksagon's ports
+      #   attached
       # @param rust_target [Boolean] whether this domain has a real Rust target; a domain without
       #   one is not checked, since nothing but the Ruby runtime serves it
       # @return [Array<Finding>] one :external_query error per bound query, none off a Rust target

data/lib/hecks/bluebook/named_pattern.rb

@@ -14,7 +14,18 @@ module Hecks
         no_whitespace: '^[^ \t\n\r]+$',
         snake_name:    "^[a-z][a-z0-9_]*$",
         git_sha:       "^[0-9a-fA-F]{7,40}$",
-        digits:        "^[0-9]+$"
+        digits:        "^[0-9]+$",
+        identifier:    "^[A-Za-z][A-Za-z0-9_]*$",
+        csv_list:      '^[^ \t\n\r,]+(,[^ \t\n\r,]+)*$',
+        command_ref:   '^[A-Z][A-Za-z0-9]*::[A-Z][A-Za-z0-9]*\.[A-Z][A-Za-z0-9]*$',
+        host_port:     "^[A-Za-z0-9_-]+(:[0-9]+)?$",
+        instance_id:   "^i-[0-9a-f]+$",
+        hostname:      "^[A-Za-z0-9][A-Za-z0-9.-]*$",
+        word_chars:    "^[A-Za-z0-9_]*$",
+        version:       "^[0-9]+[.][0-9]+[.][0-9]+",
+        http_scheme:   "^https?://",
+        capitalized:   "[A-Z][A-Za-z0-9]*",
+        single_line:   '[^\n\r]'
       }.freeze
 
       module_function

data/lib/hecks/bluebook/one_of_union.rb

@@ -0,0 +1,35 @@
+module Hecks
+  module Bluebook
+    # The reading of a tagged reference (`reference_to one_of(A, B), as: :subject`, ADR 0127):
+    # its attribute carries the `one_of` relationship, its type is the tagged value object, and
+    # that value object's `type` admits the closed set of the variants' names.
+    module OneOfUnion
+      # The relationship the attribute of a tagged reference carries.
+      RELATIONSHIP = "one_of".freeze
+
+      module_function
+
+      # @param attribute [Bluebook::Attribute] any attribute
+      # @return [Boolean] whether it is a tagged reference to a closed union
+      def union?(attribute) = attribute.relationship == RELATIONSHIP
+
+      # The tagged references `owner` declares.
+      #
+      # @param owner [Bluebook::Aggregate] the aggregate to read
+      # @return [Array<Bluebook::Attribute>] each attribute carrying the `one_of` relationship
+      def attributes(owner) = Array(owner.attributes).select { |attribute| union?(attribute) }
+
+      # The aggregates a tagged reference may point at, in declared order.
+      #
+      # @param owner [Bluebook::Aggregate] the aggregate declaring `attribute`
+      # @param attribute [Bluebook::Attribute] a tagged reference of `owner`
+      # @return [Array<String>] the variants' aggregate names; empty when the shapes are missing
+      def variants(owner, attribute)
+        tagged = owner.value_object(attribute.type.to_s)
+        admits = tagged&.attribute(:type)&.admits
+        set = admits && owner.value_object(admits.split("::").last)
+        set ? set.members.map { |member| member.to_h[:value].to_s } : []
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/pattern_subset.rb

@@ -6,6 +6,15 @@ module Hecks
     # Which regexes a bluebook `pattern:` may say: only what every engine reads the same way.
     # Backtracking-only and ASCII/Unicode-dependent constructs are refused.
     module PatternSubset
+      # A digit from 1 to 9: what follows a backslash in a numbered backreference.
+      BACKREFERENCE_DIGIT = /[1-9]/
+
+      # One ASCII letter: a character of a POSIX class name such as `alpha`.
+      ASCII_LETTER = /[a-zA-Z]/
+
+      # One ASCII digit.
+      DIGIT = /[0-9]/
+
       module_function
 
       # Returns nil when the pattern is admitted, a Rejection when it is not.
@@ -43,7 +52,7 @@ module Hecks
       end
 
       def escape_refusal(nxt)
-        return :backreference if nxt&.match?(/[1-9]/)
+        return :backreference if nxt&.match?(BACKREFERENCE_DIGIT)
         return :named_backreference if %w[k g].include?(nxt)
 
         :perl_class if %w[d D w W s S].include?(nxt)
@@ -121,7 +130,7 @@ module Hecks
         return false unless chars[index] == "[" && chars[index + 1] == ":"
 
         cursor = index + 2
-        cursor += 1 while chars[cursor]&.match?(/[a-zA-Z]/)
+        cursor += 1 while chars[cursor]&.match?(ASCII_LETTER)
         chars[cursor] == ":" && chars[cursor + 1] == "]"
       end
 
@@ -146,7 +155,7 @@ module Hecks
       end
 
       def skip_digits(chars, cursor)
-        cursor += 1 while chars[cursor]&.match?(/[0-9]/)
+        cursor += 1 while chars[cursor]&.match?(DIGIT)
         cursor
       end
     end

data/lib/hecks/bluebook/project_loader.rb

@@ -24,8 +24,9 @@ module Hecks
       # Errors raised by `ProjectRegister#register` propagate.
       def load
         discovery.bluebook_directories.each do |directory|
-          runtime = Runtime.boot(directory)
-          register.register(runtime.registry.bluebooks.values, runtime.registry, runtime, directory)
+          runtime  = Runtime.boot(directory)
+          registry = runtime.registry
+          register.register(registry.bluebooks.values, registry, runtime, directory)
         end
         self
       end

data/lib/hecks/bluebook/project_register.rb

@@ -7,6 +7,20 @@ module Hecks
         def command? = fqn.command?
 
         def query?   = fqn.query?
+
+        # @return [String] the domain the entry's verb belongs to
+        def domain = fqn.domain
+
+        # @return [String, nil] the aggregate the verb belongs to; nil for a domain-level verb
+        def aggregate_name = fqn.aggregate
+
+        # @return [String] the verb as the entry's own dispatcher names it
+        def local_verb
+          aggregate_name ? "#{domain}::#{aggregate_name}.#{declared_verb}" : "#{domain}.#{declared_verb}"
+        end
+
+        # @return [Bluebook::Aggregate, nil] the verb's aggregate, when it is a real root
+        def aggregate = dispatcher.bluebook(domain)&.aggregate(aggregate_name)
       end
 
       class DuplicateFqn < StandardError; end
@@ -31,7 +45,7 @@ module Hecks
 
       def queries = entries.values.select(&:query?)
 
-      # Registers every aggregate command/query and read model query of each chapter, under
+      # Registers every aggregate command/query and read model query of each bluebook, under
       # its versioned and (if current) unversioned FQNs.
       #
       # @return [Bluebook::ProjectRegister] self
@@ -61,8 +75,9 @@ module Hecks
       end
 
       def register_declarations(context)
-        context.bluebook.aggregates.each { |aggregate| register_aggregate!(aggregate, context) }
-        context.bluebook.read_models.each do |model|
+        bluebook = context.bluebook
+        bluebook.aggregates.each { |aggregate| register_aggregate!(aggregate, context) }
+        bluebook.read_models.each do |model|
           register_pair!(context, :query, model.query_name, model.query_name)
         end
       end
@@ -92,8 +107,9 @@ module Hecks
       end
 
       def register_fqn!(context, kind, name, declared_verb, **scope)
-        fqn = Fqn.public_send(kind, realm: context.realm, domain: context.bluebook.name, **scope, kind => name)
-        add(fqn, context.directory, context.dispatcher, declared_verb, context.bluebook.version)
+        bluebook = context.bluebook
+        fqn = Fqn.public_send(kind, realm: context.realm, domain: bluebook.name, **scope, kind => name)
+        add(fqn, context.directory, context.dispatcher, declared_verb, bluebook.version)
       end
 
       # A directory's first registration is never refused; only a second one (another tenant

data/lib/hecks/bluebook/query.rb

@@ -35,6 +35,9 @@ module Hecks
       }.freeze
 
       # The keywords the `Options` base takes; the rest belong to the query itself.
+      # A `list_of(Name)` spelling, capturing the `Name` inside.
+      LIST_OF = /\Alist_of\((.*)\)\z/
+
       OPTION_KEYS = [:wheres, :order_by, :limit, :offset, :cursor, :authorization, :null_semantics,
                      :inspection].freeze
 
@@ -55,7 +58,7 @@ module Hecks
       # The value object a `returns` names, without the `list_of(...)` wrapper.
       #
       # @return [String, nil] the value object's name, or `nil` when the query returns nothing
-      def returns_name = @returns&.sub(/\Alist_of\((.*)\)\z/, '\1')
+      def returns_name = @returns&.sub(LIST_OF, '\1')
 
       # Says whether the answer is many rows of the returned value object.
       #

data/lib/hecks/bluebook/read_model.rb

@@ -68,11 +68,11 @@ module Hecks
       #   stringified, each reduction merged in only when declared, and
       #   `extra_options_to_h`'s own dynamic tail merged last
       def to_h
-        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(reduction_pairs)
-          .merge(extra_options_to_h)
+        rows = {
+          aggregate_heads: @aggregate_heads.map { |head| head.merge(as: head[:as].to_s) },
+          group_by:        @group_by.map { |row| row.merge(field: row[:field].to_s) }
+        }
+        super.merge(rows).merge(reduction_pairs).merge(extra_options_to_h)
       end
 
       private

data/lib/hecks/bluebook/reference.rb

@@ -2,7 +2,7 @@ module Hecks
   module Bluebook
     # An attribute that points at another aggregate's head.
     #
-    # Holds the target name and resolves lazily through the chapter's own IR, since
+    # Holds the target name and resolves lazily through the bluebook'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
@@ -20,9 +20,9 @@ module Hecks
       # 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
+      #   `declared_in`'s own bluebook does not declare one by this name
       # @raise [DSL::Malformed] if `declared_in` is unset, so there is no
-      #   chapter to resolve the target against
+      #   bluebook to resolve the target against
       def resolve
         unless declared_in
           raise DSL::Malformed,

data/lib/hecks/bluebook/smoke_test.rb

@@ -13,7 +13,7 @@ module Hecks
 
       # One smoke run: what is being dispatched through, which ids earlier commands minted, and
       # the failures collected so far.
-      Run = Struct.new(:dispatcher, :domain, :chapter, :created, :failures)
+      Run = Struct.new(:dispatcher, :domain, :declaration, :created, :failures)
 
       module_function
 
@@ -28,7 +28,8 @@ module Hecks
         Dir.mktmpdir("hecks-smoke-") do |scratch|
           isolate!(dir, scratch)
           dispatcher = Hecks.boot(scratch, install_driving: false)
-          domain     = dispatcher.registry.bluebooks.keys.first
+          registry   = dispatcher.registry
+          domain     = registry.bluebooks.keys.first
           next [] unless domain
 
           smoke_domain(dispatcher, domain)
@@ -43,7 +44,7 @@ module Hecks
       #   `.bluebook` files into
       # @return [void]
       def isolate!(dir, scratch)
-        source = Adapters::Folder.new.bluebook_directory(dir)
+        source = Ports::Loading.bootstrap.bluebook_directory(dir)
         target = File.join(scratch, "bluebook")
         FileUtils.mkdir_p(target)
         Dir.glob(File.join(source, "*.bluebook")).each { |file| FileUtils.cp(file, target) }
@@ -51,20 +52,20 @@ module Hecks
 
       # Walks aggregates in declaration order so later ones can reference earlier `created` ids.
       #
-      # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the
+      # @param dispatcher [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the
       #   booted dispatcher to dispatch synthesized commands and queries through
       # @param domain [String] the domain name to smoke-test, a key of
       #   `dispatcher.registry.bluebooks`
       # @return [Array<Failure>] every dispatch or query failure collected, in
-      #   declaration order; empty when `domain` names no loaded chapter or
+      #   declaration order; empty when `domain` names no loaded bluebook or
       #   nothing failed
       def smoke_domain(dispatcher, domain)
-        chapter = dispatcher.registry.bluebook(domain)
-        return [] unless chapter
+        declaration = dispatcher.registry.bluebook(domain)
+        return [] unless declaration
 
-        run = Run.new(dispatcher, domain, chapter, {}, [])
-        chapter.aggregates.each { |aggregate| smoke_aggregate(run, aggregate) }
-        chapter.read_models.each { |model| smoke_read_model(run, model) }
+        run = Run.new(dispatcher, domain, declaration, {}, [])
+        declaration.aggregates.each { |aggregate| smoke_aggregate(run, aggregate) }
+        declaration.read_models.each { |model| smoke_read_model(run, model) }
         run.failures
       end
 
@@ -73,7 +74,7 @@ module Hecks
         creating, noncreating = aggregate.commands.partition(&:creates?)
 
         creating.each do |command|
-          args = Synthesizer.args_for(run.chapter, aggregate, command, run.created)
+          args = Synthesizer.args_for(run.declaration, aggregate, command, run.created)
           next unless smoke_created?(run, aggregate, command, args)
 
           noncreating.each { |other| smoke_other(run, aggregate, other) }
@@ -83,7 +84,8 @@ module Hecks
       # @return [Boolean] whether the creating command dispatched; a refusal is recorded instead
       def smoke_created?(run, aggregate, command, args)
         result = run.dispatcher.dispatch_flat("#{run.domain}::#{aggregate.name}.#{command.hecks_name}", args)
-        run.created[aggregate.name] = result.instance.id
+        created = result.instance
+        run.created[aggregate.name] = created.id
         true
       rescue StandardError => e
         record_failure(run, aggregate.name, command.hecks_name, e)
@@ -92,7 +94,7 @@ module Hecks
 
       # Dispatches a command against the instance the creating command made; a refusal is recorded.
       def smoke_other(run, aggregate, command)
-        args = Synthesizer.args_for(run.chapter, aggregate, command, run.created).merge(id: run.created[aggregate.name])
+        args = Synthesizer.args_for(run.declaration, aggregate, command, run.created).merge(id: run.created[aggregate.name])
         run.dispatcher.dispatch_flat("#{run.domain}::#{aggregate.name}.#{command.hecks_name}", args)
       rescue StandardError => e
         record_failure(run, aggregate.name, command.hecks_name, e)

data/lib/hecks/bluebook/synthesizer.rb

@@ -8,22 +8,26 @@ module Hecks
       # Shared with `Attribute::PRIMITIVES` so the two lists cannot drift.
       PRIMITIVES = Attribute::PRIMITIVES
 
+      # What a String field gets when `"smoke-test"` fails its pattern: a date, then a digit string,
+      # fixed so the same pattern always gets the same value.
+      PATTERN_CANDIDATES = %w[2026-01-01 1 a].freeze
+
       module_function
 
       # Synthesizes arguments for `command`. A reference whose target is not in `created`
       # gets a placeholder id.
       #
-      # @param chapter [Bluebook::Chapter] resolves value object type names to their shapes
+      # @param bluebook [Bluebook::Declaration] resolves value object type names to their shapes
       # @param aggregate [Bluebook::Aggregate] the aggregate `command` belongs to
       # @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 = {})
+      def args_for(declaration, aggregate, command, created = {})
         command.attributes.to_h do |attribute|
           if attribute.reference?
-            [attribute.name, created.fetch(attribute.type.target_name, "smoke-test-id")]
+            [attribute.name, created.fetch(attribute.target_name, "smoke-test-id")]
           else
-            [attribute.name, value_for(chapter, aggregate, attribute.type)]
+            [attribute.name, value_for(declaration, aggregate, attribute.type)]
           end
         end
       end
@@ -31,7 +35,7 @@ module Hecks
       # 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
+      # @param bluebook [Bluebook::Declaration] the bluebook to search when
       #   `type_name` is not declared on `aggregate` itself
       # @param aggregate [Bluebook::Aggregate] the aggregate `type_name` is
       #   looked up on first
@@ -40,18 +44,49 @@ module Hecks
       #   no such value object is declared; otherwise a Hash of one value per
       #   field — the closed set's own first admitted member's fields, or one
       #   freshly synthesized scalar per declared field
-      def value_for(chapter, aggregate, type_name)
-        value_object = find_value_object(chapter, aggregate, type_name)
+      def value_for(declaration, aggregate, type_name)
+        value_object = find_value_object(declaration, aggregate, type_name)
         return "smoke-test" unless value_object
         return value_object.members.first.to_h if populated_closed_set?(value_object)
 
-        value_object.attributes.to_h { |field| [field.name, field_value_for(chapter, aggregate, field.type)] }
+        value_object.attributes.to_h { |field| [field.name, field_value(declaration, aggregate, field)] }
+      end
+
+      # A field's value, one that matches its pattern when a fixed candidate does.
+      #
+      # @param field [Bluebook::Attribute] the declared field
+      # @return [Object] `field_value_for`'s value, or the first of `PATTERN_CANDIDATES` the
+      #   field's pattern admits, when that value is a String the pattern refuses
+      def field_value(declaration, aggregate, field)
+        within_pattern(field.pattern, field_value_for(declaration, aggregate, field.type))
+      end
+
+      # @param pattern [String, nil] the field's regex source, if it declares one
+      # @param value [Object] a synthesized value
+      # @yieldreturn [Boolean] asked only of a value the pattern refuses: true keeps it as it is
+      # @return [Object] `value`, or the first of `PATTERN_CANDIDATES` the pattern admits when
+      #   `value` is a String it refuses and one fits
+      def within_pattern(pattern, value, &keep)
+        return value unless refused_by?(pattern, value)
+        return value if keep&.call
+
+        PATTERN_CANDIDATES.find { |candidate| pattern_admits?(pattern, candidate) } || value
+      end
+
+      # @return [Boolean] whether the value is a String the pattern, if any, does not admit
+      def refused_by?(pattern, value) = value.is_a?(String) && !pattern.nil? && !pattern_admits?(pattern, value)
+
+      # @return [Boolean] whether the regex source admits the text; false for a source Ruby rejects
+      def pattern_admits?(source, text)
+        Regexp.new(source).match?(text)
+      rescue RegexpError
+        false
       end
 
       # The value object `type_name` names, on `aggregate` first, then on any other aggregate.
-      def find_value_object(chapter, aggregate, type_name)
+      def find_value_object(declaration, aggregate, type_name)
         aggregate.value_object(type_name) ||
-          chapter.aggregates.filter_map { |a| a.value_object(type_name) }.first
+          declaration.aggregates.filter_map { |a| a.value_object(type_name) }.first
       end
 
       # Whether `value_object` is a closed set that admits at least one member.
@@ -61,14 +96,14 @@ module Hecks
 
       # A field's value: a scalar for a primitive type, otherwise the nested value object.
       #
-      # @param chapter [Bluebook::Chapter] see `value_for`
+      # @param bluebook [Bluebook::Declaration] see `value_for`
       # @param aggregate [Bluebook::Aggregate] see `value_for`
       # @param type_name [String] the field's declared type name
       # @return [Integer, Float, true, false, String, Hash{Symbol => Object}] a
       #   bare scalar when `type_name` is a true primitive (see `scalar_for`),
       #   otherwise `value_for`'s own result for the nested value object it names
-      def field_value_for(chapter, aggregate, type_name)
-        PRIMITIVES.include?(type_name.to_s) ? scalar_for(type_name) : value_for(chapter, aggregate, type_name)
+      def field_value_for(declaration, aggregate, type_name)
+        PRIMITIVES.include?(type_name.to_s) ? scalar_for(type_name) : value_for(declaration, aggregate, type_name)
       end
 
       # A primitive's synthesized value; closed-set fields are handled by `value_for`.