hecks 3.1.1 → 3.1.3

data/lib/hecks/projector/cli_projector.rb

@@ -403,41 +403,70 @@ module Hecks
         out = ["#{bluebook.name} — #{bluebook.vision}", "",
                "  #{program} <command>! [name=value …]       do something",
                "  #{program} query <query> [name=value …]    read something", ""]
-
-        out << "commands:"
-        out.concat(listing(commands) { |spec| spec[:summary] })
-        out << ""
-        out << "queries (nothing here changes anything):"
-        out.concat(listing(questions) { |spec| first_sentence(spec[:summary]) })
+        out.concat(tables(commands, questions, all: options[:all], notes: aggregate_notes(bluebook)))
         out << ""
         out << "  #{program} <command> --help       what one command wants, and every way it refuses"
+        out.concat(all_hint(program, commands, questions)) unless options[:all]
         out << "  a command is called with its aggregate — #{example_qualified(commands)}"
         out.join("\n")
       end
 
+      # The commands table then the queries table.
+      def tables(commands, questions, all:, notes:)
+        ["commands:", *listing(commands, all: all, notes: notes) { |spec| spec[:summary] }, "",
+         "queries (nothing here changes anything):",
+         *listing(questions, all: all, notes: notes) { |spec| first_sentence(spec[:summary]) }]
+      end
+
+      # The line saying the internal commands and queries were left out and how to list them,
+      # or no line when there are none.
+      def all_hint(program, commands, questions)
+        hidden = (commands.values + questions.values).count { |spec| spec[:internal] }
+        return [] if hidden.zero?
+
+        ["  #{program} --all                  also list the #{hidden} internal commands and queries"]
+      end
+
       # The command or question lines of the help. A domain with more than one aggregate is listed
       # under a heading per aggregate, so related commands sit together; the heading is the prefix
       # every call to them carries, so the lines under it leave it out. The bookkeeping a run
-      # records about itself (`internal`: system-role commands and port operations) is set apart as
-      # names only, since a person never types them. A single-aggregate domain keeps the plain
-      # list, each name in full.
-      def listing(specs)
+      # records about itself (`internal`: system-role commands and port operations) is left out,
+      # since a person never types them; `all` lists them as names only. A single-aggregate
+      # domain keeps the plain list, each name in full.
+      #
+      # @param notes [Hash{String => String}] a line of prose per aggregate, shown under its heading
+      def listing(specs, all: false, notes: {}, &description)
         shown, internal = specs.values.partition { |spec| !spec[:internal] }
-        groups = shown.group_by { |spec| spec[:group] }
-        grouped = groups.length > 1
+        grouped = shown.map { |spec| spec[:group] }.uniq.length > 1
         named = shown.to_h { |spec| [spec, entry_name(spec, grouped)] }
+        lines = listed_rows(shown, named, grouped, notes, &description)
+        lines.concat(internal_lines(internal)) if all && !internal.empty?
+        lines
+      end
+
+      # The rows of one table: one line per spec, under a heading per aggregate when grouped.
+      def listed_rows(shown, named, grouped, notes, &description)
         width = named.values.map(&:length).max.to_i
-        lines = []
-        if grouped
-          groups.each do |group, members|
-            lines << "  #{heading(group)}" if group
-            members.each { |spec| lines << "    #{named[spec].ljust(width)}  #{yield(spec)}#{alias_note(spec)}" }
-          end
-        else
-          shown.each { |spec| lines << "  #{named[spec].ljust(width)}  #{yield(spec)}#{alias_note(spec)}" }
+        row = ->(spec, indent) { "#{indent}#{named[spec].ljust(width)}  #{description.call(spec)}#{alias_note(spec)}" }
+        return shown.map { |spec| row.call(spec, "  ") } unless grouped
+
+        shown.group_by { |spec| spec[:group] }.flat_map do |group, members|
+          [*heading_lines(group, notes), *members.map { |spec| row.call(spec, "    ") }]
         end
-        lines.concat(internal_lines(internal)) unless internal.empty?
-        lines
+      end
+
+      # The lines that open an aggregate's group: its heading, then its note when it has one.
+      def heading_lines(group, notes)
+        return [] unless group
+
+        ["  #{heading(group)}", *notes[group]&.then { |note| "    #{note}" }]
+      end
+
+      # The first sentence of each aggregate's description, keyed by aggregate name; an aggregate
+      # with no description has no entry.
+      def aggregate_notes(bluebook)
+        bluebook.aggregates.to_h { |aggregate| [aggregate.hecks_name, first_sentence(aggregate.description)] }
+                .reject { |_, note| note.empty? }
       end
 
       # The aggregate's own name as a heading: the prefix of every call to the lines under it.

