hecks 3.0.4 → 3.1.0

data/lib/hecks/cli/domain_stub.rb

@@ -0,0 +1,128 @@
+require_relative "../naming"
+
+module Hecks
+  module CLI
+    # The files `hecks init` writes: a stub domain that boots as it stands and that the author
+    # then edits into a real one (ADR 0087).
+    #
+    # Pure: it answers the text of each file and writes none, so the adapter that does the writing
+    # can check every target before it writes the first, and a spec can boot the result.
+    module DomainStub
+      # A domain's name: a capital, then letters and digits, as its bluebook spells it.
+      NAME = /\A[A-Z][A-Za-z0-9]*\z/
+
+      SQLITE_URL = 'default_database "data/%<snake>s.db"'.freeze
+      POSTGRES_URL = 'default_database "postgres://localhost/%<snake>s"'.freeze
+      private_constant :SQLITE_URL, :POSTGRES_URL
+
+      # Persistence adapters a stub can be bound to, each with the world lines that bind it, the
+      # data it keeps under `data/` (so a `.gitignore` is written), and whether it needs a server
+      # (so a memory overlay is written and the first run needs no database).
+      ADAPTERS = {
+        "Memory"            => { world: ['default_adapter "Memory"'], local_data: false, server: false },
+        "SqlitePersistence" => { world: ['default_adapter "SqlitePersistence"', SQLITE_URL],
+                                 local_data: true, server: false },
+        "Heki"              => { world: ['default_adapter "Heki"', 'persisted_by("Heki") { dir "data" }'],
+                    local_data: true, server: false },
+        "Postgres"          => { world: ['default_adapter "Postgres"', POSTGRES_URL],
+                        local_data: false, server: true },
+        "PostgresEra"       => { world: ['default_adapter "PostgresEra"', POSTGRES_URL],
+                           local_data: false, server: true }
+      }.freeze
+
+      # What `init` binds a stub to when no adapter is named: it needs no server and keeps its data.
+      DEFAULT_ADAPTER = "SqlitePersistence".freeze
+
+      module_function
+
+      # @return [Array<String>] the adapter names `init` accepts
+      def adapters = ADAPTERS.keys
+
+      # @param name [String] the domain's name, as its bluebook spells it (`Lending`)
+      # @param adapter [String, nil] an adapter named in `ADAPTERS`; the default when nil
+      # @return [Hash{String => String}] each file's path under the domain directory, and its text
+      # @raise [ArgumentError] when the name is not a capitalised word or the adapter is unknown
+      def files(name:, adapter: nil)
+        adapter ||= DEFAULT_ADAPTER
+        check!(name, adapter)
+        { "bluebook/#{Naming.snake(name)}.bluebook" => bluebook(name) }.merge(support_files(name: name, adapter: adapter))
+      end
+
+      # The files around a domain's bluebook: its world bound to the adapter, the memory overlay for
+      # an adapter that needs a server, and a `.gitignore` for one that keeps data. `hecks init`
+      # writes them beside a stub, and an interview draft beside the bluebook it renders (ADR 0088).
+      #
+      # @param name [String] the domain's name
+      # @param adapter [String, nil] an adapter named in `ADAPTERS`; the default when nil
+      # @return [Hash{String => String}] each file's path under the domain directory, and its text
+      # @raise [ArgumentError] when the name is not a capitalised word or the adapter is unknown
+      def support_files(name:, adapter: nil)
+        adapter ||= DEFAULT_ADAPTER
+        check!(name, adapter)
+        snake = Naming.snake(name)
+        files = { "bluebook/#{snake}.world" => world(name, snake, adapter) }
+        files["bluebook/environments/memory.world"] = overlay(name) if ADAPTERS.fetch(adapter).fetch(:server)
+        files[".gitignore"] = "data/\n" if ADAPTERS.fetch(adapter).fetch(:local_data)
+        files
+      end
+
+      # @param name [String] a domain name
+      # @return [String] the directory `init` writes into when none is named
+      def directory(name) = Naming.snake(name)
+
+      # @api private
+      def check!(name, adapter)
+        unless name.to_s.match?(NAME)
+          raise ArgumentError, "#{name.inspect} is not a domain name: a capital, then letters and digits (Lending)"
+        end
+        return if ADAPTERS.key?(adapter)
+
+        raise ArgumentError, "unknown adapter #{adapter.inspect}; choose one of #{adapters.join(', ')}"
+      end
+
+      # @api private
+      def bluebook(name)
+        <<~BLUEBOOK
+          Hecks.bluebook "#{name}" do
+            vision "TODO: say in one sentence what #{name} is for."
+            supporting
+
+            # TODO: rename Example to the main thing #{name} keeps track of.
+            aggregate "Example" do
+              description "TODO: describe what an Example is."
+
+              identified_by :name
+
+              attribute :name, ExampleName
+
+              value_object "ExampleName" do
+                attribute :value, String, pattern: '[^ \\t\\n\\r]'
+              end
+
+              # TODO: replace Create with the first thing that happens to an Example.
+              command "Create" do
+                goal "TODO: say what Create does"
+
+                attribute :name, ExampleName
+
+                emits "ExampleCreated"
+              end
+            end
+          end
+        BLUEBOOK
+      end
+
+      # @api private
+      def world(name, snake, adapter)
+        lines = ADAPTERS.fetch(adapter).fetch(:world).map { |line| "  #{format(line, snake: snake)}" }
+        note = adapter == "PostgresEra" ? "  # PostgresEra refuses a superuser role; use an ordinary one in the URL.\n" : ""
+        "Hecks.world \"#{name}\" do\n  realm \"#{name}\"\n#{note}#{lines.join("\n")}\nend\n"
+      end
+
+      # @api private
+      def overlay(name)
+        "Hecks.world \"#{name}\" do\n  default_adapter \"Memory\"\nend\n"
+      end
+    end
+  end
+end

