hecks 3.11.0 → 3.13.0

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

@@ -611,6 +611,10 @@ Hecks.bluebook "Bluebook" do
     # `mode` is how `pattern` (an extended regex over changed paths) decides:
     # `touches` runs the job when any changed path matches, `skips_unless` runs it
     # when any changed path does NOT match (the pattern is the safe-to-skip list).
+    # `release_only` answers a different question and ignores `pattern`: `touched` is false only
+    # when the change edits nothing but the `ReleaseFile` rows' files and lines and the base it is
+    # measured against has every inheritable `RequiredCheck` green (ADR 0107), so the run may
+    # inherit that certification.
     # `push` is what a push event does: `skip` leaves the gate out of push runs,
     # `before_sha` diffs against the push's `before` commit.
     value_object "CiGate" do
@@ -624,19 +628,44 @@ Hecks.bluebook "Bluebook" do
       member name: "runtime_changed", workflow: "ci.yml", mode: "touches",
              pattern: '^lib/hecks/runtime/', push: "before_sha",
              label: "does this change touch lib/hecks/runtime/**?"
+      member name: "release_only", workflow: "ci.yml", mode: "release_only",
+             pattern: "", push: "before_sha",
+             label: "is this change only a release bump on a certified base?"
       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)/|\.rubocop\.yml$|\.rubocop_todo\.yml$|\.mcp\.json$|\.rspec-local\.example$|README\.md$|CHANGELOG\.md$|CONTRIBUTING\.md$|SECURITY\.md$|LICENSE$|\.gitignore$)',
              push: "skip",
              label: "does this change touch anything rspec_postgres_io_parallel covers?"
     end
 
+    # The files a release bump edits, and the lines of each it may change. A commit whose whole
+    # diff against a certified base falls inside these rows inherits the base's certification
+    # (`CiGate` `release_only`, ADR 0107): its checks report success without their jobs running,
+    # and the `release_consistency` check still runs on it. `path` is the file, exact; `lines` is
+    # an extended regex every added or removed line of that file must match, empty for any line.
+    value_object "ReleaseFile" do
+      attribute :path,  String
+      attribute :lines, String
+
+      member path: "lib/hecks/version.rb", lines: "^\\s*VERSION = \"[0-9]+\\.[0-9]+\\.[0-9]+\"\\.freeze$"
+      member path: "CHANGELOG.md", lines: ""
+      member path: "README.md", lines: "^(\\*\\*Status:\\*\\* )?Current release: `[0-9]+\\.[0-9]+\\.[0-9]+`"
+      member path: "Gemfile.lock", lines: "^    hecks \\([0-9]+\\.[0-9]+\\.[0-9]+\\)$"
+      member path: "rust/host/HECKS_RELEASE", lines: "^[0-9]+\\.[0-9]+\\.[0-9]+$"
+      member path: "packages/hecks-client/package.json", lines: "^\\s*\"version\": \"[0-9]+\\.[0-9]+\\.[0-9]+\",?$"
+      member path: "packages/hecks-client/package-lock.json", lines: "^\\s*\"version\": \"[0-9]+\\.[0-9]+\\.[0-9]+\",?$"
+    end
+
     # The checks a commit must have passed before a `Promotion` moves it onto a guarded lane. Each
     # is the name of a job in .github/workflows that reports to a commit as a check run; a check
     # that a path gate skipped reports `skipped`, which counts as passed. `hecks promote` reads
     # these rows, and hecks project_lanes writes them into the ruleset of any lane that requires
     # them, so the list lives here and nowhere else.
+    #
+    # `runs` is `always` for a check a release bump still runs (it is not inherited from the base);
+    # empty for a check a bump may inherit.
     value_object "RequiredCheck" do
       attribute :name, String
+      attribute :runs, String
 
       member name: "rspec"
       member name: "checks"
@@ -647,6 +676,7 @@ Hecks.bluebook "Bluebook" do
       member name: "rspec_rust_codegen"
       member name: "rspec_rust_host"
       member name: "rspec_fuzzing"
+      member name: "release_consistency", runs: "always"
     end
 
     # The branches a change travels along. `main` takes pushes with no gate; `stable` takes only
