hecks 3.4.2 → 3.6.0

data/lib/hecks/fuzzing/differential/wire_comparison.rb

@@ -0,0 +1,74 @@
+require "json"
+require_relative "../nondeterministic"
+require_relative "../rust_gap_manifest"
+
+module Hecks
+  module Fuzzing
+    module Differential
+      # Puts a Ruby replay and a Rust binary's output into the same wire shapes and lists the
+      # fields on which they disagree, after dropping what the binary's gap manifest tolerates.
+      module WireComparison
+        module_function
+
+        # Round-trips `value` through JSON so it compares as plain wire data.
+        def jsonify(value) = JSON.parse(JSON.generate(value))
+
+        # Ruby's result in the wire shapes the Rust output is compared against.
+        def ruby_view(ruby_result)
+          { instances: jsonify(ruby_result[:instances]), events: jsonify(ruby_result[:events]),
+            refusals: refusal_rows(ruby_result[:refusals]),
+            queries: jsonify(ruby_result[:queries].map { |row| Nondeterministic.strip(row, :query_row) }),
+            sagas: jsonify(ruby_result[:sagas]),
+            dry_runs: dry_run_rows(ruby_result[:dry_runs]) }
+        end
+
+        def dry_run_rows(dry_runs) = dry_runs.map { |d| { "verb" => d[:verb].to_s, "ok" => d[:ok] } }
+
+        def refusal_rows(refusals)
+          refusals.map { |r| { "verb" => r[:verb].to_s, "kind" => r[:kind].to_s.split("::").last, "error" => r[:error] } }
+        end
+
+        # One `{field:, ruby:, rust:}` entry per wire field on which the two engines disagree.
+        def differential_divergences(differ, ruby_result, rust_output, binary)
+          view = ruby_view(ruby_result)
+          kept = Differential.manifest_partition(RustGapManifest.for_binary(binary),
+                                                 ruby_refusals: view[:refusals], rust_refusals: rust_output["refusals"],
+                                                 ruby_queries: view[:queries], rust_queries: rust_output["queries"])
+          differ.structural_skips.merge(kept[:skipped])
+          plain_divergences(view, rust_output) + kept[:stale] + kept_divergences(differ, ruby_result, view, rust_output, kept)
+        end
+
+        def plain_divergences(view, rust_output)
+          [compare("instances", view[:instances], rust_output["instances"]),
+           compare("events", view[:events], rust_output["events"])].compact
+        end
+
+        def kept_divergences(differ, ruby_result, view, rust_output, kept)
+          [compare("refusals", *kind_rows(kept)),
+           compare("queries", *wire_queries(differ, kept)),
+           compare("sagas", view[:sagas], rust_output["sagas"]),
+           compare("reactions", *reactions(differ, ruby_result, rust_output)),
+           compare("dry_runs", view[:dry_runs], Array(rust_output["dry_runs"]).map { |d| d.slice("verb", "ok") })].compact
+        end
+
+        def kind_rows(kept)
+          by_kind = ->(row) { row.slice("verb", "kind") }
+          [kept[:ruby_refusals].map(&by_kind), kept[:rust_refusals].map(&by_kind)]
+        end
+
+        def wire_queries(differ, kept)
+          wordless = ->(row) { differ.reduce_to_wire_precision(row.except("error", "reference_error")) }
+          [kept[:ruby_queries].map(&wordless), kept[:rust_queries].map(&wordless)]
+        end
+
+        def reactions(differ, ruby_result, rust_output)
+          cross_domain = differ.cross_domain_policy_names(rust_output)
+          [jsonify(ruby_result[:reactions]).reject { |r| cross_domain.include?(r["policy"]) },
+           rust_output.fetch("reactions")]
+        end
+
+        def compare(field, ruby, rust) = ruby == rust ? nil : { field: field, ruby: ruby, rust: rust }
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/differential.rb

@@ -6,6 +6,7 @@ require_relative "self_consistency"
 require_relative "rust_gap_manifest"
 require_relative "../rust_build/kernel_input"
 require_relative "nondeterministic"
