spawnfile 0.1.14 → 0.1.17

package/dist/deployment/dockerManager.js

@@ -151,7 +151,7 @@ export const probeDockerOrganizationReadiness = async (input) => {
             timeoutMs: input.timeoutMs
         });
         const inspection = await gateway.inspectUnit();
-        if (input.evidence.hasExternalMoltnet || !input.evidence.worldBindings) {
+        if (input.evidence.hasExternalMoltnet) {
             return reconcileOrganizationReadiness({
                 evidence: input.evidence, inspection, probe: null, record: correlation
             });
@@ -173,17 +173,23 @@ export const probeDockerOrganizationReadiness = async (input) => {
             });
         }
         const configs = new Map();
+        const attachmentReceipts = new Map();
         for (const network of input.evidence.networks) {
             for (const node of network.nodes) {
                 const result = await gateway.exec(["cat", node.configPath]);
                 configs.set(node.configPath, result.stdout);
+                const receipt = await gateway.exec(["cat", node.receiptPath]);
+                attachmentReceipts.set(node.receiptPath, receipt.stdout);
             }
         }
-        const bindings = await gateway.exec(["cat", input.evidence.worldBindings.artifactPath]);
+        const daimonReceipt = input.evidence.daimon == null ? null : (await gateway.exec(["cat", input.evidence.daimon.receiptPath])).stdout;
+        const bindings = input.evidence.worldBindings === null
+            ? null
+            : await gateway.exec(["cat", input.evidence.worldBindings.artifactPath]);
         return reconcileOrganizationReadiness({
             evidence: input.evidence,
             inspection,
-            probe: { configs, networks, worldBindings: bindings.stdout },
+            probe: { attachmentReceipts, configs, daimonReceipt, networks, worldBindings: bindings?.stdout ?? null },
             record: correlation
         });
     }

package/dist/deployment/dockerProbeGateway.d.ts

@@ -1,7 +1,21 @@
 import type { RuntimeProbeGateway } from "../runtime/index.js";
 import type { DeploymentRecord } from "./record.js";
 import type { DockerUnitInspection } from "./dockerInspect.js";
