hecks 5.0.0 → 7.0.0

data/lib/hecks/adapters/driven/sqlite/schema_builder.rb

@@ -5,6 +5,9 @@ module Hecks
     class Sqlite
       # DDL for one aggregate: head table, entry table, events, saga and outbox tables.
       module SchemaBuilder
+        # Any character an SQLite index name may not hold unquoted.
+        NON_IDENTIFIER_CHARACTER = /[^a-zA-Z0-9_]/
+
         private
 
         def create_aggregate_table!
@@ -12,10 +15,30 @@ module Hecks
           @db.execute(
             "CREATE TABLE IF NOT EXISTS #{quoted_table} (id TEXT PRIMARY KEY#{", " unless columns.empty?}#{columns.join(", ")})"
           )
+          ensure_aggregate_columns!
           # Called here so D1, which reuses this module, gets automatic indexing too.
           ensure_indexes!
         end
 
+        # CREATE TABLE IF NOT EXISTS never adds a column to an existing table, so an attribute the
+        # aggregate gained after its table was made gets its column here: nullable, since every row
+        # written before it holds no value. It only adds; a column the aggregate dropped is kept.
+        # SQLite column names are case-insensitive, so presence is compared that way too.
+        def ensure_aggregate_columns!
+          present = @db.execute("PRAGMA table_info(#{quoted_table})").map { |row| row["name"].to_s.downcase }
+          persisted_fields.reject { |field| present.include?(field[:name].to_s.downcase) }.each do |field|
+            add_column_once!(field)
+          end
+        end
+
+        # Another process or isolate may add the same column between the read and this ALTER;
+        # that duplicate is the outcome wanted, so only that error is let through.
+        def add_column_once!(field)
+          @db.execute("ALTER TABLE #{quoted_table} ADD COLUMN #{quote_ident(field[:name])} #{field[:sql_type]}")
+        rescue StandardError => e
+          raise unless e.message.include?("duplicate column name")
+        end
+
         def create_event_table!
           @db.execute(Ddl::EVENTS)
           # Backs #events_for's per-record lookup (a `corrects` command's history read).
@@ -58,6 +81,10 @@ module Hecks
           @db.execute("CREATE INDEX IF NOT EXISTS idx_hecks_outbox_status ON hecks_outbox(aggregate, status)")
         end
 
+        def create_dispatch_claims_table!
+          @db.execute(Ddl::DISPATCH_CLAIMS)
+        end
+
         # One row per aggregate table, naming the highest entry `sequence` this table has
         # already had projected into it — shared across every aggregate in the database file,
         # since it is keyed by table name rather than declared per aggregate.
@@ -89,8 +116,13 @@ module Hecks
 
         def declared_query_fields
           queries = @aggregate.queries + @aggregate.entities.flat_map(&:queries)
-          queries.flat_map { |query| query.wheres.map(&:field) + [query.order_by&.field] }
-                 .compact.map(&:to_s).uniq
+          fields = queries.flat_map { |query| query_fields(query) }
+          fields.compact.map(&:to_s).uniq
+        end
+
+        # The fields a query filters on, then the one it orders by (nil when it orders by none).
+        def query_fields(query)
+          query.wheres.map(&:field) + [query.order_by_field]
         end
 
         # A scalar or lifecycle field gets a btree index; a value-object path gets an expression
@@ -100,7 +132,7 @@ module Hecks
         def ensure_index_for_field!(field)
           name, * = field.to_s.split(".")
           attribute = @aggregate.attribute(name)
-          lifecycle_field = @aggregate.lifecycle&.field.to_s == name
+          lifecycle_field = @aggregate.lifecycle_field.to_s == name
 
           return if !lifecycle_field && attribute.nil?
           return if attribute&.list?
@@ -114,7 +146,7 @@ module Hecks
         # Table-prefixed because SQLite index names are global to the database.
         # The field is sanitized (a dotted path's ".") to stay a valid identifier.
         def index_name(field)
-          sanitized = field.to_s.gsub(/[^a-zA-Z0-9_]/, "_")
+          sanitized = field.to_s.gsub(NON_IDENTIFIER_CHARACTER, "_")
           "idx_#{table}_#{sanitized}"
         end
       end

data/lib/hecks/adapters/driven/sqlite/set_dialect.rb

