@starci/hfs 4.10.1 → 4.11.8

package/src/main.mjs

@@ -108,7 +108,7 @@ starci app codemod button-intent [--write] [--format json|markdown] [--report <f
 starci app sync (--check | --write) [--cwd <dir>]
 starci app check [--cwd <dir>] [--json] [--fast] [--base <ref>] [--wiring] [--coverage-from <lcov>]
 starci app db new <kebab-name> [--json] [--cwd <dir>]
-starci app db baseline [--stamp <version>] [--url-env <NAME>] [--apply] [--cwd <dir>]
+starci app db baseline [--stamp <version>] [--url-env <NAME>] [--squash [--drop-extension <a,b>] [--drop-pgmq-queue <q,job_*>] [--seed-tables <t1,t2>] [--image <ref>]] [--apply] [--cwd <dir>]
 starci app db restamp --map <restamp.yaml> [--url-env <NAME>] [--apply] [--cwd <dir>]
 starci app db plan [--url-env <NAME>] [--json] [--cwd <dir>]
 starci app db dump [--url-env <NAME>] --out <dir> [--schema-only] [--json] [--cwd <dir>]
@@ -460,11 +460,12 @@ function errorMessage(error) {
 /**
  * `harness` ({ version }) is the CLI that runs this package in-process: its version is the starci-harness an app is judged and
  * scaffolded at (runtime/scripts/hfs/canon-pins.mjs). `run` injects the database runner, `runLinter` the linter transport, `checkApp`
- * the HFS check and `stackIo` Swarm tools; production defaults execute every check.
+ * the HFS check and `stackIo` Swarm tools; production defaults execute every check. `hostIdentity` ({ label, read }) is the
+ * harness CLI's own secret.env SOPS_AGE_KEY, which `secret` reads last for the age identity; `prompt` replaces its masked prompt.
  */
 export async function main(argv, {
   cwd: baseCwd = process.cwd(), harness, stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), presets, prettier, lock, run, stackMain,
-  env = process.env, stdin, sops, tools, platform, stackIo, runLinter, checkApp,
+  env = process.env, stdin, prompt, hostIdentity, sops, tools, platform, stackIo, runLinter, checkApp,
 } = {}) {
   try {
     const global = globalOptions(argv, path.resolve(baseCwd));
@@ -472,7 +473,7 @@ export async function main(argv, {
     const out = global.quiet ? () => {} : stdout;
     if (global.help) { out(USAGE); return 0; }
     if (!VERBS.includes(verb)) { stderr(USAGE); return 2; }
-    return await dispatchMain(verb, rest, { cwd: global.cwd, harness, edition: global.edition, stdout: out, stderr, presets, prettier, lock, run, stackMain, env, stdin, sops, tools, platform, stackIo, runLinter, checkApp });
+    return await dispatchMain(verb, rest, { cwd: global.cwd, harness, edition: global.edition, stdout: out, stderr, presets, prettier, lock, run, stackMain, env, stdin, prompt, hostIdentity, sops, tools, platform, stackIo, runLinter, checkApp });
   } catch (error) {
     stderr(errorMessage(error));
     return 2;

package/stack/build.mjs

@@ -13,6 +13,7 @@ import { buildArgs } from './build-args.mjs';
 import { firstLine, lines as splitLines, tool } from './context.mjs';
 import { failure, refusal } from './errors.mjs';
 import { requireAgeIdentity } from './sealed.mjs';
+import { DB_DOCKERFILE, DB_IMAGE_APP } from '../db/image.mjs';
 import { scanImage } from './image-scan.mjs';
 
 const RELEASE_TAG = /^v\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/u;
@@ -44,8 +45,9 @@ function ownerOf(ctx, config) {
   return match[1].toLowerCase();
 }
 
-/** The Dockerfile of an app: be/apps/<app>/Dockerfile or fe/apps/<app>/Dockerfile; ambiguity and absence are refusals. */
+/** The Dockerfile of an app: be/apps/<app>/Dockerfile or fe/apps/<app>/Dockerfile, or the managed .starcistacks/images/db/Dockerfile for the db image; ambiguity and absence are refusals. */
 function dockerfileOf(config, app) {
+  if (app === DB_IMAGE_APP && fs.existsSync(path.join(config.repoRoot, DB_DOCKERFILE))) return DB_DOCKERFILE;
   const found = SIDES.map((side) => `${side}/apps/${app}/Dockerfile`).filter((file) => fs.existsSync(path.join(config.repoRoot, file)));
   if (found.length === 0) throw refusal('STACK_BUILD_NO_DOCKERFILE', `no Dockerfile for app ${app} (be/apps/${app}/Dockerfile or fe/apps/${app}/Dockerfile)`);
   if (found.length > 1) throw refusal('STACK_BUILD_AMBIGUOUS', `app ${app} has a Dockerfile on both sides: ${found.join(', ')}`);

package/stack/config.mjs

@@ -1,6 +1,7 @@
 // config.mjs - loads `environments.<env>.deploy` of .starcistacks/application-stacks.yaml for the stack verbs.
 // The block is read and judged by the same module `starci app check` uses (runtime/scripts/hfs/stack-deploy-config.mjs).
 import fs from 'node:fs';
+import { isSealedName, memberOfName } from '../runtime/scripts/lib/sealed-member.mjs';
 import path from 'node:path';
 import { parseYaml } from '../runtime/engine/yaml.mjs';
 import { DEPLOY_CONFIG_CODE, NAME, normalizeDeploy } from '../runtime/scripts/hfs/stack-deploy-config.mjs';
@@ -22,7 +23,7 @@ const projectOf = (repoRoot) => {
 };
 
 const sealedMembers = (secretsDir) => {
-  try { return new Set(fs.readdirSync(secretsDir).filter((name) => name.endsWith('.enc')).map((name) => name.slice(0, -4))); } catch { return new Set(); }
+  try { return new Set(fs.readdirSync(secretsDir).filter(isSealedName).map(memberOfName)); } catch { return new Set(); }
 };
 
 const stackServices = (stackFile) => {

package/stack/docker-transport.mjs

@@ -4,6 +4,7 @@
 // an explicit environment are affected (the minimal environment of `docker stack config` stays exactly as the render built it). The key lives in
 // a private temp directory that is overwritten and removed when the verb ends; it is never in argv, a line or an error.
 import fs from 'node:fs';
+import { memberFile } from '../runtime/scripts/lib/sealed-member.mjs';
 import path from 'node:path';
 import { writePrivate } from './private-file.mjs';
 import { openSealedSession } from './remote.mjs';
@@ -21,7 +22,7 @@ function needed(ctx, config, sshCmd) {
   if (sshCmd || ctx.env.DOCKER_HOST || ctx.env.GITHUB_ACTIONS === 'true' || ctx.env.STARCI_STACK_SEALED_SSH === '0') return false;
   const { sealed } = config.remote;
   if (!sealed) return false;
-  return [sealed.ops, sealed.sshKey, sealed.knownHosts].every((slug) => fs.existsSync(path.join(config.secretsDir, `${slug}.enc`)));
+  return [sealed.ops, sealed.sshKey, sealed.knownHosts].every((slug) => fs.existsSync(memberFile(config.secretsDir, slug)));
 }
 
 function sshConfig(session, controlPath, windows) {

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,6 +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, 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';
@@ -39,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;
@@ -57,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));
 
@@ -156,9 +159,25 @@ function trailingNewline(text) {
   return text.slice(0, end) + '\n';
 }
 
+/**
+ * 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 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). */
-/** The pinned image of a lite app's db service (contexts/stack/pins.yaml images): PostgreSQL with pg_cron, pg_net, pgmq and pgvector. */
-export const DB_IMAGE = 'supabase/postgres:17.11.0.006@sha256:c141fd17ac6a76c4323e90b3aee8ff1a23d2e89e547c2b963cfadc309c079cc2';
 export const REDIS_IMAGE = 'redis:7@sha256:c6eabf748fc7a61dbb5a705c78bcf3d6377b1127a97d0ce965c11c44ba46896f';
 
 const redisDevText = project => render(readBundled('app/package-scripts/redis-dev.json'), { project, redisImage: REDIS_IMAGE });
@@ -322,17 +341,19 @@ function imageEntries(app, source) {
 }
 
 /**
- * The build matrix of the images workflow: one entry per declared app (be then fe), each with the image name and its Dockerfile. The workflow
+ * The build matrix of the images workflow: one entry per declared app (be then fe, then a lite app's db image), each with the image name and its Dockerfile. The workflow
  * runs on the release tag, so every image is built there; no path filter narrows it. A YAML block mapping per entry, indented for
  * `strategy.matrix.include`.
  */
 export function imageMatrix(app, source) {
   const entry = (side, item) => `          - name: ${item.name}\n            file: ${dockerfilePath(side, item.name)}`;
-  return imageEntries(app, source).map(image => entry(image.side, image.entry)).join('\n');
+  const db = app.edition === 'lite' ? [`          - name: ${DB_IMAGE_APP}\n            file: ${DB_DOCKERFILE}`] : [];
+  return [...imageEntries(app, source).map(image => entry(image.side, image.entry)), ...db].join('\n');
 }
 
-/** The Dockerfile of the app a deploy image names (be first, then fe); an app hfs.json does not declare cannot be built by the managed workflow. */
+/** The Dockerfile of the app a deploy image names (be first, then fe, then a lite app's db image); an app hfs.json does not declare cannot be built by the managed workflow. */
 function stackDockerfile(app, name) {
+  if (app.edition === 'lite' && name === DB_IMAGE_APP) return DB_DOCKERFILE;
   const side = ['be', 'fe'].find(which => app.sides[which].apps.some(entry => entry.name === name));
   if (!side) throw new SyncError('HFS_SYNC_STACK_IMAGE', `deploy.images names the app ${name}, which hfs.json does not declare under be or fe`);
   return dockerfilePath(side, name);
@@ -375,8 +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 pinned db image (ruling:lite-self-hosted-postgres-passport-minio).
-    dbImage: DB_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.
@@ -460,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;
@@ -512,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);
@@ -559,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) {
@@ -572,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;
 }
 
@@ -590,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,10 +1,12 @@
 -- 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). 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). The supabase/postgres image ships only a partial
--- copy of them, and 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. It is idempotent; `starci app db migrate`
--- applies it as the database owner before the first migration of an empty database.
+-- 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 .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 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
@@ -25,7 +27,7 @@ $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 (the image's old copy is extended in place).
+-- 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);
 alter table auth.users
     add column if not exists instance_id uuid,
@@ -130,10 +132,3 @@ alter table storage.buckets enable row level security;
 
 grant select, insert, update, delete on storage.objects, storage.buckets to authenticated, service_role;
 grant select on storage.objects, storage.buckets to anon;
-
--- Replication publication the baseline adds tables to (the image ships it; a bare PostgreSQL does not).
-do $pub$
-begin
-    if not exists (select 1 from pg_publication where pubname = 'supabase_realtime') then create publication supabase_realtime; end if;
-end
-$pub$;

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,5 @@
-    "db:create": "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: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",
     "db:reset": "docker rm -f {{project}}-dev-db && docker volume rm {{project}}-dev-db-data && npm run db:create && npm run db:start",

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

@@ -27,9 +27,9 @@ components:
     role: service
     stateful: true
     volumes: [db-data]
-    image: "supabase/postgres:17.11.0.006@sha256:c141fd17ac6a76c4323e90b3aee8ff1a23d2e89e547c2b963cfadc309c079cc2"
+    image: "{{project}}/db:v0.0.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"
     compose: infra/swarm/stack.yaml
-    purpose: The app's own PostgreSQL (pg_cron, pg_net, pgmq, vector), 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
@@ -203,6 +203,8 @@ environments:
       images:
         api:
           app: api
+        db:
+          app: db
         web:
           app: web
           # Public browser configuration; replace these placeholders before deployment.

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 (image supabase/postgres: PostgreSQL with pg_cron, pg_net, pgmq and pgvector) 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/dev/infra/swarm/stack.yaml

@@ -83,7 +83,7 @@ services:
         condition: on-failure
         delay: 5s
   db:
-    image: "supabase/postgres:17.11.0.006@sha256:c141fd17ac6a76c4323e90b3aee8ff1a23d2e89e547c2b963cfadc309c079cc2"
+    image: "{{project}}/db:v0.0.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"
     environment:
       POSTGRES_DB: postgres
       POSTGRES_PASSWORD_FILE: /run/secrets/db-password

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 (image supabase/postgres) supplies PostgreSQL with pg_cron, pg_net, pgmq and pgvector 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/.starcistacks/production/infra/swarm/stack.yaml

@@ -83,7 +83,7 @@ services:
         condition: on-failure
         delay: 5s
   db:
-    image: "supabase/postgres:17.11.0.006@sha256:c141fd17ac6a76c4323e90b3aee8ff1a23d2e89e547c2b963cfadc309c079cc2"
+    image: "{{project}}/db:v0.0.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"
     environment:
       POSTGRES_DB: postgres
       POSTGRES_PASSWORD_FILE: /run/secrets/db-password

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, image supabase/postgres), 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 pinned `db` image, on 127.0.0.1:54322), export `DATABASE_URL=postgresql://supabase_admin@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
     }
   },