hecks 3.0.4 → 3.1.0

data/lib/hecks/cli/spec_example.rb

@@ -5,7 +5,7 @@ require "rspec/core"
 module Hecks
   module CLI
     # The command behind `hecks run_spec_example`: runs one spec file filtered to one example
-    # through `RSpec::Core::Runner`, so a `hecks quality_control log --demonstration` string
+    # through `RSpec::Core::Runner`, so a `hecks quality_control bug.log --demonstration` string
     # needs no `-e` quoting.
     module SpecExample
       USAGE = "usage: hecks run_spec_example <spec_file> <example description substring>"

data/lib/hecks/cli/stress_concurrency_specs.rb

@@ -31,9 +31,8 @@ module Hecks
       USAGE = <<~TEXT
         Usage: hecks stress_concurrency [--runs N] [--parallel N] [--seed-start N]
 
-          --runs N        How many times to run EACH group below (default 30).
-                           Each run uses a different --seed (seed-start + run
-                           index).
+          --runs N        How many times to run EACH group below. Each run uses
+                           a different --seed (seed-start + run index).
           --parallel N    How many parallel-safe-group runs to have going as
                            separate OS processes AT THE SAME TIME (default: this
                            machine's own core count, via Etc.nprocessors) — real
@@ -41,9 +40,12 @@ module Hecks
                            seeds one after another. The Postgres-backed group
                            always runs one process at a time regardless of this
                            flag.
-          --seed-start N  First --seed value (default 1); runs use seed_start,
+          --seed-start N  First --seed value; runs use seed_start,
                            seed_start + 1, ... seed_start + runs - 1.
 
+        `hecks stress_concurrency` fills --runs and --seed-start from the defaults its
+        bluebook declares (`hecks stress_concurrency --help` shows them).
+
         Exits 0 if every run's every example passed, 1 if anything failed -
         failing runs' full output is saved under tmp/stress-failures/
         for a real repro (same seed, same command, just add CI=true).
@@ -60,10 +62,17 @@ module Hecks
       #   unknown argument
       def call(argv, root:, out: $stdout)
         argv = argv.dup
-        settings = { runs: 30, parallel: Etc.nprocessors, seed_start: 1 }
+        settings = { parallel: Etc.nprocessors }
         status = parse!(argv, settings, out)
         return status if status
 
+        missing = %i[runs seed_start].reject { |name| settings.key?(name) }
+        unless missing.empty?
+          warn "missing #{missing.map { |name| "--#{name.to_s.tr('_', '-')}" }.join(', ')}: " \
+               "`hecks stress_concurrency` supplies the defaults its bluebook declares (--help for usage)"
+          return 64
+        end
+
         results = run_all(root, settings, out)
         report(root, results, out)
       end

data/lib/hecks/corpus.rb

@@ -17,7 +17,7 @@ module Hecks
       # The Hecks domain (ADR 0080): its chapters share one namespace and one hecksagon, so
       # they load together, as a directory, never file by file.
       hecks:     "lib/hecks/hecks",
-      # A package vendored via `uses_embryonaut_bluebook` — nested inside the
+      # A package vendored via `attaches ... from: :vendor` — nested inside the
       # consuming example's own checkout, not this gem's own framework/bluebook/.
       vendored:  "examples/*/vendor/embryonaut_bluebooks/*"
     }.freeze
@@ -31,7 +31,9 @@ module Hecks
       qa:        "lib/hecks/quality_control/*.bluebook",
       language:  "lib/hecks/language/**/*.bluebook",
       deploy:    "lib/hecks/deploy/bluebook/*.bluebook",
+      site:      "lib/hecks/site/bluebook/*.bluebook",
       tenancy:   "lib/hecks/tenancy/bluebook/*.bluebook",
+      sme:       "lib/hecks/sme/bluebook/*.bluebook",
       fixture:   "spec/fixtures/**/*.bluebook"
     }.freeze
 