@@ -0,0 +1,39 @@
+module Hecks
+  module Adapters
+    class Sqlite
+      # SQLite's spellings for the shared {SetTransform} statement (ADR 0129).
+      module SetDialect
+        # @return [String] the dialect the operator ledger's renderings name
+        def set_transform_dialect = "sqlite"
+
+        private
+
+        # Numbered, so a guard can repeat an operand's text and still bind the same value.
+        def typed_placeholder(binds, value, _type)
+          binds << value
+          "?#{binds.size}"
+        end
+
+        def null_safe_equality(left, right, negated:) = "(#{left} IS #{"NOT " if negated}#{right})"
+
+        # SQLite compares text by bytes, as Ruby compares Strings.
+        def text_ordering(sql) = sql
+
+        # An integer result that overflowed comes back as a real, which Ruby would refuse.
+        def integer_guard(sql) = "typeof(#{sql}) = 'integer'"
+
+        def scalar_read(column, member, _type) = "json_extract(#{quote_ident(column)}, '$.#{member}')"
+
+        def scalar_write(member, sql) = "json_object('#{member}', #{sql})"
+
+        def version_bump = []
+
+        def run_set_transform(sql, binds)
+          @db.execute(sql, binds).map { |row| Runtime::Instance.new(aggregate: @aggregate, id: row["id"], state: decode(row)) }
+        rescue SQLite3::Exception => e
+          raise SetTransform::Declined, "SQLite refused the set transform: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/sqlite.adapter

@@ -1,6 +1,8 @@
 Hecks.adapter "SqlitePersistence" do
   port   "persistence"
   field  :database, default: "data/{storage_name}.db"
+  # Rewrites every row of an aggregate in one statement.
+  provides "set_transform"
 end
 
 Hecks.adapter "SqliteProjection" do

data/lib/hecks/adapters/driven/sqlite.rb

@@ -3,13 +3,17 @@ require "fileutils"
 
 require_relative "sql_query_builder"
 require_relative "sqlite/schema_builder"
+require_relative "sqlite/name_guard"
 require_relative "sqlite/codec"
 require_relative "sqlite/dialect"
 require_relative "sqlite/events"
 require_relative "sqlite/journal"
 require_relative "sqlite/outbox"
+require_relative "sqlite/dispatch_claims"
 require_relative "sqlite/repository"
 require_relative "sqlite/sagas"
+require_relative "sqlite/set_dialect"
+require_relative "set_transform"
 require_relative "../../ports/persistence/append_only"
 require_relative "../../query_specification/common/null_policy"
 require_relative "../../query_specification/common/order_by"
@@ -25,22 +29,28 @@ module Hecks
     class Sqlite
       include SqlQueryBuilder
       include SchemaBuilder
+      include NameGuard
       include Codec
       include Repository
       include Journal
       include Events
       include Outbox
+      include DispatchClaims
       include Sagas
       include Dialect
+      include SetTransform
+      include SetDialect
 
       SQL_TYPES = { "Integer" => "INTEGER", "Float" => "REAL" }.freeze
 
       attr_reader :aggregate, :path
 
       # Names the optional persistence capabilities `Ports::Persistence::AppendOnly` may rely on.
+      # `:dispatch_claims`: `dispatch_claim` joins the save's transaction, so a claim and the
+      # write it guards commit or roll back together.
       #
-      # @return [Array<Symbol>] `[:atomic_put]`
-      def persistence_capabilities = [:atomic_put]
+      # @return [Array<Symbol>] `[:atomic_put, :dispatch_claims]`
+      def persistence_capabilities = %i[atomic_put dispatch_claims]
 
       # Opens (creating if absent) the database file and its aggregate, journal, event, saga
       # and outbox tables.
@@ -62,6 +72,7 @@ module Hecks
         # Scopes saga rows; falls back to the aggregate's name for a directly built adapter.
         @domain = settings.fetch(:domain) { aggregate.name }.to_s
         open_database
+        refuse_orphaned_rows!
         create_tables!
       end
 
@@ -77,7 +88,9 @@ module Hecks
       def transaction(&)
         return yield if @db.transaction_active?
 
-        @db.transaction(&)
+        # Immediate, so the write lock is taken up front: a deferred transaction that reads and then
+        # writes fails at once when another process holds the file, and the busy timeout never runs.
+        @db.transaction(:immediate, &)
       end
 
       # Names the aggregate's table; the journal table and outbox rows are keyed off it.
