@starci/hfs 4.11.12 → 4.11.15

package/stack/context.mjs

@@ -57,7 +57,7 @@ const realSleep = (ms) => new Promise((done) => { setTimeout(done, ms); });
  *   stdout, stderr text writers
  *   fetch          the HTTP seam of verify (url, init) -> Response
  *   pipe           (source, sink) -> Promise<{ source, sink, stderr }>: one process's stdout streamed into another's stdin (realPipe)
- *   sops           the secret seam (decrypt(file, format) -> map; decryptBinary(file) -> text); `io.sops`, else on first use `io.openSops()` or the app's own sops/age tools
+ *   sops           the secret seam (decrypt(file, format) -> map; decryptBinary(file) -> text); `io.sops`, else on first use `io.openSops()` or the app's own sops/age tools with the age identity decryptionIdentity finds (`io.hostIdentity` the harness CLI's secret.env)
  */
 export function stackContext(io = {}) {
   const cwd = io.cwd ?? process.cwd();
@@ -78,7 +78,7 @@ export function stackContext(io = {}) {
     pipe: io.pipe ?? realPipe,
     /** The secret seam: the app's own sops/age tools, created on first use so verbs that open no custody never need them. */
     get sops() {
-      sops ??= io.openSops?.() ?? defaultSops(env, cwd);
+      sops ??= io.openSops?.() ?? defaultSops(env, cwd, io.platform ?? process.platform, undefined, io.hostIdentity ?? null);
       return sops;
     },
   });

package/stack/deploy.mjs

@@ -3,7 +3,8 @@
 // after the stack deploy redeploys the previous accepted release from its STORED bytes; a failure before it leaves the services untouched.
 // Without `execute` a deploy renders locally and prints the plan: NO remote call at all. A rollback cannot undo data effects.
 // An urgent deploy (`urgent`, owner ruling urgent-release 2026-10-29) runs the safety floor of urgent-floor.mjs first (fresh verified encrypted
-// backup with a test decrypt, rollback target, migrate preview then execute) and refuses with the floor's own code when a step of it fails.
+// backup with a test decrypt, rollback target, migrate preview then execute) and refuses with the floor's own code when a step of it fails; its
+// first start (`firstStart`) proves the database empty and migrates it inside its own container, a `first-start` step between edge and converge.
 //
 // `deps` are the collaborators, all factories or functions with the signature of their module, defaulting to lazy dynamic imports so this
 // module never needs render.mjs / provision.mjs / remote.mjs at load time (the specs inject stubs):
