hecks 3.0.5 → 3.1.0

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

@@ -64,13 +64,13 @@ module Hecks
         $stderr = shown if hold
       end
 
-      # Takes `--wait` out of a verb's words, unless the verb declares a `wait` argument of its own.
+      # 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)
@@ -96,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.
@@ -137,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)

data/lib/hecks/doors/mcp_door.rb

@@ -266,30 +266,28 @@ module Hecks
         end
       end
 
-      # `domain:` is confined to `Storehouse::BOOT_ROOT`, and further to a reader
-      # door's `HECKS_DOOR_DOMAINS`, before anything boots.
+      # `domain:` is confined to `Storehouse::BOOT_ROOT`, and further to a restricted
+      # door's `HECKS_DOOR_DOMAINS`, before anything boots. An unrestricted door boots the
+      # domain afresh on every call; a restricted door lives for one spawner's session and
+      # keeps each named domain booted until the files of its directory change.
       def boot(domain)
-        Hecks.boot(Storehouse.confine!(scope.admit_domain!(domain), "domain"), install_doors: false)
+        path = Storehouse.confine!(scope.admit_domain!(domain), "domain")
+        return Hecks.boot(path, install_doors: false) unless scope.restricted?
+
+        resident = (@resident ||= {})
+        fingerprint = Storehouse.fingerprint(path)
+        return resident[path][:runtime] if resident[path] && resident[path][:fingerprint] == fingerprint
+
+        resident[path] = { fingerprint: fingerprint, runtime: Hecks.boot(path, install_doors: false) }
+        resident[path][:runtime]
       end
 
       # One `when` per tool, so the shared `rescue` catches every branch's escape
       # once; a domain refusal is already `{ok: false, ...}` from `Storehouse`.
       def call_tool(name, args) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
         case name
-        when "dispatch"
-          runtime = boot(args["domain"])
-          if args["steps"]
-            Storehouse.dispatch_batch(runtime: runtime, steps: args["steps"], summary: args["summary"],
-                                      source: args["source"], role: args["role"], actor_id: args["actor_id"])
-          else
-            Storehouse.dispatch(runtime: runtime, command: args["command"], summary: args["summary"],
-                                args: args["args"] || {}, source: args["source"],
-                                dry_run: args["dry_run"] == true, role: args["role"], actor_id: args["actor_id"])
-          end
-        when "query"
-          Storehouse.query(runtime: boot(args["domain"]), question: args["question"],
-                           summary: args["summary"], args: args["args"] || {}, source: args["source"],
-                           role: args["role"], actor_id: args["actor_id"])
+        when "dispatch" then dispatch_tool(args)
+        when "query" then query_tool(args)
         when "events"
           Storehouse.events(runtime: boot(args["domain"]), aggregate: args["aggregate"], id: args["id"],
                             limit: args["limit"])
@@ -319,6 +317,29 @@ module Hecks
         { ok: false, error: "#{e.class}: #{e.message}" }
       end
 
+      # A question, once the scope has admitted its arguments.
+      def query_tool(args)
+        scope.admit_arguments!(args["args"])
+        Storehouse.query(runtime: boot(args["domain"]), question: args["question"],
+                         summary: args["summary"], args: args["args"] || {}, source: args["source"],
+                         role: args["role"], actor_id: args["actor_id"])
+      end
+
+      # A single command or a batch, once the scope has admitted every command in it.
+      def dispatch_tool(args)
+        runtime = boot(args["domain"])
+        if args["steps"]
+          scope.admit_steps!(runtime, args["steps"])
+          Storehouse.dispatch_batch(runtime: runtime, steps: args["steps"], summary: args["summary"],
+                                    source: args["source"], role: args["role"], actor_id: args["actor_id"])
+        else
+          scope.admit_command!(runtime, args["command"], args["args"])
+          Storehouse.dispatch(runtime: runtime, command: args["command"], summary: args["summary"],
+                              args: args["args"] || {}, source: args["source"],
+                              dry_run: args["dry_run"] == true, role: args["role"], actor_id: args["actor_id"])
+        end
+      end
+
       def answer_tool(name, args)
         return scope.refusal(name) unless scope.permits_tool?(name)
 
@@ -352,7 +373,8 @@ module Hecks
         when "notifications/initialized"
           nil # a notification — no id, no response
         when "tools/list"
-          send_response(id, { tools: TOOLS.select { |tool| scope.permits_tool?(tool[:name]) } })
+          served = TOOLS.select { |tool| scope.permits_tool?(tool[:name]) }
+          send_response(id, { tools: served.map { |tool| scope.present(tool) } })
         when "tools/call"
           send_response(id, tool_result(answer_tool(params["name"], params["arguments"] || {})))
         when "ping"