hecks 3.1.2 → 3.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 508adf3c37fdb512fe3fa7ba61d7f614742a76b750f0072a363bec69bc99cefd
-  data.tar.gz: 825f357d3d68ccab74ba071fc4ab3abc412ffc38458968d9f038a769e2039382
+  metadata.gz: 88b11874249737158a9451d66aa0842ef88fb3f1ff047cced68d97b2ce9fdc5f
+  data.tar.gz: 2872e381ce8e7fe5d46ef7a7623134dc23d923e57bdf194758effedaa1cc4671
 SHA512:
-  metadata.gz: e55bd4e1b03b8399b7dc189bee0cd126a00ec315eed8c1060cd0dd237c443c61af26d6005af246c1855f54f683d710646bf7b05fbb068335c14fbb01eb5cdcef
-  data.tar.gz: 300db7e2fd71722c2627fa1bcc96c992776d87e796db3cdc83570eb8b48f2200c05def67bea1f116a30506c613f69e44a4573d36f3e36fd5bc394687b694855f
+  metadata.gz: 76a39ab361adfb4e07bb558cb917d46bf3d7b6bb21340ff9789cb7b6c10be47a3197df4f394e8da73129feeb5b8439d9401f5e83b8620e0a512fce966c891377
+  data.tar.gz: 58f1514450a234f3807897401daf7db410739463a8603bf58b7d73e548f14424211b4d1c5f3af1dc7421b769f39582e15c6f22188932af3de054961eed2cb641

data/examples/pizzas/bluebook/hecksagon/mock_stripe_payment_adapter.rb

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+
+# Driving adapter standing in for a Stripe webhook handler: boots Pizzas and calls
+# Dispatcher#dispatch_port, which translates the payment into PizzaPaymentReceived.
+#
+#   examples/pizzas/bluebook/hecksagon/mock_stripe_payment_adapter.rb
+
+$LOAD_PATH.unshift File.expand_path("../../../../lib", __dir__)
+
+require "hecks"
+
+DOMAIN  = File.expand_path("../..", __dir__)
+RUNTIME = Hecks.boot(DOMAIN)
+
+# Unique per run: identity is never minted, so a repeated name would be refused as AlreadyExists.
+NAME = "StripeDemoMargherita-#{Process.pid}-#{rand(10_000)}".freeze
+
+# Set the stage: an order Purchase's `given` rules will accept.
+order = Order.create_pizza(name: { value: NAME }, pizza: { price_cents: { cents: 1200 }, size: { value: "large" } })
+order.add_topping(topping: { value: "Basil" }, amount: { value: 3 })
+
+puts "Before payment: #{order.status}, customer=#{order.customer_name.inspect}"
+
+# The webhook: a real handler would verify a Stripe signature; a reference is always a bare id.
+RUNTIME.dispatch_port(
+  "Pizzas", "Order", "PaymentGateway", "Receive",
+  flat: {
+    name:          NAME,
+    customer_name: { value: "Chris" },
+    amount:        { cents: 1200 }
+  }
+)
+
+sold = Order.find(NAME)
+puts "After payment:  #{sold.status}, customer=#{sold.customer_name.to_h}"
+puts "Events: #{sold.events.map(&:name).join(', ')}"

data/examples/pizzas/bluebook/pizzas.behaviors