@@ -90,6 +103,9 @@ module Hecks
       def open_database
         FileUtils.mkdir_p(File.dirname(@path))
         @db = SQLite3::Database.new(@path)
+        # Several processes may boot one journal at once (the gate's checks do), so a busy file
+        # is waited for rather than refused as "database is locked".
+        @db.busy_timeout = 10_000
         @db.results_as_hash = true
         # The append is the recovery commit point, so the fsync policy is explicit.
         @db.execute("PRAGMA synchronous = FULL")
@@ -103,6 +119,7 @@ module Hecks
         create_event_table!
         create_saga_table!
         create_outbox_table!
+        create_dispatch_claims_table!
         create_checkpoint_table!
       end
 

data/lib/hecks/adapters/driven/tenant_provisioner.rb

@@ -37,7 +37,7 @@ module Hecks
       # @param adapter [String, Hash, nil] the adapter the overlay binds; PostgresEra when none
       # @return [Hash{Symbol => Object}] `:slug`, `:domain`, `:realm`, `:schema` and `:output`
       # @raise [Refused] when a value is outside its allow-list or the path leaves `environments/`
-      def write_overlay(slug:, domain:, realm:, schema:, database:, directory:, adapter: nil, **) # rubocop:disable Metrics/ParameterLists -- one keyword per command attribute
+      def write_overlay(slug:, domain:, realm:, schema:, database:, directory:, adapter: nil, **)
         values = { slug: unwrap(slug), domain: unwrap(domain), realm: unwrap(realm),
                    schema: unwrap(schema), database: unwrap(database),
                    adapter: adapter_name(adapter) }

data/lib/hecks/adapters/driven/worktree_overlay.rb

@@ -0,0 +1,117 @@
+module Hecks
+  module Adapters
+    # Says, once per process, when a linked worktree lacks the gitignored overlay files its main
+    # checkout keeps. Those files exist only in the main checkout, so a command run from a
+    # worktree stores in Memory without saying so. This warns; it never blocks the command.
+    module WorktreeOverlay
+      # The line a linked worktree's `.git` file holds, naming the directory in the main checkout.
+      GITDIR_LINE = /\Agitdir: (.+)\s*\z/
+
+      # Where the overlay files live, relative to a checkout's root.
+      OVERLAY_PATTERNS = ["lib/hecks/hecks/*.local.hecksagon", "lib/hecks/hecks/*.local.world",
+                          "environments/local.hecksagon", "environments/local.world"].freeze
+
+      module_function
+
+      # Warns on standard error the first time a domain loads from a linked worktree that lacks
+      # overlay files of its main checkout. Nothing is printed again in the same process.
+      #
+      # @param directory [String] the domain directory being loaded
+      # @param err [#puts] where the warning goes
+      # @return [String, nil] the warning printed, or nil when there was nothing to say
+      def warn_once(directory, err: $stderr)
+        return if @warned
+
+        text = warning_for(directory)
+        return unless text
+
+        @warned = true
+        err.puts(text)
+        text
+      end
+
+      # The warning for a directory inside a linked worktree, or nil when none applies.
+      #
+      # @param directory [String] a directory inside a checkout
+      # @return [String, nil]
+      def warning_for(directory)
+        _main, files = gap(directory)
+        message(files)
+      end
+
+      # The main checkout a linked worktree was made from, and the overlay files that checkout
+      # holds and this worktree lacks. Nothing is returned for a checkout that is not a worktree.
+      #
+      # @param directory [String] a directory inside a checkout
+      # @return [Array(String, Array<String>), Array(nil, Array)] the main checkout's root, then the
+      #   relative paths of the overlay files it holds and the worktree lacks
+      def gap(directory)
+        worktree = checkout_root(directory)
+        main = worktree && main_checkout(worktree)
+        return [nil, []] unless main
+
+        [main, missing(overlay_files(main), overlay_files(worktree))]
+      end
+
+      # Relative paths of the overlay files that a checkout holds.
+      #
+      # @param root [String] a checkout's root
+      # @return [Array<String>] sorted relative paths
+      def overlay_files(root)
+        OVERLAY_PATTERNS.flat_map { |pattern| Dir.glob(File.join(root, pattern)) }
+                        .map { |path| path.delete_prefix("#{root}/") }
+                        .sort
+      end
+
+      # The overlay files the main checkout holds and the worktree does not.
+      #
+      # @param main [Array<String>] relative paths in the main checkout
+      # @param worktree [Array<String>] relative paths in the worktree
+      # @return [Array<String>]
+      def missing(main, worktree)
+        main - worktree
+      end
+
+      # The one-line warning naming the files and the store they change.
+      #
+      # @param files [Array<String>] relative paths the worktree lacks
+      # @return [String, nil] the warning, or nil when no file is missing
+      def message(files)
+        return if files.empty?
+
+        "hecks: this worktree lacks #{files.join(", ")} from the main checkout; " \
+          "bluebooks that use them store in Memory here, not in the main checkout's store"
+      end
+
+      # The root of the checkout a directory is in, and whether that checkout is a linked worktree.
+      #
+      # @param directory [String]
+      # @return [String, nil] the root when it is a linked worktree, else nil
+      def checkout_root(directory)
+        root = ascend_to_git(File.expand_path(directory))
+        root if root && File.file?(File.join(root, ".git"))
+      end
+
+      # The main checkout a linked worktree was made from, found through its `.git` file.
+      #
+      # @param worktree [String] a linked worktree's root
+      # @return [String, nil]
+      def main_checkout(worktree)
+        gitdir = File.read(File.join(worktree, ".git"))[GITDIR_LINE, 1]
+        return unless gitdir
+
+        common = File.expand_path("../..", File.expand_path(gitdir, worktree))
+        File.dirname(common)
+      end
+
+      # Walks up from a directory to the first one holding a `.git` entry.
+      #
+      # @param directory [String] an absolute path
+      # @return [String, nil]
+      def ascend_to_git(directory)
+        root = Pathname.new(directory).ascend.find { |dir| dir.join(".git").exist? }
+        root&.to_s
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven.rb