+require_relative "differential/wire_comparison"
 
 module Hecks
   module Fuzzing
@@ -30,18 +31,26 @@ module Hecks
       # @return [Hash] the four row lists with tolerated verbs removed, `skipped:` (a
       #   `Set<String>` of tolerated verbs reached) and `stale:` (`Array<Hash>` divergences)
       def manifest_partition(gaps, ruby_refusals:, rust_refusals:, ruby_queries:, rust_queries:)
-        verb_of  = ->(row) { row.key?("verb") ? row["verb"] : row["query"] }
-        declared = ->(row) { gaps.not_generated?(verb_of.call(row)) }
-        stale = rust_queries.select(&declared).map do |row|
+        declared = ->(row) { gaps.not_generated?(wire_verb(row)) }
+        lists = { ruby_refusals: ruby_refusals, rust_refusals: rust_refusals,
+                  ruby_queries: ruby_queries, rust_queries: rust_queries }
+        reached = (ruby_refusals + rust_refusals + ruby_queries).select(&declared)
+        lists.transform_values { |rows| rows.reject(&declared) }
+             .merge(skipped: reached.to_set { |row| wire_verb(row) },
+                    stale:   stale_rows(gaps, rust_queries.select(&declared)))
+      end
+
+      # The verb a refusal row names, or the query a query row names.
+      def wire_verb(row) = row.key?("verb") ? row["verb"] : row["query"]
+
+      # One divergence per tolerated query the Rust binary answered anyway.
+      def stale_rows(gaps, answered)
+        answered.map do |row|
           { field: "manifest", verb: row["query"],
-            detail: "#{row['query']} is declared generated: false in manifest.json " \
-                    "(#{gaps.not_generated(row['query']).values_at('gap_class', 'construct').join('/')}), " \
+            detail: "#{row["query"]} is declared generated: false in manifest.json " \
+                    "(#{gaps.not_generated(row["query"]).values_at("gap_class", "construct").join("/")}), " \
                     "but the Rust binary answered it — regenerate with hecks project_rust" }
         end
-        reached = (ruby_refusals + rust_refusals + ruby_queries).select(&declared)
-        { ruby_refusals: ruby_refusals.reject(&declared), rust_refusals: rust_refusals.reject(&declared),
-          ruby_queries: ruby_queries.reject(&declared), rust_queries: rust_queries.reject(&declared),
-          skipped: reached.to_set(&verb_of), stale: stale }
       end
 
       # Runs the standard property battery on a replayed history.
@@ -63,95 +72,61 @@ module Hecks
         history[:self_consistency].values.flatten(1)
       end
 
-      # rubocop:disable-next Metrics/AbcSize
-      # rubocop:disable-next Metrics/CyclomaticComplexity
-      # rubocop:disable-next Metrics/PerceivedComplexity
-      # rubocop:disable-next Metrics/MethodLength
       # @param differ [Object] duck-typed `RustConformanceHelpers` interface
       # @param domain_path [String] the domain directory to replay
       # @param steps [Array<Hash>] the step sequence replayed on both engines
       # @param binary [String] the compiled Rust conformance binary
-      # @param modes [Array<Symbol>] `:differential` (always run), `:self_consistency`,
-      #   `:properties_in_differential`, `:adapter_parity_sqlite`
-      # @param adapter_parity_sqlite [Proc, nil] the caller's comparison; `nil` skips the mode
+      # @param options [Hash] `modes:` (required), an Array of Symbols: `:differential` (always
+      #   run), `:self_consistency`, `:properties_in_differential`, `:adapter_parity_sqlite`; and
+      #   `adapter_parity_sqlite:`, the caller's comparison as a Proc, or `nil` (the default) to
+      #   skip that mode
       # @return [Hash{Symbol => Array<Hash>}] one divergence list per active mode