data/lib/hecks/cli/interview_draft.rb

@@ -0,0 +1,246 @@
+require_relative "../naming"
+require_relative "domain_stub"
+
+module Hecks
+  module CLI
+    # Turns an interview's accepted findings into the files of a first domain (ADR 0088).
+    #
+    # Pure: it answers the text of each file and writes none, so the command that runs an interview
+    # can check every target before it writes the first, and a spec can boot the result. It shares
+    # the files around a bluebook with `hecks init` (`DomainStub.support_files`) and renders the
+    # bluebook itself, from what the developer accepted, where `init` writes a fixed stub.
+    #
+    # Only `accepted` findings reach the bluebook; every finding reaches the record. A rule is never
+    # turned into code from prose: it is a comment citing its source, to become a `given` by hand.
+    module InterviewDraft
+      ACCEPTED = "accepted".freeze
+
+      # The pattern every generated string field carries: it refuses a blank value.
+      PATTERN = %q('[^ \t\n\r]').freeze
+
+      # What stands in for a creating command nothing in the interview named.
+      STUB_NOTE = "    # TODO: no action that creates was accepted; replace Create with the real one.".freeze
+      private_constant :PATTERN, :STUB_NOTE
+
+      module_function
+
+      # The files a first interview writes: the bluebook, the files around it, and the record.
+      #
+      # @param interview [Hash] the interview, with at least one accepted thing
+      # @param adapter [String, nil] an adapter in `DomainStub::ADAPTERS`; its default when nil
+      # @return [Hash{String => String}] each file's path under the domain directory, and its text
+      # @raise [ArgumentError] when nothing was accepted, or the subject or adapter is refused
+      def files(interview, adapter: nil)
+        name = interview.fetch(:subject)
+        support = DomainStub.support_files(name: name, adapter: adapter)
+        { "bluebook/#{Naming.snake(name)}.bluebook" => bluebook(interview) }
+          .merge(support)
+          .merge(record_file(interview))
+      end
+
+      # What a later interview writes: its record, ending in the aggregates and commands it would
+      # add, for a developer to merge. An existing domain is never touched (ADR 0088).
+      #
+      # @param interview [Hash] the interview
+      # @return [Hash{String => String}] the one file, `interviews/<reference>.md`
+      def additions(interview)
+        record_file(interview, "\n## Proposed additions\n\nMerge by hand into the domain's bluebook.\n\n" \
+                               "```ruby\n#{fragment(interview)}```\n")
+      end
+
+      # The interview's record: every exchange in order, and every finding with how it was decided.
+      #
+      # @param interview [Hash] the interview
+      # @return [String] Markdown
+      def record(interview)
+        lines = ["# Interview #{interview.fetch(:reference)}: #{interview.fetch(:subject)}", "",
+                 "Expert: #{interview.fetch(:expert)}", "", "## Exchanges", ""]
+        interview.fetch(:exchanges).each_with_index { |ex, i| lines.concat(exchange_lines(ex, i + 1)) }
+        lines << "" << "## Findings" << ""
+        lines.concat(finding_lines(interview))
+        "#{lines.join("\n")}\n"
+      end
+
+      # Reads the plain interview out of an `Interview` record booted from the SME chapter.
+      #
+      # @param interview [Object] the booted record
+      # @return [Hash] the plain interview this module takes: `reference`, `subject`, `expert`,
+      #   `exchanges` (`question`, `answer`, `topic`), and `things`, `actions` and `rules`, each a
+      #   finding with its `number`, `source` and `status` and the fields of its kind
+      def from_record(interview)
+        { reference: plain(interview.reference), subject: plain(interview.subject), expert: plain(interview.expert),
+          exchanges: interview.exchanges.map { |ex| slice(ex, :question, :answer, :topic) },
+          things:    interview.thing_findings.map { |f| slice(f, :number, :name, :identifier, :source, :status) },
+          actions:   interview.action_findings.map { |f| slice(f, :number, :name, :thing, :event, :creates, :source, :status) },
+          rules:     interview.rule_findings.map { |f| slice(f, :number, :statement, :source, :status) } }
+      end
+
+      # @api private
+      def record_file(interview, tail = "")
+        { "interviews/#{file_stem(interview.fetch(:reference))}.md" => record(interview) + tail }
+      end
+
+      # @api private
+      def file_stem(reference) = reference.to_s.gsub(/[^A-Za-z0-9._-]/, "_")
+
+      # @api private
+      def bluebook(interview)
+        name = interview.fetch(:subject)
+        things = accepted(interview, :things)
+        raise ArgumentError, "nothing was accepted: a draft needs at least one thing" if things.empty?
+
+        out = ["Hecks.bluebook #{name.inspect} do"]
+        out.concat(header(interview))
+        out << %(  vision "TODO: say in one sentence what #{name} is for.")
+        out << "  supporting" << ""
+        out.concat(rule_lines(interview))
+        out << fragment(interview).chomp << "end"
+        "#{out.join("\n")}\n"
+      end
+
+      # The aggregates, with their commands: the part a later interview offers to merge.
+      # @api private
+      def fragment(interview)
+        things = accepted(interview, :things)
+        actions = accepted(interview, :actions)
+        placed = things.map { |t| word(t[:name]) }
+        blocks = things.map { |thing| aggregate(interview, thing, actions) }
+        loose = actions.reject { |a| placed.include?(word(a[:thing])) }
+        blocks << unplaced(interview, loose) unless loose.empty?
+        "#{blocks.join("\n\n")}\n"
+      end
+
+      # @api private
+      def header(interview)
+        ["  # Drafted from interview #{interview[:reference]} with #{interview[:expert]}. Each name below cites the",
+         "  # exchange it came from; edit freely."]
+      end
+
+      # @api private
+      def rule_lines(interview)
+        rules = accepted(interview, :rules)
+        return [] if rules.empty?
+
+        ["  # RULES the expert gave, for you to turn into `given` clauses:"] +
+          rules.map { |r| "  #   - #{cite(interview, r)} #{one_line(r[:statement])}" } + [""]
+      end
+
+      # @api private
+      def aggregate(interview, thing, actions)
+        name = word(thing[:name])
+        field = Naming.snake(word(thing[:identifier]))
+        field_type = identifier_type(name, field)
+        mine = actions.select { |a| word(a[:thing]) == name }
+        creating = mine.select { |a| a[:creates] }
+        rest = mine - creating
+        lines = ["  # #{source_note(interview, thing)}".rstrip,
+                 "  aggregate #{name.inspect} do",
+                 "    description #{"TODO: describe what a #{name} is.".inspect}", "",
+                 "    identified_by :#{field}", "",
+                 "    attribute :#{field}, #{field_type}", "",
+                 "    value_object #{field_type.inspect} do",
+                 "      attribute :value, String, pattern: #{PATTERN}",
+                 "    end"]
+        creating = [stub_create(name)] if creating.empty?
+        creating.each { |action| lines.concat(creating_command(interview, action, field, field_type)) }
+        rest.each { |action| lines.concat(mutating_command(interview, action, name)) }
+        (lines << "  end").join("\n")
+      end
+
+      # The creating command nothing in the interview named: a stub, marked for the developer.
+      # @api private
+      def stub_create(name) = { name: "Create", event: "#{name}Created", stub: true }
+
+      # @api private
+      def creating_command(interview, action, field, field_type)
+        verb = word(action[:name])
+        note = action[:stub] ? STUB_NOTE : "    # #{source_note(interview, action)}"
+        ["", note, "    command #{verb.inspect} do", "      goal #{"TODO: say what #{verb} does".inspect}", "",
+         "      attribute :#{field}, #{field_type}", "", "      emits #{word(action[:event]).inspect}", "    end"]
+      end
+
+      # @api private
+      def mutating_command(interview, action, name)
+        verb = word(action[:name])
+        ["", "    # #{source_note(interview, action)}", "    command #{verb.inspect} do",
+         "      goal #{"TODO: say what #{verb} does".inspect}", "", "      reference_to #{name}", "",
+         "      emits #{word(action[:event]).inspect}", "    end"]
+      end
+
+      # An action whose thing nobody accepted has nowhere to go; it is kept as a comment, not lost.
+      # @api private
+      def unplaced(interview, actions)
+        lines = ["  # UNPLACED: these accepted actions name a thing that was not accepted. Place each, or drop it."]
+        actions.each do |action|
+          lines << "  #   - #{cite(interview, action)} #{word(action[:name])} on #{action[:thing]}, announcing #{action[:event]}"
+        end
+        lines.join("\n")
+      end
+
+      # @api private
+      def identifier_type(name, field)
+        type = Naming.pascal(field)
+        type == name ? "#{type}Id" : type
+      end
+
+      # @api private
+      def exchange_lines(exchange, number)
+        lines = ["#{number}. **Q:** #{one_line(exchange[:question])}", "   **A:** #{one_line(exchange[:answer])}"]
+        topic = exchange[:topic].to_s
+        lines << "   _Topic: #{one_line(topic)}_" unless topic.empty?
+        lines
+      end
+
+      # @api private
+      def finding_lines(interview)
+        lines = interview.fetch(:things).map do |f|
+          "- Thing #{f[:number]}, #{f[:status]}: **#{f[:name]}**, identified by `#{f[:identifier]}` (exchange #{f[:source]})"
+        end
+        lines += interview.fetch(:actions).map do |f|
+          creates = f[:creates] ? ", creates it" : ""
+          "- Action #{f[:number]}, #{f[:status]}: **#{f[:name]}** on #{f[:thing]}, " \
+            "announcing `#{f[:event]}`#{creates} (exchange #{f[:source]})"
+        end
+        lines + interview.fetch(:rules).map do |f|
+          "- Rule #{f[:number]}, #{f[:status]}: #{one_line(f[:statement])} (exchange #{f[:source]})"
+        end
+      end
+
+      # @api private
+      def accepted(interview, kind) = interview.fetch(kind).select { |finding| finding[:status] == ACCEPTED }
+
+      # A free-text name as a PascalCase word safe to write into Ruby: `lend a book` is `LendABook`.
+      # @api private
+      def word(text) = text.to_s.split(/[^A-Za-z0-9]+/).reject(&:empty?).map { |part| part.sub(/\A./, &:upcase) }.join
+
+      # @api private
+      def one_line(text) = text.to_s.gsub(/\s+/, " ").strip
+
+      # @api private
+      def cite(interview, finding) = "#{interview[:reference]} ##{finding[:source]}:"
+
+      # Where a name came from: the interview, the exchange, and a short quotation of the answer.
+      # @api private
+      def source_note(interview, finding)
+        exchange = interview.fetch(:exchanges)[finding[:source].to_i - 1]
+        note = "from #{cite(interview, finding)}"
+        return note unless exchange
+
+        text = one_line(exchange[:answer])
+        text = "#{text[0, 77]}..." if text.length > 80
+        "#{note} #{text.inspect}"
+      end
+
+      # @api private
+      def plain(value)
+        return nil if value.nil?
+
+        found = value.respond_to?(:to_h) && !value.is_a?(String) ? value.to_h : value
+        found.is_a?(Hash) && found.key?(:value) ? found[:value] : found
+      end
+
+      # @api private
+      def slice(record, *keys) = keys.to_h { |key| [key, plain(record[key])] }
+    end
+  end
+end