@@ -0,0 +1,70 @@
+Hecks.behaviors "Pizzas" do
+  vision "Examples of how a pizza is built, sold, and found through this domain."
+
+  # `pizzas_behaviors.hecksagon` is a Memory-persisted sibling of
+  # `pizzas.hecksagon` that lives OUTSIDE bluebook/, so an ordinary
+  # directory boot of examples/pizzas never globs it up alongside the
+  # real one.
+  loads "pizzas.bluebook", "../pizzas_behaviors.hecksagon"
+
+  test "CreatePizza puts a fresh pizza on the menu, available for sale" do
+    tests "CreatePizza", on: "Order"
+    input  name: "Margherita", pizza: { price_cents: { cents: 1200 }, size: "large" }
+    expect status: "available", customer_name: nil
+  end
+
+  test "AddTopping refuses more than ten toppings" do
+    tests "AddTopping", on: "Order"
+    setup  "CreatePizza", name: "Loaded", pizza: { price_cents: { cents: 1500 }, size: "large" }
+    setup  "AddTopping",  name: "Loaded", topping: "Basil",     amount: 1
+    setup  "AddTopping",  name: "Loaded", topping: "Olives",    amount: 1
+    setup  "AddTopping",  name: "Loaded", topping: "Mushroom",  amount: 1
+    setup  "AddTopping",  name: "Loaded", topping: "Onion",     amount: 1
+    setup  "AddTopping",  name: "Loaded", topping: "Pepper",    amount: 1
+    setup  "AddTopping",  name: "Loaded", topping: "Sausage",   amount: 1
+    setup  "AddTopping",  name: "Loaded", topping: "Bacon",     amount: 1
+    setup  "AddTopping",  name: "Loaded", topping: "Pineapple", amount: 1
+    setup  "AddTopping",  name: "Loaded", topping: "Anchovy",   amount: 1
+    setup  "AddTopping",  name: "Loaded", topping: "Jalapeno",  amount: 1
+    input  name: "Loaded", topping: "Extra Cheese", amount: 1
+    expect refused: "at most 10 toppings"
+  end
+
+  test "Purchase refuses a pizza with no toppings on it" do
+    tests "Purchase", on: "Order"
+    setup  "CreatePizza", name: "Bare", pizza: { price_cents: { cents: 900 }, size: "small" }
+    input  name: "Bare", customer_name: "Chris", amount: { cents: 900 }
+    expect refused: "at least one topping"
+  end
+
+  test "Purchase sells the pizza and closes its lifecycle" do
+    tests "Purchase", on: "Order"
+    setup  "CreatePizza", name: "Sold Out", pizza: { price_cents: { cents: 1200 }, size: "large" }
+    setup  "AddTopping",  name: "Sold Out", topping: "Basil", amount: 2
+    input  name: "Sold Out", customer_name: "Chris", amount: { cents: 1200 }
+    expect emits: ["PizzaPurchased"]
+  end
+
+  test "a sold pizza is no longer Available" do
+    tests "Available", on: "Order", kind: :query
+    setup  "CreatePizza", name: "Fresh",     pizza: { price_cents: { cents: 1000 }, size: "small" }
+    setup  "CreatePizza", name: "Also Sold", pizza: { price_cents: { cents: 1100 }, size: "small" }
+    setup  "AddTopping",  name: "Also Sold", topping: "Basil", amount: 1
+    setup  "Purchase",    name: "Also Sold", customer_name: "Chris", amount: { cents: 1100 }
+    expect count: 1
+  end
+
+  test "CostingLessThan finds a pizza under the ceiling named" do
+    tests "CostingLessThan", on: "Order", kind: :query
+    setup  "CreatePizza", name: "Bargain", pizza: { price_cents: { cents: 800 }, size: "small" }
+    setup  "CreatePizza", name: "Splurge", pizza: { price_cents: { cents: 1800 }, size: "large" }
+    input  ceiling: { cents: 1000 }
+    expect count: 1
+  end
+
+  test "Available's own row can be checked directly, not just counted" do
+    tests "Available", on: "Order", kind: :query
+    setup  "CreatePizza", name: "Only One", pizza: { price_cents: { cents: 950 }, size: "small" }
+    expect status: "available", name: { value: "Only One" }
+  end
+end

data/examples/pizzas/bluebook/pizzas.bluebook

