spawnfile 0.1.13 → 0.1.17

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,25 @@
+import { type LifecycleInvocation } from "../deployment/index.js";
+import type { UpLifecycleRecovery } from "../deployment/upLifecycleRecoveryState.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";
+} | {
+    recovery?: UpLifecycleRecovery;
+    status: "provably_not_applied";
+} | {
+    recovery?: UpLifecycleRecovery;
+    status: "resume_safe";
+} | {
+    reason: string;
+    status: "ambiguous";
+};
+export declare const runMachineLifecycle: (invocation: LifecycleInvocation, owner: (capability: {
+    epoch: string;
+    role: "initial" | "recovery";
+}, recovery?: UpLifecycleRecovery) => Promise<string>, reconcile?: (capability: {
+    epoch: string;
+    role: "initial" | "recovery";
+}) => 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(recovery.capability));
+            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, verdict.recovery)), 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>;

package/dist/cli/lifecyclePlan.js

@@ -0,0 +1,240 @@
+import { open } from "node:fs/promises";
+import path from "node:path";
+import { TextDecoder } from "node:util";
+import { z } from "zod";
+import { admitLifecyclePlan, createDeploymentLifecycleCorrelation, readDeploymentRecordFromOutput, resolveArtifactsExportLifecycleCorrelation, } from "../deployment/index.js";
+import { resolveProjectOutputDirectory } from "../filesystem/index.js";
+import { DEFAULT_OUTPUT_DIRECTORY, SpawnfileError } from "../shared/index.js";
+import { createArtifactsExportLifecycleInvocation, } from "./artifactsCommands.js";
+import { createDownLifecycleInvocation, } from "./downCommand.js";
+export const LIFECYCLE_PLAN_REQUEST_VERSION = "spawnfile.lifecycle-plan-request.v1";
+export const MAX_LIFECYCLE_PLAN_REQUEST_BYTES = 262_144;
+const common = {
+    compiled: z.string().min(1).max(4096).nullable(),
+    docker_command: z.string().min(1).max(4096).nullable(),
+    lifecycle_invocation_id: z
+        .string()
+        .regex(/^lci_[a-z0-9][a-z0-9_-]{15,127}$/u),
+    path: z.string().min(1).max(4096),
+    timeout_ms: z.number().int().positive().nullable(),
+    version: z.literal(LIFECYCLE_PLAN_REQUEST_VERSION),
+};
+export const lifecyclePlanRequestSchema = z.discriminatedUnion("operation", [
+    z
+        .object({
+        ...common,
+        deployment: z.string().min(1).max(128).nullable(),
+        include_private: z.boolean(),
+        operation: z.literal("artifacts_export"),
+        out: z.string().min(1).max(4096),
+        reader_image: z.string().min(1).max(4096).nullable(),
+        run_id: z.string().min(1).max(512).nullable(),
+    })
+        .strict(),
+    z
+        .object({
+        ...common,
+        deployment: z.string().min(1).max(128),
+        export_to: z.string().min(1).max(4096).nullable(),
+        force: z.boolean(),
+        operation: z.literal("down"),
+        reader_image: z.string().min(1).max(4096).nullable(),
+        remove_volumes: z.boolean(),
+    })
+        .strict(),
+]);
+const fail = () => {
+    throw new SpawnfileError("validation_error", "Invalid lifecycle plan request");
+};
+const assertNoDuplicateJsonKeys = (source) => {
+    let offset = 0;
+    const whitespace = () => {
+        while (/\s/u.test(source[offset] ?? ""))
+            offset += 1;
+    };
+    const string = () => {
+        const start = offset++;
+        while (offset < source.length) {
+            if (source[offset] === "\\")
+                offset += 2;
+            else if (source[offset] === '"') {
+                offset += 1;
+                return JSON.parse(source.slice(start, offset));
+            }
+            else
+                offset += 1;
+        }
+        return fail();
+    };
+    const value = () => {
+        whitespace();
+        if (source[offset] === "{")
+            object();
+        else if (source[offset] === "[")
+            array();
+        else if (source[offset] === '"')
+            void string();
+        else
+            while (offset < source.length &&
+                !/[\s,\]}]/u.test(source[offset] ?? ""))
+                offset += 1;
+    };
+    const object = () => {
+        offset += 1;
+        whitespace();
+        const keys = new Set();
+        if (source[offset] === "}") {
+            offset += 1;
+            return;
+        }
+        while (offset < source.length) {
+            const key = string();
+            if (keys.has(key))
+                fail();
+            keys.add(key);
+            whitespace();
+            if (source[offset++] !== ":")
+                fail();
+            value();
+            whitespace();
+            if (source[offset] === "}") {
+                offset += 1;
+                return;
+            }
+            if (source[offset++] !== ",")
+                fail();
+            whitespace();
+        }
+        fail();
+    };
+    const array = () => {
+        offset += 1;
+        whitespace();
+        if (source[offset] === "]") {
+            offset += 1;
+            return;
+        }
+        while (offset < source.length) {
+            value();
+            whitespace();
+            if (source[offset] === "]") {
+                offset += 1;
+                return;
+            }
+            if (source[offset++] !== ",")
+                fail();
+            whitespace();
+        }
+        fail();
+    };
+    value();
+    whitespace();
+    if (offset !== source.length)
+        fail();
+};
+const readStdin = async (stdin) => {
+    const chunks = [];
+    let length = 0;
+    try {
+        for await (const raw of stdin) {
+            const chunk = typeof raw === "string"
+                ? new TextEncoder().encode(raw)
+                : raw instanceof Uint8Array
+                    ? Uint8Array.from(raw)
+                    : fail();
+            if (chunk.byteLength === 0 ||
+                chunk.byteLength > MAX_LIFECYCLE_PLAN_REQUEST_BYTES - length)
+                fail();
+            chunks.push(chunk);
+            length += chunk.byteLength;
+        }
+    }
+    catch {
+        fail();
+    }
+    if (length === 0)
+        fail();
+    const result = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        result.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return result;
+};
+const readFile = async (file) => {
+    const exact = path.resolve(file);
+    const handle = await open(exact, "r").catch(fail);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size > MAX_LIFECYCLE_PLAN_REQUEST_BYTES)
+            fail();
+        const bytes = new Uint8Array(stat.size);
+        let offset = 0;
+        while (offset < bytes.byteLength) {
+            const { bytesRead } = await handle.read(bytes, offset, bytes.byteLength - offset, offset);
+            if (bytesRead === 0)
+                fail();
+            offset += bytesRead;
+        }
+        return bytes;
+    }
+    finally {
+        await handle.close();
+    }
+};
+export const readLifecyclePlanRequest = async (source, stdin) => {
+    try {
+        const bytes = source === "-" ? await readStdin(stdin) : await readFile(source);
+        const text = new TextDecoder("utf-8", {
+            fatal: true,
+            ignoreBOM: true,
+        }).decode(bytes);
+        if (text.startsWith("\uFEFF"))
+            fail();
+        assertNoDuplicateJsonKeys(text);
+        return lifecyclePlanRequestSchema.parse(JSON.parse(text));
+    }
+    catch {
+        return fail();
+    }
+};
+const timeout = (value) => value === null ? undefined : String(value);
+export const createPlannedLifecycleInvocation = async (request) => {
+    const compiled = resolveProjectOutputDirectory(request.path, request.compiled ?? undefined, DEFAULT_OUTPUT_DIRECTORY);
+    if (request.operation === "artifacts_export") {
+        const options = {
+            compiled: request.compiled ?? undefined,
+            deployment: request.deployment ?? undefined,
+            dockerCommand: request.docker_command ?? undefined,
+            includePrivate: request.include_private,
+            json: true,
+            lifecycleInvocation: request.lifecycle_invocation_id,
+            out: request.out,
+            readerImage: request.reader_image ?? undefined,
+            runId: request.run_id ?? undefined,
+            timeout: timeout(request.timeout_ms),
+        };
+        const correlation = await resolveArtifactsExportLifecycleCorrelation({
+            compiledOutputDirectory: compiled,
+            deploymentName: options.deployment,
+            runId: options.runId,
+        });
+        return createArtifactsExportLifecycleInvocation(request.lifecycle_invocation_id, options, compiled, correlation);
+    }
+    const options = {
+        compiled: request.compiled ?? undefined,
+        deployment: request.deployment,
+        dockerCommand: request.docker_command ?? undefined,
+        exportTo: request.export_to ?? undefined,
+        force: request.force,
+        json: true,
+        lifecycleInvocation: request.lifecycle_invocation_id,
+        readerImage: request.reader_image ?? undefined,
+        timeout: timeout(request.timeout_ms),
+        volumes: request.remove_volumes,
+    };
+    const record = await readDeploymentRecordFromOutput(compiled, request.deployment);
+    return createDownLifecycleInvocation(request.lifecycle_invocation_id, compiled, options, createDeploymentLifecycleCorrelation(record));
+};
+export const planLifecycleInvocation = async (request) => admitLifecyclePlan(await createPlannedLifecycleInvocation(request));