@@ -197,6 +198,9 @@ async function deployExecute(ctx, config, options, d, out, cleanups) {
   const failed = await runSteps([
     ['deploy', () => stackDeploy(ctx, config, path.join(out, 'stack.yaml'))],
     ['edge', async () => d.reconcileEdge(ctx, config, path.join(out, 'stack.yaml'))],
+    // The first start of a self-hosted database (urgent-floor.mjs): its schema is bootstrapped and migrated once the database runs, before the
+    // services that need it are waited for.
+    ...(options.firstStartStep ? [['first-start', options.firstStartStep]] : []),
     ['converge', () => d.convergeStack(ctx, config, { since, timeoutSeconds: options.timeoutSeconds })],
     ...(config.postDeploy.length > 0 ? [['post-deploy', () => d.postDeployStack(ctx, config)]] : []),
     ['verify', () => d.verifyStack(ctx, config, { retrySeconds: options.retrySeconds, skipPublic: skipPublic === true, stackFile: path.join(out, 'stack.yaml') })],
@@ -245,7 +249,7 @@ export async function deployRelease(ctx, config, options = {}, deps = {}) {
     };
     if (options.urgent === true) {
       return await urgentDeploy(ctx, config, options, {
-        render, dryRun, openStore: () => openStore(ctx, config, options, d, cleanups), deployExecute: () => deployExecute(ctx, config, options, d, out, cleanups), sha256: fileSha256,
+        render, dryRun, openStore: () => openStore(ctx, config, options, d, cleanups), deployExecute: (extra = {}) => deployExecute(ctx, config, { ...options, ...extra }, d, out, cleanups), sha256: fileSha256,
       }, d.floor);
     }
     if (options.execute !== true) return await dryRun();

package/stack/remote.mjs

@@ -64,24 +64,36 @@ function sshCommandArgv(sshCmd) {
   return parts;
 }
 
-/** A sealed binary member is the file itself; a JSON object around it ({ data | <names> }, the re-sealed shape of `starci app secret rename`) is unwrapped. */
-function unwrap(text, names) {
+/**
+ * The key each sealed SSH member of `deploy.remote.sealed` holds (contexts/project/stacks.md PROJECT-STACKS-5): the one owner of
+ * these names. `sshKey` names the member whose `privateKey` is the PEM private key, `knownHosts` the member whose `knownHosts` is
+ * the pinned known_hosts text.
+ */
+export const SEALED_SSH_KEYS = Object.freeze({ sshKey: 'privateKey', knownHosts: 'knownHosts' });
+
+/** A legacy binary member is the file itself; a JSON object around it ({ data | <key> }, the re-sealed shape of `starci app secret rename`) is unwrapped. */
+function unwrap(text, key) {
   const body = lfOnly(text);
   const trimmed = body.trim();
   if (!trimmed.startsWith('{')) return body;
   let parsed;
   try { parsed = JSON.parse(trimmed); } catch { return body; }
-  for (const name of ['data', ...names]) if (typeof parsed[name] === 'string') return lfOnly(parsed[name]);
+  for (const name of ['data', key]) if (typeof parsed[name] === 'string') return lfOnly(parsed[name]);
   return body;
 }
 
+/** The sops format a sealed member is read as: a `.enc.yaml` member is YAML, a legacy `.enc` one dotenv. */
+const memberFormat = (file) => (isLegacyName(file) ? 'dotenv' : 'yaml');
+
+/** Opens one member through the sops seam; a failure is refused naming the member and the seam's own reason (format, recipients, identity). */
 function openMember(slug, read) {
   try { return read(); } catch (error) { throw refusal('STACK_REMOTE_SEALED', `cannot open the sealed member ${slug}: ${error.message}`); }
 }
 
 function opsAccount(ctx, config) {
   const slug = config.remote.sealed.ops;
-  const map = openMember(slug, () => ctx.sops.decrypt(memberFile(config.secretsDir, slug), isLegacyName(memberFile(config.secretsDir, slug)) ? 'dotenv' : 'yaml'));
+  const file = memberFile(config.secretsDir, slug);
+  const map = openMember(slug, () => ctx.sops.decrypt(file, memberFormat(file)));
   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, . _ @ -)`);
@@ -89,8 +101,17 @@ function opsAccount(ctx, config) {
   return `${map.VPS_USER}@${map.VPS_HOST}`;
 }
 
-function binaryMember(ctx, config, slug, names) {
-  return unwrap(openMember(slug, () => ctx.sops.decryptBinary(memberFile(config.secretsDir, slug))), names);
+/**
+ * The text a sealed SSH member holds under `key` (SEALED_SSH_KEYS): a `.enc.yaml` member is read as YAML and the key taken from
+ * its map; a legacy `.enc` member is the sops binary or JSON envelope it was sealed as.
+ */
+function sshMember(ctx, config, slug, key) {
+  const file = memberFile(config.secretsDir, slug);
+  if (isLegacyName(file)) return unwrap(openMember(slug, () => ctx.sops.decryptBinary(file)), key);
+  const map = openMember(slug, () => ctx.sops.decrypt(file, 'yaml'));
+  if (typeof map[key] !== 'string' || map[key] === '')
+    throw refusal('STACK_REMOTE_SEALED', `the sealed member ${slug} holds no ${key} (it holds ${Object.keys(map).join(', ') || 'no key'}): seal it with starci app secret set ${config.env ?? '<env>'} ${slug} ${key} --from-file ${key}=<file>`);
+  return lfOnly(map[key]);
 }
 
 const withNewline = (text) => `${text.trim()}\n`;
@@ -107,9 +128,9 @@ export function openSealedSession(ctx, config) {
   const account = opsAccount(ctx, config);
   if (config.nativeTarget && account !== `${config.nativeTarget.user}@${config.nativeTarget.host}`)
     throw refusal('STACK_REMOTE_OPS', 'the sealed SSH account differs from the accepted native target');
-  const key = binaryMember(ctx, config, sealed.sshKey, ['privateKey', 'key']);
+  const key = sshMember(ctx, config, sealed.sshKey, SEALED_SSH_KEYS.sshKey);
   if (!key.includes('PRIVATE KEY')) throw refusal('STACK_REMOTE_KEY', `${sealed.sshKey} does not hold a PEM private key`);
-  const known = binaryMember(ctx, config, sealed.knownHosts, ['knownHosts', 'known_hosts']).trim();
+  const known = sshMember(ctx, config, sealed.knownHosts, SEALED_SSH_KEYS.knownHosts).trim();
   assertStackAccount(config.nativeTarget, account, known);
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'stack-ssh-'));
   const keyFile = path.join(dir, 'id');

package/stack/sealed.mjs

@@ -5,7 +5,6 @@ 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';
 import { readMap } from '../runtime/scripts/hfs/secret-store.mjs';
 import { refusal } from './errors.mjs';
 
@@ -52,27 +51,32 @@ function secretRuntimeName(stack, key, value, versionKey) {
   return name;
 }
 
-const AGE_IDENTITY_ENV = /^SOPS_AGE_KEY(?:_FILE)?$/iu;
-const AGE_HINT = 'load the age identity into SOPS_AGE_KEY (the secret.env of the owner machine, or the CI secret) and retry';
+const AGE_HINT = 'add SOPS_AGE_KEY to .claude/secret.env of the app or the harness secret.env of the owner machine (the CI secret in a workflow) and retry';
 
-/** True when an age identity is reachable: SOPS_AGE_KEY or SOPS_AGE_KEY_FILE in the environment, the repository's .claude/secret.env or the per-user keys.txt. */
-export function hasAgeIdentity(ctx, config) {
-  const named = Object.entries(ctx.env).some(([name, value]) => AGE_IDENTITY_ENV.test(name) && value);
-  return named || fs.existsSync(path.join(config.repoRoot, '.claude', 'secret.env')) || fs.existsSync(secretRoots(ctx.env).identity);
+/**
+ * True when the sops seam found an age identity (secret-init.mjs decryptionIdentity, the one lookup every decrypt uses). A seam
+ * that reports no `identity` (a spec double) decides for itself.
+ */
+export function hasAgeIdentity(ctx) {
+  const { identity } = ctx.sops;
+  return identity === undefined || identity.source !== null;
 }
 
 /** Refuses up front, before any work, when sealed custody must be opened and no age identity is reachable. */
 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}`);
+  if (!hasAgeIdentity(ctx)) throw refusal('STACK_AGE_IDENTITY_MISSING', `${purpose} needs the sealed members, and no age identity is available (looked in ${ctx.sops.identity.looked.join(', ')}): ${AGE_HINT}`);
 }
 
-/** Opens one sealed member (`<secretsDir>/<member>.enc.yaml`, or a legacy `.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. A failure is refused
+ * naming the member and the seam's reason (its format, recipients and the identity tried); no value.
+ */
 export function openMember(ctx, config, member) {
   try {
     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}`}`);
+  } catch (error) {
+    throw refusal('STACK_SECRET_MEMBER_UNREADABLE', `the sealed member ${member} cannot be opened: ${error.message}${hasAgeIdentity(ctx) ? '' : `; ${AGE_HINT}`}`);
   }
 }
 