@@ -232,14 +234,14 @@ module Hecks
     Elsewhere = Struct.new(:check, :destination, :names, :why)
 
     RUST_ELSEWHERE = {
-      "meta" => Elsewhere.new(:named_in, "spec/codegen_parity_spec.rb", "bluebook_language",
+      "meta" => Elsewhere.new(:named_in, "lib/hecks/tools/regeneration_run.rb", "rust/src/generated",
                               "the self-hosted grammar (lib/hecks/language), not a domain directory — every " \
-                              "hecks project_rust run rewrites it (so the drift check diffs it), codegen parity " \
-                              "checks it as bluebook_language, and there is no directory to fuzz")
+                              "hecks project_rust run rewrites it, so the drift check diffs it with the rest " \
+                              "of rust/src/generated, and there is no directory to fuzz")
     }.freeze
 
-    # Every place a Rust-facing domain's own `uses_framework`/
-    # `uses_embryonaut_bluebook` attachment could be declared.
+    # Every place a Rust-facing domain's own `attaches` (or the deprecated `uses_framework` /
+    # `uses_embryonaut_bluebook`) attachment could be declared.
     #
     # @param root [String] repository root to search under
     # @return [String] every reachable hecksagon file's own text, joined by newlines
@@ -307,10 +309,11 @@ module Hecks
 
     # The stamp hecks project_rust writes into metadata.rs, e.g.
     # `examples/pizzas` or `the self-hosted language (...)`, with any
-    # ` (uses_framework "X")`/` (uses_embryonaut_bluebook "X")` suffix stripped.
+    # ` (attaches "X")`/` (attaches "x", from: :vendor)` suffix stripped (the deprecated
+    # `uses_framework` / `uses_embryonaut_bluebook` spellings too).
     SOURCE_STAMP = /
       GENERATED\ by\ hecks\ project_rust\ —\ (.+?)
-      (?:\ \((?:uses_framework|uses_embryonaut_bluebook)\ "\w+"\))?
+      (?:\ \((?:attaches|uses_framework|uses_embryonaut_bluebook)\ "\w+"(?:,\ from:\ :vendor)?\))?
       's\ own\ canonical\ IR,
     /x
 

data/lib/hecks/deploy/bluebook/deploy.bluebook

@@ -1,7 +1,7 @@
 # The Deploy chapter: what `deployed_to(...)` may declare, and the commands that generate, check and
 # compare a deploy recipe, project the OIDC manifests and provision a tenant.
 #
-# `hecks deploy project` and `hecks deploy provision` boot it directly; the Hecks domain attaches it, so
+# `hecks deploy recipe.project` and `hecks deploy tenant.provision` boot it directly; the Hecks domain attaches it, so
 # each command below is also `hecks deploy <verb>`. The targets validate the `deployed_to` shape
 # that `world.bluebook`'s untyped `Setting` map leaves open. Each run below records that it was
 # requested before its DeployToolchain port is asked, and what came of it after. No command
@@ -10,7 +10,7 @@ Hecks.bluebook "Deploy" do
   vision "Generate, check and compare deploy recipes, project OIDC manifests and provision tenants."
 
   aggregate "LambdaTarget" do
-    description "One domain's validated AWS Lambda deploy target — what deployed_to(\"AwsLambda\") must resolve to before hecks deploy project generates anything from it."
+    description "One domain's validated AWS Lambda deploy target — what deployed_to(\"AwsLambda\") must resolve to before hecks deploy recipe.project generates anything from it."
 
     identified_by :domain
 
@@ -38,14 +38,14 @@ Hecks.bluebook "Deploy" do
     # (Serverless v2);
     # only the emitted CloudFormation resource differs, never the runtime adapter. "Shared" borrows
     # another domain's instance under its own Postgres schema and needs an `owner` setting, which
-    # `hecks deploy project` checks, since the owning domain is a deploy-time fact.
+    # `hecks deploy recipe.project` checks, since the owning domain is a deploy-time fact.
     value_object "Database" do
       attribute :value, String, one_of: ["Postgres", "Aurora", "Shared"]
     end
 
     # "None" (default) or "Rust": the domain's own Lambda (rust/host) also serves a public web UI
     # in-process (rust/host/src/web.rs). "Ruby" is not a member: a Ruby WebFunction comes from a
-    # `lambda_handler.rb` file, and `hecks deploy project` refuses `web "Rust"` alongside one.
+    # `lambda_handler.rb` file, and `hecks deploy recipe.project` refuses `web "Rust"` alongside one.
     value_object "Web" do
       attribute :value, String, one_of: ["None", "Rust"]
     end