@@ -0,0 +1,138 @@
+Hecks.bluebook "Pizzas" do
+  vision "Put toppings on a pizza and sell it to a customer."
+  supporting
+
+  aggregate "Order" do
+    description "An order that gathers toppings on a pizza and is eventually sold to a customer."
+
+    attribute :name,          PizzaName
+    attribute :pizza,         Pizza
+    attribute :toppings,      list_of(Topping)
+    # Optional: unknown until `Purchase` sets it.
+    attribute :customer_name, CustomerName, optional: true
+
+    identified_by :name
+
+    value_object "PizzaName" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a pizza is named") { !value.to_s.empty? }
+    end
+
+    value_object "Price" do
+      attribute :cents, Integer
+
+      invariant("a price is never negative") { cents >= 0 }
+    end
+
+    value_object "CustomerName" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a customer is named") { !value.to_s.empty? }
+    end
+
+    value_object "ToppingName" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a topping is named") { !value.to_s.empty? }
+    end
+
+    value_object "ToppingAmount" do
+      attribute :value, Integer
+
+      invariant("an amount is positive") { value.positive? }
+    end
+
+    value_object "Topping" do
+      attribute :name,   String, pattern: '[^ \t\n\r]'
+      attribute :amount, Integer
+    end
+
+    # A named, reusable closed set as a sibling value object; the inline `one_of(...)` shorthand
+    # cannot be spelled inside a `value_object` block.
+    value_object "Size" do
+      attribute :value, String, one_of: ["small", "large"]
+    end
+
+    # What was ordered; who ordered it and payment state live on Order.
+    value_object "Pizza" do
+      attribute :price_cents, Price
+      attribute :size,        Size
+    end
+
+    lifecycle :status, default: "available" do
+      transition "Purchase" => "sold", from: "available"
+    end
+
+    query "Available" do
+      where(status: "available")
+      order_by :name
+    end
+
+    # Both price queries reach through the nested Pizza value object with a dotted path.
+    query "CostingLessThan" do
+      attribute :ceiling, Price
+      where(:"pizza.price_cents.cents" => { lt: :ceiling })
+      order_by :name
+    end
+
+    # A literal, not a kwarg: exercises the path where the where-clause number is stringified.
+    query "Expensive" do
+      where(:"pizza.price_cents.cents" => { gt: 1000 })
+      order_by :name
+    end
+
+    command "CreatePizza" do
+      role "Chef"
+      goal "Put a new pizza on the menu"
+
+      attribute :name,  PizzaName
+      attribute :pizza, Pizza
+
+      sets :name
+      sets :pizza
+
+      emits PizzaCreated
+    end
+
+    # AddTopping has no transition, so `from:` is its only lifecycle guard.
+    command "AddTopping", from: "available" do
+      role "Chef"
+      goal "Customize a pizza with an ingredient"
+
+      reference_to Order
+      attribute :topping, ToppingName
+      attribute :amount, ToppingAmount
+
+      given("at most 10 toppings")            { toppings.size < 10 }
+
+      sets :toppings, append: { name: :topping, amount: :amount }
+
+      emits ToppingAdded
+    end
+
+    command "Purchase", from: "available" do
+      role "Customer"
+      goal "Buy the pizza"
+
+      reference_to Order
+      attribute :amount, Price
+
+      given("a pizza needs at least one topping") { toppings.size.positive? }
+      given("a payment was actually made")         { amount.cents.positive? }
+      # Checks the payment itself is plausible (e.g. an underpayment), not whether one happened.
+      given("the payment covers the price") { amount.cents >= pizza.price_cents.cents }
+
+      # The lifecycle transition sets status; a `sets` on the lifecycle field is refused at build.
+      sets :customer_name
+
+      emits PizzaPurchased
+    end
+  end
+
+  # A payment arriving is an external fact; the business rules stay on Purchase.
+  policy "OnPizzaPaymentReceived" do
+    on Order::PizzaPaymentReceived
+    trigger Order::Purchase
+  end
+end

data/examples/pizzas/bluebook/pizzas.hecksagon

@@ -0,0 +1,21 @@
+Hecks.hecksagon "Pizzas" do
+  # Role declarations only enforce access once Governance can check them; this standalone
+  # deploy attaches and binds Governance itself.
+  attaches "Governance"
+  Pizzas::Order.persisted_by("Memory")
+
+  # The primary port: an outside adapter (a payment webhook) translates an external fact into
+  # our vocabulary; business rules stay on Purchase, reached via OnPizzaPaymentReceived.
+  Pizzas::Order.port "PaymentGateway" do
+    operation "Receive" do
+      attribute :customer_name, CustomerName
+      attribute :amount, Price
+      emits "PizzaPaymentReceived"
+    end
+  end
+end
+
+Hecks.hecksagon "Governance" do
+  Governance::RoleAssignment.persisted_by("Memory")
+  Governance::RoleTransition.persisted_by("Memory")
+end

data/examples/pizzas/bluebook/pizzas.world

@@ -0,0 +1,3 @@
+Hecks.world "Pizzas" do
+  realm "Examples"
+end

data/examples/pizzas/bluebook/translations/2-77625c.bluebook

@@ -0,0 +1,6 @@
+Hecks.data_translation "Pizzas", from: "e3f3d7", to: "77625c" do
+  aggregate "Order", was: "Pizza" do
+    move :price_cents, to: "pizza.price_cents"
+    move :size,         to: "pizza.size"
+  end
+end

data/examples/pizzas/oidc.json