package/stack/server-key.mjs

@@ -42,6 +42,22 @@ const RECIPIENT = /^age1[a-z0-9]+$/u;
 /** A command run as root: directly when the deploy user is root, else over passwordless sudo, the script read from stdin. */
 const AS_ROOT = 'if [ "$(id -u)" -eq 0 ]; then sh -s; else sudo -n sh -s; fi';
 
+/**
+ * The directories, after root's PATH, where age-keygen is looked for: sudo's secure_path (AlmaLinux 10, RHEL) leaves out
+ * /usr/local/bin, where the static installer puts it, so the presence check and every call resolve it the same way, as root.
+ */
+export const AGE_KEYGEN_DIRS = ['/usr/local/bin', '/usr/bin', '/bin'];
+
+/** The shell lines that set k to age-keygen's absolute path as root sees it, or exit 127 naming it missing. Every root script holds them. */
+export const RESOLVE_AGE_KEYGEN = [
+  'k="$(command -v age-keygen 2>/dev/null || true)"',
+  `for d in ${AGE_KEYGEN_DIRS.join(' ')}; do if [ -z "$k" ] && [ -x "$d/age-keygen" ]; then k="$d/age-keygen"; fi; done`,
+  'if [ -z "$k" ]; then echo "age-keygen is not installed" >&2; exit 127; fi',
+].join('\n');
+
+/** The root script that only resolves age-keygen and prints its path: the presence check, run exactly as the calls run. */
+export const ageKeygenScript = () => ['set -eu', RESOLVE_AGE_KEYGEN, String.raw`printf '%s\n' "$k"`].join('\n');
+
 /**
  * The GitHub Environment secret that holds an environment's server identity. It carries the name the deploy workflows read
  * (secrets.SOPS_AGE_KEY), scoped to the Environment <env>: for a job bound to <env> it overrides a repository secret of that name.
@@ -54,24 +70,25 @@ export function ensureIdentityScript(file) {
   return [
     'set -eu',
     'umask 077',
+    RESOLVE_AGE_KEYGEN,
     `f=${quoted}`,
     'if [ -e "$f" ] || [ -L "$f" ]; then',
     '  if [ -L "$f" ] || [ ! -f "$f" ]; then echo "the identity path is not an ordinary file" >&2; exit 4; fi',
     '  echo "identity kept" >&2',
     'else',
     '  mkdir -p "$(dirname "$f")"',
-    '  age-keygen -o "$f" >/dev/null 2>&1',
+    '  "$k" -o "$f" >/dev/null 2>&1',
     '  echo "identity created" >&2',
     'fi',
     'chown root:root "$f"',
     'chmod 600 "$f"',
-    'age-keygen -y "$f"',
+    '"$k" -y "$f"',
   ].join('\n');
 }
 
 /** The shell that prints only the public key of `file`, or exits 5 when there is none. */
 export function publicKeyScript(file) {
-  return ['set -eu', `f=${shellQuote(file)}`, '[ -f "$f" ] || exit 5', 'age-keygen -y "$f"'].join('\n');
+  return ['set -eu', RESOLVE_AGE_KEYGEN, `f=${shellQuote(file)}`, '[ -f "$f" ] || exit 5', '"$k" -y "$f"'].join('\n');
 }
 
 /** The shell that swaps the staged `<file>.next` in, keeping the old identity as `retired`, then prints only the new public key. */
