hecks 3.0.5 → 3.1.1

data/lib/hecks/hecks/hecks.hecksagon

@@ -1,9 +1,9 @@
 Hecks.hecksagon "Hecks" do
-  uses_framework "Governance"
+  attaches "Governance"
 
   # The chapters the gem carries: the language declared in itself (Paging comes with Bluebook),
-  # Expression, Tenancy, Deploy and QualityControl (which brings its own ports and adapters).
-  %w[Bluebook Hecksagon World Adapter Port Translation Expression Tenancy Deploy QualityControl]
+  # Expression, Tenancy, Deploy, Site, Tickets and QualityControl (the last three bring their own ports).
+  %w[Bluebook Hecksagon World Adapter Port Translation Expression Tenancy Deploy Site Tickets QualityControl]
     .each { |chapter| attaches chapter }
   # Persistence is not bound here: hecks.world's `default_adapter` binds every aggregate, so
   # environments/memory.world can swap the whole domain without a double bind.
@@ -95,6 +95,12 @@ Hecks.hecksagon "Hecks" do
       answers "DoorAnswered"
       refuses "DoorRefused"
     end
+
+    asks "Scaffold", to: Door do
+      attribute :run, DoorKey
+      answers "DoorAnswered"
+      refuses "DoorRefused"
+    end
   end
 
   Hecks::Door.port "Terminal" do
@@ -103,6 +109,12 @@ Hecks.hecksagon "Hecks" do
       answers "DoorAnswered"
       refuses "DoorRefused"
     end
+
+    asks "Converse", to: Door do
+      attribute :run, DoorKey
+      answers "DoorAnswered"
+      refuses "DoorRefused"
+    end
   end
 
   Hecks::Build.port "RustToolchain" do
@@ -394,7 +406,7 @@ Hecks.hecksagon "Hecks" do
 end
 
 # The one seam where Deploy's "Tenant" (a validated request) becomes Tenancy's "Tenant" (a fact),
-# as tenancy.hecksagon declares it for the chapters booted on their own: `hecks deploy provision`
+# as tenancy.hecksagon declares it for the chapters booted on their own: `hecks deploy tenant.provision`
 # registers the tenant it provisioned. It sits here, after `attaches` has loaded both chapters.
 Hecks.hecksagon "Tenancy" do
   translates "RegisterProvisionedTenant" do

data/lib/hecks/hecks/hecks.world

@@ -15,7 +15,7 @@
 # Postgres (a `postgres://` URL, or a bare database name); otherwise a local database named for
 # the domain. It connects as the ordinary role `hecks`, never a superuser: the era write-fence
 # (row-level security) is bypassed by one, so boot refuses it. Create the role once with
-# `hecks quality_control create_ledger_role hecks` and the database with `createdb -O hecks hecks`.
+# `hecks quality_control sweep.create_ledger_role hecks` and the database with `createdb -O hecks hecks`.
 #
 # PostgresEra versions the storage shape. Once a database holds an era, a later change to this
 # domain's shape needs a translation edge, kept in `translations/` beside the bluebook; an
@@ -26,9 +26,9 @@
 # `failure_states` are the lifecycle states `--wait` reports as exit 1 (every failure state the
 # chapter's lifecycles declare), `names` gives a command the launcher name clients type,
 # `executable` is where `hecks project_cli` writes this chapter's launcher (the gem's
-# `exe/hecks`), `streams` lists the questions `--stream` may tail (`Follow`), `memory_verbs` names
-# the verbs that launcher runs on the Memory environment unless `HECKS_ENVIRONMENT` is set (so
-# `hecks console` needs no database), and `legacy` names the verbs it hands to `Hecks::CLI` in the
+# `exe/hecks`), `streams` lists the questions `--stream` may tail (`Follow`), `memory_commands` names
+# the commands that launcher runs on the Memory environment unless `HECKS_ENVIRONMENT` is set (so
+# `hecks console` needs no database), and `legacy` names the commands it hands to `Hecks::CLI` in the
 # positional forms ADR 0066 shipped.
 Hecks.world "Hecks" do
   realm "Hecks"