@@ -679,6 +709,28 @@ Hecks.bluebook "Bluebook" do
              release_trailer: "Release-Approved-By"
     end
 
+    # A binary hecks builds once per change to its crate and publishes, so a client that needs the
+    # same binary downloads it instead of compiling it (ADR 0110). `hecks regeneration_run.project_lanes`
+    # writes .github/workflows/publish-<name>.yml from each row; `Hecks::RustBuild::PrebuiltBinary`
+    # reads the same rows to name what to download.
+    #
+    # `crate` is the directory under the checkout that is built and keyed: the key is a hash of every
+    # file in it that goes into the build, so the same bytes in the crate are the same release.
+    # `executable` is the Cargo binary and `target` the Rust triple it is built for. `runner` is the
+    # GitHub-hosted image it is built on, pinned (never `-latest`) because a binary links the
+    # runner's glibc and must run on every host that runs that image or a newer one.
+    # The release is tagged `<name>-<key>` and carries `<executable>-<target>` and its `.sha256`.
+    value_object "PrebuiltBinary" do
+      attribute :name,   String
+      attribute :crate,  String
+      attribute :executable, String
+      attribute :target, String
+      attribute :runner, String
+
+      member name: "host", crate: "rust/host", executable: "bootstrap", target: "x86_64-unknown-linux-gnu",
+             runner: "ubuntu-24.04"
+    end
+
     # The dials of the hecks_qa loop: what each is called, the type of value it takes and what it
     # does. qa/settings.yml holds the values, which are edited and reviewed as a diff; this table
     # holds the rest, so the loader (`Hecks::Fuzzing::QaSettings`) checks the file against it and

data/lib/hecks/projection_files/expression_tables.rb

@@ -47,10 +47,15 @@ module Hecks
         declared = algebra.fetch(operator[:symbol]) do
           raise Refused, "#{operator[:symbol]} is admitted but Vocabulary::Comparison declares no algebra for it"
         end
-        row.merge(compares_less_than: declared[:compares_less_than],
-                  compares_equal: declared[:compares_equal], negated: declared[:negated])
+        row.merge(compares_less_than: spelled_true?(declared[:compares_less_than]),
+                  compares_equal:     spelled_true?(declared[:compares_equal]),
+                  negated:            spelled_true?(declared[:negated]))
       end
 
+      # @param cell [Object] a `Comparison` cell, declared as the text `"true"` or `"false"`
+      # @return [Boolean] whether the cell spells true
+      def spelled_true?(cell) = cell.to_s == "true"
+
       # @param dropped [Hash{String => Array<String>}] operator to the guards evaluating through it
       # @return [String] one line for each operator a projection would strand
       def dropped_message(dropped)

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

@@ -13,11 +13,13 @@ module Hecks
           #   an ECS task definition when the world names one
           def render_compose_sh(plan, region)
             if plan.task_definition
-              template("render-compose-taskdef.sh.tmpl", "STACK" => plan.infra_name, "FAMILY" => plan.task_definition,
-                                                          "PROXY_IMAGE" => plan.proxy_image)
+              template("render-compose-taskdef.sh.tmpl",
+                       { "STACK" => plan.infra_name, "FAMILY" => plan.task_definition, "PROXY_IMAGE" => plan.proxy_image }
+                         .merge(compose_log_values(plan, region, "$s.name")))
             else
-              template("render-compose.sh.tmpl", "STACK" => plan.infra_name, "REGION" => region,
-                                                 "DB_NAME" => plan.database_name, "PROXY_IMAGE" => plan.proxy_image)
+              template("render-compose.sh.tmpl",
+                       { "STACK" => plan.infra_name, "REGION" => region, "DB_NAME" => plan.database_name,
+                         "PROXY_IMAGE" => plan.proxy_image }.merge(compose_log_values(plan, region, ".name")))
             end
           end
 

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

