spawnfile 0.1.13 → 0.1.14

package/dist/cli/containerBundleCommand.js

@@ -0,0 +1,116 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import path from "node:path";
+import { createTargetLocalContainerBundleOperations } from "../target/containerBundle.js";
+import { createContainerBundlePreparationAuthority } from "../target/containerBundleAuthority.js";
+import { createCanonicalTargetLocalBundleLookupBytes, createCanonicalTargetLocalBundleReceiptBytes, parseTargetLocalBundleLookupRequest, parseTargetLocalBundlePrepareRequest } from "../target/containerBundleContracts.js";
+import { initializeFilesystemTargetLocalBundleStore } from "../target/containerBundleFilesystemStore.js";
+import { createDockerTargetLocalBundleBuilder } from "../target/dockerContainerBundleBuilder.js";
+import { createDockerTargetExecutors } from "../target/dockerCommandExecutor.js";
+import { deriveTargetLocalContainerBundlePolicy } from "../target/containerBundlePolicy.js";
+import { readTargetDefaultConfigStdin } from "./targetDefaultConfigStdin.js";
+const MAX_BUNDLE_REQUEST_FILE_BYTES = 5_600_000;
+const readJson = async (raw) => {
+    if (typeof raw !== "string" || raw.includes("\0") || !path.isAbsolute(raw) || path.normalize(raw) !== raw
+        || Buffer.byteLength(raw, "utf8") > 4096)
+        throw new Error();
+    const file = await open(raw, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const info = await file.stat();
+        if (!info.isFile() || info.size > MAX_BUNDLE_REQUEST_FILE_BYTES)
+            throw new Error();
+        const bytes = Buffer.alloc(info.size + 1);
+        let offset = 0;
+        while (offset <= info.size) {
+            const result = await file.read(bytes, offset, info.size + 1 - offset, offset);
+            if (result.bytesRead === 0)
+                break;
+            offset += result.bytesRead;
+        }
+        if (offset !== info.size)
+            throw new Error();
+        return JSON.parse(bytes.toString("utf8", 0, offset));
+    }
+    finally {
+        await file.close();
+    }
+};
+const readRequest = async (file) => parseTargetLocalBundlePrepareRequest(await readJson(file));
+const readLookup = async (file) => parseTargetLocalBundleLookupRequest(await readJson(file));
+const operations = async (config) => {
+    const executors = createDockerTargetExecutors({ dockerCommand: config.dockerCommand });
+    return createTargetLocalContainerBundleOperations({
+        authority: createContainerBundlePreparationAuthority(config.preparedArtifactMappings),
+        builder: createDockerTargetLocalBundleBuilder({ context: config.context, executor: executors.artifact, timeoutMs: config.timeoutMs }),
+        store: await initializeFilesystemTargetLocalBundleStore(config.paths.containerBundles)
+    });
+};
+/** Production-only command. Its stdout is the secret-free canonical receipt. */
+export const registerContainerBundleCommand = (target, stdin, streams, setExitCode) => {
+    target.command("derive_container_bundle_policy")
+        .argument("<claims-file>", "Strict target-local bundle policy claims")
+        .action(async (claimsFile) => {
+        try {
+            const raw = await readJson(claimsFile);
+            if (raw === null || typeof raw !== "object" || Array.isArray(raw)
+                || Object.keys(raw).sort().join("\0") !== "archiveDigest\0artifactDigest\0baseImageConfigDigest\0bundleDigest\0entrypoint\0launcherDigest\0networkAlias\0platform") {
+                throw new Error();
+            }
+            const policy = deriveTargetLocalContainerBundlePolicy(raw);
+            streams.stdout(JSON.stringify({
+                version: "spawnfile.target-local-container-bundle-policy.v1",
+                build_policy_digest: policy.buildPolicyDigest,
+                platform_digest: policy.platformDigest
+            }));
+        }
+        catch {
+            streams.stderr("error: Invalid container bundle policy claims");
+            setExitCode(2);
+        }
+    });
+    const execute = (name) => target.command(name)
+        .argument("<request-file>", "Strict container-bundle preparation request")
+        .action(async (requestFile) => {
+        let request;
+        try {
+            request = await readRequest(requestFile);
+        }
+        catch {
+            streams.stderr("error: Invalid container bundle request");
+            setExitCode(2);
+            return;
+        }
+        try {
+            const config = await readTargetDefaultConfigStdin(stdin);
+            const receipt = await (await operations(config))[name === "prepare_container_bundle" ? "prepare" : "recover"](request);
+            streams.stdout(createCanonicalTargetLocalBundleReceiptBytes(receipt));
+        }
+        catch {
+            streams.stderr("error: Target-local container bundle preparation failed");
+            setExitCode(1);
+        }
+    });
+    execute("prepare_container_bundle");
+    execute("recover_container_bundle");
+    target.command("lookup_container_bundle").argument("<lookup-file>", "Strict semantic bundle lookup")
+        .action(async (lookupFile) => {
+        let request;
+        try {
+            request = await readLookup(lookupFile);
+        }
+        catch {
+            streams.stderr("error: Invalid container bundle lookup");
+            setExitCode(2);
+            return;
+        }
+        try {
+            const config = await readTargetDefaultConfigStdin(stdin);
+            const result = await (await operations(config)).lookup(request);
+            streams.stdout(createCanonicalTargetLocalBundleLookupBytes(result));
+        }
+        catch {
+            streams.stderr("error: Target-local container bundle preparation failed");
+            setExitCode(1);
+        }
+    });
+};

