hecks 2.8.0 → 2.9.0

data/lib/hecks/projections/deploy/preview/template.rb

@@ -8,28 +8,8 @@ module Hecks
   module Projections
     module Deploy
       module Preview
-        # Renders `preview.yaml`, the CloudFormation template of one
-        # per-branch preview stack.
-        #
-        # A separate template rather than conditions threaded through the main
-        # one, so a preview can never put the main stack's live resources in a
-        # change set. The two share a task shape and nothing else.
-        #
-        # ## What a preview owns
-        #
-        # Per branch: a cluster, service and task, a load balancer, one image
-        # repository per container, a session secret, any secrets a container
-        # declares, a log group, a CloudFront distribution (default hostname,
-        # nothing cached) and a database name on the shared instance, created
-        # by a one-shot task before the service starts.
-        #
-        # ## What it borrows and leaves out
-        #
-        # It attaches to the owner stack's VPC, subnets and compute security
-        # group and connects to the shared database instance, through the same
-        # `Owning*` parameters the main template takes for `database "Shared"`.
-        # It has no alarms, no notifications, no warmer and no custom domain:
-        # nobody should be paged for a preview.
+        # Renders `preview.yaml`, one per-branch preview stack's CloudFormation template.
+        # Kept separate from the main one, so a preview can never enter a change set against it.
         module Template
           CACHING_DISABLED = "4135ea2d-6df8-44a3-9df3-4b5a84be39ad".freeze
           ALL_VIEWER = "216adef6-5c7f-47e4-b989-5492eafa07d3".freeze
@@ -38,10 +18,6 @@ module Hecks
 
           module_function
 
-          # Renders the whole template.
-          #
-          # @param settings [Settings] the resolved preview settings
-          # @return [String] the CloudFormation YAML, ending in one newline
           def render(settings)
             [
               header(settings), parameters(settings),
@@ -50,10 +26,6 @@ module Hecks
             ].join("\n") << "\n"
           end
 
-          # Renders the file's leading comment and template description.
-          #
-          # @param settings [Settings] the resolved preview settings
-          # @return [String] the header block
           def header(settings)
             <<~YAML.chomp
               # GENERATED by bin/project_deploy - re-run it to refresh this file rather than
@@ -75,10 +47,6 @@ module Hecks
             YAML
           end
 
-          # Renders the parameters section.
-          #
-          # @param settings [Settings] the resolved preview settings
-          # @return [String] the section, one image-tag parameter per container
           def parameters(settings)
             image_tags = settings.containers.map do |c|
               <<~YAML.chomp
@@ -90,9 +58,6 @@ module Hecks
             "Parameters:\n#{indent([base_parameters, *image_tags, desired_count_parameter].join("\n"), 2)}"
           end
 
-          # Renders the parameters every preview takes: its name, database and the borrowed network.
-          #
-          # @return [String] the parameter blocks
           def base_parameters
             <<~YAML.chomp
               EnvName:
@@ -122,9 +87,6 @@ module Hecks
             YAML
           end
 
-          # Renders the parameter `preview.sh` uses to start the stack at zero tasks.
-          #
-          # @return [String] the parameter block
           def desired_count_parameter
             <<~YAML.chomp
               # The repositories are created by this stack, so the first create has no image to
@@ -135,10 +97,6 @@ module Hecks
             YAML
           end
 
-          # Collects every resource block of the template.
-          #
-          # @param settings [Settings] the resolved preview settings
-          # @return [Array<String>] the resource blocks, in template order
           def resources(settings)
             [
               AccessYaml.secrets(settings), RoutingYaml.networking(settings), repositories(settings),
@@ -149,10 +107,6 @@ module Hecks
             ].flatten
           end
 
-          # Renders one image repository per container, emptied when the stack is deleted.
-          #
-          # @param settings [Settings] the resolved preview settings
-          # @return [Array<String>] the resource blocks
           def repositories(settings)
             settings.containers.map do |c|
               <<~YAML.chomp
@@ -165,10 +119,6 @@ module Hecks
             end
           end
 
-          # Renders the cluster and the log group.
-          #
-          # @param settings [Settings] the resolved preview settings
-          # @return [Array<String>] the two resource blocks
           def cluster_and_logs(settings)
             [
               <<~YAML.chomp,
@@ -187,9 +137,6 @@ module Hecks
             ]
           end
 