@@ -0,0 +1,62 @@
+module Hecks
+  module Projections
+    module Deploy
+      module Box
+        # The CloudFront edge of a box deploy, for a world that declares `cdn`: the `edge.yaml`
+        # stack, the `edge.mk` that deploys it, and the two pieces `make stacks` gains so the box
+        # admits the CDN's addresses. Mixed into `Box`, which supplies `template`.
+        module Edge
+          # The AWS-managed prefix list of CloudFront's origin-facing addresses. Its id differs in
+          # every region, so it is looked up by this name rather than written down.
+          PREFIX_LIST_NAME = "com.amazonaws.global.cloudfront.origin-facing".freeze
+
+          # @param plan [Settings::Plan] the resolved settings
+          # @param region [String] the validated region
+          # @return [Hash{String => String}] `edge.yaml` and `edge.mk`, or nothing without a `cdn`
+          def edge_files(plan, region)
+            return {} unless plan.cdn
+
+            { "edge.yaml" => edge_yaml(plan),
+              "edge.mk"   => template("edge.mk.tmpl", "EDGE_STACK" => plan.edge_stack, "REGION" => region) }
+          end
+
+          # @param plan [Settings::Plan] the resolved settings, with a `cdn`
+          # @return [String] the CloudFront stack
+          def edge_yaml(plan)
+            values = { "STACK" => plan.infra_name, "ALIASES" => plan.cdn.aliases.join(","),
+                       "ORIGIN_HEADER" => plan.origin_header, "ORIGIN_SECRET" => plan.origin_secret }
+            template("edge.yaml.tmpl", values)
+          end
+
+          # @param plan [Settings::Plan] the resolved settings
+          # @param region [String] the validated region
+          # @return [Hash{String => String}] the Makefile markers `CDN_CHECK` and `CDN_PARAM`:
+          #   empty without a `cdn`, so a world that does not opt in renders the same Makefile
+          def edge_makefile_values(plan, region)
+            return { "CDN_CHECK" => "", "CDN_PARAM" => "" } unless plan.cdn
+
+            { "CDN_CHECK" => prefix_list_check(region), "CDN_PARAM" => "\t\tCdnPrefixListId=#{prefix_list_lookup(region)} \\" }
+          end
+
+          private
+
+          def prefix_list_query(region)
+            "aws ec2 describe-managed-prefix-lists --region #{region} --filters " \
+              "Name=prefix-list-name,Values=#{PREFIX_LIST_NAME} --query \"PrefixLists[0].PrefixListId\" --output text"
+          end
+
+          def prefix_list_lookup(region)
+            "$$(#{prefix_list_query(region)})"
+          end
+
+          # Stops `make stacks` before it changes anything when the prefix list cannot be found,
+          # because a box deployed without it has no inbound rule and the CDN gets a 504.
+          def prefix_list_check(region)
+            "\t@#{prefix_list_query(region)} | grep -q '^pl-' || { echo \"no #{PREFIX_LIST_NAME} " \
+              "prefix list in #{region}: the box would admit no CDN and answer 504\" >&2; exit 1; }"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,99 @@
+module Hecks
+  module Projections
+    module Deploy
+      module Box
+        # Where the box's containers write their logs. With `logs "cloudwatch"` (the default) every
+        # service uses Docker's `awslogs` driver into one log group the box stack creates, one
+        # stream per service, and the box role may write to that group only. With `logs "local"`
+        # the services keep Docker's rotating `json-file` logs, which a roll deletes with the
+        # container.
+        #
+        # `docker logs` keeps working with `awslogs`: Docker's dual-logging cache (Docker 20.10 and
+        # later, which the Amazon Linux 2023 package installs) keeps a local copy for reads.
+        # Mixed into `Box`, which supplies `template`.
+        module Logging
+          LOG_EXIT_CODE = "#   44  the box stack has no log group yet: update the stack (make stacks) before rolling\n".freeze
+          LOG_NOTE = <<~NOTE.freeze
+            # Every container logs to the CloudWatch group the box stack creates. A container whose log
+            # stream cannot be written does not start, so the roll first checks that the stack has the
+            # group (and the role's right to write it) and exits 44 if not. SKIP_LOG_GROUP_CHECK=1 skips it.
+            # `docker logs` and the log capture below still read the box's local copy (Docker's dual-logging cache).
+            #
+          NOTE
+          LOG_GROUP_CHECK = <<~CHECK.freeze
+            if [ "${SKIP_LOG_GROUP_CHECK:-}" = 1 ]; then
+              echo "==> skipping the log group check (SKIP_LOG_GROUP_CHECK=1)"
+            elif ! aws cloudformation describe-stack-resource --stack-name "$BOX_STACK" --logical-resource-id BoxLogGroup >/dev/null 2>&1; then
+              echo "==> $BOX_STACK has no BoxLogGroup: its containers would fail to start on the awslogs driver." >&2
+              echo "    Run make stacks to update box.yaml (log group and the role's logs policy) first, then roll again." >&2
+              exit 44
+            fi
+          CHECK
+          COMPOSE_LOG_NOTE = <<~NOTE.freeze
+            #
+            # Every service logs to the CloudWatch group the box stack creates (one stream per service). A
+            # container whose stream cannot be written does not start, so update the box stack (make stacks:
+            # the group and the role's logs policy) before the first roll that uses this file. `docker logs`
+            # still reads the box's local copy.
+          NOTE
+          JSON_FILE = '{driver: "json-file", options: {"max-size": "10m", "max-file": "3"}}'.freeze
+
+          # @param plan [Settings::Plan] the resolved settings
+          # @return [String] the log group resource spliced into `box.yaml`, or nothing for `local`
+          def log_group_yaml(plan)
+            return "" unless plan.cloudwatch_logs?
+
+            template("log-group.yaml.tmpl", "LOG_GROUP"      => plan.log_group,
+                                            "RETENTION_DAYS" => plan.log_retention_days.to_s)
+          end
+
+          # @param plan [Settings::Plan] the resolved settings
+          # @return [String] the role policy that lets the box write to its log group only, or
+          #   nothing for `local`
+          def log_policy_yaml(plan)
+            plan.cloudwatch_logs? ? template("log-policy.yaml.tmpl", {}) : ""
+          end
+
+          # The values `render-compose.sh` splices in: the jq definition of `log` and the call that
+          # names each service's stream. `local` renders the `json-file` definition and the bare
+          # `log`, so its output does not change.
+          #
+          # @param plan [Settings::Plan] the resolved settings
+          # @param region [String] the validated region
+          # @param service [String] the jq expression for a service's name in the template
+          # @return [Hash{String => String}] the template values
+          def compose_log_values(plan, region, service)
+            return { "COMPOSE_LOG_NOTE" => "", **local_log_values } unless plan.cloudwatch_logs?
+
+            { "COMPOSE_LOG_NOTE" => COMPOSE_LOG_NOTE, "LOG_DEF" => awslogs_definition(plan, region),
+              "LOG_SERVICE" => "log(#{service})", "LOG_CADDY" => 'log("caddy")', "LOG_TUNNEL" => 'log("cloudflared")' }
+          end
+
+          # The `deploy-box.sh` pieces that stop a roll onto a stack without the log group.
+          #
+          # @param plan [Settings::Plan] the resolved settings
+          # @return [Hash{String => String}] the exit-code line, the comment and the check, or empty
+          #   strings for `local`
+          def log_roll_values(plan)
+            return { "LOG_EXIT_CODE" => "", "LOG_NOTE" => "", "LOG_GROUP_CHECK" => "" } unless plan.cloudwatch_logs?
+
+            { "LOG_EXIT_CODE" => LOG_EXIT_CODE, "LOG_NOTE" => LOG_NOTE, "LOG_GROUP_CHECK" => LOG_GROUP_CHECK }
+          end
+
+          private
+
+          def awslogs_definition(plan, region)
+            options = %({"awslogs-region": "#{region}", "awslogs-group": "#{plan.log_group}", \
+"awslogs-create-group": "false", tag: $service})
+            %(def log($service): {driver: "awslogs", options: #{options}};)
+          end
+
+          def local_log_values
+            { "LOG_DEF" => "def log: #{JSON_FILE};", "LOG_SERVICE" => "log", "LOG_CADDY" => "log",
+              "LOG_TUNNEL" => "log" }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -45,7 +45,8 @@ module Hecks
                                            "RDS_STACK" => plan.rds_stack, "REGION" => region,
                                            "DIR" => "/opt/#{plan.infra_name}", "HEALTH_CHECKS" => health_checks(plan),
                                            "SMOKE_HEADER" => smoke_header(plan), "USAGE" => deploy_usage(plan),
-                                           "DB_SECRET_LINE" => database_secret_line(plan))
+                                           "DB_SECRET_LINE" => database_secret_line(plan),
+                                           **log_roll_values(plan))
           end
 
           # @param plan [Settings::Plan] the resolved settings
