@starci/hfs 4.11.21 → 4.12.0

package/stack/deploy.mjs

@@ -1,10 +1,19 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
 // deploy.mjs - the whole release (deployRelease) and the redeploy of a stored release (rollbackRelease).
 // 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 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`) proves the database empty and migrates it inside its own container, a `first-start` step between edge and converge.
+// 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.
 //
 // `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):
@@ -26,201 +35,222 @@ import { parseYaml } from '../runtime/engine/yaml.mjs';
 import { createReleaseStore } from './release-store.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`. */
-export const importModule = (file) => import(file);
-
+// reason: a dynamic import by string; the module's shape is known only to its caller (`lazy`)
+export const importModule = (file) => import(__rewriteRelativeImportExtension(file));
 /** A function that imports `file` on first call and forwards its arguments to the export `name`. */
 export const lazy = (file, name) => async (...args) => (await importModule(file))[name](...args);
-
 export const DEFAULT_DEPS = Object.freeze({
-  renderRelease: lazy('./render.mjs', 'renderRelease'),
-  provisionRelease: lazy('./provision.mjs', 'provisionRelease'),
-  convergeStack,
-  reconcileEdge: reconcileEdgeAliases,
-  postDeployStack,
-  verifyStack,
-  pruneStack,
-  releaseStore: createReleaseStore,
-  ssh: lazy('./remote.mjs', 'ownerSshRunner'),
-  floor: {},
+    renderRelease: lazy('./render.mjs', 'renderRelease'),
+    provisionRelease: lazy('./provision.mjs', 'provisionRelease'),
+    convergeStack,
+    reconcileEdge: reconcileEdgeAliases,
+    postDeployStack,
+    verifyStack,
+    pruneStack,
+    releaseStore: createReleaseStore,
+    ssh: lazy('./remote.mjs', 'ownerSshRunner'),
+    floor: {},
 });
-
 const fileSha256 = (file) => createHash('sha256').update(fs.readFileSync(file)).digest('hex');
