@zaaxch/tailframe 4.0.0 → 4.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zaaxch/tailframe",
-	"version": "4.0.0",
+	"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

@@ -131,6 +131,8 @@ add("package.json", JSON.stringify({
 add("pnpm-workspace.yaml", `packages:
   - "apps/*"
 injectWorkspacePackages: true
+minimumReleaseAgeExclude:
+  - "@zaaxch/tailframe@${contractVersion}"
 allowBuilds:
   "@firebase/util": true
   esbuild: true
@@ -241,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({
@@ -550,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) {
@@ -564,8 +565,8 @@ add(`${ui}/package.json`, JSON.stringify({ name: uiPackage, version: "0.1.0", pr
 add(`${ui}/.prettierrc.json`, JSON.stringify(prettierConfig, null, "\t"));
 add(`${ui}/.gitattributes`, gitAttributes);
 add(`${ui}/tsconfig.json`, JSON.stringify({ files: [], references: [{ path: "./tsconfig.app.json" }, { path: "./tsconfig.node.json" }] }, null, "\t"));
-add(`${ui}/tsconfig.app.json`, JSON.stringify({ extends: "@vue/tsconfig/tsconfig.dom.json", include: ["env.d.ts", "src/**/*", "src/**/*.vue"], compilerOptions: { composite: true, baseUrl: ".", paths: { "@/*": ["./src/*"] } } }, null, "\t"));
-add(`${ui}/tsconfig.node.json`, JSON.stringify({ extends: "@tsconfig/node22/tsconfig.json", include: ["vite.config.*"], compilerOptions: { composite: true, types: ["node"] } }, null, "\t"));
+add(`${ui}/tsconfig.app.json`, JSON.stringify({ extends: "@vue/tsconfig/tsconfig.dom.json", include: ["env.d.ts", "src/**/*", "src/**/*.vue"], compilerOptions: { composite: true, noEmit: true, tsBuildInfoFile: "./.tmp/tsconfig.app.tsbuildinfo", types: ["vitest/globals"], baseUrl: ".", paths: { "@/*": ["./src/*"] } } }, null, "\t"));
+add(`${ui}/tsconfig.node.json`, JSON.stringify({ extends: "@tsconfig/node22/tsconfig.json", include: ["vite.config.ts"], compilerOptions: { composite: true, noEmit: true, tsBuildInfoFile: "./.tmp/tsconfig.node.tsbuildinfo", types: ["node"] } }, null, "\t"));
 add(`${ui}/vite.config.ts`, `import { fileURLToPath, URL } from "node:url";\nimport { defineConfig } from "vitest/config";\nimport vue from "@vitejs/plugin-vue";\nimport tailwindcss from "@tailwindcss/vite";\nexport default defineConfig({ plugins: [vue(), tailwindcss()], resolve: { alias: { "@": fileURLToPath(new URL("./src", import.meta.url)) } }, server: { proxy: { "/api": { target: "http://localhost:3000", changeOrigin: true } } }, test: { environment: "jsdom", globals: true } });`);
 add(`${ui}/env.d.ts`, `/// <reference types="vite/client" />`);
 add(`${ui}/index.html`, `<!doctype html>
@@ -581,7 +582,7 @@ add(`${ui}/index.html`, `<!doctype html>
 	</body>
 </html>
 `);
-add(`${ui}/.gitignore`, `node_modules/\ndist/\n.env*\n!.env.example\ncerts/\n*.log\n`);
+add(`${ui}/.gitignore`, `node_modules/\ndist/\n.env*\n!.env.example\ncerts/\n*.log\n.tmp/\n`);
 if (options.auth === "firebase") add(`${ui}/.env.example`, `VITE_FIREBASE_API_KEY=\nVITE_FIREBASE_AUTH_DOMAIN=\nVITE_FIREBASE_PROJECT_ID=\nVITE_FIREBASE_APP_ID=\n`);
 add(`${ui}/src/core/errors.ts`, uiErrorsSource);
 add(`${ui}/src/core/rpc.ts`, uiRpcSource);
@@ -719,7 +720,7 @@ Run \`pnpm validate:architecture\` and \`pnpm format:check\`, then add focused V
 }
 
 add(`${svc}/Dockerfile`, `FROM node:22.13-bookworm AS build
-RUN corepack enable
+RUN npm install --global corepack@0.34.5 && corepack enable
 WORKDIR /workspace
 COPY package.json pnpm-workspace.yaml pnpm-lock.yaml ./
 COPY apps/service/package.json apps/service/package.json
@@ -737,7 +738,7 @@ EXPOSE 3000
 CMD ["node", "dist/server.js"]
 `);
 add(`${svc}/Dockerfile.dev`, `FROM node:22.13-alpine
-RUN corepack enable
+RUN npm install --global corepack@0.34.5 && corepack enable
 WORKDIR /workspace
 COPY package.json pnpm-workspace.yaml pnpm-lock.yaml ./
 COPY apps/service/package.json apps/service/package.json
@@ -755,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"
@@ -763,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}"
 
@@ -771,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
+
+permissions:
+    contents: read
+    id-token: write
+
+concurrency:
+    group: ${options.name}-production
+    cancel-in-progress: false
 
-      - name: Configure deployment SSH
+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
@@ -923,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:
 
@@ -934,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.
@@ -960,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}\`.
+
+The ECR repository and AWS OIDC provider/role are provisioned separately. Workflows never store long-lived AWS keys
+or create cloud infrastructure.
 
-Configure these variables:
+## GitHub release environment
 
-- \`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}\`.
+${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
 
-Configure these secrets:
+Configure \`DEPLOY_HOST\` and \`DEPLOY_USER\` as production-environment variables. Configure these secrets:
 
-${options.ui && options.auth === "firebase" ? `- \`UI_ENV_PRODUCTION\`: Vite/Firebase build-time environment.
-` : ""}- \`DEPLOY_SSH_PRIVATE_KEY\`: dedicated host deployment key.
+- \`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.
@@ -1005,8 +1233,9 @@ const serviceVolumes = [
 	...(options.auth === "firebase" ? ["      - ${SECRETS_DIR:?Set SECRETS_DIR}/firebase-service-account.json:/app/secrets/firebase-service-account.json:ro"] : [])
 ];
 const devVolumes = [
-	"      - .:/app",
-	"      - /app/node_modules",
+	"      - .:/workspace/apps/service",
+	"      - /workspace/node_modules",
+	"      - /workspace/apps/service/node_modules",
 	...(options.auth === "firebase" ? ["      - ./firebase-service-account.development.json:/app/firebase-service-account.development.json:ro"] : [])
 ];
 const productionDependencies = [
@@ -1031,9 +1260,13 @@ const productionEnvironment = [
 	...(options.redis ? ["      REDIS_URL: \"redis://:\${REDIS_PASSWORD:?Set REDIS_PASSWORD}@redis:6379\""] : [])
 ];
 const productionEnvironmentBlock = `\n    environment:\n${productionEnvironment.join("\n")}`;
-const databaseEnvironmentBlock = postgres
-	? `\n    environment:\n      POSTGRES_URI: "postgresql://${options.name}-app:development@postgres:5432/${databaseName}"`
-	: `\n    environment:\n      MONGODB_URI: "mongodb://mongodb:27017/?replicaSet=rs0&directConnection=true"`;
+const developmentEnvironment = [
+	postgres
+		? `      POSTGRES_URI: "postgresql://${options.name}-app:development@postgres:5432/${databaseName}"`
+		: `      MONGODB_URI: "mongodb://mongodb:27017/?replicaSet=rs0&directConnection=true"`,
+	...(options.auth === "firebase" ? ["      FIREBASE_SERVICE_ACCOUNT_PATH: /app/firebase-service-account.development.json"] : [])
+];
+const developmentEnvironmentBlock = `\n    environment:\n${developmentEnvironment.join("\n")}`;
 const volumeBlock = serviceVolumes.length ? `\n    volumes:\n${serviceVolumes.join("\n")}` : "";
 const workerService = options.worker ? `\n  worker:
     image: \${ECR_IMAGE:?Set ECR_IMAGE}:\${IMAGE_TAG:?Set IMAGE_TAG}
@@ -1206,7 +1439,7 @@ const devWorker = options.worker ? `\n  worker:
       dockerfile: Dockerfile.dev
     env_file:
       - .env.development
-    command: ["npm", "run", "dev:worker"]${databaseEnvironmentBlock}
+    command: ["npm", "run", "dev:worker"]${developmentEnvironmentBlock}
     volumes:
 ${devVolumes.join("\n")}${devDependsBlock}` : "";
 const devDatabase = postgres ? `\n  postgres:
@@ -1270,7 +1503,7 @@ services:
       dockerfile: Dockerfile.dev
     env_file:
       - .env.development
-    command: ["npm", "run", "schema:apply:dev"]${databaseEnvironmentBlock}
+    command: ["npm", "run", "schema:apply:dev"]${developmentEnvironmentBlock}
     volumes:
 ${devVolumes.join("\n")}
     depends_on:
@@ -1283,7 +1516,7 @@ ${devVolumes.join("\n")}
     env_file:
       - .env.development
     ports:
-      - "3000:3000"${databaseEnvironmentBlock}
+      - "3000:3000"${developmentEnvironmentBlock}
     volumes:
 ${devVolumes.join("\n")}${devDependsBlock}${devWorker}${devDatabase}${devRedis}
 volumes:

package/src/validate.mjs

@@ -65,6 +65,50 @@ function validateAppMetadata(productRoot, app) {
 	const errors = [];
 	const root = appRoot(productRoot, app);
 	if (!fs.existsSync(root)) return [`Missing configured application root: ${app.path}`];
+	if (app.kind === "service") {
+		const composeFile = path.join(root, "docker-compose.dev.yml");
+		if (!fs.existsSync(composeFile)) errors.push(`${app.path}/docker-compose.dev.yml is required`);
+		else {
+			const compose = fs.readFileSync(composeFile, "utf8");
+			const generatedProcessCount = app.profiles.includes("worker") ? 3 : 2;
+			const count = (term) => compose.split(term).length - 1;
+			for (const term of [
+				"      - .:/workspace/apps/service",
+				"      - /workspace/node_modules",
+				"      - /workspace/apps/service/node_modules"
+			]) {
+				if (count(term) < generatedProcessCount) {
+					errors.push(`${app.path}/docker-compose.dev.yml must mount every generated service process at the image workspace: ${term.trim()}`);
+				}
+			}
+			if (compose.includes("      - .:/app\n")) {
+				errors.push(`${app.path}/docker-compose.dev.yml uses the obsolete /app service source mount`);
+			}
+			if (app.profiles.includes("firebase")) {
+				for (const term of [
+					"      FIREBASE_SERVICE_ACCOUNT_PATH: /app/firebase-service-account.development.json",
+					"      - ./firebase-service-account.development.json:/app/firebase-service-account.development.json:ro"
+				]) {
+					if (count(term) < generatedProcessCount) {
+						errors.push(`${app.path}/docker-compose.dev.yml must use the canonical Firebase development credential path for every generated service process: ${term.trim()}`);
+					}
+				}
+			}
+		}
+	}
+	if (app.kind === "ui") {
+		const generatedArtifacts = fs.readdirSync(root, { withFileTypes: true })
+			.filter(
+				(entry) =>
+					entry.isFile() &&
+					(entry.name.endsWith(".tsbuildinfo") || ["vite.config.js", "vite.config.d.ts"].includes(entry.name))
+			)
+			.map((entry) => entry.name)
+			.sort();
+		for (const artifact of generatedArtifacts) {
+			errors.push(`${app.path}/${artifact} is generated compiler output; keep incremental state under apps/ui/.tmp`);
+		}
+	}
 	if (fs.existsSync(path.join(root, "tailframe.json"))) {
 		errors.push(`${app.path}/tailframe.json is forbidden; the product root owns Tailframe metadata`);
 	}