@@ -94,18 +95,25 @@ module Hecks
           end
 
           # @param plan [Settings::Plan] the resolved settings
+          # @param region [String] the validated region
           # @return [String] a Makefile whose targets create the two stacks and roll the box
-          def makefile(plan)
-            hint = plan.task_definition ? "[TASKDEF=family:revision]" : '[TAGS="web=20260101 worker=20260101"]'
-            base = template("Makefile.tmpl", { "STACK" => plan.infra_name, "DEPLOY_HINT" => hint,
-                                               "RDS_STACK" => plan.rds_stack, "BOX_STACK" => plan.box_stack,
-                                               "DEPLOY_RECIPE" => RollRecipe.deploy(plan) }
-                                               .merge(database_makefile_values(plan)))
-            plan.hosting ? "#{base}\ninclude hosting.mk\n" : base
+          def makefile(plan, region)
+            values = makefile_values(plan, region)
+            base = template("Makefile.tmpl", values)
+            includes = [("hosting.mk" if plan.hosting), ("edge.mk" if plan.cdn)].compact
+            includes.empty? ? base : "#{base}\n#{includes.map { |file| "include #{file}\n" }.join}"
           end
 
           private
 
+          def makefile_values(plan, region)
+            hint = plan.task_definition ? "[TASKDEF=family:revision]" : '[TAGS="web=20260101 worker=20260101"]'
+            { "STACK" => plan.infra_name, "DEPLOY_HINT" => hint, "RDS_STACK" => plan.rds_stack,
+              "BOX_STACK" => plan.box_stack, "DEPLOY_RECIPE" => RollRecipe.deploy(plan),
+              "AMI_PARAMETER" => ami_parameter(plan.instance_type) }
+              .merge(database_makefile_values(plan), edge_makefile_values(plan, region))
+          end
+
           def schema_list(migration)
             migration.schemas.map { |name| "`#{name}`" }.join(", ")
           end

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