@@ -7,10 +7,14 @@ end
 require_relative "driven/memory"
 require_relative "driven/sqlite"
 require_relative "driven/postgres"
-# PostgresEra lives in a persistence plugin, autoloaded so a domain that never binds
-# it loads no era code; the plugin entry point registers itself on load (ADR 0033).
-Hecks::Adapters.autoload(:PostgresEra, "hecks/ports/persistence/plugins/era")
+# PostgresEra is autoloaded so a domain that never binds it loads no era code; loading it
+# installs the era persistence plugin, which registers itself (ADR 0033).
+Hecks::Adapters.autoload(:PostgresEra, "hecks/adapters/driven/postgres_era")
 require_relative "driven/lambda"
+# Loaded on first mention: nothing about a domain's own boot needs the dump
+# tooling, and it wants the optional `pg` gem.
+Hecks::Adapters.autoload(:PostgresDump, File.join(__dir__, "driven/postgres_dump"))
+Hecks::Ports::Persistence.autoload(:PostgresDump, File.join(__dir__, "driven/postgres_dump"))
 require_relative "driven/heki"
 require_relative "driven/local_storage"
 require_relative "driven/prism"
@@ -24,5 +28,6 @@ require_relative "driven/system_clock"
 # `identity_generation` adapter would make that port ambiguous for every boot.
 require_relative "driven/governance_authorization"
 require_relative "driven/identity_registry"
+require_relative "driven/google_authentication"
 require_relative "driven/claude_code"
 require_relative "driven/script_runner"

data/lib/hecks/adapters/driving/cli/shorthand.rb

@@ -4,6 +4,10 @@ module Hecks
       module Cli
         # Rewrites the shorthand spellings of a command line into plain `name=value` words.
         module Shorthand
+          # The declared types a bare `--name` flag may stand for: a plain Boolean, or a `Switch`,
+          # which wraps one.
+          BOOLEAN_TYPES = %w[Boolean Switch].freeze
+
           module_function
 
           # Rewrites the short forms into `name=value`: `--name` for a Boolean (a following `yes`,
@@ -58,7 +62,7 @@ module Hecks
           def flag(name, options)
             name = name.tr("-", "_") unless options.key?(name) || options.keys.any? { |key| key.start_with?("#{name}.") }
             path = options.key?(name) ? name : Cli.expand(name, options)
-            return path if options.dig(path, :type) == "Boolean"
+            return path if BOOLEAN_TYPES.include?(options.dig(path, :type))
 
             raise Runtime::NotFound, "--#{name} is a flag, but this command has no Boolean argument #{name.inspect}"
           end

data/lib/hecks/adapters/driving/cli.rb

@@ -75,11 +75,11 @@ module Hecks
           case type
           when "Integer" then Integer(value)
           when "Float"   then Float(value)