@@ -87,7 +87,7 @@ Hecks.bluebook "Deploy" do
 
     # All required, no `default:`: command-level defaults apply only at the JSON/Rust-codegen
     # boundary, not Ruby's direct dispatch (interpreting.rb `normalize_args`). Defaults are
-    # resolved by `hecks deploy project` before it dispatches.
+    # resolved by `hecks deploy recipe.project` before it dispatches.
     command "Declare" do
       goal "Validate one domain's AwsLambda deploy target before anything is generated from it"
 
@@ -122,7 +122,7 @@ Hecks.bluebook "Deploy" do
   # A sibling of `LambdaTarget` with its own value objects, since value objects are not
   # shared across aggregates.
   aggregate "FargateTarget" do
-    description "One domain's validated AWS Fargate deploy target — what deployed_to(\"AwsFargate\") must resolve to before hecks deploy project generates anything from it."
+    description "One domain's validated AWS Fargate deploy target — what deployed_to(\"AwsFargate\") must resolve to before hecks deploy recipe.project generates anything from it."
 
     identified_by :domain
 
@@ -177,7 +177,7 @@ Hecks.bluebook "Deploy" do
     end
 
     # All seven required for the same reason as `LambdaTarget.Declare`; this validates a
-    # target already resolved by `hecks deploy project`'s defaults.
+    # target already resolved by `hecks deploy recipe.project`'s defaults.
     command "Declare" do
       goal "Validate one domain's AwsFargate deploy target before anything is generated from it"
 
@@ -201,10 +201,83 @@ Hecks.bluebook "Deploy" do
     end
   end
 
-  # The validated shape of `hecks deploy provision`, which does the generating and provisioning.
+  aggregate "BoxTarget" do
+    description "One domain's validated single-box deploy target — what deployed_to(\"AwsBox\") must resolve to before hecks deploy project generates a box and an RDS instance from it"
+
+    identified_by :domain
+
+    attribute :domain,         DomainName
+    attribute :region,         Region
+    attribute :instance_type,  InstanceType
+    attribute :volume_gb,      VolumeGb
+    attribute :database_class, DatabaseClass
+    attribute :storage_gb,     StorageGb
+
+    value_object "DomainName" do
+      attribute :value, String
+      invariant("a domain is named") { !value.to_s.empty? }
+    end
+
+    value_object "Region" do
+      attribute :value, String
+      invariant("a region is named") { !value.to_s.empty? }
+    end
+
+    # An EC2 instance type such as t4g.medium. The family and size are checked for shape only;
+    # EC2 refuses an unknown type at stack creation.
+    value_object "InstanceType" do
+      attribute :value, String
+      invariant("an instance type is family.size, such as t4g.medium") { value.to_s.match?(/\A[a-z][a-z0-9-]*\.[a-z0-9]+\z/) }
+    end
+
+    # The box's root disk, which holds images, the compose files and container logs; the
+    # database is on RDS.
+    value_object "VolumeGb" do
+      attribute :value, Integer
+      invariant("a volume is at least 8 GB") { value >= 8 }
+      invariant("a volume is at most 16384 GB") { value <= 16384 }
+    end
+
+    # An RDS instance class such as db.t4g.small.
+    value_object "DatabaseClass" do
+      attribute :value, String
+      invariant("a database class is db.family.size, such as db.t4g.small") { value.to_s.match?(/\Adb\.[a-z][a-z0-9-]*\.[a-z0-9]+\z/) }
+    end
+
+    # RDS storage grows with the journal; 20 GB is RDS's gp3 floor.
+    value_object "StorageGb" do
+      attribute :value, Integer
+      invariant("storage is at least 20 GB") { value >= 20 }
+      invariant("storage is at most 65536 GB") { value <= 65536 }
+    end
+
+    # All six required for the same reason as `FargateTarget.Declare`; this validates a target
+    # already resolved by `hecks deploy project`'s defaults.
+    command "Declare" do
+      goal "Validate one domain's AwsBox deploy target before anything is generated from it"
+
+      attribute :domain,         DomainName
+      attribute :region,         Region
+      attribute :instance_type,  InstanceType
+      attribute :volume_gb,      VolumeGb
+      attribute :database_class, DatabaseClass
+      attribute :storage_gb,     StorageGb
+
+      sets :domain
+      sets :region
+      sets :instance_type
+      sets :volume_gb
+      sets :database_class
+      sets :storage_gb
+
+      emits "BoxTargetDeclared"
+    end
+  end
+
+  # The validated shape of `hecks deploy tenant.provision`, which does the generating and provisioning.
   # Not a saga: each of its steps is idempotent and local, so there is nothing to resume.
   aggregate "Tenant" do