@@ -0,0 +1,40 @@
+require_relative "patterns"
+
+module Hecks
+  module Projections
+    module Deploy
+      module Box
+        module Settings
+          # Reads the `cdn` setting: the CloudFront edge in front of the box. Extended onto
+          # `Settings`. The alias names themselves are checked by the Deploy bluebook's
+          # `BoxTarget.Declare` before this runs; this checks the shape and the guard.
+          module CdnReaders
+            include Patterns
+
+            # @param value [Hash{Symbol => Object}, nil] the world's `cdn` setting
+            # @param origin_header [String, nil] the declared origin header
+            # @return [Cdn, nil] the edge to generate, or nil when the world declares none
+            # @raise [ArgumentError] when the shape is wrong or there is no origin guard
+            def read_cdn(value, origin_header)
+              return nil if value.nil?
+
+              aliases = cdn_aliases(value)
+              raise ArgumentError, CDN_NEEDS_ORIGIN if origin_header.nil?
+
+              Settings::Cdn.new(aliases: aliases.uniq)
+            end
+
+            private
+
+            def cdn_aliases(value)
+              listed = value.is_a?(Hash) && value.keys == [:aliases] ? value[:aliases] : nil
+              raise ArgumentError, CDN_SHAPE unless listed.is_a?(Array) && !listed.empty?
+
+              listed.map { |name| check(:cdn_aliases, name, CDN_ALIAS) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+require_relative "patterns"
+
+module Hecks
+  module Projections
+    module Deploy
+      module Box
+        module Settings
+          # Reads the `logs` and `log_retention_days` settings: where the containers' logs go and
+          # how long CloudWatch keeps them. Extended onto `Settings`.
+          #
+          # Retention is one of CloudWatch's own values and never "never expire", so a box's log
+          # bill is bounded by a declaration.
+          module LogReaders
+            include Patterns
+
+            # @param settings [Hash{Symbol => Object}] the world's `AwsBox` settings
+            # @return [Hash{Symbol => Object}] the plan's `logs` and `log_retention_days`
+            # @raise [ArgumentError] when `logs` is not a known destination, or the retention is not
+            #   a value CloudWatch accepts
+            def read_logs(settings)
+              destination = settings.fetch(:logs, "cloudwatch").to_s
+              raise ArgumentError, LOGS_SHAPE unless LOG_DESTINATIONS.include?(destination)
+
+              days = settings.fetch(:log_retention_days, DEFAULT_LOG_RETENTION_DAYS)
+              raise ArgumentError, retention_refusal(days) unless LOG_RETENTION_DAYS.include?(days)
+
+              { logs: destination, log_retention_days: days }
+            end
+
+            private
+
+            def retention_refusal(days)
+              "log_retention_days: #{days.inspect} is not a CloudWatch retention; use one of #{LOG_RETENTION_DAYS.join(", ")}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -23,6 +23,13 @@ module Hecks
             S3_BUCKET   = /\A[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]\z/
             S3_SHAPE    = "s3_access: a list of `{ bucket: \"name\", write: true }` hashes (write is optional)".freeze
             FROM_TASKDEF = %i[env secrets repository].freeze
+            LOG_DESTINATIONS = %w[cloudwatch local].freeze
+            DEFAULT_LOG_RETENTION_DAYS = 30
+            # The retention periods CloudWatch Logs accepts, in days, without "never expire".
+            LOG_RETENTION_DAYS = [1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1096, 1827, 2192, 2557,
+                                  2922, 3288, 3653].freeze
+            LOGS_SHAPE = "logs: \"cloudwatch\" ships every container's log to CloudWatch Logs; " \
+                         "\"local\" keeps Docker's rotating json-file logs on the box".freeze
 
             # The settings that size an RDS instance: with `shared_database` they are the shared
             # instance's.
@@ -37,6 +44,10 @@ module Hecks
                            "(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
+            CDN_ALIAS = /\A[a-z0-9.-]{4,253}\z/
+            CDN_SHAPE = "cdn: a hash with `aliases`, the non-empty list of host names the CloudFront edge answers on".freeze
+            CDN_NEEDS_ORIGIN = "cdn: the box admits CloudFront's addresses on port 80, so it needs the origin guard " \
+                               "that refuses every other caller; declare origin_header and origin_secret".freeze
             ORIGIN_PAIR = "origin_header and origin_secret go together: the header a CDN sends, " \
                           "and the secret that holds its value".freeze
           end

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

@@ -45,18 +45,33 @@ module Hecks
             # @!attribute [r] write [Boolean] whether a production box may also write and delete
             Bucket = Struct.new(:name, :write, keyword_init: true)
 
+            # The CloudFront edge a world asks for with `cdn`.
+            #
+            # @!attribute [r] aliases [Array<String>] the host names the distribution answers on
+            Cdn = Struct.new(:aliases, keyword_init: true)
+
             # Everything the generator reads, checked.
             Plan = Struct.new(
               :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, :origin_env, :tunnel, :tunnel_service, :proxy_image,
-              :task_definition, :migration, :s3_buckets, :hosting, :shared_database, keyword_init: true
+              :task_definition, :migration, :s3_buckets, :hosting, :shared_database, :cdn,
+              :logs, :log_retention_days, keyword_init: true
             ) do
               # @return [String] the CloudFormation stack that holds the database: the shared
               #   instance's when the world names one, else this site's own
               def rds_stack = shared_database || "#{stack_prefix}-#{infra_name}-rds"
 
+              # @return [String] the CloudFormation stack that holds the CloudFront edge
+              def edge_stack = "#{stack_prefix}-#{infra_name}-edge"
+
+              # @return [String] the CloudWatch log group the box's containers write to
+              def log_group = "/#{box_stack}"
+
+              # @return [Boolean] whether the containers' logs ship to CloudWatch Logs
+              def cloudwatch_logs? = logs == "cloudwatch"
+
               # @return [Boolean] whether the database lives on an instance shared with other sites
               def shared? = !shared_database.nil?
 

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

@@ -4,6 +4,8 @@ require_relative "settings/types"
 require_relative "settings/checks"
 require_relative "settings/containers"
 require_relative "settings/origin"
+require_relative "settings/cdn"
+require_relative "settings/logs"
 
 module Hecks
   module Projections
@@ -21,6 +23,8 @@ module Hecks
           extend Checks
           extend ContainerReaders
           extend OriginReaders
+          extend CdnReaders
+          extend LogReaders
 
           module_function
 
@@ -50,7 +54,7 @@ module Hecks
               shared_database: read_shared_database(settings),
               s3_buckets: read_s3_access(settings.fetch(:s3_access, [])),
               hosting: HostingSettings.read(settings, task_definition)
-            }
+            }.merge(read_logs(settings))
           end
 
           # @param settings [Hash{Symbol => Object}] the world's `AwsBox` settings