-          when "Boolean" then boolean(value)
+          when "Boolean", "Switch" then boolean(value)
           else value
           end
         rescue ArgumentError
-          raise Runtime::TypeMismatch, "#{value.inspect} is not #{type} — the chapter declares this field as #{type}"
+          raise Runtime::TypeMismatch, "#{value.inspect} is not #{type} — the bluebook declares this field as #{type}"
         end
 
         # Reads a Boolean word: `true`, `yes`, `1` or `on` is true; `false`, `no`, `0` or `off` is

data/lib/hecks/adapters/driving/cli_runner/answers.rb

@@ -1,4 +1,6 @@
 require "json"
+require_relative "run_reference"
+require_relative "read_context"
 
 module Hecks
   module Adapters
@@ -8,55 +10,116 @@ module Hecks
         # `CliRunner`.
         module Answers
           # What a dispatch needs beyond the spec: the parsed arguments, whether `--wait` was given,
-          # and the chapter and launcher setting the command belongs to.
-          Invocation = Struct.new(:args, :wait, :bluebook, :launcher)
+          # and the bluebook and launcher setting the command belongs to.
+          Invocation = Struct.new(:args, :wait, :bluebook, :launcher, :text, :plan)
+
+          # The flag that asks for a command's recorded output as plain text and nothing else.
+          TEXT = "--text".freeze
+
+          # The flag that asks what a command would write and announce, writing nothing.
+          PLAN = "--plan".freeze
 
           # Parses one resolved command's arguments, runs it as a query or command, and turns the
-          # outcome, or the domain's refusal, into `[json_or_message, status]`. With `--wait`, a
-          # question whose report names a gap (`LauncherOptions.gap_reported?`) answers status 1.
+          # outcome, or the domain's refusal, into `[json_or_message, status]`. A word the command
+          # does not take, a value its type cannot hold or a flag it lacks is a line that could
+          # not be read (`ExitStatus::USAGE`); everything the domain says no to, a missing record
+          # included, is `REFUSED`. With `--wait`, a question whose report names a gap
+          # (`LauncherOptions.gap_reported?`) is refused too.
           #
-          # @param bluebook [Bluebook::Chapter] the chapter the command belongs to
-          # @param launcher [Hash, nil] the chapter's `launcher` world setting; nil when not opted
+          # @param bluebook [Bluebook::Declaration] the bluebook the command belongs to
+          # @param launcher [Hash, nil] the bluebook's `launcher` world setting; nil when not opted
           #   in
-          def dispatch(runtime, spec, name, rest, program, asking, bluebook: nil, launcher: nil) # rubocop:disable Metrics/ParameterLists -- the signature is what `call` passes
-            args, wait = command_line(spec, rest, launcher)
-            return answer_query(runtime, spec, args, wait, launcher) if spec[:kind] == :query
+          def dispatch(runtime, spec, name, rest, program, asking, bluebook: nil, launcher: nil)
+            plan = rest.include?(PLAN)
+            args, wait, text = command_line(spec, plan ? rest - [PLAN] : rest, launcher)
+            run(runtime, spec, Invocation.new(args, wait, bluebook, launcher, text, plan), name, program, asking)
+          rescue Runtime::NotFound, Runtime::TypeMismatch => e
+            [help_pointer(e, name, program, asking), ExitStatus::USAGE]
+          end
 
-            run_command(runtime, spec, Invocation.new(args, wait, bluebook, launcher))
+          # Runs a parsed line as a query or a command, and shapes the domain's refusal.
+          # @api private
+          def run(runtime, spec, invocation, name, program, asking)
+            return plan_or_refuse(runtime, spec, invocation, name) if invocation.plan
+            return answer_query(runtime, spec, invocation.args, invocation.wait, invocation.launcher) if spec[:kind] == :query
+
+            run_command(runtime, spec, invocation)
           rescue Runtime::NotFound, Runtime::TypeMismatch => e
-            # A bad argument and a missing record both need the same next step: read the help.
-            ["#{e.message}\n\n  #{program} #{"query " if asking}#{name} --help", 1]
+            # A missing record needs the same next step as a bad argument: read the help.
+            [help_pointer(e, name, program, asking), ExitStatus::REFUSED]
           rescue *Runtime::DOMAIN_REFUSALS => e