+/**
+ * The ledger this gateway reads (`spawnfile usage`) rotates once a generation
+ * reaches `DAIMON_GROK_TURN_USAGE_LEDGER.rotateBytes`, and rotation happens on
+ * the append *after* that threshold is crossed — so a rotated generation is
+ * always at least the bound and the crossing line pushes it over. A maxBuffer
+ * merely equal to the bound therefore rejects the exact read this feature
+ * exists to perform (Node's `execFile` accepts a payload of exactly
+ * `maxBuffer` bytes and fails the next one with
+ * `ERR_CHILD_PROCESS_STDIO_MAXBUFFER`). Doubling the bound leaves a full
+ * generation of headroom, and is derived from the ledger constant rather than
+ * restated so the two cannot drift apart.
+ */
+export declare const DEFAULT_DOCKER_PROBE_MAX_BUFFER_BYTES: number;
 export type DockerProbeExecFile = (file: string, args: string[], options: {
+    maxBuffer?: number;
     timeout: number;
 }) => Promise<{
     stderr: string;
@@ -11,6 +25,9 @@ export interface DockerProbeGatewayOptions {
     dockerCommand?: string;
     execFile?: DockerProbeExecFile;
     inspection: DockerUnitInspection;
+    /** Overrides Node's 1 MiB `execFile` default `maxBuffer`. Defaults to
+     * {@link DEFAULT_DOCKER_PROBE_MAX_BUFFER_BYTES}. */
+    maxBufferBytes?: number;
     timeoutMs?: number;
 }
 export declare const createDockerProbeGateway: (record: DeploymentRecord, unit: DeploymentRecord["units"][number], options: DockerProbeGatewayOptions) => RuntimeProbeGateway;

package/dist/deployment/dockerProbeGateway.js

@@ -1,7 +1,21 @@
 import { execFile as execFileCallback } from "node:child_process";
 import { promisify } from "node:util";
+import { DAIMON_GROK_TURN_USAGE_LEDGER } from "../runtime/daimon/contractManifest.js";
 import { dockerContextNameForTarget } from "./target.js";
 const execFile = promisify(execFileCallback);
+/**
+ * The ledger this gateway reads (`spawnfile usage`) rotates once a generation
+ * reaches `DAIMON_GROK_TURN_USAGE_LEDGER.rotateBytes`, and rotation happens on
+ * the append *after* that threshold is crossed — so a rotated generation is
+ * always at least the bound and the crossing line pushes it over. A maxBuffer
+ * merely equal to the bound therefore rejects the exact read this feature
+ * exists to perform (Node's `execFile` accepts a payload of exactly
+ * `maxBuffer` bytes and fails the next one with
+ * `ERR_CHILD_PROCESS_STDIO_MAXBUFFER`). Doubling the bound leaves a full
+ * generation of headroom, and is derived from the ledger constant rather than
+ * restated so the two cannot drift apart.
+ */
+export const DEFAULT_DOCKER_PROBE_MAX_BUFFER_BYTES = 2 * DAIMON_GROK_TURN_USAGE_LEDGER.rotateBytes;
 const targetRefForUnit = (unit) => {
     const targetRef = unit.container_id ?? unit.container_name;
     if (!targetRef) {
@@ -80,9 +94,10 @@ export const createDockerProbeGateway = (record, unit, options) => {
     const dockerCommand = options.dockerCommand ?? "docker";
     const runExec = options.execFile ?? execFile;
     const timeout = options.timeoutMs ?? 10_000;
+    const maxBuffer = options.maxBufferBytes ?? DEFAULT_DOCKER_PROBE_MAX_BUFFER_BYTES;
     const exec = async (command) => {
         const targetRef = targetRefForUnit(unit);
-        return runExec(dockerCommand, withDockerTarget(record, ["exec", targetRef, ...command]), { timeout });
+        return runExec(dockerCommand, withDockerTarget(record, ["exec", targetRef, ...command]), { maxBuffer, timeout });
     };
     return {
         exec,
@@ -93,7 +108,7 @@ export const createDockerProbeGateway = (record, unit, options) => {
             const url = `http://127.0.0.1:${port}${requestPath.startsWith("/") ? requestPath : `/${requestPath}`}`;
             try {
                 const targetRef = targetRefForUnit(unit);
-                const result = await runExec(dockerCommand, withDockerTarget(record, httpProbeArgs(targetRef, imageRefForUnit(unit), url)), { timeout });
+                const result = await runExec(dockerCommand, withDockerTarget(record, httpProbeArgs(targetRef, imageRefForUnit(unit), url)), { maxBuffer, timeout });
                 return parseCurlHttpOutput(result.stdout);
             }
             catch (error) {

package/dist/deployment/downDeployment.d.ts

@@ -1,6 +1,7 @@
 import { type DeploymentLifecycleCorrelation } from "./deploymentLifecycleCorrelation.js";
 import { type DockerTeardownExecFile } from "./dockerTeardown.js";
 import { type DownReceipt } from "./downReceiptTypes.js";
+import type { DeploymentRecord } from "./record.js";
 export interface DownDeploymentOptions {
     /** Where the deployment record + compile report already live (the compile's own
      * `--out` directory) — same convention as `exportRunArtifacts`'s `compiledOutputDirectory`. */
@@ -23,6 +24,10 @@ export interface DownDeploymentOptions {
     expectedLifecycleCorrelation?: DeploymentLifecycleCorrelation;
     timeoutMs?: number;
 }
+export declare const readCanonicalDownRecord: (compiledOutputDirectory: string, deploymentName: string) => Promise<{
+    mode: "image" | "project";
+    record: DeploymentRecord;
+}>;
 /**
  * `spawnfile down` — record-driven teardown: resolves the deployment record, enforces the
  * export-before-teardown invariant, `docker rm -f`s every recorded container unit, and

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,102 @@ import { defaultDockerTeardownExecFile, removeDockerContainer, removeDockerVolum
 import { DOWN_RECEIPT_VERSION } from "./downReceiptTypes.js";
 import { initializeOrganizationHandoffAuthorityStore, } from "./organizationHandoffAuthorityStore.js";
 import { readDeploymentRecordFromOutput } from "./record.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));
+    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 +192,18 @@ 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 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) {
@@ -121,12 +221,12 @@ export const downDeployment = async (options) => {
         }
     }
     const report = await readCompileReport(compiledOutputDirectory);
-    const volumeNames = [
-        ...new Set((report?.container?.persistent_mounts ?? []).map((mount) => mount.volume_name)),
-    ].sort();
-    const retainedVolumes = [];
+    const { owned, skipped } = partitionDeclaredVolumes(report?.container?.persistent_mounts ?? [], (mount) => mount.volume_name);
+    // 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 +235,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/index.d.ts

@@ -4,6 +4,7 @@ export * from "./artifactsExportPlan.js";
 export * from "./artifactsExportTypes.js";
 export * from "./privateArtifactsExport.js";
 export * from "./buildImageCacheStore.js";
+export * from "./candidateDiagnostics.js";
 export * from "./dockerLabels.js";
 export * from "./dockerInspect.js";
 export * from "./dockerLogs.js";
@@ -16,11 +17,14 @@ 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 "./canaryCutover.js";
+export * from "./productStateClone.js";
 export * from "./record.js";
 export * from "./target.js";
 export * from "./upReceiptTypes.js";

package/dist/deployment/index.js

@@ -4,6 +4,7 @@ export * from "./artifactsExportPlan.js";
 export * from "./artifactsExportTypes.js";
 export * from "./privateArtifactsExport.js";
 export * from "./buildImageCacheStore.js";
+export * from "./candidateDiagnostics.js";
 export * from "./dockerLabels.js";
 export * from "./dockerInspect.js";
 export * from "./dockerLogs.js";
@@ -16,11 +17,14 @@ 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 "./canaryCutover.js";
+export * from "./productStateClone.js";
 export * from "./record.js";
 // Compatibility target exports remain available from this legacy deployment barrel.
 export * from "./target.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;