data/lib/hecks/cli/model_check.rb

@@ -88,7 +88,7 @@ module Hecks
       end
 
       # `root:` is the source's parent, so a member declaring
-      # `uses_embryonaut_bluebook` can vendor from it.
+      # `attaches ... from: :vendor` can vendor from it.
       def boot(source)
         root = File.directory?(source) ? File.dirname(source) : nil
         registry = Runtime::Registry.new(root: root)

data/lib/hecks/cli/project_cli.rb

@@ -17,7 +17,7 @@ module Hecks
       # Build output and other trees under a root that hold no domain a caller means.
       IGNORED = %r{\A(rust|deploy|tmp|coverage)/}
 
-      # What a chapter name, a domain path and a launcher verb may be made of.
+      # What a chapter name, a domain path and a launcher command may be made of.
       NAME = /\A[A-Za-z][A-Za-z0-9_ ]*\z/
       PATH = %r{\A[\w./-]+\z}
       VERB = /\A[A-Za-z_][A-Za-z0-9_]*\z/
@@ -40,9 +40,28 @@ module Hecks
         status.zero? ? puts(text) : abort(text)
       LAUNCHER_TAIL
 
+      # What a Memory command does when refused: say why, from the record's `refusal`.
+      MEMORY_REFUSAL = <<~'LAUNCHER_REFUSAL'.gsub(/^/, "  ").freeze
+        if MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))
+          why = begin
+            require "json"
+            JSON.parse(text).dig("state", "refusal", "value")
+          rescue JSON::ParserError
+            nil
+          end
+          warn(why ? why.sub(/\A(\w+::)+\w+: /, "") : reason)
+        else
+          puts text
+          warn reason
+        end
+      LAUNCHER_REFUSAL
+
       # The generator's name as an executable launcher's header states it, whoever ran it.
       GENERATOR = "hecks project_cli".freeze
 