-            # The refusal is the chapter's own sentence, verbatim.
-            [e.message, 1]
+            # The refusal is the bluebook's own sentence, verbatim.
+            [coded(e), ExitStatus::REFUSED]
           rescue StandardError => e
             # So is a wrapped tool's, when a question's adapter refuses to answer.
             raise unless tool_refusal?(e)
 
-            [e.message, 1]
+            [e.message, ExitStatus::REFUSED]
+          end
+
+          # A refusal's text, led by its stable code so a script can branch on it.
+          # @api private
+          def coded(error) = "[#{error.code}] #{error.message}"
+
+          # An error's message, then the line that prints the command's help.
+          # @api private
+          def help_pointer(error, name, program, asking)
+            "#{coded(error)}\n\n  #{program} #{"query " if asking}#{name} --help"
           end
 
-          # The parsed arguments of a command line and whether to wait for the reactions.
+          # The parsed arguments of a command line, whether to wait for the reactions, and whether
+          # `--text` asked for the recorded output alone (which waits).
           def command_line(spec, rest, launcher)
-            rest, wait = LauncherOptions.take_wait(spec, rest) if launcher
-            [Cli.arguments(spec, rest), wait || LauncherOptions.settled?(launcher, spec)]
+            text = launcher ? rest.include?(TEXT) : false
+            rest, wait = LauncherOptions.take_wait(spec, launcher ? rest - [TEXT] : rest)
+            [Cli.arguments(spec, rest), text || wait || LauncherOptions.settled?(launcher, spec), text]
           end
 
           # Whether the error is a wrapped tool's refusal. Matched by name: the adapters belong to
           # the
-          # Hecks chapter, which a client's runtime never loads.
+          # Hecks bluebook, which a client's runtime never loads.
           def tool_refusal?(error)
-            error.class.ancestors.map(&:name).include?(CliRunner::TOOL_REFUSAL)
+            ancestor_names = error.class.ancestors.map(&:name)
+            ancestor_names.include?(CliRunner::TOOL_REFUSAL)
+          end
+
+          # Answers `--plan`: a command's plan, or usage for a query, which writes nothing to plan.
+          # @api private
+          def plan_or_refuse(runtime, spec, invocation, name)
+            return plan_refused_for_query(name) if spec[:kind] == :query
+
+            plan_answer(runtime, spec, invocation)
+          end
+
+          # Lists what a command would write and announce, writing nothing. A refusal the real run
+          # would give is answered as that refusal.
+          # @api private
+          def plan_answer(runtime, spec, invocation)
+            lines = runtime.plan_flat(spec[:command], **normalized_request(spec, invocation.args))
+            [lines.empty? ? "would not write or announce anything" : lines.join("\n"), ExitStatus::ANSWERED]
+          rescue *Runtime::DOMAIN_REFUSALS, Runtime::NotFound, Runtime::TypeMismatch => e
+            [coded(e), ExitStatus::REFUSED]
+          end
+
+          # A query has nothing to write, so `--plan` on one is a usage mistake.
+          # @api private
+          def plan_refused_for_query(name)
+            ["hecks: #{name} is a query and writes nothing, so --plan has nothing to show", ExitStatus::USAGE]
           end
 
           # Runs a command and answers its outcome, settled when `--wait` asks for it.
           def run_command(runtime, spec, invocation)
-            args, minted = LauncherOptions.run_key(runtime, spec, invocation.args, invocation.launcher)
+            args, minted = RunReference.prepare(runtime, spec, invocation.args, invocation.launcher)
+            replayed = RunReplay.answer(runtime, spec, args)
+            return replayed if replayed
+
             handle = runtime.dispatch_flat(spec[:command], normalized_request(spec, args))
-            extra  = refusals_and_run(handle, minted)
-            return settled(runtime, spec, handle, invocation.bluebook, invocation.launcher, extra) if invocation.wait
+            extra  = refusals_and_run(handle, minted, args)
+            if invocation.wait
+              return settled(runtime, spec, handle, invocation.bluebook, invocation.launcher, extra, text: invocation.text)
+            end
 
-            [JSON.pretty_generate(outcome(handle, extra)), 0]
+            [JSON.pretty_generate(outcome(handle, extra)), ExitStatus::ANSWERED]
           end
 
           # The request a command takes from its parsed arguments.
@@ -65,8 +128,8 @@ module Hecks
           end
 
           # The refused reactions of the dispatch, led by the minted run key when one was.