data/lib/hecks/quality_control/adapters/agent.rb

@@ -2,6 +2,7 @@
 
 require "open3"
 require "shellwords"
+require_relative "agent_profile"
 
 module Hecks
   module Adapters
@@ -27,10 +28,11 @@ module Hecks
       # The command an ask runs.
       #
       # @param command [String, Array<String>, nil] a command line, or its words
-      # @return [Array<String>] `command` as words; `QA_MINER_AGENT` else `DEFAULT_COMMAND` when nil
-      def command_for(command = nil)
+      # @param profile [AgentProfile, nil] when given, the default command takes its tools, budget
+      # @return [Array<String>] `command` as words; `QA_MINER_AGENT` else the default when nil
+      def command_for(command = nil, profile = nil)
         command ||= ENV.fetch("QA_MINER_AGENT", nil)
-        return DEFAULT_COMMAND unless command
+        return default_command(profile) unless command
 
         command.is_a?(String) ? Shellwords.split(command) : command
       end
@@ -41,11 +43,13 @@ module Hecks
       # @param command [String, Array<String>, nil] the agent's command; see `command_for`
       # @param chdir [String] the directory the agent works in
       # @param log [String, nil] a file the agent's output is appended to
+      # @param profile [AgentProfile, nil] what the run may do; nil runs it as the caller could
       # @return [String] the agent's output
-      # @raise [Failed] when the agent cannot start or exits non-zero
-      def ask(prompt:, chdir:, command: nil, log: nil)
-        words = command_for(command)
-        output, status = Open3.capture2e(*words, stdin_data: prompt, chdir: chdir)
+      # @raise [Failed] when the agent cannot start, runs past its timeout or exits non-zero
+      def ask(prompt:, chdir:, command: nil, log: nil, profile: nil)
+        words = command_for(command, profile)
+        refuse_unconfinable!(words, profile)
+        output, status = run(words, prompt, chdir, profile)
         File.open(log, "a") { |file| file.puts(output) } if log
         return output if status.success?
 
@@ -53,6 +57,58 @@ module Hecks
       rescue SystemCallError => e
         raise Failed, "agent could not start (#{words.first}): #{e.message}"
       end
+
+      private
+
+      # Permission rules are a feature of `claude`: any other command would run unconfined.
+      def refuse_unconfinable!(words, profile)
+        return if profile.nil? || profile.sandboxed? || words == default_command(profile)
+
+        raise Failed, "permission confinement applies only to the default claude command"
+      end
+
+      def run(words, prompt, chdir, profile)
+        return run_confined(words, prompt, chdir, profile) if profile
+
+        Open3.capture2e(*words, stdin_data: prompt, chdir: chdir)
+      end
+
+      def default_command(profile)
+        return DEFAULT_COMMAND unless profile
+
+        %w[claude -p --permission-mode] + [profile.permission_mode] + profile.tool_flags
+      end
+
+      # Runs `words` under the profile's sandbox with only the environment it names, in its own
+      # process group so a timeout takes the agent's children with it.
+      def run_confined(words, prompt, chdir, profile)
+        raise Failed, "no sandbox here; refusing to run an agent unconfined" unless profile.available?
+
+        Open3.popen2e(profile.environment, *profile.confine(words),
+                      chdir: chdir, unsetenv_others: true, pgroup: true) do |stdin, out, waiter|
+          feed(stdin, prompt)
+          reader = Thread.new { out.read }
+          finish(waiter, reader, profile.timeout)
+        end
+      end
+
+      def feed(stdin, prompt)
+        stdin.write(prompt)
+      rescue Errno::EPIPE
+        nil
+      ensure
+        stdin.close
+      end
+
+      def finish(waiter, reader, timeout)
+        unless waiter.join(timeout)
+          Process.kill("KILL", -waiter.pid)
+          waiter.join
+          reader.join
+          raise Failed, "agent timed out after #{timeout}s"
+        end
+        [reader.value, waiter.value]
+      end
     end
   end
 end