@@ -0,0 +1,24 @@
+{
+  "audience": "Pizzas",
+  "scopes": [
+    {
+      "scope": "pizzas:order.add_topping",
+      "verb": "Pizzas::Order.AddTopping",
+      "role": "Chef"
+    },
+    {
+      "scope": "pizzas:order.create_pizza",
+      "verb": "Pizzas::Order.CreatePizza",
+      "role": "Chef"
+    },
+    {
+      "scope": "pizzas:order.purchase",
+      "verb": "Pizzas::Order.Purchase",
+      "role": "Customer"
+    }
+  ],
+  "roles": [
+    "Chef",
+    "Customer"
+  ]
+}

data/examples/pizzas/pizzas_behaviors.hecksagon

@@ -0,0 +1,19 @@
+# Memory-bound sibling of pizzas.hecksagon: `pizzas.behaviors` boots a fresh runtime per
+# test, so it loads this sibling instead of the one beside the bluebook.
+Hecks.hecksagon "Pizzas" do
+  attaches "Governance"
+  Pizzas::Order.persisted_by("Memory")
+
+  Pizzas::Order.port "PaymentGateway" do
+    operation "Receive" do
+      attribute :customer_name, CustomerName
+      attribute :amount, Price
+      emits "PizzaPaymentReceived"
+    end
+  end
+end
+
+Hecks.hecksagon "Governance" do
+  Governance::RoleAssignment.persisted_by("Memory")
+  Governance::RoleTransition.persisted_by("Memory")
+end

data/lib/hecks/cli/console.rb

@@ -47,12 +47,15 @@ module Hecks
       end
 
       # @param runtime [Runtime] a booted domain
-      # @return [String] each chapter's vision and its aggregates' commands
+      # @return [String] each chapter's vision, and its aggregates' descriptions and commands
       def overview(runtime)
         runtime.registry.bluebooks.each_value.map do |bluebook|
           aggregates = bluebook.aggregates.map do |aggregate|
             commands = aggregate.commands.map { |command| "#{Naming.snake(command.hecks_name)}!" }.sort.join(", ")
-            "    #{aggregate.name}: #{commands}"
+            description = aggregate.description.to_s.strip
+            lines = ["    #{aggregate.name}: #{commands}"]
+            lines << "      #{description}" unless description.empty?
+            lines.join("\n")
           end
 
           "\n    #{bluebook.name} — #{bluebook.vision}\n#{aggregates.join("\n")}\n"

data/lib/hecks/doors/cli_runner.rb

@@ -120,6 +120,7 @@ module Hecks
 
         name = argv.first
         return { answer: [cli[:usage], 0] } if name.nil? || %w[--help -h help].include?(name)
+        return { answer: [all_usage(bluebook, options), 0] } if name == "--all"
 
         asking, name, argv = entry_word(cli, argv)
         return { answer: [cli[:usage], 1] } if name.nil?
@@ -141,6 +142,11 @@ module Hecks
           launcher: launcher }
       end
 
+      # The usage with the internal commands and queries listed too, which `--all` asks for.
+      def all_usage(bluebook, options)
+        Projector.call(:cli, bluebook: bluebook, options: options.merge(all: true))[:usage]
+      end
+
       # Reads the entry words of a line: whether it asks a query, the bare name, and the words
       # from the name on.
       #

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.2".freeze
+  VERSION = "3.1.3".freeze
 end

data/rust/host/HECKS_RELEASE

@@ -1 +1 @@
-3.1.2
+3.1.3

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hecks
 version: !ruby/object:Gem::Version
-  version: 3.1.2
+  version: 3.1.3
 platform: ruby
 authors:
 - Chris Young
@@ -35,6 +35,14 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- examples/pizzas/bluebook/hecksagon/mock_stripe_payment_adapter.rb
+- examples/pizzas/bluebook/pizzas.behaviors
+- examples/pizzas/bluebook/pizzas.bluebook
+- examples/pizzas/bluebook/pizzas.hecksagon
+- examples/pizzas/bluebook/pizzas.world
+- examples/pizzas/bluebook/translations/2-77625c.bluebook
+- examples/pizzas/oidc.json
+- examples/pizzas/pizzas_behaviors.hecksagon
 - exe/hecks
 - lib/hecks.rb
 - lib/hecks/adapters.rb
@@ -618,6 +626,7 @@ files:
 - lib/hecks/projector/target.rb
 - lib/hecks/quality_control/adapters/agent.adapter
 - lib/hecks/quality_control/adapters/agent.rb
+- lib/hecks/quality_control/adapters/agent_profile.rb
 - lib/hecks/quality_control/adapters/angle_tools.adapter
 - lib/hecks/quality_control/adapters/angle_tools.rb
 - lib/hecks/quality_control/adapters/clearance_recorder.rb