-          # Renders the CDN distribution, which caches nothing.
-          #
-          # @return [String] the resource block
           def distribution
             <<~YAML.chomp
               # One behavior, nothing cached: a preview is for looking at a change, so no cache means
@@ -219,9 +166,6 @@ module Hecks
             YAML
           end
 
-          # Renders the outputs `preview.sh` reads back.
-          #
-          # @return [String] the section
           def outputs
             <<~YAML.chomp
               Outputs:

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

@@ -5,73 +5,8 @@ require_relative "preview/script"
 module Hecks
   module Projections
     module Deploy
-      # Per-branch preview stacks for a `deployed_to("AwsFargate")` domain: one
-      # isolated copy of the stack per git branch, created and torn down by a
-      # generated script.
-      #
-      # Opt-in. A domain with no `preview` setting gets exactly the files it
-      # got before; `Fargate.call` asks `requested?` and merges in `call`'s
-      # files only when the answer is yes.
-      #
-      # ## What is generated
-      #
-      # - `preview.yaml`: a separate CloudFormation template, so a preview never
-      #   appears in a change set against the live stack (see `Template`).
-      # - `preview.sh`: `deploy` (create or update), `destroy`, `list`, `url`,
-      #   `name`, `ensure-database` and `login` (see `Script`).
-      # - The database step is a one-shot task declared in `preview.yaml`
-      #   and run by `preview.sh`; there is no separate file, because the
-      #   instance is reachable only from inside the VPC.
-      #
-      # ## Settings
-      #
-      # ```ruby
-      # deployed_to("AwsFargate") do
-      #   region "us-east-1"
-      #   preview do
-      #     containers [{ name: "web", port: 8080, host: true, default: true }]
-      #   end
-      # end
-      # ```
-      #
-      # `preview true` and a block with no settings accept every default. Keys:
-      #
-      # - `prefix`: stack, cluster, service and image repository name prefix.
-      #   Default `<stack_prefix>-<stack>-preview`.
-      # - `alb_prefix`: load balancer name prefix, at most 11 characters.
-      #   Default the first 8 letters of the stack name plus `pv`.
-      # - `owner_stack`: the stack whose VPC, subnets and compute security group
-      #   the preview attaches to. Default the `owner_stack` of a Shared main
-      #   stack, else the main stack.
-      # - `database_stack`: the stack whose outputs name the shared database
-      #   instance. Default `owner_stack`.
-      # - `database_endpoint_output`, `database_secret_output`: the output keys
-      #   holding the instance host and the master secret ARN. Defaults
-      #   `DatabaseEndpoint` and `DatabaseSecretArn`.
-      # - `db_prefix`: a preview's database is `<db_prefix>_pv_<env>`. Default
-      #   the stack name, lowercased, at most 30 characters.
-      # - `protected_databases`: names the database task refuses, added to the
-      #   main database, `postgres` and the two template databases. Default `[]`.
-      # - `protected_branches`: branches `preview.sh` refuses. Default
-      #   `["main", "master"]`.
-      # - `cpu`, `memory`: task size. Default the main stack's.
-      # - `log_retention_days`: a value CloudWatch accepts. Default `7`.
-      # - `session_cookie`: cookie name; sets `HECKS_SESSION_COOKIE` on the host
-      #   and is what `login` writes. Default the host's own default.
-      # - `first_admin`: whether `preview.sh` signs the deployer up and offers
-      #   `login`. Default `true`.
-      # - `signup_path`: the host route the signup posts to. Default `/signups`.
-      # - `landing_path`: the page `login` points the browser at. Default `/`.
-      # - `db_init_image`: image of the database task; needs `sh` and `psql`.
-      #   Default the public Postgres 16 alpine image.
-      # - `containers`: the containers the preview task runs. Default the main
-      #   stack's container list; see `Containers` for the entry keys.
-      #
-      # ## Why a preview mints no era and needs no bastion
-      #
-      # The host mints era 1 itself on an empty database, and the database
-      # task runs inside the VPC, so neither the main stack's bastion nor a
-      # tunnel is involved.
+      # Per-branch preview stacks for a `deployed_to("AwsFargate")` domain, opt-in
+      # via a `preview` setting; the host mints era 1 itself, so no bastion is needed.
       module Preview
         module_function
 

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

@@ -2,21 +2,8 @@ module Hecks
   module Projections
     module Deploy
       module Scripts
