@zaaxch/tailframe 4.0.1 → 4.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zaaxch/tailframe",
-	"version": "4.0.1",
+	"version": "4.0.2",
 	"description": "Tailframe architecture toolkit: validates the Tailframe structure, import-boundary, and file-convention contracts. The package version is the contract version.",
 	"type": "module",
 	"bin": {

package/src/new.mjs

@@ -243,8 +243,7 @@ add(`${svc}/package.json`, JSON.stringify({
 		"schema:apply": "node dist/app/cli/applySchema.js", "schema:apply:dev": "ts-node -r tsconfig-paths/register src/app/cli/applySchema.ts",
 		"test:db:up": "docker compose -f docker-compose.test.yml up -d", "test:db:down": "docker compose -f docker-compose.test.yml down -v",
 		"docker:dev": "docker compose -f docker-compose.dev.yml up",
-		"docker:prod": "docker compose -f docker-compose.yml up -d",
-		"docker:push": "bash scripts/build_and_push.sh"
+		"docker:prod": "docker compose -f docker-compose.yml up -d"
 	}, dependencies: svcDeps, devDependencies: svcDevDeps
 }, null, "\t"));
 add(`${svc}/tsconfig.json`, JSON.stringify({
@@ -552,10 +551,10 @@ ${options.ui ? "- In production, serve the compiled UI from `dist/public` with a
 The ECR build targets \`linux/amd64\`. ${options.ui ? "Its default immutable tag is `<product-sha>` and production Compose requires that exact tag." : "Its default immutable tag is `<product-sha>` and production Compose requires that exact tag."} The runtime image contains production dependencies only and runs as the Node user.${options.ui && options.auth === "firebase" ? ` The build requires \`${ui}/.env.production\` and mounts it as a BuildKit secret only while Vite compiles the browser bundle; it is not copied into the final image.` : ""}
 
 ## Production deployment
-Only service \`main\` pushes or manual workflow dispatch deploy; UI pushes never trigger deployment. GitHub Actions may replace files under \`/opt/${options.name}/current\` and MUST NOT replace persistent configuration, credentials, keyfiles, or data under \`/opt/${options.name}/shared\`. Keep Node runtime behavior in the shared service \`.env.production\`, Compose interpolation and infrastructure credentials in \`.env.infrastructure\`, and fixed topology wiring in Compose \`environment:\`. The optional UI build-time \`.env.production\` is a separate ephemeral file. Do not run deployment until the host and GitHub production environment have been bootstrapped according to \`docs/production-deployment.md\`.
+Pull requests into product \`main\` validate release candidates. The resulting \`main\` push validates again before GitHub Actions may publish an immutable image tagged with the full product commit SHA. Image publication and production deployment are separate workflows: deployment is manual from \`main\`, accepts only an already-published full SHA from \`main\` history, and checks out that exact commit for deployment files. GitHub Actions may replace files under \`/opt/${options.name}/current\` and MUST NOT replace persistent configuration, credentials, keyfiles, or data under \`/opt/${options.name}/shared\`. Keep Node runtime behavior in the shared service \`.env.production\`, Compose interpolation and infrastructure credentials in \`.env.infrastructure\`, and fixed topology wiring in Compose \`environment:\`. The optional UI build-time \`.env.production\` is a separate ephemeral file. Do not run deployment until the host and GitHub environments have been bootstrapped according to \`docs/production-deployment.md\`.
 
 ## Tests and validation
-Run \`pnpm validate:architecture\` and \`pnpm format:check\` after changing files or imports. The generated service also includes unit tests and ${postgres ? "PostgreSQL-backed" : "Mongo-backed"} integration tests. Run focused service database tests through pnpm for the full service check. Test use cases, policies, ${postgres ? "PostgreSQL" : "Mongo"} repository adapters, and HTTP boundaries where behavior lives. Every public operation needs success and error-envelope coverage; authenticated operations need trusted-identity coverage; persisted capabilities need ${postgres ? "PostgreSQL" : "Mongo"} ownership/query coverage; UI-enabled services must verify that \`/api\` paths never fall through to the SPA. All AWS/ECR and Docker commands, including the service \`docker:push\` script, must run outside the sandbox from the first attempt.
+Run \`pnpm validate:architecture\` and \`pnpm format:check\` after changing files or imports. The generated service also includes unit tests and ${postgres ? "PostgreSQL-backed" : "Mongo-backed"} integration tests. Run focused service database tests through pnpm for the full service check. Test use cases, policies, ${postgres ? "PostgreSQL" : "Mongo"} repository adapters, and HTTP boundaries where behavior lives. Every public operation needs success and error-envelope coverage; authenticated operations need trusted-identity coverage; persisted capabilities need ${postgres ? "PostgreSQL" : "Mongo"} ownership/query coverage; UI-enabled services must verify that \`/api\` paths never fall through to the SPA. All AWS/ECR and Docker commands, including the release image script, must run outside the sandbox from the first attempt.
 `);
 
 if (options.ui) {
@@ -757,7 +756,7 @@ set -euo pipefail
 
 SERVICE_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
 PRODUCT_ROOT="$(cd "\${SERVICE_DIR}/../.." && pwd)"
-PRODUCT_SHA="$(git -C "\${PRODUCT_ROOT}" rev-parse --short HEAD)"
+PRODUCT_SHA="$(git -C "\${PRODUCT_ROOT}" rev-parse HEAD)"
 ECR_REPOSITORY="\${ECR_REPOSITORY:-${options.name}}"
 IMAGE_TAG="\${IMAGE_TAG:-\${PRODUCT_SHA}}"
 REGISTRY="\${AWS_ACCOUNT_ID}.dkr.ecr.\${AWS_REGION}.amazonaws.com"
@@ -765,6 +764,11 @@ IMAGE="\${REGISTRY}/\${ECR_REPOSITORY}:\${IMAGE_TAG}"
 DOCKERFILE="\${SERVICE_DIR}/Dockerfile"
 ${options.ui && options.auth === "firebase" ? `UI_ENV_FILE="\${UI_ENV_FILE:-\${PRODUCT_ROOT}/apps/ui/.env.production}"` : ""}
 
+if [[ "\${IMAGE_TAG}" != "\${PRODUCT_SHA}" ]]; then
+	echo "IMAGE_TAG must equal the full product commit SHA (\${PRODUCT_SHA})" >&2
+	exit 1
+fi
+
 aws ecr get-login-password --region "\${AWS_REGION}" |
 	docker login --username AWS --password-stdin "\${REGISTRY}"
 
@@ -773,106 +777,305 @@ docker push "\${IMAGE}"
 
 echo "Pushed \${IMAGE}"
 `);
-const workflowUiPath = options.ui ? '      - "apps/ui/**"\n' : "";
+const workflowUiPath = options.ui ? '            - "apps/ui/**"\n' : "";
 const workflowUiEnvironment = options.ui && options.auth === "firebase" ? `
-      - name: Write UI production environment
-        env:
-          UI_ENV_PRODUCTION: \${{ secrets.UI_ENV_PRODUCTION }}
-        run: |
-          printf '%s\\n' "$UI_ENV_PRODUCTION" > apps/ui/.env.production
+            - name: Write UI production environment
+              if: steps.existing.outputs.exists != 'true'
+              env:
+                  UI_ENV_PRODUCTION: \${{ secrets.UI_ENV_PRODUCTION }}
+              run: |
+                  test -n "$UI_ENV_PRODUCTION"
+                  printf '%s\\n' "$UI_ENV_PRODUCTION" > apps/ui/.env.production
 ` : "";
-add(".github/workflows/deploy.yml", `name: Build and deploy
+const deploymentArtifactDirectory = postgres ? "postgres" : "mongo";
+const deploymentArtifactFile = postgres ? "10-create-application-user.sh" : "10-create-users.js";
+const deploymentArtifactChmod = postgres ? ` /opt/${options.name}/current/deploy/postgres/10-create-application-user.sh` : "";
+add(".github/workflows/release-image.yml", `name: Validate and build release image
 
 on:
-  push:
-    branches:
-      - main
-    paths:
-      - "apps/service/**"
-${workflowUiPath}      - "package.json"
-      - "pnpm-workspace.yaml"
-      - "pnpm-lock.yaml"
-      - ".github/workflows/deploy.yml"
-  workflow_dispatch:
+    pull_request:
+        branches:
+            - main
+        paths:
+            - "apps/service/**"
+${workflowUiPath}            - "package.json"
+            - "pnpm-workspace.yaml"
+            - "pnpm-lock.yaml"
+            - "tailframe.json"
+            - ".github/workflows/release-image.yml"
+    push:
+        branches:
+            - main
+        paths:
+            - "apps/service/**"
+${workflowUiPath}            - "package.json"
+            - "pnpm-workspace.yaml"
+            - "pnpm-lock.yaml"
+            - "tailframe.json"
+            - ".github/workflows/release-image.yml"
 
 permissions:
-  contents: read
-  id-token: write
+    contents: read
 
 concurrency:
-  group: ${options.name}-production
-  cancel-in-progress: false
+    group: ${options.name}-release-\${{ github.ref }}
+    cancel-in-progress: true
 
 jobs:
-  deploy:
-    name: Deploy production
-    if: \${{ vars.DEPLOY_HOST != '' && vars.DEPLOY_USER != '' }}
-    runs-on: ubuntu-latest
-    environment: production
-    env:
-      AWS_ACCOUNT_ID: \${{ vars.AWS_ACCOUNT_ID }}
-      AWS_REGION: \${{ vars.AWS_REGION }}
-      ECR_REPOSITORY: \${{ vars.ECR_REPOSITORY || '${options.name}' }}
-      DEPLOY_HOST: \${{ vars.DEPLOY_HOST }}
-      DEPLOY_USER: \${{ vars.DEPLOY_USER }}
-
-    steps:
-      - name: Checkout product
-        uses: actions/checkout@v6
-${workflowUiEnvironment}
-      - name: Resolve immutable image
-        id: image
-        run: |
-          product_sha="$(git rev-parse --short HEAD)"
-          echo "tag=\${product_sha}" >> "$GITHUB_OUTPUT"
-          echo "registry=\${AWS_ACCOUNT_ID}.dkr.ecr.\${AWS_REGION}.amazonaws.com" >> "$GITHUB_OUTPUT"
-          echo "image=\${AWS_ACCOUNT_ID}.dkr.ecr.\${AWS_REGION}.amazonaws.com/\${ECR_REPOSITORY}" >> "$GITHUB_OUTPUT"
-
-      - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@v6
-        with:
-          role-to-assume: \${{ vars.AWS_ROLE_ARN }}
-          aws-region: \${{ vars.AWS_REGION }}
-
-      - name: Build and push image
+    validate:
+        name: Validate release candidate
+        runs-on: ubuntu-latest
+
+        steps:
+            - name: Checkout product
+              uses: actions/checkout@v6
+
+            - name: Install pnpm
+              uses: pnpm/action-setup@v4
+              with:
+                  version: 11.22.0
+
+            - name: Install Node.js
+              uses: actions/setup-node@v6
+              with:
+                  node-version: 22.13.0
+                  cache: pnpm
+
+            - name: Install dependencies
+              run: pnpm install --frozen-lockfile
+
+            - name: Validate architecture and formatting
+              run: |
+                  pnpm sync:architecture
+                  pnpm validate:architecture
+                  pnpm format:check
+
+            - name: Start integration database
+              run: pnpm --filter ${servicePackage} test:db:up
+
+            - name: Run application tests
+              run: pnpm test
+
+            - name: Stop integration database
+              if: always()
+              run: pnpm --filter ${servicePackage} test:db:down
+
+            - name: Type-check and build applications
+              run: |
+                  pnpm type-check
+                  pnpm build
+
+    build-image:
+        name: Build immutable image
+        needs: validate
+        if: >-
+            github.event_name == 'push' &&
+            vars.AWS_ACCOUNT_ID != '' &&
+            vars.AWS_REGION != '' &&
+            vars.AWS_ROLE_ARN != ''
+        runs-on: ubuntu-latest
+        environment:
+            name: release
+            deployment: false
+        permissions:
+            contents: read
+            id-token: write
         env:
-          IMAGE_TAG: \${{ steps.image.outputs.tag }}
-        run: apps/service/scripts/build_and_push.sh
+            AWS_ACCOUNT_ID: \${{ vars.AWS_ACCOUNT_ID }}
+            AWS_REGION: \${{ vars.AWS_REGION }}
+            ECR_REPOSITORY: \${{ vars.ECR_REPOSITORY || '${options.name}' }}
+
+        steps:
+            - name: Checkout product
+              uses: actions/checkout@v6
+
+            - name: Configure AWS credentials
+              uses: aws-actions/configure-aws-credentials@v6
+              with:
+                  role-to-assume: \${{ vars.AWS_ROLE_ARN }}
+                  aws-region: \${{ vars.AWS_REGION }}
+
+            - name: Resolve immutable image
+              id: image
+              run: |
+                  product_sha="$(git rev-parse HEAD)"
+                  registry="\${AWS_ACCOUNT_ID}.dkr.ecr.\${AWS_REGION}.amazonaws.com"
+                  image="\${registry}/\${ECR_REPOSITORY}"
+                  echo "tag=\${product_sha}" >> "$GITHUB_OUTPUT"
+                  echo "registry=\${registry}" >> "$GITHUB_OUTPUT"
+                  echo "image=\${image}" >> "$GITHUB_OUTPUT"
+
+            - name: Check for existing image
+              id: existing
+              env:
+                  IMAGE_TAG: \${{ steps.image.outputs.tag }}
+              run: |
+                  digest="$(aws ecr describe-images \\
+                    --repository-name "$ECR_REPOSITORY" \\
+                    --image-ids "imageTag=$IMAGE_TAG" \\
+                    --query 'imageDetails[0].imageDigest' \\
+                    --output text 2>/dev/null || true)"
+                  if [[ -n "$digest" && "$digest" != "None" ]]; then
+                    echo "exists=true" >> "$GITHUB_OUTPUT"
+                  else
+                    echo "exists=false" >> "$GITHUB_OUTPUT"
+                  fi
+${workflowUiEnvironment}
+            - name: Build and push image
+              if: steps.existing.outputs.exists != 'true'
+              env:
+                  IMAGE_TAG: \${{ steps.image.outputs.tag }}
+              run: apps/service/scripts/build_and_push.sh
+
+            - name: Verify published image
+              id: published
+              env:
+                  IMAGE_TAG: \${{ steps.image.outputs.tag }}
+              run: |
+                  digest="$(aws ecr describe-images \\
+                    --repository-name "$ECR_REPOSITORY" \\
+                    --image-ids "imageTag=$IMAGE_TAG" \\
+                    --query 'imageDetails[0].imageDigest' \\
+                    --output text)"
+                  test -n "$digest"
+                  test "$digest" != "None"
+                  echo "digest=\${digest}" >> "$GITHUB_OUTPUT"
+
+            - name: Record release image
+              env:
+                  IMAGE: \${{ steps.image.outputs.image }}
+                  IMAGE_TAG: \${{ steps.image.outputs.tag }}
+                  IMAGE_DIGEST: \${{ steps.published.outputs.digest }}
+              run: |
+                  {
+                    echo "### ${title} release image"
+                    echo
+                    echo "- Image: \`\${IMAGE}:\${IMAGE_TAG}\`"
+                    echo "- Digest: \`\${IMAGE_DIGEST}\`"
+                  } >> "$GITHUB_STEP_SUMMARY"
+`);
+add(".github/workflows/deploy.yml", `name: Deploy release image
+
+on:
+    workflow_dispatch:
+        inputs:
+            image_tag:
+                description: Full 40-character product commit SHA already published to ECR
+                required: true
+                type: string
 
-      - name: Configure deployment SSH
+permissions:
+    contents: read
+    id-token: write
+
+concurrency:
+    group: ${options.name}-production
+    cancel-in-progress: false
+
+jobs:
+    deploy:
+        name: Deploy production
+        if: github.ref == 'refs/heads/main'
+        runs-on: ubuntu-latest
+        environment: production
         env:
-          DEPLOY_SSH_PRIVATE_KEY: \${{ secrets.DEPLOY_SSH_PRIVATE_KEY }}
-          DEPLOY_SSH_KNOWN_HOSTS: \${{ secrets.DEPLOY_SSH_KNOWN_HOSTS }}
-        run: |
-          install -m 700 -d ~/.ssh
-          printf '%s\\n' "$DEPLOY_SSH_PRIVATE_KEY" > ~/.ssh/${options.name}-deploy
-          chmod 600 ~/.ssh/${options.name}-deploy
-          printf '%s\\n' "$DEPLOY_SSH_KNOWN_HOSTS" > ~/.ssh/known_hosts
-
-      - name: Authenticate server with ECR
-        run: |
-          aws ecr get-login-password --region "$AWS_REGION" |
-            ssh -i ~/.ssh/${options.name}-deploy "\${DEPLOY_USER}@\${DEPLOY_HOST}" \\
-              "docker login --username AWS --password-stdin '\${{ steps.image.outputs.registry }}'"
-
-      - name: Install deployment files
-        run: |
-          ssh -i ~/.ssh/${options.name}-deploy "\${DEPLOY_USER}@\${DEPLOY_HOST}" \\
-            "install -m 755 -d /opt/${options.name}/current/deploy/mongo"
-          scp -i ~/.ssh/${options.name}-deploy \\
-            apps/service/docker-compose.yml \\
-            apps/service/scripts/deploy_remote.sh \\
-            "\${DEPLOY_USER}@\${DEPLOY_HOST}:/opt/${options.name}/current/"
-          scp -i ~/.ssh/${options.name}-deploy \\
-            apps/service/deploy/mongo/10-create-users.js \\
-            "\${DEPLOY_USER}@\${DEPLOY_HOST}:/opt/${options.name}/current/deploy/mongo/"
-          ssh -i ~/.ssh/${options.name}-deploy "\${DEPLOY_USER}@\${DEPLOY_HOST}" \\
-            "chmod 755 /opt/${options.name}/current/deploy_remote.sh"
-
-      - name: Deploy image
-        run: |
-          ssh -i ~/.ssh/${options.name}-deploy "\${DEPLOY_USER}@\${DEPLOY_HOST}" \\
-            "/opt/${options.name}/current/deploy_remote.sh '\${{ steps.image.outputs.tag }}' '\${{ steps.image.outputs.image }}'"
+            AWS_ACCOUNT_ID: \${{ vars.AWS_ACCOUNT_ID }}
+            AWS_REGION: \${{ vars.AWS_REGION }}
+            ECR_REPOSITORY: \${{ vars.ECR_REPOSITORY || '${options.name}' }}
+            DEPLOY_HOST: \${{ vars.DEPLOY_HOST }}
+            DEPLOY_USER: \${{ vars.DEPLOY_USER }}
+            IMAGE_TAG: \${{ inputs.image_tag }}
+
+        steps:
+            - name: Validate deployment input
+              run: |
+                  [[ "$IMAGE_TAG" =~ ^[0-9a-f]{40}$ ]]
+                  test -n "$AWS_ACCOUNT_ID"
+                  test -n "$AWS_REGION"
+                  test -n "$DEPLOY_HOST"
+                  test -n "$DEPLOY_USER"
+
+            - name: Checkout exact product commit
+              uses: actions/checkout@v6
+              with:
+                  ref: \${{ inputs.image_tag }}
+                  fetch-depth: 0
+
+            - name: Verify product release commit
+              run: |
+                  test "$(git rev-parse HEAD)" = "$IMAGE_TAG"
+                  git merge-base --is-ancestor "$IMAGE_TAG" origin/main
+
+            - name: Configure AWS credentials
+              uses: aws-actions/configure-aws-credentials@v6
+              with:
+                  role-to-assume: \${{ vars.AWS_ROLE_ARN }}
+                  aws-region: \${{ vars.AWS_REGION }}
+
+            - name: Resolve and verify image
+              id: image
+              run: |
+                  registry="\${AWS_ACCOUNT_ID}.dkr.ecr.\${AWS_REGION}.amazonaws.com"
+                  image="\${registry}/\${ECR_REPOSITORY}"
+                  digest="$(aws ecr describe-images \\
+                    --repository-name "$ECR_REPOSITORY" \\
+                    --image-ids "imageTag=$IMAGE_TAG" \\
+                    --query 'imageDetails[0].imageDigest' \\
+                    --output text)"
+                  test -n "$digest"
+                  test "$digest" != "None"
+                  echo "registry=\${registry}" >> "$GITHUB_OUTPUT"
+                  echo "image=\${image}" >> "$GITHUB_OUTPUT"
+                  echo "digest=\${digest}" >> "$GITHUB_OUTPUT"
+
+            - name: Configure deployment SSH
+              env:
+                  DEPLOY_SSH_PRIVATE_KEY: \${{ secrets.DEPLOY_SSH_PRIVATE_KEY }}
+                  DEPLOY_SSH_KNOWN_HOSTS: \${{ secrets.DEPLOY_SSH_KNOWN_HOSTS }}
+              run: |
+                  test -n "$DEPLOY_SSH_PRIVATE_KEY"
+                  test -n "$DEPLOY_SSH_KNOWN_HOSTS"
+                  install -m 700 -d ~/.ssh
+                  printf '%s\\n' "$DEPLOY_SSH_PRIVATE_KEY" > ~/.ssh/${options.name}-deploy
+                  chmod 600 ~/.ssh/${options.name}-deploy
+                  printf '%s\\n' "$DEPLOY_SSH_KNOWN_HOSTS" > ~/.ssh/known_hosts
+
+            - name: Authenticate server with ECR
+              run: |
+                  aws ecr get-login-password --region "$AWS_REGION" |
+                    ssh -i ~/.ssh/${options.name}-deploy "\${DEPLOY_USER}@\${DEPLOY_HOST}" \\
+                      "docker login --username AWS --password-stdin '\${{ steps.image.outputs.registry }}'"
+
+            - name: Install deployment files
+              run: |
+                  ssh -i ~/.ssh/${options.name}-deploy "\${DEPLOY_USER}@\${DEPLOY_HOST}" \\
+                    "install -m 755 -d /opt/${options.name}/current/deploy/${deploymentArtifactDirectory}"
+                  scp -i ~/.ssh/${options.name}-deploy \\
+                    apps/service/docker-compose.yml \\
+                    apps/service/scripts/deploy_remote.sh \\
+                    "\${DEPLOY_USER}@\${DEPLOY_HOST}:/opt/${options.name}/current/"
+                  scp -i ~/.ssh/${options.name}-deploy \\
+                    apps/service/deploy/${deploymentArtifactDirectory}/${deploymentArtifactFile} \\
+                    "\${DEPLOY_USER}@\${DEPLOY_HOST}:/opt/${options.name}/current/deploy/${deploymentArtifactDirectory}/"
+                  ssh -i ~/.ssh/${options.name}-deploy "\${DEPLOY_USER}@\${DEPLOY_HOST}" \\
+                    "chmod 755 /opt/${options.name}/current/deploy_remote.sh${deploymentArtifactChmod}"
+
+            - name: Deploy image
+              run: |
+                  ssh -i ~/.ssh/${options.name}-deploy "\${DEPLOY_USER}@\${DEPLOY_HOST}" \\
+                    "/opt/${options.name}/current/deploy_remote.sh '$IMAGE_TAG' '\${{ steps.image.outputs.image }}'"
+
+            - name: Record deployment
+              env:
+                  IMAGE: \${{ steps.image.outputs.image }}
+                  IMAGE_DIGEST: \${{ steps.image.outputs.digest }}
+              run: |
+                  {
+                    echo "### ${title} production deployment"
+                    echo
+                    echo "- Image: \`\${IMAGE}:\${IMAGE_TAG}\`"
+                    echo "- Digest: \`\${IMAGE_DIGEST}\`"
+                  } >> "$GITHUB_STEP_SUMMARY"
 `);
 add(`${svc}/scripts/deploy_remote.sh`, `#!/usr/bin/env bash
 set -euo pipefail
@@ -925,9 +1128,20 @@ add(`${svc}/docs/production-deployment.md`, `# Production deployment
 
 ## Delivery model
 
-GitHub Actions checks out the product once, builds one
-non-root production image, tags it \`<product-sha>\`, pushes it to ECR, and installs only deployment artifacts on the host.
-Changes to the service, optional UI, root workspace/lock configuration, or deployment files on product \`main\`, plus manual dispatch, trigger this workflow.
+Delivery is split into two GitHub Actions workflows:
+
+1. \`release-image.yml\` validates pull requests into \`main\`. After merge, the resulting \`main\` push is validated
+   again before the workflow builds one non-root production image, tags it with the full 40-character product commit
+   SHA, and pushes it to ECR. If that tag already exists, the workflow reuses it instead of rebuilding it.
+2. \`deploy.yml\` is manual-only. It runs only from product \`main\`, accepts the full SHA of an existing ECR image,
+   verifies the commit belongs to \`main\` history, checks out that exact commit for deployment files, and updates the host.
+
+Only service${options.ui ? ", UI," : ","} workspace, lockfile, architecture, and release-workflow changes trigger validation.
+The ECR build job runs only for the post-merge \`main\` push and remains skipped until the repository AWS variables are
+configured. No push or merge deploys production automatically.
+
+Configure the ECR repository with immutable image tags and restrict routine push permission to the repository's
+release workflow. Record the full commit SHA and ECR digest; deployment and migration must use that release image.
 
 The host separates replaceable artifacts from persistent state:
 
@@ -936,14 +1150,15 @@ The host separates replaceable artifacts from persistent state:
 ├── current/
 │   ├── docker-compose.yml
 │   ├── deploy_remote.sh
-│   └── deploy/mongo/10-create-users.js
+│   └── deploy/${deploymentArtifactDirectory}/${deploymentArtifactFile}
 └── shared/
     ├── .env.production
     ├── .env.infrastructure
 ${options.auth === "firebase" ? `    ├── secrets/firebase-service-account.json
-` : ""}    ├── mongo/config/keyfile
+` : ""}${postgres ? `    ├── postgres/data/
+` : `    ├── mongo/config/keyfile
     ├── mongo/data/
-${options.redis ? `    └── redis/data/
+`}${options.redis ? `    └── redis/data/
 ` : ""}\`\`\`
 
 Actions may replace \`current/\` and must never replace \`shared/\`. The server never needs a source checkout.
@@ -962,42 +1177,53 @@ Do not inject \`.env.infrastructure\` into Node. Make both host environment file
 ## One-time host bootstrap
 
 1. Install Docker Engine and Docker Compose.
-2. Create \`/opt/${options.name}/current/deploy/mongo\`, \`/opt/${options.name}/shared/mongo/config\`, and
-   \`/opt/${options.name}/shared/mongo/data\`${options.redis ? `, plus \`/opt/${options.name}/shared/redis/data\`` : ""}.
+${postgres
+	? `2. Create \`/opt/${options.name}/current/deploy/postgres\` and \`/opt/${options.name}/shared/postgres/data\`${options.redis ? `, plus \`/opt/${options.name}/shared/redis/data\`` : ""}.`
+	: `2. Create \`/opt/${options.name}/current/deploy/mongo\`, \`/opt/${options.name}/shared/mongo/config\`, and
+   \`/opt/${options.name}/shared/mongo/data\`${options.redis ? `, plus \`/opt/${options.name}/shared/redis/data\`` : ""}.`}
 3. Install \`.env.production\` and a completed \`.env.infrastructure\` under \`shared/\`.
-4. Generate the MongoDB replica key with \`openssl rand -base64 756\`, make it owned by UID/GID \`999:999\`, and
+${postgres ? "" : `4. Generate the MongoDB replica key with \`openssl rand -base64 756\`, make it owned by UID/GID \`999:999\`, and
    mode \`0400\`.
-${options.auth === "firebase" ? `5. Install the Firebase service account at \`shared/secrets/firebase-service-account.json\`, owned by \`root:1000\` and mode \`0640\`.
-6. ` : "5. "}Give the deployment user Docker access and write access to \`current/\`; keep \`shared/\` and its files protected.
-${options.auth === "firebase" ? "7" : "6"}. Authorize the dedicated deployment SSH key and record the host key for GitHub Actions.
+`}${options.auth === "firebase" ? `${postgres ? "4" : "5"}. Install the Firebase service account at \`shared/secrets/firebase-service-account.json\`, owned by \`root:1000\` and mode \`0640\`.
+` : ""}${postgres ? (options.auth === "firebase" ? "5" : "4") : (options.auth === "firebase" ? "6" : "5")}. Give the deployment user Docker access and write access to \`current/\`; keep \`shared/\` and its files protected.
+${postgres ? (options.auth === "firebase" ? "6" : "5") : (options.auth === "firebase" ? "7" : "6")}. Authorize the dedicated deployment SSH key and record the host key for GitHub Actions.
 
-Use a fresh Mongo data directory. Migrating an existing unauthenticated database requires a separately reviewed plan.
+Use a fresh ${postgres ? "PostgreSQL" : "MongoDB"} data directory. Migrating an existing unauthenticated database requires a separately reviewed plan.
 
-## GitHub production environment
+## GitHub repository variables
+
+Configure \`AWS_ACCOUNT_ID\`, \`AWS_REGION\`, and \`AWS_ROLE_ARN\` as repository variables for the
+repository-restricted OIDC role. Optionally set \`ECR_REPOSITORY\`; the default is \`${options.name}\`.
 
-Configure these variables:
+The ECR repository and AWS OIDC provider/role are provisioned separately. Workflows never store long-lived AWS keys
+or create cloud infrastructure.
 
-- \`AWS_ACCOUNT_ID\`, \`AWS_REGION\`, and \`AWS_ROLE_ARN\` for the repository-restricted OIDC role.
-- \`DEPLOY_HOST\` and \`DEPLOY_USER\`; the deployment job remains skipped until both exist.
-- Optional \`ECR_REPOSITORY\`; the default is \`${options.name}\`.
+## GitHub release environment
 
-Configure these secrets:
+${options.ui && options.auth === "firebase" ? `Configure the \`UI_ENV_PRODUCTION\` secret for the Vite/Firebase build-time environment. The release environment MAY require approval before exposing production-capable browser configuration.
+` : "The release workflow uses this environment without creating a deployment record. It MAY require approval before publishing an image.\n"}
+## GitHub production environment
 