-    description "One tenant's validated identity — which realm and Postgres schema `hecks deploy provision` provisions before booting a domain directory under Runtime.boot's own `environment:` overlay for it."
+    description "One tenant's validated identity — which realm and Postgres schema `hecks deploy tenant.provision` provisions before booting a domain directory under Runtime.boot's own `environment:` overlay for it."
 
     identified_by :slug
 
@@ -268,7 +341,7 @@ Hecks.bluebook "Deploy" do
       transition "Abandon"     => "refused",     from: "requested"
     end
 
-    # `hecks deploy provision <directory> slug=s domain= realm= schema= database= [adapter=]`.
+    # `hecks deploy tenant.provision <directory> slug=s domain= realm= schema= database= [adapter=]`.
     # The only command that creates a tenant: its slug, schema and realm are validated by the value
     # objects' patterns and invariants, then the overlay is written through the TenantProvisioning
     # port; the adapter answers PostgresEra when `adapter` is left out. `dry_run?` on this verb
@@ -424,7 +497,7 @@ Hecks.bluebook "Deploy" do
       transition "Fault"    => "faulted",   from: "requested"
     end
 
-    # `hecks deploy project <domain> [tenant=] [schema=] [out=] [environment=]`. A schema override
+    # `hecks deploy recipe.project <domain> [tenant=] [schema=] [out=] [environment=]`. A schema override
     # needs its tenant; the generator says so, and a domain with no `deployed_to` target, or one
     # whose settings conflict, is faulted with the generator's own sentence.
     command "Project" do
@@ -630,7 +703,7 @@ Hecks.bluebook "Deploy" do
       transition "Refuse" => "refused",  from: "requested"
     end
 
-    # `hecks deploy diff <before> after=<template> [--json] [--strict]`. `--strict` also counts
+    # `hecks deploy template_comparison.diff <before> after=<template> [--json] [--strict]`. `--strict` also counts
     # cosmetic differences (comments, key order); `--json` writes the report as JSON.
     command "Diff" do
       goal "Compare two CloudFormation templates and report what differs by logical id"

data/lib/hecks/deploy/oidc.json