-      def diff(differ, domain_path, steps, binary, modes:, adapter_parity_sqlite: nil)
-        self_consistency = modes.include?(:self_consistency)
-        ruby_result    = Replay.call(domain_path, steps, self_consistency: self_consistency)
-        ruby_instances = JSON.parse(JSON.generate(ruby_result[:instances]))
-        ruby_events    = JSON.parse(JSON.generate(ruby_result[:events]))
-        ruby_refusals  = ruby_result[:refusals].map do |r|
-          { "verb" => r[:verb].to_s, "kind" => r[:kind].to_s.split("::").last, "error" => r[:error] }
-        end
-        ruby_queries  = JSON.parse(JSON.generate(ruby_result[:queries].map { |row| Nondeterministic.strip(row, :query_row) }))
-        ruby_sagas    = JSON.parse(JSON.generate(ruby_result[:sagas]))
-        ruby_dry_runs = ruby_result[:dry_runs].map { |d| { "verb" => d[:verb].to_s, "ok" => d[:ok] } }
+      def diff(differ, domain_path, steps, binary, **options)
+        modes, adapter_parity = diff_options(options)
+        ruby_result = Replay.call(domain_path, steps, self_consistency: modes.include?(:self_consistency))
+        outcomes = mode_outcomes(ruby_result, modes, adapter_parity)
+        stdout, status = Open3.capture2(binary, stdin_data: RustBuild::KernelInput.json(domain_path, steps))
+        return outcomes.merge(differential: [process_failure(status, stdout)]) unless status.success?
 
-        outcomes = {}
-        outcomes[:properties_in_differential] = property_divergences(ruby_result) if modes.include?(:properties_in_differential)
-        if modes.include?(:adapter_parity_sqlite) && adapter_parity_sqlite
-          outcomes[:adapter_parity_sqlite] = adapter_parity_sqlite.call
-        end
+        rust_outcomes = rust_outcomes(differ, ruby_result, JSON.parse(stdout), binary, modes.include?(:self_consistency))
+        outcomes.merge(rust_outcomes)
+      end
 
-        stdout, status = Open3.capture2(binary, stdin_data: RustBuild::KernelInput.json(domain_path, steps))
-        unless status.success?
-          return outcomes.merge(differential: [{ field:  "process",
-                                                 detail: "rust binary exited #{status.exitstatus}: #{stdout}" }])
-        end
+      # Splits the keywords of `diff` into the modes and the parity hook, refusing any other.
+      def diff_options(options)
+        unknown = options.keys - [:modes, :adapter_parity_sqlite]
+        raise ArgumentError, "unknown keyword: #{unknown.first.inspect}" if unknown.any?
+
+        [options.fetch(:modes) { raise ArgumentError, "missing keyword: :modes" }, options[:adapter_parity_sqlite]]
+      end
 
-        rust_output = JSON.parse(stdout)
-        rust_live_instances = JSON.parse(JSON.generate(rust_output["instances"])) if self_consistency
+      # The `:differential` outcome, plus `:self_consistency` when that mode is active.
+      def rust_outcomes(differ, ruby_result, rust_output, binary, self_consistency)
+        live_instances = WireComparison.jsonify(rust_output["instances"]) if self_consistency
         differ.strip_emitted_flags!(rust_output["instances"])
         differ.strip_emitted_flags!(rust_output["queries"])
         differ.strip_occurred_at!(rust_output["events"])
+        outcomes = { differential: WireComparison.differential_divergences(differ, ruby_result, rust_output, binary) }
+        outcomes[:self_consistency] = rust_self_consistency(ruby_result, binary, differ, live_instances) if self_consistency
+        outcomes
+      end
 