data/lib/hecks/quality_control/adapters/agent_profile.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+
+module Hecks
+  module Adapters
+    # What one `Agent` run may do: which tools it holds, where it may write, what it may reach on
+    # the network, which environment variables it sees and how long it may run.
+    #
+    # Confinement uses the macOS sandbox. Where there is none, a confined run refuses to start
+    # rather than run unconfined.
+    class AgentProfile
+      # What the network rule lets through: nothing, outbound HTTPS and name lookups, or anything.
+      NETWORKS = %i[none https any].freeze
+
+      # How a run is confined: under the operating system's sandbox, or by the permission rules
+      # of the `claude` command itself. Only the second leaves the user's own login usable, since
+      # the sandbox refuses the keychain and `~/.claude`.
+      CONFINEMENTS = %i[sandbox permissions].freeze
+
+      # The variables every confined agent sees besides the ones its profile names.
+      BASE_ENV = %w[PATH HOME USER LOGNAME SHELL LANG LC_ALL TERM TMPDIR].freeze
+
+      # The tools that write files; a permissions-confined run holds them only through path rules.
+      WRITING_TOOLS = %w[Write Edit MultiEdit NotebookEdit].freeze
+
+      # Home-relative places an agent may not read: credentials and the harness's own state.
+      CREDENTIAL_PATHS = %w[
+        .ssh .aws .gnupg .claude .config/gh .config/op .gem/credentials .netrc Library/Keychains
+      ].freeze
+
+      SANDBOX = "/usr/bin/sandbox-exec"
+
+      # @return [Array<String>] the tools the agent is given
+      attr_reader :tools
+      # @return [Array<String>] the directories the agent may write, besides the temp directory
+      attr_reader :writable
+      # @return [Symbol] one of `NETWORKS`
+      attr_reader :network
+      # @return [Array<String>] the environment variable names the agent may see besides `BASE_ENV`
+      attr_reader :env
+      # @return [Integer, nil] seconds the run may take; nil for no limit
+      attr_reader :timeout
+      # @return [Float, nil] the most the run may spend, in dollars, for an agent that takes one
+      attr_reader :budget
+      # @return [Symbol] one of `CONFINEMENTS`
+      attr_reader :confinement
+
+      # @param tools [Array<String>] the tools the agent is given
+      # @param writable [Array<String>] directories the agent may write
+      # @param network [Symbol] one of `NETWORKS`
+      # @param env [Array<String>] environment variable names to pass through
+      # @param timeout [Integer, nil] seconds the run may take
+      # @param budget [Float, nil] dollars the run may spend
+      # @param confinement [Symbol] one of `CONFINEMENTS`; `network` applies to the sandbox only
+      # @raise [ArgumentError] when `network` or `confinement` is not one it knows
+      def initialize(tools: [], writable: [], network: :none, env: [], timeout: nil, budget: nil,
+                     confinement: :sandbox)
+        unless NETWORKS.include?(network)
+          raise ArgumentError, "network must be one of #{NETWORKS.inspect}, not #{network.inspect}"
+        end
+        unless CONFINEMENTS.include?(confinement)
+          raise ArgumentError, "confinement must be one of #{CONFINEMENTS.inspect}, not #{confinement.inspect}"
+        end
+
+        @tools = tools.dup.freeze
+        @writable = writable.dup.freeze
+        @network = network
+        @env = env.dup.freeze
+        @timeout = timeout
+        @budget = budget
+        @confinement = confinement
+      end
+
+      # @return [Boolean] whether this profile is enforced by the operating system's sandbox
+      def sandboxed?
+        confinement == :sandbox
+      end
+
+      # @return [Boolean] whether this machine can apply this profile's confinement
+      def available?
+        !sandboxed? || File.executable?(SANDBOX)
+      end
+
+      # @param words [Array<String>] the agent's command
+      # @return [Array<String>] `words`, run under the sandbox with this profile's policy; the
+      #   words unchanged when the confinement is the command's own permission rules
+      def confine(words)
+        sandboxed? ? [SANDBOX, "-p", policy, *words] : words
+      end
+
+      # @return [String] the `claude` permission mode this profile runs under
+      def permission_mode
+        sandboxed? ? "acceptEdits" : "dontAsk"
+      end
+
+      # @param source [Hash{String => String}] the environment to take values from
+      # @return [Hash{String => String}] only the variables this profile lets the agent see
+      def environment(source = ENV)
+        source.to_h.slice(*BASE_ENV, *env)
+      end
+
+      # The `claude` flags this profile's tools and budget become.
+      #
+      # @return [Array<String>]
+      def tool_flags
+        flags = tools.empty? ? [] : ["--tools", tools.join(","), "--allowedTools", *allowed_tools]
+        flags += ["--strict-mcp-config"] unless sandboxed?
+        flags + (budget ? ["--max-budget-usd", budget.to_s] : [])
+      end
+
+      # @return [String] the sandbox policy: reads open but for credentials, writes where allowed
+      def policy
+        [
+          "(version 1)", "(allow default)",
+          "(deny file-write*)", write_rule, "(deny file-read*#{paths_clause(credential_paths)})",
+          *network_rules
+        ].join("\n")
+      end
+
+      private
+
+      # The tools allowed without asking. A permissions-confined run holds the writing tools only
+      # through an `Edit` rule per writable directory, which every file-writing tool answers to.
+      def allowed_tools
+        return [tools.join(",")] if sandboxed?
+
+        tools - WRITING_TOOLS + writable.map { |path| "Edit(/#{real(path)}/**)" }
+      end
+
+      def write_rule
+        allowed = [real(Dir.tmpdir), *writable.map { |path| real(path) }]
+        devices = '(literal "/dev/null") (literal "/dev/tty") (regex #"^/dev/fd/")'
+        "(allow file-write*#{paths_clause(allowed)} #{devices})"
+      end
+
+      def credential_paths
+        CREDENTIAL_PATHS.map { |path| File.join(Dir.home, path) }
+      end
+
+      def paths_clause(paths)
+        paths.map { |path| " (subpath #{quote(path)})" }.join
+      end
+
+      def network_rules
+        case network
+        when :any then []
+        when :https then ["(deny network*)", '(allow network-outbound (remote tcp "*:443") (remote udp "*:53"))',
+                          '(allow network-outbound (remote unix-socket (path-literal "/private/var/run/mDNSResponder")))']
+        else ["(deny network*)"]
+        end
+      end
+
+      def real(path)
+        File.realpath(path)
+      rescue SystemCallError
+        File.expand_path(path)
+      end
+
+      def quote(path)
+        %("#{path.gsub('\\', '\\\\\\\\').gsub('"', '\\"')}")
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/cli/qa_mine_combinations.rb

