@starci/hfs 4.11.0 → 4.11.11

package/sync/index.mjs

@@ -30,7 +30,7 @@ import { DEFAULT_PORT, NODE_IMAGE, dockerfilePath } from '../runtime/scripts/hfs
 import { isFile } from '../runtime/scripts/lib/fs-kind.mjs';
 import { readDeclaredSonarKey } from './sonar-key.mjs';
 import { readDeclaredStack, stackWorkflowVariables } from './stack-images.mjs';
-import { DB_DOCKERFILE, DB_IMAGE_APP } from '../db/image.mjs';
+import { DB_DOCKERFILE, DB_IMAGE_APP, RETIRED_DB_DOCKERFILE } from '../db/image.mjs';
 import { byCodeUnit } from '../report/order.mjs';
 import { isRuntimeExampleApp } from '../runtime/scripts/lib/runtime-example.mjs';
 import { ciWorkflowCommands } from './ci-commands.mjs';
@@ -40,6 +40,8 @@ import { grammarLintFor } from '../runtime/scripts/lib/grammar-lint.mjs';
 import { LIST } from '../runtime/scripts/lib/loosening-config.mjs';
 import { readTruths } from '../runtime/scripts/lib/loosening-state.mjs';
 import { parseYaml as bundledParseYaml } from '../runtime/engine/yaml.mjs';
+import { bootstrapSection } from '../runtime/scripts/hfs/rules/database-constants.mjs';
+import { SERVER_AGE_IDENTITY } from '../stack/server-key.mjs';
 
 export const TEMPLATES_DIR = path.join(import.meta.dirname, '..', 'templates');
 const NODE_MAJOR = 22;
@@ -58,9 +60,10 @@ export class SyncError extends Error {
 }
 
 // mode: file = whole file, block = the marked block inside a file the app also writes to, scripts = the `scripts` block of
-// package.json. A template that can hold a comment opens with {{header}}; a file whose exact content is specified (JSON, the
-// eslint one-liner) has no header.
-const MODE_OF_GROUP = Object.freeze({ 'package-scripts': 'scripts', 'package-scripts-lite': 'scripts' });
+// package.json, section = the whole file but the one marked section a database verb owns (db/bootstrap.sql, whose squash section
+// `starci app db baseline --squash` writes). A template that can hold a comment opens with {{header}}; a file whose exact content is
+// specified (JSON, the eslint one-liner) has no header.
+const MODE_OF_GROUP = Object.freeze({ 'package-scripts': 'scripts', 'package-scripts-lite': 'scripts', 'db-bootstrap': 'section' });
 const GLOB_CHARACTERS = new Set('*?<>{}[]');
 const literalFile = file => file.length >= 2 && !file.endsWith('/') && ![...file].some(character => GLOB_CHARACTERS.has(character));
 
@@ -158,13 +161,22 @@ function trailingNewline(text) {
 }
 
 /**
- * The base image of a lite app's managed db/Dockerfile (contexts/stack/pins.yaml images postgres, ruling:lite-official-postgres-image): the
- * Docker Official postgres image by digest, to which the Dockerfile adds only PGVECTOR_PACKAGE from PGDG.
+ * The base image of a lite app's managed .starcistacks/images/db/Dockerfile (contexts/stack/pins.yaml images postgres, ruling:lite-official-postgres-image): the
+ * Docker Official postgres image by digest, to which the Dockerfile adds PGVECTOR_PACKAGE from PGDG and the PGMQ release.
  */
 export const DB_BASE_IMAGE = 'postgres:17.11@sha256:31ba9c94a03ada9988f2bb493a22a75eef3a185884533e5cdbcd498ea835b08f';
 /** The PGDG package of pgvector at the exact version the db image installs (the one extension the image does not ship). */
 export const PGVECTOR_PACKAGE = 'postgresql-17-pgvector=0.8.7-1.pgdg13+1';
-/** The local tag the development db container and the drift scratch database run, built from the app's db/Dockerfile. */
+/**
+ * The pgmq release the db image installs for the event bus (ruling:lite-pgmq-bus-bullmq-jobs): its source tarball, verified by sha256
+ * when Docker adds it. PGDG does not package pgmq; it is SQL objects only, so the Dockerfile copies its control and script files.
+ */
+export const PGMQ = Object.freeze({
+  version: '1.13.1',
+  source: 'https://github.com/pgmq/pgmq/archive/refs/tags/v1.13.1.tar.gz',
+  sha256: '67221f288f42f95c002a64df40f7d660e765e32df8ada0f2672ba915a14827f7',
+});
+/** The local tag the development db container and the drift scratch database run, built from the app's .starcistacks/images/db/Dockerfile. */
 export const dbLocalImage = project => `${project}-db:local`;
 /** The digest-pinned image of a lite app's declared Redis, in every environment that runs it (ruling:R212/case-10). */
 export const REDIS_IMAGE = 'redis:7@sha256:c6eabf748fc7a61dbb5a705c78bcf3d6377b1127a97d0ce965c11c44ba46896f';