-        divergences = []
-        divergences << { field: "instances", ruby: ruby_instances, rust: rust_output["instances"] } \
-          unless rust_output["instances"] == ruby_instances
-        divergences << { field: "events", ruby: ruby_events, rust: rust_output["events"] } \
-          unless rust_output["events"] == ruby_events
-
-        kept = manifest_partition(RustGapManifest.for_binary(binary),
-                                  ruby_refusals: ruby_refusals, rust_refusals: rust_output["refusals"],
-                                  ruby_queries: ruby_queries, rust_queries: rust_output["queries"])
-        differ.structural_skips.merge(kept[:skipped])
-        divergences.concat(kept[:stale])
-
-        by_kind = ->(r) { r.slice("verb", "kind") }
-        rust_refusals      = kept[:rust_refusals].map(&by_kind)
-        kept_ruby_refusals = kept[:ruby_refusals].map(&by_kind)
-        divergences << { field: "refusals", ruby: kept_ruby_refusals, rust: rust_refusals } \
-          unless rust_refusals == kept_ruby_refusals
-
-        wordless          = ->(row) { differ.reduce_to_wire_precision(row.except("error", "reference_error")) }
-        rust_queries      = kept[:rust_queries].map(&wordless)
-        kept_ruby_queries = kept[:ruby_queries].map(&wordless)
-        divergences << { field: "queries", ruby: kept_ruby_queries, rust: rust_queries } \
-          unless rust_queries == kept_ruby_queries
-
-        divergences << { field: "sagas", ruby: ruby_sagas, rust: rust_output["sagas"] } \
-          unless rust_output["sagas"] == ruby_sagas
-
-        cross_domain = differ.cross_domain_policy_names(rust_output)
-        kept_ruby_reactions = JSON.parse(JSON.generate(ruby_result[:reactions]))
-                                  .reject { |r| cross_domain.include?(r["policy"]) }
-        rust_reactions = rust_output.fetch("reactions")
-        divergences << { field: "reactions", ruby: kept_ruby_reactions, rust: rust_reactions } \
-          unless rust_reactions == kept_ruby_reactions
-
-        rust_dry_runs = Array(rust_output["dry_runs"]).map { |d| d.slice("verb", "ok") }
-        divergences << { field: "dry_runs", ruby: ruby_dry_runs, rust: rust_dry_runs } \
-          unless rust_dry_runs == ruby_dry_runs
-        outcomes[:differential] = divergences
+      # The modes that run on the Ruby side alone, before the binary is touched.
+      def mode_outcomes(ruby_result, modes, adapter_parity)
+        outcomes = {}
+        outcomes[:properties_in_differential] = property_divergences(ruby_result) if modes.include?(:properties_in_differential)
+        outcomes[:adapter_parity_sqlite] = adapter_parity.call if modes.include?(:adapter_parity_sqlite) && adapter_parity
+        outcomes
+      end
 
-        if self_consistency
-          outcomes[:self_consistency] =
-            self_consistency_divergences(ruby_result) +
-            SelfConsistency.check_rust_rehydration(binary, differ, rust_live_instances) +
-            SelfConsistency.check_rust_idempotency(binary, differ, rust_live_instances)
-        end
+      def process_failure(status, stdout)
+        { field: "process", detail: "rust binary exited #{status.exitstatus}: #{stdout}" }
+      end
 
-        outcomes
+      def rust_self_consistency(ruby_result, binary, differ, rust_live_instances)
+        self_consistency_divergences(ruby_result) +
+          SelfConsistency.check_rust_rehydration(binary, differ, rust_live_instances) +
+          SelfConsistency.check_rust_idempotency(binary, differ, rust_live_instances)
       end
     end
   end

data/lib/hecks/fuzzing/domain_generator/block_rendering.rb

