@starci/hfs 4.12.2 → 4.13.2

package/stack/deploy.mjs

@@ -10,10 +10,16 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // deploy: render, provision, store the release record, pre-pull, `docker stack deploy`, converge, post-deploy tasks (deploy.postDeploy, when declared), verify, accept, prune. A failure at or
 // 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 app that declares the `database:` block gets the database phases of db-phases.mjs in every deploy (owner approval 2026-10-31): migrate preview, a
+// verified backup only when something is pending, the expand migrations inside the database container before the stack deploy, the contract migrations
+// after accept, and an automatic first start when no release was ever accepted. An app without the block deploys exactly as before.
 // 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; its
 // first start (`firstStart`) deploys the stack with only the database running (the `deploy-hold` step), proves the database empty and migrates it inside its own
 // container (the `first-start` step), then deploys the real stack and converges.
+// Every execute run is one recorded ATTEMPT (journal.mjs): the deploy lock of the manager (shared with the owner's urgent deploy), the deploy journal written at
+// every phase boundary, the skip when the accepted release already runs this commit, and the live services snapshotted after converge, after a rollback and on accept
+// (status.mjs; `stack status` and `stack verify` judge them). Preflight also pulls the images of the rollback target, so a registry clean-up cannot strand a rollback.
 //
 // `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):
@@ -28,11 +34,16 @@ import { convergeStack } from './converge.mjs';
 import { describeClash, edgeCollisions, reconcileEdgeAliases } from './edge-alias.mjs';
 import { firstLine, tool } from './context.mjs';
 import { hasPlaceholderDigest, isReleaseId } from './digest.mjs';
+import { contractPhase, declaredDatabase, expandPhase, firstStartHooks, FLOOR_DEPS, unknownDatabaseService } from './db-phases.mjs';
 import { failure, refusal } from './errors.mjs';
+import { recordedAttempt } from './journal.mjs';
 import { postDeployStack } from './post-deploy.mjs';
 import { pruneStack } from './prune.mjs';
+import { compareWithRelease, observedServices, stackImages } from './status.mjs';
 import { parseYaml } from '../runtime/engine/yaml.mjs';
 import { createReleaseStore } from './release-store.mjs';
+import { contractFinding, enforceContractGuard } from './rollback-guard.mjs';
+import { gateIsOn } from './ssh-gate.mjs';
 import { urgentDeploy } from './urgent-floor.mjs';
 import { verifyStack } from './verify.mjs';
 /** Loads `file` (relative to this module). Split out so a spec can load a real sibling module through `lazy`. */
@@ -49,6 +60,7 @@ export const DEFAULT_DEPS = Object.freeze({
     verifyStack,
     pruneStack,
     releaseStore: createReleaseStore,
+    observedServices,
     ssh: lazy('./remote.mjs', 'ownerSshRunner'),
     floor: {},
 });