-
 const IMAGE_LINE = /^[ \t]+image:[ \t]*(\S+)[ \t]*$/gmu;
 const QUOTE = /^["']|["']$/gu;
 const IMAGE_REF = /^[A-Za-z0-9][A-Za-z0-9./_:@-]*$/u;
-
 /** Every network alias the services of a rendered stack claim: [{ service, alias }]. */
 function stackAliases(bytes) {
-  const services = parseYaml(bytes)?.services ?? {};
-  return Object.entries(services).flatMap(([service, entry]) => Object.values(entry?.networks ?? {}).flatMap((network) => (network?.aliases ?? []).map((alias) => ({ service, alias }))));
+    // reason: the rendered stack, parsed YAML read defensively
+    const services = parseYaml(bytes)?.services ?? {};
+    return Object.entries(services).flatMap(([service, entry]) => Object.values(entry?.networks ?? {}).flatMap((network) => (network?.aliases ?? []).map((alias) => ({ service, alias }))));
 }
-
 /**
  * A swarm service must never claim an alias that a live (compose) upstream of the declared ingress still answers to: on the shared overlay both would
  * share the name and the old route would round-robin into the new service BEFORE the routes are published. Refused before anything is changed.
  */
 function refuseSharedAliases(config, bytes) {
-  const live = new Map((config.ingress?.upstreams ?? []).filter((upstream) => upstream.container !== null).flatMap((upstream) => upstream.aliases.map((alias) => [alias, upstream.name])));
-  const clash = stackAliases(bytes).find(({ alias }) => live.has(alias));
-  if (clash) throw refusal('STACK_DEPLOY_ALIAS_SHARED', `service ${clash.service} claims the network alias ${clash.alias}, which the live upstream ${live.get(clash.alias)} of deploy.ingress.upstreams still answers to: give the swarm service its own alias (for example ${clash.alias}-swarm) and point the published routes at it; nothing was changed`);
+    const live = new Map((config.ingress?.upstreams ?? []).filter((upstream) => upstream.container !== null).flatMap((upstream) => upstream.aliases.map((alias) => [alias, upstream.name])));
+    const clash = stackAliases(bytes).find(({ alias }) => live.has(alias));
+    if (clash)
+        throw refusal('STACK_DEPLOY_ALIAS_SHARED', `service ${clash.service} claims the network alias ${clash.alias}, which the live upstream ${live.get(clash.alias)} of deploy.ingress.upstreams still answers to: give the swarm service its own alias (for example ${clash.alias}-swarm) and point the published routes at it; nothing was changed`);
 }
-
 /**
  * Read-only preflight on the live edge networks: the implicit short name of a service (`api` for shop_api) must not equal a name another container or
  * service of the same external network resolves (docker stack deploy adds it as an alias, and the other tenant's `http://api` would reach this stack).
  */
 async function refuseEdgeCollisions(run, config, bytes) {
-  const { clashes } = await edgeCollisions(run, config, bytes);
-  if (clashes.length > 0) throw refusal('STACK_DEPLOY_ALIAS_SHARED', describeClash(clashes[0]));
+    const { clashes } = await edgeCollisions(run, config, bytes);
+    const [first] = clashes;
+    if (first)
+        throw refusal('STACK_DEPLOY_ALIAS_SHARED', describeClash(first));
 }
-
 /** The release id (first 16 hex of the sha256 of the rendered stack bytes) and the distinct images of a rendered release. */
 function inspectRendered(out, config) {
-  const bytes = fs.readFileSync(path.join(out, 'stack.yaml'), 'utf8');
-  refuseSharedAliases(config, bytes);
-  if (hasPlaceholderDigest(bytes)) throw refusal('STACK_DEPLOY_PLACEHOLDER', 'the rendered stack still carries a placeholder digest; nothing was changed');
-  const images = [...new Set([...bytes.matchAll(IMAGE_LINE)].map((match) => match[1].replaceAll(QUOTE, '')))];
-  const unsafe = images.find((image) => !IMAGE_REF.test(image));
-  if (unsafe) throw refusal('STACK_DEPLOY_IMAGE', `the rendered stack names an image that is not a plain reference (${unsafe}); nothing was changed`);
-  return { releaseId: createHash('sha256').update(bytes).digest('hex').slice(0, 16), images, bytes };
+    const bytes = fs.readFileSync(path.join(out, 'stack.yaml'), 'utf8');
+    refuseSharedAliases(config, bytes);
+    if (hasPlaceholderDigest(bytes))
+        throw refusal('STACK_DEPLOY_PLACEHOLDER', 'the rendered stack still carries a placeholder digest; nothing was changed');
+    const images = [...new Set([...bytes.matchAll(IMAGE_LINE)].map((match) => match[1].replaceAll(QUOTE, '')))];
+    const unsafe = images.find((image) => !IMAGE_REF.test(image));
+    if (unsafe)
+        throw refusal('STACK_DEPLOY_IMAGE', `the rendered stack names an image that is not a plain reference (${unsafe}); nothing was changed`);
+    return { releaseId: createHash('sha256').update(bytes).digest('hex').slice(0, 16), images, bytes };
 }
-
 function renderOptions(options, out, previous) {
-  return { images: options.images ?? {}, sourceSha: options.sourceSha, previous, out, allowUnpinned: false, extraCompose: [] };
+    return { images: options.images ?? {}, sourceSha: options.sourceSha, previous, out, allowUnpinned: false, extraCompose: [] };
 }
-
 /** A step that returns { ok, lines } whatever happens: an exception becomes a failed step (used once the services may have changed). */
 async function attempt(action) {
-  try {
-    return await action();
-  } catch (error) {
-    return { ok: false, lines: [String(error.message)] };
-  }
+    try {
+        return await action();
+    }
+    catch (error) {
+        return { ok: false, lines: [String(error.message)] };
+    }
 }
-
-/** `docker stack deploy` of a stored or rendered file. */
-function stackDeploy(ctx, config, file) {
-  const run = tool(ctx, 'docker', ['stack', 'deploy', '--prune', '--with-registry-auth', '--resolve-image', 'always', '--detach=true', '-c', file, config.stack]);
-  if (run.status !== 0) return { ok: false, lines: [`docker stack deploy failed: ${firstLine(run.stderr)}`] };
-  return { ok: true, lines: [`deploy: requested ${config.stack} from ${path.basename(path.dirname(file))}/${path.basename(file)}`] };
+/** `docker stack deploy` of a stored or rendered file (`overrides`: compose files merged over it, in order). */
+function stackDeploy(ctx, config, file, overrides = []) {
+    const files = [file, ...overrides].flatMap((one) => ['-c', one]);
+    const run = tool(ctx, 'docker', ['stack', 'deploy', '--prune', '--with-registry-auth', '--resolve-image', 'always', '--detach=true', ...files, config.stack]);
+    if (run.status !== 0)
+        return { ok: false, lines: [`docker stack deploy failed: ${firstLine(run.stderr)}`] };
+    return { ok: true, lines: [`deploy: requested ${config.stack} from ${path.basename(path.dirname(file))}/${path.basename(file)}`] };
+}
+/** The node label no node carries: a global service constrained to it has no node to run on, so none of its tasks start. */
+const HOLD_LABEL = 'node.labels.starci-first-start-hold == 1';
+/**
+ * The compose override of a first start's hold deploy, written beside the stack: every service except the database at 0 replicas, a global-mode
+ * service (it has no replica count) constrained to a node label no node carries. Merged over the rendered stack by `docker stack deploy -c`, so the
+ * release's own bytes (and id) stay untouched and the real deploy that follows is the stored stack.yaml.
+ */
+function writeHoldOverride(config, out, database) {
+    // reason: the rendered stack, parsed YAML read defensively
+    const stack = parseYaml(fs.readFileSync(path.join(out, 'stack.yaml'), 'utf8'));
+    const services = stack?.services ?? {};
+    if (!Object.hasOwn(services, database))
+        throw refusal('STACK_FIRST_START_USAGE', `--db-service ${database} is not a service of the stack ${config.stack}; nothing was deployed`);
+    const held = Object.fromEntries(Object.entries(services).filter(([name]) => name !== database).map(([name, entry]) => [
+        name,
+        entry?.deploy?.mode === 'global' ? { deploy: { placement: { constraints: [HOLD_LABEL] } } } : { deploy: { replicas: 0 } },
+    ]));
+    const file = path.join(out, 'stack.first-start-hold.yaml');
+    fs.writeFileSync(file, `${JSON.stringify({ version: stack?.version ?? '3.8', services: held }, null, 2)}
+`);
+    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) {
-  const failed = await findInOrder(plan, async ([step, action]) => {
-    const result = await attempt(action);
-    lines.push(...result.lines);
-    steps.push({ step, ok: result.ok });
-    return !result.ok;
-  });
-  return failed ? failed[0] : '';
+    const failed = await findInOrder(plan, async ([step, action]) => {
+        const result = await attempt(action);
+        lines.push(...result.lines);
+        steps.push({ step, ok: result.ok });
+        return !result.ok;
+    });
+    return failed ? failed[0] : '';
 }
-
 const isoBefore = (ctx, seconds) => new Date(ctx.now() - seconds * 1000).toISOString();
-
 /** Opens the release store over the ssh runner of this invocation; the runner's cleanup is queued on `cleanups` (sealed session files). */
 async function openRunner(ctx, config, options, d, cleanups) {
-  const run = await d.ssh(ctx, config, { sshCmd: options.sshCmd ?? null });
-  cleanups.push(() => run.cleanup?.());
-  return run;
+    const run = await d.ssh(ctx, config, { sshCmd: options.sshCmd ?? null });
+    cleanups.push(() => run.cleanup?.());
+    return run;
 }
-
 const openStore = async (ctx, config, options, d, cleanups) => d.releaseStore(config, await openRunner(ctx, config, options, d, cleanups));
-
 /** 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) {
-  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);
-  lines.push(failed ? 'ROLLBACK DID NOT CONVERGE: follow the stack runbook, Rollback' : `rolled back to ${previous}`);
-  return { lines, ok: !failed };
+    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);
+    lines.push(failed ? 'ROLLBACK DID NOT CONVERGE: follow the stack runbook, Rollback' : `rolled back to ${previous}`);
+    return { lines, ok: !failed };
 }
-
 /** After the accept: prune with both release records (non-fatal) and drop dangling images (failure ignored). */
 async function housekeeping(ctx, config, d, store, { previous, out }, lines) {
-  const outcome = await attempt(async () => {
-    const keepFiles = [path.join(out, 'release.json')];
-    if (previous) {
-      await store.fetch(previous, path.join(out, 'previous'));
-      keepFiles.push(path.join(out, 'previous', 'release.json'));
-    }
-    return d.pruneStack(ctx, config, { keepFiles, execute: true });
-  });
-  lines.push(...outcome.lines);
-  if (!outcome.ok) lines.push('prune failed (non-fatal; superseded objects stay until the next release)');
-  tool(ctx, 'docker', ['image', 'prune', '-f']);
+    const outcome = await attempt(async () => {
+        const keepFiles = [path.join(out, 'release.json')];
+        if (previous) {
+            await store.fetch(previous, path.join(out, 'previous'));
+            keepFiles.push(path.join(out, 'previous', 'release.json'));
+        }
+        return d.pruneStack(ctx, config, { keepFiles, execute: true });
+    });
+    lines.push(...outcome.lines);
+    if (!outcome.ok)
+        lines.push('prune failed (non-fatal; superseded objects stay until the next release)');
+    tool(ctx, 'docker', ['image', 'prune', '-f']);
 }
-
 function prePull(ctx, images) {
-  const lines = [];
-  for (const image of images) {
-    const run = tool(ctx, 'docker', ['pull', '--quiet', image]);
-    if (run.status !== 0) throw failure('STACK_DEPLOY_PULL', `docker pull ${image} failed: ${firstLine(run.stderr)}`);
-    lines.push(`pulled ${image}`);
-  }
-  return lines;
+    const lines = [];
+    for (const image of images) {
+        const run = tool(ctx, 'docker', ['pull', '--quiet', image]);
+        if (run.status !== 0)
+            throw failure('STACK_DEPLOY_PULL', `docker pull ${image} failed: ${firstLine(run.stderr)}`);
+        lines.push(`pulled ${image}`);
+    }
+    return lines;
 }
-
+/** 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);
-  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') });
-  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 }] };
+    const run = await openRunner(ctx, config, options, d, cleanups);
+    const store = d.releaseStore(config, run);
+    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') });
+    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 }] };
 }
-
 async function deployExecute(ctx, config, options, d, out, cleanups) {
-  const prepared = await prepareRelease(ctx, config, options, d, out, cleanups);
-  const { releaseId, previous, store } = prepared;
-  const lines = [...prepared.lines];
-  const steps = [...prepared.stepsDone];
-  const data = { releaseId, previous: previous || null, steps, rolledBack: false };
-  if (!prepared.ok) return { ok: false, lines: [...lines, 'deploy not started; the services are untouched'], data };
-  const since = isoBefore(ctx, 60);
-  const { skipPublic } = options;
-  const failed = await runSteps([
-    ['deploy', () => stackDeploy(ctx, config, path.join(out, 'stack.yaml'))],
-    ['edge', async () => d.reconcileEdge(ctx, config, path.join(out, 'stack.yaml'))],
-    // The first start of a self-hosted database (urgent-floor.mjs): its schema is bootstrapped and migrated once the database runs, before the
-    // services that need it are waited for.
-    ...(options.firstStartStep ? [['first-start', options.firstStartStep]] : []),
-    ['converge', () => d.convergeStack(ctx, config, { since, timeoutSeconds: options.timeoutSeconds })],
-    ...(config.postDeploy.length > 0 ? [['post-deploy', () => d.postDeployStack(ctx, config)]] : []),
-    ['verify', () => d.verifyStack(ctx, config, { retrySeconds: options.retrySeconds, skipPublic: skipPublic === true, stackFile: path.join(out, 'stack.yaml') })],
-    ...(skipPublic ? [] : [['accept', async () => { await store.accept(releaseId); return { ok: true, lines: [`accepted release ${releaseId}`] }; }]]),
-  ], lines, steps);
-  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, then starci app stack accept --release ${releaseId} --execute`], data };
-  }
-  if (!failed) {
-    await housekeeping(ctx, config, d, store, { previous, out }, lines);
-    return { ok: true, lines: [...lines, `deployed release ${releaseId}`], data };
-  }
-  lines.push(`deploy failed at ${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);
-  data.rolledBack = back.ok;
-  return { ok: false, lines: [...lines, ...back.lines], data };
+    const prepared = await prepareRelease(ctx, config, options, d, out, cleanups);
+    const { releaseId, previous, store } = prepared;
+    const lines = [...prepared.lines];
+    const steps = [...prepared.stepsDone];
+    const data = { releaseId, previous: previous || null, steps, rolledBack: false };
+    if (!prepared.ok)
+        return { ok: false, lines: [...lines, 'deploy not started; the services are untouched'], data };
+    const since = isoBefore(ctx, 60);
+    const { skipPublic } = options;
+    const stackFile = path.join(out, 'stack.yaml');
+    // 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;
+    const failed = await runSteps([
+        ...(hold ? [['deploy-hold', () => stackDeploy(ctx, config, stackFile, [hold])]] : []),
+        ...(options.firstStartStep ? [['first-start', options.firstStartStep]] : []),
+        ['deploy', () => stackDeploy(ctx, config, stackFile)],
+        ['edge', async () => d.reconcileEdge(ctx, config, stackFile)],
+        ['converge', () => d.convergeStack(ctx, config, { since, timeoutSeconds: options.timeoutSeconds })],
+        ...(config.postDeploy.length > 0 ? [['post-deploy', () => d.postDeployStack(ctx, config)]] : []),
+        ['verify', () => d.verifyStack(ctx, config, { retrySeconds: options.retrySeconds, skipPublic: skipPublic === true, stackFile: path.join(out, 'stack.yaml') })],
+        ...(skipPublic ? [] : [['accept', async () => { await store.accept(releaseId); return { ok: true, lines: [`accepted release ${releaseId}`] }; }]]),
+    ], lines, steps);
+    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 };
+    }
+    if (!failed) {
+        await housekeeping(ctx, config, d, store, { previous, out }, lines);
+        return { ok: true, lines: [...lines, `deployed release ${releaseId}`], data };
+    }
+    lines.push(`deploy failed at ${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);
+    data.rolledBack = back.ok;
+    return { ok: false, lines: [...lines, ...back.lines], data };
 }
-
 /**
  * Deploys a release: `options` = { images, sourceSha, execute, out, timeoutSeconds, retrySeconds, skipPublic, sshCmd, urgent, dbUrlEnv, backupOut }.
  * skipPublic (the first deploy into a shared ingress, whose public routes exist only after `ingress publish`): the verification checks only what runs
@@ -228,99 +258,117 @@ async function deployExecute(ctx, config, options, d, out, cleanups) {
  * Returns { ok, lines, data: { releaseId, previous, steps: [{ step, ok }], rolledBack } }.
  */
 export async function deployRelease(ctx, config, options = {}, deps = {}) {
-  const d = { ...DEFAULT_DEPS, ...deps };
-  if (!options.sourceSha) throw refusal('STACK_DEPLOY_SOURCE_SHA', '--source-sha is required (the git commit being deployed)');
-  const made = options.out ? null : fs.mkdtempSync(path.join(os.tmpdir(), 'stack-release-'));
-  const out = options.out ?? made;
-  const cleanups = [];
-  try {
-    // The local render and its inspection: a release that cannot render is refused before anything remote happens.
-    const render = async () => {
-      const rendered = await d.renderRelease(ctx, config, renderOptions(options, out, null));
-      return { rendered, releaseId: inspectRendered(out, config).releaseId };
-    };
-    const dryRun = async () => {
-      const { rendered, releaseId } = await render();
-      const post = config.postDeploy.length > 0 ? ` post-deploy tasks (${config.postDeploy.join(', ')}),` : '';
-      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`;
-      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);
+    const d = { ...DEFAULT_DEPS, ...deps };
+    if (!hasSourceSha(options))
+        throw refusal('STACK_DEPLOY_SOURCE_SHA', '--sha is required (the git commit being deployed)');
+    const made = options.out ? null : fs.mkdtempSync(path.join(os.tmpdir(), 'stack-release-'));
+    const out = (options.out ?? made); // made exists whenever options.out is absent
+    const cleanups = [];
+    try {
+        // The local render and its inspection: a release that cannot render is refused before anything remote happens.
+        const render = async () => {
+            const rendered = await d.renderRelease(ctx, config, renderOptions(options, out, null));
+            return { rendered, releaseId: inspectRendered(out, config).releaseId };
+        };
+        const dryRun = async () => {
+            const { rendered, releaseId } = await render();
+            const post = config.postDeploy.length > 0 ? ` post-deploy tasks (${config.postDeploy.join(', ')}),` : '';
+            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`;
+            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)
+            return await dryRun();
+        await render();
+        return await deployExecute(ctx, config, options, d, out, cleanups);
+    }
+    finally {
+        cleanups.forEach((close) => close());
+        if (made)
+            fs.rmSync(made, { recursive: true, force: true });
     }
-    if (options.execute !== true) return await dryRun();
-    await render();
-    return await deployExecute(ctx, config, options, d, out, cleanups);
-  } finally {
-    cleanups.forEach((close) => close());
-    if (made) fs.rmSync(made, { recursive: true, force: true });
-  }
 }
-
 /**
  * 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.
  */
 export async function rollbackRelease(ctx, config, options = {}, deps = {}) {
-  const d = { ...DEFAULT_DEPS, ...deps };
-  const release = options.release ?? null;
-  if (release !== null && !isReleaseId(release)) 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');
-    if (options.execute !== true) return { ok: true, lines: [`dry run: would redeploy release ${target}`], data: { release: target, executed: false } };
-    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'stack-rollback-'));
-    const lines = [];
-    const steps = [];
-    const since = isoBefore(ctx, 30);
-    const failed = await runSteps([
-      ['fetch', async () => { await store.fetch(target, dir); return { ok: true, lines: [] }; }],
-      ['deploy', () => stackDeploy(ctx, config, path.join(dir, 'stack.yaml'))],
-      ['edge', async () => d.reconcileEdge(ctx, config, path.join(dir, 'stack.yaml'))],
-      ['converge', () => d.convergeStack(ctx, config, { since, timeoutSeconds: options.timeoutSeconds ?? 600 })],
-      ['verify', () => d.verifyStack(ctx, config, { retrySeconds: 180, stackFile: path.join(dir, '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 } };
-  } finally {
-    if (dir) fs.rmSync(dir, { recursive: true, force: true });
-    cleanups.forEach((close) => close());
-  }
+    const d = { ...DEFAULT_DEPS, ...deps };
+    const release = options.release ?? null;
+    if (release !== null && !isReleaseId(release))
+        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');
+        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 } };
+    }
+    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 }.
  */
 export async function acceptRelease(ctx, config, options = {}, deps = {}) {
-  const d = { ...DEFAULT_DEPS, ...deps };
-  const release = options.release ?? null;
-  if (!isReleaseId(release)) throw refusal('STACK_RELEASE_ID', 'accept needs --release <16 lowercase hex characters> (the id the deploy printed)');
-  const cleanups = [];
-  const store = await openStore(ctx, config, options, d, cleanups);
-  const out = fs.mkdtempSync(path.join(os.tmpdir(), 'stack-accept-'));
-  try {
-    try { await store.fetch(release, out); } catch { throw refusal('STACK_ACCEPT_UNKNOWN', `release ${release} has no stored record on the manager`); }
-    const previous = await store.current();
-    if (previous === release) 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 } };
-  } finally {
-    fs.rmSync(out, { recursive: true, force: true });
-    cleanups.forEach((close) => close());
-  }
+    const d = { ...DEFAULT_DEPS, ...deps };
+    const release = options.release ?? null;
+    if (!isReleaseId(release))
+        throw refusal('STACK_RELEASE_ID', 'accept needs --release <16 lowercase hex characters> (the id the deploy printed)');
+    const cleanups = [];
+    const store = await openStore(ctx, config, options, d, cleanups);
+    const out = fs.mkdtempSync(path.join(os.tmpdir(), 'stack-accept-'));
+    try {
+        try {
+            await store.fetch(release, out);
+        }
+        catch {
+            throw refusal('STACK_ACCEPT_UNKNOWN', `release ${release} has no stored record on the manager`);
+        }
+        const previous = await store.current();
+        if (previous === release)
+            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 } };
+    }
+    finally {
+        fs.rmSync(out, { recursive: true, force: true });
+        cleanups.forEach((close) => close());
+    }
 }

package/stack/digest.d.mts

@@ -0,0 +1,8 @@
+/** A release identifier: the first 16 hex characters of the release digest. */
+export declare const RELEASE_ID: RegExp;
+/** Detects an unreplaced image digest in an image reference or in rendered stack bytes. */
+export declare const hasPlaceholderDigest: (bytes: unknown) => boolean;
+/** True for a pinned image reference; `allowUnpinned` (a local throwaway swarm) still refuses the placeholder digest. */
+export declare const isImageReference: (value: unknown, allowUnpinned?: boolean) => boolean;
+/** True for 16 lowercase hex characters. */
+export declare const isReleaseId: (value: unknown) => value is string;