@@ -1,6 +1,11 @@
 {
   "audience": "Deploy",
   "scopes": [
+    {
+      "scope": "deploy:box_target.declare",
+      "verb": "Deploy::BoxTarget.Declare",
+      "role": null
+    },
     {
       "scope": "deploy:fargate_target.declare",
       "verb": "Deploy::FargateTarget.Declare",

data/lib/hecks/doc/reference.rb

@@ -4,7 +4,8 @@ require_relative "../naming"
 module Hecks
   module Doc
     # The DSL reference, projected from the language's own Syntax chapter so
-    # its tables can never drift from the live builders. Regenerate with `hecks project_reference`.
+    # its tables can never drift from the live builders. Regenerate with
+    # `hecks language_run.project_reference`.
     module Reference
       GENERATED_END = "<!-- generated:end -->".freeze
       TODO_SENTINEL = "<!-- TODO: document this word -->".freeze
@@ -84,7 +85,7 @@ module Hecks
 
           *The tables on this page are generated from the language's own
           aggregate-local syntax tables (`lib/hecks/language/**/*.bluebook`)
-          by `hecks project_reference` — do not edit inside the markers. The prose
+          by `hecks language_run.project_reference` — do not edit inside the markers. The prose
           between them is hand-written and survives regeneration.*
           #{GENERATED_END}
           #{"\n#{preamble}\n" unless preamble.empty?}
@@ -172,7 +173,7 @@ module Hecks
           # The DSL reference
 
           One page per context — the place in a file where a word may be
-          typed. Generated by `hecks project_reference` from the Syntax chapter;
+          typed. Generated by `hecks language_run.project_reference` from the Syntax chapter;
           the prose between the generated markers is hand-written and
           survives regeneration.
 

data/lib/hecks/doors/cli_door.rb

@@ -11,17 +11,17 @@ module Hecks
 
       module_function
 
-      # Builds a verb's nested, typed argument Hash from its `name=value` words.
+      # Builds a command's nested, typed argument Hash from its `name=value` words.
       #
       #   arguments(spec, ["reference.value=A-1", "sequence.value=99"])
       #   # => { reference: { value: "A-1" }, sequence: { value: 99 } }
       #
-      # @param spec [Hash{Symbol => Object}] one verb's entry from `Projector::CliProjector`
-      # @param pairs [Array<String>] the words after the verb: `name=value` pairs, where a path may
-      #   be the short form of a single-field value object (`reference` for `reference.value`);
-      #   `--name` for a Boolean; and at most one bare word, which fills the verb's first argument
+      # @param spec [Hash{Symbol => Object}] one command's entry from `Projector::CliProjector`
+      # @param pairs [Array<String>] the words after the command: `name=value` pairs, where a path
+      #   may be the short form of a single-field value object (`reference` for `reference.value`);
+      #   `--name` for a Boolean; and at most one bare word, which fills the first argument
       # @return [Hash{Symbol => Object}] the arguments nested by path, leaves cast to type
-      # @raise [Runtime::NotFound] if a path, flag or bare word does not fit the verb
+      # @raise [Runtime::NotFound] if a path, flag or bare word does not fit the command
       # @raise [Runtime::TypeMismatch] if a value does not parse as its Integer or Float
       def arguments(spec, pairs)
         # Extra accepted arguments stay out of help, which teaches only to=....
@@ -44,7 +44,7 @@ module Hecks
 
       # Rewrites the short forms into `name=value`: `--name` for a Boolean (a following `yes`,
       # `no`, `true`, `false`, `on`, `off`, `1` or `0` is that flag's value, not an argument),
-      # `--name=value` as `name=value`, and one bare word as the verb's first argument (`to` for
+      # `--name=value` as `name=value`, and one bare word as the command's first argument (`to` for
       # a command on an existing aggregate, the first attribute for one that creates).
       def normalize(spec, words, options)
         queue = words.dup
@@ -84,20 +84,20 @@ module Hecks
         path = options.key?(name) ? name : expand(name, options)
         return path if options.dig(path, :type) == "Boolean"
 
-        raise Runtime::NotFound, "--#{name} is a flag, but this verb has no Boolean argument #{name.inspect}"
+        raise Runtime::NotFound, "--#{name} is a flag, but this command has no Boolean argument #{name.inspect}"
       end
 
-      # The one bare word, as a pair for the verb's first argument the launcher does not mint.
+      # The one bare word, as a pair for the command's first argument the launcher does not mint.
       def positional(word, spec)
         first = spec[:arguments].find { |argument| !argument[:minted] }
         return "#{first[:path]}=#{word}" if first
 
         if spec[:arguments].any?
-          raise Runtime::NotFound, "#{word.inspect} is not name=value; this verb's only argument is its run key, " \
+          raise Runtime::NotFound, "#{word.inspect} is not name=value; this command's only argument is its run key, " \
                                    "which is minted when omitted (run=<key> names one)"
         end
 
-        raise Runtime::NotFound, "#{word.inspect} is not name=value, and this verb takes no arguments"
+        raise Runtime::NotFound, "#{word.inspect} is not name=value, and this command takes no arguments"
       end
 
       # Words the refusal for more than one unnamed argument.
@@ -187,9 +187,9 @@ module Hecks
         hash
       end
 
-      # Words the refusal for an argument the verb does not take, listing what it does.
+      # Words the refusal for an argument the command does not take, listing what it does.
       def unknown(path, known)
-        "no argument #{path.inspect} — this verb takes #{known.sort.join(', ')}"
+        "no argument #{path.inspect} — this command takes #{known.sort.join(', ')}"
       end
     end
   end

data/lib/hecks/doors/cli_runner.rb

@@ -13,6 +13,8 @@ module Hecks
     module CliRunner
       # The class an adapter raises when the tool it wraps refuses.
       TOOL_REFUSAL = "Hecks::Adapters::ConsoleCapture::Failure".freeze
+      # The words that open the query namespace; `ask` is the older spelling.
+      QUERY_WORDS = %w[query ask].freeze
 
       module_function
 
@@ -20,7 +22,7 @@ module Hecks
       # The booted domain's own chapter is projected, or an attached one its first word names.
       #
       # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
-      # @param argv [Array<String>] an optional `ask`, the verb or question name, then
+      # @param argv [Array<String>] an optional `query` (or `ask`), the command or query name, then
       #   `path=value` pairs; `--help`, `-h`, `help` or nothing answers usage
       # @param program [String] how the caller was invoked, echoed in usage and hints
       # @return [Array(String, Integer)] the text and the status: 0 answered, 1 refused or misused
@@ -71,7 +73,7 @@ module Hecks
         cursor = nil
         loop do
           ask  = cursor ? args.except(:from_now).merge(since: { value: cursor }) : args
-          rows = runtime.query(spec[:verb], **ask)
+          rows = runtime.query(spec[:command], **ask)
           row  = rows.first || {}
           Array(row[:events]).each { |event| out.puts(JSON.generate(entry_line(JsonDoor.materialize(event)))) }
           out.flush
@@ -93,23 +95,23 @@ module Hecks
       # Answers a command line that asks only for usage, from the projection alone.
       #
       # Needs a registry and no bound adapter, so a `Runtime::Loader::Described` serves: the
-      # help text, the no-argument usage, a verb's `--help` and an unknown verb's hint all come
+      # help text, the no-argument usage, a command's `--help` and an unknown one's hint all come
       # out byte-identical to `call`'s.
       #
       # @param runtime [#registry] a booted domain, or what `Hecks.describe` answers
       # @param argv [Array<String>] as for `call`
       # @param program [String] how the caller was invoked
       # @return [Array(String, Integer), nil] the text and status, or nil when the line would
-      #   run a verb or question and so needs a booted domain
+      #   run a command or question and so needs a booted domain
       def usage(runtime:, argv:, program: "hecks run")
         resolve(runtime, argv, program)[:answer]
       end
 
       # Parses a command line against the projection: either the answer it gives without
-      # running anything, or the verb it would run.
+      # running anything, or the command it would run.
       #
       # @return [Hash] `{answer: [text, status]}`, or `{spec:, name:, rest:, asking:, program:,
-      #   bluebook:, launcher:}` for a verb to dispatch
+      #   bluebook:, launcher:}` for a command to dispatch
       def resolve(runtime, argv, program)
         bluebook, argv, program = chapter_for(runtime, argv, program)
         launcher = LauncherOptions.settings(runtime, bluebook.name)
@@ -119,18 +121,11 @@ module Hecks
         name = argv.first
         return { answer: [cli[:usage], 0] } if name.nil? || %w[--help -h help].include?(name)
 
-        # `ask` gives questions their own namespace; a chapter may declare a command and query
-        # of one name.
-        asking = name == "ask"
-        argv   = argv[1..] if asking
-        name   = argv.first
+        asking, name, argv = entry_word(cli, argv)
         return { answer: [cli[:usage], 1] } if name.nil?
 
-        # A question answers to its bare name too; `ask` is needed only when a command shares it.
-        asking ||= !cli[:names][:command].key?(name) && cli[:names][:question].key?(name)
-
-        # The alias map lets `create_pizza` and `order.create_pizza` reach the same verb.
-        pool = asking ? cli[:questions] : cli[:verbs]
+        # The alias map lets `create_pizza` and `order.create_pizza` reach the same command.
+        pool = asking ? cli[:questions] : cli[:commands]
         key  = cli[:names][asking ? :question : :command][name]
         spec = pool[key]
         return { answer: [unknown(cli, name, asking, program), 1] } unless spec
@@ -138,7 +133,7 @@ module Hecks
         rest = argv[1..]
         if rest.include?("--help")
           help = Projector.call(:cli, bluebook: bluebook,
-                                      options:  options.merge(verb: name, ask: asking))[:usage]
+                                      options:  options.merge(command: name, ask: asking))[:usage]
           return { answer: [help, 0] }
         end
 
@@ -146,6 +141,27 @@ module Hecks
           launcher: launcher }
       end
 
+      # Reads the entry words of a line: whether it asks a query, the bare name, and the words
+      # from the name on.
+      #
+      # `query` gives queries their own namespace (`ask` is its older spelling); a chapter may
+      # declare a command and a query of one name. A trailing `!` says the word is a command and
+      # is not part of the name. A query answers to its bare name too; `query` is needed only when
+      # a command shares it.
+      #
+      # @return [Array(Boolean, String, Array<String>)] `asking`, `name` (nil when absent), `argv`
+      def entry_word(cli, argv)
+        asking = QUERY_WORDS.include?(argv.first)
+        argv   = argv[1..] if asking
+        name   = argv.first
+        return [asking, nil, argv] if name.nil?
+
+        bang = name.end_with?("!")
+        name = name.chomp("!") if bang
+        asking ||= !bang && !cli[:names][:command].key?(name) && cli[:names][:question].key?(name)
+        [asking, name, argv]
+      end
+
       # The chapter a command line speaks to: the booted domain's own, or, when the first word
       # names a chapter its hecksagon attaches or uses as a framework member (`deploy`,
       # `governance`), that chapter, with the word dropped and added to the program name.
@@ -158,11 +174,11 @@ module Hecks
         [runtime.registry.bluebook(target), argv[1..], "#{program} #{argv.first}"]
       end
 
-      # Parses one resolved verb's arguments, runs it as a query or command, and turns the
+      # 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.
       #
-      # @param bluebook [Bluebook::Chapter] the chapter the verb belongs to
+      # @param bluebook [Bluebook::Chapter] the chapter the command belongs to
       # @param launcher [Hash, nil] the chapter's `launcher` world setting; nil when not opted in
       def dispatch(runtime, spec, name, rest, program, asking, bluebook: nil, launcher: nil)
         rest, wait = LauncherOptions.take_wait(spec, rest) if launcher
@@ -171,10 +187,10 @@ module Hecks
         return answer_query(runtime, spec, args, wait) if spec[:kind] == :query
 
         args, minted = LauncherOptions.run_key(runtime, spec, args, launcher)
-        # Answers with only this verb's outcome; a full store dump is every record there is.
+        # Answers with only this command's outcome; a full store dump is every record there is.
         request = CommandRequest.normalize(args, receiver:        spec[:receiver],
                                                  legacy_receiver: spec[:legacy_receiver])
-        handle = runtime.dispatch_flat(spec[:verb], request)
+        handle = runtime.dispatch_flat(spec[:command], request)
         extra  = refused_answer(handle)
         extra  = { run: minted }.merge(extra) if minted
         return settled(runtime, spec, handle, bluebook, launcher, extra) if wait
@@ -185,7 +201,7 @@ module Hecks
                                 events: handle.events.map(&:name) }.merge(extra)), 0]
       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} #{'ask ' if asking}#{name} --help", 1]
