hecks 0.3.0 → 1.0.0

data/lib/hecks/fuzzing/isolated_boot.rb

@@ -1,5 +1,6 @@
 require "fileutils"
 require "tmpdir"
+require "securerandom"
 
 module Hecks
   module Fuzzing
@@ -23,15 +24,58 @@ module Hecks
     # domain's own rules and shape are untouched ; only WHICH adapter this
     # one ephemeral copy answers through changes. What the domain is
     # bound to for real deployment is never touched — only this tmp copy.
+    #
+    # `adapter:` (PRD 02) — Memory is the default and the only mode every
+    # existing caller still gets with no change. `:sqlite` rebinds to the
+    # REAL SQLite adapter instead of the in-memory one, for exactly the
+    # same reason PRD 02 exists: 15 declared properties (properties.rb)
+    # and every fuzz/replay run has only ever been checked against
+    # Memory's own hand-written repository, never against a real,
+    # persisted, SQL-backed one — and `spec/adapters/query_agreement_spec
+    # .rb` already found 4 shipped query bugs from exactly that
+    # comparison, on a fixed corpus far smaller than what the fuzzer
+    # generates. `:sqlite` rewrites to `"SqlitePersistence"` — the name
+    # `lib/hecks/adapters/driven/sqlite.adapter` actually registers under
+    # (`Sqlite` is the class; `SqlitePersistence` is a thin subclass
+    # that's the one real port binding names) — and needs no `.world`
+    # settings at all, the same reason Memory needs none:
+    # `Sqlite#resolve_path` already defaults an
+    # unbound `database` setting to `"data/<table>.db"` relative to
+    # `root:`, which `Hecks.boot(copy)` passes as this ephemeral copy's
+    # own directory — a fresh, empty `data/` per run, exactly like
+    # Memory's own zero-history guarantee, just backed by a real SQLite
+    # file instead of a Hash. Postgres/PostgresEra are deliberately NOT
+    # added here: a real Postgres run needs a live server and shared
+    # connection settings this in-process, no-adapter-config path has no
+    # place to source safely — that stays `io: true`-gated, direct-adapter
+    # coverage (`spec/adapters/driven/postgres_*_spec.rb`), not this.
     module IsolatedBoot
       module_function
 
-      def call(domain_path)
+      # PRD 02 (docs/future-features.md) — `adapter:` picks WHICH real
+      # persistence this one ephemeral boot answers through, not just
+      # Memory. `:memory` is the original, zero-config behavior (every
+      # other caller in this codebase that doesn't pass `adapter:` gets
+      # exactly what it always got). `:sqlite` is nearly as cheap —
+      # `Adapters::Sqlite#resolve_path` already defaults to
+      # `data/<table>.db` under the copy's own root with no settings at
+      # all, the same "needs nothing declared" property Memory has, so a
+      # real on-disk B-tree gets exercised for free. `:postgres` is the
+      # expensive one — a real server, a real round trip per dispatch —
+      # so `bin/fuzz --adapter postgres` is meant to run with smaller
+      # seed/step counts than the Memory default, not as a like-for-like
+      # swap; see that flag's own comment.
+      def call(domain_path, adapter: :memory)
         Dir.mktmpdir("hecks-fuzz") do |tmp|
           copy = File.join(tmp, File.basename(domain_path))
           copy_dereferencing(domain_path, copy)
           FileUtils.rm_rf(File.join(copy, "data"))
-          rebind_to_memory!(copy)
+          case adapter
+          when :memory   then rebind_to_memory!(copy)
+          when :sqlite   then rebind_to_sqlite!(copy)
+          when :postgres then rebind_to_postgres!(copy)
+          else raise ArgumentError, "unknown fuzz adapter #{adapter.inspect} — :memory, :sqlite, or :postgres"
+          end
           yield copy
         end
       end
@@ -47,8 +91,8 @@ module Hecks
       #
       # `FileUtils.cp` follows a symlink and copies its CONTENT, which is
       # what an isolated boot wants: the copy has to stand alone, since
-      # rebind_to_memory! rewrites files in it and must not reach back
-      # through a link into the real tree.
+      # rebind! rewrites files in it and must not reach back through a
+      # link into the real tree.
       def copy_dereferencing(source, destination)
         FileUtils.mkdir_p(destination)
         Dir.glob(File.join(source, "**", "*"), File::FNM_DOTMATCH).each do |path|