@@ -37,10 +37,11 @@ Hecks.world "Hecks" do
   launcher "Launcher", run_keys: true,
                        failure_states: %w[flagged failed drifted unreachable refused faulted halted stopped
                                           abandoned red needs_fix],
-                       names: { "mcp" => "serve_mcp", "console" => "open_console" },
+                       names: { "mcp" => "door.serve_mcp", "console" => "operation.open_console", "init" => "door.init",
+                                "interview" => "door.interview" },
                        streams: %w[Follow],
                        executable: "exe/hecks",
-                       memory_verbs: %w[console],
+                       memory_commands: %w[console init interview],
                        legacy: %w[run docs narrate ir stores model_check smoke_test
                                   project_diagrams project_cli mcp]
 end

data/lib/hecks/hecks/site.behaviors

@@ -0,0 +1,17 @@
+Hecks.behaviors "Site" do
+  vision "A projection of a site's route table is recorded as requested before anything outside is asked."
+
+  loads "hecks.bluebook", "custodian.bluebook", "codebase.bluebook", "context_map.hecksagon", "hecks.hecksagon", "site.world", "environments/memory.world"
+
+  test "ProjectSite keeps a project that has no bluebook as a faulted projection" do
+    tests "ProjectSite", on: "SiteProjection"
+    input run: { value: "routes" }, domain: { value: "/tmp/hecks-behaviors-absent/project" }
+    expect emits: %w[SiteProjectionRequested SiteRefused SiteFaulted]
+  end
+
+  test "ProjectSite refuses a run that is not named" do
+    tests "ProjectSite", on: "SiteProjection"
+    input run: { value: "" }, domain: { value: "/tmp/hecks-behaviors-absent/project" }
+    expect refused: "must match"
+  end
+end

data/lib/hecks/hecks/site.world

@@ -0,0 +1,10 @@
+# The Site chapter's launcher when the Hecks domain attaches it: `hecks site <verb>` reads the
+# world named for the chapter, as `deploy.world` does for the Deploy chapter. Its store is not set
+# here: hecks.world's `default_adapter` fills the gap, so the memory overlay swaps it with the rest.
+#
+# `run_keys` mints the `run` key of a projection, and `--wait` reports a faulted projection (a
+# routes.ts out of date under `--check`, or a route table the projector refused) as exit 1.
+Hecks.world "Site" do
+  launcher "Launcher", run_keys: true,
+                       failure_states: %w[faulted refused halted stopped abandoned red needs_fix]
+end

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

@@ -2,7 +2,7 @@
 # Memory: this chapter is read, never written to a store.
 Hecks.hecksagon "Bluebook" do
   # `role "Language"` is real access control only once Governance can check it (S8).
-  uses_framework "Governance"
+  attaches "Governance"
   persisted_by "Memory"
 end
 

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

@@ -5,9 +5,7 @@ Hecks.bluebook "Hecksagon" do
     identified_by HecksagonName, as: :domain
 
     attribute :subscriptions,      list_of(Subscription)
-    attribute :framework_members,  list_of(FrameworkMember)
-    attribute :vendored_bluebooks, list_of(VendoredBluebook)
-    attribute :attached_chapters,  list_of(AttachedChapter)
+    attribute :attachments,        list_of(Attachment)
 
     value_object "HecksagonName" do
       attribute :value, String
@@ -19,22 +17,20 @@ Hecks.bluebook "Hecksagon" do
       invariant("a subscription names an event") { !value.to_s.empty? }
     end
 
-    # A `framework/bluebook/` member this hecksagon attaches, such as Governance or Identity.
-    value_object "FrameworkMember" do
-      attribute :value, String
-      invariant("a framework member is named") { !value.to_s.empty? }
-    end
-
-    # A separate bluebook package vendored into the consuming project, not shipped in hecks's lib/.
-    value_object "VendoredBluebook" do
-      attribute :value, String
-      invariant("a vendored bluebook is named") { !value.to_s.empty? }
+    # A chapter this hecksagon attaches: `value` is its name, `source` is `gem` for a chapter the
+    # gem carries (a framework member such as Governance, or a language chapter such as Deploy)
+    # or `vendor` for a package vendored into the consuming project, not shipped in hecks's lib/.
+    value_object "Attachment" do
+      attribute :value,  String
+      attribute :source, String, default: "gem"
+      invariant("an attachment is named") { !value.to_s.empty? }
+      invariant("an attachment comes from the gem or from vendor") { source == "gem" || source == "vendor" }
     end
 