-        # The `deployed_to("AwsFargate")` settings the hosting scripts read,
-        # with their defaults and the check each value must pass.
-        #
-        # Every value ends up inside a shell script or a Makefile, so each one
-        # is refused unless it matches a conservative pattern for what it names
-        # (a region, a cluster, a GitHub repository). That check is what lets
-        # the renderers write values without per-context escaping.
-        #
-        # The containers, their ECR repositories and image-tag parameters, and
-        # the default cluster and service names are not settings here. They come
-        # from the template generator's own resolved plan
-        # (`Fargate::Settings::Plan`), so a script can only name what the
-        # generated `template.yaml` defines.
-        #
-        # The keys are documented on `Scripts`.
+        # The `deployed_to("AwsFargate")` settings the hosting scripts read, checked
+        # against a conservative pattern so a renderer can splice one in without escaping.
         class Settings
           RESOURCE  = /\A[a-zA-Z0-9][a-zA-Z0-9_-]*\z/
           REGION    = /\A[a-z]{2}(-[a-z]+)+-\d\z/
@@ -34,16 +21,7 @@ module Hecks
           attr_reader :region, :stack, :cluster, :service, :containers, :hecks_release, :hecks_source,
                       :hecks_cache_dir, :smoke_repo, :smoke_workflow, :smoke_ref, :expected_eras, :public_url
 
-          # Reads and checks every hosting setting.
-          #
-          # @param deploy_settings [Hash{Symbol => Object}] the world's
-          #   `deployed_to("AwsFargate")` settings
-          # @param plan [Fargate::Settings::Plan] the template generator's resolved settings:
-          #   its `layout` holds the containers, its `names` the cluster and service
-          # @param stack_name [String] the CloudFormation stack
-          # @param region [String] the validated AWS region
-          # @raise [ArgumentError] if `hecks_release` is missing, or a value
-          #   does not match the pattern for what it names
+          # `plan.layout` holds the containers; `plan.names` the cluster and service.
           def initialize(deploy_settings:, plan:, stack_name:, region:)
             @raw = deploy_settings
             @region = check(:region, region, REGION)

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

@@ -4,64 +4,11 @@ require_relative "scripts/settings"
 module Hecks
   module Projections
     module Deploy
-      # The hosting scripts an AWS Fargate deploy ships beside its template:
-      # the steps an operator runs after `make deploy` has created the stack.
-      # `Fargate.call` adds them when the domain's
-      # `deployed_to("AwsFargate")` block opts in, and leaves its file map
-      # untouched otherwise.
-      #
-      # ## What it emits
-      #
-      # - `deploy-service.sh` reads the service's active task definition,
-      #   pushes a local image under a never-reused tag, swaps one container's
-      #   image, and syncs that container's CloudFormation `*ImageTag`
-      #   parameter with `--use-previous-template`, checking afterwards that no
-      #   other parameter changed.
-      # - `smoke-after-deploy.sh` waits for the roll to settle, then dispatches
-      #   a GitHub workflow and reports its result. Exit codes 20 to 23 are its
-      #   own.
-      # - `hosting.mk` is included by the generated `Makefile`. It pins the
-      #   Hecks release the domain image is built from (`HECKS_ROOT` resolves
-      #   to a cached checkout of that release's tag, never to a path on one
-      #   machine) and adds the `deploy-service`, `smoke-after-deploy` and
-      #   `check-era` targets.
-      # - `expected-era` is the allow-list `bin/check_era` compares a host's
-      #   `GET /version` era against.
-      #
-      # ## Settings
-      #
-      # Read from `deployed_to("AwsFargate")`. Everything but `hosting_scripts`
-      # and `hecks_release` has a default; the ones the stack template already
-      # names (`stack_name`, `stack_prefix`, `region`) are not repeated here.
-      #
-      # - `hosting_scripts` opts in to every file above, when `true`. Off by default.
-      # - `hecks_release` is the Hecks release the domain image is built from,
-      #   such as `"2.5.1"`. Required.
-      # - `hecks_source` is the repository URL the release tag is fetched from.
-      #   Defaults to the Hecks repository.
-      # - `hecks_cache_dir` is where release checkouts are kept, a Make expression.
-      #   Defaults to `$(HOME)/.cache/hecks`.
-      # - `ecs_cluster` and `ecs_service` name the cluster and service. They default to the
-      #   names the generated template gives them: the stack name, or the `names` override.
-      # - `smoke_repo` is the GitHub `owner/name` holding the smoke workflow, and
-      #   `smoke_workflow` its file name. With neither set, `REPO` and `WORKFLOW` must
-      #   come from the environment.
-      # - `smoke_ref` is the ref the workflow is dispatched on. Defaults to `main`.
-      # - `expected_eras` lists the era ids `expected-era` holds. Defaults to none, so a
-      #   host is only checked to report an era.
-      # - `public_url` is the host URL `make check-era` requests. Without it, `URL` must
-      #   be passed to `make`.
-      #
-      # ## Names come from the template
-      #
-      # The containers, their ECR repositories and their image-tag parameters are not
-      # settings of the scripts. `deploy-service.sh` accepts exactly the containers the
-      # template's `Fargate::Containers::Layout` holds (the domain container, then each
-      # entry of the world's `containers`), and for each one pushes to the repository and
-      # syncs the parameter that layout names: the values the template renders. Rename them
-      # with `domain_container` and `containers` (see `Fargate`), and the scripts, and the
-      # `Makefile`'s `deploy`, follow.
+      # The hosting scripts an AWS Fargate deploy ships beside its template: the steps an
+      # operator runs after `make deploy` has created the stack.
       module Scripts