-          def refusals_and_run(handle, minted)
-            extra = refused_answer(handle)
+          def refusals_and_run(handle, minted, args = {})
+            extra = refused_answer(handle).merge(ids: RunReference.ids(args, handle.id))
             minted ? { run: minted }.merge(extra) : extra
           end
 
@@ -80,16 +143,16 @@ module Hecks
           # Runs a question and answers its rows, or its text when an adapter answered in text.
           #
           # @param wait [Boolean, nil] whether `--wait` was given: a report naming a gap then fails
-          # @param launcher [Hash, nil] the chapter's `launcher` setting, which may name the
+          # @param launcher [Hash, nil] the bluebook's `launcher` setting, which may name the
           #   questions that refuse a run they do not hold
           # @return [Array(String, Integer)] the answer and the status
           def answer_query(runtime, spec, args, wait, launcher = nil)
-            rows = runtime.query(spec[:command], **args)
-            return [unknown_run(args), 1] if rows.empty? && LauncherOptions.unknown_run?(launcher, spec)
+            rows = runtime.query(spec[:command], **ReadContext.fill(spec, args))
+            return [unknown_run(args), ExitStatus::REFUSED] if rows.empty? && LauncherOptions.unknown_run?(launcher, spec)
 
             text = text_answer(spec, rows)
             [text || JSON.pretty_generate(rows.map { |row| Json.materialize(row) }),
-             wait && LauncherOptions.gap_reported?(text) ? 1 : 0]
+             wait && LauncherOptions.gap_reported?(text) ? ExitStatus::REFUSED : ExitStatus::ANSWERED]
           end
 
           # What a question about one run answers when the process holds no such run, for a
@@ -130,8 +193,7 @@ module Hecks
           # without this the answer would say nothing of it. A defect (a crash) is shown apart, as
           # `reaction_defects:`, and fails `--wait`.
           #
-          # @param handle [Runtime::Dispatcher::Result, Runtime::RemoteDispatcher::Result] the
-          #   outcome
+          # @param handle [Runtime::Dispatcher::Result, Adapters::Lambda::RemoteDispatcher::Result]
           # @return [Hash] `refused_reactions:` each with the `policy`, its `trigger`, the `reason`;
           #   empty when every reaction was delivered (or a remote host sent no per-step log), plus
           #   `reaction_defects:` when one crashed
@@ -144,8 +206,8 @@ module Hecks
 
           # Shapes a port operation's outcome, which has no state: each event with its full payload.
           #
-          # The answer lives only in the payloads, so names alone would drop it. Exit status stays 0
-          # for refusal events too, since a healthy no is an answer, not a misuse.
+          # The answer lives only in the payloads, so names alone would drop it. The status stays
+          # `ANSWERED` for refusal events too, since a healthy no is an answer, not a misuse.
           def answered(handle)
             # A port operation hydrates no instance, so the handle's `id` is nil by design.
             { id:     handle.id || handle.events.first&.id,

data/lib/hecks/adapters/driving/cli_runner/bang_rule.rb

@@ -0,0 +1,35 @@
+module Hecks
+  module Adapters
+    module Driving
+      module CliRunner
+        # The bang rule: a line that writes says so with `!`, and a command written without it is
+        # refused, naming the spelling that writes. Extended into `CliRunner`.
+        module BangRule
+          # The word a line names as typed, before the launcher's own rewrites.
+          def typed_word(argv)
+            CliRunner::QUERY_WORDS.include?(argv.first) ? argv[1] : argv.first
+          end
+
+          # The answer a line gets before any command runs: its help, or its refusal for a
+          # command written without its bang.
+          def early_answer(scope, cli, line)
+            return [command_help(scope, line[:name], line[:asking]), ExitStatus::ANSWERED] if line[:argv][1..].include?("--help")
+
+            bang_less_refusal(cli, line[:asking], line[:word], line[:name], scope[:program])
+          end
+
+          # A command written without its `!` is refused. A query, and a name that is not a
+          # command, pass.
+          #
+          # @return [Array(String, Integer), nil] the refusal and its usage status, or nil
+          def bang_less_refusal(cli, asking, word, name, program)
+            return nil if asking || word.nil? || word.end_with?("!")
+            return nil unless cli[:names][:command].key?(name)
+
+            ["#{program}: #{word} is a command and writes; write it as #{word}!", ExitStatus::USAGE]
+          end
+        end
+      end
+    end
+  end
+end