+        ["#{e.message}\n\n  #{program} #{'query ' if asking}#{name} --help", 1]
       rescue *Runtime::DOMAIN_REFUSALS => e
         # The refusal is the chapter's own sentence, verbatim.
         [e.message, 1]
@@ -202,7 +218,7 @@ module Hecks
       # @param wait [Boolean, nil] whether `--wait` was given: a report naming a gap then fails
       # @return [Array(String, Integer)] the answer and the status
       def answer_query(runtime, spec, args, wait)
-        rows = runtime.query(spec[:verb], **args)
+        rows = runtime.query(spec[:command], **args)
         text = text_answer(spec, rows)
         [text || JSON.pretty_generate(rows.map { |row| JsonDoor.materialize(row) }),
          wait && LauncherOptions.gap_reported?(text) ? 1 : 0]
@@ -256,7 +272,7 @@ module Hecks
 
       # The aggregate a top-level command belongs to; nil for an entity command or a port.
       def aggregate_of(bluebook, spec)
-        head = spec[:verb].split("::", 2).last
+        head = spec[:command].split("::", 2).last
         return if head.count(".") != 1
 
         bluebook.aggregates.find { |aggregate| aggregate.hecks_name == head.split(".").first }
@@ -317,19 +333,23 @@ module Hecks
           end }
       end
 