+        # Container names, repositories and image-tag parameters come from `plan`, not
+        # from a setting here; rename them in `Fargate::Settings::Plan` and these scripts follow.
         SCRIPT_DIR = File.join(__dir__, "scripts").freeze
 
         module_function

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

@@ -1,57 +1,22 @@
 module Hecks
   module Projections
     module Deploy
-      # Plumbing `Lambda` and `Fargate` both need — VPC/subnet/security-group
-      # resources, RDS/Aurora, `bastion.yaml`, and a cross-domain policy's
-      # own least-privilege invoke grant are the same problem (get a
-      # domain's own Postgres instance stood up and reachable for the one
-      # boot that mints era 1, and let a domain call another domain's
-      # Lambda) whichever compute target ships the domain's own code.
-      #
-      # Plain module functions, not a registered `Projector::Target` — this
-      # has no `deployed_to(...)` block of its own to generate from, only
-      # helpers the two real targets call with the facts they have already
-      # resolved (`db_id`, `aurora`, `google_oauth_present`, and so on).
-      #
-      # Every `*_table` method here answers the same `key`/`var`/`name`
-      # strings regardless of which target built them — `stack_outputs`'
-      # own `"FunctionSecurityGroupId"` key, in particular, is what a
-      # Shared-mode domain looks up from its owner's stack (`bin/project_deploy`'s
-      # own Shared-mode branch), and that lookup has to succeed the same
-      # way whether the owner is a `Lambda` or a `Fargate` deploy.
+      # VPC, RDS/Aurora, bastion and cross-domain invoke plumbing shared by the
+      # `Lambda` and `Fargate` deploy targets. Plain module functions, not a Target.
       module Shared
         module_function
 
-        # The stack↔bastion contract — one shared table each of
-        # `template.yaml`'s Outputs, `bastion.yaml`'s Parameters, and a
-        # Makefile's own eval/`--parameter-overrides` lines reads from,
-        # instead of three to four independent string literals per fact
-        # with nothing checking they agree. `var` is the Make variable
-        # each output becomes.
+        # The stack-to-bastion contract: one table that `template.yaml` Outputs,
+        # `bastion.yaml` Parameters and the Makefile overrides all read from.
+        # Empty when `shared`, since such a domain provisions no VPC/RDS of its own.
         #