@@ -62,7 +66,7 @@ module Hecks
             origin_env = read_origin_env(settings, secret, task_definition)
             tunnel, tunnel_service = read_tunnel(settings.fetch(:tunnel, false), containers)
             { origin_header: header, origin_secret: secret, origin_env: origin_env,
-              tunnel: tunnel, tunnel_service: tunnel_service }
+              tunnel: tunnel, tunnel_service: tunnel_service, cdn: read_cdn(settings[:cdn], header) }
           end
 
           # @return [Hash{Symbol => Object}] the plan's names, sizes, routes and secret scopes

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

@@ -20,16 +20,19 @@ module Hecks
             template("box.yaml.tmpl",
                      "STACK" => plan.infra_name, "INSTANCE_TYPE" => plan.instance_type,
                      "VOLUME_GB" => plan.volume_gb.to_s, "SNAPSHOTS_KEEP" => plan.snapshots_keep.to_s,
-                     "AMI_PARAMETER" => ami_parameter(plan.instance_type),
                      "COMPUTE_DOMAIN" => compute_domain(region),
                      "SECRET_RESOURCES" => secret_resources(plan), "WRITABLE_SECRETS" => writable_secrets(plan),
                      "TUNNEL_EGRESS" => tunnel_egress(plan),
                      "SWAP_COMMANDS" => swap_commands(plan), "ECR_REPOSITORIES" => ecr_repositories(plan),
-                     "ECR_OUTPUTS" => ecr_outputs(plan), "S3_POLICY" => s3_policy(plan))
+                     "ECR_OUTPUTS" => ecr_outputs(plan), "S3_POLICY" => s3_policy(plan),
+                     "LOG_GROUP" => log_group_yaml(plan), "LOG_POLICY" => log_policy_yaml(plan))
           end
 
           # Graviton families end their generation digit with `g` (`t4g`, `m7gd`, `c6gn`).
           #