@@ -16,23 +16,28 @@ module Hecks
     # The command behind `hecks quality_control target.mine_combinations`: asks an agent to mine the
     # adversarial corpus for new domain combinations, then checks them. It is opt-in and never run
     # by `hecks quality_control sweep.tick` (an agent call costs money and answers differently each
-    # run).
-    # `--brief` prints the agent's prompt and stops; `--from <dir>` re-checks an earlier run;
-    # `--against <domain>` narrows the census; `--agent "cmd"` reads the prompt on stdin.
+    # run). `--brief` prints the agent's prompt and stops; `--from <dir>` re-checks an earlier run;
+    # `--against <domain>` narrows the census; `--agent "cmd"` reads the prompt on stdin;
+    # `--confine` limits the default agent to writing the run's candidates directory.
     #
     # The agent defaults to `claude -p` (`QA_MINER_AGENT` overrides); candidates that boot are
     # checked by `hecks quality_control target.check_generated_domains --source`, whose report is
     # this command's report. Exit 0: all clean. 2: a finding (see
-    # `.claude/skills/hecks_qa/SKILL.md`). 1: an operational
-    # error.
+    # `.claude/skills/hecks_qa/SKILL.md`). 1: an operational error.
     class QaMineCombinations
       EXIT_OK = 0
       EXIT_ERROR = 1
       RESULT_MARKER = "QA_GENERATED_RESULT "
 
+      # What `--confine` lets the default agent do: read anything, write the candidates directory,
+      # run for twenty minutes and spend two dollars.
+      CONFINED_TOOLS = %w[Read Glob Grep Write Edit].freeze
+      CONFINED_TIMEOUT = 1200
+      CONFINED_BUDGET = 2.0
+
       USAGE = "usage: hecks quality_control mine_combinations [--candidates N] [--rust] [--seeds K] " \
               "[--steps M] " \
-              "[--adversarial F] [--repair-rounds R] [--agent CMD] [--from <candidates-dir>] " \
+              "[--adversarial F] [--repair-rounds R] [--agent CMD] [--confine] [--from <candidates-dir>] " \
               "[--against <domain> …] [--brief]"
 
       Miner = Hecks::Fuzzing::CombinationMiner
