spawnfile 0.1.14 → 0.1.18

package/dist/distribution/consumeImage.js

@@ -1,10 +1,12 @@
 import os from "node:os";
 import path from "node:path";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
-import { acquireHomeDeploymentLock, createDockerDeploymentLabels, homeDeploymentExists, normalizeDeploymentName, readHomeDeploymentRecord, resolveDockerDeploymentTarget, verifyDockerDeploymentTarget, writeHomeDeployment } from "../deployment/index.js";
+import { acquireHomeDeploymentLock, activationBeforeStart, captureCandidateDiagnostics, createDockerDeploymentLabels, listHomeDeploymentRecords, HomeDeploymentRecordingError, normalizeDeploymentName, sanitizeCandidateDiagnostic, recordDeploymentRollback, resolveHomeRecordPath, writeHomeDeployment } from "../deployment/index.js";
 import { SpawnfileError } from "../shared/index.js";
-import { deriveDeploymentName, deriveVolumeName, renderEnvFileContent, resolveImageEnvironment } from "./consumeImageSupport.js";
+import { readPreviousSource, resolveExistingOrNewTarget, deriveDeploymentName, derivePersistentMountVolumeName, renderEnvFileContent, resolveImageEnvironment } from "./consumeImageSupport.js";
+import { acquireExclusiveVolumeReservations, assertCandidateContainerReady, assertContainerStopped, inspectContainerSnapshot, restorePreviousContainer, rollbackCandidateContainer } from "./consumeImageLifecycle.js";
 import { createConsumerDockerRunner } from "./dockerRunner.js";
+import { resolveDaimonDockerSecurityArgsForImage } from "./consumeImageDaimonDocker.js";
 import { extractImageReport, resolveDockerBaseArgs } from "./extractImage.js";
 import { parseImageReference } from "./imageRef.js";
 import { prepareImageRuntimeAuthMounts } from "./imageRuntimeAuth.js";
@@ -35,15 +37,6 @@ const resolveRegistryDigest = async (imageRef, runDocker) => {
         return null;
     }
 };