@@ -136,10 +148,10 @@ function writeHoldOverride(config, out, database) {
 `);
     return file;
 }
-/** Runs [name, action] steps in order until one fails; records { step, ok } and collects the lines. Returns the failed step name or ''. */
-async function runSteps(plan, lines, steps) {
+/** Runs [name, action] steps in order until one fails; records { step, ok } and collects the lines; each step is also a phase of the journal. Returns the failed step name or ''. */
+async function runSteps(plan, lines, steps, rec) {
     const failed = await findInOrder(plan, async ([step, action]) => {
-        const result = await attempt(action);
+        const result = await rec.phase(step, () => attempt(action), (done) => done.ok);
         lines.push(...result.lines);
         steps.push({ step, ok: result.ok });
         return !result.ok;
@@ -153,17 +165,17 @@ async function openRunner(ctx, config, options, d, cleanups) {
     cleanups.push(() => run.cleanup?.());
     return run;
 }
-const openStore = async (ctx, config, options, d, cleanups) => d.releaseStore(config, await openRunner(ctx, config, options, d, cleanups));
+const openStore = async (ctx, config, options, d, cleanups) => d.releaseStore(config, await openRunner(ctx, config, options, d, cleanups), { gated: gateIsOn(ctx.env) });
 /** Redeploys a stored release after a failed deploy: fetch, stack deploy, converge. Returns the lines to print. */
-async function redeployStored(ctx, config, d, store, previous, out, steps) {
+async function redeployStored(ctx, config, d, store, previous, out, steps, rec) {
     const dir = path.join(out, 'previous');
     const lines = [`ROLLING BACK to the previous accepted release ${previous}`];
     const failed = await runSteps([
         ['rollback-fetch', async () => { await store.fetch(previous, dir); return { ok: true, lines: [] }; }],
         ['rollback-deploy', () => stackDeploy(ctx, config, path.join(dir, 'stack.yaml'))],
         ['rollback-edge', async () => d.reconcileEdge(ctx, config, path.join(dir, 'stack.yaml'))],
-        ['rollback-converge', () => d.convergeStack(ctx, config, { since: isoBefore(ctx, 30), timeoutSeconds: 600 })],
-    ], lines, steps);
+        ['rollback-converge', async () => { const converged = await d.convergeStack(ctx, config, { since: isoBefore(ctx, 30), timeoutSeconds: 600 }); snapshot(ctx, config, d, rec, 'rollback'); return converged; }],
+    ], lines, steps, rec);
     lines.push(failed ? 'ROLLBACK DID NOT CONVERGE: follow the stack runbook, Rollback' : `rolled back to ${previous}`);
     return { lines, ok: !failed };
 }
@@ -192,28 +204,103 @@ function prePull(ctx, images) {
     }
     return lines;
 }
+/**
+ * Pulls the images of the rollback target (the release accepted at the start of the deploy) that the new release does not already name: a registry clean-up
+ * must not strand a rollback, so a target whose images no longer pull refuses the deploy before the services are touched.
+ */
+async function prePullRollbackTarget(ctx, store, previous, pulled) {
+    const target = await store.read(previous);
+    const images = [...new Set(Object.values(stackImages(target.stackYaml)))].filter((image) => IMAGE_REF.test(image) && !pulled.includes(image));
+    const lines = [];
+    for (const image of images) {
+        const run = tool(ctx, 'docker', ['pull', '--quiet', image]);
+        if (run.status !== 0)
+            throw failure('STACK_DEPLOY_ROLLBACK_PULL', `the rollback target ${previous} names ${image}, which no longer pulls (${firstLine(run.stderr)}): a failed deploy could not go back; nothing was changed`);
+        lines.push(`pulled ${image} (rollback target ${previous})`);
+    }
+    return lines;
+}
+/** The live services into the recorder under `moment`; null (and no snapshot) when docker cannot be asked: a snapshot never fails a deploy. */
+function snapshot(ctx, config, d, rec, moment) {
+    try {
+        const services = d.observedServices(ctx, config);
+        rec.snapshot(moment, services);
+        return services;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Accepts `releaseId`: stamps the services observed now into its release record (`observed.accept`, what `stack status` compares against), stores it
+ * again, and moves the pointers. Without a snapshot the release is accepted as before.
+ */
+async function acceptObserved(ctx, config, d, store, rec, { out, releaseId }) {
+    const services = snapshot(ctx, config, d, rec, 'accept');
+    if (services) {
+        try {
+            const file = path.join(out, 'release.json');
+            const record = JSON.parse(fs.readFileSync(file, 'utf8'));
+            fs.writeFileSync(file, `${JSON.stringify({ ...record, observed: { at: new Date(ctx.now()).toISOString(), accept: services } }, null, 2)}
+`);
+            await store.store(out, releaseId);
+        }
+        catch (error) {
+            rec.warnings.push(`journal: the observed services were not stored in the release record (${firstLine(error.message)})`);
+        }
+    }
+    await store.accept(releaseId);
+}
+/**
+ * The accepted release when it already runs this commit and its services still match it (nothing to deploy), else null. A same-commit release whose
+ * services drifted (Swarm rolled one back, a manual update) is deployed again; an unreadable swarm is deployed too.
+ */
+async function alreadyLive(ctx, config, d, store, sourceSha, lines) {
+    const current = await store.current();
+    if (!current)
+        return null;
+    try {
+        const stored = await store.read(current);
+        if (stored.release.sourceSha !== sourceSha)
+            return null;
+        const drift = compareWithRelease(stored, d.observedServices(ctx, config));
+        if (drift.length === 0)
+            return current;
+        lines.push(`release ${current} runs this commit, but ${drift.map((entry) => `${entry.service} (${entry.kind})`).join(', ')} differ: deploying again`);
+    }
+    catch {
+        lines.push(`release ${current} could not be compared with the live services: deploying`);
+    }
+    return null;
+}
 /** True when the deploy names the commit it deploys. */
 const hasSourceSha = (options) => Boolean(options.sourceSha);
 /** Everything before the stack deploy: any failure here leaves the services untouched. Returns { ok, lines, releaseId, images, previous }. */
-async function prepareRelease(ctx, config, options, d, out, cleanups) {
-    const run = await openRunner(ctx, config, options, d, cleanups);
-    const store = d.releaseStore(config, run);
+async function prepareRelease(ctx, config, options, d, out, seams) {
+    const { run, store, rec } = seams;
     const previous = await store.current();
-    const rendered = await d.renderRelease(ctx, config, renderOptions(options, out, previous || null));
-    const { releaseId, images, bytes } = inspectRendered(out, config);
-    await refuseEdgeCollisions(run, config, bytes);
-    const lines = [...(rendered.lines ?? [])];
-    const provisioned = await d.provisionRelease(ctx, config, { execute: true, out, releaseFile: path.join(out, 'release.json') });
+    rec.note({ previous: previous || null });
+    const prepared = await rec.phase('render', async () => {
+        const rendered = await d.renderRelease(ctx, config, renderOptions(options, out, previous || null));
+        const inspected = inspectRendered(out, config);
+        await refuseEdgeCollisions(run, config, inspected.bytes);
+        return { rendered, ...inspected };
+    });
+    const { releaseId, images } = prepared;
+    rec.note({ releaseId });
+    const lines = [...(prepared.rendered.lines ?? [])];
+    const provisioned = await rec.phase('provision', () => d.provisionRelease(ctx, config, { execute: true, out, releaseFile: path.join(out, 'release.json') }), (done) => done.ok !== false);
     lines.push(...(provisioned.lines ?? []));
     if (provisioned.ok === false)
-        return { ok: false, lines, releaseId, previous, store, stepsDone: [{ step: 'render', ok: true }, { step: 'provision', ok: false }] };
-    await store.store(out, releaseId);
-    lines.push(...prePull(ctx, images));
-    return { ok: true, lines, releaseId, previous, store, stepsDone: [{ step: 'render', ok: true }, { step: 'provision', ok: true }, { step: 'store', ok: true }, { step: 'pre-pull', ok: true }] };
+        return { ok: false, lines, releaseId, previous, stepsDone: [{ step: 'render', ok: true }, { step: 'provision', ok: false }] };
+    await rec.phase('store', () => store.store(out, releaseId));
+    lines.push(...await rec.phase('pre-pull', async () => [...prePull(ctx, images), ...(previous ? await prePullRollbackTarget(ctx, store, previous, images) : [])]));
+    return { ok: true, lines, releaseId, previous, stepsDone: [{ step: 'render', ok: true }, { step: 'provision', ok: true }, { step: 'store', ok: true }, { step: 'pre-pull', ok: true }] };
 }
-async function deployExecute(ctx, config, options, d, out, cleanups) {
-    const prepared = await prepareRelease(ctx, config, options, d, out, cleanups);
-    const { releaseId, previous, store } = prepared;
+async function deployExecute(ctx, config, options, d, out, seams) {
+    const { store, rec, run } = seams;
+    const prepared = await prepareRelease(ctx, config, options, d, out, seams);
+    const { releaseId, previous } = prepared;
     const lines = [...prepared.lines];
     const steps = [...prepared.stepsDone];
     const data = { releaseId, previous: previous || null, steps, rolledBack: false };
@@ -225,37 +312,76 @@ async function deployExecute(ctx, config, options, d, out, cleanups) {
     // The first start of a self-hosted database (urgent-floor.mjs): the services that need its schema must not start against an empty one (their
     // healthchecks fail and update_config rolls them back), so the stack is first deployed with only the database running, the schema is
     // bootstrapped and migrated, and then the real stack is deployed.
-    const hold = options.firstStartStep && options.firstStartDb ? writeHoldOverride(config, out, options.firstStartDb) : null;
+    // An app that declares the `database:` block migrates in every deploy (db-phases.mjs); with no accepted release the first start is chosen by itself.
+    const database = options.urgent === true ? null : await declaredDatabase(ctx, config);
+    const phase = database ? { ctx, config, database, f: { ...FLOOR_DEPS, ...d.floor }, run, dbUrlEnv: options.dbUrlEnv, backupOut: options.backupOut } : null;
+    const unknown = database ? unknownDatabaseService(config, database) : null;
+    if (unknown)
+        return { ok: false, refused: unknown, lines: [...lines, 'deploy not started; the services are untouched'], data: { ...data, refused: unknown.code } };
+    let first = options.firstStartStep && options.firstStartDb ? { step: options.firstStartStep, service: options.firstStartDb } : null;
+    let firstCode = null;
+    if (phase && !first && phase.database.target === 'stack' && !previous) {
+        const automatic = firstStartHooks(phase);
+        first = { service: automatic.service, step: async () => { const outcome = await automatic.step(); firstCode = outcome.code ?? null; return outcome; } };
+    }
+    if (phase && !first) {
+        const expanded = await rec.phase('migrate', () => expandPhase(phase), (done) => done.ok);
+        rec.note({ backup: expanded.record.backup, migrations: expanded.record.applied });
+        lines.push(...expanded.lines);
+        steps.push(...expanded.steps);
+        data.migrations = expanded.record;
+        if (!expanded.ok)
+            return { ok: false, refused: expanded.refused, lines: [...lines, 'deploy not started; the services are untouched'], data: { ...data, refused: expanded.refused?.code } };
+    }
+    const hold = first ? writeHoldOverride(config, out, first.service) : null;
     const failed = await runSteps([
         ...(hold ? [['deploy-hold', () => stackDeploy(ctx, config, stackFile, [hold])]] : []),
-        ...(options.firstStartStep ? [['first-start', options.firstStartStep]] : []),
+        ...(first ? [['first-start', first.step]] : []),
         ['deploy', () => stackDeploy(ctx, config, stackFile)],
         ['edge', async () => d.reconcileEdge(ctx, config, stackFile)],
-        ['converge', () => d.convergeStack(ctx, config, { since, timeoutSeconds: options.timeoutSeconds })],
+        ['converge', async () => { const converged = await d.convergeStack(ctx, config, { since, timeoutSeconds: options.timeoutSeconds }); snapshot(ctx, config, d, rec, 'converge'); return converged; }],
         ...(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') })],
-        ...(skipPublic ? [] : [['accept', async () => { await store.accept(releaseId); return { ok: true, lines: [`accepted release ${releaseId}`] }; }]]),
-    ], lines, steps);
+        ...(skipPublic ? [] : [['accept', async () => { await acceptObserved(ctx, config, d, store, rec, { out, releaseId }); return { ok: true, lines: [`accepted release ${releaseId}`] }; }]]),
+    ], lines, steps, rec);
     if (!failed && skipPublic) {
         data.pendingAccept = true;
-        return { ok: true, lines: [...lines, `deployed release ${releaseId}: converged and verified inside the stack; the public hosts were NOT checked and the release is NOT accepted yet`, `next: starci app stack ingress publish --env ${config.env} --execute, then starci app stack accept --env ${config.env} --release ${releaseId} --execute`], data };
+        return { ok: true, lines: [...lines, ...(phase && !first ? ['db: the contract migrations (if any) run when the release is accepted'] : []), `deployed release ${releaseId}: converged and verified inside the stack; the public hosts were NOT checked and the release is NOT accepted yet`, `next: starci app stack ingress publish --env ${config.env} --execute, then starci app stack accept --env ${config.env} --release ${releaseId} --execute`], data };
     }
     if (!failed) {
         await housekeeping(ctx, config, d, store, { previous, out }, lines);
+        // The contract migrations run only now, with the release accepted and serving: the previous release is no longer the one the stack runs.
+        const contract = phase && !first ? await rec.phase('contract', () => contractPhase(phase), (done) => done.ok) : null;
+        if (contract) {
+            lines.push(...contract.lines);
+            rec.note({ migrations: [...(data.migrations?.applied ?? []), ...contract.applied], contract: contract.applied });
+            steps.push({ step: 'contract', ok: contract.ok });
+            data.migrations = { ...data.migrations, contractApplied: contract.applied };
+        }
+        if (contract && !contract.ok)
+            return { ok: false, lines: [...lines, `release ${releaseId} is accepted and serving; its contract migration is red: the owner decides`], data: { ...data, accepted: true, contractFailed: true } };
         return { ok: true, lines: [...lines, `deployed release ${releaseId}`], data };
     }
     lines.push(`deploy failed at ${failed}`);
+    const migrations = data.migrations;
+    if (migrations?.applied?.length)
+        lines.push(`db: the ${migrations.applied.length} expand migration(s) this deploy applied stay (the previous release keeps working on the expanded schema; a rollback restores services, never data); the backup ${migrations.backup?.receiptPath ?? ''} is the way back for data`);
+    const stopped = firstCode ? { refused: { code: firstCode, message: 'the first start failed' } } : {};
     if (!previous)
-        return { ok: false, lines: [...lines, 'no previous accepted release; services were rolled back by update_config where they had a previous spec'], data };
-    const back = await redeployStored(ctx, config, d, store, previous, out, steps);
+        return { ok: false, lines: [...lines, 'no previous accepted release; services were rolled back by update_config where they had a previous spec'], data, ...stopped };
+    const back = await redeployStored(ctx, config, d, store, previous, out, steps, rec);
     data.rolledBack = back.ok;
-    return { ok: false, lines: [...lines, ...back.lines], data };
+    return { ok: false, lines: [...lines, ...back.lines], data, ...stopped };
 }
+/** What starts an attempt: the owner's urgent deploy, a CI run (`--ci-run`) or a manual dispatch. */
+const triggerOf = (options) => (options.urgent === true ? 'urgent' : options.ciRun ? 'ci' : 'dispatch');
 /**
- * Deploys a release: `options` = { images, sourceSha, execute, out, timeoutSeconds, retrySeconds, skipPublic, sshCmd, urgent, dbUrlEnv, backupOut }.
+ * Deploys a release: `options` = { images, sourceSha, execute, out, timeoutSeconds, retrySeconds, skipPublic, sshCmd, urgent, dbUrlEnv, backupOut, ciRun, redeploy }.
  * skipPublic (the first deploy into a shared ingress, whose public routes exist only after `ingress publish`): the verification checks only what runs
  * inside the stack, and the release stays PENDING (stored and deployed, pointer not moved) until `acceptRelease` has verified it in full.
- * Returns { ok, lines, data: { releaseId, previous, steps: [{ step, ok }], rolledBack } }.
+ * With `execute` the run is one recorded attempt under the deploy lock (journal.mjs); the accepted release that already runs this commit ends it green
+ * as `already-current` unless `redeploy` is set.
+ * Returns { ok, lines, data: { releaseId, previous, steps: [{ step, ok }], rolledBack, attempt } }.
  */
 export async function deployRelease(ctx, config, options = {}, deps = {}) {
     const d = { ...DEFAULT_DEPS, ...deps };
@@ -273,20 +399,44 @@ export async function deployRelease(ctx, config, options = {}, deps = {}) {
         const dryRun = async () => {
             const { rendered, releaseId } = await render();
             const post = config.postDeploy.length > 0 ? ` post-deploy tasks (${config.postDeploy.join(', ')}),` : '';
+            const database = options.urgent === true ? null : await declaredDatabase(ctx, config);
+            const databasePlan = database ? `; database (${database.target === 'stack' ? `inside the ${database.service} container, no URL held` : 'external, by --db-url-env'}): migrate preview, a verified backup only when a migration is pending, the expand migrations before the deploy, the contract migrations after the accept, and an automatic first start when no release was ever accepted` : '';
             const plan = options.skipPublic
-                ? `dry run: release ${releaseId} would be provisioned, stored, pre-pulled, deployed, converged,${post} and verified inside the stack (public hosts skipped); it would stay pending until ingress publish and stack accept`
-                : `dry run: release ${releaseId} would be provisioned, stored, pre-pulled, deployed, converged,${post} verified, accepted`;
+                ? `dry run: release ${releaseId} would be provisioned, stored, pre-pulled, deployed, converged,${post} and verified inside the stack (public hosts skipped); it would stay pending until ingress publish and stack accept${databasePlan}`
+                : `dry run: release ${releaseId} would be provisioned, stored, pre-pulled, deployed, converged,${post} verified, accepted${databasePlan}`;
             return { ok: true, lines: [...(rendered.lines ?? []), plan], data: { releaseId, steps: [{ step: 'render', ok: true }], executed: false } };
         };
-        if (options.urgent === true) {
-            return await urgentDeploy(ctx, config, options, {
-                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) {
+            if (options.urgent !== true)
+                return await dryRun();
+            const never = (what) => () => Promise.reject(new Error(`a dry run ${what}`));
+            return await urgentDeploy(ctx, config, options, { render, dryRun, openStore: never('opens no store'), deployExecute: never('deploys nothing'), sha256: fileSha256 }, d.floor);
         }
-        if (options.execute !== true)
-            return await dryRun();
-        await render();
-        return await deployExecute(ctx, config, options, d, out, cleanups);
+        if (options.urgent !== true)
+            await render();
+        const run = await openRunner(ctx, config, options, d, cleanups);
+        const store = d.releaseStore(config, run, { gated: gateIsOn(ctx.env) });
+        const meta = {
+            kind: 'deploy', trigger: triggerOf(options), sourceSha: options.sourceSha, ciRun: options.ciRun,
+            urgent: options.urgent === true ? { role: ctx.env.STARCI_ROLE ?? 'unknown', reason: options.reason ?? '' } : undefined,
+        };
+        return await recordedAttempt(ctx, config, store, meta, { waitSeconds: options.lockWaitSeconds }, async (rec) => {
+            const notes = [];
+            const current = options.redeploy === true ? null : await rec.phase('idempotence', () => alreadyLive(ctx, config, d, store, options.sourceSha, notes));
+            if (current) {
+                rec.note({ releaseId: current });
+                return { ok: true, lines: [`already current: release ${current} runs commit ${options.sourceSha.slice(0, 10)} and its services match it; nothing to deploy`], data: { releaseId: current, previous: null, steps: [], rolledBack: false, alreadyCurrent: true } };
+            }
+            const seams = { run, store, rec };
+            const done = options.urgent === true
+                ? await urgentDeploy(ctx, config, options, {
+                    render, dryRun, openStore: async () => store, sha256: fileSha256,
+                    deployExecute: (extra = {}) => deployExecute(ctx, config, { ...options, ...extra }, d, out, seams),
+                    note: (record) => rec.note({ urgent: record }),
+                }, d.floor)
+                : await deployExecute(ctx, config, options, d, out, seams);
+            return { ...done, lines: [...notes, ...done.lines] };
+        });
     }
     finally {
         cleanups.forEach((close) => close());
@@ -296,7 +446,7 @@ export async function deployRelease(ctx, config, options = {}, deps = {}) {
 }
 /**
  * Redeploys a stored release (default: the `previous` pointer): `options` = { release, execute, timeoutSeconds, sshCmd }.
- * `release` is read from `options` only and must be null or 16 lowercase hex.
+ * `release` is read from `options` only and must be null or 16 lowercase hex. With `execute` it is one recorded attempt under the deploy lock.
  */
 export async function rollbackRelease(ctx, config, options = {}, deps = {}) {
     const d = { ...DEFAULT_DEPS, ...deps };
@@ -305,38 +455,47 @@ export async function rollbackRelease(ctx, config, options = {}, deps = {}) {
         throw refusal('STACK_RELEASE_ID', 'the release must be 16 lowercase hex characters');
     const cleanups = [];
     const store = await openStore(ctx, config, options, d, cleanups);
-    let dir = null;
     try {
         const target = release ?? await store.previous();
         if (!target)
             throw refusal('STACK_ROLLBACK_NO_TARGET', 'no previous accepted release is recorded; name one with --release');
+        // A manual rollback to a release older than an applied contract migration is refused unless the owner acknowledges the data effect.
+        const notice = enforceContractGuard(contractFinding(await store.journals(), target), options.dataAcknowledged === true);
         if (options.execute !== true)
-            return { ok: true, lines: [`dry run: would redeploy release ${target}`], data: { release: target, executed: false } };
-        const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'stack-rollback-'));
-        dir = scratch;
-        const lines = [];
-        const steps = [];
-        const since = isoBefore(ctx, 30);
-        const failed = await runSteps([
-            ['fetch', async () => { await store.fetch(target, scratch); return { ok: true, lines: [] }; }],
-            ['deploy', () => stackDeploy(ctx, config, path.join(scratch, 'stack.yaml'))],
-            ['edge', async () => d.reconcileEdge(ctx, config, path.join(scratch, 'stack.yaml'))],
-            ['converge', () => d.convergeStack(ctx, config, { since, timeoutSeconds: options.timeoutSeconds ?? 600 })],
-            ['verify', () => d.verifyStack(ctx, config, { retrySeconds: 180, stackFile: path.join(scratch, 'stack.yaml') })],
-            ['accept', async () => { await store.accept(target); return { ok: true, lines: [] }; }],
-        ], lines, steps);
-        lines.push(failed ? `rollback to ${target} failed at ${failed}` : `rolled back to release ${target}; a rollback cannot undo data effects`);
-        return { ok: !failed, lines, data: { release: target, executed: true, steps } };
+            return { ok: true, lines: [...notice, `dry run: would redeploy release ${target}`], data: { release: target, executed: false } };
+        return await recordedAttempt(ctx, config, store, { kind: 'rollback', trigger: 'dispatch' }, { waitSeconds: options.lockWaitSeconds }, async (rec) => {
+            const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'stack-rollback-'));
+            try {
+                rec.note({ releaseId: target, previous: await store.current() || null });
+                const lines = [];
+                const steps = [];
+                const since = isoBefore(ctx, 30);
+                const stackFile = path.join(scratch, 'stack.yaml');
+                const failed = await runSteps([
+                    ['fetch', async () => { await store.fetch(target, scratch); return { ok: true, lines: [] }; }],
+                    ['deploy', () => stackDeploy(ctx, config, stackFile)],
+                    ['edge', async () => d.reconcileEdge(ctx, config, stackFile)],
+                    ['converge', async () => { const converged = await d.convergeStack(ctx, config, { since, timeoutSeconds: options.timeoutSeconds ?? 600 }); snapshot(ctx, config, d, rec, 'converge'); return converged; }],
+                    ['verify', () => d.verifyStack(ctx, config, { retrySeconds: 180, stackFile })],
+                    ['accept', async () => { await acceptObserved(ctx, config, d, store, rec, { out: scratch, releaseId: target }); return { ok: true, lines: [] }; }],
+                ], lines, steps, rec);
+                lines.unshift(...notice);
+                lines.push(failed ? `rollback to ${target} failed at ${failed}` : `rolled back to release ${target}; a rollback cannot undo data effects`);
+                return { ok: !failed, lines, data: { release: target, executed: true, steps } };
+            }
+            finally {
+                fs.rmSync(scratch, { recursive: true, force: true });
+            }
+        });
     }
     finally {
-        if (dir)
-            fs.rmSync(dir, { recursive: true, force: true });
         cleanups.forEach((close) => close());
     }
 }
 /**
  * Accepts a release that a `skipPublic` deploy left pending: the FULL verification (public hosts and checks inside the stack) must pass first, then the
- * pointer moves and the superseded secrets and configs are pruned. `options` = { release, execute, retrySeconds, sshCmd }.
+ * pointer moves and the superseded secrets and configs are pruned. `options` = { release, execute, retrySeconds, sshCmd }. With `execute` it is one recorded
+ * attempt under the deploy lock.
  */
 export async function acceptRelease(ctx, config, options = {}, deps = {}) {
     const d = { ...DEFAULT_DEPS, ...deps };
@@ -358,14 +517,25 @@ export async function acceptRelease(ctx, config, options = {}, deps = {}) {
             return { ok: true, lines: [`release ${release} is already the accepted release`], data: { release, accepted: true, executed: options.execute === true } };
         if (options.execute !== true)
             return { ok: true, lines: [`dry run: would run the full verification (public hosts and checks inside the stack) and then accept release ${release}`], data: { release, accepted: false, executed: false } };
-        const verified = await d.verifyStack(ctx, config, { retrySeconds: options.retrySeconds, stackFile: path.join(out, 'stack.yaml') });
-        const lines = [...(verified.lines ?? [])];
-        if (!verified.ok)
-            return { ok: false, lines: [...lines, `release ${release} is NOT accepted: the full verification failed`], data: { release, accepted: false, executed: true } };
-        await store.accept(release);
-        lines.push(`accepted release ${release}`);
-        await housekeeping(ctx, config, d, store, { previous: previous || null, out }, lines);
-        return { ok: true, lines, data: { release, accepted: true, executed: true } };
+        return await recordedAttempt(ctx, config, store, { kind: 'accept', trigger: 'dispatch' }, { waitSeconds: options.lockWaitSeconds }, async (rec) => {
+            rec.note({ releaseId: release, previous: previous || null });
+            const verified = await rec.phase('verify', () => d.verifyStack(ctx, config, { retrySeconds: options.retrySeconds, stackFile: path.join(out, 'stack.yaml') }), (done) => done.ok);
+            const lines = [...(verified.lines ?? [])];
+            if (!verified.ok)
+                return { ok: false, lines: [...lines, `release ${release} is NOT accepted: the full verification failed`], data: { release, accepted: false, executed: true } };
+            await rec.phase('accept', () => acceptObserved(ctx, config, d, store, rec, { out, releaseId: release }));
+            lines.push(`accepted release ${release}`);
+            await housekeeping(ctx, config, d, store, { previous: previous || null, out }, lines);
+            const database = await declaredDatabase(ctx, config);
+            const contract = database ? await rec.phase('contract', () => contractPhase({ ctx, config, database, f: { ...FLOOR_DEPS, ...d.floor }, run: null, dbUrlEnv: options.dbUrlEnv }), (done) => done.ok) : null;
+            if (contract) {
+                lines.push(...contract.lines);
+                rec.note({ migrations: contract.applied, contract: contract.applied });
+            }
+            if (contract && !contract.ok)
+                return { ok: false, lines: [...lines, `release ${release} is accepted and serving; its contract migration is red: the owner decides`], data: { release, accepted: true, executed: true, contractFailed: true } };
+            return { ok: true, lines, data: { release, accepted: true, executed: true, ...(contract ? { contractApplied: contract.applied } : {}) } };
+        });
     }
     finally {
         fs.rmSync(out, { recursive: true, force: true });

package/stack/journal.d.mts

@@ -0,0 +1,146 @@
+import type { DeployConfig } from './config.mjs';
+import type { StackContext } from './context.mjs';
+import type { LockTrigger, ReleaseStore } from './release-store.mjs';
+import type { ActionResult } from './remote.mjs';
+import type { ObservedService } from './status.mjs';
+/** What started the attempt: a CI run, a manual dispatch or the owner's urgent deploy. */
+export type Trigger = LockTrigger;
+/** What the attempt does. */
+export type AttemptKind = 'deploy' | 'rollback' | 'accept';
+/** How an attempt ended; `running` is the document of an attempt that has not finished (or was cancelled). */
+export type Outcome = 'running' | 'accepted' | 'pending' | 'rolled-back' | 'rollback-failed' | 'failed' | 'refused' | 'already-current';
+/** One phase of an attempt. */
+export interface PhaseRecord {
+    phase: string;
+    startedAt: string;
+    endedAt: string | null;
+    verdict: 'running' | 'ok' | 'failed';
+}
+/** The document of one attempt, as /srv/<stack>/deploys/<attempt>.json holds it. */
+export interface AttemptDocument {
+    schema: 'starci/stack-deploy-attempt@1';
+    attempt: string;
+    kind: AttemptKind;
+    stack: string;
+    env: string;
+    startedAt: string;
+    endedAt: string | null;
+    trigger: Trigger;
+    sourceSha: string | null;
+    /** The release tag when the attempt ran from a tag (GITHUB_REF_NAME of a tag run). */
+    tag: string | null;
+    /** The CI run: its id and, when the runner environment names the repository, its URL. */
+    ci: {
+        run: string;
+        url: string | null;
+    } | null;
+    /** The owner's urgent record: who and why (the reason is the owner's own text, bounded). */
+    urgent: {
+        role: string;
+        reason: string;
+        tag: string | null;
+    } | null;
+    releaseId: string | null;
+    previous: string | null;
+    phases: PhaseRecord[];
+    /** Reserved for the backup phase: its receipt (names and digests only). Null when no backup ran. */
+    backup: Record<string, unknown> | null;
+    /** Reserved for the migrate and contract phases: the names of the migrations that were applied. */
+    migrations: string[];
+    /** The contract migrations this attempt applied (the marker the manual rollback guard reads); empty when it applied none. */
+    contract: string[];
+    /** `docker service inspect` snapshots by moment: `converge`, `rollback`, `accept`. */
+    observed: Record<string, ObservedService[]>;
+    outcome: Outcome;
+    error: {
+        code: string;
+        message: string;
+    } | null;
+}
+/** The facts of a finished attempt that a notification carries: names, digests and codes, never a message text or a value. */
+export interface AttemptSummary {
+    attempt: string;
+    kind: AttemptKind;
+    stack: string;
+    env: string;
+    outcome: Outcome;
+    trigger: Trigger;
+    sourceSha: string | null;
+    tag: string | null;
+    releaseId: string | null;
+    ciUrl: string | null;
+    errorCode: string | null;
+}
+/** What an attempt is told about itself when it opens. */
+export interface AttemptMeta {
+    kind: AttemptKind;
+    trigger: Trigger;
+    sourceSha?: string | undefined;
+    /** The id of the CI run (digits); with it the trigger is `ci`. */
+    ciRun?: string | undefined;
+    urgent?: {
+        role: string;
+        reason: string;
+        tag?: string | undefined;
+    } | undefined;
+}
+/** The facts an attempt learns while it runs. */
+export interface Note {
+    releaseId?: string | null;
+    previous?: string | null;
+    backup?: Record<string, unknown> | null;
+    migrations?: string[];
+    contract?: string[];
+    urgent?: {
+        role: string;
+        reason: string;
+        tag?: string | undefined;
+    };
+}
+/** The open record of one attempt. */
+export interface Recorder {
+    readonly id: string;
+    /** Journal failures after the first write; the caller prints them. */
+    readonly warnings: string[];
+    note(facts: Note): void;
+    /** Registers what runs at the start of every later phase (the lock refresh). */
+    beforePhase(next: () => Promise<void>): void;
+    /** Runs `action` as the named phase: start and end are written; a throw is recorded as failed and rethrown. `passed` judges a returned value (default: ok). */
+    phase<T>(name: string, action: () => T | Promise<T>, passed?: (value: T) => boolean): Promise<T>;
+    snapshot(moment: string, services: ObservedService[]): void;
+    finish(outcome: Outcome, error?: {
+        code: string;
+        message: string;
+    } | null): Promise<void>;
+    /** The facts of the attempt as it stands (call after `finish` for a notification). */
+    summary(): AttemptSummary;
+}
+/** A new attempt id: the UTC time and 8 random hex characters. */
+export declare const newAttemptId: (ctx: Pick<StackContext, "now">) => string;
+/**
+ * Opens the journal of an attempt and returns its recorder. Writes the first document and the index line; a failure of either is the refusal
+ * `STACK_DEPLOY_JOURNAL` (the manager cannot keep a record, so nothing is changed).
+ */
+export declare function openAttempt(ctx: StackContext, config: DeployConfig, store: ReleaseStore, meta: AttemptMeta): Promise<Recorder>;
+/** What the lock wait takes. */
+export interface LockWait {
+    waitSeconds?: number | undefined;
+    pollSeconds?: number | undefined;
+}
+/** The default wait for a held deploy lock (the design's ten minutes). */
+export declare const LOCK_WAIT_SECONDS = 600;
+/** A taken lock: refresh keeps it alive, release gives it back. */
+export interface LockHold {
+    token: string;
+    refresh(): Promise<boolean>;
+    release(): Promise<boolean>;
+}
+/** Takes the deploy lock, waiting while another deploy holds it; `STACK_DEPLOY_LOCKED` when the wait ends. */
+export declare function holdLock(ctx: StackContext, store: ReleaseStore, trigger: Trigger, wait?: LockWait): Promise<LockHold>;
+/** How a finished result reads as an outcome. */
+export declare function outcomeOf(result: ActionResult, kind: AttemptKind): Outcome;
+/**
+ * Runs `body` as one recorded attempt under the deploy lock: journal opened, lock taken, `body(recorder)` run, outcome written, lock released. The result
+ * gains `data.attempt` (the attempt id) and the journal's warnings as lines; a throw is recorded as `refused` and rethrown.
+ */
+export declare function recordedAttempt(ctx: StackContext, config: DeployConfig, store: ReleaseStore, meta: AttemptMeta, wait: LockWait, body: (recorder: Recorder) => Promise<ActionResult>): Promise<ActionResult>;