+          # Only a first create reads it, from `make stacks`: a live box keeps the image it runs,
+          # because a newer one would replace the instance.
+          #
           # @param instance_type [String] an EC2 instance type
           # @return [String] the SSM parameter of the matching Amazon Linux image
           def ami_parameter(instance_type)

data/lib/hecks/projections/deploy/box/templates/Makefile.tmpl

@@ -1,21 +1,37 @@
 # @@STACK@@: @@WHAT@@.
 #   make stacks VPC=vpc-... PRIVATE_SUBNETS=subnet-a,subnet-b PUBLIC_SUBNET=subnet-c [REHEARSAL=true]
 #   make deploy @@DEPLOY_HINT@@
+# `make stacks` keeps a live box on the image it runs, so an update never replaces the instance.
+# To move to a newer image on purpose:  make stacks ... AMI_ID=ami-...
 RDS_STACK = @@RDS_STACK@@
 BOX_STACK = @@BOX_STACK@@
 @@REHEARSAL_NOTE@@
 REHEARSAL ?= false
+AMI_ID ?=
 
 HECKS ?= hecks
 
 @@PHONY@@
 stacks:
+@@CDN_CHECK@@
 @@RDS_DEPLOY@@
+	@AMI="$(AMI_ID)"; SRC="given as AMI_ID"; \
+	if [ -z "$$AMI" ]; then \
+		BOX=$$(aws cloudformation describe-stack-resource --stack-name $(BOX_STACK) --logical-resource-id Box --query StackResourceDetail.PhysicalResourceId --output text 2>/dev/null); \
+		case "$$BOX" in \
+			i-*) AMI=$$(aws ec2 describe-instances --instance-ids "$$BOX" --query "Reservations[0].Instances[0].ImageId" --output text); SRC="pinned: the image $$BOX runs" ;; \
+			*) AMI=$$(aws ssm get-parameter --name @@AMI_PARAMETER@@ --query Parameter.Value --output text); SRC="new: no $(BOX_STACK) stack yet, so the latest image" ;; \
+		esac; \
+	fi; \
+	case "$$AMI" in ami-*) ;; *) echo "no ami- image found for $(BOX_STACK): pass one with AMI_ID=ami-..." >&2; exit 1 ;; esac; \
+	echo "==> AmiId $$AMI ($$SRC)"; \
 	aws cloudformation deploy --template-file box.yaml --stack-name $(BOX_STACK) --capabilities CAPABILITY_IAM \
 		--parameter-overrides VpcId=$(VPC) SubnetId=$(PUBLIC_SUBNET) \
 		DbSecurityGroupId=$$(aws cloudformation describe-stacks --stack-name $(RDS_STACK) --query "Stacks[0].Outputs[?OutputKey=='DbSecurityGroupId'].OutputValue" --output text) \
 @@DB_SECRET_PARAM@@