-        # Empty when `shared` — a Shared-mode domain provisions no
-        # VPC/RDS of its own to expose at all (`bastion_parameters`,
-        # `bastion_yaml`, and era-minting are all skipped for the same
-        # reason: there's nothing here for a bastion to reach). A
-        # Shared-mode domain's own stack is never an owner, so nothing
-        # downstream ever needs to look these up from it either.
-        #
-        # @param shared [Boolean] whether this domain borrows another domain's
-        #   RDS instance (`database "Shared"`) rather than provisioning its own
-        # @param db_id [String] the RDS/VPC resources' own shared logical-id prefix
-        # @param db_ref_id [String] the logical id `.Endpoint`/`.MasterUserSecret` resolve
-        #   against — `db_id` itself for plain RDS, `"#{db_id}Cluster"` for Aurora
-        # @param secret_intrinsic [String] the rendered `!Ref`/`!GetAtt` expression for
-        #   this domain's own database secret
-        # @param compute_security_group_ref [String] the `!Ref` expression for the
-        #   compute resource's own security group (a Lambda function's, an `ECS`
-        #   service's) — reused by a Shared-mode domain elsewhere to attach its own
-        #   compute to this domain's VPC without minting a security group of its own
-        # @param google_oauth_present [Boolean] whether this domain's own NAT
-        #   Gateway/public-subnet resources exist, and so whether `PublicSubnetId`/
-        #   `BastionSubnetId` are real outputs to expose
-        # @return [Array<Hash{Symbol => String}>] frozen; each entry a `{key:, var:,
-        #   ref:}` triple
+        # @param shared [Boolean] whether this domain borrows another domain's RDS instance
+        # @param db_id [String] shared logical-id prefix of the RDS/VPC resources
+        # @param db_ref_id [String] logical id `.Endpoint` resolves against (Cluster for Aurora)
+        # @param secret_intrinsic [String] rendered `!Ref`/`!GetAtt` for the database secret
+        # @param compute_security_group_ref [String] `!Ref` for the compute's security group
+        # @param google_oauth_present [Boolean] whether the NAT/public-subnet resources exist
+        # @return [Array<Hash{Symbol => String}>] frozen `{key:, var:, ref:}` entries
         def stack_outputs(shared:, db_id:, db_ref_id:, secret_intrinsic:, compute_security_group_ref:, google_oauth_present:)
           return [].freeze if shared
 
@@ -60,44 +25,25 @@ module Hecks
             { key: "DbSecurityGroupId", var: "DB_SG_ID",       ref: "!Ref #{db_id}SecurityGroup" },
             { key: "DatabaseEndpoint",  var: "DB_HOST",       ref: "!GetAtt #{db_ref_id}.Endpoint.Address" },
             { key: "DatabaseSecretArn", var: "DB_SECRET_ARN", ref: secret_intrinsic },
-            # Not consumed by anything in this domain's own generated output —
-            # a "Shared"-mode domain elsewhere looks these two up live to
-            # attach its own compute to this domain's VPC/security group
-            # without minting either itself.
+            # Read live by a Shared-mode domain to attach its compute to this VPC.
             { key: "FunctionSecurityGroupId", var: "FN_SG_ID",            ref: compute_security_group_ref },
             { key: "PrivateSubnetAId",        var: "PRIVATE_SUBNET_A_ID", ref: "!Ref #{db_id}SubnetA" },
             { key: "PrivateSubnetBId",        var: "PRIVATE_SUBNET_B_ID", ref: "!Ref #{db_id}SubnetB" },
-            # Only when google_oauth_present — #{db_id}PublicSubnet (and the
-            # Internet Gateway it's attached through) only exist as resources
-            # at all when the NAT Gateway block does. `bastion.yaml` needs
-            # this: a VPC accepts only one attached Internet Gateway, and one
-            # already exists once this is true — its own temporary IGW+subnet
-            # would collide (a real, live "Resource.AlreadyAssociated").
+            # A VPC accepts one Internet Gateway; `bastion.yaml` must reuse this subnet's
+            # rather than mint its own (Resource.AlreadyAssociated).
             *(google_oauth_present ? [{ key: "PublicSubnetId", var: "PUBLIC_SUBNET_ID", ref: "!Ref #{db_id}PublicSubnet" }] : []),
-            # A separate subnet from PublicSubnetId, same shared route
-            # table/Internet Gateway -- #{db_id}PublicSubnet always lands in
-            # AZ index 0 (`!Select [0, !GetAZs '']`), and a real, live
-            # CREATE_FAILED caught this account unable to launch any EC2
-            # instance there at all ("Your requested instance type ... is
-            # not supported in your requested Availability Zone
-            # (us-east-1a)") -- NatGateway and RDS aren't EC2 instances and
-            # never hit this, only BastionInstance does. AZ index 1 instead,
-            # matching #{db_id}SubnetB's own choice.
+            # Separate AZ-1 subnet: EC2 instances cannot launch in AZ index 0 on this
+            # account, which only the bastion hits.
             *(google_oauth_present ? [{ key: "BastionSubnetId", var: "BASTION_SUBNET_ID", ref: "!Ref #{db_id}BastionPublicSubnet" }] : []),
           ].freeze
         end
 