+      # The launcher's test for a Memory command; a trailing `!` is not part of the name.
+      RUNS_ON_MEMORY = 'MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))'.freeze
+
       module_function
 
       # Writes a launcher for each named domain, or for every domain under `root`.
@@ -103,7 +122,7 @@ module Hecks
         label      = executable || "#{path}/#{snake}"
         file       = File.join(root, label)
         text       = launcher(path, name, program, executable: executable, legacy: setting[:legacy],
-                          opted: !setting.empty?)
+                          memory_commands: setting[:memory_commands], opted: !setting.empty?)
         return skip(path, "#{label} is a directory") if File.directory?(file)
 
         return :drifted if check && !(File.file?(file) && File.read(file) == text)
@@ -149,11 +168,12 @@ module Hecks
       # @param program [String] the generator's invocation, named in the header
       # @param executable [String, nil] the file's path under the root when it is not beside the
       #   domain; its program name is then that file's basename, and its header names the generator
-      # @param legacy [Array<String>, nil] verbs an executable hands to `Hecks::CLI` first
+      # @param legacy [Array<String>, nil] commands an executable hands to `Hecks::CLI` first
+      # @param memory_commands [Array<String>, nil] commands that default to Memory
       # @param opted [Boolean] whether the chapter's world declares a `launcher` setting
       # @return [String] the Ruby source