@@ -65,7 +70,8 @@ module Hecks
         @out_dir = @options[:from] || File.join(@run_dir, "candidates")
         @agent_log = File.join(@run_dir, "agent.log")
         @agent = Hecks::Adapters::Agent.new
-        @command = @agent.command_for(@options[:agent])
+        @profile = confinement_profile if @options[:confine]
+        @command = @agent.command_for(@options[:agent], @profile)
         corpus = @options[:against].empty? ? Miner.corpus_paths(@root) : @options[:against]
         @brief = Miner.brief(corpus, root: @root, bug_titles: Miner.recent_bug_titles(@root))
         prompt = Miner.prompt(@root, @brief, count: @options[:candidates], out_dir: @out_dir)
@@ -89,7 +95,7 @@ module Hecks
 
       def parse(argv)
         options = { candidates: 3, rust: false, seeds: 5, steps: 25, adversarial: 0.3, repair_rounds: 1,
-                    agent: nil, from: nil, brief: false, against: [] }
+                    agent: nil, from: nil, brief: false, confine: false, against: [] }
         until argv.empty?
           arg = argv.shift
           if %w[-h --help].include?(arg)
@@ -108,6 +114,7 @@ module Hecks
           options[key] = reader.call(argv.shift)
         when "--rust" then options[:rust] = true
         when "--brief" then options[:brief] = true
+        when "--confine" then options[:confine] = true
         when "--against" then options[:against] << File.expand_path(argv.shift)
         else abort "#{USAGE}\nunexpected argument: #{arg.inspect}"
         end
@@ -124,12 +131,19 @@ module Hecks
 
       # Returns nil when the agent finished, else why it did not.
       def ask_agent(prompt)
-        @agent.ask(prompt: prompt, command: @command, chdir: @root, log: @agent_log)
+        @agent.ask(prompt: prompt, command: @command, chdir: @root, log: @agent_log, profile: @profile)
         nil
       rescue Hecks::Adapters::Agent::Failed => e
         e.message
       end
 