-        # `bastion.yaml`'s own Parameters — deliberately allowed to rename
-        # (`RdsSecurityGroupId` reads better inside `bastion.yaml` than the
-        # stack output's own `DbSecurityGroupId`), which is exactly the kind
-        # of rename that can silently drift between the two files without
-        # this shared table.
+        # `bastion.yaml`'s Parameters, kept in one table so renames cannot drift
+        # from the stack outputs.
         #
-        # @param shared [Boolean] whether this domain borrows another domain's
-        #   RDS instance — see `stack_outputs`' own comment
+        # @param shared [Boolean] see `stack_outputs`
         # @param google_oauth_present [Boolean] see `stack_outputs`
-        # @return [Array<Hash{Symbol => String}>] frozen; each entry a `{name:,
-        #   from_output:, type:}` triple
+        # @return [Array<Hash{Symbol => String}>] frozen `{name:, from_output:, type:}` entries
         def bastion_parameters(shared:, google_oauth_present:)
           return [].freeze if shared
 
@@ -109,16 +55,9 @@ module Hecks
           ].freeze
         end
 
-        # A generation-time assertion, not a bluebook refusal — this is the
-        # generator catching its own bug immediately, before writing a
-        # single file, instead of producing a `bastion.yaml` whose Parameter
-        # nothing could ever fill.
+        # Generation-time check that every bastion parameter maps to a stack output.
         #
-        # @param bastion_parameters [Array<Hash{Symbol => String}>] as `bastion_parameters` builds
-        # @param stack_outputs [Array<Hash{Symbol => String}>] as `stack_outputs` builds
-        # @return [void]
-        # @raise [RuntimeError] if any parameter names a `from_output` absent from
-        #   `stack_outputs`
+        # @raise [RuntimeError] if a parameter names a `from_output` absent from `stack_outputs`
         def check_bastion_parameters!(bastion_parameters, stack_outputs)
           bastion_parameters.each do |param|
             stack_outputs.any? { |o| o[:key] == param[:from_output] } or
@@ -126,27 +65,13 @@ module Hecks
           end
         end
 
-        # Renders the least-privilege IAM grant a cross-domain policy's own
-        # invoke needs — one `lambda:InvokeFunction` statement per declared
-        # `across:` target, appended to the compute role's existing
-        # `Policies:` list. `rust/host`'s own `lambda_client.rs`
-        # (`AwsLambdaInvoker`) is the one piece of a cross-domain dispatch
-        # path that needs this at all, regardless of which compute target
-        # ships the calling domain's own code — a Fargate task and a Lambda
-        # function both reach another domain's dispatch Lambda the same way.
-        #
-        # Declared, not deployed: an ARN naming a function that does not
-        # exist yet is still valid IAM policy — the call simply fails with
-        # `ResourceNotFoundException` instead of `AccessDeniedException`
-        # until the target domain is deployed for real.
+        # Renders one `lambda:InvokeFunction` IAM statement per `across:` target,
+        # to append to the compute role's `Policies:` list.
+        # An ARN for a not-yet-deployed function is valid IAM; the call just fails until then.
         #
-        # @param targets [Array<String>] the domain names this stack's `across:` targets
-        #   declare
-        # @param base [String] the marker line's own rendered indentation whitespace;
-        #   everything below is built relative to it
-        # @return [String] the rendered comment plus one `Statement`-shaped IAM policy
-        #   entry granting invoke on each target's function ARN, ending in exactly one
-        #   trailing newline; an empty string if `targets` is empty
+        # @param targets [Array<String>] domain names declared by `across:`
+        # @param base [String] indentation of the marker line
+        # @return [String] the YAML ending in one newline; empty if `targets` is empty
         def cross_domain_invoke_policy_yaml(targets, base)
           return "" if targets.empty?
 
@@ -173,32 +98,18 @@ module Hecks
           ].join("\n") + "\n"
         end
 