-      # @raise [ArgumentError] if a name, path, executable or legacy verb is not plain
-      def launcher(path, name, program, executable: nil, legacy: nil, opted: !executable.nil?)
+      # @raise [ArgumentError] if a name, path, executable or legacy command is not plain
+      def launcher(path, name, program, executable: nil, legacy: nil, memory_commands: nil, opted: !executable.nil?)
         plain!("chapter name", name, NAME)
         plain!("domain path", path, PATH)
         snake = Naming.snake(name)
@@ -174,45 +194,48 @@ module Hecks
           where = shown = "#{path}/#{snake}"
         end
 
-        handoff  = legacy_handoff(Array(legacy)) if executable
+        handoff  = legacy_handoff(Array(legacy)) + memory_default(Array(memory_commands)) if executable
         encoding = opted ? ENCODING : ""
         ending   = opted ? OPTED_ENDING : PLAIN_ENDING
+        ending   = quiet_ending(ending) if executable && !Array(memory_commands).empty?
 
         <<~RUBY
           #!/usr/bin/env ruby
 
           # #{name}'s command line — GENERATED by #{program}. Do not edit.
           #
-          # A launcher, not a CLI: the verbs, their arguments and their refusals are
+          # A launcher, not a CLI: the commands, their arguments and their refusals are
           # projected from the bluebook beside it every time this runs, so a change
           # to the chapter shows up here without re-minting anything.
           #
