@starci/hfs 4.11.13 → 4.11.15

package/scaffold/add-inbox-lite.mjs

@@ -13,6 +13,10 @@ const PLACEHOLDER = /@@([A-Za-z][A-Za-z0-9]*)@@/g;
 const timestampOf = (now) =>
   new Date(now()).toISOString().replace(/\D/g, "").slice(0, 14);
 const upperOf = (name) => name.replaceAll("-", "_").toUpperCase();
+const camelOf = (name) => {
+  const pascal = pascalOf(name);
+  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+};
 const snakeOf = (name) => name.replaceAll("-", "_");
 
 const template = (relative, values) => {
@@ -72,8 +76,6 @@ const databasePatches = (root) => {
       "lite add webhook needs the scaffolded platform/database capability",
     );
   let index = fs.readFileSync(indexFile, "utf8").replace(/\r\n/g, "\n");
-  if (!index.includes('export { recordWebhookDelivery, webhookReceiptInsert } from "./webhook-inbox.client"'))
-    index = `${index.trimEnd()}\nexport { recordWebhookDelivery, webhookReceiptInsert } from "./webhook-inbox.client"\n`;
   if (!index.split("\n").some((line) => line.startsWith("export { ") && line.includes("DatabaseErrorCode") && line.endsWith(' } from "./errors/database.error"')))
     index = `${index.trimEnd()}\nexport { DatabaseError, DatabaseErrorCode } from "./errors/database.error"\n`;
   let error = withSqlIdentifierError(fs.readFileSync(errorFile, "utf8").replace(/\r\n/g, "\n"));
@@ -107,7 +109,15 @@ const handoffPlatformFiles = (root, values) => {
   const planned = [];
   for (const capability of ["inbox", "idempotency", "event-bus"]) {
     const base = `be/src/modules/platform/${capability}`;
-    if (fs.existsSync(path.join(root, base, "index.ts"))) continue;
+    if (fs.existsSync(path.join(root, base, "index.ts"))) {
+      // The provider intake claims through the EntityInbox port; an inbox written before it cannot serve a new provider.
+      if (capability === "inbox" && !fs.readFileSync(path.join(root, base, "index.ts"), "utf8").includes("InjectEntityInbox"))
+        throw new ScaffoldError(
+          "HFS_ADD_INBOX_ENTITY_PORT",
+          `${base} predates the EntityInbox port (InjectEntityInbox, claimRow) the ${values.provider} intake claims through; bring it to the inbox of this hfs first`,
+        );
+      continue;
+    }
     const folder = path.join(TEMPLATES_DIR, "be", "inbox", "platform", capability);
     for (const file of filesBelow(folder)) {
       const relative = path.relative(folder, file).replaceAll("\\", "/");
@@ -149,6 +159,28 @@ const eventFiles = (root, provider, values) => {
   return { planned, patches };
 };
 
+/** The lite entity list (BE-PERSISTENCE-3), where the provider inbox's `<provider>InboxEntities` is spread once. */
+const PRIMARY_ENTITIES_FILE = ["be", "src", "modules", "platform", "database", "entities.ts"];
+const PRIMARY_ENTITIES = /(export const PRIMARY_ENTITIES[^=]*=\s*\[)([\s\S]*?)(\])/;
+
+/** entities.ts with the receipt entity list imported from the provider inbox barrel and spread into PRIMARY_ENTITIES. */
+const primaryEntitiesPatch = (root, provider, list) => {
+  const file = path.join(root, ...PRIMARY_ENTITIES_FILE);
+  const relative = PRIMARY_ENTITIES_FILE.join("/");
+  if (!fs.existsSync(file))
+    throw new ScaffoldError("HFS_ADD_INBOX_DATABASE", `lite add webhook names ${list} in PRIMARY_ENTITIES of ${relative}, which is missing`);
+  const text = fs.readFileSync(file, "utf8").replace(/\r\n/g, "\n");
+  if (!PRIMARY_ENTITIES.test(text))
+    throw new ScaffoldError("HFS_ADD_INBOX_DATABASE", `lite add webhook names ${list} in PRIMARY_ENTITIES of ${relative}, which declares no PRIMARY_ENTITIES array`);
+  if (new RegExp(String.raw`\.\.\.${list}\b`).test(text)) return { file, text };
+  const withList = text.replace(PRIMARY_ENTITIES, (all, head, items, tail) =>
+    `${head}${[...items.split(",").map((item) => item.trim()).filter(Boolean), `...${list}`].join(", ")}${tail}`);
+  const lines = withList.split("\n");
+  const lastImport = lines.reduce((at, line, index) => (line.startsWith("import ") ? index : at), -1);
+  lines.splice(lastImport + 1, 0, `import { ${list} } from "@modules/domain/${provider}-inbox"`);
+  return { file, text: lines.join("\n") };
+};
+
 const eventPatternPatch = (root) => {
   const file = path.join(root, "hfs.json");
   const declaration = JSON.parse(fs.readFileSync(file, "utf8"));
@@ -190,6 +222,7 @@ export function addLiteWebhookInbox({
     ...values,
     provider,
     Provider,
+    providerCamel: camelOf(provider),
     providerUpper: upperOf(provider),
     table,
   };
@@ -221,6 +254,14 @@ export function addLiteWebhookInbox({
       relative: `${base}/${provider}-inbox.service.spec.ts`,
       text: template("service.spec.ts.tpl", renderValues),
     },
+    {
+      relative: `${base}/persistence/entities/${provider}-inbox.entity.ts`,
+      text: template("entity.ts.tpl", renderValues),
+    },
+    {
+      relative: `${base}/persistence/entities/index.ts`,
+      text: template("entities.index.ts.tpl", renderValues),
+    },
     {
       relative: `be/src/modules/events/${provider}/${provider}-delivery-recorded.event.ts`,
       text: template("delivery-recorded.event.ts.tpl", renderValues),
@@ -242,26 +283,6 @@ export function addLiteWebhookInbox({
       text: render(fs.readFileSync(path.join(TEMPLATES_DIR, "be", "skeleton-lite", "src", "modules", "platform", "database", file), "utf8"), {}),
     });
   }
-  const databaseClient = path.join(
-    root,
-    "be",
-    "src",
-    "modules",
-    "platform",
-    "database",
-    "webhook-inbox.client.ts",
-  );
-  if (!fs.existsSync(databaseClient))
-    planned.push(
-      {
-        relative: "be/src/modules/platform/database/webhook-inbox.client.ts",
-        text: template("database-client.ts.tpl", renderValues),
-      },
-      {
-        relative: "be/src/modules/platform/database/webhook-inbox.client.spec.ts",
-        text: template("database-client.spec.ts.tpl", renderValues),
-      },
-    );
   const clashes = planned
     .filter((entry) => fs.existsSync(path.join(root, ...entry.relative.split("/"))))
     .map((entry) => entry.relative);
@@ -272,6 +293,7 @@ export function addLiteWebhookInbox({
     );
   const patches = [
     ...databasePatches(root),
+    primaryEntitiesPatch(root, provider, `${renderValues.providerCamel}InboxEntities`),
     ...events.patches,
     eventPatternPatch(root),
   ];

package/scaffold/lite-exports.mjs

@@ -108,6 +108,19 @@ const REGISTRATIONS = Object.freeze({
       source: "./webhook-signature.service",
       names: ["WebhookSignatureService"],
     },
+    {
+      // The webhook door types its request with the correlation the logging middleware stamps on it.
+      file: "be/src/modules/platform/logging/index.ts",
+      source: "./correlation.contracts",
+      names: ["CorrelationRequest"],
+      type: true,
+    },
+    {
+      // The lite event bus refuses an envelope whose correlation id is not one the logging capability issues.
+      file: "be/src/modules/platform/logging/index.ts",
+      source: "./correlation.policy",
+      names: ["isCorrelationId"],
+    },
   ],
   "webhook-full": [
     {

package/src/main.mjs

@@ -116,11 +116,11 @@ starci app db migrate [--execute] [--url-env <NAME>] [--json] [--cwd <dir>]
 starci app db post-cutover [--execute] [--green-at <ISO> | --owner-confirms-old-app-gone] [--url-env <NAME>] [--json] [--cwd <dir>]
 starci app db drift [--url-env <NAME>] [--json] [--cwd <dir>]
 starci app release gate [--execute] [--source <ref>] [--tag-prefix <prefix>] [--backfill <tag>] [--json] [--cwd <dir>]
-starci app release push [--execute] [--remote <name>] [--urgent --reason <text>] [--json] [--cwd <dir>]
+starci app release push [--execute] [--remote <name>] [--urgent --reason <text> [--lint-baseline <tag>]] [--json] [--cwd <dir>]
 starci app upgrade [--plan] [--cwd <dir>]
 starci app stack <up|down|status> [--stack <dir>] [--services <list>] [--k3d] [--force] [--json] [--cwd <dir>]
 starci app stack <prepare|doctor|connect|disconnect|build-args|render|deploy|converge|verify|rollback|prune|backup|jobs> --env <env> [--execute] [--json] [--cwd <dir>]
-starci app stack deploy --env <env> --source-sha <sha> --urgent [--db-url-env <NAME>] [--backup-out <dir>] [--execute] [--json] [--cwd <dir>]
+starci app stack deploy --env <env> --source-sha <sha> --urgent [--db-url-env <NAME>] [--backup-out <dir>] [--first-start --db-service <service>] [--execute] [--json] [--cwd <dir>]
 starci app explain <path> [--cwd <dir>] [--json]
 starci app emit [--cwd <dir>]
 starci app new service <dir> <name> [--inject <binding>...] [--cwd <dir>]

package/stack/cli.mjs

@@ -14,8 +14,8 @@ const DOCKER_ACTIONS = new Set(['deploy', 'accept', 'converge', 'verify', 'rollb
 
 export const ACTIONS = Object.freeze(['prepare', 'doctor', 'connect', 'disconnect', 'build-args', 'render', 'deploy', 'converge', 'verify', 'rollback', 'prune', 'backup', 'jobs', 'task', 'ingress', 'retire', 'build', 'accept']);
 
-const BOOLEAN = new Set(['--execute', '--json', '--swarm-state', '--init-swarm', '--owner-approved', '--fix-live-restore', '--skip-public', '--skip-internal', '--allow-unpinned', '--push', '--urgent']);
-const VALUE = new Set(['--env', '--image', '--source-sha', '--previous', '--out', '--release', '--since', '--timeout', '--retry', '--keep', '--app', '--ssh-cmd', '--extra-compose', '--project', '--target-binding', '--db-url-env', '--backup-out']);
+const BOOLEAN = new Set(['--execute', '--json', '--swarm-state', '--init-swarm', '--owner-approved', '--fix-live-restore', '--skip-public', '--skip-internal', '--allow-unpinned', '--push', '--urgent', '--first-start']);
+const VALUE = new Set(['--env', '--image', '--source-sha', '--previous', '--out', '--release', '--since', '--timeout', '--retry', '--keep', '--app', '--ssh-cmd', '--extra-compose', '--project', '--target-binding', '--db-url-env', '--backup-out', '--db-service']);
 const REPEAT = new Set(['--image', '--keep', '--extra-compose', '--project']);
 
 /** Splits argv into { flags, positional }; an unknown flag or a flag without its value is a refusal. */
@@ -72,6 +72,7 @@ const OPTIONS = {
     images: parseImages(flags.image), sourceSha: flags['source-sha'], execute: flags.execute === true,
     out: flags.out ? path.resolve(cwd, flags.out) : null, timeoutSeconds: number(flags, 'timeout'), retrySeconds: number(flags, 'retry'), skipPublic: flags['skip-public'] === true,
     urgent: flags.urgent === true, dbUrlEnv: flags['db-url-env'], backupOut: flags['backup-out'] ? path.resolve(cwd, flags['backup-out']) : undefined,
+    firstStart: flags['first-start'] === true, dbService: flags['db-service'],
   }),
   converge: ({ flags }) => ({ since: flags.since, timeoutSeconds: number(flags, 'timeout') }),
   verify: ({ flags }) => ({ retrySeconds: number(flags, 'retry'), skipPublic: flags['skip-public'] === true, skipInternal: flags['skip-internal'] === true }),
@@ -126,7 +127,8 @@ export async function stackMain(argv, io = {}) {
     if (binding && (!['deploy', 'verify'].includes(action) || flags['ssh-cmd'] || flags['skip-public'] || flags['skip-internal']))
       throw refusal('STACK_USAGE', 'the bound native consumer supports only complete deploy or verify');
     const config = bindStackTarget(ctx, loadDeployConfig({ repoRoot: ctx.cwd, env: flags.env ?? 'production' }), binding);
-    if (action !== 'deploy' && (flags.urgent || flags['db-url-env'] || flags['backup-out'])) throw refusal('STACK_USAGE', '--urgent, --db-url-env and --backup-out belong to deploy');
+    if (action !== 'deploy' && (flags.urgent || flags['db-url-env'] || flags['backup-out'] || flags['first-start'] || flags['db-service'])) throw refusal('STACK_USAGE', '--urgent, --db-url-env, --backup-out, --first-start and --db-service belong to deploy');
+    if (!flags.urgent && (flags['first-start'] || flags['db-service'])) throw refusal('STACK_USAGE', '--first-start and --db-service are the first start of an empty database under the urgent floor: add --urgent');
     if (action === 'deploy' && !flags.urgent && (flags['db-url-env'] || flags['backup-out'])) throw refusal('STACK_USAGE', '--db-url-env and --backup-out choose the urgent floor\'s database and backup folder: add --urgent');
     const options = OPTIONS[action]({ flags, positional, cwd: ctx.cwd });
     const handler = await handlerOf(action, io.importer ?? ((file) => import(file)));

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/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/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()

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

@@ -1,9 +1,17 @@
 import { Injectable } from "@nestjs/common"
-import type { EntityManager } from "typeorm"
+import type { EntityManager, ObjectLiteral } from "typeorm"
 import { InjectClock } from "@modules/platform/clock"
 import type { Clock } from "@modules/platform/clock"
-import { BATCH_ROWS, DatabaseError, DatabaseErrorCode, callDbFunction } from "@modules/platform/database"
-import type { ClientOperation, ClientOperationEffect, Inbox, InboxEventId } from "./inbox.port"
+import { BATCH_ROWS, DatabaseError, DatabaseErrorCode, callDbFunction, returnedRows, rowShape } from "@modules/platform/database"
+import type {
+    ClientOperation,
+    ClientOperationEffect,
+    EntityInbox,
+    Inbox,
+    InboxEntityReceipt,
+    InboxEventId,
+    InboxReceiptId,
+} from "./inbox.port"
 import { IdempotencyError, IdempotencyErrorCode } from "@modules/platform/idempotency"
 import { InboxError, InboxErrorCode } from "./errors/inbox.error"
 import { clientSource } from "./client-operation.policy"
@@ -43,19 +51,43 @@ interface InboxSweepRow {
     readonly deleted_count: number
 }
 
+/** The row a receipt insert returns to the transaction that won it. */
+const isReceiptRow = rowShape({ id: "string" })
+
+/** The provider's delivery id, trimmed; a missing or blank one is refused before anything is claimed or written. */
+const deliveryIdOf = (eventId: InboxEventId): string => {
+    const deliveryId = eventId?.trim()
+    if (!deliveryId) throw new DatabaseError({ code: DatabaseErrorCode.WebhookDeliveryIdRequired })
+    return deliveryId
+}
+
 @Injectable()
 /** Claims a delivery with the receipt transaction, so a failure can be retried without losing the delivery. */
-export class PostgresInbox implements Inbox {
+export class PostgresInbox implements Inbox, EntityInbox {
     constructor(@InjectClock() private readonly clock: Clock) {}
 
     /** The first claim wins; the same source and delivery id becomes a no-op on redelivery. */
     async claim(source: string, eventId: InboxEventId, tx: EntityManager): Promise<boolean> {
-        const normalizedEventId = eventId?.trim()
-        if (!normalizedEventId) {
-            throw new DatabaseError({ code: DatabaseErrorCode.WebhookDeliveryIdRequired })
-        }
-        const rows = await callDbFunction<InboxEventRow>(tx, "public.inbox_claim_event", [source, normalizedEventId])
-        return rows.length > 0
+        return this.claimDelivery(source, deliveryIdOf(eventId), tx)
+    }
+
+    /** The claim first; only its winner inserts the receipt row, and a row that already exists is left as it is. */
+    async claimRow<Row extends ObjectLiteral>(
+        source: string,
+        eventId: InboxEventId,
+        tx: EntityManager,
+        receipt: InboxEntityReceipt<Row>,
+    ): Promise<InboxReceiptId> {
+        const deliveryId = deliveryIdOf(eventId)
+        if (!(await this.claimDelivery(source, deliveryId, tx))) return undefined
+        const inserted = await tx
+            .createQueryBuilder(receipt.entity, "receipt")
+            .insert()
+            .values(receipt.row(deliveryId))
+            .orIgnore()
+            .returning("id")
+            .execute()
+        return returnedRows(inserted.raw, isReceiptRow)[0]?.id
     }
 
     /** Runs once in the domain transaction, returning the persisted JSON outcome on both the first call and every retry. */
@@ -99,4 +131,10 @@ export class PostgresInbox implements Inbox {
         const rows = await callDbFunction<InboxSweepRow>(tx, "public.inbox_sweep_clients", [cutoff, BATCH_ROWS])
         return rows[0]?.deleted_count ?? 0
     }
+
+    /** Claims a normalized delivery id; an answered row means this transaction holds the first claim. */
+    private async claimDelivery(source: string, deliveryId: string, tx: EntityManager): Promise<boolean> {
+        const rows = await callDbFunction<InboxEventRow>(tx, "public.inbox_claim_event", [source, deliveryId])
+        return rows.length > 0
+    }
 }