+		AmiId=$$AMI \
 		AlertTopicArn=$$(aws cloudformation describe-stacks --stack-name $(RDS_STACK) --query "Stacks[0].Outputs[?OutputKey=='AlertTopicArn'].OutputValue" --output text) \
+@@CDN_PARAM@@
 		Rehearsal=$(REHEARSAL)
 
 @@PROVISION@@

data/lib/hecks/projections/deploy/box/templates/box.yaml.tmpl

@@ -20,9 +20,12 @@ Parameters:
     Type: String
     Default: @@INSTANCE_TYPE@@
   AmiId:
-    Type: AWS::SSM::Parameter::Value<AWS::EC2::Image::Id>
-    Default: @@AMI_PARAMETER@@
-    Description: Never re-resolve this on a live box, because a newer image replaces the instance.
+    Type: AWS::EC2::Image::Id
+    Description: >-
+      The image the box runs, always given and never resolved here. Resolving the public image
+      key again on a live box finds the newest image, and a changed ImageId replaces the instance
+      and its Elastic IP association. make stacks passes the running box's own image, and takes a
+      newer one only when AMI_ID is given.
   RootVolumeGb:
     Type: Number
     Default: @@VOLUME_GB@@
@@ -82,7 +85,7 @@ Resources:
       SourceSecurityGroupId: !Ref BoxSecurityGroup
       Description: App box
 
-  BoxRole:
+@@LOG_GROUP@@  BoxRole:
     Type: AWS::IAM::Role
     Properties:
       AssumeRolePolicyDocument:
@@ -106,6 +109,7 @@ Resources:
 @@SECRET_RESOURCES@@
 @@WRITABLE_SECRETS@@
 @@S3_POLICY@@
+@@LOG_POLICY@@
 
   BoxProfile:
     Type: AWS::IAM::InstanceProfile

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

@@ -10,6 +10,7 @@
 #   42  the roll succeeded but the box is not healthy after it
 #   43  no restore anchor: the database's backups cannot be read, or are kept fewer days than
 #       MIN_BACKUP_RETENTION_DAYS (default 3)
+@@LOG_EXIT_CODE@@
 #
 # Before anything changes, the roll names the point the database can be restored to: the instance, the
 # moment this roll starts, and how long its continuous backups are kept. A roll that mints a new era is
@@ -23,6 +24,7 @@
 # cannot run, the roll goes on. SKIP_LOG_CAPTURE=1 skips it; LOG_CAPTURE_SERVICES="a b" limits it to
 # those services (deploy-service.sh sets the one it rolls).
 #
+@@LOG_NOTE@@
 @@USAGE@@
 set -euo pipefail
 HERE=$(cd "$(dirname "$0")" && pwd)
@@ -37,6 +39,7 @@ DB_HOST=$(out "$RDS_STACK" DbEndpoint)
 @@DB_SECRET_LINE@@
 [ -n "$BOX" ] && [ "$BOX" != None ] || { echo "no instance in stack $BOX_STACK" >&2; exit 40; }
 ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
+@@LOG_GROUP_CHECK@@
 
 if [ "${SKIP_RESTORE_ANCHOR:-}" = 1 ]; then
   echo "==> skipping the restore anchor (SKIP_RESTORE_ANCHOR=1)"