-          #   #{where}                  every verb, and every question
-          #   #{where} <verb> --help    what it wants, and how it refuses
+          #   #{where}                  every command, and every question
+          #   #{where} <command> --help    what it wants, and how it refuses
 
           #{encoding}$LOAD_PATH.unshift File.expand_path("#{up}lib", __dir__)
           #{handoff}
           require "hecks"
 
-          #{entry(name, boot, shown, opted)}
+          #{entry(name, boot, shown, opted, quiet: !Array(memory_commands).empty?)}
           #{ending}
         RUBY
       end
 
       # @api private
       # @return [String] the launcher's middle: for an opted-in launcher, usage answered from the
-      #   projection and a boot only for a line that runs a verb; for any other, the boot and
+      #   projection and a boot only for a line that runs a command; for any other, the boot and
       #   dispatch every launcher has always had, byte for byte
-      def entry(name, boot, shown, opted)
-        opted ? described_entry(name, boot, shown) : plain_entry(name, boot, shown)
+      def entry(name, boot, shown, opted, quiet: false)
+        opted ? described_entry(name, boot, shown, quiet: quiet) : plain_entry(name, boot, shown)
       end
 
       # @api private
       # @return [String] the opted-in launcher's middle
-      def described_entry(name, boot, shown)
+      def described_entry(name, boot, shown, quiet: false)
+        started = "Hecks.boot_described(described, install_doors: false)"
+        started = "Hecks::Doors::LauncherOptions.quietly(hold: #{RUNS_ON_MEMORY}) { #{started} }" if quiet
         <<~RUBY.chomp
           # Usage is answered from the projected chapter alone: no adapter is bound and no
-          # database is opened. Only a line that runs a verb boots the domain,
+          # database is opened. Only a line that runs a command boots the domain,
           # and it boots from what the usage check already loaded.
           domain = #{boot}
           program = "#{shown}"
@@ -227,7 +250,7 @@ module Hecks
           )
           unless text
             runtime = begin
