spawnfile 0.1.13 → 0.1.17

package/dist/deployment/productStateClone.js

@@ -0,0 +1,319 @@
+import { constants } from "node:fs";
+import { chmod, copyFile, link, mkdir, open, readFile, readdir, rename, rm, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+import path from "node:path";
+import { z } from "zod";
+import { SpawnfileError } from "../shared/index.js";
+const digest = z.string().regex(/^sha256:[a-f0-9]{64}$/u);
+const relative = z.string().min(1).max(255).refine((value) => !path.isAbsolute(value) && !value.split(/[\\/]/u).includes(".."));
+const proofSchema = z.object({ version: z.literal("spawnfile.product-state-quiescence.v1"), state: z.literal("quiesced"), source_run_id: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/u), files: z.array(z.object({ path: relative, sha256: digest }).strict()).min(1).max(4096) }).strict();
+const forbidden = /(?:^|[._/-])(?:auth|credential|token|secret|session|wake)(?:[._/-]|$)|\.(?:db|sqlite|sqlite3)(?:-|$)/iu;
+const execFile = promisify(execFileCallback);
+const authoritySchema = z.object({ version: z.literal("spawnfile.product-state-source-authority.v1"), source_run_id: z.string(), container_id: z.string().regex(/^[a-f0-9]{64}$/u), image_id: z.string().regex(/^sha256:[a-f0-9]{64}$/u), started_at: z.string().min(1), was_paused: z.boolean(), source: z.string().min(1), mount_path: z.string().min(1), volume_name: z.string().min(1), candidate_volume_name: z.string().min(1), candidate_resource_identity: digest }).strict();
+const defaultDockerExec = async (command, args) => await execFile(command, args, { encoding: "utf8", maxBuffer: 1_048_576, timeout: 10_000 });
+const inspectContainer = async (docker, command, container) => { const value = JSON.parse((await docker(command, ["inspect", container])).stdout); if (!Array.isArray(value) || value.length !== 1 || typeof value[0] !== "object")
+    throw new SpawnfileError("validation_error", "Managed source container inspection failed"); return value[0]; };
+const restoreRunningState = async (docker, command, authority) => {
+    await docker(command, ["unpause", authority.container_id]);
+    const restored = await inspectContainer(docker, command, authority.container_id);
+    if (restored.Id !== authority.container_id || restored.Image !== authority.image_id || restored.State?.StartedAt !== authority.started_at || restored.State?.Running !== true || restored.State?.Paused !== false)
+        throw new SpawnfileError("validation_error", "Managed source state restoration could not be proven");
+};
+export const issueProductStateSourceAuthority = async (input, docker = defaultDockerExec) => {
+    const inspected = await inspectContainer(docker, input.dockerCommand, input.container), labels = inspected.Config?.Labels, state = inspected.State;
+    const mounts = Array.isArray(inspected.Mounts) ? inspected.Mounts.filter((mount) => mount.Type === "volume" && mount.Destination === input.mountPath && mount.RW === true) : [];
+    if (inspected.Id?.length !== 64 || !/^sha256:[a-f0-9]{64}$/u.test(inspected.Image) || labels?.["com.spawnfile.run_id"] !== input.sourceRunId || state?.Running !== true || typeof state.StartedAt !== "string" || mounts.length !== 1 || typeof mounts[0].Source !== "string" || typeof mounts[0].Name !== "string")
+        throw new SpawnfileError("validation_error", "Source run does not own one exact managed writable state root");
+    const volume = JSON.parse((await docker(input.dockerCommand, ["volume", "inspect", input.candidateVolumeName])).stdout);
+    if (!Array.isArray(volume) || volume.length !== 1 || typeof volume[0]?.Mountpoint !== "string")
+        throw new SpawnfileError("validation_error", "Candidate volume is unavailable");
+    return authoritySchema.parse({ version: "spawnfile.product-state-source-authority.v1", source_run_id: input.sourceRunId, container_id: inspected.Id, image_id: inspected.Image, started_at: state.StartedAt, was_paused: state.Paused === true, source: mounts[0].Source, mount_path: input.mountPath, volume_name: mounts[0].Name, candidate_volume_name: input.candidateVolumeName, candidate_resource_identity: input.candidateResourceIdentity });
+};
+const hashFile = async (file) => {
+    const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || info.size > 67_108_864)
+            throw new SpawnfileError("validation_error", "Product state file is unsafe or oversized");
+        return `sha256:${createHash("sha256").update(await handle.readFile()).digest("hex")}`;
+    }
+    finally {
+        await handle.close();
+    }
+};
+const syncDirectory = async (directory) => { const handle = await open(directory, constants.O_RDONLY); try {
+    await handle.sync();
+}
+finally {
+    await handle.close();
+} };
+const syncTreeDirectories = async (directory) => { for (const entry of await readdir(directory, { withFileTypes: true }))
+    if (entry.isDirectory())
+        await syncTreeDirectories(path.join(directory, entry.name)); await syncDirectory(directory); };
+const wholeSourceManifest = async (root) => {
+    const result = new Map();
+    const visit = async (directory, prefix) => {
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if ([".spawnfile-product-state-write-fence", ".spawnfile-product-state-preseed-journal", ".spawnfile-resource-identity"].includes(relativePath))
+                continue;
+            const absolutePath = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                await visit(absolutePath, relativePath);
+                continue;
+            }
+            if (!entry.isFile() || result.size >= 4096)
+                throw new SpawnfileError("validation_error", "Product-state source contains an unsafe or excessive entry");
+            result.set(relativePath, await hashFile(absolutePath));
+        }
+    };
+    await visit(root, "");
+    return result;
+};
+const verifyWholeSourceManifest = async (root, proof) => {
+    const actual = await wholeSourceManifest(root), expected = new Map(proof.files.map((entry) => [entry.path, entry.sha256]));
+    if (actual.size !== expected.size || [...actual].some(([name, checksum]) => expected.get(name) !== checksum))
+        throw new SpawnfileError("validation_error", "Whole product-state source manifest drifted or is incomplete");
+};
+export const createProductStateProof = async (source, sourceRunId) => {
+    const manifest = await wholeSourceManifest(source);
+    const files = [...manifest].sort(([left], [right]) => left.localeCompare(right)).map(([filePath, sha256]) => { if (forbidden.test(filePath))
+        throw new SpawnfileError("validation_error", "Product-state source includes prohibited state"); return { path: filePath, sha256 }; });
+    return proofSchema.parse({ version: "spawnfile.product-state-quiescence.v1", state: "quiesced", source_run_id: sourceRunId, files });
+};
+export const issueProductStateSourceSnapshot = async (input, docker = defaultDockerExec) => {
+    const authority = authoritySchema.parse(await issueProductStateSourceAuthority(input, docker));
+    let pausedByUs = false;
+    try {
+        if (!authority.was_paused) {
+            await docker(input.dockerCommand, ["pause", authority.container_id]);
+            pausedByUs = true;
+        }
+        const frozen = await inspectContainer(docker, input.dockerCommand, authority.container_id);
+        if (frozen.Id !== authority.container_id || frozen.Image !== authority.image_id || frozen.State?.StartedAt !== authority.started_at || frozen.State?.Paused !== true)
+            throw new SpawnfileError("validation_error", "Source changed before authoritative snapshot");
+        return { authority, proof: await createProductStateProof(authority.source, authority.source_run_id) };
+    }
+    finally {
+        if (pausedByUs)
+            await restoreRunningState(docker, input.dockerCommand, authority);
+    }
+};
+export const cloneQuiescedProductState = async (input) => {
+    const proof = proofSchema.parse(input.proof);
+    if (proof.source_run_id === input.candidateRunId)
+        throw new SpawnfileError("validation_error", "Candidate state namespace must differ from source");
+    const destinationExists = await stat(input.destination).then((info) => { if (!info.isDirectory())
+        throw new SpawnfileError("validation_error", "Candidate state destination is not a directory"); return true; }, (error) => error.code === "ENOENT" ? false : Promise.reject(error));
+    const journalPath = path.join(input.destination, ".spawnfile-product-state-preseed-journal");
+    if (destinationExists && await stat(journalPath).then(() => true, () => false)) {
+        const journal = z.object({ version: z.literal("spawnfile.product-state-preseed-journal.v1"), candidate_run_id: z.string(), entries: z.array(relative), staging: relative }).strict().parse(JSON.parse(await readFile(journalPath, "utf8")));
+        if (journal.candidate_run_id !== input.candidateRunId)
+            throw new SpawnfileError("validation_error", "Candidate preseed journal belongs to another run");
+        const identityPath = path.join(input.destination, ".spawnfile-resource-identity"), activated = input.activationIdentity && await readFile(identityPath, "utf8").then((value) => value === `${input.activationIdentity}\n`, () => false);
+        if (activated) {
+            await verifyWholeSourceManifest(input.destination, proof);
+            await rm(journalPath);
+            await syncDirectory(input.destination);
+            return { files: proof.files.length, source_run_id: proof.source_run_id, candidate_run_id: input.candidateRunId };
+        }
+        for (const entry of [...journal.entries, journal.staging])
+            await rm(path.join(input.destination, entry), { recursive: true, force: true });
+        await rm(journalPath);
+        await syncDirectory(input.destination);
+    }
+    if (destinationExists && (await readdir(input.destination)).length !== 0)
+        throw new SpawnfileError("validation_error", "Candidate state destination is not empty");
+    const names = new Set();
+    for (const entry of proof.files) {
+        if (forbidden.test(entry.path) || names.has(entry.path))
+            throw new SpawnfileError("validation_error", "Product-state classification contains a prohibited or duplicate path");
+        names.add(entry.path);
+        if (await hashFile(path.join(input.source, entry.path)) !== entry.sha256)
+            throw new SpawnfileError("validation_error", "Quiesced product-state checksum mismatch");
+    }
+    const temporary = destinationExists ? path.join(input.destination, `.spawnfile-preseed-${process.pid}`) : `${input.destination}.candidate-${process.pid}`;
+    await mkdir(temporary, { recursive: false, mode: 0o700 });
+    const activated = [];
+    try {
+        for (const entry of proof.files) {
+            const target = path.join(temporary, entry.path);
+            await mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+            await copyFile(path.join(input.source, entry.path), target, constants.COPYFILE_EXCL);
+            const copied = await open(target, constants.O_RDONLY);
+            try {
+                await copied.sync();
+            }
+            finally {
+                await copied.close();
+            }
+            if (await hashFile(target) !== entry.sha256 || await hashFile(path.join(input.source, entry.path)) !== entry.sha256)
+                throw new SpawnfileError("validation_error", "Product state changed during clone");
+        }
+        await syncTreeDirectories(temporary);
+        if (destinationExists) {
+            const entries = await readdir(temporary), journal = await open(journalPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+            try {
+                await journal.writeFile(`${JSON.stringify({ version: "spawnfile.product-state-preseed-journal.v1", candidate_run_id: input.candidateRunId, entries, staging: path.basename(temporary) })}\n`);
+                await journal.sync();
+            }
+            finally {
+                await journal.close();
+            }
+            await syncDirectory(input.destination);
+            for (const entry of entries) {
+                await rename(path.join(temporary, entry), path.join(input.destination, entry));
+                activated.push(path.join(input.destination, entry));
+                await syncDirectory(input.destination);
+            }
+            await rm(temporary, { recursive: true });
+            await syncDirectory(input.destination);
+            await verifyWholeSourceManifest(input.destination, proof);
+            if (input.activationIdentity) {
+                const identity = await open(path.join(input.destination, ".spawnfile-resource-identity"), constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+                try {
+                    await identity.writeFile(`${input.activationIdentity}\n`);
+                    await identity.sync();
+                }
+                finally {
+                    await identity.close();
+                }
+                await syncDirectory(input.destination);
+            }
+            await rm(journalPath);
+            await syncDirectory(input.destination);
+        }
+        else {
+            await rename(temporary, input.destination);
+            await syncDirectory(path.dirname(input.destination));
+        }
+    }
+    catch (error) {
+        if (input.activationIdentity) {
+            await rm(path.join(input.destination, ".spawnfile-resource-identity"), { force: true });
+            if (destinationExists)
+                await syncDirectory(input.destination);
+        }
+        for (const entry of activated.reverse()) {
+            await rm(entry, { recursive: true, force: true });
+            if (destinationExists)
+                await syncDirectory(input.destination);
+        }
+        await rm(temporary, { recursive: true, force: true });
+        await syncDirectory(destinationExists ? input.destination : path.dirname(input.destination));
+        await rm(journalPath, { force: true });
+        if (destinationExists)
+            await syncDirectory(input.destination);
+        throw error;
+    }
+    return { files: proof.files.length, source_run_id: proof.source_run_id, candidate_run_id: input.candidateRunId };
+};
+export const runProductStateCloneWorkflow = async (input, docker = defaultDockerExec) => {
+    const authority = authoritySchema.parse(JSON.parse(await readFile(input.authorityReceiptPath, "utf8")));
+    const candidateVolume = JSON.parse((await docker(input.dockerCommand, ["volume", "inspect", authority.candidate_volume_name])).stdout);
+    if (!Array.isArray(candidateVolume) || candidateVolume.length !== 1 || candidateVolume[0]?.Mountpoint !== path.resolve(input.destination))
+        throw new SpawnfileError("validation_error", "Clone destination is not the attested candidate volume");
+    const current = await inspectContainer(docker, input.dockerCommand, authority.container_id), currentMounts = Array.isArray(current.Mounts) ? current.Mounts : [];
+    if (current.Id !== authority.container_id || current.Image !== authority.image_id || current.State?.StartedAt !== authority.started_at || current.Config?.Labels?.["com.spawnfile.run_id"] !== authority.source_run_id || current.State?.Running !== true || current.State?.Paused !== authority.was_paused || !currentMounts.some((mount) => mount.Type === "volume" && mount.Name === authority.volume_name && mount.Source === authority.source && mount.Destination === authority.mount_path && mount.RW === true))
+        throw new SpawnfileError("validation_error", "Source run authority is stale or rebound");
+    const proofBytes = await readFile(input.proofPath);
+    if (proofBytes.length > 1_048_576)
+        throw new SpawnfileError("validation_error", "Product-state proof is oversized");
+    const proof = proofSchema.parse(JSON.parse(proofBytes.toString("utf8")));
+    if (proof.source_run_id !== authority.source_run_id)
+        throw new SpawnfileError("validation_error", "Proof source run does not match managed authority");
+    const fencePath = path.join(authority.source, ".spawnfile-product-state-write-fence");
+    const fence = await open(fencePath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o400);
+    const modes = [];
+    let pausedByUs = false;
+    try {
+        await fence.writeFile(`${proof.source_run_id}\n`);
+        await fence.sync();
+        if (!authority.was_paused) {
+            await docker(input.dockerCommand, ["pause", authority.container_id]);
+            pausedByUs = true;
+        }
+        const frozen = await inspectContainer(docker, input.dockerCommand, authority.container_id);
+        if (frozen.State?.Paused !== true || frozen.State?.StartedAt !== authority.started_at || frozen.Id !== authority.container_id)
+            throw new SpawnfileError("validation_error", "Managed source cgroup did not freeze exactly");
+        await verifyWholeSourceManifest(authority.source, proof);
+        for (const entry of proof.files) {
+            if (forbidden.test(entry.path))
+                throw new SpawnfileError("validation_error", "Product-state classification contains a prohibited path");
+            const file = path.join(authority.source, entry.path), info = await stat(file);
+            modes.push({ file, mode: info.mode & 0o777 });
+            await chmod(file, info.mode & ~0o222);
+        }
+        const cloned = await cloneQuiescedProductState({ source: authority.source, destination: input.destination, proof, candidateRunId: input.candidateRunId, activationIdentity: authority.candidate_resource_identity });
+        await verifyWholeSourceManifest(authority.source, proof);
+        await verifyWholeSourceManifest(input.destination, proof);
+        const receipt = { version: "spawnfile.product-state-clone-receipt.v1", ...cloned, proof_sha256: `sha256:${createHash("sha256").update(proofBytes).digest("hex")}`, destination: path.resolve(input.destination), candidate_volume_name: authority.candidate_volume_name, source_container_id: authority.container_id };
+        const temporaryReceipt = `${input.receiptPath}.tmp-${process.pid}`;
+        await mkdir(path.dirname(input.receiptPath), { recursive: true, mode: 0o700 });
+        let published = false;
+        try {
+            const receiptFile = await open(temporaryReceipt, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+            try {
+                await receiptFile.writeFile(`${JSON.stringify(receipt)}\n`);
+                await receiptFile.sync();
+            }
+            finally {
+                await receiptFile.close();
+            }
+            await link(temporaryReceipt, input.receiptPath);
+            published = true;
+            const receiptDirectory = await open(path.dirname(input.receiptPath), constants.O_RDONLY);
+            try {
+                await receiptDirectory.sync();
+            }
+            finally {
+                await receiptDirectory.close();
+            }
+            await rm(temporaryReceipt);
+            await syncDirectory(path.dirname(input.receiptPath));
+        }
+        catch (error) {
+            await rm(temporaryReceipt, { force: true });
+            await syncDirectory(path.dirname(input.receiptPath));
+            if (published) {
+                await rm(input.receiptPath, { force: true });
+                await syncDirectory(path.dirname(input.receiptPath));
+            }
+            for (const entry of await readdir(input.destination)) {
+                await rm(path.join(input.destination, entry), { recursive: true, force: true });
+                await syncDirectory(input.destination);
+            }
+            throw error;
+        }
+        return receipt;
+    }
+    finally {
+        let restorationError;
+        for (const item of modes.reverse())
+            try {
+                await chmod(item.file, item.mode);
+            }
+            catch (error) {
+                restorationError ??= error;
+            }
+        try {
+            await fence.close();
+            await rm(fencePath, { force: true });
+            await syncDirectory(authority.source);
+        }
+        catch (error) {
+            restorationError ??= error;
+        }
+        try {
+            if (pausedByUs)
+                await restoreRunningState(docker, input.dockerCommand, authority);
+        }
+        catch (error) {
+            restorationError ??= error;
+        }
+        if (restorationError)
+            throw new SpawnfileError("validation_error", "Product-state source restoration failed", { cause: restorationError });
+    }
+};

package/dist/deployment/record.d.ts

@@ -1,4 +1,7 @@
 import { z } from "zod";
+import { type OrganizationHandoff } from "./organizationHandoffTypes.js";
+import { type OpaqueTargetHandle } from "../target/index.js";
+import { type OrganizationReadiness } from "./organizationReady.js";
 declare const recordSourceSchema: z.ZodUnion<readonly [z.ZodObject<{
     kind: z.ZodLiteral<"project">;
     root: z.ZodString;
@@ -15,7 +18,10 @@ export declare const deploymentRecordSchema: z.ZodObject<{
     env_file: z.ZodOptional<z.ZodString>;
     manager: z.ZodString;
     name: z.ZodString;
+    organization_handoff: z.ZodOptional<z.ZodUnknown>;
+    organization_handoff_handle: z.ZodOptional<z.ZodString>;
     output_directory: z.ZodNullable<z.ZodString>;
+    run_id: z.ZodOptional<z.ZodString>;
     source: z.ZodUnion<readonly [z.ZodObject<{
         kind: z.ZodLiteral<"project">;
         root: z.ZodString;
@@ -63,8 +69,27 @@ export declare const deploymentRecordSchema: z.ZodObject<{
         }, z.core.$strict>]>>;
     }, z.core.$strict>>;
     version: z.ZodLiteral<"spawnfile.deployment.v2">;
+    export_index: z.ZodOptional<z.ZodObject<{
+        exported_at: z.ZodString;
+        path: z.ZodString;
+        run_id: z.ZodString;
+    }, z.core.$strict>>;
+    organization_ready: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
+        code: z.ZodUnion<readonly [z.ZodLiteral<"organization_ready">, z.ZodLiteral<"external_moltnet">, z.ZodLiteral<"compiled_evidence_missing">, z.ZodLiteral<"unit_unavailable">, z.ZodLiteral<"unit_restarted">, z.ZodLiteral<"probe_unavailable">, z.ZodLiteral<"identity_mismatch">, z.ZodLiteral<"topology_mismatch">, z.ZodLiteral<"probe_timeout">, z.ZodLiteral<"probe_cancelled">]>;
+        compile_fingerprint: z.ZodString;
+        run_id: z.ZodNullable<z.ZodString>;
+        state: z.ZodUnion<readonly [z.ZodLiteral<"ready">, z.ZodLiteral<"pending">, z.ZodLiteral<"failed">, z.ZodLiteral<"cancelled">]>;
+        unit_id: z.ZodString;
+        version: z.ZodLiteral<"spawnfile.organization-ready.v1">;
+        world_binding_digest: z.ZodNullable<z.ZodString>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
 }, z.core.$strict>;
-export type DeploymentRecord = z.infer<typeof deploymentRecordSchema>;
+export type DeploymentRecord = Omit<z.infer<typeof deploymentRecordSchema>, "organization_handoff" | "organization_handoff_handle" | "organization_ready"> & {
+    organization_handoff?: OrganizationHandoff;
+    organization_handoff_handle?: OpaqueTargetHandle;
+    organization_ready?: OrganizationReadiness;
+};
 export declare const parseDeploymentRecord: (source: unknown, sourceLabel?: string) => DeploymentRecord;
 export declare const readDeploymentRecord: (recordPath: string) => Promise<DeploymentRecord>;
 export declare const readDeploymentRecordFromOutput: (outputDirectory: string, deploymentName: string) => Promise<DeploymentRecord>;

package/dist/deployment/record.js

@@ -3,7 +3,10 @@ import { readdir, rename, writeFile } from "node:fs/promises";
 import { z } from "zod";
 import { ensureDirectory, readUtf8File } from "../filesystem/index.js";
 import { SpawnfileError } from "../shared/index.js";
+import { parseOrganizationHandoff } from "./organizationHandoffTypes.js";
+import { parseOpaqueTargetHandle } from "../target/index.js";
 import { normalizeDeploymentName, resolveDeploymentRecordPath, resolveDeploymentRecordsDirectory } from "./names.js";
+import { parseOrganizationReadiness, organizationReadinessSchema } from "./organizationReady.js";
 const contextTargetSchema = z.object({
     endpoint_fingerprint: z.string().regex(/^sha256:[a-f0-9]{32}$/),
     kind: z.literal("context"),
@@ -82,12 +85,40 @@ export const deploymentRecordSchema = z.object({
     env_file: z.string().min(1).optional(),
     manager: z.string().min(1),
     name: z.string().min(1),
+    organization_handoff: z.unknown().optional(),
+    organization_handoff_handle: z.string().optional(),
     output_directory: z.string().min(1).nullable(),
+    // Optional: the NOOPOLIS_RUN_ID stamped on every authority container's
+    // causal events for this deployment's run (see specs/CAUSAL.md and
+    // src/runtime/common.ts). Populated only when the compiling process had a
+    // run id set (every `spawnfile run`/`up --detach` invocation via
+    // ensureNoopolisRunId()); absent for image-consume/recovered records that
+    // have no reliable run-time id to source. This is what lets
+    // `spawnfile artifacts export --run-id <id>` find the deployment whose
+    // containers/volumes were compiled under that run.
+    run_id: z.string().min(1).optional(),
     source: recordSourceSchema,
     target: targetSchema,
     units: z.array(unitSchema).min(1),
-    version: z.literal("spawnfile.deployment.v2")
-}).strict();
+    version: z.literal("spawnfile.deployment.v2"),
+    // Optional: stamped by `spawnfile artifacts export` (artifactsExport.ts) once it has
+    // successfully written `spawnfile.export-index.v1` for this deployment's run. This is
+    // the record-driven marker `spawnfile down` (downDeployment.ts) reads to enforce the
+    // export-before-teardown invariant (Decision 21) without needing to be told, out of
+    // band, where a prior export went: down resolves the SAME deployment record export
+    // already writes back to, so the two commands share one source of truth. Absent means
+    // "never exported" — not "exported to an unknown location".
+    export_index: z.object({
+        exported_at: z.string().min(1),
+        path: z.string().min(1),
+        run_id: z.string().min(1)
+    }).strict().optional(),
+    organization_ready: organizationReadinessSchema.optional()
+}).strict().superRefine((value, context) => {
+    if (value.organization_handoff_handle !== undefined && value.organization_handoff === undefined) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["organization_handoff_handle"], message: "organization handoff handle requires organization handoff" });
+    }
+});
 const upgradeV1Record = (record) => ({
     auth_profile: record.auth_profile,
     compile_fingerprint: record.compile_fingerprint,
@@ -104,7 +135,14 @@ const upgradeV1Record = (record) => ({
 const hasVersion = (source, version) => typeof source === "object"
     && source !== null
     && source.version === version;
+const readOrganizationReadiness = (source) => {
+    if (typeof source !== "object" || source === null || !Object.hasOwn(source, "organization_ready")) {
+        return undefined;
+    }
+    return parseOrganizationReadiness(source.organization_ready);
+};
 export const parseDeploymentRecord = (source, sourceLabel = "deployment record") => {
+    const organizationReadiness = readOrganizationReadiness(source);
     let record;
     if (hasVersion(source, "spawnfile.deployment.v1")) {
         const parsed = deploymentRecordV1Schema.safeParse(source);
@@ -118,13 +156,20 @@ export const parseDeploymentRecord = (source, sourceLabel = "deployment record")
         if (!parsed.success) {
             throw new SpawnfileError("validation_error", `Invalid ${sourceLabel}: ${z.prettifyError(parsed.error)}`);
         }
-        record = parsed.data;
+        const { organization_handoff: organizationHandoff, organization_handoff_handle: organizationHandoffHandle, organization_ready: _organizationReady, ...recordWithoutMetadata } = parsed.data;
+        record = {
+            ...recordWithoutMetadata,
+            ...(organizationHandoff === undefined
+                ? {}
+                : { organization_handoff: parseOrganizationHandoff(organizationHandoff) }),
+            ...(organizationHandoffHandle === undefined ? {} : { organization_handoff_handle: parseOpaqueTargetHandle(organizationHandoffHandle) })
+        };
     }
     const normalizedName = normalizeDeploymentName(record.name);
     if (normalizedName !== record.name) {
         throw new SpawnfileError("validation_error", `Invalid ${sourceLabel}: deployment name must be normalized`);
     }
-    return record;
+    return organizationReadiness ? { ...record, organization_ready: organizationReadiness } : record;
 };
 export const readDeploymentRecord = async (recordPath) => {
     let parsed;

package/dist/deployment/target.d.ts

@@ -1,35 +1 @@
-export type DockerDeploymentTarget = {
-    endpoint_fingerprint: string;
-    kind: "context";
-    name: string;
-} | {
-    endpoint_fingerprint: string;
-    kind: "docker-context";
-    context: string;
-} | {
-    kind: "host";
-    value: string;
-};
-export type DockerTargetExecFile = (file: string, args: string[], options: {
-    timeout: number;
-}) => Promise<{
-    stderr: string;
-    stdout: string;
-}>;
-export interface ResolveDockerDeploymentTargetOptions {
-    context?: string | null;
-    dockerCommand?: string;
-    dockerHost?: string | null;
-    execFile?: DockerTargetExecFile;
-    timeoutMs?: number;
-}
-export declare const createEndpointFingerprint: (endpoint: string) => string;
-export declare const createDockerDeploymentTarget: (input: {
-    context?: string;
-    endpoint?: string;
-    host?: string;
-}) => DockerDeploymentTarget;
-export declare const dockerContextNameForTarget: (target: DockerDeploymentTarget) => string | null;
-export declare const dockerHostValueForTarget: (target: DockerDeploymentTarget) => string | null;
-export declare const resolveDockerDeploymentTarget: (input?: ResolveDockerDeploymentTargetOptions) => Promise<DockerDeploymentTarget>;
-export declare const verifyDockerDeploymentTarget: (target: DockerDeploymentTarget, options?: Omit<ResolveDockerDeploymentTargetOptions, "context" | "dockerHost">) => Promise<string | null>;
+export * from "../target/dockerTarget.js";

package/dist/deployment/target.js

@@ -1,96 +1 @@
-import { createHash } from "node:crypto";
-import { execFile as execFileCallback } from "node:child_process";
-import { promisify } from "node:util";
-import { SpawnfileError } from "../shared/index.js";
-const execFile = promisify(execFileCallback);
-export const createEndpointFingerprint = (endpoint) => {
-    const normalized = endpoint.trim();
-    if (normalized.length === 0) {
-        throw new SpawnfileError("validation_error", "Deployment target endpoint must not be empty");
-    }
-    return `sha256:${createHash("sha256").update(normalized).digest("hex").slice(0, 32)}`;
-};
-const parseDockerEndpoint = (stdout) => {
-    const trimmed = stdout.trim();
-    if (trimmed.length === 0) {
-        throw new SpawnfileError("runtime_error", "Docker context endpoint was empty");
-    }
-    try {
-        const parsed = JSON.parse(trimmed);
-        if (typeof parsed === "string" && parsed.trim().length > 0) {
-            return parsed.trim();
-        }
-    }
-    catch {
-        // Docker/podman variants may return a plain string instead of JSON.
-    }
-    return trimmed;
-};
-const resolveDockerContextEndpoint = async (context, options) => {
-    try {
-        const { stdout } = await options.execFile(options.dockerCommand, ["context", "inspect", context, "--format", "{{json .Endpoints.docker.Host}}"], { timeout: options.timeoutMs });
-        return parseDockerEndpoint(stdout);
-    }
-    catch (error) {
-        const reason = error instanceof Error ? error.message : String(error);
-        throw new SpawnfileError("runtime_error", `Unable to resolve Docker context "${context}": ${reason}`);
-    }
-};
-export const createDockerDeploymentTarget = (input) => {
-    const host = input.host?.trim();
-    if (host) {
-        return {
-            kind: "host",
-            value: host
-        };
-    }
-    const context = input.context?.trim();
-    const endpoint = input.endpoint?.trim();
-    if (!context || !endpoint) {
-        throw new SpawnfileError("validation_error", "Docker context deployment targets require both context and endpoint");
-    }
-    return {
-        name: context,
-        endpoint_fingerprint: createEndpointFingerprint(endpoint),
-        kind: "context"
-    };
-};
-export const dockerContextNameForTarget = (target) => target.kind === "context"
-    ? target.name
-    : target.kind === "docker-context"
-        ? target.context
-        : null;
-export const dockerHostValueForTarget = (target) => target.kind === "host" ? target.value : null;
-export const resolveDockerDeploymentTarget = async (input = {}) => {
-    const explicitContext = input.context?.trim();
-    const host = explicitContext ? undefined : input.dockerHost?.trim() ?? process.env.DOCKER_HOST?.trim();
-    if (host) {
-        return createDockerDeploymentTarget({ host });
-    }
-    const resolvedOptions = {
-        dockerCommand: input.dockerCommand ?? "docker",
-        execFile: input.execFile ?? execFile,
-        timeoutMs: input.timeoutMs ?? 10_000
-    };
-    const context = explicitContext || "default";
-    const endpoint = await resolveDockerContextEndpoint(context, resolvedOptions);
-    return createDockerDeploymentTarget({ context, endpoint });
-};
-export const verifyDockerDeploymentTarget = async (target, options = {}) => {
-    if (target.kind === "host") {
-        return null;
-    }
-    const context = dockerContextNameForTarget(target);
-    if (!context) {
-        return null;
-    }
-    const current = await resolveDockerDeploymentTarget({
-        ...options,
-        context
-    });
-    const currentFingerprint = current.kind === "host" ? null : current.endpoint_fingerprint;
-    if (currentFingerprint !== target.endpoint_fingerprint) {
-        throw new SpawnfileError("runtime_error", `Docker context "${context}" endpoint changed since deployment`);
-    }
-    return context;
-};
+export * from "../target/dockerTarget.js";

package/dist/deployment/upLifecycleRecoveryState.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Ephemeral grants issued only by the durable up reconciler. They are kept
+ * process-local: a restart reconstructs them by re-reading and re-verifying
+ * the lifecycle records, never by trusting caller-supplied recovery data.
+ */
+export interface NoDockerMutationRecovery {
+    readonly kind: "no_docker_mutation";
+}
+export interface DeploymentRecordRecovery {
+    readonly kind: "deployment_record";
+}
+export interface DetachedContainerRecovery {
+    readonly containerId: string;
+    readonly containerName: string;
+    readonly deploymentLabels: Readonly<Record<string, string>>;
+    readonly imageId: string;
+    readonly kind: "detached_container";
+}
+export type UpLifecycleRecovery = NoDockerMutationRecovery | DeploymentRecordRecovery | DetachedContainerRecovery;
+export declare const noDockerMutationRecovery: () => NoDockerMutationRecovery;
+export declare const deploymentRecordRecovery: () => DeploymentRecordRecovery;
+export declare const detachedContainerRecovery: (value: Omit<DetachedContainerRecovery, "kind">) => DetachedContainerRecovery;
+export declare const isTrustedUpLifecycleRecovery: (value: unknown) => value is UpLifecycleRecovery;

package/dist/deployment/upLifecycleRecoveryState.js

@@ -0,0 +1,12 @@
+const grants = new WeakSet();
+const grant = (value) => {
+    const result = Object.freeze(value);
+    grants.add(result);
+    return result;
+};
+export const noDockerMutationRecovery = () => grant({ kind: "no_docker_mutation" });
+export const deploymentRecordRecovery = () => grant({ kind: "deployment_record" });
+export const detachedContainerRecovery = (value) => grant({ ...value, kind: "detached_container" });
+export const isTrustedUpLifecycleRecovery = (value) => value !== null
+    && typeof value === "object"
+    && grants.has(value);