@starci/hfs 4.12.2 → 4.13.2

package/stack/status.mjs

@@ -0,0 +1,115 @@
+// 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';
+import { gateIsOn } from './ssh-gate.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, { gated: gateIsOn(ctx.env) });
+        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) {

package/stack/verify.mjs

@@ -1,10 +1,12 @@
 // verify.mjs - functional verification after convergence: the declared HTTP journeys (config.verify.http) and the declared checks inside a
 // running task (config.verify.exec). Probes are bounded and read-only; a POST body comes only from the declared config and nothing here
 // mutates business data. HTTP goes through ctx.fetch, docker through ctx.spawn, waits through ctx.sleep and time through ctx.now.
+import fs from 'node:fs';
 import { isDeepStrictEqual } from 'node:util';
 import { eachInOrder, repeatInOrder } from '../runtime/scripts/lib/in-order.mjs';
 import { lines as splitLines, tool } from './context.mjs';
 import { edgeAttachmentsOf, verifyEdgeAttachment } from './edge-alias.mjs';
+import { compareWithRelease, digestOf, observedServices, stackImages } from './status.mjs';
 const RETRY_MS = 6000;
 const HTTP_TIMEOUT_MS = 8000;
 function expect(condition, message) {
@@ -87,6 +89,28 @@ async function verifyEdge(ctx, config, results, file) {
     }
     await eachInOrder(attachments, (item) => runCheck(ctx, results, `edge aliases of ${item.service} on ${item.network} are exactly the declared ones`, () => verifyEdgeAttachment(ctx, config, item)));
 }
+/**
+ * Drift: when the stack file pins its images by digest (a rendered release), every service it names runs exactly that digest and none was rolled back by
+ * Swarm, so a release that Swarm quietly reverted never reads as verified. A stack file without pinned images (the source) has nothing to compare.
+ */
+async function verifyDrift(ctx, config, results, file) {
+    let stackYaml;
+    try {
+        stackYaml = fs.readFileSync(file, 'utf8');
+        if (!Object.values(stackImages(stackYaml)).some((image) => digestOf(image) !== null))
+            return;
+    }
+    catch (error) {
+        results.push({ name: 'drift: the stack file is readable', ok: false, detail: String(error.message) });
+        return;
+    }
+    await runCheck(ctx, results, 'drift: the services run the digests of the stack file', () => {
+        const live = observedServices(ctx, config);
+        const drift = compareWithRelease({ stackYaml, release: {} }, live).filter((entry) => entry.kind !== 'not in the release');
+        expect(drift.length === 0, drift.map((entry) => `${entry.service}: ${entry.kind}`).join('; '));
+        return `${live.length} service(s)`;
+    });
+}
 const verifyExec = (ctx, config, results) => eachInOrder([...new Set(config.verify.exec.map((check) => check.service))], (service) => verifyService(ctx, config, results, service));
 /**
  * Runs the declared verification. Returns { ok, lines, data: { checks: [{ name, ok }] } }; the lines read `PASS|FAIL  name  detail`.
@@ -99,6 +123,8 @@ export async function verifyStack(ctx, config, { retrySeconds = 180, skipPublic
         await eachInOrder(config.verify.http, (check) => runCheck(ctx, results, check.name, () => probeHttp(ctx, check), { retry: check.retry, retrySeconds }));
     if (!skipInternal && stackFile)
         await verifyEdge(ctx, config, results, stackFile);
+    if (!skipInternal && stackFile)
+        await verifyDrift(ctx, config, results, stackFile);
     if (!skipInternal)
         await verifyExec(ctx, config, results);
     return {

package/sync/ci-commands.mjs

@@ -9,8 +9,10 @@ const exampleCommand = (source, command) => source?.runtimeExample
     : command;
 const UPLOAD_ARTIFACT = 'actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2';
 const DOWNLOAD_ARTIFACT = 'actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0';
-const SONAR_CONDITION = "${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') }}";
-/** Codecov uploads on release tags with its required authentication; a missing report, an unavailable endpoint or a rejected upload fails the job. */
+// Sonar and the Codecov upload run on every full run (a release tag or a candidate), so a release is analysed before it ships; the plan job decides.
+const FULL_RUN = "needs.plan.outputs.full == 'true'";
+const SONAR_CONDITION = `\${{ !cancelled() && ${FULL_RUN} }}`;
+/** Codecov uploads on every full run with its required authentication; a missing report, an unavailable endpoint or a rejected upload fails the job. */
 function codecovSteps(lcovReport, codecov) {
     if (codecov.enabled === false || codecov.wiring === 'not-used')
         return [
@@ -20,7 +22,7 @@ function codecovSteps(lcovReport, codecov) {
     return [
         '      - name: coverage upload',
         '        uses: codecov/codecov-action@0fb7174895f61a3b6b78fc075e0cd60383518dac # v5.5.5',
-        "        if: ${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') }}",
+        `        if: ${SONAR_CONDITION}`,
         '        with:',
         codecov.auth === 'token' ? `          token: \${{ secrets.${codecov.token} }}` : '          use_oidc: true',
         `          files: ${lcovReport}`,
@@ -28,7 +30,7 @@ function codecovSteps(lcovReport, codecov) {
         '          fail_ci_if_error: true',
     ].join('\n');
 }
-/** Sonar is required: on release tags it consumes the test coverage and lint artifacts, and a missing token fails the job with a clear refusal. */
+/** Sonar is required: on every full run it consumes the test coverage and lint artifacts, and a missing token fails the job with a clear refusal. */
 function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, timeout) {
     if (!sonar)
         return '';
@@ -36,7 +38,8 @@ function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, timeout) {
     const host = sonar.provider === 'sonarcloud' ? 'https://sonarcloud.io' : `\${{ vars.${sonar.hostVar} }}`;
     const header = [
         '  sonar:',
-        '    needs: [lint, coverage]',
+        '    needs: [plan, lint, coverage]',
+        `    if: \${{ ${FULL_RUN} }}`,
         `    timeout-minutes: ${timeout}`,
         '    runs-on: ubuntu-latest',
         '    env:',
@@ -219,6 +222,8 @@ export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info',
             `          NODE_OPTIONS: ${settings.nodeOptions}`,
         ]).join('\n'),
         codecovSteps: codecovSteps(lcovReport, codecov),
+        verdictSonarNeed: sonar ? ', sonar' : '',
+        verdictSonarCheck: sonar ? `\n          if [[ "$FULL" == true && "$CHECKS" == true ]]; then expect sonar success; else expect sonar idle; fi` : '',
         sonarJob: sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, settings.timeoutSonar),
         lcovArtifact,
     };

package/sync/format-worker.d.mts

@@ -0,0 +1 @@
+export {};

package/sync/format-worker.mjs

@@ -0,0 +1,17 @@
+// format-worker.mts - a worker thread of sync/format.mts: loads the repository's own prettier once and checks the batches it is sent.
+import { parentPort } from 'node:worker_threads';
+import { checkBatch, loadPrettier } from './format.mjs';
+let loaded;
+parentPort?.on('message', (message) => {
+    void (async () => {
+        try {
+            if (loaded?.repoRoot !== message.repoRoot)
+                loaded = { repoRoot: message.repoRoot, prettier: loadPrettier(message.repoRoot) };
+            const findings = await checkBatch({ repoRoot: message.repoRoot, files: message.files, prettier: loaded.prettier });
+            parentPort?.postMessage({ findings, count: message.files.length });
+        }
+        catch (error) {
+            parentPort?.postMessage({ error: String(error.message ?? error), code: error.code });
+        }
+    })();
+});

package/sync/format.d.mts

@@ -27,12 +27,30 @@ export type FormatFinding = {
 };
 /** The repository's own prettier, or a SyncError when it is not installed. */
 export declare function loadPrettier(repoRoot: string): Prettier;
+/** Files per batch: one message to a worker, one progress step. */
+export declare const FORMAT_BATCH = 64;
+/** The formattable files of `files`: lockfiles are written by npm and never formatted. */
+export declare const formattable: (files: readonly string[]) => string[];
 /**
- * The HFS_FORMAT findings over the tracked `files` of `repoRoot`: one per file prettier would change, or cannot parse.
- * `prettier` is a seam for specs; the default is the repository's own.
+ * The HFS_FORMAT findings of one batch of `files`, in this thread. The ignore file is read by prettier once per call and the configuration is
+ * resolved with prettier's own cache, so a batch costs one lookup per directory.
  */
-export declare function formatFindings({ repoRoot, files, prettier }: {
+export declare function checkBatch({ repoRoot, files, prettier }: {
+    repoRoot: string;
+    files: readonly string[];
+    prettier: Prettier;
+}): Promise<FormatFinding[]>;
+/** Cuts `files` into batches of `size`. */
+export declare function batches<T>(files: readonly T[], size?: number): T[][];
+/** How many worker threads a list of `count` files gets: none below WORKER_MIN_FILES, else up to the cores left over, at most 8. */
+export declare function workerCount(count: number, cores?: number): number;
+/**
+ * The HFS_FORMAT findings over the tracked `files` of `repoRoot`: one per file prettier would change, or cannot parse, sorted by path.
+ * `prettier` is a seam for specs (and keeps the run in this thread); the default is the repository's own, in worker threads for a long list.
+ */
+export declare function formatFindings({ repoRoot, files, prettier, onProgress }: {
     repoRoot: string;
     files: readonly string[];
     prettier?: Prettier | undefined;
+    onProgress?: ((done: number) => void) | undefined;
 }): Promise<FormatFinding[]>;