hecks 3.2.0 → 3.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c79ef6cb53e23b9faa0f452f116af208c659512f00716e47c7f3cdaad3d51e86
-  data.tar.gz: b693ea21f847607ca2964759f9e0cec9dc7c4f8e1ea341b6636e99f8b4b1d294
+  metadata.gz: 9b963870a34a1483bc0156042a2967a72f8fc1b8e907ba5d8cac5a5382d4999d
+  data.tar.gz: 26697af02778cda282a44c1ca099e36a9866bf2d204ab5abb23df8ac2a86283a
 SHA512:
-  metadata.gz: 38d1467d95484bcf093d6671982bf5e4edc4fc1be8907d849a88df9b85ab2b9810f88ce9533a9d1d125187fd47c26191fbe3e104e90307ee6fb19b3cffa37546
-  data.tar.gz: 329631cf0d425b281c4a4770318d2956ae95ca7d2e0b12e2e0054bd2f0d72a3310a92d1ce2fa125d5a056c76026c27472230a0710335790267db173ada8e48db
+  metadata.gz: a81b0ffb4b0e04024518169e3c6dd51a3f55b5da39659a852c2a0c9528453fe0eb9facf07d7b18bd35d7924c5a08331b2f1ad82a7e5c4c43c61fae55490d46ed
+  data.tar.gz: f6780cb0c58069a5049081c7a319424787c9fea1fd94a5085153d7b99533c0e1974c23dfeb3515b66f3b2d8d3c7ca83a08dcd5f024df02da2b2fc9609c3ba6b7

data/lib/hecks/bluebook/dsl/hecksagon_builder.rb

@@ -57,9 +57,9 @@ module Hecks
           end
         end
 
-        # The release that drops the deprecated spellings of `attaches`; kept in step with
-        # `Hecks::Doors::REMOVAL`, which this file cannot require.
-        REMOVAL = "3.2.0".freeze
+        # The release that drops the deprecated spellings of `attaches`; independent of
+        # `Hecks::Doors::REMOVAL`, which covers the older `Facade` aliases.
+        REMOVAL = "3.3.0".freeze
 
         attr_reader :binds, :subscriptions, :attachments
 

data/lib/hecks/cli/check_era.rb

@@ -2,11 +2,9 @@ require_relative "../ports/persistence/plugins/era/expected_era"
 
 module Hecks
   module CLI
-    # The command behind `hecks check_era` and Custodian's `Host.CheckEra`: asks a running host
-    # which era it reports and compares it with an allow-list file. Read-only: one GET, no writes.
+    # The check behind Custodian's `Host.CheckEra`: asks a running host which era it reports and
+    # compares it with an allow-list file. Read-only: one GET, no writes.
     module CheckEra
-      USAGE = "usage: hecks check_era <url> <expected-era-file> [--timeout=<seconds>]".freeze
-
       # What a check found.
       #
       # @!attribute [r] verdict
@@ -14,7 +12,7 @@ module Hecks
       # @!attribute [r] version
       #   @return [String] the gem version the host reports, empty when it reports none
       # @!attribute [r] line
-      #   @return [String] the sentence `hecks check_era` prints for this finding
+      #   @return [String] the sentence the check reports for this finding
       Finding = Struct.new(:verdict, :version, :line)
 
       module_function
@@ -36,35 +34,6 @@ module Hecks
         Finding.new(verdict, document.fetch("version"), sentence(verdict, file))
       end
 
-      # Runs `hecks check_era`: prints the finding and answers the exit status.
-      #
-      # @param argv [Array<String>] the url, the allow-list file and an optional `--timeout=N`
-      # @param out [IO] where a finding goes
-      # @param err [IO] where a refusal goes
-      # @return [Integer] 0 when the era is expected or unlisted, 1 on a mismatch, 2 on bad
-      #   usage or an unreadable file, 3 when the host cannot be reached or answers no era
-      def run(argv, out: $stdout, err: $stderr)
-        timeout = 10
-        args = argv.reject do |arg|
-          next false unless arg.start_with?("--timeout=")
-
-          timeout = arg.delete_prefix("--timeout=").to_f
-          true
-        end
-        url, file = args
-        return usage(err) unless url && file && args.size == 2 && timeout.positive?
-
-        finding = assess(url, file, timeout: timeout)
-        (finding.verdict.ok? ? out : err).puts(finding.line)
-        finding.verdict.ok? ? 0 : 1
-      rescue Errno::ENOENT, Errno::EACCES => e
-        err.puts("cannot read #{file}: #{e.message}")
-        2
-      rescue Runtime::EraCheck::ExpectedEra::Unreachable, Runtime::EraCheck::ExpectedEra::BadResponse => e
-        err.puts("era check failed: #{e.message}")
-        3
-      end
-
       # @param verdict [Runtime::EraCheck::ExpectedEra::Verdict] the comparison
       # @param file [String] the allow-list file, named in the sentence
       # @return [String] the one line that says what the comparison found
