@starci/hfs 4.12.2 → 4.13.0

package/stack/remote.mjs

@@ -15,6 +15,7 @@ import path from 'node:path';
 import { tool } from './context.mjs';
 import { restrictToUser, writePrivate } from './private-file.mjs';
 import { refusal } from './errors.mjs';
+import { openMember as openSealedMember } from './sealed.mjs';
 import { createSshSession, sessionDirectory } from './ssh-session.mjs';
 import { assertStackAccount } from './target-binding.mjs';
 const ACCOUNT = /^[A-Za-z0-9._@-]+$/u;
@@ -215,22 +216,36 @@ function ciHome(ctx) {
         throw refusal('STACK_CONNECT_NO_HOME', 'HOME is not set');
     return path.join(ctx.env.HOME, '.ssh');
 }
-function ciInputs(ctx) {
+/** The sealed member that holds the CI transport of an environment: VPS_SSH_KEY (the CI-only deploy key), VPS_KNOWN_HOSTS, VPS_HOST and VPS_USER. */
+export const CI_MEMBER = 'vps-ci';
+/**
+ * The CI transport values: the sealed member `vps-ci` of the environment (opened with the server identity the job holds) when it exists, else the
+ * variables of the job (the transition, and the owner's own runs). The member keeps the host, the account, the key and the pinned host keys out of
+ * GitHub and of a public log; the pinned host keys are reviewed in git as ciphertext.
+ */
+function ciValues(ctx, config) {
+    const present = typeof config.secretsDir === 'string' && fs.existsSync(memberFile(config.secretsDir, CI_MEMBER));
+    if (!present)
+        return { values: ctx.env, sealed: false };
+    const map = openSealedMember(ctx, config, CI_MEMBER);
+    return { values: Object.fromEntries(CI_VARIABLES.map((name) => [name, typeof map[name] === 'string' ? map[name] : undefined])), sealed: true };
+}
+function ciInputs(ctx, values, sealed) {
     for (const name of CI_VARIABLES)
-        if (!ctx.env[name])
-            throw refusal('STACK_CONNECT_MISSING', `${name} is not set`);
+        if (!values[name])
+            throw refusal('STACK_CONNECT_MISSING', sealed ? `the sealed member ${CI_MEMBER} holds no ${name}` : `${name} is not set and the environment has no sealed member ${CI_MEMBER}`);
     const [host, user] = ['VPS_HOST', 'VPS_USER'].map((name) => {
-        const value = ctx.env[name]; // set: every CI variable was checked above
+        const value = values[name]; // set: every CI variable was checked above
         if (!ACCOUNT.test(value) || value.startsWith('-'))
             throw refusal('STACK_CONNECT_INVALID', `${name} must match ${ACCOUNT}`);
         return value;
     });
-    const key = lfOnly(ctx.env.VPS_SSH_KEY);
+    const key = lfOnly(values.VPS_SSH_KEY);
     if (!key.includes('PRIVATE KEY'))
         throw refusal('STACK_CONNECT_INVALID', 'VPS_SSH_KEY is not a PEM private key');
     if (!ctx.env.GITHUB_ENV)
         throw refusal('STACK_CONNECT_NO_GITHUB_ENV', 'GITHUB_ENV is not set');
-    return { key: withNewline(key), known: withNewline(lfOnly(ctx.env.VPS_KNOWN_HOSTS)), host, user };
+    return { key: withNewline(key), known: withNewline(lfOnly(values.VPS_KNOWN_HOSTS)), host, user };
 }
 const sshBlock = (alias, inputs) => [
     '', `Host ${alias}`, `  HostName ${inputs.host}`, `  User ${inputs.user}`, '  IdentityFile ~/.ssh/deploy_key',
@@ -240,18 +255,23 @@ const sshBlock = (alias, inputs) => [
 /** CI transport: pinned key, known_hosts, ssh config block and DOCKER_HOST=ssh://<alias> in $GITHUB_ENV. */
 export async function connectCi(ctx, config, { execute = false } = {}) {
     const dir = ciHome(ctx);
-    const inputs = ciInputs(ctx);
+    const { values, sealed } = ciValues(ctx, config);
+    const inputs = ciInputs(ctx, values, sealed);
     const alias = config.remote.host;
-    const plan = [`${dir}/deploy_key (0600) from VPS_SSH_KEY`, `${dir}/known_hosts (0644) from VPS_KNOWN_HOSTS`, `a Host ${alias} block in ${dir}/config`, `DOCKER_HOST=ssh://${alias} in GITHUB_ENV`];
-    const data = { host: alias, files: ['deploy_key', 'known_hosts', 'config'] };
+    const origin = sealed ? `the sealed member ${CI_MEMBER}` : 'VPS_SSH_KEY';
+    const plan = [`${dir}/deploy_key (0600) from ${origin}`, `${dir}/known_hosts (0644) from ${sealed ? CI_MEMBER : 'VPS_KNOWN_HOSTS'}`, `a Host ${alias} block in ${dir}/config`, `DOCKER_HOST=ssh://${alias} in GITHUB_ENV`];
+    const data = { host: alias, files: ['deploy_key', 'known_hosts', 'config'], sealed };
     if (!execute)
         return { ok: true, lines: plan.map((item) => `dry run: would write ${item}`), data };
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
     writeWithMode(path.join(dir, 'deploy_key'), inputs.key, 0o600);
     writeWithMode(path.join(dir, 'known_hosts'), inputs.known, 0o644);
     fs.appendFileSync(path.join(dir, 'config'), sshBlock(alias, inputs), { mode: 0o600 });
-    fs.appendFileSync(ctx.env.GITHUB_ENV, `DOCKER_HOST=ssh://${alias}\n`);
-    return { ok: true, lines: plan.map((item) => `wrote ${item}`), data };
+    fs.appendFileSync(ctx.env.GITHUB_ENV, `DOCKER_HOST=ssh://${alias}
+`);
+    // The log of a public repository is public: mask the host, the account and the releases root before any later line can carry them.
+    const masks = sealed ? [inputs.host, inputs.user, config.remote.releasesBase].filter((value) => typeof value === 'string' && value.length >= 4).map((value) => `::add-mask::${value}`) : [];
+    return { ok: true, lines: [...masks, ...plan.map((item) => `wrote ${item}`)], data };
 }
 /** CI cleanup: closes the ssh control master (failure ignored) and removes the deploy key. */
 export async function disconnectCi(ctx, config, { execute = false } = {}) {

package/stack/server-key.d.mts

@@ -28,6 +28,8 @@ export interface ServerKeyOptions {
 export declare const SERVER_AGE_IDENTITY = "/root/.config/sops/age/keys.txt";
 /** The managed workflow `--restore github` dispatches (templates/app/ci-workflows*). */
 export declare const RESTORE_WORKFLOW = "stack-key-restore.yml";
+/** A command run as root: directly when the deploy user is root, else over passwordless sudo, the script read from stdin. */
+export declare 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.

package/stack/server-key.mjs

@@ -37,7 +37,7 @@ export const SERVER_AGE_IDENTITY = '/root/.config/sops/age/keys.txt';
 export const RESTORE_WORKFLOW = 'stack-key-restore.yml';
 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';
+export 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.

package/stack/status.d.mts

@@ -0,0 +1,49 @@
+import type { DeployConfig } from './config.mjs';
+import type { StackContext } from './context.mjs';
+import type { ReleaseStore } from './release-store.mjs';
+import type { ActionResult, Runner, SshOptions } from './remote.mjs';
+/** One live service of the stack as `docker service inspect` reports it (names, digests and states only; no environment, no secret). */
+export interface ObservedService {
+    /** The service name without the stack prefix (`api` for `shop_api`). */
+    service: string;
+    /** The image reference of the service spec, or null when it has none. */
+    image: string | null;
+    /** The `sha256:...` digest the image reference pins, or null when it is a tag only. */
+    digest: string | null;
+    /** The update state of the service (`completed`, `rollback_completed`, ...), null when it was never updated. */
+    updateState: string | null;
+    /** The first 16 hex of the sha256 of the canonical task template: it changes when anything a task runs with changes. */
+    taskTemplateHash: string | null;
+}
+/** The kinds of drift a status reports. */
+export type DriftKind = 'rolled back by swarm' | 'updated outside a release' | 'missing' | 'not in the release';
+/** One service that does not run what the accepted release says. */
+export interface ServiceDrift {
+    service: string;
+    kind: DriftKind;
+    detail: string;
+}
+/** The `sha256:...` digest an image reference pins, or null. */
+export declare const digestOf: (image: string | null | undefined) => string | null;
+/** The image of each service of a stack file, by service name (the pinned references of a rendered release). */
+export declare function stackImages(stackYaml: string): Record<string, string>;
+/** The live services of the stack, sorted by name. Throws when docker cannot be asked. */
+export declare function observedServices(ctx: Pick<StackContext, 'spawn'>, config: Pick<DeployConfig, 'stack'>): ObservedService[];
+/** What a release says its services run: the stack's images and, when it was accepted by this version, the services observed at the accept. */
+export interface ExpectedRelease {
+    stackYaml: string;
+    release: Record<string, unknown>;
+}
+/** Compares the live services with a release; an empty list means they run the release. */
+export declare function compareWithRelease(expected: ExpectedRelease, live: readonly ObservedService[]): ServiceDrift[];
+/** The collaborators of a status (the specs inject stubs). */
+export interface StatusDeps {
+    ssh: (ctx: StackContext, config: DeployConfig, options: SshOptions) => Runner | Promise<Runner>;
+    releaseStore: (config: DeployConfig, ssh: Runner) => ReleaseStore;
+    observedServices: (ctx: StackContext, config: DeployConfig) => ObservedService[];
+}
+/**
+ * `stack status`: the accepted release against the live services. Returns { ok, lines, data: { release, sourceSha, drift, services } }; ok is false exactly
+ * when a service drifted. An environment with no accepted release reports that and is not a drift.
+ */
+export declare function statusStack(ctx: StackContext, config: DeployConfig, options?: SshOptions, deps?: Partial<StatusDeps>): Promise<ActionResult>;

package/stack/status.mjs

@@ -0,0 +1,114 @@
+// status.mjs - what runs against what was accepted: `starci app stack status --env <env>` (read-only) compares the live services of the stack with the
+// accepted release and prints the drift per service. A service is drifted when
+//   - Swarm rolled it back by itself (its update state is `rollback_*`): the release still reads as the new one, the service runs the old spec;
+//   - its live image digest is not the digest the release's stack.yaml names, or its task template is not the one observed when the release was accepted
+//     (a manual `docker service update`): `updated outside a release`;
+//   - it is missing from the swarm, or runs in the stack without being in the release.
+// `observedServices(ctx, config)` is the one reader of the live services: the deploy snapshots it into its journal (after converge, after a rollback and on
+// accept) and into release.json (`observed`), and `verifyStack` judges the digests it reads. Every call is a docker query; nothing here changes the swarm.
+import { createHash } from 'node:crypto';
+import { parseYaml } from '../runtime/engine/yaml.mjs';
+import { canonical } from './converge.mjs';
+import { lines as splitLines, toolOutput } from './context.mjs';
+import { createReleaseStore } from './release-store.mjs';
+const DIGEST = /@(sha256:[0-9a-f]{64})$/u;
+const IMAGE_FIELD = /^[A-Za-z0-9][A-Za-z0-9./_:@-]*$/u;
+/** The `sha256:...` digest an image reference pins, or null. */
+export const digestOf = (image) => (image ? (DIGEST.exec(image)?.[1] ?? null) : null);
+/** The image of each service of a stack file, by service name (the pinned references of a rendered release). */
+export function stackImages(stackYaml) {
+    // reason: the stack file, parsed YAML read defensively
+    const services = parseYaml(stackYaml)?.services ?? {};
+    const pairs = Object.entries(services).map(([name, entry]) => [name, entry?.image]);
+    return Object.fromEntries(pairs.filter((pair) => typeof pair[1] === 'string' && IMAGE_FIELD.test(pair[1])));
+}
+const shortDigest = (digest) => (digest ? digest.slice(0, 19) : 'no digest');
+/** Reads one `docker service inspect` document into an ObservedService. */
+function observe(stack, name, text) {
+    // reason: `docker service inspect` output, parsed JSON read defensively below
+    const inspect = JSON.parse(text);
+    const image = inspect?.Spec?.TaskTemplate?.ContainerSpec?.Image;
+    const template = inspect?.Spec?.TaskTemplate;
+    const state = inspect?.UpdateStatus?.State;
+    const reference = typeof image === 'string' && IMAGE_FIELD.test(image) ? image : null;
+    return {
+        service: name.startsWith(`${stack}_`) ? name.slice(stack.length + 1) : name,
+        image: reference,
+        digest: digestOf(reference),
+        updateState: typeof state === 'string' && /^[a-z_]+$/u.test(state) ? state : null,
+        taskTemplateHash: template === undefined ? null : createHash('sha256').update(canonical(template)).digest('hex').slice(0, 16),
+    };
+}
+/** The live services of the stack, sorted by name. Throws when docker cannot be asked. */
+export function observedServices(ctx, config) {
+    const names = splitLines(toolOutput(ctx, 'docker', ['service', 'ls', '--filter', `label=com.docker.stack.namespace=${config.stack}`, '--format', '{{.Name}}'])).sort();
+    return names.map((name) => observe(config.stack, name, toolOutput(ctx, 'docker', ['service', 'inspect', name, '--format', '{{json .}}'])));
+}
+/** The `observed.accept` services of a release record, or [] when it carries none (an older release). */
+function acceptedObservation(release) {
+    const observed = release.observed;
+    const list = observed?.accept;
+    return Array.isArray(list) ? list.filter((entry) => typeof entry === 'object' && entry !== null && typeof entry.service === 'string') : [];
+}
+/** Compares the live services with a release; an empty list means they run the release. */
+export function compareWithRelease(expected, live) {
+    const images = stackImages(expected.stackYaml);
+    const accepted = new Map(acceptedObservation(expected.release).map((entry) => [entry.service, entry]));
+    const running = new Map(live.map((entry) => [entry.service, entry]));
+    const drift = [];
+    for (const [service, image] of Object.entries(images)) {
+        const now = running.get(service);
+        if (!now) {
+            drift.push({ service, kind: 'missing', detail: 'the release names it and no such service runs' });
+            continue;
+        }
+        const wanted = digestOf(image);
+        if (now.updateState?.startsWith('rollback'))
+            drift.push({ service, kind: 'rolled back by swarm', detail: `update state ${now.updateState}; runs ${shortDigest(now.digest)}, the release names ${shortDigest(wanted)}` });
+        else if (wanted && now.digest !== wanted)
+            drift.push({ service, kind: 'updated outside a release', detail: `runs ${shortDigest(now.digest)}, the release names ${shortDigest(wanted)}` });
+        else {
+            const seen = accepted.get(service)?.taskTemplateHash ?? null;
+            if (seen && now.taskTemplateHash && seen !== now.taskTemplateHash)
+                drift.push({ service, kind: 'updated outside a release', detail: 'its task template changed since the release was accepted' });
+        }
+    }
+    for (const service of running.keys())
+        if (!Object.hasOwn(images, service))
+            drift.push({ service, kind: 'not in the release', detail: 'it runs in the stack and the accepted release does not name it' });
+    return drift;
+}
+// reason: a dynamic import by string, resolved on first use so a spec that injects `ssh` never loads remote.mjs
+const ownerSsh = async (ctx, config, options) => (await import('./remote.mjs')).ownerSshRunner(ctx, config, options);
+const DEFAULT_DEPS = { ssh: ownerSsh, releaseStore: createReleaseStore, observedServices };
+/**
+ * `stack status`: the accepted release against the live services. Returns { ok, lines, data: { release, sourceSha, drift, services } }; ok is false exactly
+ * when a service drifted. An environment with no accepted release reports that and is not a drift.
+ */
+export async function statusStack(ctx, config, options = {}, deps = {}) {
+    const d = { ...DEFAULT_DEPS, ...deps };
+    const run = await d.ssh(ctx, config, { sshCmd: options.sshCmd ?? null });
+    try {
+        const store = d.releaseStore(config, run);
+        const current = await store.current();
+        const live = d.observedServices(ctx, config);
+        if (!current)
+            return { ok: true, lines: [`status: ${config.stack} has no accepted release${live.length > 0 ? `; ${live.length} service(s) run in the stack` : ''}`], data: { release: null, sourceSha: null, drift: [], services: live } };
+        const stored = await store.read(current);
+        const drift = compareWithRelease(stored, live);
+        const sourceSha = typeof stored.release.sourceSha === 'string' ? stored.release.sourceSha : null;
+        const drifted = new Map(drift.map((entry) => [entry.service, entry]));
+        const names = [...new Set([...Object.keys(stackImages(stored.stackYaml)), ...live.map((entry) => entry.service)])].sort();
+        const rows = names.map((name) => {
+            const found = drifted.get(name);
+            const now = live.find((entry) => entry.service === name);
+            return found ? `DRIFT  ${name}  ${found.kind}: ${found.detail}` : `PASS  ${name}  ${shortDigest(now?.digest ?? null)}`;
+        });
+        const head = `status: accepted release ${current}${sourceSha ? ` (commit ${sourceSha.slice(0, 10)})` : ''}`;
+        const tail = drift.length === 0 ? 'status: every service runs the accepted release' : `status: ${drift.length} service(s) differ from the accepted release`;
+        return { ok: drift.length === 0, lines: [head, ...rows, tail], data: { release: current, sourceSha, drift, services: live } };
+    }
+    finally {
+        run.cleanup?.();
+    }
+}

package/stack/urgent-floor.d.mts

@@ -1,7 +1,10 @@
-import { type DbTarget as PostgresTarget } from '../db/postgres.mjs';
 import type { DeployConfig } from './config.mjs';
 import type { StackContext } from './context.mjs';
+import { FIRST_START_WAIT_SECONDS, FLOOR_DEPS } from './db-phases.mjs';
+import type { BackupData, BackupReceipt, FirstStartStepResult, FloorDeps } from './db-phases.mjs';
 import type { ActionResult } from './remote.mjs';
+export { FIRST_START_WAIT_SECONDS, FLOOR_DEPS };
+export type { BackupData, BackupReceipt, FirstStartStepResult, FloorDeps };
 /** The options of an urgent deploy the floor reads. */
 export interface FloorOptions {
     skipPublic?: boolean | undefined;
@@ -12,56 +15,6 @@ export interface FloorOptions {
     backupOut?: string | undefined;
     execute?: boolean | undefined;
 }
-/** The receipt of a database backup (db/backup-receipt.mjs). */
-export interface BackupReceipt {
-    schemaOnly: boolean;
-    at: string;
-    file: string;
-    bytes: number;
-    sha256: string;
-    parts: string[];
-}
-/** What a backup hands back: where the receipt is and what it says. */
-export interface BackupData {
-    receiptPath: string;
-    receipt?: BackupReceipt | undefined;
-}
-/** The database a floor step reaches (db/postgres.mjs). */
-type DbTarget = Record<string, unknown>;
-/** The verdict of one migrate pass. */
-interface MigrateResult {
-    ok: boolean;
-    lines?: string[] | undefined;
-}
-/** Whether the database is empty, and why not. */
-interface Emptiness {
-    empty: boolean;
-    history: boolean;
-    publicTables: number;
-}
-/** The collaborators of the floor, each defaulting to the app's own db verbs. */
-export interface FloorDeps {
-    backup: (ctx: StackContext, args: {
-        target: DbTarget;
-        out: string;
-    }) => Promise<BackupData>;
-    decrypt: (ctx: StackContext, args: {
-        archive: string;
-        identity: string | null;
-        parts: string[];
-    }) => Promise<{
-        parts: string[];
-    }>;
-    migrate: (ctx: StackContext, args: {
-        target: DbTarget;
-        execute: boolean;
-    }) => Promise<MigrateResult>;
-    dbContainer: (ctx: StackContext, config: DeployConfig, args: {
-        service: string;
-        seconds: number;
-    }) => Promise<string | undefined>;
-    emptiness: (ctx: StackContext, target: PostgresTarget) => Promise<Emptiness>;
-}
 /** The data a deploy result carries that the floor reads. */
 export interface DeployData {
     steps?: {
@@ -87,20 +40,16 @@ export interface UrgentRun {
     }): Promise<DeployOutcome>;
     dryRun(): Promise<ActionResult>;
     sha256(file: string): string;
+    /** Hands the urgent record (tag, role, reason) to the deploy journal once the floor has read it. */
+    note?(record: {
+        tag: string;
+        role: string;
+        reason: string;
+    }): void;
 }
-/** The outcome of the `first-start` step. */
-export interface FirstStartStepResult {
-    ok: boolean;
-    code?: string;
-    lines: string[];
-}
-/** How long a first start waits for the database service's container to accept connections. */
-export declare const FIRST_START_WAIT_SECONDS = 180;
-export declare const FLOOR_DEPS: Readonly<FloorDeps>;
 /**
  * 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
  * data names the urgent release.
  */
 export declare function urgentDeploy(ctx: StackContext, config: DeployConfig, options: FloorOptions, run: UrgentRun, deps?: Partial<FloorDeps>): Promise<ActionResult>;
-export {};

package/stack/urgent-floor.mjs

@@ -1,12 +1,12 @@
 // urgent-floor.mjs - the safety floor of an urgent deploy (`starci app stack deploy --urgent`, owner ruling urgent-release 2026-10-29). An urgent
 // release skips CI and the full gate, never this floor; each step that fails is a refusal with its own code, never a warning:
 //   record     the commit carries a pushed URGENT record (release/urgent.mjs)                     STACK_URGENT_NO_RECORD, STACK_URGENT_NOT_PUSHED
-//   backup     a fresh full database backup, encrypted to the app's age recipients (db dump)       STACK_URGENT_BACKUP_FAILED
-//   verified   its receipt names this run, its size, age header and sha256 match the archive        STACK_URGENT_BACKUP_UNVERIFIED
-//   decrypt    a test decrypt with the operator's age identity (SOPS_AGE_KEY_FILE) lists every part STACK_URGENT_DECRYPT_UNAVAILABLE, STACK_URGENT_DECRYPT_FAILED
+//   backup     a fresh full database backup, encrypted to the app's age recipients (db dump)       STACK_DEPLOY_BACKUP_FAILED
+//   verified   its receipt names this run, its size, age header and sha256 match the archive        STACK_DEPLOY_BACKUP_UNVERIFIED
+//   decrypt    a test decrypt with the operator's age identity (SOPS_AGE_KEY_FILE) lists every part STACK_DEPLOY_BACKUP_DECRYPT_UNAVAILABLE, STACK_DEPLOY_BACKUP_DECRYPT_FAILED
 //   render     the release renders locally (deploy.mjs inspectRendered)                           its own STACKS_/STACK_DEPLOY_ refusal
 //   rollback   an accepted previous release exists, so a red deploy has somewhere to go back to    STACK_URGENT_NO_ROLLBACK_TARGET
-//   migrate    db migrate previews the plan, then executes it                                     STACK_URGENT_MIGRATE_PREVIEW_RED, STACK_URGENT_MIGRATE_FAILED
+//   migrate    db migrate previews the plan, then executes it                                     STACK_DEPLOY_MIGRATE_PREVIEW_RED, STACK_DEPLOY_MIGRATE_FAILED
 //   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.
@@ -20,101 +20,28 @@
 //   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.
+// The backup, decrypt, migrate and first-start steps are shared with the automatic deploy (db-phases.mjs), under the same STACK_DEPLOY_* codes; the
+// urgent path keeps its operator-held --db-url-env and its always-on backup (the floor is never skipped). `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 { DEFAULT_DB_URL_ENV, dbTarget, inContainer } 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';
-const SHA = /^[a-f0-9]{64}$/u;
-/** The code or message of a thrown value, for a refusal line. */
-const reasonOf = (error) => String(error?.code ?? error?.message ?? error);
-/** The message of a thrown value. */
-const messageOf = (error) => String(error?.message ?? error);
+import { FIRST_START_WAIT_SECONDS, FLOOR_DEPS, backupProblems, firstStartStep as sharedFirstStartStep, messageOf, reasonOf, refused } from './db-phases.mjs';
+import { localFacts } from './manager-backup.mjs';
+export { FIRST_START_WAIT_SECONDS, FLOOR_DEPS };
 /** The database a floor step reaches: the connection named by --db-url-env (default DATABASE_URL). */
 const targetOf = (options) => (options.dbUrlEnv ? { urlEnv: options.dbUrlEnv } : {});
 /** The backups of an urgent deploy live outside every repository: --backup-out, else ~/.starci-backups/<project>. */
 const backupDir = (config, options) => options.backupOut ?? path.join(os.homedir(), '.starci-backups', config.project);
-async function defaultBackup(ctx, { target, out }) {
-    const { dumpDatabase } = await import('../db/dump.mjs');
-    return dumpDatabase(ctx, { ...target, out }).data;
-}
-async function defaultDecrypt(ctx, { archive, identity, parts }) {
-    const { backupTool } = await import('../db/backup-receipt.mjs');
-    const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'starci-decrypt-'));
-    try {
-        backupTool(ctx, 'age', ['-d', '-i', identity, '-o', path.join(scratch, 'backup.tar'), archive]);
-        const listed = String(backupTool(ctx, 'tar', ['-tf', 'backup.tar'], { cwd: scratch }).stdout ?? '').split(/\r?\n/u).map((line) => line.replace(/^\.\//u, '').trim());
-        const missing = parts.filter((part) => !listed.includes(part));
-        if (missing.length > 0)
-            throw new Error(`the decrypted archive lacks ${missing.join(', ')}`);
-        return { parts: listed.filter(Boolean) };
-    }
-    finally {
-        fs.rmSync(scratch, { recursive: true, force: true });
-    }
-}
-async function defaultMigrate(ctx, { target, execute }) {
-    const { loadDatabase, migrateDatabase } = await import('../db/migrate.mjs');
-    // The urgent deploy's --execute is the arming of this one migration: the floor runs it, it never waits for a second switch.
-    const armed = Object.create(ctx, { env: { value: { ...ctx.env, STARCI_DB_ARMED: '1' } } });
-    return migrateDatabase(armed, loadDatabase(ctx.cwd), { ...target, execute });
-}
-/** 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 } });
 /** Problems of the backup receipt against its archive: written by this run, a full backup, its size, age header and sha256 equal to the file's. */
 function receiptProblems(receipt, archive, startedMs, sha256) {
-    const problems = [];
-    if (!receipt || typeof receipt !== 'object')
-        return ['no receipt'];
-    if (receipt.schemaOnly !== false)
-        problems.push('the backup is not a full (data) backup');
-    if (!Number.isFinite(Date.parse(receipt.at)) || Date.parse(receipt.at) < startedMs - 1000)
-        problems.push('the receipt is not from this run');
-    if (!fs.existsSync(archive))
-        return [...problems, 'the archive is missing'];
-    const size = fs.statSync(archive).size;
-    const header = Buffer.alloc(AGE_HEADER.length);
-    const fd = fs.openSync(archive, 'r');
-    try {
-        fs.readSync(fd, header, 0, header.length, 0);
-    }
-    finally {
-        fs.closeSync(fd);
-    }
-    if (header.toString('ascii') !== AGE_HEADER)
-        problems.push('the archive has no age header');
-    if (size !== receipt.bytes)
-        problems.push(`the archive is ${size} bytes, the receipt says ${receipt.bytes}`);
-    if (!SHA.test(String(receipt.sha256 ?? '')) || sha256(archive) !== receipt.sha256)
-        problems.push('the archive sha256 differs from the receipt');
-    return problems;
+    const facts = localFacts(archive);
+    return backupProblems(receipt, facts.exists ? { ...facts, sha256: sha256(archive) } : facts, startedMs);
 }
 /** What the floor needs before anything runs: the pushed urgent record, a declared database, the identity of the test decrypt, the full public verify. */
 function preconditions(ctx, config, options) {
@@ -135,7 +62,7 @@ function preconditions(ctx, config, options) {
     }
     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');
+        throw refusal('STACK_DEPLOY_BACKUP_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 };
 }
 /**
@@ -150,19 +77,19 @@ async function guard(ctx, config, options, { f, run, identity, lines }) {
         backup = await f.backup(ctx, { target, out: backupDir(config, options) });
     }
     catch (error) {
-        return refused(lines, 'STACK_URGENT_BACKUP_FAILED', `the fresh database backup failed (${reasonOf(error)}); nothing was migrated or deployed`);
+        return refused(lines, 'STACK_DEPLOY_BACKUP_FAILED', `the fresh database backup failed (${reasonOf(error)}); nothing was migrated or deployed`);
     }
     const archive = path.join(path.dirname(backup.receiptPath), backup.receipt?.file ?? '');
     const problems = receiptProblems(backup.receipt, archive, started, run.sha256);
     if (problems.length > 0)
-        return refused(lines, 'STACK_URGENT_BACKUP_UNVERIFIED', `${problems.join('; ')}; nothing was migrated or deployed`);
+        return refused(lines, 'STACK_DEPLOY_BACKUP_UNVERIFIED', `${problems.join('; ')}; nothing was migrated or deployed`);
     const receipt = backup.receipt; // receiptProblems reports 'no receipt' when it is absent
     lines.push(`floor: backup ${path.basename(archive)} (${receipt.bytes} bytes, sha256 ${receipt.sha256.slice(0, 12)}) receipt ${backup.receiptPath}`);
     try {
         await f.decrypt(ctx, { archive, identity, parts: receipt.parts });
     }
     catch (error) {
-        return refused(lines, 'STACK_URGENT_DECRYPT_FAILED', `the test decrypt of the backup failed (${reasonOf(error)}); nothing was migrated or deployed`);
+        return refused(lines, 'STACK_DEPLOY_BACKUP_DECRYPT_FAILED', `the test decrypt of the backup failed (${reasonOf(error)}); nothing was migrated or deployed`);
     }
     lines.push(`floor: test decrypt listed ${receipt.parts.length} part(s)`);
     const { releaseId } = await run.render();
@@ -179,7 +106,7 @@ async function guard(ctx, config, options, { f, run, identity, lines }) {
     }
     lines.push(...(preview.lines ?? []).map((line) => `floor: migrate preview: ${line}`));
     if (!preview.ok)
-        return refused(lines, 'STACK_URGENT_MIGRATE_PREVIEW_RED', 'the migration preview is red; nothing was migrated or deployed');
+        return refused(lines, 'STACK_DEPLOY_MIGRATE_PREVIEW_RED', 'the migration preview is red; nothing was migrated or deployed');
     let applied;
     try {
         applied = await f.migrate(ctx, { target, execute: true });
@@ -189,42 +116,19 @@ async function guard(ctx, config, options, { f, run, identity, lines }) {
     }
     lines.push(...(applied.lines ?? []).map((line) => `floor: migrate: ${line}`));
     if (!applied.ok)
-        return refused(lines, 'STACK_URGENT_MIGRATE_FAILED', `the migration failed; nothing was deployed (restore from ${backup.receiptPath} if the database is half migrated)`);
+        return refused(lines, 'STACK_DEPLOY_MIGRATE_FAILED', `the migration failed; nothing was deployed (restore from ${backup.receiptPath} if the database is half migrated)`);
     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.
+ * The `first-start` step of an urgent first start (between the hold deploy and the real one): the shared step (db-phases.mjs) against the database
+ * the operator's --db-url-env names, reached inside its container. 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 }); // preconditions required --db-service
-    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)`,
-                // A first start that migrated and then rolled back leaves exactly this: a migrated volume and no serving release.
-                `if an earlier first start migrated this volume and then rolled back, and the owner confirms it holds no data, remove that volume (docker volume rm on the server) and run the first start again`,
-            ] };
-    }
-    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: [messageOf(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 };
+function firstStartStep(ctx, config, options, f) {
+    return sharedFirstStartStep(ctx, config, {
+        service: options.dbService, // preconditions required --db-service
+        targetFor: (container) => inContainer(dbTarget(ctx, options.dbUrlEnv ?? DEFAULT_DB_URL_ENV), container),
+        hint: 'a database with data takes the plain urgent floor (backup first)',
+    }, f);
 }
 /**
  * A first start: the rollback target, then the deploy whose `first-start` step bootstraps and migrates the empty database. Returns the dry-run
@@ -262,6 +166,7 @@ async function firstStartDeploy(ctx, config, options, run, f, lines) {
 export async function urgentDeploy(ctx, config, options, run, deps = {}) {
     const f = { ...FLOOR_DEPS, ...deps };
     const { record, identity } = preconditions(ctx, config, options);
+    run.note?.(record);
     const lines = [`urgent         ${record.tag} (${options.sourceSha.slice(0, 10)}) by ${record.role}: ${record.reason}`];
     let deployed;
     if (options.firstStart === true) {