-              Hecks.boot_described(described, install_doors: false)
+              #{started}
             rescue StandardError => e
               abort "cannot open #{name}: \#{e.message.lines.first.strip}"
             end
@@ -265,11 +288,39 @@ module Hecks
       end
 
       # @api private
-      # @return [String] the lines that hand the legacy verbs to `Hecks::CLI`, or nothing
+      # @param ending [String] the launcher's closing lines
+      # @return [String] the same lines, except that a memory command prints no settled record, only
+      #   the reason it was refused: a person is at it, so the record is noise
+      def quiet_ending(ending)
+        ending.sub("  puts text\n  warn reason\n", MEMORY_REFUSAL)
+              .sub("status.zero? ? puts(text)",
+                   "exit 0 if status.zero? && MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp(\"!\"))\nstatus.zero? ? puts(text)")
+      end
+
+      # @api private
+      # @return [String] the lines that default the listed commands to Memory, or nothing
+      def memory_default(commands)
+        return "" if commands.empty?
+
+        commands.each { |command| plain!("memory command", command, VERB) }
+
+        <<~RUBY
+
+          # These commands keep nothing worth a database, so they run on Memory unless told otherwise.
+          # A person is at them: they wait for their result, say why when they are refused, and print
+          # no record when they end well.
+          MEMORY_COMMANDS = %w[#{commands.join(' ')}].freeze
+          ENV["HECKS_ENVIRONMENT"] ||= "memory" if MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))
+          ARGV << "--wait" if MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!")) && !ARGV.include?("--wait")
+        RUBY
+      end
+
+      # @api private
+      # @return [String] the lines that hand the legacy commands to `Hecks::CLI`, or nothing
       def legacy_handoff(legacy)
         return "" if legacy.empty?
 
-        legacy.each { |verb| plain!("legacy verb", verb, VERB) }
+        legacy.each { |command| plain!("legacy command", command, VERB) }
 
         <<~RUBY
 

data/lib/hecks/cli/reference.rb

@@ -5,7 +5,8 @@ require_relative "../projection_files"
 
 module Hecks
   module CLI
-    # The command behind `hecks project_reference`: regenerates `docs/implemented/reference/` from
+    # The command behind `hecks language_run.project_reference`: regenerates
+    # `docs/implemented/reference/` from
     # the language's Syntax chapter. Tables come from the declaration; prose is kept from the
     # committed pages.
     module Reference

data/lib/hecks/cli/refresh_rspec_runtime_baseline.rb

@@ -39,7 +39,7 @@ module Hecks
         if argv.first == "--from-run"
           from_run(root, argv.fetch(1) { abort USAGE }, out)
         else
-          from_local(root, argv.fetch(0, "6"), out)
+          from_local(root, argv.fetch(0) { abort USAGE }, out)
         end
         0
       end

data/lib/hecks/cli/seed_semantics_corpus.rb

@@ -6,18 +6,30 @@ require_relative "../fuzzing"
 
 module Hecks
   module CLI
-    # The command behind `hecks seed_semantics_corpus`: seeds (or deliberately re-seeds) the
-    # `expect` block of semantics-corpus fixtures from the Ruby runtime. Review the result
+    # The command behind `hecks test_suite_run.seed_semantics_corpus`: seeds (or re-seeds) the
+    # `expect` block of corpus fixtures from the Ruby runtime. Review the result
     # against `docs/semantics/bluebook-semantics.md` before committing.
     #
-    #   hecks seed_semantics_corpus                                # fill fixtures missing an expect
-    #   SEED=refusal_kind_lifecycle hecks seed_semantics_corpus    # re-seed one, deliberately
+    # Seeds `spec/corpus/semantics/` and the conformance corpus ({FULL_SCRIPTS} plus
+    # `spec/corpus/rust_conformance/`, whose `expect` also freezes more).
+    #
+    #   hecks test_suite_run.seed_semantics_corpus   # fill what lacks an expect
+    #   SEED=refusal_kind_lifecycle hecks test_suite_run.seed_semantics_corpus   # re-seed one
     #
     # The seeded expectation is the definition, not a recording: both runtimes are compared to it.
     # `occurred_at` is stripped from events (C7.3/C9.1); refusals keep verb, error and kind (C8.2).
     module SeedSemanticsCorpus
       module_function
 
