@starci/hfs 4.11.0 → 4.11.8

package/stack/remote.mjs

@@ -8,6 +8,7 @@
 // `bash -s` fail with `set: pipefail`). Key material lives in memory and in a private temp directory only; it is never in argv (only the key
 // FILE path is), in a line, in a result or in an error message.
 import fs from 'node:fs';
+import { isLegacyName, memberFile } from '../runtime/scripts/lib/sealed-member.mjs';
 import os from 'node:os';
 import path from 'node:path';
 import { tool } from './context.mjs';
@@ -78,7 +79,7 @@ function openMember(slug, read) {
 
 function opsAccount(ctx, config) {
   const slug = config.remote.sealed.ops;
-  const map = openMember(slug, () => ctx.sops.decrypt(path.join(config.secretsDir, `${slug}.enc`), 'dotenv'));
+  const map = openMember(slug, () => ctx.sops.decrypt(memberFile(config.secretsDir, slug), isLegacyName(memberFile(config.secretsDir, slug)) ? 'dotenv' : 'yaml'));
   for (const name of ['VPS_HOST', 'VPS_USER']) {
     const value = map[name];
     if (typeof value !== 'string' || !ACCOUNT.test(value) || value.startsWith('-')) throw refusal('STACK_REMOTE_OPS', `${slug} must hold ${name} (letters, digits, . _ @ -)`);
@@ -87,7 +88,7 @@ function opsAccount(ctx, config) {
 }
 
 function binaryMember(ctx, config, slug, names) {
-  return unwrap(openMember(slug, () => ctx.sops.decryptBinary(path.join(config.secretsDir, `${slug}.enc`))), names);
+  return unwrap(openMember(slug, () => ctx.sops.decryptBinary(memberFile(config.secretsDir, slug))), names);
 }
 
 const withNewline = (text) => `${text.trim()}\n`;
@@ -159,7 +160,7 @@ function withOwnerTransport(ctx, config, { sshCmd = null } = {}) {
   const { sealed } = config.remote;
   if (config.nativeTarget) return Object.create(ctx, { env: { value: { ...ctx.env, STARCI_STACK_SEALED_SSH: '1' }, enumerable: true } });
   if (sshCmd || !sealed || ctx.env.GITHUB_ACTIONS === 'true' || ctx.env.STARCI_STACK_SEALED_SSH !== undefined) return ctx;
-  const present = [sealed.ops, sealed.sshKey, sealed.knownHosts].every((slug) => fs.existsSync(path.join(config.secretsDir, `${slug}.enc`)));
+  const present = [sealed.ops, sealed.sshKey, sealed.knownHosts].every((slug) => fs.existsSync(memberFile(config.secretsDir, slug)));
   if (!present) return ctx;
   return Object.create(ctx, { env: { value: { ...ctx.env, STARCI_STACK_SEALED_SSH: '1' }, enumerable: true } });
 }

package/stack/sealed.mjs

@@ -2,6 +2,7 @@
 // service is granted (the shared half of the release tools). No value is ever written to disk, printed or put in an argument list:
 // callers receive `value` and must keep it in memory. Config objects (non-secret files mounted into services) are versioned by content.
 import { createHash, createHmac } from 'node:crypto';
+import { memberFile } from '../runtime/scripts/lib/sealed-member.mjs';
 import fs from 'node:fs';
 import path from 'node:path';
 import { secretRoots } from '../runtime/scripts/hfs/secret-files.mjs';
@@ -65,10 +66,10 @@ export function requireAgeIdentity(ctx, config, purpose) {
   if (!hasAgeIdentity(ctx, config)) throw refusal('STACK_AGE_IDENTITY_MISSING', `${purpose} needs the sealed members, and no age identity is available: ${AGE_HINT}`);
 }
 
-/** Opens one sealed member (`<secretsDir>/<member>.enc`) into a { KEY: value } map. Names the member only on failure. */
+/** Opens one sealed member (`<secretsDir>/<member>.enc.yaml`, or a legacy `.enc`) into a { KEY: value } map. Names the member only on failure. */
 export function openMember(ctx, config, member) {
   try {
-    const map = readMap(path.join(config.secretsDir, `${member}.enc`), ctx.sops);
+    const map = readMap(memberFile(config.secretsDir, member), ctx.sops);
     return Object.fromEntries(Object.entries(map).map(([key, value]) => [key, typeof value === 'string' && !value.includes(String.fromCodePoint(0)) ? lfText(value) : value]));
   } catch {
     throw refusal('STACK_SECRET_MEMBER_UNREADABLE', `the sealed member ${member} cannot be opened${hasAgeIdentity(ctx, config) ? ' (is the age identity a recipient of this member?)' : `: no age identity is available, ${AGE_HINT}`}`);
@@ -116,13 +117,13 @@ function sealGrants(config, memberOf, versionKey) {
 }
 
 function sealSettings(config, memberOf) {
-  const block = config.secrets.settings;
-  if (block === null) return {};
-  const map = memberOf(block.member);
   const settings = {};
-  for (const key of block.keys.filter((name) => present(map, name))) {
-    if (UNSAFE_SETTING.test(map[key])) throw refusal('STACK_SETTING_INVALID', `${key} must be a plain one-line value`);
-    settings[key] = map[key];
+  for (const block of config.secrets.settings) {
+    const map = memberOf(block.member);
+    for (const key of block.keys.filter((name) => present(map, name))) {
+      if (UNSAFE_SETTING.test(map[key])) throw refusal('STACK_SETTING_INVALID', `${key} must be a plain one-line value`);
+      settings[key] = map[key];
+    }
   }
   return settings;
 }

package/stack/target-binding.mjs

@@ -1,5 +1,6 @@
 // Public endpoint assertions for admitted native consumers; this module never opens custody.
 import fs from 'node:fs';
+import { memberFile } from '../runtime/scripts/lib/sealed-member.mjs';
 import path from 'node:path';
 import { refusal } from './errors.mjs';
 
@@ -52,7 +53,7 @@ export function bindStackTarget(ctx, config, binding) {
     || !config.remote.sealed || ctx.env.DOCKER_HOST || ctx.env.DOCKER_CONTEXT || ctx.env.GITHUB_ACTIONS
     || ctx.env.STARCI_STACK_SEALED_SSH !== undefined) denied();
   for (const member of Object.values(config.remote.sealed)) {
-    const file = path.join(config.secretsDir, `${member}.enc`);
+    const file = memberFile(config.secretsDir, member);
     assertBoundCustody(config.repoRoot, file);
   }
   return { ...config, nativeTarget: binding };

package/sync/hygiene.mjs

@@ -58,7 +58,7 @@ export function hygieneFindings(files, ignored) {
     if (file.startsWith(WORK) && ignored.has(file)) {
       findings.push({ file, code: 'HFS_WORK_AGENT_DATA', message: 'is agent output, which .starciwork/.gitignore refuses; keep it in the scratchpad or the blob store' });
     }
-    if (file.startsWith(STACKS) && !file.endsWith('.enc') && !file.endsWith('.env.example') && !file.endsWith('/secrets/.gitkeep')) {
+    if (file.startsWith(STACKS) && !/\.enc(?:\.yaml)?$/.test(file) && !file.endsWith('.env.example') && !file.endsWith('/secrets/.gitkeep')) {
       if (file.includes('/secrets/')) findings.push({ file, code: 'HFS_PLAINTEXT_SECRET', message: 'sits under secrets/ but is not sealed; only <slug>.enc may be tracked' });
       else if (PLAINTEXT_NAME.test(file)) findings.push({ file, code: 'HFS_PLAINTEXT_SECRET', message: 'is a plaintext secret; seal it to .starcistacks/<env>/secrets/<slug>.enc' });
     }

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,7 @@ 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';
 
 export const TEMPLATES_DIR = path.join(import.meta.dirname, '..', 'templates');
 const NODE_MAJOR = 22;
@@ -58,9 +59,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 +160,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 +396,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.
@@ -472,9 +486,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 +539,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 +587,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 +606,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 +625,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/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
 }

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

@@ -1,9 +1,21 @@
 import { injector } from "@modules/platform/composition"
 import type { TypedParameterDecorator } from "@modules/platform/composition"
-import type { EventBus } from "./event-bus.port"
+import { MODULE_OPTIONS_TOKEN } from "./event-bus.module-definition"
+import type { EventBusOptions } from "./event-bus.options"
+import type { EventBus, EventConsumerRegistry } from "./event-bus.port"
 
 /** Token of the transactional EventBus publisher. */
 export const EVENT_BUS: unique symbol = Symbol("platform.event-bus")
 
+/** Token of the registry reactors subscribe their consumers to. */
+export const EVENT_CONSUMER_REGISTRY: unique symbol = Symbol("platform.event-bus.consumers")
+
 /** Injects the EventBus port. Parameter type: EventBus. */
 export const InjectEventBus = (): TypedParameterDecorator<EventBus> => injector<EventBus>(EVENT_BUS)
+
+/** Injects the consumer registry. Parameter type: EventConsumerRegistry. */
+export const InjectEventConsumerRegistry = (): TypedParameterDecorator<EventConsumerRegistry> =>
+    injector<EventConsumerRegistry>(EVENT_CONSUMER_REGISTRY)
+
+/** Injects the module's options. Parameter type: EventBusOptions. */
+export const InjectEventBusOptions = (): TypedParameterDecorator<EventBusOptions> => injector<EventBusOptions>(MODULE_OPTIONS_TOKEN)

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

@@ -0,0 +1,9 @@
+/** Log events of the event bus. */
+export enum EventBusLogEvent {
+    /** A consumer threw; the message reappears after its visibility timeout. */
+    ConsumerFailed = "event-bus.consumer.failed",
+    /** A delivery ran out of deliveries or was malformed and moved to its consumer's dead-letter queue. */
+    DeliveryDead = "event-bus.delivery.dead",
+    /** A read of a consumer's queue failed; the loop reads again after its idle pause. */
+    ReadFailed = "event-bus.read.failed",
+}

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

@@ -1,6 +1,6 @@
 import { ConfigurableModuleBuilder } from "@nestjs/common"
 import type { EventBusOptions } from "./event-bus.options"
 
-export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<EventBusOptions>()
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } = new ConfigurableModuleBuilder<EventBusOptions>()
     .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
     .build()

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

@@ -1,19 +1,25 @@
 import { Module } from "@nestjs/common"
 import type { DynamicModule } from "@nestjs/common"
-import { EVENT_BUS } from "./event-bus.decorators"
+import { EVENT_BUS, EVENT_CONSUMER_REGISTRY } from "./event-bus.decorators"
 import { ConfigurableModuleClass, OPTIONS_TYPE } from "./event-bus.module-definition"
 import { EventBusService } from "./event-bus.service"
+import { EventConsumerService } from "./event-consumer.service"
 
 @Module({})
-/** Provides the transactional lite EventBus publisher, shared by domain intake services. */
+/** Provides the lite event bus on pgmq: the transactional publisher and the read loops of the consumer groups. */
 export class EventBusModule extends ConfigurableModuleClass {
-    /** Registers the publishing capability once per app. */
+    /** Registers the capability once per app. */
     static register(options: typeof OPTIONS_TYPE): DynamicModule {
         const base = super.register(options)
         return {
             ...base,
-            providers: [...(base.providers ?? []), { provide: EVENT_BUS, useClass: EventBusService }],
-            exports: [EVENT_BUS],
+            providers: [
+                ...(base.providers ?? []),
+                { provide: EVENT_BUS, useClass: EventBusService },
+                EventConsumerService,
+                { provide: EVENT_CONSUMER_REGISTRY, useExisting: EventConsumerService },
+            ],
+            exports: [EVENT_BUS, EVENT_CONSUMER_REGISTRY],
         }
     }
 }