@@ -385,10 +397,13 @@ export function variables(app, scope, presets, sonarKey, manifest = loadSlotMani
     project: app.project,
     appBinary: APP_BINARY,
     appScripts: appScripts(app, source),
-    // A lite app's own database runs in development as one container of the image its db/Dockerfile builds (ruling:lite-official-postgres-image).
+    // A lite app's own database runs in development as one container of the image its .starcistacks/images/db/Dockerfile builds (ruling:lite-db-image-in-stacks).
     dbImage: dbLocalImage(app.project),
     dbBaseImage: DB_BASE_IMAGE,
     pgvectorPackage: PGVECTOR_PACKAGE,
+    pgmqVersion: PGMQ.version,
+    pgmqSource: PGMQ.source,
+    pgmqSha256: PGMQ.sha256,
     // A lite app's declared Redis (sides.be.backing, ruling:R212/case-10) runs in development as one container of its pinned image.
     backingScripts: lite && (app.sides.be.backing ?? []).includes('redis') ? redisDevText(app.project) : '',
     // turbo builds every fe app workspace; ^build (turbo.json) builds the packages each app imports first, and caches both.
@@ -398,6 +413,8 @@ export function variables(app, scope, presets, sonarKey, manifest = loadSlotMani
     // The typed lint reads the types the fe packages declare (their dist, turbo.json: lint dependsOn ^build), so the packages are built first.
     lintPrefix: packages ? 'npm run codegen --silent && turbo run build --filter=./fe/packages/* && ' : 'npm run codegen --silent && ',
     nodeMajor: String(NODE_MAJOR),
+    // The deploy server's age identity the restore workflow writes (stack/server-key.mjs owns the path).
+    serverAgeIdentity: SERVER_AGE_IDENTITY,
     sonarKey: sonarKey ?? app.project,
     sonarHostLine: sonarHostLine(quality.sonar),
     sonarExclusions: sonarScope(presets).exclusions.join(','),
@@ -472,9 +489,10 @@ export function renderTargets(hfs, presets, { sonarKey, readTemplate = readBundl
   });
 }
 
-// The part of a file sync manages: all of it, the marked block, or the scripts block as text.
+// The part of a file sync manages: all of it, all of it but the verb's section, the marked block, or the scripts block as text.
 function managedPart(mode, text, markers = { begin: BLOCK_BEGIN, end: BLOCK_END }) {
   if (mode === 'file') return text;
+  if (mode === 'section') return bootstrapSection(text).head;
   if (mode === 'scripts') {
     const scripts = parseScripts(text);
     return scripts ? scriptsText(scripts) : null;
@@ -524,6 +542,7 @@ export function writtenContent(target, existing) {
     }
     return `${JSON.stringify({ ...pkg, scripts: target.scripts }, null, 2)}\n`;
   }
+  if (target.mode === 'section') return `${target.content}${bootstrapSection(existing ?? '').section ?? ''}`;
   if (target.mode === 'block' && existing) {
     const current = managedPart('block', existing, target.markers);
     if (current !== null) return existing.replace(current, () => target.content);
@@ -571,6 +590,12 @@ export async function renderRepo(root, { presets, parseYaml, notices, manifest =
 
 /** The folders a lite app's sync retires (ruling lite-self-hosted-postgres-passport-minio): the generated Supabase row types nothing reads any more. */
 const LITE_RETIRED_DIRS = Object.freeze(['supabase/types']);
+/** The files a lite app's sync retires, each with the reason --check prints. */
+const LITE_RETIRED_FILES = Object.freeze({
+  [RETIRED_DB_DOCKERFILE]: `the db image moved to ${DB_DOCKERFILE} (ruling lite-db-image-in-stacks)`,
+});
+/** Why a retired file goes: a retired file's own reason, else the folder's. */
+const retiredReason = (file) => LITE_RETIRED_FILES[file] ?? 'the lite edition generates no database types';
 
 /** The app-relative files of the retired folders that still exist under `root` of a lite app; sync --write deletes them, --check reports them. */
 export function retiredFiles(root, hfs) {
@@ -584,6 +609,7 @@ export function retiredFiles(root, hfs) {
     else found.push(rel);
   };
   for (const dir of LITE_RETIRED_DIRS) walk(dir);
+  for (const file of Object.keys(LITE_RETIRED_FILES)) walk(file);
   return found;
 }
 
@@ -602,7 +628,7 @@ function syncOptions(argv) {
 function reportSyncCheck(root, targets, out, retired = []) {
   const results = checkTargets(root, targets);
   const bad = results.filter(item => item.status !== 'ok');
-  for (const file of retired) out(`HFS_SYNC_DRIFT ${file}: retired, the lite edition generates no database types; run "npx starci app sync --write" to delete it`);
+  for (const file of retired) out(`HFS_SYNC_DRIFT ${file}: retired, ${retiredReason(file)}; run "npx starci app sync --write" to delete it`);
   for (const result of bad) {
     const found = result.actualHash ? `, found ${result.actualHash.slice(0, 12)}` : '';
     const where = result.difference ? ` (line ${result.difference.line}: expected ${JSON.stringify(result.difference.expected)}, found ${JSON.stringify(result.difference.actual)})` : '';

package/templates/app/ci-workflows/github/workflows/images.yml

@@ -1,6 +1,8 @@
 {{header}}
 # Builds the image of every app on its release tag, so a Dockerfile that no longer builds fails that release.
 # It never pushes: publishing an image is the product's decision, not this file's.
+# When an environment declares images, the job is bound to that protected GitHub environment and opens its sealed build
+# arguments with that environment's SOPS_AGE_KEY (its server identity, starci app secret server-key <env> --backup github).
 name: images
 
 on:

package/templates/app/ci-workflows/github/workflows/stack-deploy.yml

@@ -7,7 +7,9 @@
 # operation rollback  redeploys a stored release; "release" is 16 lowercase hex characters, empty means the previous accepted release
 # The environment input names a protected GitHub environment (required reviewers) that holds:
 #   vars    VPS_HOST, VPS_USER (the swarm manager); a variable named in deploy.passEnv, when the stack interpolates one
-#   secrets SOPS_AGE_KEY (the age identity of .sops.yaml), VPS_SSH_KEY (CI-only deploy key), VPS_KNOWN_HOSTS (pinned host keys)
+#   secrets SOPS_AGE_KEY (that environment's server identity, stored there by starci app secret server-key <env> --backup github;
+#           both jobs are bound to the environment, so they read it and never a repository secret of that name), VPS_SSH_KEY
+#           (CI-only deploy key), VPS_KNOWN_HOSTS (pinned host keys)
 # Nothing else is a secret: images are pushed with the workflow token, which also reads the CI verdict of the tag's commit a production deploy
 # waits for (requireCi deploy.prod). Dispatch inputs reach scripts only through env.
 name: deploy stack

package/templates/app/ci-workflows/github/workflows/stack-key-restore.yml

@@ -0,0 +1,58 @@
+{{header}}
+# Restores the deploy server's age identity from its GitHub Environment backup (starci app secret server-key <env> --backup github
+# stored it; --restore github dispatches this file). It runs by hand only and writes {{serverAgeIdentity}} on the server when no
+# identity is there and the secret's public key is the recipient input (deploy.remote.serverRecipient), with umask 077 and mode 600,
+# owned by root; it never echoes the identity and never overwrites one.
+# The environment input names the protected GitHub environment of the deploy (required reviewers or main only), which holds:
+#   vars    VPS_HOST, VPS_USER (the swarm manager)
+#   secrets SOPS_AGE_KEY (that environment's server identity, the one its deploy jobs read), VPS_SSH_KEY (CI-only deploy key),
+#           VPS_KNOWN_HOSTS (pinned host keys)
+name: restore stack key
+
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: Protected environment holding the deploy transport and the server identity backup
+        required: true
+        type: environment
+      recipient:
+        description: The public age recipient of the server identity, deploy.remote.serverRecipient of that environment
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: stack-${{ inputs.environment }}
+  cancel-in-progress: false
+
+jobs:
+  restore:
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.environment }}
+    timeout-minutes: 10
+    steps:
+      - name: write the identity on the server
+        env:
+          RECIPIENT: ${{ inputs.recipient }}
+          AGE_IDENTITY: ${{ secrets.SOPS_AGE_KEY }}
+          VPS_SSH_KEY: ${{ secrets.VPS_SSH_KEY }}
+          VPS_KNOWN_HOSTS: ${{ secrets.VPS_KNOWN_HOSTS }}
+          VPS_HOST: ${{ vars.VPS_HOST }}
+          VPS_USER: ${{ vars.VPS_USER }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          [[ "$RECIPIENT" =~ ^age1[a-z0-9]+$ ]] || { echo "recipient must be one public age recipient (age1...)" >&2; exit 1; }
+          [ -n "$AGE_IDENTITY" ] || { echo "SOPS_AGE_KEY is not set in this environment" >&2; exit 1; }
+          umask 077
+          dir="$(mktemp -d)"
+          trap 'rm -rf "$dir"' EXIT
+          printf '%s\n' "$VPS_SSH_KEY" > "$dir/id"
+          printf '%s\n' "$VPS_KNOWN_HOSTS" > "$dir/known_hosts"
+          # The server writes the identity beside its target, keeps it only when its public key is the recipient, then moves it in.
+          remote="f={{serverAgeIdentity}}; r=$RECIPIENT; "'if [ "$(id -u)" -eq 0 ]; then S=; else S="sudo -n"; fi; if $S test -e "$f"; then cat >/dev/null; echo "the server already holds $f; move it aside first" >&2; exit 3; fi; $S sh -c '"'"'umask 077; f="$1"; r="$2"; d="$(dirname "$f")"; mkdir -p "$d"; t="$(mktemp "$d/.restore.XXXXXX")"; cat > "$t"; if [ "$(age-keygen -y "$t" 2>/dev/null)" != "$r" ]; then rm -f "$t"; echo "the secret is not the identity of $r (or age-keygen is missing); nothing was written" >&2; exit 6; fi; chown root:root "$t"; chmod 600 "$t"; mv "$t" "$f"; age-keygen -y "$f"'"'"' sh "$f" "$r"'
+          printf '%s\n' "$AGE_IDENTITY" | ssh -T -i "$dir/id" -o IdentitiesOnly=yes -o UserKnownHostsFile="$dir/known_hosts" \
+            -o StrictHostKeyChecking=yes -o BatchMode=yes -o ConnectTimeout=20 "$VPS_USER@$VPS_HOST" "$remote"

package/templates/app/ci-workflows-lite/github/workflows/images.yml

@@ -1,6 +1,8 @@
 {{header}}
 # Builds each image declared by the lite app. The API image is required; a front-end image is emitted only when declared.
 # It runs on the release tag, so every image is built there, and never pushes.
+# When an environment declares images, the job is bound to that protected GitHub environment and opens its sealed build
+# arguments with that environment's SOPS_AGE_KEY (its server identity, starci app secret server-key <env> --backup github).
 name: images
 
 on:

package/templates/app/ci-workflows-lite/github/workflows/stack-deploy.yml

@@ -7,7 +7,9 @@
 # operation rollback  redeploys a stored release; "release" is 16 lowercase hex characters, empty means the previous accepted release
 # The environment input names a protected GitHub environment (required reviewers) that holds:
 #   vars    VPS_HOST, VPS_USER (the swarm manager); a variable named in deploy.passEnv, when the stack interpolates one
-#   secrets SOPS_AGE_KEY (the age identity of .sops.yaml), VPS_SSH_KEY (CI-only deploy key), VPS_KNOWN_HOSTS (pinned host keys)
+#   secrets SOPS_AGE_KEY (that environment's server identity, stored there by starci app secret server-key <env> --backup github;
+#           both jobs are bound to the environment, so they read it and never a repository secret of that name), VPS_SSH_KEY
+#           (CI-only deploy key), VPS_KNOWN_HOSTS (pinned host keys)
 # Nothing else is a secret: images are pushed with the workflow token, which also reads the CI verdict of the tag's commit a production deploy
 # waits for (requireCi deploy.prod). Dispatch inputs reach scripts only through env.
 name: deploy stack

package/templates/app/ci-workflows-lite/github/workflows/stack-key-restore.yml

@@ -0,0 +1,58 @@
+{{header}}
+# Restores the deploy server's age identity from its GitHub Environment backup (starci app secret server-key <env> --backup github
+# stored it; --restore github dispatches this file). It runs by hand only and writes {{serverAgeIdentity}} on the server when no
+# identity is there and the secret's public key is the recipient input (deploy.remote.serverRecipient), with umask 077 and mode 600,
+# owned by root; it never echoes the identity and never overwrites one.
+# The environment input names the protected GitHub environment of the deploy (required reviewers or main only), which holds:
+#   vars    VPS_HOST, VPS_USER (the swarm manager)
+#   secrets SOPS_AGE_KEY (that environment's server identity, the one its deploy jobs read), VPS_SSH_KEY (CI-only deploy key),
+#           VPS_KNOWN_HOSTS (pinned host keys)
+name: restore stack key
+
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: Protected environment holding the deploy transport and the server identity backup
+        required: true
+        type: environment
+      recipient:
+        description: The public age recipient of the server identity, deploy.remote.serverRecipient of that environment
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: stack-${{ inputs.environment }}
+  cancel-in-progress: false
+
+jobs:
+  restore:
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.environment }}
+    timeout-minutes: 10
+    steps:
+      - name: write the identity on the server
+        env:
+          RECIPIENT: ${{ inputs.recipient }}
+          AGE_IDENTITY: ${{ secrets.SOPS_AGE_KEY }}
+          VPS_SSH_KEY: ${{ secrets.VPS_SSH_KEY }}
+          VPS_KNOWN_HOSTS: ${{ secrets.VPS_KNOWN_HOSTS }}
+          VPS_HOST: ${{ vars.VPS_HOST }}
+          VPS_USER: ${{ vars.VPS_USER }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          [[ "$RECIPIENT" =~ ^age1[a-z0-9]+$ ]] || { echo "recipient must be one public age recipient (age1...)" >&2; exit 1; }
+          [ -n "$AGE_IDENTITY" ] || { echo "SOPS_AGE_KEY is not set in this environment" >&2; exit 1; }
+          umask 077
+          dir="$(mktemp -d)"
+          trap 'rm -rf "$dir"' EXIT
+          printf '%s\n' "$VPS_SSH_KEY" > "$dir/id"
+          printf '%s\n' "$VPS_KNOWN_HOSTS" > "$dir/known_hosts"
+          # The server writes the identity beside its target, keeps it only when its public key is the recipient, then moves it in.
+          remote="f={{serverAgeIdentity}}; r=$RECIPIENT; "'if [ "$(id -u)" -eq 0 ]; then S=; else S="sudo -n"; fi; if $S test -e "$f"; then cat >/dev/null; echo "the server already holds $f; move it aside first" >&2; exit 3; fi; $S sh -c '"'"'umask 077; f="$1"; r="$2"; d="$(dirname "$f")"; mkdir -p "$d"; t="$(mktemp "$d/.restore.XXXXXX")"; cat > "$t"; if [ "$(age-keygen -y "$t" 2>/dev/null)" != "$r" ]; then rm -f "$t"; echo "the secret is not the identity of $r (or age-keygen is missing); nothing was written" >&2; exit 6; fi; chown root:root "$t"; chmod 600 "$t"; mv "$t" "$f"; age-keygen -y "$f"'"'"' sh "$f" "$r"'
+          printf '%s\n' "$AGE_IDENTITY" | ssh -T -i "$dir/id" -o IdentitiesOnly=yes -o UserKnownHostsFile="$dir/known_hosts" \
+            -o StrictHostKeyChecking=yes -o BatchMode=yes -o ConnectTimeout=20 "$VPS_USER@$VPS_HOST" "$remote"

package/templates/app/db-bootstrap/db/bootstrap.sql

@@ -1,16 +1,18 @@
 -- Managed by starci app sync (slot app.db.bootstrap); do not edit: run "npx starci app sync --write".
 -- The pre-migration bootstrap of a lite app's self-hosted PostgreSQL (ruling lite-self-hosted-postgres-passport-minio), run on the official
--- postgres image of db/Dockerfile (ruling lite-official-postgres-image). Migrations written for Supabase reference objects GoTrue and Supabase
+-- postgres image of .starcistacks/images/db/Dockerfile (ruling lite-official-postgres-image). Migrations written for Supabase reference objects GoTrue and Supabase
 -- Storage created: the browser roles, the `auth` schema (auth.users, auth.identities, auth.sessions, auth.uid/jwt/role) and the `storage`
 -- schema (storage.buckets, storage.objects). A lite app runs neither GoTrue nor storage-api: auth is the app's own (integrations/passport) and
--- storage is the S3 endpoint of integrations/object-storage. This file gives the migrations those objects, EMPTY, and nothing else; nothing
--- else of Supabase (supabase_admin, the `extensions` schema, the realtime publication) exists. It is idempotent; `starci app db migrate`
--- applies it as the database owner before the first migration of an empty database.
+-- storage is the S3 endpoint of integrations/object-storage. This file gives the migrations those objects, EMPTY, and the `extensions` schema
+-- every allowed extension is created in (`create extension ... with schema extensions`, the app role's search_path is `public, extensions`);
+-- nothing else of Supabase (supabase_admin, the realtime publication) exists. It is idempotent; `starci app db migrate` applies it as the
+-- database owner before the first migration of an empty database.
 --
 -- auth.users keeps the GoTrue column set so restored rows and foreign keys from public tables stay valid; encrypted_password holds bcrypt hashes.
 -- auth.uid(), auth.role() and auth.jwt() read the request.jwt.claims setting; the API connects as app_be and sets none, so they return NULL and
 -- every policy that names them denies the browser roles, which have no door in lite.
 
+create schema if not exists extensions;
 create schema if not exists auth;
 create schema if not exists storage;
 
@@ -23,6 +25,7 @@ end
 $roles$;
 
 grant usage on schema auth, storage to anon, authenticated, service_role;
+grant usage on schema extensions to anon, authenticated, service_role;
 
 -- auth.users: the full GoTrue column set (a copy an earlier database carries is extended in place).
 create table if not exists auth.users (id uuid primary key);

package/templates/app/db-image/starcistacks/images/db/Dockerfile

@@ -0,0 +1,18 @@
+# Managed by starci app sync (slot app.db.image); do not edit: run "npx starci app sync --write".
+# The image of the db service of a lite app, kept with the stacks (rulings lite-official-postgres-image, lite-pgmq-bus-bullmq-jobs and
+# lite-db-image-in-stacks): the Docker Official postgres image, pinned by digest, plus pgvector from the PGDG repository the image
+# already configures and pgmq, the event bus, from its pinned release source verified by sha256 (pgmq is SQL objects only, so its
+# control and script files are copied and nothing is compiled; it installs into its own schema pgmq). The contrib extensions
+# (pgcrypto, pg_trgm, unaccent, uuid-ossp, btree_gist) ship in the image. The stack's db service, `npm run db:create`,
+# `starci app db drift` and `starci app db baseline --squash` all build this file, with this folder as the build context.
+FROM {{dbBaseImage}}
+ADD --checksum=sha256:{{pgmqSha256}} {{pgmqSource}} /tmp/pgmq.tar.gz
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends {{pgvectorPackage}} \
+    && rm -rf /var/lib/apt/lists/* \
+    && tar -xzf /tmp/pgmq.tar.gz -C /tmp \
+    && extension="$(pg_config --sharedir)/extension" \
+    && cp /tmp/pgmq-{{pgmqVersion}}/pgmq-extension/pgmq.control "$extension/" \
+    && cp /tmp/pgmq-{{pgmqVersion}}/pgmq-extension/sql/pgmq.sql "$extension/pgmq--{{pgmqVersion}}.sql" \
+    && cp /tmp/pgmq-{{pgmqVersion}}/pgmq-extension/sql/pgmq--*--*.sql "$extension/" \
+    && rm -rf /tmp/pgmq.tar.gz /tmp/pgmq-{{pgmqVersion}}

package/templates/app/gitignore

@@ -7,7 +7,7 @@ schema.gql
 .next/
 next-env.d.ts
 # .starcistacks custody at the app root: modules/schemas/stacks-layout.yaml custody.gitignoreRules, in order. Only the
-# declaration, runbooks, key lists, seeds, the rendered environment, the infra definitions and sealed *.enc are tracked.
+# declaration, runbooks, key lists, seeds, the rendered environment, the infra definitions and sealed members (*.enc.yaml, legacy *.enc) are tracked.
 .starcistacks/**
 !.starcistacks/**/
 !.starcistacks/**/KEYS.md
@@ -32,6 +32,7 @@ next-env.d.ts
 .starcistacks/*/infra/terraform/*.tfstate.*
 .starcistacks/*/infra/terraform/files/
 .starcistacks/*/infra/terraform/*.tar.gz
+!.starcistacks/**/secrets/*.enc.yaml
 !.starcistacks/**/*.enc
 
 # Host-local agent credentials and app age identity never enter Git.

package/templates/app/gitignore-lite

@@ -7,12 +7,13 @@ schema.gql
 .next/
 next-env.d.ts
 # .starcistacks custody at the app root: modules/schemas/stacks-layout.yaml custody.gitignoreRules, in order. Only the
-# declaration, runbooks, key lists, seeds, the rendered environment, the infra definitions and sealed *.enc are tracked.
+# declaration, runbooks, key lists, seeds, the rendered environment, the infra definitions, the db image and sealed members (*.enc.yaml, legacy *.enc) are tracked.
 .starcistacks/**
 !.starcistacks/**/
 !.starcistacks/**/KEYS.md
 !.starcistacks/**/.gitkeep
 !.starcistacks/application-stacks.yaml
+!.starcistacks/images/db/Dockerfile
 !.starcistacks/*/README.md
 !.starcistacks/*/environment.json
 !.starcistacks/*/seeds/**
@@ -32,6 +33,7 @@ next-env.d.ts
 .starcistacks/*/infra/terraform/*.tfstate.*
 .starcistacks/*/infra/terraform/files/
 .starcistacks/*/infra/terraform/*.tar.gz
+!.starcistacks/**/secrets/*.enc.yaml
 !.starcistacks/**/*.enc
 
 # Host-local agent credentials and app age identity never enter Git.

package/templates/app/package-scripts/db.json

@@ -1,4 +1,4 @@
-    "db:image": "docker build --tag {{dbImage}} db",
+    "db:image": "docker build --tag {{dbImage}} .starcistacks/images/db",
     "db:create": "npm run db:image && docker create --name {{project}}-dev-db -p 127.0.0.1:54322:5432 -e POSTGRES_HOST_AUTH_METHOD=trust -v {{project}}-dev-db-data:/var/lib/postgresql/data {{dbImage}}",
     "db:start": "docker start {{project}}-dev-db",
     "db:stop": "docker stop {{project}}-dev-db",

package/templates/app/skeleton-lite/.starcistacks/application-stacks.yaml

@@ -29,7 +29,7 @@ components:
     volumes: [db-data]
     image: "{{project}}/db:v0.0.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"
     compose: infra/swarm/stack.yaml
-    purpose: The app's own PostgreSQL, the official postgres image plus pgvector built from db/Dockerfile, migrated by starci app db migrate.
+    purpose: The app's own PostgreSQL, the official postgres image plus pgvector built from .starcistacks/images/db/Dockerfile, migrated by starci app db migrate.
     required: true
   ingress:
     role: ingress

package/templates/app/skeleton-lite/.starcistacks/dev/README.md

@@ -1,6 +1,6 @@
 # Development stack
 
-Every development dependency runs in Docker Linux containers. The `db` service (the official postgres image plus pgvector, built from `db/Dockerfile`) starts with `npm run db:start` and takes the migrations with `npm run db:push`; storage is the S3-compatible MinIO the environment names. Every other declared dependency, such as Redis, starts through its managed `<dep>:create`, `<dep>:start` and `<dep>:stop` scripts or the declared container model; Compose is an implementation detail. The app services may run in the local Docker Swarm model or through a declared native development profile while dependencies stay in Docker.
+Every development dependency runs in Docker Linux containers. The `db` service (the official postgres image plus pgvector, built from `.starcistacks/images/db/Dockerfile`) starts with `npm run db:start` and takes the migrations with `npm run db:push`; storage is the S3-compatible MinIO the environment names. Every other declared dependency, such as Redis, starts through its managed `<dep>:create`, `<dep>:start` and `<dep>:stop` scripts or the declared container model; Compose is an implementation detail. The app services may run in the local Docker Swarm model or through a declared native development profile while dependencies stay in Docker.
 The application image references contain illustrative all-zero digests. Replace them with verified published release digests in the manifest, model and `.starcistacks/dev/infra/swarm/releases/images.lock.yaml` before starting the container model. Seal the local database connection and the integration credentials; a container cannot use the host's loopback address without owner-configured networking. Local source development remains available through the app scripts.
 
 The runtime template tracks no encrypted members. Scaffolding generates the six declared members with placeholder values encrypted to this app's own recipient in `.sops.yaml`. Replace those values with `starci app secret set dev` using the matching host age identity in untracked local custody. Existing generated envelopes are decryptable with that app identity and can be updated in place. Each Docker secret contains the corresponding key's real value, and the API receives it through its declared mounted file.

package/templates/app/skeleton-lite/.starcistacks/production/README.md

@@ -1,7 +1,7 @@
 # Production stack
 
 The tracked model declares Docker Swarm application services and one digest-pinned Caddy ingress.
-The `db` service (the official postgres image plus pgvector, built from `db/Dockerfile` and pushed with the release images) supplies PostgreSQL on a named volume; sign-in is the API's own (Passport) and storage is the S3-compatible MinIO the environment names. The app and its dependencies run on Docker Swarm. A Redis service runs only when `hfs.json` `sides.be.backing` declares it for a capability that needs it: one stateful replica with a digest-pinned image, a named volume with a backup entry and its password as a sealed member granted as a Swarm secret (Redis runs `--appendonly yes` with the volume at `/data`). The scaffold declares none; `starci app add queue|job` declares Redis and renders it here.
+The `db` service (the official postgres image plus pgvector, built from `.starcistacks/images/db/Dockerfile` and pushed with the release images) supplies PostgreSQL on a named volume; sign-in is the API's own (Passport) and storage is the S3-compatible MinIO the environment names. The app and its dependencies run on Docker Swarm. A Redis service runs only when `hfs.json` `sides.be.backing` declares it for a capability that needs it: one stateful replica with a digest-pinned image, a named volume with a backup entry and its password as a sealed member granted as a Swarm secret (Redis runs `--appendonly yes` with the volume at `/data`). The scaffold declares none; `starci app add queue|job` declares Redis and renders it here.
 The model is a deployment declaration. It contains no owner credentials, real DNS receipt, completed release or restore proof. Public records under `.starcistacks/production/infra/swarm/` explicitly mark those owner-run operations as pending.
 Its application image references contain illustrative all-zero digests; they identify no published image and must be replaced before deployment.
 

package/templates/app/skeleton-lite/README.md

@@ -8,7 +8,7 @@ The starter keeps one deployable API and one web app, with the same code structu
 
 ## Stack
 
-TypeScript everywhere, NestJS in `be/`, Next.js with next-intl in `fe/`, PostgreSQL (the `db` service: the official postgres image plus pgvector, built from `db/Dockerfile`), Passport for Google and password sign-in, S3-compatible storage (MinIO), npm workspaces, and Turbo for front-end tasks.
+TypeScript everywhere, NestJS in `be/`, Next.js with next-intl in `fe/`, PostgreSQL (the `db` service: the official postgres image plus pgvector, built from `.starcistacks/images/db/Dockerfile`), Passport for Google and password sign-in, S3-compatible storage (MinIO), npm workspaces, and Turbo for front-end tasks.
 
 ## Repository layout
 
@@ -24,7 +24,7 @@ Declare `ci.github.repository` and `ci.github.defaultBranch` in `.starcistacks/a
 
 ## Development
 
-Every development dependency runs in Docker Linux containers. Create the local database once with `npm run db:create`, start it with `npm run db:start` (one container of the image `db/Dockerfile` builds, on 127.0.0.1:54322), export `DATABASE_URL=postgresql://postgres@127.0.0.1:54322/postgres` and apply `db/bootstrap.sql` and the migrations with `npm run db:push`; start any other declared dependency through its managed `<dep>:create`, `<dep>:start` and `<dep>:stop` scripts or the declared container model. Compose is an implementation detail. Configure the local environment and start the API and web app using the package scripts for the declared development profile. In production, the app and its dependencies, the database included, run on Docker Swarm; pgvector owns vector search.
+Every development dependency runs in Docker Linux containers. Create the local database once with `npm run db:create`, start it with `npm run db:start` (one container of the image `.starcistacks/images/db/Dockerfile` builds, on 127.0.0.1:54322), export `DATABASE_URL=postgresql://postgres@127.0.0.1:54322/postgres` and apply `db/bootstrap.sql` and the migrations with `npm run db:push`; start any other declared dependency through its managed `<dep>:create`, `<dep>:start` and `<dep>:stop` scripts or the declared container model. Compose is an implementation detail. Configure the local environment and start the API and web app using the package scripts for the declared development profile. In production, the app and its dependencies, the database included, run on Docker Swarm; pgvector owns vector search.
 
 ```sh
 npm install

package/templates/be/inbox/delivery-recorded.event.ts.tpl

@@ -3,6 +3,8 @@ import type { ParsedEvent } from "@modules/platform/event-bus"
 
 /** A durable receipt reference; processing reads the provider payload after the intake commits. */
 export interface @@Provider@@DeliveryRecordedPayload {
+    /** The business key a consumer's inbox claims: the receipt, once per consumer however often it is delivered. */
+    readonly dedupeKey: string
     readonly receiptId: string
 }
 
@@ -20,17 +22,17 @@ export class @@Provider@@DeliveryRecordedEvent extends BaseEvent {
         super()
     }
 
-    /** The receipt identity is stable across relay retries and distinct from a consumer's inbox source. */
-    static create(payload: @@Provider@@DeliveryRecordedPayload): @@Provider@@DeliveryRecordedEvent {
-        return new @@Provider@@DeliveryRecordedEvent(payload.receiptId, payload)
+    /** The receipt identity is stable across redeliveries and distinct from a consumer's inbox source. */
+    static create(payload: Omit<@@Provider@@DeliveryRecordedPayload, "dedupeKey">): @@Provider@@DeliveryRecordedEvent {
+        return new @@Provider@@DeliveryRecordedEvent(payload.receiptId, { dedupeKey: payload.receiptId, receiptId: payload.receiptId })
     }
 
-    /** Reads an outbox envelope; malformed deliveries never reach a processing consumer. */
+    /** Reads the event envelope; malformed deliveries never reach a processing consumer. */
     static parse(envelope: unknown): ParsedEvent<@@Provider@@DeliveryRecordedEvent> {
         if (typeof envelope !== "object" || envelope === null || !("eventId" in envelope) || !("payload" in envelope)) return null
         const { eventId, payload } = envelope
         if (typeof eventId !== "string" || !eventId.trim() || typeof payload !== "object" || payload === null || !("receiptId" in payload)) return null
         if (typeof payload.receiptId !== "string" || !payload.receiptId.trim()) return null
-        return new @@Provider@@DeliveryRecordedEvent(eventId, { receiptId: payload.receiptId })
+        return new @@Provider@@DeliveryRecordedEvent(eventId, { dedupeKey: payload.receiptId, receiptId: payload.receiptId })
     }
 }

package/templates/be/inbox/events.json.tpl

@@ -1,7 +1,7 @@
 {
   "events": {
     "@@provider@@.delivery-recorded": {
-      "payload": { "receiptId": "string" },
+      "payload": { "dedupeKey": "string", "receiptId": "string" },
       "version": 1
     }
   },

package/templates/be/inbox/platform/event-bus/event-bus.contracts.ts.tpl

@@ -1,23 +1,38 @@
+/**
+ * The suffix of a consumer's dead-letter queue: a delivery past its consumer's maxDeliveries moves from `<topic>__<consumer>` to
+ * `<topic>__<consumer>__dead`, which an operator reads and replays (BE-EVENT-BUS-4).
+ */
+export const DEAD_QUEUE_SUFFIX = "__dead"
+
+/** The deliveries a consumer gets before its message moves to the dead-letter queue, when its subscription names none. */
+export const DEFAULT_MAX_DELIVERIES = 5
+
+/** What every event payload carries: the business key a consumer's inbox claims, stable across redelivery and replay. */
+export interface EventPayload {
+    /** The business identity of the fact (an order id, a receipt id): the consumer claims (consumer, dedupeKey) once. */
+    readonly dedupeKey: string
+}
+
 /** The base of each typed event in modules/events: its stable identity, name and payload. */
 export abstract class BaseEvent {
-    /** A receiver uses this stable identity to deduplicate redelivery. */
+    /** The stable identity of this event, carried for logs and tracing. */
     abstract readonly eventId: string
-    /** The event name listed by the service's vendored event contract. */
+    /** The event name listed by the service's vendored event contract; it is the pgmq topic the event is sent to. */
     abstract readonly eventName: string
-    /** The fact that a reactor or job processes after commit. */
-    abstract readonly payload: object
+    /** The fact that a reactor processes after commit, with its business dedupe key. */
+    abstract readonly payload: EventPayload
 }
 
 /** Parsing either returns the event or refuses a mismatched envelope. */
 export type ParsedEvent<Event extends BaseEvent> = Event | null
 
-/** The class side of a typed event, shared by publishers and later consumers. */
+/** The class side of a typed event, shared by publishers and consumers. */
 export interface EventClass<Event extends BaseEvent> {
     /** The contract's event name. */
     readonly eventName: string
     /** The contract's payload version. */
     readonly version: number
-    /** Reads the event from its durable envelope. */
+    /** Reads the event from its envelope. */
     parse(envelope: unknown): ParsedEvent<Event>
 }
 
@@ -25,21 +40,25 @@ export interface EventClass<Event extends BaseEvent> {
 export interface EventDelivery<Event extends BaseEvent> {
     /** The request id carried explicitly from intake to delivery. */
     readonly correlationId: string
-    /** The consumer's idempotency key. */
+    /** The stable identity of the event. */
     readonly eventId: string
+    /** The consumer's queue, `<topic>__<consumer>`: the first half of the inbox claim. */
+    readonly consumer: string
+    /** The payload's business key: the second half of the inbox claim. */
+    readonly dedupeKey: string
     /** The typed event. */
     readonly event: Event
-    /** The number of attempts, including this one. */
+    /** The number of deliveries, including this one. */
     readonly attempt: number
 }
 
 /** Explicit request context carried independently of the business payload. */
 export interface EventMetadata {
-    /** The originating request or promoted legacy event identity. */
+    /** The originating request or promoted event identity. */
     readonly correlationId: string
 }
 
-/** The typed event's durable envelope, read only after the intake transaction commits. */
+/** The typed event's envelope, sent once to its topic in the publisher's transaction and routed to every bound consumer queue. */
 export interface EventEnvelope {
     /** The originating request context, independent of the business payload. */
     readonly metadata: EventMetadata
@@ -48,5 +67,33 @@ export interface EventEnvelope {
     /** The contract's event name. */
     readonly eventName: string
     /** The data of the fact. */
-    readonly payload: object
+    readonly payload: EventPayload
+}
+
+/** One message of a consumer's queue, as event_bus_read returns it. */
+export interface EventMessage {
+    /** The pgmq message id within its queue. */
+    readonly msgId: string
+    /** How many times the message has been read, including this read. */
+    readonly readCt: number
+    /** The envelope as the publisher sent it; untrusted until parsed. */
+    readonly message: unknown
+}
+
+/** What a reactor's subscription may tune; every field is a literal of the subscription. */
+export interface EventSubscriptionOptions {
+    /** The deliveries before the message moves to the dead-letter queue. Default DEFAULT_MAX_DELIVERIES. */
+    readonly maxDeliveries?: number
+}
+
+/** A delivery a consumer gave up on, as its dead-letter queue holds it. */
+export interface DeadLetter {
+    /** The message id in the dead-letter queue: what requeue takes. */
+    readonly id: string
+    /** Why it was moved: its deliveries ran out, or its envelope was malformed. */
+    readonly reason: string
+    /** The deliveries it had. */
+    readonly readCount: number
+    /** The envelope as it was read. */
+    readonly message: unknown
 }