+      # The profile `--confine` runs the agent under: it writes only the candidates directory.
+      def confinement_profile
+        FileUtils.mkdir_p(@out_dir)
+        Hecks::Adapters::AgentProfile.new(confinement: :permissions, tools: CONFINED_TOOLS, writable: [@out_dir],
+                                          timeout: CONFINED_TIMEOUT, budget: CONFINED_BUDGET)
+      end
+
       def boot_error(candidate, boot_root)
         dir = Hecks::Fuzzing::DomainGenerator.write(
           { "source" => File.read(candidate[:bluebook]), "aggregates" => [], "policies" => [] },

data/lib/hecks/version.rb

@@ -1,5 +1,5 @@
 module Hecks
   # Read directly by the gemspec, so this file must never require the
   # rest of the gem (its dependencies aren't resolved yet at that point).
-  VERSION = "3.1.1".freeze
+  VERSION = "3.1.3".freeze
 end

data/rust/codegen/src/commands.rs

@@ -444,14 +444,7 @@ pub fn emit_command(exemplar: &Exemplar, command: &Json, aggregate: &Json, domai
         .collect();
 
     let transition = mutations::lifecycle_transition_for(command, aggregate);
-    let transition_arg = match &transition {
-        Some(t) => format!(
-            "Some(crate::kernel::TransitionCheck {{ field: {}, from_states: &[{}] }})",
-            naming::ruby_inspect_string(&t.field),
-            t.from_states.iter().map(|s| naming::ruby_inspect_string(s)).collect::<Vec<_>>().join(", ")
-        ),
-        None => "None".to_string(),
-    };
+    let transition_arg = mutations::transition_check_arg(transition.as_ref());
 
     let mutations_list = command.get("mutations").map(Json::each).unwrap_or(&[]);
     // A `delegate` mutation is rendered by `delegation_of`, which overwrites `mutation_lines`;
@@ -772,14 +765,7 @@ fn delegation_of(exemplar: &Exemplar, command: &Json, aggregate: &Json, value_ob
         })
         .collect();
     let transition = mutations::lifecycle_transition_for(target, entity);
-    let transition_arg = match &transition {
-        Some(t) => format!(
-            "Some(crate::kernel::TransitionCheck {{ field: {}, from_states: &[{}] }})",
-            naming::ruby_inspect_string(&t.field),
-            t.from_states.iter().map(|s| naming::ruby_inspect_string(s)).collect::<Vec<_>>().join(", ")
-        ),
-        None => "None".to_string(),
-    };
+    let transition_arg = mutations::transition_check_arg(transition.as_ref());
     let mut mutation_lines: Vec<String> = target
         .get("mutations")
         .map(Json::each)
@@ -896,14 +882,7 @@ pub fn emit_entity_command(
         .collect();
 
     let transition = mutations::lifecycle_transition_for(command, entity);
-    let transition_arg = match &transition {
-        Some(t) => format!(
-            "Some(crate::kernel::TransitionCheck {{ field: {}, from_states: &[{}] }})",
-            naming::ruby_inspect_string(&t.field),
-            t.from_states.iter().map(|s| naming::ruby_inspect_string(s)).collect::<Vec<_>>().join(", ")
-        ),
-        None => "None".to_string(),
-    };
+    let transition_arg = mutations::transition_check_arg(transition.as_ref());
 
     let mutations_list = command.get("mutations").map(Json::each).unwrap_or(&[]);
     let mut mutation_lines: Vec<String> = mutations_list.iter().map(|m| mutations::emit_mutation_line(exemplar, m, entity, command, value_objects_by_name, false)).collect();
@@ -1063,14 +1042,7 @@ pub fn emit_nested_entity_command(
 
     // The nested entity's lifecycle, as in `emit_entity_command`.
     let transition = mutations::lifecycle_transition_for(command, nested);
-    let transition_arg = match &transition {
-        Some(t) => format!(
-            "Some(crate::kernel::TransitionCheck {{ field: {}, from_states: &[{}] }})",
-            naming::ruby_inspect_string(&t.field),
-            t.from_states.iter().map(|s| naming::ruby_inspect_string(s)).collect::<Vec<_>>().join(", ")
-        ),
-        None => "None".to_string(),
-    };
+    let transition_arg = mutations::transition_check_arg(transition.as_ref());
 
     let mutations_list = command.get("mutations").map(Json::each).unwrap_or(&[]);
     let mut mutation_lines: Vec<String> = mutations_list.iter().map(|m| mutations::emit_mutation_line(exemplar, m, nested, command, value_objects_by_name, false)).collect();

data/rust/codegen/src/mutations.rs

@@ -392,6 +392,23 @@ pub struct Transition {
     pub field: String,
     pub to_state: String,
     pub from_states: Vec<String>,
+    /// A row with no `from:` admits every state, so no check is emitted for the command.
+    pub unconstrained: bool,
+}
+
+/// The `Option<TransitionCheck>` expression a dispatch function is generated with.
+///
+/// `None` covers both "no transition" and an unconstrained one; an empty `from_states` slice
+/// would refuse every state instead of admitting every state.
+pub fn transition_check_arg(transition: Option<&Transition>) -> String {
+    match transition {
+        Some(t) if !t.unconstrained => format!(
+            "Some(crate::kernel::TransitionCheck {{ field: {}, from_states: &[{}] }})",
+            naming::ruby_inspect_string(&t.field),
+            t.from_states.iter().map(|s| naming::ruby_inspect_string(s)).collect::<Vec<_>>().join(", ")
+        ),
+        _ => "None".to_string(),
+    }
 }
 
 /// Collapses a command's transition rows into the shape `TransitionCheck` wants.
@@ -417,19 +434,25 @@ pub fn lifecycle_transition_for(command: &Json, aggregate: &Json) -> Option<Tran
             }
         }
         let field = lifecycle.get("field").and_then(Json::as_str).unwrap_or("").to_string();
-        return Some(Transition { field, to_state: String::new(), from_states });
+        return Some(Transition { field, to_state: String::new(), from_states, unconstrained: false });
     }
 
     let field = lifecycle.get("field").and_then(Json::as_str).unwrap_or("").to_string();
     let to_state = rows[0].get("to_state").map(Json::to_s).unwrap_or_default();
     let mut from_states: Vec<String> = Vec::new();
+    let mut unconstrained = false;
     for row in &rows {
-        let from = row.get("from_state").map(Json::to_s).unwrap_or_default();
-        if !from_states.contains(&from) {
-            from_states.push(from);
+        match row.get_raw("from_state") {
+            None | Some(Json::Null) => unconstrained = true,
+            Some(from) => {
+                let from = from.to_s();
+                if !from_states.contains(&from) {
+                    from_states.push(from);
+                }
+            }
         }
     }
-    Some(Transition { field, to_state, from_states })
+    Some(Transition { field, to_state, from_states, unconstrained })
 }
 
 /// Right-hand side for a `set`, coercing the source into the target attribute's declared type.