@@ -0,0 +1,70 @@
+module Hecks
+  module Fuzzing
+    module DomainGenerator
+      # Renders the blocks a blueprint nests inside aggregates and entities: value objects,
+      # lifecycles and commands.
+      module BlockRendering
+        def render_value_object(name, value_object, indent)
+          body = value_object_body(name, value_object)
+          ["", "#{indent}value_object #{name.inspect} do", *body.map { |line| "#{indent}  #{line}" }, "#{indent}end"]
+        end
+
+        def value_object_body(name, value_object)
+          case value_object["kind"]
+          when "string"   then string_body(name)
+          when "positive" then ["attribute :value, Integer", "invariant(#{"a #{name} is positive".inspect}) { value.positive? }"]
+          when "integer"  then ["attribute :value, Integer"]
+          when "closed"   then ["attribute :value, String, one_of: #{value_object["members"].inspect}"]
+          end
+        end
+
+        def string_body(name)
+          ["attribute :value, String, pattern: '[^ \\t\\n\\r]'",
+           "invariant(#{"a #{name} is not blank".inspect}) { !value.to_s.empty? }"]
+        end
+
+        def render_lifecycle(lifecycle, indent)
+          ["", "#{indent}lifecycle :#{lifecycle["field"]}, default: #{lifecycle["default"].inspect} do",
+           *lifecycle["transitions"].map { |transition| render_transition(transition, indent) },
+           "#{indent}end"]
+        end
+
+        def render_transition(transition, indent)
+          from = transition["from"].size == 1 ? transition["from"].first.inspect : transition["from"].inspect
+          "#{indent}  transition #{transition["command"].inspect} => #{transition["to"].inspect}, from: #{from}"
+        end
+
+        def render_command(command, self_name, indent)
+          ["", "#{indent}command #{command["name"].inspect} do",
+           *command_header(command, self_name, indent),
+           *command_body(command, indent),
+           "#{indent}end"]
+        end
+
+        # A command's role, goal and references.
+        def command_header(command, self_name, indent)
+          out = []
+          out << "#{indent}  role #{command["role"].inspect}" if command["role"]
+          out << "#{indent}  goal #{"#{command["name"]} it".inspect}"
+          out << "#{indent}  reference_to #{self_name}" if self_name && !command["creates"]
+          out + command["references"].map { |target| "#{indent}  reference_to #{target}" }
+        end
+
+        # A command's arguments, givens, sets and emitted events.
+        def command_body(command, indent)
+          [*command["args"].map { |arg| "#{indent}  #{render_attribute(arg)}" },
+           *command["givens"].map { |given| "#{indent}  given(#{given["label"].inspect}) { #{given["expr"]} }" },
+           *command["sets"].map { |set| "#{indent}  #{render_set(set)}" },
+           *command["emits"].map { |event| "#{indent}  emits #{event.inspect}" }]
+        end
+
+        def render_set(set)
+          return "sets :#{set["target"]}, to: :#{set["to"]}" if set["to"]
+          return "sets :#{set["target"]}, append: { #{set["append"].map { |k, v| "#{k}: :#{v}" }.join(", ")} }" if set["append"]
+
+          "sets :#{set["target"]}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/domain_generator/builder/attribute_shapes.rb

@@ -0,0 +1,105 @@
+module Hecks
+  module Fuzzing
+    module DomainGenerator
+      class Builder
+        # The shapes a form puts on one aggregate's attributes and rules: lifecycle, query, list,
+        # closed set, default and optional attributes.
+        module AttributeShapes
+          private
+
+          def lifecycle(aggregate)
+            return if aggregate["lifecycle"]
+
+            name = aggregate["name"]
+            command(aggregate, "Close")
+            command(aggregate, "Reopen")
+            aggregate["lifecycle"] = { "field" => "status", "default" => "open", "transitions" => [
+              { "command" => "Close", "to" => "closed", "from" => ["open"], "requires" => ["command:#{name}.Close"] },
+              { "command" => "Reopen", "to" => "open", "from" => ["closed"], "requires" => ["command:#{name}.Reopen"] }
+            ] }
+          end
+
+          def query(aggregate)
+            return if aggregate["queries"].any? { |query| query["name"] == "Listed" }
+
+            where = if aggregate["lifecycle"] || chance?(0.5)
+                      lifecycle(aggregate)
+                      { "field" => "status", "value" => "open", "requires" => ["lifecycle:#{aggregate["name"]}"] }
+                    else
+                      priority_where(aggregate)
+                    end
+            aggregate["queries"] << { "name" => "Listed", "wheres" => [where], "order_by" => aggregate["identity"].first }
+          end
+
+          def priority_where(aggregate)
+            members = closed_set(aggregate)
+            { "field" => "priority.value", "value" => members.first,
+              "requires" => ["attribute:#{aggregate["name"]}.priority"] }
+          end
+
+          def list_attr(aggregate)
+            name = aggregate["name"]
+            return if aggregate["attributes"].any? { |attribute| attribute["name"] == "tags" }
+
+            vo(aggregate, "#{name}Tag", "string")
+            aggregate["attributes"] << { "name" => "tags", "type" => "#{name}Tag", "list" => true }
+            command(aggregate, "Retag", args: [{ "name" => "tags", "type" => "#{name}Tag", "list" => true }],
+                                        sets: [{ "target" => "tags", "requires" => ["attribute:#{name}.tags"] }])
+          end
+
+          def closed_set(aggregate)
+            name = aggregate["name"]
+            existing = aggregate["vos"]["#{name}Priority"]
+            return existing["members"] if existing
+
+            members = CLOSED_SETS.sample(random: @random)
+            vo(aggregate, "#{name}Priority", "closed", members: members)
+            aggregate["attributes"] << { "name" => "priority", "type" => "#{name}Priority", "optional" => true }
+            command(aggregate, "Prioritize", args: [{ "name" => "priority", "type" => "#{name}Priority" }],
+                                             sets: [{ "target" => "priority", "requires" => ["attribute:#{name}.priority"] }])
+            members
+          end
+
+          def default_attr(aggregate)
+            name = aggregate["name"]
+            return if aggregate["attributes"].any? { |attribute| attribute["name"] == "score" }
+
+            vo(aggregate, "#{name}Score", "integer")
+            aggregate["attributes"] << { "name" => "score", "type" => "#{name}Score", "default" => 0 }
+            add_rescore(aggregate, name)
+            score_invariant(aggregate, name) if chance?(0.5)
+          end
+
+          def add_rescore(aggregate, name)
+            score = "attribute:#{name}.score"
+            command(aggregate, "Rescore", args: [{ "name" => "amount", "type" => "#{name}Score" }], givens: score_givens(name),
+                                          sets: [{ "target" => "score", "to" => "amount", "requires" => [score] }])
+          end
+
+          def score_invariant(aggregate, name)
+            aggregate["invariants"] << { "label" => "a score is never negative", "expr" => "score.value >= 0",
+                                         "requires" => ["attribute:#{name}.score"] }
+          end
+
+          # Half the time, a given that a score never drops.
+          def score_givens(name)
+            return [] unless chance?(0.5)
+
+            [{ "label" => "a score never drops", "expr" => "amount.value >= score.value",
+               "requires" => ["attribute:#{name}.score"] }]
+          end
+
+          def optional_arg(aggregate)
+            name = aggregate["name"]
+            return if aggregate["attributes"].any? { |attribute| attribute["name"] == "note" }
+
+            vo(aggregate, "#{name}Note", "string")
+            aggregate["attributes"] << { "name" => "note", "type" => "#{name}Note", "optional" => true }
+            command(aggregate, "Annotate", args: [{ "name" => "note", "type" => "#{name}Note", "optional" => true }],
+                                           sets: [{ "target" => "note", "requires" => ["attribute:#{name}.note"] }])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/domain_generator/builder/shapes.rb

@@ -0,0 +1,97 @@
+module Hecks
+  module Fuzzing
+    module DomainGenerator
+      class Builder
+        # The shapes a form puts on one aggregate's identity and entities.
+        module Shapes
+          private
+
+          def composite_id(aggregate)
+            return if aggregate["identity"].size > 1
+
+            name = aggregate["name"]
+            vo(aggregate, "#{name}Branch", "string")
+            vo(aggregate, "#{name}Number", "positive")
+            aggregate["identity"] = %w[branch number]
+            swap_code_attribute!(aggregate, name)
+            open = creating(aggregate)
+            open["args"] = branch_number_attributes(name)
+            open["sets"] = [{ "target" => "branch" }, { "target" => "number" }]
+            aggregate["vos"].delete("#{name}Code")
+          end
+
+          def swap_code_attribute!(aggregate, name)
+            aggregate["attributes"].reject! { |attribute| attribute["name"] == "code" }
+            aggregate["attributes"].unshift(*branch_number_attributes(name))
+          end
+
+          def branch_number_attributes(name)
+            [{ "name" => "branch", "type" => "#{name}Branch" }, { "name" => "number", "type" => "#{name}Number" }]
+          end
+
+          def entity(aggregate, composite: false, lifecycle: false)
+            name = next_entity_name(aggregate)
+            return unless name
+
+            parts = composite ? %w[batch sequence] : ["sequence"]
+            types = entity_value_objects(aggregate, name, composite)
+            list  = "#{name.downcase}s"
+
+            aggregate["attributes"] << entity_list_attribute(aggregate["name"], name, list)
+            aggregate["entities"] << entity_piece(aggregate["name"], name, parts, types, lifecycle)
+            add_entity_command(aggregate, name, list, parts, types)
+          end
+
+          def next_entity_name(aggregate)
+            (ENTITY_NAMES - aggregate["entities"].map { |entity| entity["name"] }).first
+          end
+
+          def entity_list_attribute(owner, name, list)
+            { "name" => list, "type" => name, "list" => true, "requires" => ["entity:#{owner}.#{name}"] }
+          end
+
+          def add_entity_command(aggregate, name, list, parts, types)
+            owner = aggregate["name"]
+            command(aggregate, "Add#{name}",
+                    args:  parts.map { |part| { "name" => part, "type" => types[part] } },
+                    sets:  [{ "target" => list, "append" => parts.to_h { |part| [part, part] },
+                              "requires" => ["attribute:#{owner}.#{list}", "entity:#{owner}.#{name}"] }],
+                    emits: ["#{owner}#{name}Added"])
+          end
+
+          # Declares the value objects an entity's attributes use; answers part name => type name.
+          def entity_value_objects(aggregate, name, composite)
+            vo(aggregate, "#{name}Sequence", "positive")
+            vo(aggregate, "#{name}Batch", "string") if composite
+            vo(aggregate, "#{name}Label", "string")
+            { "sequence" => "#{name}Sequence", "batch" => "#{name}Batch" }
+          end
+
+          # Qualified by the owner, not just the entity name: `ENTITY_NAMES`
+          # is shared across aggregates, so two could otherwise both emit a
+          # bare "LineAdded" with different shapes.
+          def entity_piece(owner, name, parts, types, lifecycle)
+            piece = { "name" => name, "identity" => parts, "requires" => [],
+                      "attributes" => parts.map { |part| { "name" => part, "type" => types[part] } } +
+                                      [{ "name" => "label", "type" => "#{name}Label", "optional" => true }],
+                      "lifecycle" => nil,
+                      "commands" => [{ "name" => "Label", "creates" => false, "references" => [],
+                                       "args" => [{ "name" => "label", "type" => "#{name}Label" }], "givens" => [],
+                                       "sets" => [{ "target" => "label" }], "emits" => ["#{owner}#{name}Labeled"] }] }
+            settle(piece, owner, name) if lifecycle || chance?(0.2)
+            piece
+          end
+
+          # Gives an entity a `Settle` command and the lifecycle it drives.
+          def settle(piece, owner, name)
+            piece["commands"] << { "name" => "Settle", "creates" => false, "references" => [], "args" => [], "givens" => [],
+                                   "sets" => [], "emits" => ["#{owner}#{name}Settled"] }
+            piece["lifecycle"] = { "field" => "state", "default" => "pending",
+                                   "transitions" => [{ "command" => "Settle", "to" => "settled", "from" => ["pending"],
+                                                       "requires" => ["command:#{owner}.#{name}.Settle"] }] }
+          end
+        end
+      end
+    end
+  end
+end