@@ -65,28 +109,178 @@ module Hecks
       end
 
       def rebind_to_memory!(copy)
-        Dir.glob(File.join(copy, "**", "*.hecksagon")).each do |path|
-          # `persisted_by`/`projected_by` can be spelled two ways now —
-          # aggregate-scoped (`Banking::Customer.persisted_by("Heki")`,
-          # always parenthesised) and, since §0's domain-level default
-          # binds, a bare call at the hecksagon's own root
-          # (`persisted_by "Heki"`, no parens, no receiver). Both must
-          # be caught here or a domain that only declares the bare form
-          # keeps its real adapter under an "isolated" fuzz boot.
-          lines = File.readlines(path).reject { |line| line.match?(/\bprojected_by\s*\(?\s*"/) }
-          File.write(path, lines.join.gsub(/persisted_by\s*\(?\s*"[^"]+"\s*\)?/, 'persisted_by("Memory")'))
-        end
+        rewrite_bindings!(copy, "Memory")
 
         # THE SETTINGS, NOT JUST THE BIND — `WorldBuilder#method_missing`
         # stores a settings block under BOTH "verb:adapter" and the bare
         # "verb" (world_builder.rb:32-33), so a bind rewritten to Memory
         # still falls back to whatever adapter's settings were declared
         # bare — Postgres's `database:`, which Memory does not take and
-        # WiringError refuses on sight. Memory needs no settings at all
-        # (a domain with no .world boots it as the default), so the
-        # simplest correct fix is dropping .world from the copy entirely.
+        # WiringError refuses on sight. Both Memory and Sqlite need no
+        # settings at all (`Sqlite#resolve_path` defaults `database` to
+        # `data/<table>.db` under `root:` when unset — the same
+        # zero-config default Memory gets from having no `.world` at
+        # all), so the simplest correct fix for either target is
+        # dropping `.world` from the copy entirely.
+        Dir.glob(File.join(copy, "**", "*.world")).each { |path| File.delete(path) }
+      end
+
+      # SAME DANCE AS MEMORY, ONE ADAPTER OVER — `Adapters::Sqlite#
+      # resolve_path` (adapters/driven/sqlite.rb) defaults to
+      # `data/<table>.db` under the boot's own root when no `database`
+      # setting is declared, which `data/` already being cleared makes a
+      # fresh on-disk store with zero configuration, the same "no .world
+      # needed" property Memory has. `data/` itself is left for Sqlite to
+      # recreate on first write, same as it always was for Memory/Heki —
+      # nothing here creates it up front.
+      def rebind_to_sqlite!(copy)
+        rewrite_bindings!(copy, "SqlitePersistence")
         Dir.glob(File.join(copy, "**", "*.world")).each { |path| File.delete(path) }
       end
+
+      # THE EXPENSIVE ONE — Postgres has no zero-config default the way
+      # Sqlite/Memory do (`Adapters::Postgres.connect_for` refuses outright
+      # with no `database` setting), so dropping `.world` the way the
+      # other two do would just move the WiringError from "wrong adapter"
+      # to "no adapter." Every domain name this copy declares gets a
+      # FRESH `.world` written for it instead — not a rewrite of whatever
+      # was there, a replacement, same reasoning `rewrite_bindings!`
+      # already applies to `.hecksagon`: this ephemeral boot owns every
+      # binding decision, nothing about a real deployment's own settings
+      # is relevant or safe to half-preserve here.
+      #
+      # ONE SHARED SCHEMA, DROPPED AND RECREATED BEFORE EVERY BOOT — not a
+      # fresh randomly-named one per call. `bin/fuzz` drives every
+      # ephemeral boot sequentially (one `IsolatedBoot.call` fully exits
+      # before the next begins — see that file's own single-threaded
+      # `while` loop), so nothing is ever concurrent here ; a fresh name
+      # every time would just leak schemas in `FUZZ_POSTGRES_DATABASE`
+      # forever with nothing to ever drop them. If a caller ever DOES
+      # start running fuzz adapters concurrently, this needs to move to a
+      # process-unique schema name (`SecureRandom.hex` is already
+      # `require`d here for exactly that day) — flagged, not solved,
+      # since nothing today calls this from more than one thread.
+      FUZZ_POSTGRES_DATABASE = "hecks_fuzz"
+      FUZZ_POSTGRES_SCHEMA   = "hecks_fuzz"
+
+      def rebind_to_postgres!(copy)
+        require "pg"
+        rewrite_bindings!(copy, "Postgres")
+        ensure_fuzz_schema!
+
+        # ONE `.world` PER DIRECTORY A `.hecksagon` ACTUALLY LIVES IN, not
+        # one at `copy`'s own root — `Folder#load_domain` resolves a
+        # SINGLE `bluebook_directory` and globs `*.world` there, non-
+        # recursively (`Folder#load_each`); a domain can hold several
+        # `Hecks.hecksagon "<Name>" do ... end` SIBLING blocks in that one
+        # file (banking.hecksagon declares "Banking", "Governance", and
+        # "Identity" together), so every name found in one `.hecksagon`
+        # file gets bundled into one `.world` written beside it, not
+        # scattered by name.
+        Dir.glob(File.join(copy, "**", "*.hecksagon")).each do |hecksagon_path|
+          names = File.read(hecksagon_path).scan(/Hecks\.hecksagon\s+"([^"]+)"/).flatten.uniq
+          next if names.empty?
+
+          world_path = File.join(File.dirname(hecksagon_path), "hecks_fuzz_postgres.world")
+          File.write(world_path, names.map { |name|
+            <<~WORLD
+              Hecks.world "#{name}" do
+                persisted_by("Postgres") do
+                  database "#{FUZZ_POSTGRES_DATABASE}"
+                  schema "#{FUZZ_POSTGRES_SCHEMA}"
+                end
+              end
+            WORLD
+          }.join("\n"))
+        end
+
+        # Any PRE-EXISTING `.world` this copy shipped with (a real
+        # deployment's own connection string) is now redundant with — and
+        # would conflict with, `Registry#add_world`'s own header on
+        # loading the same domain name twice — the fresh one just
+        # written above, so it goes the same way `rebind_to_memory!`
+        # already sends every `.world` in a Memory-mode boot.
+        Dir.glob(File.join(copy, "**", "*.world")).each do |path|
+          File.delete(path) unless File.basename(path) == "hecks_fuzz_postgres.world"
+        end
+      end
+
+      # ADMIN CONNECTION LIVES OUTSIDE THE TMP COPY ENTIRELY — same as
+      # every other real-Postgres spec in this repo (`support/
+      # postgres_probe.rb`'s own header). Database created once per
+      # process and remembered (`@fuzz_database_ready` on this module's
+      # own singleton, the same memoization shape `PostgresProbe
+      # .available?` already uses) ; the schema inside it is dropped and
+      # recreated on EVERY call, which is what actually isolates one
+      # ephemeral boot's data from the next.
+      def ensure_fuzz_schema!
+        # `Adapters::Postgres#initialize` opens ONE real `PG::Connection`
+        # PER AGGREGATE and never explicitly closes it — fine for a
+        # process that boots once and runs, exactly what every other
+        # caller of this adapter is. A fuzz run boots dozens to hundreds
+        # of EPHEMERAL times in one process (every seed does at least a
+        # generate + a replay, `replay_is_deterministic` doubles that,
+        # shrinking multiplies it further), and `PG::Connection` only
+        # actually closes its socket when Ruby's GC finalizes the
+        # (by-then-unreferenced) object — which, under a tight loop like
+        # this, does not reliably keep pace with how fast new
+        # connections open. Discovered live: `bin/fuzz --adapter
+        # postgres` against `examples/banking` hit a real local
+        # Postgres's own `max_connections` after roughly a dozen
+        # ephemeral boots, `PG::ConnectionBad: ... "too many clients
+        # already"`. A `GC.start` here — right before the next ephemeral
+        # boot's connections open, not on some timer — reclaims every
+        # connection the PREVIOUS boot's now-unreferenced adapters held,
+        # keeping the live count bounded regardless of run length. This
+        # is a real constraint on running Postgres in a loop, not
+        # something to route around by connecting less carefully.
+        GC.start
+
+        unless @fuzz_database_ready
+          admin = PG.connect(dbname: "postgres")
+          exists = admin.exec_params(
+            "SELECT 1 FROM pg_database WHERE datname = $1", [FUZZ_POSTGRES_DATABASE]
+          ).ntuples.positive?
+          admin.exec(%(CREATE DATABASE "#{FUZZ_POSTGRES_DATABASE}")) unless exists
+          admin.close
+          @fuzz_database_ready = true
+        end
+
+        db = PG.connect(dbname: FUZZ_POSTGRES_DATABASE)
+        # QUIET ON PURPOSE — same as `Adapters::Postgres.connect_for`'s
+        # own `SET client_min_messages`: a `DROP SCHEMA ... CASCADE` that
+        # actually has something to drop (every boot after the first)
+        # NOTICEs once per dropped object, which is the ordinary case
+        # here, not news, and would otherwise bury `bin/fuzz`'s own
+        # output under a wall of "drop cascades to table ..." on every
+        # single ephemeral boot.
+        db.exec("SET client_min_messages = warning")
+        quoted = db.quote_ident(FUZZ_POSTGRES_SCHEMA)
+        db.exec("DROP SCHEMA IF EXISTS #{quoted} CASCADE")
+        db.exec("CREATE SCHEMA #{quoted}")
+        db.close
+      end
+
+      # THE SHARED REWRITE — factored out of `rebind_to_memory!` when
+      # Sqlite/Postgres modes needed the identical `.hecksagon` surgery
+      # with only the target adapter name differing. `persisted_by`/
+      # `projected_by` can be spelled two ways: aggregate-scoped
+      # (`Banking::Customer.persisted_by("Heki")`, always parenthesised)
+      # and, since §0's domain-level default binds, a bare call at the
+      # hecksagon's own root (`persisted_by "Heki"`, no parens, no
+      # receiver). Both must be caught here or a domain that only
+      # declares the bare form keeps its real adapter under an
+      # "isolated" fuzz boot. `projected_by` is dropped outright rather
+      # than rebound, for every target adapter — `Registry
+      # #read_repository` already falls back to the authoritative
+      # repository when none exists, so a read model this ephemeral copy
+      # never wires is simply unread, not broken.
+      def rewrite_bindings!(copy, adapter_name)
+        Dir.glob(File.join(copy, "**", "*.hecksagon")).each do |path|
+          lines = File.readlines(path).reject { |line| line.match?(/\bprojected_by\s*\(?\s*"/) }
+          File.write(path, lines.join.gsub(/persisted_by\s*\(?\s*"[^"]+"\s*\)?/, "persisted_by(\"#{adapter_name}\")"))
+        end
+      end
     end
   end
 end

data/lib/hecks/fuzzing/properties.rb

@@ -236,9 +236,9 @@ module Hecks
       # comparison depended on, anything. Two independent replays, not a
       # cached one compared to itself, so a bug that corrupts the FIRST
       # run's own bookkeeping cannot pass by agreeing with itself.
-      def replay_is_deterministic(domain_path, steps)
-        first  = Replay.call(domain_path, steps)
-        second = Replay.call(domain_path, steps)
+      def replay_is_deterministic(domain_path, steps, adapter: :memory)
+        first  = Replay.call(domain_path, steps, adapter: adapter)
+        second = Replay.call(domain_path, steps, adapter: adapter)
 
         comparable = ->(history) { history.reject { |key, _| key == :bluebook || key == :bluebooks } }
         return true if comparable.call(first) == comparable.call(second)
@@ -257,9 +257,34 @@ module Hecks
       # drifted before — an adapter that ACCEPTS what the reference says
       # matches nothing, or orders what it refuses to order, shows up
       # here as a finding no self-referential adapter spec could see.
+      # M23 — `Replay` now runs the native and reference engines
+      # INDEPENDENTLY (each in its own begin/rescue — see that file's own
+      # comment at the capture site), so this property can tell apart what
+      # used to be indistinguishable: "both engines refused" (fine — the
+      # ask was genuinely bad, nothing to compare) from "one refused and
+      # the other did not" (a real divergence — the two engines disagree
+      # about whether the ask was even VALID, never mind what it answers).
+      # `native_refused`/`reference_refused` are read by KEY PRESENCE, not
+      # truthiness — `Replay` only ever adds `:error`/`:reference_error`
+      # to an entry when that side actually raised, so an absent key is an
+      # unambiguous "this side answered." A read-model ask (no reference
+      # twin attempted at all, `asked[:query]` without "::") is skipped
+      # entirely, same as always — there is no second engine to disagree
+      # with.
       def query_answers_match_reference(history)
         offenders = history.fetch(:queries).filter_map do |asked|
-          next if asked[:error] || asked[:reference_rows].nil?
+          next unless asked[:query].is_a?(String) && asked[:query].include?("::")
+
+          native_refused    = asked.key?(:error)
+          reference_refused = asked.key?(:reference_error)
+
+          if native_refused != reference_refused
+            next "#{asked[:query]} #{asked[:args].inspect} — native #{native_refused ? "refused (#{asked[:error]})" : 'answered'}, " \
+                 "but the reference interpreter #{reference_refused ? "refused (#{asked[:reference_error]})" : 'answered'} — " \
+                 "a refusal-shaped divergence, not just a differing row set"
+          end
+
+          next if native_refused
           next if asked[:rows] == asked[:reference_rows]
 
           "#{asked[:query]} #{asked[:args].inspect} answered #{asked[:rows].inspect} " \
@@ -462,10 +487,12 @@ module Hecks
 
           command = command_for_verb(bluebooks, refusal[:verb])
           next "#{refusal[:verb]} raised #{refusal[:kind]}, but no declared command resolves that verb" unless command
-          next if command.guard_descriptions.include?(match[2])
+
+          declared = effective_guard_descriptions(bluebooks, refusal[:verb], command)
+          next if declared.include?(match[2])
 
           "#{refusal[:verb]} refused — #{match[2].inspect} — but #{command.hecks_name} declares no given " \
-            "or ensures with that description (it declares #{command.guard_descriptions.inspect})"
+            "or ensures with that description (it declares #{declared.inspect})"
         end
 
         offenders.empty? || offenders.join("; ")
@@ -488,6 +515,25 @@ module Hecks
       # refusal read as "no declared command resolves that verb" purely
       # because `history[:bluebook]` was Expression, not Translation; the
       # refusal was real, this property's own domain resolution was not.
+      # A DELEGATING DOOR REFUSES WITH ITS TARGET'S OWN WORDS. `delegates_to`
+      # (CommandBuilder#delegates_to_impl) hands the whole dispatch to one
+      # entity command, and that command's given is what refuses — raised
+      # back through the door, in the door's name (chess: `Game.MoveKnight
+      # refused — "it is that color's turn"`, a given Knight.Move declares
+      # and MoveKnight, a pure passthrough, never could). Read the door's
+      # own guards first, then every delegation target's; an offence is
+      # only a description NEITHER declares. Found live mining chess's
+      # history: every refused move through a door read as undeclared.
+      def effective_guard_descriptions(bluebooks, verb, command)
+        own = command.guard_descriptions
+        delegated = command.mutations.select { |m| m.op == :delegate }.flat_map do |delegation|
+          domain, aggregate_name, = Naming.split_verb(verb)
+          target = command_for_verb(bluebooks, "#{domain}::#{aggregate_name}.#{delegation.target}")
+          target ? target.guard_descriptions : []
+        end
+        own + delegated
+      end
+
       def command_for_verb(bluebooks, verb)
         domain, aggregate_name, command_path = Naming.split_verb(verb)
         return nil unless command_path

data/lib/hecks/fuzzing/replay.rb

@@ -57,12 +57,12 @@ module Hecks
       # DISPATCH_ORDER.
       GUARD_REFUSAL_CLASSES = [Runtime::GivenNotMet, Runtime::LifecycleRefused].freeze
 
-      def call(domain_path, steps)
+      def call(domain_path, steps, adapter: :memory)
         # See isolated_boot.rb's own header: resets data/ AND rebinds
-        # persistence to Memory, since a Postgres-bound domain's real store
-        # lives outside the copied directory and cannot be reached by
-        # resetting data/ alone.
-        IsolatedBoot.call(domain_path) do |copy|
+        # persistence to the chosen adapter (Memory by default), since a
+        # Postgres-bound domain's real store lives outside the copied
+        # directory and cannot be reached by resetting data/ alone.
+        IsolatedBoot.call(domain_path, adapter: adapter) do |copy|
           runtime = Hecks.boot(copy)
 
           refusals        = []
@@ -112,22 +112,55 @@ module Hecks
                 next
               end
 
+              # THE QUERY ORACLE — TWO INDEPENDENT ENGINES, EACH RUN AND
+              # CAUGHT ON ITS OWN, never a single shared `begin`/`rescue`
+              # wrapping both calls. A shared begin/rescue meant `runtime.
+              # query` raising (native refuses) short-circuited BEFORE
+              # `runtime.reference_query` ever ran at all — the entry
+              # recorded only `error:`, with no `reference_rows` and no
+              # record of what the reference interpreter would have
+              # answered — and `runtime.reference_query` raising instead
+              # (reference refuses, native already succeeded) landed in the
+              # SAME rescue, discarding the native `rows` this begin block
+              # had already computed and recording the whole ask as an
+              # ordinary refusal. Either way, "one engine refused and the
+              # other did not" — a real divergence, exactly the shape a
+              # differential oracle exists to catch — read as "refused,
+              # nothing to compare" and vanished. Each engine's own
+              # success/failure is captured here independently instead, so
+              # `Properties.query_answers_match_reference` can tell "both
+              # refused" (fine) apart from "one refused, the other did not"
+              # (a finding) rather than having every refusal-shaped run
+              # skipped uniformly.
+              native_rows = native_error = nil
               begin
-                rows = runtime.query(question, **args)
-                # THE QUERY ORACLE'S OTHER HALF — the same ask at the same
-                # instant, answered by the reference interpreter instead of
-                # the bound adapter's native hook. Recorded side by side so
-                # Properties.query_answers_match_reference can treat any
-                # difference as a finding. Read-model asks (bare domain
-                # form, no "::") have no reference twin and record only the
-                # one answer.
-                reference = question.include?("::") ? runtime.reference_query(question, **args) : nil
-                queries << { query: question, args: args, rows: rows, reference_rows: reference,
-                             instances_at: snapshot_instances(runtime) }
+                native_rows = runtime.query(question, **args)
               rescue *Runtime::DOMAIN_REFUSALS, Bluebook::Expression::EvaluationError => e
-                queries << { query: question, args: args, error: e.message }
-                refusals << { verb: question, error: e.message, kind: e.class.name }
+                native_error = e
               end
+
+              # Read-model asks (bare domain form, no "::") have no
+              # reference twin at all — never attempted, not "attempted and
+              # agreed."
+              has_reference = question.include?("::")
+              reference_rows = reference_error = nil
+              if has_reference
+                begin
+                  reference_rows = runtime.reference_query(question, **args)
+                rescue *Runtime::DOMAIN_REFUSALS, Bluebook::Expression::EvaluationError => e
+                  reference_error = e
+                end
+              end
+
+              entry = { query: question, args: args, rows: native_rows, instances_at: snapshot_instances(runtime) }
+              entry[:error] = native_error.message if native_error
+              if has_reference
+                entry[:reference_rows]  = reference_rows
+                entry[:reference_error] = reference_error.message if reference_error
+              end
+              queries << entry
+
+              refusals << { verb: question, error: native_error.message, kind: native_error.class.name } if native_error
               next
             end
 

data/lib/hecks/fuzzing/sequence_generator/outcome_tracker.rb

@@ -1,4 +1,5 @@
 require_relative "../value_generator"
+require_relative "../../naming"
 
 module Hecks
   module Fuzzing
@@ -11,8 +12,7 @@ module Hecks
 
         def record_outcome(catalog, entry, args)
           aggregate = entry[:aggregate]
-          parent_key = (aggregate.identified_by || :id).to_s
-          parent_scalar = ValueGenerator.scalar_of(args[parent_key])
+          parent_scalar = identity_scalar_of(aggregate, args)
 
           @known_ids[aggregate.hecks_name] << parent_scalar if entry[:entity].nil? && entry[:command].creates?
 
@@ -35,6 +35,32 @@ module Hecks
           @entity_known_ids[key] << new_id
         end
 
+        # THE SCALAR THIS STEP'S OWN AGGREGATE IDENTITY RESOLVES TO, from the
+        # args a creating (or entity-populating) command actually
+        # dispatched — a SINGLE declared head (or the untyped default
+        # `:id`) reads straight off its own top-level arg the way this
+        # always has (`ValueGenerator.scalar_of`, opening the identity value
+        # object). A genuinely COMPOSITE identity (`composite_identity?`,
+        # shared with StepBuilder#add_identity! — see its own comment) has
+        # no such top-level arg at all: `add_identity!` deliberately leaves
+        # a composite creating command's own individually-declared fields
+        # alone rather than forcing a synthetic `id` neither the bluebook
+        # nor the command ever declared, so this joins those fields itself,
+        # in the SAME declaration order `Runtime::Identity.of` joins them
+        # at dispatch (`Naming.identity`, `Naming::IDENTITY_JOIN`) — which
+        # is exactly what makes the result usable later as the bare `id:`
+        # a composite Revoke/act-again command expects (`Identity.from`'s
+        # own untyped fallback, reached when `identity_of` finds no
+        # top-level field args to join, reads a bare `id:` straight
+        # through unattributed).
+        def identity_scalar_of(aggregate, args)
+          parent_key = (aggregate.identified_by || :id).to_s
+          return ValueGenerator.scalar_of(args[parent_key]) unless composite_identity?(aggregate)
+
+          parts = aggregate.identity_paths.map { |path| ValueGenerator.scalar_of(args[path.to_s.split(".").first]) }
+          Naming.identity(parts)
+        end
+
         def pick_known(name)
           pool = @known_ids[name]
           return ValueGenerator.random_id(@random) if pool.empty? || @random.rand < ValueGenerator::INVALID_REFERENCE_PROBABILITY

data/lib/hecks/fuzzing/sequence_generator/step_builder.rb

@@ -2,6 +2,8 @@ require_relative "../../bluebook/expression/resolver"
 require_relative "../invalid_value_generator"
 require_relative "../value_generator"
 require_relative "../../runtime/errors"
+require_relative "../../runtime/value"
+require_relative "../../naming"
 
 module Hecks
   module Fuzzing
@@ -52,10 +54,6 @@ module Hecks
 
         def args_for(attributes, aggregate)
           args = attributes.each_with_object({}) do |attribute, built|
-            # List-typed direct command arguments have no example in this repo's
-            # domains today — every list is populated via a per-element append
-            # command instead. Skipped rather than guessed at.
-            next if attribute.list?
             # AN OPTIONAL ARGUMENT IS SOMETIMES NOT GIVEN, and that is an
             # ordinary payload rather than a damaged one — see
             # OPTIONAL_OMITTED_PROBABILITY for why this cannot live in
@@ -63,12 +61,52 @@ module Hecks
             # exist at all.
             next if attribute.optional? && @random.rand < SequenceGenerator::OPTIONAL_OMITTED_PROBABILITY
 
-            built[attribute.name.to_s] = ValueGenerator.value_for(attribute, aggregate, random: @random, known_ids: @known_ids)
+            if attribute.list?
+              value = list_value_for(attribute, aggregate)
+              # A list-of-ENTITY command attribute has no real example
+              # anywhere in this repo's domains — every entity-owned list is
+              # populated via a per-element append command instead, never a
+              # whole-list command argument — so `list_value_for` (below)
+              # answers `nil` for one rather than guessing at an entity's own
+              # shape, and this step still skips it exactly as it always
+              # has. A list-of-VALUE-OBJECT attribute (`ConsoleSettings::
+              # Collection.ReplaceColumns`' own `columns`, `list_of(Column)`)
+              # is the real, previously-unfuzzable case this now covers —
+              # `sets :columns` imports the owner aggregate's own declared
+              # `list_of` attribute onto the command verbatim (Command
+              # Builder#resolve_bare_set!), so it is a required, ordinary
+              # top-level argument like any other, not an entity mutation.
+              next if value.nil?
+
+              built[attribute.name.to_s] = value
+            else
+              built[attribute.name.to_s] = ValueGenerator.value_for(attribute, aggregate, random: @random, known_ids: @known_ids)
+            end
           end
 
           malform(args, attributes, aggregate)
         end
 
+        # A `list_of` ATTRIBUTE'S OWN VALUE — an array of independently
+        # generated elements, each shaped exactly the way a bare (non-list)
+        # attribute of the SAME declared element type already is
+        # (`ValueGenerator.value_for`), since `list_of(X)`'s own element
+        # coercion is `X`'s ordinary shape repeated, not a different one
+        # (`Attribute#type` is already unwrapped from `list_of(...)` at
+        # declare time — the same fact `command_builder.rb`'s own comment
+        # on `resolve_bare_set!` names). 0-3 elements — enough to exercise a
+        # genuinely non-trivial replace without generating pathologically
+        # large payloads every time. `nil`, not `[]`, when the element type
+        # isn't a declared value object at all (an entity-typed list) — see
+        # `args_for`'s own comment on why that case still skips rather than
+        # guesses.
+        def list_value_for(attribute, aggregate)
+          value_object = Runtime::Value.value_object_for(aggregate, attribute.type.to_s)
+          return nil unless value_object
+
+          Array.new(@random.rand(0..3)) { ValueGenerator.value_for(attribute, aggregate, random: @random, known_ids: @known_ids) }
+        end
+
         # ONE MALFORMATION AT A TIME, and usually none. A step whose payload is
         # wrong in three ways only ever proves which check runs first ; wrong in
         # exactly one way names the check that fired. And the rate stays low on
@@ -120,13 +158,40 @@ module Hecks
             entity_scalar = pick_entity_known(aggregate.hecks_name, entry[:entity].hecks_name, parent_scalar)
             args[entity_key] = identity_shaped(entry[:entity], entry[:entity].identified_by, entity_scalar, aggregate)
           elsif entry[:command].creates?
-            args[parent_key] ||= identity_shaped(aggregate, aggregate.identified_by, ValueGenerator.random_id(@random), aggregate)
+            # A COMPOSITE IDENTITY (`identified_by` answering nil with MORE
+            # THAN ONE declared path — Behaviour::Identified's own "a
+            # composite has no single head" comment) supplies every one of
+            # its parts as its own ordinary, individually-declared command
+            # attribute already — `RoleAssignment::Assign` takes actor_id/
+            # role_name/starts_at directly, `args_for` (above) already
+            # generated all three. Forcing a synthetic top-level `id` here
+            # too — this codebase's own fallback for the SINGLE-key and the
+            # genuinely untyped (`identity_paths.empty?`, no `identified_by`
+            # declared at all) cases — hands a composite creating command
+            # an argument it never declared at all, refused every time as
+            # unknown before this check existed (a creating `Assign`/`Grant`
+            # step was never anything BUT refused). `identity_paths.empty?`
+            # is the untyped default (falls all the way back to a minted
+            # `:id` the runtime itself never declared as an attribute
+            # either), which still needs exactly the old minting behavior.
+            unless composite_identity?(aggregate)
+              args[parent_key] ||= identity_shaped(aggregate, aggregate.identified_by, ValueGenerator.random_id(@random), aggregate)
+            end
           else
             scalar = pick_known(aggregate.hecks_name)
             args[parent_key] = identity_shaped(aggregate, aggregate.identified_by, scalar, aggregate)
           end
         end
 
+        # TRUE ONLY FOR A GENUINE MULTI-FIELD IDENTITY — `identified_by`
+        # returns nil both for a real composite (`identity_paths.size > 1`)
+        # and for the untyped default with NO identity declared at all
+        # (`identity_paths.size == 0`, Behaviour::Identified's own
+        # `Array(@identified_by)` fallback) ; only the first of those two
+        # has its own parts already sitting in `args` as real, individually-
+        # generated command attributes.
+        def composite_identity?(aggregate) = aggregate.identified_by.nil? && aggregate.identity_paths.size > 1
+
         # A bare scalar id, shaped to match whatever `construct` itself
         # declares that identity field as. `Account::LedgerEntry` is addressed
         # by `sequence`, and `sequence` is declared as a value-object-typed

data/lib/hecks/fuzzing/sequence_generator.rb

@@ -73,8 +73,8 @@ module Hecks
       # the generating end rather than the scoring end.
       UNEXERCISED_WEIGHT = 4
 
-      def self.generate(domain_path, seed:, steps:)
-        new(domain_path, seed: seed, steps: steps).call
+      def self.generate(domain_path, seed:, steps:, adapter: :memory)
+        new(domain_path, seed: seed, steps: steps, adapter: adapter).call
       end
 
       # How many EVENTS the generated sequence actually produced — not
@@ -87,10 +87,11 @@ module Hecks
       # replay one.
       attr_reader :event_count
 
-      def initialize(domain_path, seed:, steps:)
+      def initialize(domain_path, seed:, steps:, adapter: :memory)
         @domain_path      = domain_path
         @seed             = seed
         @step_count       = steps
+        @adapter          = adapter
         @random           = Random.new(seed)
         @known_ids        = Hash.new { |h, k| h[k] = [] }
         @entity_known_ids = Hash.new { |h, k| h[k] = [] }
@@ -106,7 +107,7 @@ module Hecks
         # a Postgres-bound domain's real store lives outside the copied
         # directory entirely and `rm_rf`ing data/ alone cannot reach it —
         # see isolated_boot.rb's own header.
-        IsolatedBoot.call(@domain_path) do |copy|
+        IsolatedBoot.call(@domain_path, adapter: @adapter) do |copy|
           runtime = Hecks.boot(copy)
           catalog = build_catalog(runtime)
           Array.new(@step_count) { attempt_step(runtime, catalog) }.compact