-    # A chapter the gem carries (the language, Expression, Tenancy, Deploy) this hecksagon attaches.
-    value_object "AttachedChapter" do
+    # The name an attachment is asked for by, before its source is known.
+    value_object "ChapterName" do
       attribute :value, String
-      invariant("an attached chapter is named") { !value.to_s.empty? }
+      invariant("a chapter is named") { !value.to_s.empty? }
     end
 
     command "Declare" do
@@ -59,35 +55,14 @@ Hecks.bluebook "Hecksagon" do
       emits "SubscriptionAdded"
     end
 
-    command "UsesFramework" do
-      role "Deployment"
-      goal "Attach a framework/bluebook/ member to this hecksagon"
-
-      attribute :member, FrameworkMember
-
-      sets :framework_members, append: { value: :member }
-
-      emits "FrameworkMemberAttached"
-    end
-
-    command "UsesEmbryonautBluebook" do
-      role "Deployment"
-      goal "Attach a vendored, external bluebook to this hecksagon"
-
-      attribute :package, VendoredBluebook
-
-      sets :vendored_bluebooks, append: { value: :package }
-
-      emits "VendoredBluebookAttached"
-    end
-
     command "Attaches" do
       role "Deployment"
-      goal "Attach a chapter the gem carries to this hecksagon, by name"
+      goal "Attach a chapter to this hecksagon, from the gem or from vendor"
 
-      attribute :chapter, AttachedChapter
+      attribute :chapter, ChapterName
+      attribute :source,  String, default: "gem"
 
-      sets :attached_chapters, append: { value: :chapter }
+      sets :attachments, append: { value: :chapter, source: :source }
 
       emits "ChapterAttached"
     end
@@ -107,9 +82,10 @@ 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: "uses_framework",  context: "Hecksagon", body: "none", inner: "", opens: "", fills: "framework_members"
-      member word: "uses_embryonaut_bluebook", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "vendored_bluebooks"
-      member word: "attaches",        context: "Hecksagon", body: "none", inner: "", opens: "", fills: "attached_chapters"
+      member word: "attaches",        context: "Hecksagon", body: "none", inner: "", opens: "", fills: "attachments"
+      # Deprecated spellings of `attaches`; they warn and are removed in 3.2.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"
       # A cross-domain reaction wired here rather than in the bluebook; reuses the Policy context.
       # No `calls:` — HecksagonBuilder#translates is an ordinary method, found before `word_gate`.
@@ -138,9 +114,10 @@ Hecks.bluebook "Hecksagon" do
 
       member keyword: "hecksagon",       context: "File", at: "1", named: "", kind: "text", required: "true", fills: "domain"
       member keyword: "subscribe",       context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "subscriptions"
-      member keyword: "uses_framework",  context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "framework_members"
-      member keyword: "uses_embryonaut_bluebook", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "vendored_bluebooks"
-      member keyword: "attaches",        context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "attached_chapters"
+      member keyword: "attaches",        context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "attachments"
+      member keyword: "attaches",        context: "Hecksagon", at: "",  named: "from", kind: "symbol", required: "false", fills: "source"
+      member keyword: "uses_framework",  context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "attachments"
+      member keyword: "uses_embryonaut_bluebook", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "attachments"
       member keyword: "port",            context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "name"
       member keyword: "translates",      context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "name"
 

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

@@ -16,7 +16,7 @@ module Hecks
 
       # Runs both halves of the era gate over every bluebook in a registry.
       #
-      # Looks up each bluebook's own source separately: `uses_framework` can share a boot between
+      # Looks up each bluebook's own source separately: `attaches` can share a boot between
       # the domain's own bluebook and a differently-sourced one, so one file read once and reused
       # for every bluebook would attribute the wrong text.
       #
@@ -84,7 +84,7 @@ module Hecks
       # Reads the source text one bluebook was declared in, wherever that source lives.
       #
       # Matched by declared name, not position: a domain directory using