+      # Full corpus scripts held to the conformance bar, keyed by file, valued by domain.
+      FULL_SCRIPTS = {
+        "spec/corpus/banking.json" => "examples/banking",
+        "spec/corpus/chess.json"   => "examples/chess"
+      }.freeze
+
+      # The `expect` keys a conformance fixture freezes beyond the semantics three.
+      CONFORMANCE_KEYS = %w[queries sagas dry_runs reactions].freeze
+
       # Seeds the fixtures that need it and reports which.
       #
       # @param root [String] the checkout whose `spec/corpus/semantics/` is seeded
@@ -26,12 +38,13 @@ module Hecks
       # @return [Integer] the exit status, always 0
       def call(root:, env: ENV, out: $stdout)
         only = env.fetch("SEED", nil)
-        seeded = Dir.glob(File.join(root, "spec/corpus/semantics", "*.json")).filter_map do |path|
+        seeded = corpus_paths(root).filter_map do |path, domain, full|
           fixture = JSON.parse(File.read(path))
           name = File.basename(path, ".json")
           next if only ? only != name : fixture.key?("expect")
 
-          fixture["expect"] = expectation_for(root, fixture)
+          fixture["domain"] ||= domain if domain
+          fixture["expect"] = expectation_for(root, fixture, full: full)
           File.write(path, "#{JSON.pretty_generate(fixture)}\n")
           name
         end
@@ -39,19 +52,35 @@ module Hecks
         0
       end
 
+      # @param root [String] the checkout
+      # @return [Array<Array>] `[path, domain_to_add_or_nil, full_expect?]` for every seedable file
+      def corpus_paths(root)
+        semantics = Dir.glob(File.join(root, "spec/corpus/semantics", "*.json")).map { |p| [p, nil, false] }
+        conformance = Dir.glob(File.join(root, "spec/corpus/rust_conformance", "*.json")).map { |p| [p, nil, true] }
+        scripts = FULL_SCRIPTS.map { |file, domain| [File.join(root, file), domain, true] }
+        semantics + conformance + scripts
+      end
+
       # Replays the fixture's script against the Ruby runtime. Each refusal's `"kind"` is reduced
       # to its class name; `occurred_at` is stripped from events.
       #
       # @param root [String] the checkout the fixture's domain path is relative to
       # @param fixture [Hash] the parsed fixture: `domain` and `steps`
-      # @return [Hash{String => Array}] its `"expect"` block: refusals, instances, events
-      def expectation_for(root, fixture)
+      # @param full [Boolean] also freeze queries, sagas, dry runs, reactions (conformance)
+      # @return [Hash{String => Array}] its `"expect"` block: refusals, instances, events, and
+      #   with `full` the {CONFORMANCE_KEYS}
+      def expectation_for(root, fixture, full: false)
         result = Hecks::Fuzzing::Replay.call(File.join(root, fixture["domain"]), fixture["steps"])
-        {
+        expect = {
           "refusals"  => JSON.parse(JSON.generate(result[:refusals])).each { |r| r["kind"] = r["kind"]&.split("::")&.last },
           "instances" => JSON.parse(JSON.generate(result[:instances])),
           "events"    => JSON.parse(JSON.generate(result[:events])).each { |e| e.delete("occurred_at") }
         }
+        return expect unless full
+
+        # instances_at is Replay's per-query snapshot for the property harness, not an outcome.
+        expect["queries"] = JSON.parse(JSON.generate(result[:queries].map { |q| q.except(:instances_at) }))
+        expect.merge!(CONFORMANCE_KEYS.drop(1).to_h { |k| [k, JSON.parse(JSON.generate(result[k.to_sym]))] })
       end
 
       # @param out [IO] where the report goes