-      # Words the answer for an unknown verb or question, suggesting up to five near names.
+      # Words the answer for an unknown command or question, suggesting up to five near names.
       # Ranked by shared prefix, which survives a dropped letter where a substring match would not.
       def unknown(cli, name, asking, program)
         # Both spellings are candidates: `order.create_piza` shares no prefix with `create_pizza`.
         pool = cli[:names][asking ? :question : :command].keys
-        near = pool.map    { |candidate| [shared_prefix(candidate, name), candidate] }
-                   .select { |shared, _| shared >= [name.length / 2, 3].max }
-                   .sort_by { |shared, candidate| [-shared, candidate] }
-                   .map(&:last)
-
-        lines = ["no such #{asking ? 'question' : 'verb'}: #{name}"]
+        # A bare name is the commonest slip now that the aggregate is required: its homes first.
+        homes = (pool + cli[:names][asking ? :command : :question].keys)
+                .select { |candidate| candidate.split(".").last == name }.uniq
+        similar = pool.map { |candidate| [shared_prefix(candidate, name), candidate] }
+                      .select { |shared, _| shared >= [name.length / 2, 3].max }
+                      .sort_by { |shared, candidate| [-shared, candidate] }
+                      .map(&:last)
+        near = homes + (similar - homes)
+
+        lines = ["no such #{asking ? 'query' : 'command'}: #{name}"]
         lines += ["", "did you mean:", *near.first(5).map { |candidate| "  #{candidate}" }] unless near.empty?