-      # `uses_framework` may hold more than one file, and a framework
+      # `attaches` may hold more than one file, and a framework
       # member or vendored bluebook is excluded from the single-file
       # fallback so its own real source is read, not a sibling's.
       #
@@ -150,11 +150,11 @@ module Hecks
       #
       # @param registry [Runtime::Registry] the registry whose hecksagons are searched
       # @param bluebook_name [String] the bluebook's declared Pascal-case name
-      # @return [String, nil] the package name as written in `uses_embryonaut_bluebook`; nil
+      # @return [String, nil] the package name as written in `attaches ... from: :vendor`; nil
       #   when no hecksagon vendored a package whose name Pascal-cases to `bluebook_name`
       def vendored_bluebook_name_for(registry, bluebook_name)
         registry.hecksagons.each_value do |hecksagon|
-          match = hecksagon.vendored_bluebooks.find { |name| Naming.pascal(name) == bluebook_name }
+          match = hecksagon.vendored_packages.find { |name| Naming.pascal(name) == bluebook_name }
           return match if match
         end
         nil

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

@@ -0,0 +1,324 @@
+module Hecks
+  module Projections
+    module Deploy
+      module Box
+        # Resolves a world's `deployed_to("AwsBox")` settings into the checked plan the box
+        # generator renders from.
+        #
+        # Every string that reaches a template or a script is matched against a conservative
+        # pattern first, so a world file cannot splice shell, YAML or Caddy syntax into the output.
+        # A setting the world leaves out resolves to the default the golden stack was built with.
+        module Settings
+          NAME        = /\A[a-z][a-z0-9-]{0,40}\z/
+          REPOSITORY  = %r{\A[a-z0-9][a-z0-9._/-]{1,100}\z}
+          URL_PATH    = %r{\A/[A-Za-z0-9._~!$&'()*+,;=:@%/-]*\z}
+          SECRET_NAME = %r{\A[A-Za-z0-9/_+=.@-]{1,256}\*?\z}
+          ENV_KEY     = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+          ENV_VALUE   = /\A[^\x00-\x1f\x7f]*\z/
+          HEADER      = /\A[A-Za-z][A-Za-z0-9-]{0,63}\z/
+          DB_NAME     = /\A[a-zA-Z][a-zA-Z0-9]{0,62}\z/
+          ENGINE      = /\A\d{2}(\.\d{1,2})?\z/
+          PREFIX      = /\A[a-z][a-z0-9-]{0,20}\z/
+          IMAGE       = %r{\A[a-z0-9][a-z0-9._/:@-]{1,200}\z}
+          TASKDEF     = /\A[a-zA-Z0-9_-]{1,255}\z/
+          SCHEMA      = /\A[a-z][a-z0-9_]{0,62}\z/
+          MIGRATION_SHAPE = "migration: a hash needs `schemas`, a list of the schema names to copy".freeze
+          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
+          # Default images, each a version tag plus the digest of its multi-architecture index,
+          # so a rebuilt box pulls the same bytes.
+          TUNNEL_IMAGE = "cloudflare/cloudflared:2026.9.3" \
+                         "@sha256:072c067d25ccbe61d46e18f0d0723255f2bb5304f7317caa95b27031520ff92c".freeze
+          PROXY_IMAGE  = "public.ecr.aws/docker/library/caddy:2.8" \
+                         "@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_PAIR = "origin_header and origin_secret go together: the header a CDN sends, " \
+                        "and the secret that holds its value".freeze
+
+          # One container the box runs: its image repository, its port and its settings.
+          #
+          # @!attribute [r] name [String] the compose service name
+          # @!attribute [r] repository [String] the ECR repository holding its images
+          # @!attribute [r] port [Integer] the port it listens on, on the box's own network
+          # @!attribute [r] env [Hash{String => String}] plain environment variables
+          # @!attribute [r] secrets [Hash{String => String}] environment variable => secret name,
+          #   resolved on the box at deploy time and never written into a template
+          Container = Struct.new(:name, :repository, :port, :env, :secrets, keyword_init: true)
+
+          # A set of URL paths one container serves.
+          #
+          # @!attribute [r] container [String] the container's name
+          # @!attribute [r] paths [Array<String>] Caddy path patterns, such as "/cms/*"
+          Route = Struct.new(:container, :paths, keyword_init: true)
+
+          # A Cloudflare tunnel the box runs as a service, pointed at one container.
+          #
+          # @!attribute [r] container [String] the container the tunnel forwards to
+          # @!attribute [r] port [Integer] that container's port
+          # @!attribute [r] token_secret [String] the secret holding the tunnel token
+          # @!attribute [r] image [String] the cloudflared image
+          Tunnel = Struct.new(:container, :port, :token_secret, :image, keyword_init: true)
+
+          # The data a project moves from its old database into the new RDS instance.
+          #
+          # @!attribute [r] schemas [Array<String>] the schemas to copy
+          # @!attribute [r] database [String] the database holding them on the RDS instance
+          # @!attribute [r] source_database [String] the database holding them on the old server
+          Migration = Struct.new(:schemas, :database, :source_database, keyword_init: true)
+
+          # An S3 bucket the box's role may read, and in production write.
+          #
+          # @!attribute [r] name [String] the bucket's name
+          # @!attribute [r] write [Boolean] whether a production box may also write and delete
+          Bucket = Struct.new(:name, :write, 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, :tunnel, :tunnel_service, :proxy_image, :task_definition,
+            :migration, :s3_buckets, keyword_init: true
+          ) do
+            # @return [String] the CloudFormation stack that holds the database
+            def rds_stack = "#{stack_prefix}-#{infra_name}-rds"
+
+            # @return [String] the CloudFormation stack that holds the box
+            def box_stack = "#{stack_prefix}-#{infra_name}-box"
+
+            # @return [Container] the container that answers every path no route claims
+            def default
+              containers.find { |c| c.name == default_container }
+            end
+          end
+
+          module_function
+
+          # @param deploy_settings [Hash{Symbol => Object}] the world's `AwsBox` settings
+          # @param target [Object] the validated `BoxTarget` (its instance type, volume, database
+          #   class and storage, already checked by `Declare`)
+          # @param infra_name [String] the stack name the world or the domain gives
+          # @return [Plan] the resolved plan
+          # @raise [ArgumentError] when a setting is missing, malformed or inconsistent
+          def resolve(deploy_settings:, target:, infra_name:)
+            s = deploy_settings
+            check(:stack_name, infra_name, NAME)
+            database_name = read_database_name(s, infra_name)
+            listed = s.fetch(:containers) { raise ArgumentError, missing_containers }
+            task_definition = read_task_definition(s[:task_definition], listed)
+            containers = read_containers(listed, infra_name)
+            header, secret = read_origin(s)
+            tunnel, tunnel_service = read_tunnel(s.fetch(:tunnel, false), containers)
+
+            Plan.new(
+              infra_name: infra_name, stack_prefix: check(:stack_prefix, s.fetch(:stack_prefix, "hecks"), PREFIX),
+              **declared_sizes(target), **read_sizes(s), database_name: database_name,
+              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),
+              tunnel: tunnel, tunnel_service: tunnel_service,
+              proxy_image: check(:proxy_image, s.fetch(:proxy_image, PROXY_IMAGE), IMAGE),
+              task_definition: task_definition, migration: read_migration(s[:migration], database_name),
+              s3_buckets: read_s3_access(s.fetch(:s3_access, []))
+            )
+          end
+
+          # @param target [Object] the declared `BoxTarget`
+          # @return [Hash{Symbol => Object}] the sizes `Declare` has already validated
+          def declared_sizes(target)
+            %i[instance_type volume_gb database_class storage_gb].to_h { |key| [key, target.state[key].value] }
+          end
+
+          # @param settings [Hash{Symbol => Object}] the world's settings
+          # @return [Hash{Symbol => Integer}] swap, backup retention and snapshot retention, bounded
+          def read_sizes(settings)
+            {
+              swap_gb:        integer(:swap_gb, settings.fetch(:swap_gb, 2), 0, 64),
+              backup_days:    integer(:backup_days, settings.fetch(:backup_days, 7), 1, 35),
+              snapshots_keep: integer(:snapshots_keep, settings.fetch(:snapshots_keep, 7), 1, 1000)
+            }
+          end
+
+          # @param value [Hash{Symbol => Object}, nil] the world's `migration` setting
+          # @param database_name [String] the RDS database, which the schemas move into by default
+          # @return [Migration, nil] the data to move, or nil when the world declares none
+          # @raise [ArgumentError] when the setting is not a hash with a non-empty list of schemas
+          def read_migration(value, database_name)
+            return nil if value.nil?
+            raise ArgumentError, MIGRATION_SHAPE unless value.is_a?(Hash)
+
+            listed = value.fetch(:schemas) { raise ArgumentError, MIGRATION_SHAPE }
+            raise ArgumentError, MIGRATION_SHAPE unless listed.is_a?(Array) && !listed.empty?
+
+            database = check(:migration_database, value.fetch(:database, database_name), DB_NAME)
+            Migration.new(schemas: listed.map { |name| check(:migration_schemas, name, SCHEMA) }.uniq, database: database,
+                          source_database: check(:migration_source_database, value.fetch(:source_database, database), DB_NAME))
+          end
+
+          # @param list [Array<Hash>] the world's `s3_access` setting
+          # @return [Array<Bucket>] the buckets, each readable and optionally writable in production
+          # @raise [ArgumentError] when the setting is not a list of bucket hashes
+          def read_s3_access(list)
+            raise ArgumentError, S3_SHAPE unless list.is_a?(Array)
+
+            list.map do |spec|
+              raise ArgumentError, S3_SHAPE unless spec.is_a?(Hash)
+
+              name = check(:s3_bucket, spec.fetch(:bucket) { raise ArgumentError, S3_SHAPE }, S3_BUCKET)
+              Bucket.new(name: name, write: boolean(:s3_write, spec.fetch(:write, false)))
+            end.uniq(&:name)
+          end
+
+          def read_database_name(settings, infra_name)
+            check(:database_name, settings.fetch(:database_name, infra_name.gsub(/[^a-zA-Z0-9]/, "")), DB_NAME)
+          end
+
+          # With a task definition, the images, environment and secrets are read from it at deploy
+          # time, so a container that also sets them is ambiguous and refused.
+          #
+          # @param family [String, nil] the ECS task definition family the world names
+          # @param listed [Array<Hash>] the containers as the world wrote them
+          # @return [String, nil] the checked family, or nil when the world does not use one
+          # @raise [ArgumentError] when the family is malformed or a container sets what it supplies
+          def read_task_definition(family, listed)
+            return nil if family.nil?
+
+            check(:task_definition, family, TASKDEF)
+            Array(listed).each do |spec|
+              clash = spec.is_a?(Hash) ? FROM_TASKDEF & spec.keys : []
+              next if clash.empty?
+
+              raise ArgumentError, "containers: #{spec[:name]} sets #{clash.join(', ')}, which the task definition " \
+                                   "#{family} supplies; drop #{clash.size == 1 ? 'it' : 'them'} or drop task_definition"
+            end
+            family
+          end
+
+          def read_containers(list, infra_name)
+            raise ArgumentError, missing_containers unless list.is_a?(Array) && !list.empty?
+
+            containers = list.map { |c| read_container(c, infra_name) }
+            names = containers.map(&:name)
+            dup = names.find { |n| names.count(n) > 1 }
+            raise ArgumentError, "containers: two containers are named #{dup.inspect}" if dup
+
+            ports = containers.map(&:port)
+            clash = ports.find { |p| ports.count(p) > 1 }
+            raise ArgumentError, "containers: two containers listen on port #{clash}; they share the box's network" if clash
+
+            containers
+          end
+
+          def read_container(spec, infra_name)
+            raise ArgumentError, "containers: each container is a hash, got #{spec.inspect}" unless spec.is_a?(Hash)
+
+            name = check(:container_name, spec.fetch(:name) { raise ArgumentError, "containers: a container has no name" }, NAME)
+            Container.new(
+              name: name, repository: check(:repository, spec.fetch(:repository, "#{infra_name}-#{name}"), REPOSITORY),
+              port: integer(:port, spec.fetch(:port) { raise ArgumentError, "containers: #{name} has no port" }, 1, 65_535),
+              env: string_map(:env, spec.fetch(:env, {}), ENV_KEY, ENV_VALUE),
+              secrets: string_map(:secrets, spec.fetch(:secrets, {}), ENV_KEY, SECRET_NAME)
+            )
+          end
+
+          def read_routes(list, containers)
+            raise ArgumentError, "routes: expected a list" unless list.is_a?(Array)
+
+            list.map { |spec| read_route(spec, containers) }
+          end
+
+          def read_route(spec, containers)
+            container = spec.fetch(:container) { raise ArgumentError, "routes: a route has no container" }
+            name = check(:route_container, container, NAME)
+            known_container!(:routes, name, containers)
+            paths = Array(spec.fetch(:paths) { raise ArgumentError, "routes: the route for #{name} has no paths" })
+            raise ArgumentError, "routes: the route for #{name} has no paths" if paths.empty?
+
+            Route.new(container: name, paths: paths.map { |p| check(:path, p, URL_PATH) })
+          end
+
+          def read_default(name, containers)
+            return containers.first.name if name.nil? && containers.size == 1
+            raise ArgumentError, "default_container: name the container that answers every other path" if name.nil?
+
+            known_container!(:default_container, check(:default_container, name, NAME), containers)
+          end
+
+          def known_container!(key, name, containers)
+            return name if containers.any? { |c| c.name == name }
+
+            raise ArgumentError, "#{key}: #{name.inspect} is not a declared container"
+          end
+
+          def read_origin(settings)
+            header = settings[:origin_header]
+            secret = settings[:origin_secret]
+            return [nil, nil] if header.nil? && secret.nil?
+            raise ArgumentError, ORIGIN_PAIR if header.nil? || secret.nil?
+
+            [check(:origin_header, header, HEADER), check(:origin_secret, secret, SECRET_NAME)]
+          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
+          # @param containers [Array<Container>] the declared containers
+          # @return [Array(Boolean, Tunnel)] whether the egress opens, and the service if one runs
+          def read_tunnel(value, containers)
+            return [boolean(:tunnel, value), nil] unless value.is_a?(Hash)
+
+            to = value.fetch(:to) { raise ArgumentError, TUNNEL_SHAPE }
+            target = known_container!(:tunnel, check(:tunnel_to, to, NAME), containers)
+            token = check(:tunnel_token_secret, value.fetch(:token_secret) { raise ArgumentError, TUNNEL_SHAPE }, SECRET_NAME)
+            image = check(:tunnel_image, value.fetch(:image, TUNNEL_IMAGE), IMAGE)
+            port = containers.find { |c| c.name == target }.port
+            [true, Tunnel.new(container: target, port: port, token_secret: token, image: image)]
+          end
+
+          def read_prefixes(settings, infra_name)
+            list = Array(settings.fetch(:secret_prefixes, ["#{infra_name}/*"]))
+            list.map { |p| check(:secret_prefixes, p, SECRET_NAME) }
+          end
+
+          def string_map(key, value, key_pattern, value_pattern)
+            raise ArgumentError, "#{key}: expected a hash" unless value.is_a?(Hash)
+
+            value.to_h { |k, v| [check(key, k.to_s, key_pattern), check(key, v.to_s, value_pattern)] }
+          end
+
+          def check(key, value, pattern)
+            return value if value.is_a?(String) && value.match?(pattern)
+
+            raise ArgumentError, "#{key}: #{value.inspect} does not match #{pattern.inspect}"
+          end
+
+          def integer(key, value, low, high)
+            return value if value.is_a?(Integer) && value.between?(low, high)
+
+            raise ArgumentError, "#{key}: #{value.inspect} must be an integer from #{low} to #{high}"
+          end
+
+          def boolean(key, value)
+            return value if [true, false].include?(value)
+
+            raise ArgumentError, "#{key}: #{value.inspect} must be true or false"
+          end
+
+          def missing_containers
+            <<~MSG
+              deployed_to("AwsBox") needs at least one container. Add one, e.g.:
+
+                  deployed_to("AwsBox") do
+                    region "us-east-1"
+                    containers [{ name: "web", port: 8080 }]
+                  end
+            MSG
+          end
+        end
+      end
+    end
+  end
+end