spawnfile 0.1.14 → 0.1.18

package/dist/deployment/downDeployment.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { fileExists, readUtf8File } from "../filesystem/index.js";
+import { derivePersistentMountVolumeName, parseDistributionReport } from "../distribution/index.js";
 import { REPORT_FILENAME, SpawnfileError } from "../shared/index.js";
 import { exportRunArtifacts } from "./artifactsExport.js";
 import { assertDeploymentLifecycleCorrelation, } from "./deploymentLifecycleCorrelation.js";
@@ -7,6 +8,104 @@ import { defaultDockerTeardownExecFile, removeDockerContainer, removeDockerVolum
 import { DOWN_RECEIPT_VERSION } from "./downReceiptTypes.js";
 import { initializeOrganizationHandoffAuthorityStore, } from "./organizationHandoffAuthorityStore.js";
 import { readDeploymentRecordFromOutput } from "./record.js";
+import { assertRecordedMemoryRetention, recordedMemoryForDeletion } from "./recordedMemoryRetention.js";
+import { readHomeDeploymentRecord, readHomeDeploymentReport, resolveHomeRecordPath } from "./homeStore.js";
+import { resolveDeploymentRecordPath } from "./names.js";
+import { dockerContextNameForTarget } from "./target.js";
+export const readCanonicalDownRecord = async (compiledOutputDirectory, deploymentName) => {
+    const projectPath = resolveDeploymentRecordPath(path.resolve(compiledOutputDirectory), deploymentName);
+    const homePath = resolveHomeRecordPath(deploymentName);
+    const [projectExists, homeExists] = await Promise.all([fileExists(projectPath), fileExists(homePath)]);
+    if (projectExists && homeExists)
+        throw new SpawnfileError("runtime_error", "Deployment record is ambiguous between project and image stores");
+    if (projectExists) {
+        const record = await readDeploymentRecordFromOutput(path.resolve(compiledOutputDirectory), deploymentName);
+        if (record.source.kind !== "project")
+            throw new SpawnfileError("runtime_error", "Project deployment store contains a non-project record");
+        return { mode: "project", record };
+    }
+    if (homeExists) {
+        const record = await readHomeDeploymentRecord(deploymentName);
+        if (record.source.kind !== "image")
+            throw new SpawnfileError("runtime_error", "Image deployment store contains a non-image record");
+        return { mode: "image", record };
+    }
+    throw new SpawnfileError("validation_error", `No recorded deployment named ${deploymentName}`);
+};
+const imageDown = async (record, options, runner) => {
+    if (record.source.kind !== "image" || record.units.length !== 1)
+        throw new SpawnfileError("runtime_error", "Image deployment record is invalid for teardown");
+    if (!record.export_index && !options.force)
+        throw new SpawnfileError("runtime_error", "Image deployment artifact export is unsupported; pass --force to discard unexported artifacts");
+    const unit = record.units[0];
+    if (!unit.container_id || !unit.image_id)
+        throw new SpawnfileError("runtime_error", "Image deployment has no exact recorded container or image identity");
+    const context = dockerContextNameForTarget(record.target);
+    const prefix = context ? ["--context", context] : record.target.kind === "host" ? ["--host", record.target.value] : [];
+    const inspected = await runner.execFile(runner.dockerCommand, [...prefix, "container", "inspect", "--format", "{{json .Id}}\n{{json .Name}}\n{{json .Image}}\n{{json .Config.Labels}}", unit.container_id], { timeout: runner.timeoutMs });
+    let identity;
+    try {
+        const [idLine, nameLine, imageLine, labelsLine, ...extra] = inspected.stdout.trim().split("\n");
+        if (!idLine || !nameLine || !imageLine || !labelsLine || extra.length)
+            throw new Error();
+        identity = { id: JSON.parse(idLine), imageId: JSON.parse(imageLine), name: JSON.parse(nameLine), labels: JSON.parse(labelsLine) };
+    }
+    catch {
+        throw new SpawnfileError("runtime_error", "Image deployment container identity is malformed");
+    }
+    if (identity.id !== unit.container_id || identity.name !== `/${unit.container_name}` || identity.imageId !== unit.image_id
+        || identity.labels["com.spawnfile.deployment"] !== record.name
+        || identity.labels["com.spawnfile.compile_fingerprint"] !== record.compile_fingerprint
+        || identity.labels["com.spawnfile.unit"] !== unit.id) {
+        throw new SpawnfileError("runtime_error", "Image deployment container identity does not match its record");
+    }
+    let reportValue;
+    try {
+        reportValue = JSON.parse(await readHomeDeploymentReport(record.name));
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new SpawnfileError("runtime_error", `Cached image distribution report is unreadable: ${reason}`);
+    }
+    const report = parseDistributionReport(reportValue, "cached image distribution report");
+    if (report.compile_fingerprint !== record.compile_fingerprint)
+        throw new SpawnfileError("runtime_error", "Cached image distribution report does not match its deployment record");
+    const { owned, skipped } = partitionDeclaredVolumes(report.persistent_mounts, (mount) => derivePersistentMountVolumeName(record.name, mount));
+    assertRecordedMemoryRetention(recordedMemoryForDeletion(record, report, report.persistent_mounts, options), report.persistent_mounts, owned, (mount) => derivePersistentMountVolumeName(record.name, mount), options);
+    const volumes = [...owned, ...skipped].sort();
+    const removed = await removeDockerContainer(record.target, unit.container_id, runner);
+    if (!removed.removed)
+        return { deployment: record.name, errors: [`unable to remove container ${unit.container_id} (unit ${unit.id}): ${removed.error}`], retained_volumes: volumes, units_stopped: [], version: DOWN_RECEIPT_VERSION, ...(skipped.length > 0 ? { skipped_volumes: skipped } : {}) };
+    const errors = [], retained = [...skipped];
+    if (options.removeVolumes)
+        for (const volume of owned) {
+            const result = await removeDockerVolume(record.target, volume, runner);
+            if (!result.removed) {
+                errors.push(`unable to remove volume ${volume}: ${result.error}`);
+                retained.push(volume);
+            }
+        }
+    else
+        retained.push(...owned);
+    return { deployment: record.name, errors, retained_volumes: retained.sort(), units_stopped: [unit.id], version: DOWN_RECEIPT_VERSION, ...(skipped.length > 0 ? { skipped_volumes: skipped } : {}) };
+};
+/**
+ * Splits the volumes a `--volumes` teardown found into the ones this deployment
+ * owns and the author-declared ones it shares with every other deployment of the
+ * project. See downReceiptTypes.ts for why the declared ones are never removed.
+ */
+const partitionDeclaredVolumes = (mounts, volumeNameOf) => {
+    const skipped = new Set();
+    const owned = new Set();
+    for (const mount of mounts) {
+        (mount.declared_volume_name?.trim() ? skipped : owned).add(volumeNameOf(mount));
+    }
+    // A name claimed by both is shared state, and the compiler already rejects that
+    // collision; fail safe here regardless by never removing it.
+    for (const name of skipped)
+        owned.delete(name);
+    return { owned: [...owned].sort(), skipped: [...skipped].sort() };
+};
 const targetRefForUnit = (unit) => unit.container_id ?? unit.container_name;
 const readCompileReport = async (compiledOutputDirectory) => {
     const reportPath = path.join(compiledOutputDirectory, REPORT_FILENAME);
@@ -95,15 +194,22 @@ export const downDeployment = async (options) => {
     const dockerCommand = options.dockerCommand ?? "docker";
     const execFileImpl = options.execFile ?? defaultDockerTeardownExecFile;
     const timeoutMs = options.timeoutMs ?? 30_000;
-    const initialRecord = await readDeploymentRecordFromOutput(compiledOutputDirectory, options.deploymentName);
+    const resolved = await readCanonicalDownRecord(compiledOutputDirectory, options.deploymentName);
+    const initialRecord = resolved.record;
     assertDeploymentLifecycleCorrelation(initialRecord, options.expectedLifecycleCorrelation);
+    const runnerOptions = { dockerCommand, execFile: execFileImpl, timeoutMs };
+    if (resolved.mode === "image")
+        return imageDown(initialRecord, options, runnerOptions);
+    const report = await readCompileReport(compiledOutputDirectory);
+    const mounts = report?.container?.persistent_mounts ?? [];
+    const { owned, skipped } = partitionDeclaredVolumes(mounts, (mount) => mount.volume_name);
+    assertRecordedMemoryRetention(recordedMemoryForDeletion(initialRecord, report, mounts, options), mounts, owned, (mount) => mount.volume_name, options);
     const record = await ensureExported(initialRecord, {
         ...options,
         compiledOutputDirectory,
     });
     assertDeploymentLifecycleCorrelation(record, options.expectedLifecycleCorrelation);
     await closeOrganizationHandoff(record);
-    const runnerOptions = { dockerCommand, execFile: execFileImpl, timeoutMs };
     const unitsStopped = [];
     const errors = [];
     for (const unit of record.units) {
@@ -120,13 +226,11 @@ export const downDeployment = async (options) => {
             errors.push(`unable to remove container ${containerRef} (unit ${unit.id}): ${outcome.error}`);
         }
     }
-    const report = await readCompileReport(compiledOutputDirectory);
-    const volumeNames = [
-        ...new Set((report?.container?.persistent_mounts ?? []).map((mount) => mount.volume_name)),
-    ].sort();
-    const retainedVolumes = [];
+    // Declared volumes are retained unconditionally: they are shared project
+    // state, not this deployment's, so `--volumes` must never destroy them.
+    const retainedVolumes = [...skipped];
     if (options.removeVolumes) {
-        for (const volumeName of volumeNames) {
+        for (const volumeName of owned) {
             const outcome = await removeDockerVolume(record.target, volumeName, runnerOptions);
             if (!outcome.removed) {
                 errors.push(`unable to remove volume ${volumeName}: ${outcome.error}`);
@@ -135,12 +239,13 @@ export const downDeployment = async (options) => {
         }
     }
     else {
-        retainedVolumes.push(...volumeNames);
+        retainedVolumes.push(...owned);
     }
     return {
         deployment: record.name,
         errors,
         retained_volumes: retainedVolumes.sort(),
+        ...(skipped.length > 0 ? { skipped_volumes: skipped } : {}),
         units_stopped: unitsStopped.sort(),
         version: DOWN_RECEIPT_VERSION,
     };

package/dist/deployment/downReceiptTypes.d.ts

@@ -6,8 +6,22 @@ import { z } from "zod";
  * `unit.id`, e.g. `"<deployment>-container"`), not raw Docker container ids, so a caller
  * can cross-reference the up-receipt/deployment record without re-deriving anything.
  * `retained_volumes` is "named volumes still present on disk after this call returns" —
- * true whether they were never touched (the default) or survived an attempted
- * `--volumes` removal that failed (surfaced in `errors`, not silently dropped).
+ * true whether they were never touched (the default), survived an attempted
+ * `--volumes` removal that failed (surfaced in `errors`, not silently dropped), or
+ * were deliberately skipped as shared project state (`skipped_volumes`).
+ *
+ * `skipped_volumes` is the third outcome this contract originally could not express.
+ * An author-declared volume name (a workspace resource `name`, a
+ * `store.persistence.name`, a memory bank's `persistence.name`) is verbatim in every
+ * mode and every deployment, so it is NOT "this deployment's named volume" — a
+ * `down --volumes` of a dev or scratch deployment would otherwise destroy the
+ * production state that same name refers to, whenever production happens to be
+ * stopped (Docker only refuses a volume that is currently in use). Those volumes are
+ * skipped, listed here AND in `retained_volumes`, and removing one is a deliberate
+ * project-level act: `docker volume rm <name>`.
+ *
+ * The field is OMITTED when nothing was skipped, so every receipt that could be
+ * produced before this existed is still byte-identical.
  */
 export declare const DOWN_RECEIPT_VERSION: "spawnfile.down-receipt.v1";
 export declare const downReceiptSchema: z.ZodObject<{
@@ -15,6 +29,7 @@ export declare const downReceiptSchema: z.ZodObject<{
     deployment: z.ZodString;
     units_stopped: z.ZodArray<z.ZodString>;
     retained_volumes: z.ZodArray<z.ZodString>;
+    skipped_volumes: z.ZodOptional<z.ZodArray<z.ZodString>>;
     errors: z.ZodArray<z.ZodString>;
 }, z.core.$strict>;
 export type DownReceipt = z.infer<typeof downReceiptSchema>;

package/dist/deployment/downReceiptTypes.js

@@ -6,8 +6,22 @@ import { z } from "zod";
  * `unit.id`, e.g. `"<deployment>-container"`), not raw Docker container ids, so a caller
  * can cross-reference the up-receipt/deployment record without re-deriving anything.
  * `retained_volumes` is "named volumes still present on disk after this call returns" —
- * true whether they were never touched (the default) or survived an attempted
- * `--volumes` removal that failed (surfaced in `errors`, not silently dropped).
+ * true whether they were never touched (the default), survived an attempted
+ * `--volumes` removal that failed (surfaced in `errors`, not silently dropped), or
+ * were deliberately skipped as shared project state (`skipped_volumes`).
+ *
+ * `skipped_volumes` is the third outcome this contract originally could not express.
+ * An author-declared volume name (a workspace resource `name`, a
+ * `store.persistence.name`, a memory bank's `persistence.name`) is verbatim in every
+ * mode and every deployment, so it is NOT "this deployment's named volume" — a
+ * `down --volumes` of a dev or scratch deployment would otherwise destroy the
+ * production state that same name refers to, whenever production happens to be
+ * stopped (Docker only refuses a volume that is currently in use). Those volumes are
+ * skipped, listed here AND in `retained_volumes`, and removing one is a deliberate
+ * project-level act: `docker volume rm <name>`.
+ *
+ * The field is OMITTED when nothing was skipped, so every receipt that could be
+ * produced before this existed is still byte-identical.
  */
 export const DOWN_RECEIPT_VERSION = "spawnfile.down-receipt.v1";
 export const downReceiptSchema = z
@@ -16,6 +30,7 @@ export const downReceiptSchema = z
     deployment: z.string().min(1),
     units_stopped: z.array(z.string().min(1)),
     retained_volumes: z.array(z.string().min(1)),
+    skipped_volumes: z.array(z.string().min(1)).optional(),
     errors: z.array(z.string().min(1))
 })
     .strict();

package/dist/deployment/homeStore.d.ts

@@ -1,12 +1,20 @@
 import type { DistributionReport } from "../distribution/index.js";
 import { type DeploymentRecord } from "./record.js";
+export { HomeDeploymentRecordingError } from "./recordPublication.js";
 export declare const resolveHomeDeploymentsDirectory: () => string;
 export declare const resolveHomeDeploymentDirectory: (deploymentName: string) => string;
 export declare const resolveHomeRecordPath: (deploymentName: string) => string;
 export declare const resolveHomeReportPath: (deploymentName: string) => string;
+/**
+ * Acquires an exclusive lock for a home deployment so concurrent `up`
+ * invocations (and a drained release holding it across its swap) cannot race
+ * on the same record or orphan each other's containers. Returns a release
+ * function. Throws if a live operation holds the lock; a lock left by a
+ * process that is gone is reclaimed. See `pidLock.ts`.
+ */
 export declare const acquireHomeDeploymentLock: (deploymentName: string) => Promise<() => Promise<void>>;
 /** Writes the record and the cached distribution report together, record last. */
-export declare const writeHomeDeployment: (record: DeploymentRecord, report: DistributionReport) => Promise<{
+export declare const writeHomeDeployment: (record: DeploymentRecord, report: DistributionReport, previous?: DeploymentRecord | null) => Promise<{
     recordPath: string;
     reportPath: string;
 }>;

package/dist/deployment/homeStore.js

@@ -1,84 +1,47 @@
 import path from "node:path";
-import { open, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { readdir } from "node:fs/promises";
 import { resolveSpawnfileHome } from "../auth/index.js";
-import { ensureDirectory, readUtf8File } from "../filesystem/index.js";
+import { ensureDirectory, readUtf8File, writeDurableFile } from "../filesystem/index.js";
 import { SpawnfileError } from "../shared/index.js";
 import { normalizeDeploymentName } from "./names.js";
+import { acquirePidLock, PidLockBusyError } from "./pidLock.js";
 import { parseDeploymentRecord } from "./record.js";
+import { bindDeploymentRecording, publishDeploymentRecord, writeAtomicDeploymentFile } from "./recordPublication.js";
+export { HomeDeploymentRecordingError } from "./recordPublication.js";
 export const resolveHomeDeploymentsDirectory = () => path.join(resolveSpawnfileHome(), "deployments");
 export const resolveHomeDeploymentDirectory = (deploymentName) => path.join(resolveHomeDeploymentsDirectory(), normalizeDeploymentName(deploymentName));
 export const resolveHomeRecordPath = (deploymentName) => path.join(resolveHomeDeploymentDirectory(deploymentName), "record.json");
 export const resolveHomeReportPath = (deploymentName) => path.join(resolveHomeDeploymentDirectory(deploymentName), "spawnfile-report.json");
 /**
  * Acquires an exclusive lock for a home deployment so concurrent `up`
- * invocations cannot race on the same record (and orphan each other's
- * containers). Returns a release function. Throws if the deployment is already
- * locked by another in-flight operation.
+ * invocations (and a drained release holding it across its swap) cannot race
+ * on the same record or orphan each other's containers. Returns a release
+ * function. Throws if a live operation holds the lock; a lock left by a
+ * process that is gone is reclaimed. See `pidLock.ts`.
  */
-const isProcessAlive = (pid) => {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        // ESRCH means no such process (stale); EPERM means it exists but is ours to
-        // not signal — treat as alive to stay safe.
-        return error.code === "EPERM";
-    }
-};
 export const acquireHomeDeploymentLock = async (deploymentName) => {
     const directory = resolveHomeDeploymentDirectory(deploymentName);
     await ensureDirectory(directory);
-    const lockPath = path.join(directory, ".lock");
-    const write = async () => {
-        const handle = await open(lockPath, "wx");
-        try {
-            await handle.write(JSON.stringify({ pid: process.pid }));
-        }
-        finally {
-            await handle.close();
-        }
-    };
     try {
-        await write();
+        return await acquirePidLock(path.join(directory, ".lock"));
     }
     catch (error) {
-        if (error.code !== "EEXIST") {
-            throw error;
-        }
-        // A lock exists. Reclaim it only if the owning process is gone (a crashed
-        // deploy must not lock the deployment forever); otherwise it is genuinely busy.
-        let ownerPid = null;
-        try {
-            ownerPid = JSON.parse(await readUtf8File(lockPath)).pid ?? null;
-        }
-        catch {
-            ownerPid = null;
-        }
-        if (ownerPid !== null && isProcessAlive(ownerPid)) {
+        if (error instanceof PidLockBusyError) {
             throw new SpawnfileError("runtime_error", `Deployment "${normalizeDeploymentName(deploymentName)}" is already being modified by another operation`);
         }
-        await rm(lockPath, { force: true });
-        await write();
+        throw error;
     }
-    return async () => {
-        await rm(lockPath, { force: true });
-    };
-};
-const writeAtomic = async (filePath, content) => {
-    const temporaryPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
-    await writeFile(temporaryPath, content, "utf8");
-    await rename(temporaryPath, filePath);
 };
 /** Writes the record and the cached distribution report together, record last. */
-export const writeHomeDeployment = async (record, report) => {
+export const writeHomeDeployment = async (record, report, previous) => {
     const parsed = parseDeploymentRecord(record);
     const directory = resolveHomeDeploymentDirectory(parsed.name);
     await ensureDirectory(directory);
     const reportPath = resolveHomeReportPath(parsed.name);
     const recordPath = resolveHomeRecordPath(parsed.name);
-    await writeAtomic(reportPath, `${JSON.stringify(report, null, 2)}\n`);
-    await writeAtomic(recordPath, `${JSON.stringify(parsed, null, 2)}\n`);
+    const reportBytes = `${JSON.stringify(report, null, 2)}\n`;
+    const bound = parseDeploymentRecord(bindDeploymentRecording(recordPath, parsed, report, reportBytes));
+    await publishDeploymentRecord(recordPath, bound, (durable) => (durable ? writeDurableFile : writeAtomicDeploymentFile)(reportPath, reportBytes), previous);
     return { recordPath, reportPath };
 };
 export const readHomeDeploymentRecord = async (deploymentName) => {

package/dist/deployment/index.d.ts

@@ -4,6 +4,8 @@ export * from "./artifactsExportPlan.js";
 export * from "./artifactsExportTypes.js";
 export * from "./privateArtifactsExport.js";
 export * from "./buildImageCacheStore.js";
+export * from "./candidateDiagnostics.js";
+export * from "./candidateRecording.js";
 export * from "./dockerLabels.js";
 export * from "./dockerInspect.js";
 export * from "./dockerLogs.js";
@@ -16,11 +18,19 @@ export * from "./downDeployment.js";
 export * from "./downReceiptTypes.js";
 export * from "./homeStore.js";
 export * from "./lifecycleCompletion.js";
+export * from "./lifecycleUpRecords.js";
 export * from "./names.js";
 export * from "./organizationHandoffTypes.js";
 export * from "./organizationHandoffAuthorityTypes.js";
 export * from "./organizationHandoffAuthorityStore.js";
 export * from "./organizationReady.js";
+export * from "./pidLock.js";
+export * from "./canaryCutover.js";
+export * from "./productStateClone.js";
 export * from "./record.js";
+export * from "./recordedMemoryRetention.js";
 export * from "./target.js";
 export * from "./upReceiptTypes.js";
+export * from "./resourceLog.js";
+export * from "./activation.js";
+export { bindDeploymentRecording, reconcileDeploymentResources } from "./recordPublication.js";

package/dist/deployment/index.js

@@ -4,6 +4,8 @@ export * from "./artifactsExportPlan.js";
 export * from "./artifactsExportTypes.js";
 export * from "./privateArtifactsExport.js";
 export * from "./buildImageCacheStore.js";
+export * from "./candidateDiagnostics.js";
+export * from "./candidateRecording.js";
 export * from "./dockerLabels.js";
 export * from "./dockerInspect.js";
 export * from "./dockerLogs.js";
@@ -16,12 +18,20 @@ export * from "./downDeployment.js";
 export * from "./downReceiptTypes.js";
 export * from "./homeStore.js";
 export * from "./lifecycleCompletion.js";
+export * from "./lifecycleUpRecords.js";
 export * from "./names.js";
 export * from "./organizationHandoffTypes.js";
 export * from "./organizationHandoffAuthorityTypes.js";
 export * from "./organizationHandoffAuthorityStore.js";
 export * from "./organizationReady.js";
+export * from "./pidLock.js";
+export * from "./canaryCutover.js";
+export * from "./productStateClone.js";
 export * from "./record.js";
+export * from "./recordedMemoryRetention.js";
 // Compatibility target exports remain available from this legacy deployment barrel.
 export * from "./target.js";
 export * from "./upReceiptTypes.js";
+export * from "./resourceLog.js";
+export * from "./activation.js";
+export { bindDeploymentRecording, reconcileDeploymentResources } from "./recordPublication.js";

package/dist/deployment/lifecycleCompletionContracts.d.ts

@@ -6,6 +6,10 @@ export declare const LIFECYCLE_OWNER_VERSION: "spawnfile.lifecycle-owner.v1";
 export declare const LIFECYCLE_ADMISSION_VERSION: "spawnfile.lifecycle-admission.v1";
 export declare const LIFECYCLE_AMBIGUOUS_VERSION: "spawnfile.lifecycle-ambiguous.v1";
 export declare const LIFECYCLE_TERMINAL_VERSION: "spawnfile.lifecycle-terminal.v1";
+export declare const LIFECYCLE_UP_START_VERSION: "spawnfile.lifecycle-up-start.v1";
+export declare const LIFECYCLE_UP_RESERVATION_VERSION: "spawnfile.lifecycle-up-reservation.v1";
+export declare const LIFECYCLE_UP_CLEANUP_VERSION: "spawnfile.lifecycle-up-cleanup.v1";
+export declare const LIFECYCLE_UP_EXTRA_LABELS: "image-config-labels";
 export declare const LIFECYCLE_RECORD_MAX_BYTES = 1000000;
 export declare const lifecycleIdSchema: z.ZodString;
 export declare const lifecycleInvocationSchema: z.ZodObject<{
@@ -94,6 +98,68 @@ export declare const lifecycleCompletionSchema: z.ZodObject<{
     version: z.ZodLiteral<"spawnfile.lifecycle-completion.v1">;
 }, z.core.$strict>;
 export type LifecycleCompletion = z.infer<typeof lifecycleCompletionSchema>;
+export declare const lifecycleUpReservationSchema: z.ZodObject<{
+    container_name: z.ZodString;
+    docker_command: z.ZodString;
+    docker_context: z.ZodNullable<z.ZodString>;
+    invocation: z.ZodObject<{
+        correlation: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodNull]>>;
+        id: z.ZodString;
+        operation: z.ZodEnum<{
+            down: "down";
+            up: "up";
+            artifacts_export: "artifacts_export";
+        }>;
+        request_policy: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodNull]>>;
+        version: z.ZodLiteral<"spawnfile.lifecycle-invocation.v1">;
+    }, z.core.$strict>;
+    label_authority: z.ZodObject<{
+        required: z.ZodRecord<z.ZodString, z.ZodString>;
+        permitted_extra_labels: z.ZodLiteral<"image-config-labels">;
+    }, z.core.$strict>;
+    version: z.ZodLiteral<"spawnfile.lifecycle-up-reservation.v1">;
+}, z.core.$strict>;
+export type LifecycleUpReservation = z.infer<typeof lifecycleUpReservationSchema>;
+export declare const lifecycleUpStartSchema: z.ZodObject<{
+    attempt: z.ZodNumber;
+    container_id: z.ZodString;
+    container_name: z.ZodString;
+    image_id: z.ZodString;
+    invocation: z.ZodObject<{
+        correlation: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodNull]>>;
+        id: z.ZodString;
+        operation: z.ZodEnum<{
+            down: "down";
+            up: "up";
+            artifacts_export: "artifacts_export";
+        }>;
+        request_policy: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodNull]>>;
+        version: z.ZodLiteral<"spawnfile.lifecycle-invocation.v1">;
+    }, z.core.$strict>;
+    label_authority: z.ZodObject<{
+        required: z.ZodRecord<z.ZodString, z.ZodString>;
+        permitted_extra_labels: z.ZodLiteral<"image-config-labels">;
+    }, z.core.$strict>;
+    version: z.ZodLiteral<"spawnfile.lifecycle-up-start.v1">;
+}, z.core.$strict>;
+export type LifecycleUpStart = z.infer<typeof lifecycleUpStartSchema>;
+export declare const lifecycleUpCleanupSchema: z.ZodObject<{
+    attempt: z.ZodNumber;
+    container_id: z.ZodString;
+    invocation: z.ZodObject<{
+        correlation: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodNull]>>;
+        id: z.ZodString;
+        operation: z.ZodEnum<{
+            down: "down";
+            up: "up";
+            artifacts_export: "artifacts_export";
+        }>;
+        request_policy: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodNull]>>;
+        version: z.ZodLiteral<"spawnfile.lifecycle-invocation.v1">;
+    }, z.core.$strict>;
+    version: z.ZodLiteral<"spawnfile.lifecycle-up-cleanup.v1">;
+}, z.core.$strict>;
+export type LifecycleUpCleanup = z.infer<typeof lifecycleUpCleanupSchema>;
 export declare const lifecycleTerminalSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     completion: z.ZodObject<{
         invocation: z.ZodObject<{

package/dist/deployment/lifecycleCompletionContracts.js

@@ -7,6 +7,11 @@ export const LIFECYCLE_OWNER_VERSION = "spawnfile.lifecycle-owner.v1";
 export const LIFECYCLE_ADMISSION_VERSION = "spawnfile.lifecycle-admission.v1";
 export const LIFECYCLE_AMBIGUOUS_VERSION = "spawnfile.lifecycle-ambiguous.v1";
 export const LIFECYCLE_TERMINAL_VERSION = "spawnfile.lifecycle-terminal.v1";
+export const LIFECYCLE_UP_START_VERSION = "spawnfile.lifecycle-up-start.v1";
+export const LIFECYCLE_UP_RESERVATION_VERSION = "spawnfile.lifecycle-up-reservation.v1";
+export const LIFECYCLE_UP_CLEANUP_VERSION = "spawnfile.lifecycle-up-cleanup.v1";
+// Docker carries an image's config labels onto a container; no other extras are allowed.
+export const LIFECYCLE_UP_EXTRA_LABELS = "image-config-labels";
 export const LIFECYCLE_RECORD_MAX_BYTES = 1_000_000;
 export const lifecycleIdSchema = z
     .string()
@@ -70,6 +75,35 @@ export const lifecycleCompletionSchema = z
     version: z.literal(LIFECYCLE_COMPLETION_VERSION),
 })
     .strict();
+const lifecycleUpLabelAuthoritySchema = z.object({
+    required: z.record(z.string().min(1).max(255), z.string().max(4096)),
+    permitted_extra_labels: z.literal(LIFECYCLE_UP_EXTRA_LABELS),
+}).strict();
+export const lifecycleUpReservationSchema = z.object({
+    container_name: z.string().min(1).max(255),
+    docker_command: z.string().min(1).max(4096),
+    docker_context: z.string().min(1).max(128).nullable(),
+    invocation: lifecycleInvocationSchema,
+    label_authority: lifecycleUpLabelAuthoritySchema,
+    version: z.literal(LIFECYCLE_UP_RESERVATION_VERSION),
+}).strict();
+export const lifecycleUpStartSchema = z
+    .object({
+    attempt: z.number().int().min(0).max(16),
+    container_id: z.string().regex(/^[a-f0-9]{64}$/u),
+    container_name: z.string().min(1).max(255),
+    image_id: z.string().regex(/^sha256:[a-f0-9]{64}$/u),
+    invocation: lifecycleInvocationSchema,
+    label_authority: lifecycleUpLabelAuthoritySchema,
+    version: z.literal(LIFECYCLE_UP_START_VERSION),
+})
+    .strict();
+export const lifecycleUpCleanupSchema = z.object({
+    attempt: z.number().int().min(0).max(16),
+    container_id: z.string().regex(/^[a-f0-9]{64}$/u),
+    invocation: lifecycleInvocationSchema,
+    version: z.literal(LIFECYCLE_UP_CLEANUP_VERSION),
+}).strict();
 export const lifecycleTerminalSchema = z.discriminatedUnion("status", [
     z
         .object({

package/dist/deployment/lifecycleCompletionPaths.d.ts

@@ -1,9 +1,12 @@
 export declare const failLifecycleStore: (message: string) => never;
 export declare const resolveLifecycleCompletionDirectory: () => string;
-export declare const lifecycleRecordName: (id: string, kind: "admission" | "completion" | "evidence" | "plan" | "recovery") => string;
+export declare const lifecycleRecordName: (id: string, kind: "admission" | "completion" | "evidence" | "plan" | "recovery" | "up-reservation") => string;
 export declare const resolveLifecycleCompletionPath: (id: string) => string;
 export declare const admissionPath: (id: string) => string;
 export declare const planPath: (id: string) => string;
 export declare const recoveryPath: (id: string) => string;
 export declare const evidencePath: (id: string) => string;
+export declare const upReservationPath: (id: string) => string;
+export declare const upStartPath: (id: string, attempt: number) => string;
+export declare const upCleanupPath: (id: string, attempt: number) => string;
 export declare const heartbeatPath: (id: string) => string;

package/dist/deployment/lifecycleCompletionPaths.js

@@ -13,4 +13,7 @@ export const admissionPath = (id) => lifecyclePath(id, "admission");
 export const planPath = (id) => lifecyclePath(id, "plan");
 export const recoveryPath = (id) => lifecyclePath(id, "recovery");
 export const evidencePath = (id) => lifecyclePath(id, "evidence");
+export const upReservationPath = (id) => lifecyclePath(id, "up-reservation");
+export const upStartPath = (id, attempt) => path.join(resolveLifecycleCompletionDirectory(), `${lifecycleIdSchema.parse(id)}.up-start-${attempt}`);
+export const upCleanupPath = (id, attempt) => path.join(resolveLifecycleCompletionDirectory(), `${lifecycleIdSchema.parse(id)}.up-cleanup-${attempt}`);
 export const heartbeatPath = (id) => path.join(resolveLifecycleCompletionDirectory(), `${lifecycleIdSchema.parse(id)}.heartbeat`);

package/dist/deployment/lifecycleCompletionPublication.d.ts

@@ -1,5 +1,7 @@
 type RecordReader = (file: string, links?: readonly number[]) => Promise<string | null>;
+export declare const LIFECYCLE_PUBLICATION_SETTLE_TIMEOUT_MS = 1000;
 export declare const settleLifecyclePublication: (file: string) => Promise<void>;
+export declare const settleLifecyclePublicationUntil: (settled: () => Promise<boolean>) => Promise<void>;
 export declare const readSettledLifecycleRecord: (file: string, read: RecordReader) => Promise<string | null>;
 export declare const matchesSettledLifecyclePublication: (file: string, expected: string, read: RecordReader) => Promise<boolean>;
 export {};

package/dist/deployment/lifecycleCompletionPublication.js

@@ -1,16 +1,30 @@
 import { lstat } from "node:fs/promises";
+import { performance } from "node:perf_hooks";
 import { SpawnfileError } from "../shared/index.js";
+// A competing publisher removes its temporary hard link asynchronously.  A
+// short run of event-loop turns can elapse before that unlink is scheduled
+// when many lifecycle operations are active, so leave a bounded but practical
+// window before treating an extra link as hostile.
+export const LIFECYCLE_PUBLICATION_SETTLE_TIMEOUT_MS = 1_000;
+const LIFECYCLE_PUBLICATION_SETTLE_BACKOFF_MS = 2;
 const refuse = (message) => {
     throw new SpawnfileError("runtime_error", `Lifecycle completion store refused: ${message}`);
 };
 export const settleLifecyclePublication = async (file) => {
-    for (let attempt = 0; attempt < 16; attempt += 1) {
+    await settleLifecyclePublicationUntil(async () => {
         const info = await lstat(file).catch(() => refuse("publication changed"));
-        if (info.nlink === 1)
+        return info.nlink === 1;
+    });
+};
+export const settleLifecyclePublicationUntil = async (settled) => {
+    const deadline = performance.now() + LIFECYCLE_PUBLICATION_SETTLE_TIMEOUT_MS;
+    while (true) {
+        if (await settled())
             return;
-        await new Promise((resolve) => setImmediate(resolve));
+        if (performance.now() >= deadline)
+            refuse("publication did not settle");
+        await new Promise((resolve) => setTimeout(resolve, LIFECYCLE_PUBLICATION_SETTLE_BACKOFF_MS));
     }
-    refuse("publication did not settle");
 };
 export const readSettledLifecycleRecord = async (file, read) => {
     const text = await read(file, [1, 2]);

package/dist/deployment/lifecycleCompletionStore.d.ts

@@ -1,4 +1,4 @@
-export { admissionPath, evidencePath, failLifecycleStore, heartbeatPath, lifecycleRecordName, planPath, recoveryPath, resolveLifecycleCompletionDirectory, resolveLifecycleCompletionPath } from "./lifecycleCompletionPaths.js";
+export { admissionPath, evidencePath, failLifecycleStore, heartbeatPath, lifecycleRecordName, planPath, recoveryPath, upCleanupPath, upReservationPath, upStartPath, resolveLifecycleCompletionDirectory, resolveLifecycleCompletionPath } from "./lifecycleCompletionPaths.js";
 export { existingLifecycleRoot, lifecycleRoot, syncLifecycleDirectory } from "./lifecycleCompletionRoot.js";
 export type LifecycleStoreTestHookPoint = "before_missing_return" | "before_record_open" | "before_publish_link" | "before_publish_temp_open" | "before_publish_unlink";
 export declare const setLifecycleStoreTestHook: (hook: ((point: LifecycleStoreTestHookPoint) => Promise<void> | void) | null) => void;