@@ -782,3 +805,49 @@ fn emit_mutation_line_body(
         other => panic!("unsupported mutation op {other:?} — command_skip_reason should have caught this"),
     }
 }
+
+#[cfg(test)]
+mod transition_tests {
+    use super::*;
+
+    fn aggregate(rows: &str) -> Json {
+        Json::parse(&format!(
+            r#"{{"name":"Account","lifecycle":{{"field":"status","default":"draft","transitions":[{rows}]}}}}"#
+        ))
+        .unwrap()
+    }
+
+    fn command(name: &str) -> Json {
+        Json::parse(&format!(r#"{{"name":"{name}"}}"#)).unwrap()
+    }
+
+    #[test]
+    fn a_transition_without_from_admits_every_state() {
+        let account = aggregate(r#"{"command":"Open","to_state":"open","from_state":null}"#);
+        let transition = lifecycle_transition_for(&command("Open"), &account).unwrap();
+        assert!(transition.unconstrained);
+        assert_eq!(transition.to_state, "open");
+        assert_eq!(transition_check_arg(Some(&transition)), "None");
+    }
+
+    #[test]
+    fn a_transition_with_from_checks_that_state() {
+        let account = aggregate(r#"{"command":"Close","to_state":"closed","from_state":"open"}"#);
+        let transition = lifecycle_transition_for(&command("Close"), &account).unwrap();
+        assert!(!transition.unconstrained);
+        assert_eq!(
+            transition_check_arg(Some(&transition)),
+            r#"Some(crate::kernel::TransitionCheck { field: "status", from_states: &["open"] })"#
+        );
+    }
+
+    #[test]
+    fn one_unconstrained_row_among_constrained_ones_admits_every_state() {
+        let account = aggregate(
+            r#"{"command":"Reopen","to_state":"open","from_state":"closed"},
+               {"command":"Reopen","to_state":"open","from_state":null}"#,
+        );
+        let transition = lifecycle_transition_for(&command("Reopen"), &account).unwrap();
+        assert_eq!(transition_check_arg(Some(&transition)), "None");
+    }
+}

data/rust/host/HECKS_RELEASE

@@ -1 +1 @@
-3.1.1
+3.1.3

data/rust/host/src/web/registration_receipt/tests.rs

@@ -0,0 +1,39 @@
+use super::*;
+
+#[test]
+fn cents_render_as_dollars_with_two_places() {
+    assert_eq!(dollars(10800), "$108.00");
+    assert_eq!(dollars(14805), "$148.05");
+    assert_eq!(dollars(5), "$0.05");
+}
+
+#[test]
+fn the_built_in_receipt_names_the_event_the_first_name_and_the_amount() {
+    let body = built_in_body(Some("Ada"), "Yogadelics", Some(10800));
+    assert!(body.starts_with("Hi Ada,"));
+    assert!(body.contains("You're registered for Yogadelics."));
+    assert!(body.contains("$108.00"));
+    assert_eq!(receipt_subject("Yogadelics"), "You're registered for Yogadelics");
+}
+
+#[test]
+fn a_built_in_receipt_without_a_name_or_amount_still_reads_cleanly() {
+    let body = built_in_body(None, "Yogadelics", None);
+    assert!(body.starts_with("Hi,"));
+    assert!(!body.contains("payment of"));
+}
+
+#[test]
+fn the_sites_finished_email_is_read() {
+    let answer = serde_json::json!({"subject": "You're registered for Yogadelics", "body": "Hi Ada,\n\nWhere: Somewhere\n"});
+    assert_eq!(
+        site_email_from_json(&answer),
+        Some(SiteEmail { subject: "You're registered for Yogadelics".into(), body: "Hi Ada,\n\nWhere: Somewhere\n".into() })
+    );
+}
+
+#[test]
+fn an_incomplete_answer_from_the_site_falls_back_to_the_built_in_wording() {
+    assert_eq!(site_email_from_json(&serde_json::json!({"error": "no such session"})), None);
+    assert_eq!(site_email_from_json(&serde_json::json!({"subject": "Hi", "body": "  "})), None);
+}