package/dist/cli/downCommand.d.ts

@@ -0,0 +1,25 @@
+import type { Command } from "commander";
+import { type DeploymentLifecycleCorrelation, type LifecycleInvocation } from "../deployment/index.js";
+import type { CliHandlers, CliStreams } from "./runCli.js";
+export interface DownOptions {
+    compiled?: string;
+    deployment: string;
+    dockerCommand?: string;
+    exportTo?: string;
+    force?: boolean;
+    json?: boolean;
+    lifecycleInvocation?: string;
+    readerImage?: string;
+    timeout?: string;
+    volumes?: boolean;
+}
+export declare const createDownLifecyclePolicy: (options: DownOptions) => {
+    docker_command: string | null;
+    export_to: string | null;
+    force: boolean;
+    reader_image: string | null;
+    remove_volumes: boolean;
+    timeout_ms: number | null;
+};
+export declare const createDownLifecycleInvocation: (id: string, compiledOutputDirectory: string, options: DownOptions, correlation: DeploymentLifecycleCorrelation) => LifecycleInvocation;
+export declare const registerDownCommand: (program: Command, handlers: CliHandlers, streams: CliStreams) => void;

package/dist/cli/downCommand.js

@@ -0,0 +1,134 @@
+import path from "node:path";
+import { createDeploymentLifecycleCorrelation, findLifecycleInvocation, readDeploymentRecordFromOutput, } from "../deployment/index.js";
+import { resolveProjectOutputDirectory } from "../filesystem/index.js";
+import { DEFAULT_OUTPUT_DIRECTORY, SpawnfileError } from "../shared/index.js";
+import { canonicalLifecycleJson } from "../deployment/lifecycleCompletionContracts.js";
+import { createLifecycleInvocation, requireMachineLifecycle, runMachineLifecycle, } from "./lifecycleMachine.js";
+export const createDownLifecyclePolicy = (options) => ({
+    docker_command: options.dockerCommand ?? null,
+    export_to: options.exportTo ? path.resolve(options.exportTo) : null,
+    force: options.force ?? false,
+    reader_image: options.readerImage ?? null,
+    remove_volumes: options.volumes ?? false,
+    timeout_ms: options.timeout ? Number(options.timeout) : null,
+});
+export const createDownLifecycleInvocation = (id, compiledOutputDirectory, options, correlation) => createLifecycleInvocation(id, "down", {
+    compiled_output_directory: compiledOutputDirectory,
+    ...correlation,
+}, createDownLifecyclePolicy(options));
+const correlationFrom = (stored) => {
+    const value = stored.correlation;
+    if (typeof value.compile_fingerprint !== "string" ||
+        typeof value.deployment_instance_digest !== "string" ||
+        typeof value.deployment !== "string" ||
+        (value.run_id !== null && typeof value.run_id !== "string") ||
+        typeof value.target !== "string") {
+        throw new SpawnfileError("runtime_error", "Invalid stored down correlation");
+    }
+    return {
+        compile_fingerprint: value.compile_fingerprint,
+        deployment: value.deployment,
+        deployment_instance_digest: value.deployment_instance_digest,
+        run_id: value.run_id,
+        target: value.target,
+    };
+};
+const assertExactRequest = (stored, compiledOutputDirectory, options) => {
+    if (stored.operation !== "down" ||
+        stored.correlation.compiled_output_directory !== compiledOutputDirectory ||
+        stored.correlation.deployment !== options.deployment ||
+        JSON.stringify(stored.request_policy) !==
+            JSON.stringify(createDownLifecyclePolicy(options))) {
+        throw new SpawnfileError("runtime_error", "Lifecycle invocation id drift");
+    }
+};
+export const registerDownCommand = (program, handlers, streams) => {
+    program
+        .command("down")
+        .description("Tear down a recorded deployment; named volumes are retained by default.")
+        .argument("[path]", "Project directory or Spawnfile path", process.cwd())
+        .requiredOption("--deployment <name>", "Deployment record name to tear down")
+        .option("--compiled <directory>", "Compile output directory")
+        .option("--docker-command <command>", "Docker command")
+        .option("--export-to <directory>", "Export first, then tear down")
+        .option("--force", "Discard un-exported artifacts")
+        .option("--reader-image <image>", "Image used to read named volumes during auto export")
+        .option("--timeout <ms>", "Bound each Docker call in milliseconds")
+        .option("--volumes", "Also remove named volumes")
+        .option("--json", "Render a spawnfile.down-receipt.v1 machine-readable receipt")
+        .option("--lifecycle-invocation <id>", "Durably bind this exact JSON lifecycle invocation")
+        .action(async (inputPath, options) => {
+        requireMachineLifecycle(options.lifecycleInvocation, options.json);
+        const compiled = resolveProjectOutputDirectory(inputPath, options.compiled, DEFAULT_OUTPUT_DIRECTORY);
+        const render = async (expected) => {
+            const expectedUnits = expected
+                ? (await readDeploymentRecordFromOutput(compiled, options.deployment)).units.map((unit) => unit.id).sort()
+                : undefined;
+            const receipt = await handlers.downDeployment({
+                compiledOutputDirectory: compiled,
+                deploymentName: options.deployment,
+                dockerCommand: options.dockerCommand,
+                exportTo: options.exportTo,
+                force: options.force,
+                readerImage: options.readerImage,
+                removeVolumes: options.volumes,
+                timeoutMs: options.timeout ? Number(options.timeout) : undefined,
+                ...(expected ? { expectedLifecycleCorrelation: expected } : {}),
+            });
+            if (expectedUnits !== undefined &&
+                (receipt.errors.length !== 0 ||
+                    (options.volumes === true &&
+                        receipt.retained_volumes.length !== 0) ||
+                    JSON.stringify([...receipt.units_stopped].sort()) !==
+                        JSON.stringify(expectedUnits))) {
+                throw new SpawnfileError("runtime_error", "Lifecycle down is incomplete and remains retryable");
+            }
+            return JSON.stringify(receipt, null, 2);
+        };
+        if (options.json && options.lifecycleInvocation) {
+            const stored = await findLifecycleInvocation(options.lifecycleInvocation);
+            let exact;
+            let correlation;
+            if (stored) {
+                assertExactRequest(stored, compiled, options);
+                exact = stored;
+                correlation = correlationFrom(stored);
+            }
+            else {
+                const record = await readDeploymentRecordFromOutput(compiled, options.deployment);
+                correlation = createDeploymentLifecycleCorrelation(record);
+                exact = createDownLifecycleInvocation(options.lifecycleInvocation, compiled, options, correlation);
+            }
+            const output = await runMachineLifecycle(exact, () => render(correlation), async () => {
+                try {
+                    const current = createDeploymentLifecycleCorrelation(await readDeploymentRecordFromOutput(compiled, options.deployment));
+                    return canonicalLifecycleJson(current) ===
+                        canonicalLifecycleJson(correlation)
+                        ? { status: "resume_safe" }
+                        : {
+                            reason: "deployment_correlation_changed",
+                            status: "ambiguous",
+                        };
+                }
+                catch {
+                    return {
+                        reason: "deployment_correlation_unavailable",
+                        status: "ambiguous",
+                    };
+                }
+            });
+            streams.stdout(output);
+            return;
+        }
+        const output = await render();
+        if (options.json) {
+            streams.stdout(output);
+            return;
+        }
+        const receipt = JSON.parse(output);
+        streams.stdout(`deployment: ${receipt.deployment}`);
+        receipt.units_stopped.forEach((unit) => streams.stdout(`stopped: ${unit}`));
+        receipt.retained_volumes.forEach((volume) => streams.stdout(`retained volume: ${volume}`));
+        receipt.errors.forEach((error) => streams.stderr(`error: ${error}`));
+    });
+};