-${options.ui && options.auth === "firebase" ? `- \`UI_ENV_PRODUCTION\`: Vite/Firebase build-time environment.
-` : ""}- \`DEPLOY_SSH_PRIVATE_KEY\`: dedicated host deployment key.
+Configure \`DEPLOY_HOST\` and \`DEPLOY_USER\` as production-environment variables. Configure these secrets:
+
+- \`DEPLOY_SSH_PRIVATE_KEY\`: dedicated host deployment key.
 - \`DEPLOY_SSH_KNOWN_HOSTS\`: pinned host key.
 
-The ECR repository and AWS OIDC provider/role are provisioned separately. The workflow never stores long-lived AWS
-keys or creates cloud infrastructure.
+Restrict the production environment's deployment branches to \`main\`. Required reviewer approval MAY add a second
+manual gate, but the branch restriction and manual full-SHA input remain mandatory.
 
 ## Deploy and rollback
 
+Run \`Deploy release image\` manually from \`main\` and enter the full SHA recorded by the release workflow. The
+deployment fails before contacting the host if the SHA is invalid, is not in \`main\` history, cannot be checked out,
+or has no matching ECR image.
+
 The remote script requires the provisioned infrastructure file, atomically replaces only \`ECR_IMAGE\` and
 \`IMAGE_TAG\`, validates Compose, pulls, and starts with health waiting. Roll back by selecting a previous immutable
-tag and running the same script. Never use \`docker compose down -v\` in production; image rollback does not restore
-database state.
+full-SHA release and running the same workflow. Never use \`docker compose down -v\` in production; image rollback
+does not restore database state.
 
-MongoDB and optional Redis expose no host ports and require authentication. Verify API readiness, container health,
+${postgres ? "PostgreSQL" : "MongoDB"} and optional Redis expose no host ports and require authentication. Verify API readiness, container health,
 database/cache authentication, file permissions, and off-host backup/restore before treating the deployment as
 production-ready. Product-specific TLS, capacity limits, migrations, and scheduled-work grace periods must be added
 from measured application requirements rather than copied from another product.