@@ -79,6 +96,7 @@ export function swapIdentityScript(file, retired) {
   return [
     'set -eu',
     'umask 077',
+    RESOLVE_AGE_KEYGEN,
     `f=${shellQuote(file)}`,
     `r=${shellQuote(retired)}`,
     'n="$f.next"',
@@ -87,7 +105,7 @@ export function swapIdentityScript(file, retired) {
     'mv "$f" "$r"',
     'mv "$n" "$f"',
     'chmod 600 "$f" "$r"',
-    'age-keygen -y "$f"',
+    '"$k" -y "$f"',
   ].join('\n');
 }
 
@@ -112,14 +130,20 @@ function declaredRemote(repoRoot, env) {
   return remote;
 }
 
-/** Ensures age-keygen on the server: stack prepare's installer owns the install (with --execute); without it the exact commands. */
+/** True when root resolves age-keygen the way every server-key script does (ageKeygenScript). */
+const hasKeygen = (run) => asRoot(run, ageKeygenScript()).status === 0;
+
+/**
+ * Ensures age-keygen on the server, checked as root exactly as it is called: stack prepare's installer owns the install (with
+ * --execute); without it the exact commands.
+ */
 function ensureTool(run, execute, lines) {
-  if (run('command -v age-keygen').status === 0) return true;
+  if (hasKeygen(run)) return true;
   const install = `install age on the server (one of: ${Object.values(AGE_INSTALL).join('; ')})`;
   if (!execute) { lines.push(`dry run: age-keygen is missing on the server; --execute installs it with stack prepare's installer, or ${install}`); return false; }
   const problems = [];
   installAge(run, { note: (text) => lines.push(text), bad: (text) => problems.push(text) });
-  if (problems.length || run('command -v age-keygen').status !== 0)
+  if (problems.length || !hasKeygen(run))
     throw refusal('STACK_SERVER_KEY_NO_AGE', `age-keygen is not on the server and could not be installed (${problems.join('; ') || 'still missing'}): ${install}`);
   return true;
 }

package/stack/urgent-floor.mjs

@@ -10,13 +10,23 @@
 //   deploy     the release with its readiness verify (deploy.verify); red rolls back by itself    STACK_URGENT_RED_ROLLED_BACK, STACK_URGENT_ROLLBACK_FAILED,
 //                                                                                                 STACK_URGENT_DEPLOY_NOT_STARTED (red before the stack deploy)
 // The public-host checks are never skipped (STACK_URGENT_SKIP_PUBLIC). A rollback cannot undo the migrations: the backup above is their way back.
+// The first start (`--first-start --db-service <service>`, owner ruling 2026-10-29) is the floor of a self-hosted database the release itself
+// starts: there is nothing to back up and nothing reaches it before the stack runs it, so instead of backup, decrypt and migrate before the deploy
+// the release deploys and, between edge and converge, the floor waits for the database service's container to accept connections, proves the
+// database empty (no migration history, no table in public) and runs migrate preview then execute inside that container (db/bootstrap.sql first,
+// as the --db-url-env role). Every other step holds: record, rollback target, readiness verify, automatic rollback. Each failure is its own code:
+//   STACK_FIRST_START_USAGE (no --db-service), STACK_FIRST_START_NO_DATABASE (no container accepted connections in time),
+//   STACK_FIRST_START_NOT_EMPTY (a history or a public table: use the plain urgent floor), STACK_FIRST_START_MIGRATE_RED (preview or execute red);
+// each rolls the release back to the previous one; the migrations a red first start applied stay in a database no release used before.
 // `deps` are the collaborators (backup, decrypt, migrate), each defaulting to the app's own db verbs; a spec injects stubs.
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { readDeclaration } from '../release/index.mjs';
 import { releaseDir } from '../release/gate.mjs';
+import { DEFAULT_DB_URL_ENV, dbTarget, inContainer, queryRows } from '../db/postgres.mjs';
 import { readUrgent } from '../release/records.mjs';
+import { lines as splitLines, tool } from './context.mjs';
 import { refusal } from './errors.mjs';
 
 const AGE_HEADER = 'age-encryption.org/v1\n';
@@ -54,7 +64,28 @@ async function defaultMigrate(ctx, { target, execute }) {
   return migrateDatabase(armed, loadDatabase(ctx.cwd), { ...target, execute });
 }
 
-export const FLOOR_DEPS = Object.freeze({ backup: defaultBackup, decrypt: defaultDecrypt, migrate: defaultMigrate });
+/** How long a first start waits for the database service's container to accept connections. */
+export const FIRST_START_WAIT_SECONDS = 180;
+
+/** The running container of `service` whose server accepts connections (pg_isready), polled until `seconds` pass; undefined when none did. */
+async function defaultDbContainer(ctx, config, { service, seconds }) {
+  const deadline = ctx.now() + seconds * 1000;
+  for (;;) {
+    const found = tool(ctx, 'docker', ['ps', '-q', '--filter', `label=com.docker.swarm.service.name=${config.stack}_${service}`, '--filter', 'status=running']);
+    const id = splitLines(found.stdout)[0];
+    if (id && tool(ctx, 'docker', ['exec', id, 'pg_isready', '-q']).status === 0) return id;
+    if (ctx.now() >= deadline) return undefined;
+    await new Promise((resolve) => { setTimeout(resolve, 3000); });
+  }
+}
+
+/** Whether the target database is empty: no migration history table and no table in public. */
+async function defaultEmptiness(ctx, target) {
+  const [row] = queryRows(ctx, target, "select to_regclass('supabase_migrations.schema_migrations') is not null as history, (select count(*)::int from pg_tables where schemaname = 'public') as public_tables", { withhold: true });
+  return { empty: row?.history === false && row?.public_tables === 0, history: row?.history === true, publicTables: Number(row?.public_tables ?? -1) };
+}
+
+export const FLOOR_DEPS = Object.freeze({ backup: defaultBackup, decrypt: defaultDecrypt, migrate: defaultMigrate, dbContainer: defaultDbContainer, emptiness: defaultEmptiness });
 
 /** A refused floor step: the lines so far and the code; the CLI prints both and exits 2. */
 const refused = (lines, code, message, data = {}) => ({ ok: false, refused: { code, message }, lines, data: { ...data, refused: code } });
@@ -83,6 +114,11 @@ function preconditions(ctx, config, options) {
   if (!record) throw refusal('STACK_URGENT_NO_RECORD', `${options.sourceSha} has no urgent record: push it with starci app release push --urgent --reason "<text>" --execute first`);
   if (record.pushed !== true) throw refusal('STACK_URGENT_NOT_PUSHED', `the urgent release ${record.tag} of ${options.sourceSha.slice(0, 10)} was never pushed`);
   if (!readDeclaration(config.repoRoot ?? ctx.cwd).database) throw refusal('STACK_URGENT_NO_DATABASE', 'the floor backs up and migrates the database the `database:` block declares, and this app declares none');
+  if (options.firstStart === true) {
+    // A first start backs nothing up, so it needs no identity for a test decrypt; it needs the service its database runs as.
+    if (!options.dbService) throw refusal('STACK_FIRST_START_USAGE', '--first-start names the stack service of the database it bootstraps: add --db-service <service>');
+    return { record, identity: null };
+  }
   const identity = ctx.env.SOPS_AGE_KEY_FILE;
   if (!identity || !fs.existsSync(identity)) throw refusal('STACK_URGENT_DECRYPT_UNAVAILABLE', 'the test decrypt of the backup reads the age identity named by SOPS_AGE_KEY_FILE, which is not set or not a file');
   return { record, identity };
@@ -122,6 +158,57 @@ async function guard(ctx, config, options, { f, run, identity, lines }) {
   return null;
 }
 
+/**
+ * The `first-start` step of a first start's deploy (between edge and converge): the database container, the proof it is empty, migrate preview
+ * then execute inside it. Returns { ok, lines, code } where code names the failure.
+ */
+async function firstStartStep(ctx, config, options, f) {
+  const service = `${config.stack}_${options.dbService}`;
+  const container = await f.dbContainer(ctx, config, { service: options.dbService, seconds: FIRST_START_WAIT_SECONDS });
+  if (!container) return { ok: false, code: 'STACK_FIRST_START_NO_DATABASE', lines: [`first start: no running container of ${service} accepted connections within ${FIRST_START_WAIT_SECONDS}s`] };
+  const target = inContainer(dbTarget(ctx, options.dbUrlEnv ?? DEFAULT_DB_URL_ENV), container);
+  const state = await f.emptiness(ctx, target);
+  if (!state.empty) {
+    const found = state.history ? 'a migration history' : `${state.publicTables < 0 ? 'an unreadable count of' : state.publicTables} table(s) in public`;
+    return { ok: false, code: 'STACK_FIRST_START_NOT_EMPTY', lines: [`first start refused: the database of ${service} holds ${found}; a database with data takes the plain urgent floor (backup first)`] };
+  }
+  const lines = [`first start: the database of ${service} is empty (no migration history, no table in public): nothing to back up`];
+  for (const execute of [false, true]) {
+    let result;
+    try { result = await f.migrate(ctx, { target: { target }, execute }); } catch (error) { result = { ok: false, lines: [String(error?.message ?? error)] }; }
+    lines.push(...(result.lines ?? []).map((line) => `first start: migrate${execute ? '' : ' preview'}: ${line}`));
+    if (!result.ok) return { ok: false, code: 'STACK_FIRST_START_MIGRATE_RED', lines: [...lines, `first start: the migration${execute ? '' : ' preview'} is red`] };
+  }
+  return { ok: true, lines };
+}
+
+/**
+ * A first start: the rollback target, then the deploy whose `first-start` step bootstraps and migrates the empty database. Returns the dry-run
+ * plan or a refused result, or { deployed } for the verdicts it shares with the plain floor.
+ */
+async function firstStartDeploy(ctx, config, options, run, f, lines) {
+  if (options.execute !== true) {
+    const plan = await run.dryRun();
+    return { ...plan, lines: [...lines, `floor (never skipped), first start of ${config.stack}_${options.dbService}: rollback target, deploy, then before converge: wait for the database, prove it empty, migrate preview then execute inside its container; readiness verify and automatic rollback`, ...plan.lines] };
+  }
+  const { releaseId } = await run.render();
+  lines.push(`floor: release ${releaseId} rendered`);
+  const store = await run.openStore();
+  if (!(await store.current())) return refused(lines, 'STACK_URGENT_NO_ROLLBACK_TARGET', 'no accepted previous release is stored on the manager, so a red first start could not roll back; nothing was deployed');
+  let code = null;
+  const deployed = await run.deployExecute({
+    firstStartStep: async () => {
+      const step = await firstStartStep(ctx, config, options, f);
+      code = step.code ?? null;
+      return step;
+    },
+  });
+  if (!deployed.ok && code) {
+    return refused([...lines, ...deployed.lines], code, `the first start failed; ${deployed.data?.rolledBack ? `the release was rolled back to ${deployed.data.previous}` : 'the rollback did not converge: follow the stack runbook, Rollback'}`, deployed.data);
+  }
+  return { deployed };
+}
+
 /**
  * An urgent deploy: the floor's preconditions, then (with execute) its guard steps, then `deployExecute` (the release, its readiness verify and the
  * automatic rollback). `run` = { render(), openStore(), deployExecute(), dryRun(), sha256 }. Returns { ok, lines, data } or a refused result whose
@@ -131,13 +218,20 @@ export async function urgentDeploy(ctx, config, options, run, deps = {}) {
   const f = { ...FLOOR_DEPS, ...deps };
   const { record, identity } = preconditions(ctx, config, options);
   const lines = [`urgent         ${record.tag} (${options.sourceSha.slice(0, 10)}) by ${record.role}: ${record.reason}`];
-  if (options.execute !== true) {
-    const plan = await run.dryRun();
-    return { ...plan, lines: [...lines, 'floor (never skipped): fresh encrypted database backup, receipt verify, test decrypt, rollback target, migrate preview then execute, deploy with readiness verify and automatic rollback', ...plan.lines] };
+  let deployed;
+  if (options.firstStart === true) {
+    const first = await firstStartDeploy(ctx, config, options, run, f, lines);
+    if (!first.deployed) return { ...first, data: { ...first.data, urgent: record.tag, firstStart: true } };
+    deployed = first.deployed;
+  } else {
+    if (options.execute !== true) {
+      const plan = await run.dryRun();
+      return { ...plan, lines: [...lines, 'floor (never skipped): fresh encrypted database backup, receipt verify, test decrypt, rollback target, migrate preview then execute, deploy with readiness verify and automatic rollback', ...plan.lines] };
+    }
+    const stop = await guard(ctx, config, options, { f, run, identity, lines });
+    if (stop) return { ...stop, data: { ...stop.data, urgent: record.tag } };
+    deployed = await run.deployExecute();
   }
-  const stop = await guard(ctx, config, options, { f, run, identity, lines });
-  if (stop) return { ...stop, data: { ...stop.data, urgent: record.tag } };
-  const deployed = await run.deployExecute();
   const all = [...lines, ...deployed.lines];
   if (deployed.ok) return { ...deployed, lines: all, data: { ...deployed.data, urgent: record.tag } };
   const data = { ...deployed.data, urgent: record.tag };

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

@@ -53,6 +53,6 @@ jobs:
           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"'
+          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 '"'"'PATH="$PATH:/usr/local/bin"; 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/stack-key-restore.yml

@@ -53,6 +53,6 @@ jobs:
           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"'
+          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 '"'"'PATH="$PATH:/usr/local/bin"; 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/be/inbox/entities.index.ts.tpl

@@ -0,0 +1,4 @@
+import { @@Provider@@InboxEntity } from "./@@provider@@-inbox.entity"
+
+/** The entities of the @@provider@@-inbox capability, named in PRIMARY_ENTITIES of platform/database/entities.ts. */
+export const @@providerCamel@@InboxEntities = [@@Provider@@InboxEntity]

package/templates/be/inbox/entity.ts.tpl

@@ -0,0 +1,29 @@
+import { Column, Entity, PrimaryGeneratedColumn } from "typeorm"
+
+@Entity({ schema: "public", name: "@@table@@" })
+/** One @@provider@@ delivery receipt, a row of public.@@table@@ from its inbox migration in db/migrations; a reactor or job consumes it after commit. */
+export class @@Provider@@InboxEntity {
+    /** The receipt id the winning claim answers. */
+    @PrimaryGeneratedColumn("uuid", { name: "id" })
+    id!: string
+
+    /** The provider the receipt belongs to; the table admits only @@provider@@. */
+    @Column({ name: "provider", type: "text" })
+    provider!: string
+
+    /** The provider's delivery id, unique with the provider. */
+    @Column({ name: "delivery_id", type: "text" })
+    deliveryId!: string
+
+    /** When the delivery was recorded; the database sets it. */
+    @Column({ name: "received_at", type: "timestamptz", insert: false, update: false })
+    receivedAt!: Date
+
+    /** The verified delivery body the consumer reads; it carries no credential. */
+    @Column({ name: "payload", type: "jsonb" })
+    payload!: object
+
+    /** When the consumer finished the delivery; null while it is pending. */
+    @Column({ name: "processed_at", type: "timestamptz", nullable: true })
+    processedAt!: Date | null
+}

package/templates/be/inbox/index.ts.tpl

@@ -1,2 +1,3 @@
 export { @@Provider@@InboxModule } from "./@@provider@@-inbox.module"
 export { @@Provider@@InboxService } from "./@@provider@@-inbox.service"
+export { @@providerCamel@@InboxEntities } from "./persistence/entities/index"

package/templates/be/inbox/platform/inbox/inbox.decorators.ts.tpl

@@ -1,9 +1,12 @@
 import { injector } from "@modules/platform/composition"
 import type { TypedParameterDecorator } from "@modules/platform/composition"
-import type { Inbox } from "./inbox.port"
+import type { EntityInbox, Inbox } from "./inbox.port"
 
-/** Token of the shared, transaction-owned inbox claims. */
+/** Token of the shared, transaction-owned inbox claims; its provider is an EntityInbox too. */
 export const INBOX: unique symbol = Symbol("platform.inbox")
 
 /** Injects the Inbox port. Parameter type: Inbox. */
 export const InjectInbox = (): TypedParameterDecorator<Inbox> => injector<Inbox>(INBOX)
+
+/** Injects the Inbox port of a capability whose provider receipt is an entity row. Parameter type: EntityInbox. */
+export const InjectEntityInbox = (): TypedParameterDecorator<EntityInbox> => injector<EntityInbox>(INBOX)

package/templates/be/inbox/platform/inbox/inbox.port.ts.tpl

@@ -1,4 +1,4 @@
-import type { EntityManager } from "typeorm"
+import type { EntityManager, EntityTarget, ObjectLiteral, QueryDeepPartialEntity } from "typeorm"
 
 /** The authenticated scope and complete normalized body of a client operation; the key is never part of the body. */
 export interface ClientOperation {
@@ -27,3 +27,31 @@ export interface Inbox {
     /** Deletes one bounded batch of completed client claims older than the cutoff. */
     sweepClients(cutoff: Date, tx: EntityManager): Promise<number>
 }
+
+/** A provider's receipt row: its entity, mapping a table with an `id` column, and the complete row, delivery key and payload included. */
+export interface InboxEntityReceipt<Row extends ObjectLiteral> {
+    /** The provider's receipt entity. */
+    readonly entity: EntityTarget<Row>
+    /**
+     * The row the receipt holds, built from the delivery id the claim normalized (trimmed, never missing), so the receipt keys
+     * exactly what was claimed; the deferred consumer reads it, so it carries no credential.
+     */
+    readonly row: (deliveryId: string) => QueryDeepPartialEntity<Row>
+}
+
+/** The id of the receipt row a winning claim inserted; undefined when the delivery was a repeat or its receipt already existed. */
+export type InboxReceiptId = string | undefined
+
+/** The inbox of a capability whose provider receipt is an entity row, so it records the receipt without raw SQL. */
+export interface EntityInbox extends Inbox {
+    /**
+     * Claims once per source and event id, then inserts the receipt row, both in the caller transaction. Answers the id the
+     * winning insert returned; a repeated delivery, or a receipt row that already exists, inserts nothing and answers undefined.
+     */
+    claimRow<Row extends ObjectLiteral>(
+        source: string,
+        eventId: InboxEventId,
+        tx: EntityManager,
+        receipt: InboxEntityReceipt<Row>,
+    ): Promise<InboxReceiptId>
+}

package/templates/be/inbox/platform/inbox/inbox.service.spec.ts.tpl

@@ -1,7 +1,7 @@
 import { IdempotencyErrorCode } from "@modules/platform/idempotency"
 import { Test } from "@nestjs/testing"
 import type { ClientOperation } from "./inbox.port"
-import { FakeClock, fakeTransaction, mockEntityManager } from "@starci/jest-preset"
+import { FakeClock, fakeTransaction, mockEntityManager, queueQueryBuilders } from "@starci/jest-preset"
 import { BATCH_ROWS, DatabaseError, DatabaseErrorCode } from "@modules/platform/database"
 import { CLOCK } from "@modules/platform/clock"
 import { InboxError, InboxErrorCode } from "./errors/inbox.error"
@@ -29,6 +29,15 @@ const REQUEST = {
 }
 const OUTCOME = { kind: "ok", value: { orderId: "order-1" } }
 
+/** A provider receipt entity as a capability maps its inbox table. */
+class SpecReceiptEntity {
+    id!: string
+    provider!: string
+    deliveryId!: string
+}
+
+const RECEIPT = { entity: SpecReceiptEntity, row: (deliveryId: string) => ({ provider: "spec", deliveryId }) }
+
 const build = async () => {
     const module = await Test.createTestingModule({
         providers: [PostgresInbox, { provide: CLOCK, useValue: new FakeClock("2026-02-03T04:05:06.000Z") }],
@@ -94,6 +103,61 @@ describe("PostgresInbox delivery rollback and validation", () => {
     })
 })
 
+describe("PostgresInbox entity receipts", () => {
+    it("claims the trimmed delivery id, then inserts the receipt row it keys in the caller's transaction and answers its id", async () => {
+        const subject = await build()
+        const manager = mockEntityManager({ query: [CLAIM_EVENT, [{ event_id: "delivery-1" }]] })
+        const [insert] = queueQueryBuilders(manager, [{ execute: { raw: [{ id: "receipt-1" }] } }])
+
+        await expect(subject.claimRow("webhook:spec", "  delivery-1  ", manager, RECEIPT)).resolves.toBe("receipt-1")
+
+        expect(manager.query).toHaveBeenCalledWith(CLAIM_EVENT, ["webhook:spec", "delivery-1"])
+        expect(manager.createQueryBuilder).toHaveBeenCalledWith(SpecReceiptEntity, "receipt")
+        expect(insert?.callsOf("values")).toEqual([[{ provider: "spec", deliveryId: "delivery-1" }]])
+        expect(insert?.callsOf("orIgnore")).toEqual([[]])
+        expect(insert?.callsOf("returning")).toEqual([["id"]])
+    })
+
+    it("inserts no receipt for a delivery already claimed", async () => {
+        const subject = await build()
+        const manager = mockEntityManager({ query: [CLAIM_EVENT, []] })
+
+        await expect(subject.claimRow("webhook:spec", "delivery-1", manager, RECEIPT)).resolves.toBeUndefined()
+
+        expect(manager.createQueryBuilder).not.toHaveBeenCalled()
+    })
+
+    it("answers undefined when the receipt row already exists", async () => {
+        const subject = await build()
+        const manager = mockEntityManager({ query: [CLAIM_EVENT, [{ event_id: "delivery-1" }]] })
+        queueQueryBuilders(manager, [{ execute: { raw: [] } }])
+
+        await expect(subject.claimRow("webhook:spec", "delivery-1", manager, RECEIPT)).resolves.toBeUndefined()
+    })
+
+    it("refuses a returned receipt row without a text id", async () => {
+        const subject = await build()
+        const manager = mockEntityManager({ query: [CLAIM_EVENT, [{ event_id: "delivery-1" }]] })
+        queueQueryBuilders(manager, [{ execute: { raw: [{ id: 7 }] } }])
+
+        await expect(subject.claimRow("webhook:spec", "delivery-1", manager, RECEIPT)).rejects.toMatchObject({
+            code: DatabaseErrorCode.ReturningRowRejected,
+        })
+    })
+
+    it("refuses a missing delivery id before claiming or inserting", async () => {
+        const subject = await build()
+        const manager = mockEntityManager()
+
+        await expect(subject.claimRow("webhook:spec", undefined, manager, RECEIPT)).rejects.toMatchObject({
+            code: DatabaseErrorCode.WebhookDeliveryIdRequired,
+        })
+
+        expect(manager.query).not.toHaveBeenCalled()
+        expect(manager.createQueryBuilder).not.toHaveBeenCalled()
+    })
+})
+
 describe("PostgresInbox client transaction admission", () => {
     it("refuses a manager outside an active transaction before claiming or applying an effect", async () => {
         const inbox = await build()