-const containerExists = async (runDocker, containerName) => {
-    try {
-        await runDocker(["container", "inspect", containerName]);
-        return true;
-    }
-    catch {
-        return false;
-    }
-};
 const resolveLocalImageId = async (imageRef, runDocker) => {
     try {
         const raw = (await runDocker([
@@ -74,7 +67,9 @@ export const consumeImageUp = async (imageRef, options = {}) => {
     const isExplicitName = Boolean(options.deploymentName);
     // Hold an exclusive lock for the whole operation so a concurrent `up` for the
     // same deployment cannot race on the record or orphan a container.
-    const releaseLock = await acquireHomeDeploymentLock(deploymentName);
+    const releaseLock = options.deploymentLockHeld
+        ? async () => undefined
+        : await acquireHomeDeploymentLock(deploymentName);
     try {
         return await consumeImageUpLocked(imageRef, parsedRef, deploymentName, isExplicitName, options);
     }
@@ -84,7 +79,8 @@ export const consumeImageUp = async (imageRef, options = {}) => {
 };
 const consumeImageUpLocked = async (imageRef, parsedRef, deploymentName, isExplicitName, options) => {
     void parsedRef;
-    const alreadyExists = await homeDeploymentExists(deploymentName);
+    const previousRecord = (await listHomeDeploymentRecords()).find((entry) => entry.record.name === deploymentName)?.record;
+    const alreadyExists = previousRecord !== undefined;
     if (alreadyExists && !isExplicitName) {
         throw new SpawnfileError("validation_error", `Deployment "${deploymentName}" already exists (derived from image ${imageRef}). ` +
             `To redeploy it, re-run with --deployment ${deploymentName}; ` +
@@ -131,6 +127,7 @@ const consumeImageUpLocked = async (imageRef, parsedRef, deploymentName, isExpli
     // port for two containers at once. There is a brief restart gap, unavoidable
     // when reusing host ports without a proxy.
     const backupName = `${containerName}-previous-${Date.now().toString(36)}`;
+    let volumeReservation;
     try {
         await writeFile(envFilePath, renderEnvFileContent(env), "utf8");
         // Prepare import-based model auth (the consumer's Claude/Codex login) and
@@ -138,24 +135,45 @@ const consumeImageUpLocked = async (imageRef, parsedRef, deploymentName, isExpli
         // config is already baked into the image; this only resolves the credential
         // mounts. Doing it first guarantees an unusable import fails while the live
         // container is still untouched, never mid-swap.
-        const authMountArgs = options.authProfile && availableImports.length > 0
-            ? (await prepareImageRuntimeAuthMounts({
-                authProfile: options.authProfile,
-                report,
-                tempRoot: workDir
-            })).mountArgs
-            : [];
-        const liveExists = await containerExists(runDocker, containerName);
-        if (liveExists) {
+        const authMountArgs = (await prepareImageRuntimeAuthMounts({
+            authProfile: options.authProfile ?? null,
+            ...(options.daimonContainerCredentialUid === undefined
+                ? {}
+                : { daimonContainerCredentialUid: options.daimonContainerCredentialUid }),
+            report,
+            tempRoot: workDir
+        })).mountArgs;
+        const daimonDockerSecurityArgs = await resolveDaimonDockerSecurityArgsForImage(imageRef, report, runDocker, workDir);
+        volumeReservation = await acquireExclusiveVolumeReservations(report, deploymentName, containerName, imageRef, runDocker);
+        const previousContainer = await inspectContainerSnapshot(runDocker, containerName);
+        const now = options.now ?? (() => new Date());
+        let stoppedAt;
+        if (previousContainer !== null) {
             await runDocker(["rename", containerName, backupName]);
-            await runDocker(["stop", backupName]).catch(() => undefined);
+            try {
+                await runDocker(["stop", backupName]);
+                await assertContainerStopped(runDocker, backupName, previousContainer.id);
+                if (report.recording)
+                    stoppedAt = now().getTime();
+            }
+            catch (error) {
+                try {
+                    await restorePreviousContainer(runDocker, previousContainer, backupName, containerName);
+                }
+                catch {
+                    throw new SpawnfileError("runtime_error", "Prior deployment stop failed and its original state could not be restored");
+                }
+                throw error;
+            }
         }
-        const runArgs = ["run", "-d", "--name", containerName, "--env-file", envFilePath];
+        const runArgs = [
+            "run", "-d", "--name", containerName, ...daimonDockerSecurityArgs, "--env-file", envFilePath
+        ];
         for (const port of report.ports) {
             runArgs.push("-p", `${port}:${port}`);
         }
         for (const mount of report.persistent_mounts) {
-            runArgs.push("-v", `${deriveVolumeName(deploymentName, mount.id)}:${mount.target}`);
+            runArgs.push("-v", `${derivePersistentMountVolumeName(deploymentName, mount)}:${mount.target}`);
         }
         runArgs.push(...authMountArgs);
         const labels = createDockerDeploymentLabels({
@@ -169,86 +187,85 @@ const consumeImageUpLocked = async (imageRef, parsedRef, deploymentName, isExpli
             runArgs.push("--label", `${name}=${value}`);
         }
         runArgs.push(imageRef);
-        let runOutput;
+        let candidateId;
+        let activation = {};
         try {
-            runOutput = (await runDocker(runArgs)).toString("utf8").trim();
+            activation = report.recording ? await activationBeforeStart(stoppedAt, now) : {};
+            const runOutput = (await runDocker(runArgs)).toString("utf8").trim();
+            const observedId = runOutput.split("\n").pop()?.trim();
+            if (!observedId || !/^[a-f0-9]{64}$/u.test(observedId)) {
+                throw new SpawnfileError("runtime_error", "Candidate container returned invalid identity");
+            }
+            candidateId = observedId;
+            await assertCandidateContainerReady(runDocker, candidateId, containerName);
+            const imageId = await resolveLocalImageId(imageRef, runDocker);
+            const digest = await resolveRegistryDigest(imageRef, runDocker);
+            const record = {
+                auth_profile: options.authProfileName ?? null,
+                compile_fingerprint: inspection.compileFingerprint,
+                created_at: now().toISOString(),
+                ...activation,
+                ...(report.recording ? { recording: report.recording } : {}),
+                ...(options.envFilePath ? { env_file: path.resolve(options.envFilePath) } : {}),
+                manager: "docker",
+                name: deploymentName,
+                output_directory: null,
+                source: { digest, kind: "image", ref: imageRef },
+                target,
+                units: [
+                    {
+                        container_id: candidateId,
+                        container_name: containerName,
+                        contains: buildContainsEntries(report),
+                        id: unitIdFor(deploymentName),
+                        image_id: imageId,
+                        image_tag: imageRef,
+                        kind: "container",
+                        runtime_instances: report.runtime_instances.map((instance) => instance.id).sort()
+                    }
+                ],
+                version: "spawnfile.deployment.v2"
+            };
+            const written = await writeHomeDeployment(record, report, previousRecord);
+            if (previousContainer !== null) {
+                await runDocker(["rm", "-f", previousContainer.id]).catch(() => undefined);
+            }
+            return {
+                containerName,
+                deploymentName,
+                imageRef,
+                previous,
+                record,
+                recordPath: written.recordPath
+            };
         }
         catch (error) {
-            // The new container failed to start; remove the failed attempt and restore
-            // the previous deployment so a failed redeploy never loses the live one.
-            await runDocker(["rm", "-f", containerName]).catch(() => undefined);
-            if (liveExists) {
-                await runDocker(["rename", backupName, containerName]).catch(() => undefined);
-                await runDocker(["start", containerName]).catch(() => undefined);
+            if (error instanceof HomeDeploymentRecordingError) {
+                if (previousContainer !== null)
+                    await runDocker(["rm", "-f", previousContainer.id]).catch(() => undefined);
+                throw error;
             }
-            throw error;
-        }
-        // The new container is up — discard the previous one.
-        if (liveExists) {
-            await runDocker(["rm", "-f", backupName]).catch(() => undefined);
+            const diagnostics = candidateId ? await captureCandidateDiagnostics({
+                candidateId, deploymentName, runDocker, secretValues: Object.values(env)
+            }) : null;
+            const detail = diagnostics ? ` (${diagnostics.summary}); ${diagnostics.path
+                ? `private diagnostics: ${diagnostics.path}` : "private diagnostics unavailable"}` : "";
+            const failure = (cause) => new SpawnfileError("runtime_error", sanitizeCandidateDiagnostic(cause instanceof Error ? cause.message : String(cause), Object.values(env)) + detail);
+            try {
+                await rollbackCandidateContainer(runDocker, candidateId, containerName, previousContainer, backupName, report.recording && activation.activated_at ? () => recordDeploymentRollback(resolveHomeRecordPath(deploymentName), { name: deploymentName, created_at: activation.activated_at, ...activation }, report, `${JSON.stringify(report, null, 2)}\n`, now().toISOString()) : undefined);
+            }
+            catch (rollbackError) {
+                throw failure(rollbackError);
+            }
+            throw failure(error);
         }
-        const containerId = runOutput.split("\n").pop()?.trim() || null;
-        const imageId = await resolveLocalImageId(imageRef, runDocker);
-        const digest = await resolveRegistryDigest(imageRef, runDocker);
-        const record = {
-            auth_profile: options.authProfileName ?? null,
-            compile_fingerprint: inspection.compileFingerprint,
-            created_at: new Date().toISOString(),
-            ...(options.envFilePath ? { env_file: path.resolve(options.envFilePath) } : {}),
-            manager: "docker",
-            name: deploymentName,
-            output_directory: null,
-            source: { digest, kind: "image", ref: imageRef },
-            target,
-            units: [
-                {
-                    container_id: containerId,
-                    container_name: containerName,
-                    contains: buildContainsEntries(report),
-                    id: unitIdFor(deploymentName),
-                    image_id: imageId,
-                    image_tag: imageRef,
-                    kind: "container",
-                    runtime_instances: report.runtime_instances.map((instance) => instance.id).sort()
-                }
-            ],
-            version: "spawnfile.deployment.v2"
-        };
-        const written = await writeHomeDeployment(record, report);
-        return {
-            containerName,
-            deploymentName,
-            imageRef,
-            previous,
-            record,
-            recordPath: written.recordPath
-        };
     }
     finally {
-        await rm(workDir, { force: true, recursive: true }).catch(() => undefined);
-    }
-};
-const readPreviousSource = async (deploymentName) => {
-    try {
-        const existing = await readHomeDeploymentRecord(deploymentName);
-        if (existing.source.kind !== "image") {
-            return null;
+        try {
+            await volumeReservation?.release();
+        }
+        finally {
+            await rm(workDir, { force: true, recursive: true }).catch(() => undefined);
         }
-        return { digest: existing.source.digest, ref: existing.source.ref };
-    }
-    catch {
-        return null;
-    }
-};
-const resolveExistingOrNewTarget = async (deploymentName, alreadyExists, options) => {
-    if (alreadyExists && !options.dockerContext && !options.dockerHost) {
-        const existing = await readHomeDeploymentRecord(deploymentName);
-        await verifyDockerDeploymentTarget(existing.target, { dockerCommand: options.dockerCommand });
-        return existing.target;
     }
-    return resolveDockerDeploymentTarget({
-        context: options.dockerContext ?? null,
-        dockerCommand: options.dockerCommand,
-        dockerHost: options.dockerHost ?? null
-    });
 };

package/dist/distribution/consumeImageDaimonDocker.d.ts

@@ -0,0 +1,3 @@
+import type { DockerCommandRunner } from "./dockerRunner.js";
+import type { DistributionReport } from "./types.js";
+export declare const resolveDaimonDockerSecurityArgsForImage: (imageRef: string, report: DistributionReport, runDocker: DockerCommandRunner, securityDirectory: string) => Promise<string[]>;

package/dist/distribution/consumeImageDaimonDocker.js

@@ -0,0 +1,45 @@
+import { randomUUID } from "node:crypto";
+import { SpawnfileError } from "../shared/errors.js";
+import { DAIMON_DOCKER_RUNTIME_SECURITY_ARGS, daimonEngineDockerSecurityArgsForConfigs, materializeDaimonGrokSeccompProfile } from "../shared/daimonCodexDocker.js";
+import { extractSingleFileFromTar } from "./tarReader.js";
+const DAIMON_CONFIG_SIZE_CAP_BYTES = 4 * 1024 * 1024;
+const daimonInstancesFrom = (report) => report.runtime_instances.filter((instance) => instance.runtime === "daimon");
+const assertAbsoluteConfigPath = (instance) => {
+    if (!instance.config_path.startsWith("/")) {
+        throw new SpawnfileError("validation_error", "Daimon runtime instance has a non-absolute generated config path");
+    }
+    return instance.config_path;
+};
+const readDaimonConfigSourcesFromImage = async (imageRef, instances, runDocker) => {
+    const helperName = `spawnfile-daimon-config-${randomUUID()}`;
+    await runDocker(["create", "--name", helperName, imageRef]);
+    try {
+        const sources = [];
+        for (const instance of instances) {
+            let tar;
+            try {
+                tar = await runDocker(["cp", `${helperName}:${assertAbsoluteConfigPath(instance)}`, "-"]);
+            }
+            catch (error) {
+                if (error instanceof SpawnfileError)
+                    throw error;
+                throw new SpawnfileError("validation_error", "Could not read Daimon's generated organization config before Docker launch");
+            }
+            sources.push(extractSingleFileFromTar(tar, { maxBytes: DAIMON_CONFIG_SIZE_CAP_BYTES }).toString("utf8"));
+        }
+        return sources;
+    }
+    finally {
+        await runDocker(["rm", "-f", helperName]).catch(() => undefined);
+    }
+};
+export const resolveDaimonDockerSecurityArgsForImage = async (imageRef, report, runDocker, securityDirectory) => {
+    const daimonInstances = daimonInstancesFrom(report);
+    if (daimonInstances.length === 0)
+        return [];
+    const sources = await readDaimonConfigSourcesFromImage(imageRef, daimonInstances, runDocker);
+    return [
+        ...DAIMON_DOCKER_RUNTIME_SECURITY_ARGS,
+        ...(await daimonEngineDockerSecurityArgsForConfigs(sources, () => materializeDaimonGrokSeccompProfile(securityDirectory)))
+    ];
+};

package/dist/distribution/consumeImageLifecycle.d.ts

@@ -0,0 +1,20 @@
+import type { DockerCommandRunner } from "./dockerRunner.js";
+import type { DistributionReport } from "./types.js";
+export interface ContainerSnapshot {
+    readonly id: string;
+    readonly name: string;
+    readonly running: boolean;
+}
+export interface ExclusiveVolumeReservation {
+    release(): Promise<void>;
+}
+export declare const inspectContainerSnapshot: (runDocker: DockerCommandRunner, reference: string) => Promise<ContainerSnapshot | null>;
+export declare const assertExclusiveVolumesAvailable: (report: DistributionReport, deploymentLineage: string, deploymentContainerName: string, runDocker: DockerCommandRunner) => Promise<void>;
+export declare const acquireExclusiveVolumeReservations: (report: DistributionReport, deploymentLineage: string, deploymentContainerName: string, imageReference: string, runDocker: DockerCommandRunner) => Promise<ExclusiveVolumeReservation>;
+export declare const defaultCandidateReadinessTimeoutMs = 600000;
+export declare const candidateReadinessTimeoutEnv = "SPAWNFILE_CANDIDATE_READINESS_TIMEOUT_MS";
+export declare const resolveCandidateReadinessTimeoutMs: (env?: NodeJS.ProcessEnv) => number;
+export declare const assertCandidateContainerReady: (runDocker: DockerCommandRunner, candidateId: string, expectedName: string) => Promise<void>;
+export declare const assertContainerStopped: (runDocker: DockerCommandRunner, reference: string, expectedId: string) => Promise<void>;
+export declare const restorePreviousContainer: (runDocker: DockerCommandRunner, previous: ContainerSnapshot, backupName: string, deploymentName: string) => Promise<void>;
+export declare const rollbackCandidateContainer: (runDocker: DockerCommandRunner, candidateId: string | undefined, candidateName: string, previous: ContainerSnapshot | null, backupName: string, onCandidateRemoved?: () => Promise<void>) => Promise<void>;

package/dist/distribution/consumeImageLifecycle.js

@@ -0,0 +1,242 @@
+import { createHash, randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { SpawnfileError } from "../shared/index.js";
+import { derivePersistentMountVolumeName } from "./consumeImageSupport.js";
+const dockerId = /^[a-f0-9]{64}$/u;
+const missingContainer = /(?:No such (?:container|object)|container .* not found)/iu;
+const snapshotFormat = "{{json .Id}}\n{{json .Name}}\n{{json .State.Running}}";
+const reservationFormat = "{{json .Id}}\n{{json .Config.Labels}}";
+const reservationVersionLabel = "com.spawnfile.exclusive-volume-reservation";
+const reservationOwnerLabel = "com.spawnfile.exclusive-volume-owner";
+const reservationVolumeLabel = "com.spawnfile.exclusive-volume-digest";
+const parseSnapshot = (raw) => {
+    try {
+        const [idRaw, nameRaw, runningRaw, ...extra] = raw.toString("utf8").trim().split("\n");
+        if (!idRaw || !nameRaw || !runningRaw || extra.length > 0)
+            throw new Error("shape");
+        const id = JSON.parse(idRaw);
+        const name = JSON.parse(nameRaw);
+        const running = JSON.parse(runningRaw);
+        if (typeof id !== "string" || !dockerId.test(id)
+            || typeof name !== "string" || !name.startsWith("/") || name.length < 2
+            || typeof running !== "boolean")
+            throw new Error("values");
+        return { id, name: name.slice(1), running };
+    }
+    catch {
+        throw new SpawnfileError("runtime_error", "Container returned invalid identity state");
+    }
+};
+export const inspectContainerSnapshot = async (runDocker, reference) => {
+    try {
+        return parseSnapshot(await runDocker([
+            "container", "inspect", "--format", snapshotFormat, reference
+        ]));
+    }
+    catch (error) {
+        if (error instanceof SpawnfileError && error.message === "Container returned invalid identity state")
+            throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        if (missingContainer.test(message))
+            return null;
+        throw new SpawnfileError("runtime_error", "Unable to determine container identity state");
+    }
+};
+export const assertExclusiveVolumesAvailable = async (report, deploymentLineage, deploymentContainerName, runDocker) => {
+    for (const mount of report.persistent_mounts.filter((candidate) => candidate.lifecycle === "exclusive-reattach")) {
+        const volume = derivePersistentMountVolumeName(deploymentLineage, mount);
+        const occupants = (await runDocker([
+            "ps", "--filter", `volume=${volume}`, "--format", "{{.Names}}"
+        ])).toString("utf8").split("\n").map((name) => name.trim()).filter(Boolean);
+        if (occupants.some((name) => name !== deploymentContainerName)) {
+            throw new SpawnfileError("runtime_error", `Exclusive persistent mount ${mount.id} is attached to another running deployment; stop that deployment before reattaching the realm`);
+        }
+    }
+};
+const reservationName = (volumeDigest) => `spawnfile-volume-reservation-${volumeDigest.slice("sha256:".length, 24 + "sha256:".length)}`;
+const inspectReservation = async (runDocker, record) => {
+    try {
+        const output = (await runDocker([
+            "container", "inspect", "--format", reservationFormat, record.id
+        ])).toString("utf8").trim().split("\n");
+        if (output.length !== 2)
+            throw new Error("shape");
+        const id = JSON.parse(output[0]);
+        const labels = JSON.parse(output[1]);
+        if (id !== record.id || !labels || typeof labels !== "object" || Array.isArray(labels))
+            throw new Error("identity");
+        const values = labels;
+        if (values[reservationVersionLabel] !== "v1"
+            || values[reservationOwnerLabel] !== record.owner
+            || values[reservationVolumeLabel] !== record.volumeDigest)
+            throw new Error("authority");
+    }
+    catch {
+        throw new SpawnfileError("runtime_error", "Exclusive persistent mount reservation identity is unavailable");
+    }
+};
+const releaseReservations = async (runDocker, records) => {
+    let failed = false;
+    for (const record of [...records].reverse()) {
+        try {
+            await inspectReservation(runDocker, record);
+            await runDocker(["container", "rm", record.id]);
+        }
+        catch {
+            failed = true;
+        }
+    }
+    if (failed)
+        throw new SpawnfileError("runtime_error", "Unable to release exclusive persistent mount reservation");
+};
+export const acquireExclusiveVolumeReservations = async (report, deploymentLineage, deploymentContainerName, imageReference, runDocker) => {
+    const volumes = report.persistent_mounts
+        .filter((mount) => mount.lifecycle === "exclusive-reattach")
+        .map((mount) => derivePersistentMountVolumeName(deploymentLineage, mount))
+        .sort();
+    const records = [];
+    try {
+        for (const volume of volumes) {
+            const volumeDigest = `sha256:${createHash("sha256").update(volume).digest("hex")}`;
+            const owner = randomUUID();
+            const name = reservationName(volumeDigest);
+            let id;
+            try {
+                id = (await runDocker([
+                    "container", "create", "--name", name,
+                    "--label", `${reservationVersionLabel}=v1`,
+                    "--label", `${reservationOwnerLabel}=${owner}`,
+                    "--label", `${reservationVolumeLabel}=${volumeDigest}`,
+                    imageReference
+                ])).toString("utf8").trim();
+            }
+            catch {
+                throw new SpawnfileError("runtime_error", "Exclusive persistent mount reservation is already held");
+            }
+            if (!dockerId.test(id))
+                throw new SpawnfileError("runtime_error", "Exclusive persistent mount reservation returned invalid identity");
+            const record = { id, name, owner, volumeDigest };
+            records.push(record);
+            await inspectReservation(runDocker, record);
+        }
+        await assertExclusiveVolumesAvailable(report, deploymentLineage, deploymentContainerName, runDocker);
+    }
+    catch (error) {
+        if (records.length > 0)
+            await releaseReservations(runDocker, records);
+        throw error;
+    }
+    let released = false;
+    return {
+        release: async () => {
+            if (released)
+                return;
+            await releaseReservations(runDocker, records);
+            released = true;
+        }
+    };
+};
+const parseCandidateState = (raw) => {
+    try {
+        const [idRaw, nameRaw, stateRaw, ...extra] = raw.toString("utf8").trim().split("\n");
+        if (!idRaw || !nameRaw || !stateRaw || extra.length > 0)
+            throw new Error("shape");
+        const id = JSON.parse(idRaw);
+        const name = JSON.parse(nameRaw);
+        const state = JSON.parse(stateRaw);
+        if (typeof id !== "string" || !dockerId.test(id)
+            || typeof name !== "string" || !name.startsWith("/") || name.length < 2
+            || !state || typeof state !== "object" || typeof state.Running !== "boolean")
+            throw new Error("values");
+        return { snapshot: { id, name: name.slice(1), running: state.Running }, state };
+    }
+    catch {
+        throw new SpawnfileError("runtime_error", "Candidate container returned invalid readiness state");
+    }
+};
+export const defaultCandidateReadinessTimeoutMs = 600_000;
+export const candidateReadinessTimeoutEnv = "SPAWNFILE_CANDIDATE_READINESS_TIMEOUT_MS";
+// Large orgs can take minutes to boot; the budget is overridable per host.
+// Anything other than a positive integer falls back to the default.
+export const resolveCandidateReadinessTimeoutMs = (env = process.env) => {
+    const raw = env[candidateReadinessTimeoutEnv]?.trim();
+    if (!raw || !/^[0-9]+$/u.test(raw))
+        return defaultCandidateReadinessTimeoutMs;
+    const value = Number(raw);
+    return Number.isSafeInteger(value) && value > 0 ? value : defaultCandidateReadinessTimeoutMs;
+};
+const candidateReadinessPollMs = 1_000;
+export const assertCandidateContainerReady = async (runDocker, candidateId, expectedName) => {
+    if (!dockerId.test(candidateId))
+        throw new SpawnfileError("runtime_error", "Candidate container returned invalid identity");
+    const deadline = Date.now() + resolveCandidateReadinessTimeoutMs();
+    for (;;) {
+        const { snapshot, state } = parseCandidateState(await runDocker([
+            "container", "inspect", "--format", "{{json .Id}}\n{{json .Name}}\n{{json .State}}", candidateId
+        ]));
+        if (snapshot.id !== candidateId || snapshot.name !== expectedName) {
+            throw new SpawnfileError("runtime_error", "Candidate container identity did not match detached run");
+        }
+        const health = state.Health?.Status;
+        if (state.Running === true && (health === undefined || health === "healthy"))
+            return;
+        // Docker may exhaust its health retries while a live process is still
+        // initializing. Honor our full readiness budget; only healthy can pass.
+        if (state.Running !== true || (health !== "starting" && health !== "unhealthy"))
+            break;
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0)
+            break;
+        await delay(Math.min(candidateReadinessPollMs, remainingMs));
+    }
+    throw new SpawnfileError("runtime_error", "Candidate container did not become ready");
+};
+export const assertContainerStopped = async (runDocker, reference, expectedId) => {
+    const observed = await inspectContainerSnapshot(runDocker, reference);
+    if (observed === null || observed.id !== expectedId || observed.running) {
+        throw new SpawnfileError("runtime_error", "Prior container did not reach a verified stopped state");
+    }
+};
+export const restorePreviousContainer = async (runDocker, previous, backupName, deploymentName) => {
+    const backup = await inspectContainerSnapshot(runDocker, backupName);
+    if (backup === null || backup.id !== previous.id) {
+        throw new SpawnfileError("runtime_error", "Prior container rollback identity is unavailable");
+    }
+    await runDocker(["rename", backupName, deploymentName]);
+    if (previous.running !== backup.running) {
+        await runDocker([previous.running ? "start" : "stop", previous.id]);
+    }
+    const restored = await inspectContainerSnapshot(runDocker, previous.id);
+    if (restored === null || restored.id !== previous.id || restored.name !== deploymentName
+        || restored.running !== previous.running) {
+        throw new SpawnfileError("runtime_error", "Prior container rollback state could not be verified");
+    }
+};
+export const rollbackCandidateContainer = async (runDocker, candidateId, candidateName, previous, backupName, onCandidateRemoved) => {
+    const failed = [];
+    if (candidateId !== undefined) {
+        try {
+            const candidate = await inspectContainerSnapshot(runDocker, candidateId);
+            if (candidate !== null) {
+                if (candidate.id !== candidateId || candidate.name !== candidateName)
+                    throw new Error("identity");
+                await runDocker(["rm", "-f", candidateId]);
+            }
+            await onCandidateRemoved?.();
+        }
+        catch {
+            failed.push("candidate cleanup");
+        }
+    }
+    if (previous !== null) {
+        try {
+            await restorePreviousContainer(runDocker, previous, backupName, candidateName);
+        }
+        catch {
+            failed.push("prior restore");
+        }
+    }
+    if (failed.length > 0) {
+        throw new SpawnfileError("runtime_error", `Candidate deployment failed and rollback was incomplete (${failed.join(", ")})`);
+    }
+};

package/dist/distribution/consumeImageSupport.d.ts

@@ -1,9 +1,23 @@
+import { type DockerDeploymentTarget } from "../deployment/index.js";
+import type { ConsumeImageUpOptions } from "./consumeImage.js";
 import type { ParsedImageReference } from "./imageRef.js";
 import type { DistributionReport } from "./types.js";
+import type { DistributionPersistentMount } from "./types.js";
 /** Derives a kebab-case deployment name from the image repository component. */
 export declare const deriveDeploymentName: (ref: ParsedImageReference) => string;
 /** Per-deployment volume name so two deployments never share a store. */
 export declare const deriveVolumeName: (deploymentName: string, mountId: string) => string;
+/**
+ * An author-declared name wins over any derivation, in image mode exactly as
+ * in project mode. Without this, an operator who pre-created
+ * `clank-newsroom-store` and deployed the published image silently got
+ * `spawnfile-exclusive-<id>-<hash>` — a brand-new empty volume — while the
+ * spec promised the declared name verbatim.
+ *
+ * Only a DECLARED name travels in the report; an undeclared mount is still
+ * named per deployment so two deployments of one image never share state.
+ */
+export declare const derivePersistentMountVolumeName: (deploymentName: string, mount: DistributionPersistentMount) => string;
 export interface ResolveImageEnvironmentInput {
     authValues: Record<string, string>;
     envFileEnv?: Record<string, string>;
@@ -16,3 +30,8 @@ export interface ResolveImageEnvironmentInput {
  */
 export declare const resolveImageEnvironment: (input: ResolveImageEnvironmentInput) => Record<string, string>;
 export declare const renderEnvFileContent: (env: Record<string, string>) => string;
+export declare const readPreviousSource: (deploymentName: string) => Promise<{
+    digest: string | null;
+    ref: string;
+} | null>;
+export declare const resolveExistingOrNewTarget: (deploymentName: string, alreadyExists: boolean, options: ConsumeImageUpOptions) => Promise<DockerDeploymentTarget>;