-        lines += ["", "  #{program}#{' ask' if asking}   for the full list"]
+        lines += ["", "  #{program}#{' query' if asking}   for the full list"]
         lines.join("\n")
       end
 

data/lib/hecks/doors/launcher_options.rb

@@ -1,3 +1,4 @@
+require "stringio"
 require_relative "../ports/identity_generation"
 require_relative "../runtime/errors"
 require_relative "cli_door"
@@ -46,13 +47,30 @@ module Hecks
         { program: program, names: settings && settings[:names], mint_run_keys: settings && settings[:run_keys] }
       end
 
-      # Takes `--wait` out of a verb's words, unless the verb declares a `wait` argument of its own.
+      # Runs the block with standard error held back, so the wiring notes hecks prints about its own
+      # chapters (a Memory journal loses sagas on restart) do not open a console session. They are
+      # for an operator running a stored journal. A raised error still surfaces, unchanged.
+      #
+      # @param hold [Boolean] whether to hold standard error back; false runs the block as it is
+      # @yield the boot
+      # @return [Object] the block's value
+      def quietly(hold: true)
+        return yield unless hold
+
+        shown = $stderr
+        $stderr = StringIO.new
+        yield
+      ensure
+        $stderr = shown if hold
+      end
+
+      # Takes `--wait` out of a command's words, unless it declares a `wait` argument of its own.
       #
       # `--wait=false` (or `no`, `0`, `off`) is a `--wait` that was switched off; a bare `--wait`
       # may be followed by its Boolean word.
       #
-      # @param spec [Hash] the verb's projected spec
-      # @param words [Array<String>] the words after the verb
+      # @param spec [Hash] the command's projected spec
+      # @param words [Array<String>] the words after the command
       # @return [Array(Array<String>, Boolean)] the remaining words, and whether `--wait` was given
       # @raise [Runtime::TypeMismatch] if `--wait=` carries something that is not a Boolean word
       def take_wait(spec, words)
@@ -78,7 +96,7 @@ module Hecks
       def streams?(launcher, spec)
         return false unless launcher && spec[:kind] == :query
 
-        Array(launcher[:streams]).map(&:to_s).include?(spec[:verb].to_s.split(/[.:]+/).last)
+        Array(launcher[:streams]).map(&:to_s).include?(spec[:command].to_s.split(/[.:]+/).last)
       end
 
       # Takes `--stream` out of a question's words.
@@ -119,7 +137,7 @@ module Hecks
       # rather than sent on without one.
       #
       # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
-      # @param spec [Hash] the verb's projected spec
+      # @param spec [Hash] the command's projected spec
       # @param args [Hash] the parsed arguments
       # @param settings [Hash, nil] the chapter's `launcher` setting
       # @return [Array(Hash, String)] the arguments, and the key minted (nil when none was)