-        # Renders one domain's own private VPC, subnets, RDS/Aurora Postgres
-        # instance, and the two security groups pairing it with its compute
-        # — everything `Lambda` and `Fargate` both need to give a
-        # non-`"Shared"`-mode domain a real, reachable Postgres endpoint.
-        # Dedented flush-left, the same shape a caller's own enclosing
-        # `<<~` heredoc expects to reindent as it splices this in.
+        # Renders a domain's private VPC, subnets, RDS/Aurora Postgres and the two
+        # security groups pairing it with its compute, dedented flush-left.
+        # The compute group has no inbound rule; it only needs egress to the database.
         #
-        # `compute_logical_id`'s own security group carries no inbound rule
-        # at all — neither a Lambda function nor a Fargate task/`ALB` target
-        # group receives traffic over this VPC-attached `ENI` directly, only
-        # egress to the database (and, when `google_oauth_present`, to the
-        # internet for a real OAuth token exchange).
-        #
-        # @param db_id [String] the RDS/VPC resources' own shared logical-id prefix
-        # @param db_name [String] the database identifier RDS/Aurora provisions
-        # @param infra_name [String] the domain's own AWS-facing name, quoted in the
-        #   `DBSubnetGroupDescription`
+        # @param db_id [String] shared logical-id prefix of the RDS/VPC resources
+        # @param db_name [String] database identifier RDS/Aurora provisions
+        # @param infra_name [String] AWS-facing domain name, quoted in the subnet group description
         # @param aurora [Boolean] Aurora Serverless v2 when true, plain RDS otherwise
-        # @param google_oauth_present [Boolean] whether a NAT Gateway, public subnet, and
-        #   the compute security group's own internet egress rule are needed
-        # @param compute_logical_id [String] the compute resource's own logical id,
-        #   naming its security group and egress rules
-        # @param compute_description [String] the compute security group's own
-        #   `GroupDescription` text — what actually terminates the `ENI` this ingress
-        #   pairs with
-        # @return [String] the rendered CloudFormation Resources, flush-left
+        # @param google_oauth_present [Boolean] whether to add a NAT Gateway and internet egress
+        # @param compute_logical_id [String] logical id naming the compute's security group
+        # @param compute_description [String] the compute security group's `GroupDescription`
+        # @return [String] the rendered CloudFormation Resources
         def vpc_and_database_yaml(db_id:, db_name:, infra_name:, aurora:, google_oauth_present:, compute_logical_id:, compute_description:)
           <<~OWNDB.rstrip
             #{db_id}Vpc:
@@ -466,25 +377,15 @@ module Hecks
           OWNDB
         end
 
-        # Renders the temporary era-minting bastion — a standalone
-        # CloudFormation template, deployed and destroyed by `make
-        # mint-era`, never merged into the main stack. SSM Session Manager
-        # only, never SSH: no key pair, no inbound security group rule at
-        # all — the only way in is `aws ssm start-session`, itself gated by
-        # the caller's own IAM permissions.
-        #
-        # Callers skip this entirely when `shared` — a Shared-mode domain
-        # provisions no RDS/VPC of its own for a bastion to reach, and era-
-        # minting for it reuses its owner's own already-standing bastion
-        # path instead.
+        # Renders the temporary era-minting bastion: a standalone template deployed
+        # and destroyed by `make mint-era`. SSM Session Manager only, no inbound rules.
+        # Callers skip this when `shared`, as there is no RDS/VPC for it to reach.
         #
-        # @param domain [String] the domain directory's path, named in the header comment
-        # @param infra_name [String] the domain's own AWS-facing name
-        # @param stack_name [String] the main stack's own name, tagged onto the bastion instance
-        # @param db_id [String] the RDS/VPC resources' own shared logical-id prefix, as
-        #   `vpc_and_database_yaml` names them
-        # @param google_oauth_present [Boolean] whether the main stack already has its own
-        #   public subnet/Internet Gateway to reuse, rather than minting a second one
+        # @param domain [String] domain directory path, named in the header comment
+        # @param infra_name [String] AWS-facing domain name
+        # @param stack_name [String] main stack name, tagged onto the instance
+        # @param db_id [String] shared logical-id prefix, as `vpc_and_database_yaml` names it
+        # @param google_oauth_present [Boolean] reuse the stack's public subnet, mint none
         # @param bastion_parameters [Array<Hash{Symbol => String}>] as `bastion_parameters` builds
         # @return [String] the rendered CloudFormation template
         def bastion_yaml(domain:, infra_name:, stack_name:, db_id:, google_oauth_present:, bastion_parameters:)