package/dist/cli/lifecyclePlanningCommands.d.ts

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

package/dist/cli/lifecyclePlanningCommands.js

@@ -0,0 +1,30 @@
+import { lookupLifecycleCompletion } from "../deployment/index.js";
+import { SpawnfileError } from "../shared/index.js";
+import { planLifecycleInvocation, readLifecyclePlanRequest } from "./lifecyclePlan.js";
+export const registerLifecyclePlanningCommands = (program, streams, stdin) => {
+    const lifecycle = program
+        .command("lifecycle")
+        .description("Plan or read durable machine lifecycle operations");
+    lifecycle
+        .command("plan")
+        .description("Admit an exact read-only artifacts-export or down lifecycle plan")
+        .requiredOption("--request <file>", "Strict spawnfile.lifecycle-plan-request.v1 JSON file, or - for stdin")
+        .action(async (options) => {
+        streams.stdout(JSON.stringify(await planLifecycleInvocation(await readLifecyclePlanRequest(options.request, stdin)), null, 2));
+    });
+    lifecycle
+        .command("lookup")
+        .description("Read one lifecycle completion without Docker or provider inspection")
+        .argument("[invocation]", "Lifecycle invocation id")
+        .option("--lifecycle-invocation <id>", "Lifecycle invocation id")
+        .action(async (invocation, options) => {
+        const id = options.lifecycleInvocation ?? invocation;
+        if (!id ||
+            (invocation !== undefined &&
+                options.lifecycleInvocation !== undefined &&
+                invocation !== options.lifecycleInvocation)) {
+            throw new SpawnfileError("validation_error", "lifecycle lookup requires exactly one lifecycle invocation id");
+        }
+        streams.stdout(JSON.stringify(await lookupLifecycleCompletion(id), null, 2));
+    });
+};

package/dist/cli/paideiaDelegation.d.ts

@@ -0,0 +1,17 @@
+import { type TrainingContext } from "../compiler/training/index.js";
+import type { CliStreams } from "./runCli.js";
+export interface DelegatePaideiaTrainingOptions {
+    context: TrainingContext;
+    command: string;
+    args: readonly string[];
+    dryRun: boolean;
+    repairMeasurements?: string;
+    repairWitness?: string;
+    trainingImage?: string;
+    trainingConfig?: string;
+    timeoutMs: number;
+    streams: CliStreams;
+    signal?: AbortSignal;
+}
+/** Delegates through the public CLI, never importing Paideia or selecting a fallback adapter. */
+export declare const delegatePaideiaTraining: (options: DelegatePaideiaTrainingOptions) => Promise<number>;