@@ -78,11 +47,6 @@ module Hecks
           "host reports era #{verdict.era}, which is not in #{file} (expected: #{verdict.allowed.join(', ')})"
         end
       end
-
-      def usage(err)
-        err.puts(USAGE)
-        2
-      end
     end
   end
 end

data/lib/hecks/doors/mcp_door.rb

@@ -343,7 +343,20 @@ module Hecks
       def answer_tool(name, args)
         return scope.refusal(name) unless scope.permits_tool?(name)
 
-        call_tool(name, args)
+        call_tool(name, scope.with_default_domain(args))
+      end
+
+      # One line per allowed command: what it takes and the role it declares, read from the booted
+      # domain the door serves. Nil when the door serves no single domain or it will not boot, so
+      # `tools/list` still answers, with the commands as a bare list.
+      def command_guide
+        return unless scope.commands_mode? && scope.default_domain
+
+        McpGuideCache.remember(scope.default_domain, scope.allowed_commands) do
+          Storehouse.command_guide(boot(scope.default_domain), scope.allowed_commands)
+        end
+      rescue StandardError
+        nil
       end
 
       def tool_result(payload)
@@ -374,7 +387,8 @@ module Hecks
           nil # a notification — no id, no response
         when "tools/list"
           served = TOOLS.select { |tool| scope.permits_tool?(tool[:name]) }
-          send_response(id, { tools: served.map { |tool| scope.present(tool) } })
+          guide = command_guide
+          send_response(id, { tools: served.map { |tool| scope.present(tool, guide) } })
         when "tools/call"
           send_response(id, tool_result(answer_tool(params["name"], params["arguments"] || {})))
         when "ping"

data/lib/hecks/doors/mcp_door_scope.rb

@@ -201,18 +201,40 @@ module Hecks
         end
       end
 
-      # The tool as `tools/list` shows it: on a commands door, `dispatch` names the commands it
-      # serves, so a caller sees them as an enum instead of finding out by being refused.
+      # The one domain a restricted door serves, when it serves exactly one: a call may leave
+      # `domain:` out and get it. Nil for an unrestricted door and for one that names several.
+      #
+      # @return [String, nil] the domain path as `HECKS_DOOR_DOMAINS` named it, resolved
+      def default_domain
+        @allowed_domains.first if restricted? && @allowed_domains.size == 1
+      end
+
+      # The arguments with the default domain filled in when the caller left it out.
+      #
+      # @param args [Hash] a tool call's arguments
+      # @return [Hash] `args`, with `"domain"` set when the door has a default and none was given
+      def with_default_domain(args)
+        return args unless default_domain && args["domain"].to_s.strip.empty?
+
+        args.merge("domain" => default_domain)
+      end
+
+      # The tool as `tools/list` shows it. A door that serves one domain makes `domain:` optional.
+      # On a commands door, `dispatch` also names the commands it serves as an enum, so a caller
+      # sees them as typed choices instead of finding out by being refused, and says what each
+      # takes and which role it declares.
       #
       # @param tool [Hash] a tool definition from `McpDoor::TOOLS`
+      # @param guide [Array<String>, nil] one line per allowed command (`Storehouse.command_guide`)
       # @return [Hash] the definition, narrowed for this door
-      def present(tool)
+      def present(tool, guide = nil)
+        tool = domain_optional(tool) if default_domain
         return tool unless commands_mode? && tool[:name] == "dispatch"
 
         properties = tool[:inputSchema][:properties]
         narrowed = properties.merge(command: with_enum(properties[:command]),
                                     steps:   properties[:steps].merge(items: step_items(properties[:steps][:items])))