package/dist/cli/index.js

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
-import { runCli } from "./runCli.js";
-const exitCode = await runCli(process.argv.slice(2));
-process.exit(exitCode);
+import { isTargetLookupInvocation } from "./targetCliRoute.js";
+const argv = process.argv.slice(2);
+const exitCode = isTargetLookupInvocation(argv)
+    ? await (await import("./targetLookupCli.js")).runTargetLookupCli(argv)
+    : await (await import("./runCli.js")).runCli(argv);
+process.exitCode = exitCode;

package/dist/cli/lifecycleCommands.d.ts

@@ -1,3 +1,3 @@
 import type { Command } from "commander";
 import type { CliHandlers, CliStreams } from "./runCli.js";
-export declare const registerLifecycleCommands: (program: Command, handlers: CliHandlers, streams: CliStreams) => void;
+export declare const registerLifecycleCommands: (program: Command, handlers: CliHandlers, streams: CliStreams, stdin: AsyncIterable<unknown>) => void;

package/dist/cli/lifecycleCommands.js

@@ -1,182 +1,12 @@
-import { readRunEnvFile } from "../compiler/runProjectAuth.js";
-import { SpawnfileError } from "../shared/index.js";
-import { resolveCommandInput } from "./resolveCommandInput.js";
-const resolveAuthProfileForImage = async (handlers, authProfile) => {
-    if (!authProfile || !handlers.requireAuthProfile) {
-        return null;
-    }
-    return handlers.requireAuthProfile(authProfile);
-};
-const shortDigest = (digest) => digest ? digest.replace(/^sha256:/, "").slice(0, 12) : "unknown";
-/** Summarizes a redeploy as previous → new ref/digest, per specs/DISTRIBUTION.md. */
-const formatRedeploySummary = (previous, newRef, newDigest) => {
-    // Only claim "unchanged" when we actually resolved a matching digest; two null
-    // digests (local-only images) are unknown, not provably identical.
-    if (previous.ref === newRef && newDigest !== null && previous.digest === newDigest) {
-        return `redeployed image ${newRef} (digest unchanged ${shortDigest(newDigest)})`;
-    }
-    return (`redeployed image: ${previous.ref} (${shortDigest(previous.digest)}) ` +
-        `→ ${newRef} (${shortDigest(newDigest)})`);
-};
-export const registerLifecycleCommands = (program, handlers, streams) => {
-    program
-        .command("compile")
-        .description("Compile a project into runtime-native output under .spawn")
-        .argument("[path]", "Project directory or Spawnfile path", process.cwd())
-        .option("-o, --out <directory>", "Output directory")
-        .action(async (inputPath, options) => {
-        const result = await handlers.compileProject(inputPath, { outputDirectory: options.out });
-        streams.stdout(`compiled to ${result.outputDirectory}`);
-        streams.stdout(`report: ${result.reportPath}`);
-    });
-    program
-        .command("build")
-        .description("Compile and build the organization Docker image")
-        .argument("[path]", "Project directory or Spawnfile path", process.cwd())
-        .option("--context <name>", "Docker context for the build target")
-        .option("--docker-command <command>", "Docker command")
-        .option("-o, --out <directory>", "Output directory")
-        .option("-t, --tag <image>", "Docker image tag")
-        .action(async (inputPath, options) => {
-        const result = await handlers.buildProject(inputPath, {
-            dockerContext: options.context,
-            dockerCommand: options.dockerCommand,
-            imageTag: options.tag,
-            outputDirectory: options.out
-        });
-        streams.stdout(`built image ${result.imageTag}`);
-        streams.stdout(`compiled to ${result.outputDirectory}`);
-        streams.stdout(`report: ${result.reportPath}`);
-    });
-    program
-        .command("run")
-        .description("Compile, build, and run the organization container locally")
-        .argument("[path]", "Project directory or Spawnfile path", process.cwd())
-        .option("-o, --out <directory>", "Output directory")
-        .option("-t, --tag <image>", "Docker image tag")
-        .option("--auth-profile <name>", "Local Spawnfile auth profile")
-        .option("--context <name>", "Docker context for the deployment target")
-        .option("--deployment <name>", "Detached deployment record name")
-        .option("--docker-command <command>", "Docker command")
-        .option("--name <container>", "Docker container name")
-        .option("--env-file <file>", "Path to an env file for runtime secrets")
-        .option("--image", "Interpret the argument as an image reference")
-        .option("-d, --detach", "Run the container in detached mode")
-        .action(async (inputPath, options) => {
-        const runInput = resolveCommandInput(inputPath, { forceImage: options.image });
-        if (runInput.kind === "image" || (runInput.kind === "invalid" && options.image)) {
-            throw new SpawnfileError("validation_error", `Image-mode run is not supported. Deploy the image with: ` +
-                `spawnfile up ${inputPath} --auth-profile <profile> ` +
-                "(add --env-file for any extra secrets; image deployments always detach).");
-        }
-        if (runInput.kind === "invalid") {
-            throw new SpawnfileError("validation_error", `Cannot resolve "${inputPath}" as a project path or image reference. ` +
-                "Pass a project directory, a Spawnfile path, or an image like 'name:tag' (use --image to force image mode).");
-        }
-        const result = await handlers.runProject(inputPath, {
-            authProfile: options.authProfile,
-            containerName: options.name,
-            detach: options.detach,
-            deploymentName: options.deployment,
-            dockerCommand: options.dockerCommand,
-            dockerContext: options.context,
-            envFilePath: options.envFile,
-            imageTag: options.tag,
-            outputDirectory: options.out
-        });
-        if (options.detach) {
-            streams.stdout(`running container ${result.containerName ?? "unknown"}`);
-            streams.stdout(`image: ${result.imageTag}`);
-        }
-    });
-    program
-        .command("publish")
-        .description("Compile, build, verify, and push the organization image to a registry")
-        .argument("[path]", "Project directory or Spawnfile path", process.cwd())
-        .requiredOption("-t, --tag <image>", "Registry image reference to push")
-        .option("-o, --out <directory>", "Output directory")
-        .option("--docker-command <command>", "Docker command")
-        .action(async (inputPath, options) => {
-        const publishInput = resolveCommandInput(inputPath);
-        if (publishInput.kind !== "project") {
-            throw new SpawnfileError("validation_error", "publish operates on a project path, not an image reference");
-        }
-        const result = await handlers.publishProject(inputPath, {
-            dockerCommand: options.dockerCommand,
-            imageTag: options.tag,
-            outputDirectory: options.out
-        });
-        streams.stdout(`published ${result.imageTag}`);
-        streams.stdout(`digest: ${result.digest ?? "unknown"}`);
-        streams.stdout(`next: spawnfile up ${result.imageTag} --detach --auth-profile <profile>`);
-    });
-    program
-        .command("up")
-        .description("Deploy an organization from a project or a published image reference")
-        .argument("[path]", "Project directory, Spawnfile path, or image reference", process.cwd())
-        .option("-o, --out <directory>", "Output directory")
-        .option("-t, --tag <image>", "Docker image tag")
-        .option("--auth-profile <name>", "Local Spawnfile auth profile")
-        .option("--context <name>", "Docker context for the deployment target")
-        .option("--deployment <name>", "Detached deployment record name")
-        .option("--docker-command <command>", "Docker command")
-        .option("--name <container>", "Docker container name")
-        .option("--env-file <file>", "Path to an env file for runtime secrets")
-        .option("--image", "Interpret the argument as an image reference")
-        .option("--pull", "Pull the image before deploying")
-        .option("-d, --detach", "Run the container in detached mode")
-        .action(async (inputPath, options) => {
-        const upInput = resolveCommandInput(inputPath, { forceImage: options.image });
-        if (upInput.kind === "invalid") {
-            throw new SpawnfileError("validation_error", `Cannot resolve "${inputPath}" as a project path or image reference. ` +
-                "Pass a project directory, a Spawnfile path, or an image like 'name:tag' (use --image to force image mode).");
-        }
-        if (upInput.kind === "image") {
-            const [authProfile, envFileEnv] = await Promise.all([
-                resolveAuthProfileForImage(handlers, options.authProfile),
-                readRunEnvFile(options.envFile)
-            ]);
-            const consumed = await handlers.consumeImageUp(upInput.ref, {
-                authProfile,
-                authProfileName: options.authProfile ?? null,
-                authValues: authProfile?.env ?? {},
-                deploymentName: options.deployment,
-                dockerCommand: options.dockerCommand,
-                dockerContext: options.context,
-                envFileEnv,
-                envFilePath: options.envFile ?? null,
-                pull: options.pull
-            });
-            if (consumed.previous) {
-                const newDigest = consumed.record.source.kind === "image" ? consumed.record.source.digest : null;
-                streams.stdout(formatRedeploySummary(consumed.previous, consumed.imageRef, newDigest));
-            }
-            else {
-                streams.stdout(`deployed image ${consumed.imageRef}`);
-            }
-            streams.stdout(`deployment: ${consumed.deploymentName}`);
-            streams.stdout(`running container ${consumed.containerName}`);
-            streams.stdout(`record: ${consumed.recordPath}`);
-            streams.stdout(`next: spawnfile status --deployment ${consumed.deploymentName} --live`);
-            return;
-        }
-        const result = await handlers.upProject(inputPath, {
-            authProfile: options.authProfile,
-            containerName: options.name,
-            detach: options.detach,
-            deploymentName: options.deployment,
-            dockerCommand: options.dockerCommand,
-            dockerContext: options.context,
-            envFilePath: options.envFile,
-            imageTag: options.tag,
-            outputDirectory: options.out
-        });
-        streams.stdout(`built image ${result.imageTag}`);
-        streams.stdout(`compiled to ${result.outputDirectory}`);
-        streams.stdout(`report: ${result.reportPath}`);
-        if (options.detach) {
-            streams.stdout(`running container ${result.containerName ?? "unknown"}`);
-            streams.stdout(`image: ${result.imageTag}`);
-        }
-    });
+import { registerCompileBuildCommands } from "./compileBuildCommands.js";
+import { registerDownCommand } from "./downCommand.js";
+import { registerLifecyclePlanningCommands } from "./lifecyclePlanningCommands.js";
+import { registerRunPublishCommands } from "./runPublishCommands.js";
+import { registerUpCommand } from "./upCommand.js";
+export const registerLifecycleCommands = (program, handlers, streams, stdin) => {
+    registerLifecyclePlanningCommands(program, streams, stdin);
+    registerCompileBuildCommands(program, handlers, streams);
+    registerRunPublishCommands(program, handlers, streams);
+    registerUpCommand(program, handlers, streams);
+    registerDownCommand(program, handlers, streams);
 };

package/dist/cli/lifecycleMachine.d.ts

@@ -0,0 +1,19 @@
+import { type LifecycleInvocation } from "../deployment/index.js";
+export declare const createLifecycleInvocation: (id: string, operation: LifecycleInvocation["operation"], correlation: LifecycleInvocation["correlation"], requestPolicy: LifecycleInvocation["request_policy"]) => LifecycleInvocation;
+export declare const digestLifecycleBinding: (value: string | undefined) => string | null;
+export type LifecycleReconciliation = {
+    outcomeBytes: string;
+    status: "completed";
+} | {
+    status: "provably_not_applied";
+} | {
+    status: "resume_safe";
+} | {
+    reason: string;
+    status: "ambiguous";
+};
+export declare const runMachineLifecycle: (invocation: LifecycleInvocation, owner: (capability: {
+    epoch: string;
+    role: "initial" | "recovery";
+}) => Promise<string>, reconcile?: () => Promise<LifecycleReconciliation>) => Promise<string>;
+export declare const requireMachineLifecycle: (invocationId: string | undefined, json: boolean | undefined) => void;

package/dist/cli/lifecycleMachine.js

@@ -0,0 +1,78 @@
+import { createHash } from "node:crypto";
+import { claimLifecycleInvocation, claimLifecycleRecovery, completeLifecycleInvocation, findExactLifecycleCompletion, markLifecycleAmbiguous, renewLifecycleOwner, } from "../deployment/index.js";
+import { SpawnfileError } from "../shared/index.js";
+export const createLifecycleInvocation = (id, operation, correlation, requestPolicy) => ({
+    correlation,
+    id,
+    operation,
+    request_policy: requestPolicy,
+    version: "spawnfile.lifecycle-invocation.v1",
+});
+export const digestLifecycleBinding = (value) => value === undefined
+    ? null
+    : `sha256:${createHash("sha256").update(value).digest("hex")}`;
+const withLifecycleHeartbeat = async (invocation, capability, task) => {
+    await renewLifecycleOwner(invocation, capability);
+    let failure;
+    const timer = setInterval(() => {
+        void renewLifecycleOwner(invocation, capability).catch((error) => {
+            failure = error;
+        });
+    }, 10_000);
+    timer.unref();
+    try {
+        const result = await task();
+        if (failure)
+            throw failure;
+        return result;
+    }
+    finally {
+        clearInterval(timer);
+    }
+};
+export const runMachineLifecycle = async (invocation, owner, reconcile) => {
+    const existing = await findExactLifecycleCompletion(invocation);
+    if (existing)
+        return existing.outcome_bytes;
+    const claim = await claimLifecycleInvocation(invocation);
+    if (claim.status === "replay") {
+        const replay = await findExactLifecycleCompletion(invocation);
+        if (!replay) {
+            throw new SpawnfileError("runtime_error", "Lifecycle replay completion disappeared");
+        }
+        return replay.outcome_bytes;
+    }
+    if (claim.status === "pending" && reconcile) {
+        const recovery = await claimLifecycleRecovery(invocation);
+        if (recovery.status === "replay") {
+            const completed = await findExactLifecycleCompletion(invocation);
+            if (completed)
+                return completed.outcome_bytes;
+            throw new SpawnfileError("runtime_error", "Lifecycle replay completion disappeared");
+        }
+        if (recovery.status === "owner") {
+            const verdict = await withLifecycleHeartbeat(invocation, recovery.capability, reconcile);
+            if (verdict.status === "completed") {
+                return (await completeLifecycleInvocation(invocation, verdict.outcomeBytes, recovery.capability)).outcome_bytes;
+            }
+            if (verdict.status === "provably_not_applied" ||
+                verdict.status === "resume_safe") {
+                return (await completeLifecycleInvocation(invocation, await withLifecycleHeartbeat(invocation, recovery.capability, () => owner(recovery.capability)), recovery.capability)).outcome_bytes;
+            }
+            await markLifecycleAmbiguous(invocation, "reconciliation_ambiguous", recovery.capability);
+            throw new SpawnfileError("runtime_error", `Lifecycle recovery is ambiguous: ${verdict.reason}`);
+        }
+        if (recovery.status === "ambiguous") {
+            throw new SpawnfileError("runtime_error", "Lifecycle recovery owner died; invocation is ambiguous");
+        }
+    }
+    if (claim.status !== "owner") {
+        throw new SpawnfileError("runtime_error", "Lifecycle invocation already has an in-flight owner");
+    }
+    return (await completeLifecycleInvocation(invocation, await withLifecycleHeartbeat(invocation, claim.capability, () => owner(claim.capability)), claim.capability)).outcome_bytes;
+};
+export const requireMachineLifecycle = (invocationId, json) => {
+    if (invocationId !== undefined && !json) {
+        throw new SpawnfileError("validation_error", "--lifecycle-invocation is only valid with --json");
+    }
+};

package/dist/cli/lifecyclePlan.d.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { type LifecycleInvocation } from "../deployment/index.js";
+export declare const LIFECYCLE_PLAN_REQUEST_VERSION: "spawnfile.lifecycle-plan-request.v1";
+export declare const MAX_LIFECYCLE_PLAN_REQUEST_BYTES = 262144;
+export declare const lifecyclePlanRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    deployment: z.ZodNullable<z.ZodString>;
+    include_private: z.ZodBoolean;
+    operation: z.ZodLiteral<"artifacts_export">;
+    out: z.ZodString;
+    reader_image: z.ZodNullable<z.ZodString>;
+    run_id: z.ZodNullable<z.ZodString>;
+    compiled: z.ZodNullable<z.ZodString>;
+    docker_command: z.ZodNullable<z.ZodString>;
+    lifecycle_invocation_id: z.ZodString;
+    path: z.ZodString;
+    timeout_ms: z.ZodNullable<z.ZodNumber>;
+    version: z.ZodLiteral<"spawnfile.lifecycle-plan-request.v1">;
+}, z.core.$strict>, z.ZodObject<{
+    deployment: z.ZodString;
+    export_to: z.ZodNullable<z.ZodString>;
+    force: z.ZodBoolean;
+    operation: z.ZodLiteral<"down">;
+    reader_image: z.ZodNullable<z.ZodString>;
+    remove_volumes: z.ZodBoolean;
+    compiled: z.ZodNullable<z.ZodString>;
+    docker_command: z.ZodNullable<z.ZodString>;
+    lifecycle_invocation_id: z.ZodString;
+    path: z.ZodString;
+    timeout_ms: z.ZodNullable<z.ZodNumber>;
+    version: z.ZodLiteral<"spawnfile.lifecycle-plan-request.v1">;
+}, z.core.$strict>], "operation">;
+export type LifecyclePlanRequest = z.infer<typeof lifecyclePlanRequestSchema>;
+export declare const readLifecyclePlanRequest: (source: string, stdin: AsyncIterable<unknown>) => Promise<LifecyclePlanRequest>;
+export declare const createPlannedLifecycleInvocation: (request: LifecyclePlanRequest) => Promise<LifecycleInvocation>;
+export declare const planLifecycleInvocation: (request: LifecyclePlanRequest) => Promise<LifecycleInvocation>;