-        tool.merge(description: "#{tool[:description]} This door dispatches only: #{allowed_commands.join(', ')}.",
+        tool.merge(description: dispatch_description(tool[:description], guide),
                    inputSchema: tool[:inputSchema].merge(properties: narrowed))
       end
 
@@ -287,6 +309,23 @@ module Hecks
         File.join(File.realpath(current), *missing)
       end
 
+      def domain_optional(tool)
+        schema = tool[:inputSchema]
+        return tool unless schema[:properties].key?(:domain)
+
+        note = "Optional: this door serves one domain, #{default_domain}, and uses it when you leave this out."
+        properties = schema[:properties].merge(domain: schema[:properties][:domain].merge(description: note))
+        tool.merge(inputSchema: schema.merge(properties: properties, required: schema[:required] - ["domain"]))
+      end
+
+      def dispatch_description(base, guide)
+        intro = "#{base} This door dispatches only the commands below, each with the role it declares: pass " \
+                "that role as `role`. A command that takes `run` takes a key you choose, and the call answers " \
+                "the record as it stands once its reactions have run; an argument marked * is required."
+        entries = Array(guide).empty? ? allowed_commands : guide
+        ([intro] + entries.map { |entry| "- #{entry}" }).join("\n")
+      end
+
       def with_enum(property)
         property.merge(enum: allowed_commands)
       end

data/lib/hecks/doors/mcp_guide_cache.rb

@@ -0,0 +1,75 @@
+require "digest"
+require "fileutils"
+require "json"
+require_relative "../cache_dir"
+require_relative "../storehouse"
+require_relative "../bluebook/meta_validator/verdict_cache"
+
+module Hecks
+  module Doors
+    # Remembers the command guide a commands door builds for `tools/list`, so a door that starts
+    # again does not boot its domain to describe its commands. A client waits only a moment for a
+    # server's tools, and a boot at that point costs more than the wait.
+    #
+    # An entry is keyed by the domain directory's files, a digest of the hecks code, and the
+    # allowed commands, so a change to any of them builds a new guide. The file is JSON, read only
+    # from a directory and a file that only this user can write (the verdict cache's own check),
+    # and only when it is a list of strings: a guide is text an agent reads as instructions.
+    module McpGuideCache
+      module_function
+
+      # The guide for a domain and its allowed commands, from the cache or else from the block,
+      # which is then remembered. A cache that cannot be written is not an error: the next start
+      # builds the guide again.
+      #
+      # @param domain [String] the domain directory the guide describes
+      # @param commands [Array<String>] the allowed command names
+      # @yieldreturn [Array<String>, nil] the guide, built when none is remembered
+      # @return [Array<String>, nil] the guide
+      def remember(domain, commands)
+        file = File.join(dir, "#{key(domain, commands)}.json")
+        cached = read(file)
+        return cached if cached
+
+        guide = yield
+        write(file, guide) if guide.is_a?(Array) && guide.any?
+        guide
+      end
+
+      # @return [String] the directory entries live in
+      def dir = Hecks::CacheDir.path("mcp_door_guides")
+
+      # @param domain [String] the domain directory
+      # @param commands [Array<String>] the allowed command names
+      # @return [String] a hex SHA-256 over the domain's files, the hecks code and the commands
+      def key(domain, commands)
+        parts = [Storehouse.fingerprint(domain), Bluebook::MetaValidator::VerdictCache.code_digest,
+                 commands.sort.join(",")]
+        Digest::SHA256.hexdigest(parts.join("\0"))
+      end
+
+      # @param file [String] an entry's path
+      # @return [Array<String>, nil] the guide, or nil when absent, untrusted or malformed
+      def read(file)
+        return unless File.file?(file) && Bluebook::MetaValidator::VerdictCache.trusted?(file)
+
+        guide = JSON.parse(File.read(file))
+        guide if guide.is_a?(Array) && guide.all?(String)
+      rescue StandardError
+        nil
+      end
+
+      # @param file [String] an entry's path
+      # @param guide [Array<String>] the guide to remember
+      # @return [void]
+      def write(file, guide)
+        FileUtils.mkdir_p(dir, mode: 0o700)
+        temp = "#{file}.#{Process.pid}.tmp"
+        File.write(temp, JSON.generate(guide), perm: 0o600)
+        File.rename(temp, file)
+      rescue StandardError
+        FileUtils.rm_f(temp) if temp
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/properties/dispatch_and_mutations.rb

@@ -118,8 +118,9 @@ module Hecks
 
             owner = owner_for_verb(bluebooks, entry[:verb]) || aggregate
 
+            args = with_declared_defaults(command, entry[:args])
             command.mutations.select { |m| RECOMPUTABLE_MUTATION_OPS.include?(m.op) }.filter_map do |mutation|
-              expected = recompute_mutation(mutation, entry[:before][mutation.target], entry[:args], entry[:before],
+              expected = recompute_mutation(mutation, entry[:before][mutation.target], args, entry[:before],
                                             aggregate, command, owner)
               next if expected == :unrecomputable
 
@@ -134,6 +135,21 @@ module Hecks
           offenders.empty? || offenders.join("; ")
         end
 
+        # The arguments the command actually ran with: an argument the caller left out takes the
+        # default its attribute declares, as dispatch fills it, so the recomputation starts from
+        # the same facts.
+        #
+        # @param command [Object] the command the step dispatched
+        # @param args [Hash] the arguments the step offered
+        # @return [Hash] `args`, with each omitted defaulted argument filled
+        def with_declared_defaults(command, args)
+          command.attributes.each_with_object(args.dup) do |attribute, held|
+            next if attribute.default.nil? || held.key?(attribute.name.to_sym) || held.key?(attribute.name.to_s)
+
+            held[attribute.name.to_sym] = attribute.default
+          end
+        end
+
         # Root aggregate for `verb`, derived from the verb alone because hand-built
         # entries may lack `:domain`/`:aggregate`. Value-object types resolve against
         # the root's namespace only.

data/lib/hecks/hecks/adapters/codebase/test_runner.rb

@@ -38,7 +38,9 @@ module Hecks
           status = Dir.chdir(@tree.root) { runner.call(["--example", example, path], out, out) }
           raise ConsoleCapture::Failure, out.string.strip unless status.zero?
 
-          out.string.strip
+          out.string.strip.tap do |report|
+            raise ConsoleCapture::Failure, "the test runner printed nothing for #{file}" if report.empty?
+          end
         end
 
         private
@@ -47,7 +49,13 @@ module Hecks
           return self.class.runner if self.class.runner
 
           require "rspec/core"
-          RSpec::Core::Runner.method(:run)
+          # A process that runs one example after another, as a resident door does, has to reset
+          # RSpec between runs: its reporter keeps the first run's output stream, so a later run
+          # would write into that and answer an empty report.
+          lambda do |args, err, out|
+            RSpec.reset
+            RSpec::Core::Runner.run(args, err, out)
+          end
         end
       end
     end

data/lib/hecks/hecks/adapters/rust_workspace.rb

@@ -22,7 +22,7 @@ module Hecks
       CHECKOUT_MARKER = "hecks.gemspec"
 
       # What a copy holds: the workspace manifest, the kernel and every crate a domain build uses.
-      PACKAGED = %w[Cargo.toml Cargo.lock project.rb project_rust_pipeline.rb project src codegen parser
+      PACKAGED = %w[Cargo.toml Cargo.lock src codegen parser
                     host build web lsp].freeze
 
       # Left out of a copy: build output anywhere, the corpus tests, and the corpus domains.

data/lib/hecks/hecks/adapters/site_toolchain.rb

@@ -9,13 +9,16 @@ module Hecks
     # The `SiteToolchain` port's adapter: projects a site's route table into its `routes.ts`, or
     # checks the file on disk is current.
     #
-    # The projection runs the `project_site` tool in a child of the checkout, with its printing and
-    # exit status captured: a tool that ends non-zero is a refusal whose reason is what it printed.
-    # Outside a hecks checkout the ask is refused with "needs a hecks checkout".
+    # The projection runs the `project_site` tool in this process, with its printing and exit status
+    # captured: a tool that ends non-zero is a refusal whose reason is what it printed. The tool
+    # ships in the gem and reads only the project it is given, so it needs no hecks checkout.
     class SiteToolchain
       # The `Hecks::Tools` tool the ask runs, by ask.
       SCRIPTS = { project: "project_site" }.freeze
 
+      # The tool's flag for each `SiteProjection` field that takes a value.
+      FLAGS = { "out" => :out, "template" => :template, "extension" => :extension }.freeze
+
       # Accepts the arguments every driven adapter is built with and keeps none of them.
       #
       # @param aggregate [Object, nil] unused
@@ -25,17 +28,17 @@ module Hecks
 
       # Writes a project's `routes.ts` from its declared route table, or with `check` only compares.
       #
-      # @param held [Hash] the `SiteProjection` record: `domain`, and `out` and `check` when set
+      # @param held [Hash] the `SiteProjection` record: `domain`, and `out`, `template`, `extension`
+      #   and `check` when set
       # @return [Hash{Symbol => Hash}] `output:` one line per file written or found current
-      # @raise [ConsoleCapture::Failure] when the tree is not a checkout, the route table is
-      #   refused (an unknown cache class, a duplicate path), or under `check` a file is out of date
+      # @raise [ConsoleCapture::Failure] when the route table is refused (an unknown cache class,
+      #   a duplicate path), a path or the extension is refused, or under `check` a file is out
+      #   of date
       def project(**held)
-        flags = []
-        flags << "--out=#{plain(held[:out])}" unless plain(held[:out]).nil?
+        flags = FLAGS.filter_map { |flag, key| "--#{flag}=#{located(key, held[key])}" unless plain(held[key]).nil? }
         flags << "--check" if plain(held[:check]) == true
-        tree = Codebase::Tree.new
-        tree.require_checkout!
-        result = Codebase::RubyChild.new(tree).capture(SCRIPTS.fetch(:project), *flags, plain(held[:domain]))
+        result = Codebase::RubyChild.new(Codebase::Tree.new).capture(SCRIPTS.fetch(:project), *flags,
+                                                                     located(:domain, held[:domain]))
         raise ConsoleCapture::Failure, message_of(result) unless result.ok?
 
         { output: { value: result.out } }
@@ -48,6 +51,13 @@ module Hecks
         text.empty? ? "the tool ended with status #{result.status.exitstatus}" : text
       end
 
+      # The tool runs from the tool's own root, so a path the caller gave relative to where they
+      # stand is made absolute first; the extension is not a path.
+      def located(key, argument)
+        value = plain(argument)
+        value.nil? || key == :extension ? value : File.expand_path(value)
+      end
+
       def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
     end
   end

data/lib/hecks/language/bluebook/vocabulary.bluebook

@@ -625,16 +625,16 @@ Hecks.bluebook "Bluebook" do
              pattern: '^lib/hecks/runtime/', push: "skip",
              label: "does this change touch lib/hecks/runtime/**?"
       member name: "postgres_io_relevant_changed", workflow: "ci-postgres-io-parallel.yml", mode: "skips_unless",
-             pattern: '^(docs/|editors/|release/|deploy/|\.claude/|\.githooks/|rust/(parser|codegen|host|build|lsp|web|tests|project)/|rust/project\.rb$|rust/project_rust_pipeline\.rb$|\.rubocop\.yml$|\.rubocop_todo\.yml$|\.mcp\.json$|\.rspec-local\.example$|README\.md$|CHANGELOG\.md$|CONTRIBUTING\.md$|SECURITY\.md$|LICENSE$|\.gitignore$)',
+             pattern: '^(docs/|editors/|release/|deploy/|\.claude/|\.githooks/|rust/(parser|codegen|host|build|lsp|web|tests)/|\.rubocop\.yml$|\.rubocop_todo\.yml$|\.mcp\.json$|\.rspec-local\.example$|README\.md$|CHANGELOG\.md$|CONTRIBUTING\.md$|SECURITY\.md$|LICENSE$|\.gitignore$)',
              push: "before_sha",
              label: "does this change touch anything rspec_postgres_io_parallel covers?"
     end
 
     # Rust keywords (strict + reserved) a generated identifier must not
-    # collide with. RustProjection::Projector::RUST_KEYWORDS reads this;
-    # hecks project_reserved_names projects it into
-    # rust/codegen/src/reserved_names.rs, so Ruby and Rust escape or refuse
-    # the same words from one declaration instead of two hand-typed copies.
+    # collide with. ModelCheck reads this; hecks project_reserved_names
+    # projects it into rust/codegen/src/reserved_names.rs, so Ruby and Rust
+    # escape or refuse the same words from one declaration instead of two
+    # hand-typed copies.
     value_object "RustReservedWord" do
       attribute :word, String,
                 one_of: ["as", "break", "const", "continue", "crate", "dyn", "else", "enum", "extern", "false",
@@ -648,8 +648,8 @@ Hecks.bluebook "Bluebook" do
     # as a Cargo `[features]` key: every key rust/Cargo.toml already uses
     # outside `[features]` (`[package]`, `[lib]`, `[[bin]]`) plus `default`,
     # which Cargo reserves for the auto-enabled feature set. Read by
-    # RustProjection::Projector::CARGO_RESERVED_DOMAIN_NAMES and projected by
-    # hecks project_reserved_names, same as RustReservedWord above.
+    # Hecks::RustBuild::DomainName and projected by hecks
+    # project_reserved_names, same as RustReservedWord above.
     value_object "CargoReservedName" do
       attribute :name, String,
                 one_of: ["name", "version", "edition", "path", "authors", "license", "description", "default",

data/lib/hecks/language/hecksagon/hecksagon.bluebook

@@ -83,7 +83,7 @@ Hecks.bluebook "Hecksagon" do
       member word: "hecksagon",       context: "File",     body: "keywords", inner: "Hecksagon",      opens: "Hecksagon",      fills: ""
       member word: "subscribe",       context: "Hecksagon", body: "none", inner: "", opens: "", fills: "subscriptions"
       member word: "attaches",        context: "Hecksagon", body: "none", inner: "", opens: "", fills: "attachments"
-      # Deprecated spellings of `attaches`; they warn and are removed in 3.2.0.
+      # Deprecated spellings of `attaches`; they warn and are removed in 3.3.0.
       member word: "uses_framework",  context: "Hecksagon", body: "none", inner: "", opens: "", fills: "attachments", status: "deprecated"
       member word: "uses_embryonaut_bluebook", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "attachments", status: "deprecated"
       member word: "port",            context: "Hecksagon",     body: "keywords", inner: "DomainPort",    opens: "DomainPort",    fills: "", calls: "port_impl"

data/lib/hecks/ports/persistence/plugins/era/expected_era.rb

@@ -58,7 +58,7 @@ module Hecks
         # @return [String] the `era` the host's `/version` document carries
         # @raise [Unreachable] if the request fails or the status is not `200`
         # @raise [BadResponse] if the body is not JSON or its `era` is not a non-empty string
-        def fetch_era(url, timeout: 10)
+        def fetch_era(url, timeout:)
           fetch_version(url, timeout: timeout).fetch("era")
         end
 
@@ -70,7 +70,7 @@ module Hecks
         #   host reports none)
         # @raise [Unreachable] if the request fails or the status is not `200`
         # @raise [BadResponse] if the body is not JSON or its `era` is not a non-empty string
-        def fetch_version(url, timeout: 10)
+        def fetch_version(url, timeout:)
           response = get(version_url(url), timeout)
           raise Unreachable, "#{version_url(url)} answered #{response.code}" unless response.code == "200"
 
@@ -105,7 +105,7 @@ module Hecks
         # @raise [Errno::ENOENT] if the allow-list file does not exist
         # @raise [Unreachable] see `fetch_era`
         # @raise [BadResponse] see `fetch_era`
-        def check(url, file, timeout: 10)
+        def check(url, file, timeout:)
           allowed = parse(File.read(file))
           verdict(fetch_era(url, timeout: timeout), allowed)
         end

data/lib/hecks/projections/deploy/box/settings.rb

@@ -34,6 +34,8 @@ module Hecks
                          "@sha256:226d1f059b75399fe19182893c7184591c07b97afc8dfcf44eeb80c9a77a530f".freeze
           TUNNEL_SHAPE = "tunnel: a hash needs `to` (the container it forwards to) and `token_secret` " \
                          "(the secret holding the tunnel token)".freeze
+          ORIGIN_ENV_SHAPE = "origin_env: the container environment variable names that hold the origin secret " \
+                             "need an origin_secret and a task_definition to compare against".freeze
           ORIGIN_PAIR = "origin_header and origin_secret go together: the header a CDN sends, " \
                         "and the secret that holds its value".freeze
 
@@ -79,7 +81,7 @@ module Hecks
             :infra_name, :stack_prefix, :instance_type, :volume_gb, :swap_gb, :database_class,
             :storage_gb, :backup_days, :snapshots_keep, :database_name, :engine_version,
             :containers, :routes, :default_container, :origin_header, :origin_secret,
-            :secret_prefixes, :writable_secrets, :tunnel, :tunnel_service, :proxy_image, :task_definition,
+            :secret_prefixes, :writable_secrets, :origin_env, :tunnel, :tunnel_service, :proxy_image, :task_definition,
             :migration, :s3_buckets, keyword_init: true
           ) do
             # @return [String] the CloudFormation stack that holds the database
@@ -110,6 +112,7 @@ module Hecks
             task_definition = read_task_definition(s[:task_definition], listed)
             containers = read_containers(listed, infra_name)
             header, secret = read_origin(s)
+            origin_env = read_origin_env(s, secret, task_definition)
             tunnel, tunnel_service = read_tunnel(s.fetch(:tunnel, false), containers)
 
             Plan.new(
@@ -118,7 +121,7 @@ module Hecks
               engine_version: check(:engine_version, s.fetch(:engine_version, "16").to_s, ENGINE),
               containers: containers, routes: read_routes(s.fetch(:routes, []), containers),
               default_container: read_default(s[:default_container], containers), origin_header: header,
-              origin_secret: secret, secret_prefixes: read_prefixes(s, infra_name),
+              origin_secret: secret, origin_env: origin_env, secret_prefixes: read_prefixes(s, infra_name),
               writable_secrets: read_writable_secrets(s),
               tunnel: tunnel, tunnel_service: tunnel_service,
               proxy_image: check(:proxy_image, s.fetch(:proxy_image, PROXY_IMAGE), IMAGE),
@@ -263,6 +266,24 @@ module Hecks
             [check(:origin_header, header, HEADER), check(:origin_secret, secret, SECRET_NAME)]
           end
 
+          # The container environment variables that hold the origin secret in the task
+          # definition. Only Caddy reads the named secret; the containers keep the task
+          # definition's copy, so a copy that differs makes every request through the CDN
+          # fail. Naming them lets deploy refuse a mismatch.
+          #
+          # @param settings [Hash{Symbol => Object}] the world's `AwsBox` settings
+          # @param secret [String, nil] the declared origin secret
+          # @param task_definition [String, nil] the declared task definition family
+          # @return [Array<String>] the variable names, empty when none are declared
+          # @raise [ArgumentError] when named without an origin secret and a task definition
+          def read_origin_env(settings, secret, task_definition)
+            names = Array(settings.fetch(:origin_env, []))
+            return [] if names.empty?
+            raise ArgumentError, ORIGIN_ENV_SHAPE if secret.nil? || task_definition.nil?
+
+            names.map { |name| check(:origin_env, name, ENV_KEY) }.uniq
+          end
+
           # `tunnel true` only opens the outbound port; a hash also runs cloudflared as a service.
           #
           # @param value [Boolean, Hash{Symbol => Object}] the world's `tunnel` setting

data/lib/hecks/projections/deploy/box/templates/deploy-box.sh.tmpl

@@ -55,6 +55,7 @@ ROLL=$(jq -n --arg compose "$(B64 "$WORK/compose.json")" --arg secrets "$(B64 "$
   --arg registry "$ACCOUNT.dkr.ecr.$REGION.amazonaws.com" --arg dir "$DIR" '
   {commands: ["cloud-init status --wait >/dev/null 2>&1 || true",
     "set -e", "mkdir -p \($dir)/caddy-extra && cd \($dir)", "umask 077",
+    "CADDY_BEFORE=$(cat Caddyfile 2>/dev/null | sha256sum)",
     "echo \($compose) | base64 -d > compose.json; echo \($secrets) | base64 -d > secrets.json",
     "echo \($caddy) | base64 -d > Caddyfile; echo \($fetch) | base64 -d > fetch-secrets.sh",
     "bash fetch-secrets.sh",
@@ -62,6 +63,7 @@ ROLL=$(jq -n --arg compose "$(B64 "$WORK/compose.json")" --arg secrets "$(B64 "$
     "aws ecr get-login-password --region '"$REGION"' | docker login --username AWS --password-stdin \($registry) >/dev/null",
     "docker compose -f compose.json pull --quiet",
     "docker compose -f compose.json up -d --remove-orphans",
+    "[ \"$(sha256sum < Caddyfile)\" = \"$CADDY_BEFORE\" ] || docker compose -f compose.json restart caddy",
     "for i in $(seq 1 40); do docker compose -f compose.json ps --format \"{{.Status}}\" | grep -qE \"^Up (Less than a second|[0-4] seconds?)|Restarting|Created|Exited\" || break; sleep 1; done; docker compose -f compose.json ps --format \"table {{.Service}}\\t{{.Status}}\""],
    executionTimeout: ["900"]}')
 

data/lib/hecks/projections/deploy/box/templates/render-compose-taskdef.sh.tmpl

@@ -9,6 +9,10 @@
 # are replaced with the RDS stack's values where the task defines them, and every container runs on
 # the box's own network, so the proxy reaches each one on 127.0.0.1:<port>. Secrets (name + valueFrom)
 # are written to secrets.json for fetch-secrets.sh to resolve on the box.
+#
+# When the world names origin_env, the named origin secret is compared with those variables in the
+# task definition and the render refuses on any difference (Caddy checks the CDN's header against
+# the secret; the containers check it against their own copy). Values are never printed.
 set -euo pipefail
 HERE=$(cd "$(dirname "$0")" && pwd)
 DB_HOST=${1:?rds endpoint}
@@ -18,6 +22,19 @@ TD=${3:-@@FAMILY@@}
 DEF=$(aws ecs describe-task-definition --task-definition "$TD" --query 'taskDefinition.containerDefinitions' --output json)
 echo "rendering from task definition $TD" >&2
 
+ORIGIN_ENV=$(jq -r '.origin.env // [] | .[]' "$HERE/services.json")
+if [ -n "$ORIGIN_ENV" ]; then
+  ORIGIN_SECRET_ID=$(jq -r '.origin.secret' "$HERE/services.json")
+  ORIGIN_VALUE=$(aws secretsmanager get-secret-value --secret-id "$ORIGIN_SECRET_ID" --query SecretString --output text)
+  for NAME in $ORIGIN_ENV; do
+    HOLDERS=$(echo "$DEF" | jq -r --arg n "$NAME" '[.[] | select(any((.environment // [])[]; .name == $n)) | .name] | join(" ")')
+    [ -n "$HOLDERS" ] || { echo "refusing to render: origin_env names $NAME, which no container in $TD sets" >&2; exit 1; }
+    DIFFERENT=$(echo "$DEF" | jq -r --arg n "$NAME" --arg v "$ORIGIN_VALUE" \
+      '[.[] | select(any((.environment // [])[]; .name == $n and .value != $v)) | .name] | join(" ")')
+    [ -z "$DIFFERENT" ] || { echo "refusing to render: $NAME in $TD (container: $DIFFERENT) differs from the origin secret $ORIGIN_SECRET_ID; the proxy would refuse every request from the CDN. Make them equal." >&2; exit 1; }
+  done
+fi
+
 jq --argjson def "$DEF" --arg host "$DB_HOST" --arg secret "$DB_SECRET" '
   def log: {driver: "json-file", options: {"max-size": "10m", "max-file": "3"}};
   def env(c): ((c.environment // []) | map({(.name): .value}) | add // {})

data/lib/hecks/projections/deploy/box.rb

@@ -379,9 +379,19 @@ module Hecks
         def route_blocks(plan)
           routes = plan.routes.each_with_index.map do |route, i|
             port = plan.containers.find { |c| c.name == route.container }.port
-            "@r#{i + 1} path #{route.paths.join(' ')}\nhandle @r#{i + 1} {\n\treverse_proxy 127.0.0.1:#{port}\n}\n\n"
+            "@r#{i + 1} path #{route.paths.join(' ')}\nhandle @r#{i + 1} {\n#{upstream(port)}}\n\n"
           end
-          "#{routes.join}handle {\n\treverse_proxy 127.0.0.1:#{plan.default.port}\n}\n"
+          "#{routes.join}handle {\n#{upstream(plan.default.port)}}\n"
+        end
+
+        # One upstream. A request that arrives while its container is being replaced
+        # waits, and is tried again every quarter second for up to 15 seconds, so a
+        # deploy shows a visitor a slow page instead of a 502.
+        #
+        # @param port [Integer] the container's port
+        # @return [String] the `reverse_proxy` block, one tab in, ending in a newline
+        def upstream(port)
+          "\treverse_proxy 127.0.0.1:#{port} {\n\t\tlb_try_duration 15s\n\t\tlb_try_interval 250ms\n\t}\n"
         end
 
         # @param plan [Settings::Plan] the resolved settings
@@ -425,6 +435,7 @@ module Hecks
         def services_json(plan)
           services = plan.containers.to_h { |c| [c.name, service_entry(plan, c)] }
           origin = plan.origin_secret ? { "header" => plan.origin_header, "secret" => plan.origin_secret } : nil
+          origin["env"] = plan.origin_env if origin && plan.origin_env.any?
           document = { "services" => services, "origin" => origin }
           document["task_definition"] = plan.task_definition if plan.task_definition
           document["tunnel"] = tunnel_entry(plan.tunnel_service) if plan.tunnel_service

data/lib/hecks/projections/site/edge/behaviours.rb

@@ -63,9 +63,11 @@ module Hecks
 
           def reference(text) = text.nil? || text == "none" ? nil : Checks.resolve(text)
 
-          # CloudFront takes three sets of methods: read, read with `OPTIONS`, and all.
+          # CloudFront takes three sets of methods: read, read with `OPTIONS`, and all. A route's
+          # `edge_methods` are the verbs the edge lets through; they are its own `methods` unless
+          # the row says more.
           def methods(rows)
-            verbs = rows.flat_map(&:verbs).uniq
+            verbs = rows.flat_map(&:edge_verbs).uniq
             return Deploy::Fargate::Cdn::METHODS.fetch("all") unless (verbs - ["GET"]).empty?
 
             assets = rows.all? { |row| row.origin == "assets" }
@@ -76,7 +78,7 @@ module Hecks
           # http and redirected; anything else (a form, an API, a signed or admin page, a route of
           # the cms or the domain) is served over https only.
           def protocol(row)
-            plain = row.auth == "public" && row.verbs == ["GET"] && %w[website assets].include?(row.origin)
+            plain = row.auth == "public" && row.edge_verbs == ["GET"] && %w[website assets].include?(row.origin)
             plain ? "redirect-to-https" : "https-only"
           end