spawnfile 0.1.12 → 0.1.14

package/dist/cli/targetSecretSourceInput.js

@@ -0,0 +1,121 @@
+import { Buffer } from "node:buffer";
+import { open } from "node:fs/promises";
+import { MAX_TARGET_SECRET_SOURCE_SECRET_BYTES, TARGET_SECRET_SOURCE_ERROR, assertOrdinaryJsonGraph, createCanonicalTargetSecretSourceJson, parseCanonicalTargetSecretSourceJson, parseTargetSecretSourceOpaqueHandle } from "../auth/targetSecretSourceRecordCommon.js";
+import { parseTargetSecretSourceGrantCommandInput } from "../auth/targetSecretSourceGrantRecords.js";
+export const TARGET_SECRET_SOURCE_REQUEST_VERSION = "spawnfile.auth.target-secret.source-request.v1";
+export const TARGET_SECRET_SOURCE_GRANT_REQUEST_VERSION = "spawnfile.auth.target-secret.grant-request.v1";
+export const TARGET_SECRET_SOURCE_RECEIPT_VERSION = "spawnfile.auth.target-secret.receipt.v1";
+export const MAX_TARGET_SECRET_SOURCE_REQUEST_FILE_BYTES = 65_536;
+const fail = () => { throw new Error(TARGET_SECRET_SOURCE_ERROR); };
+const exact = (raw, keys) => {
+    assertOrdinaryJsonGraph(raw);
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return fail();
+    const record = raw;
+    const actual = Object.keys(record).sort();
+    if (actual.length !== keys.length || actual.some((key, index) => key !== keys[index]))
+        fail();
+    return record;
+};
+export const parseTargetSecretSourceRequestBytes = (bytes) => {
+    const record = exact(parseCanonicalTargetSecretSourceJson(bytes), ["source_handle", "version"]);
+    if (record.version !== TARGET_SECRET_SOURCE_REQUEST_VERSION)
+        fail();
+    return Object.freeze({
+        source_handle: parseTargetSecretSourceOpaqueHandle(record.source_handle),
+        version: TARGET_SECRET_SOURCE_REQUEST_VERSION
+    });
+};
+export const parseTargetSecretSourceGrantRequestBytes = (bytes) => {
+    const record = exact(parseCanonicalTargetSecretSourceJson(bytes), ["grant", "version"]);
+    if (record.version !== TARGET_SECRET_SOURCE_GRANT_REQUEST_VERSION)
+        fail();
+    return parseTargetSecretSourceGrantCommandInput(record.grant);
+};
+const readRequestFile = async (filePath, parse, options) => {
+    let bytes;
+    let handle;
+    try {
+        handle = await open(filePath, "r");
+        const info = await handle.stat();
+        if (!info.isFile() || info.size < 1 || info.size > MAX_TARGET_SECRET_SOURCE_REQUEST_FILE_BYTES)
+            fail();
+        await options.beforeReadForTest?.();
+        bytes = Buffer.alloc(info.size + 1);
+        let offset = 0;
+        while (offset < bytes.length) {
+            const { bytesRead } = await handle.read(bytes, offset, bytes.length - offset, offset);
+            if (bytesRead === 0)
+                break;
+            offset += bytesRead;
+        }
+        if (offset !== info.size)
+            fail();
+        return parse(bytes.subarray(0, offset));
+    }
+    catch {
+        return fail();
+    }
+    finally {
+        bytes?.fill(0);
+        await handle?.close().catch(() => undefined);
+    }
+};
+export const readTargetSecretSourceRequestFile = (filePath, options = {}) => readRequestFile(filePath, parseTargetSecretSourceRequestBytes, options);
+export const readTargetSecretSourceGrantRequestFile = (filePath, options = {}) => readRequestFile(filePath, parseTargetSecretSourceGrantRequestBytes, options);
+export const createTargetSecretSourceReceiptBytes = (raw) => {
+    try {
+        const record = exact(raw, ["kind", "source_handle"]);
+        const kinds = ["author", "grant", "revoke-grant", "revoke-version", "rotate"];
+        if (!kinds.includes(record.kind))
+            fail();
+        const receipt = Object.freeze({
+            kind: record.kind,
+            source_handle: parseTargetSecretSourceOpaqueHandle(record.source_handle),
+            version: TARGET_SECRET_SOURCE_RECEIPT_VERSION
+        });
+        const canonical = createCanonicalTargetSecretSourceJson(receipt);
+        return canonical;
+    }
+    catch {
+        return fail();
+    }
+};
+export const readBoundedTargetSecretStdin = async (input, maximumBytes) => {
+    const chunks = [];
+    let total = 0;
+    try {
+        if (!input || typeof input[Symbol.asyncIterator] !== "function"
+            || !Number.isSafeInteger(maximumBytes) || maximumBytes < 1
+            || maximumBytes > MAX_TARGET_SECRET_SOURCE_SECRET_BYTES)
+            fail();
+        for await (const raw of input) {
+            if (typeof raw === "string" && Buffer.byteLength(raw, "utf8") > maximumBytes - total)
+                fail();
+            if (raw instanceof Uint8Array && raw.byteLength > maximumBytes - total)
+                fail();
+            const chunk = typeof raw === "string" ? new TextEncoder().encode(raw)
+                : raw instanceof Uint8Array ? Uint8Array.from(raw) : fail();
+            chunks.push(chunk);
+            total += chunk.length;
+            if (total > maximumBytes)
+                fail();
+        }
+        if (total === 0)
+            fail();
+        const result = new Uint8Array(total);
+        let offset = 0;
+        for (const chunk of chunks) {
+            result.set(chunk, offset);
+            offset += chunk.length;
+        }
+        return result;
+    }
+    catch {
+        return fail();
+    }
+    finally {
+        for (const chunk of chunks)
+            chunk.fill(0);
+    }
+};

package/dist/cli/targetWorldClockCommand.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from "commander";
+import { type TargetWorldClockReceipt, type TargetWorldClockRequest } from "../target/worldClock.js";
+export interface TargetWorldClockSession {
+    queryWorldClock?(request: TargetWorldClockRequest): Promise<TargetWorldClockReceipt>;
+}
+export type TargetWorldClockSessionLoader = (configInput: unknown) => Promise<TargetWorldClockSession>;
+export declare const registerTargetWorldClockCommand: (target: Command, session: TargetWorldClockSession | TargetWorldClockSessionLoader, streams: {
+    readonly stderr: (message: string) => void;
+    readonly stdout: (message: string) => void;
+}, setExitCode: (exitCode: 1 | 2) => void) => void;

package/dist/cli/targetWorldClockCommand.js

@@ -0,0 +1,42 @@
+import { createCanonicalTargetWorldClockReceiptBytes, verifyTargetWorldClockReceipt, } from "../target/worldClock.js";
+import { formatCaughtTargetCliError } from "./targetReceiptOutput.js";
+import { readTargetWorldClockRequestFile } from "./targetRequestFile.js";
+export const registerTargetWorldClockCommand = (target, session, streams, setExitCode) => {
+    target.command("query_world_clock")
+        .description("Query one exact activated world's observed public clock")
+        .argument("<request-file>", "Strict world clock request JSON file")
+        .action(async (requestFile) => {
+        let request;
+        try {
+            request = await readTargetWorldClockRequestFile(requestFile);
+        }
+        catch {
+            streams.stderr("error: Invalid world clock request");
+            setExitCode(2);
+            return;
+        }
+        let active;
+        try {
+            active = typeof session === "function"
+                ? await session(target.opts().config)
+                : session;
+            if (typeof active.queryWorldClock !== "function")
+                throw new TypeError();
+        }
+        catch {
+            streams.stderr("error: Invalid target configuration");
+            setExitCode(2);
+            return;
+        }
+        try {
+            const receipt = verifyTargetWorldClockReceipt({
+                receipt: await active.queryWorldClock(request), request,
+            });
+            streams.stdout(createCanonicalTargetWorldClockReceiptBytes(receipt));
+        }
+        catch (error) {
+            streams.stderr(formatCaughtTargetCliError(error, "Target world clock query crashed"));
+            setExitCode(1);
+        }
+    });
+};

package/dist/cli/targetWorldClockCrossProcess.test-helper.d.ts

@@ -0,0 +1,13 @@
+import { type TargetWorldClockRequest } from "../target/worldClock.js";
+export type BuiltWorldClockMode = "success" | "tick-zero" | "stale" | "topology" | "activation" | "nonzero-action";
+export interface BuiltWorldClockState {
+    readonly callsPath: string;
+    readonly config: Readonly<Record<string, unknown>>;
+    readonly home: string;
+    readonly modePath: string;
+    readonly request: TargetWorldClockRequest;
+    readonly requestPath: string;
+    readonly root: string;
+}
+export declare const createBuiltWorldClockState: () => Promise<BuiltWorldClockState>;
+export declare const selectBuiltWorldClockMode: (state: BuiltWorldClockState, mode: BuiltWorldClockMode) => Promise<void>;

package/dist/cli/targetWorldClockCrossProcess.test-helper.js

@@ -0,0 +1,109 @@
+import { chmod, mkdtemp, realpath, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { parseOpaqueTargetHandle } from "../target/contracts.js";
+import { createDockerArtifactSpec } from "../target/dockerArtifactsProvider.js";
+import { createDockerResourceSpec } from "../target/dockerResourcesProvider.js";
+import { createWorldServiceAuthorization, parseWorldServiceResolution } from "../target/dockerWorldServiceAuthority.js";
+import { worldServiceSpecForBinding } from "../target/dockerWorldServiceLifecycle.js";
+import { createWorldServiceBinding, initializeWorldServiceAuthorityStore, worldServiceResourceBindings, } from "../target/dockerWorldServiceStore.js";
+import { createCanonicalWorldServiceActivationBytes, createTargetTopologyActivationReceiptDigest, createWorldServiceActivationDigest, parseWorldServiceActivation, } from "../target/topologyActivation.js";
+import { parseTargetWorldClockRequest } from "../target/worldClock.js";
+const d = (value) => `sha256:${value.repeat(64).slice(0, 64)}`;
+const h = (value) => parseOpaqueTargetHandle(`opaque_${value.repeat(16)}`);
+const containerId = "c".repeat(64);
+const after = (args, flag) => args[args.indexOf(flag) + 1];
+const inspection = (spec) => ({
+    AutoRemove: false, BindCount: 0, CapAddCount: 0, CapDrop: ["ALL"], CgroupnsMode: "private", DeviceCount: 0,
+    DeviceRequestCount: 0, DnsCount: 0, Domainname: "", ExposedPortCount: 0, ExtraHostCount: 0, GroupAddCount: 0,
+    Hostname: spec.containerName, Id: containerId, Image: spec.imageReference, IpcMode: "none", Labels: spec.receiptLabels,
+    LinkCount: 0, LogType: "none", Mounts: spec.createArgs.filter((value, index, values) => values[index - 1] === "--mount")
+        .map((value) => Object.fromEntries(value.split(",").map((part) => part.split("=", 2))))
+        .map((mount) => ({ Destination: mount.dst, Name: mount.src, RW: mount.dst === spec.evidenceMountPath, Type: "volume" })),
+    Name: `/${spec.containerName}`, NetworkAliases: spec.networkAlias ? [spec.networkAlias] : null,
+    NetworkAttachmentCount: 1, NetworkAttachmentId: "b".repeat(64), NetworkAttachmentName: after(spec.createArgs, "--network"),
+    NetworkMode: after(spec.createArgs, "--network"), PidMode: "", PortBindingCount: 0, Privileged: false,
+    PublishAllPorts: false, ReadonlyRootfs: true, RestartMaximumRetryCount: 0, RestartPolicyName: "no",
+    SecurityOpt: ["no-new-privileges=true"], Status: "running", Tmpfs: { "/tmp": "rw,noexec,nosuid,nodev,size=1m,mode=1777" },
+    UTSMode: "", UsernsMode: "", VolumesFromCount: 0,
+});
+const fixture = () => {
+    const selectedTarget = { fingerprint: `sha256:${"1".repeat(32)}`, handle: h("1") };
+    const runId = "run-built-clock";
+    const dataClaim = { operationHandle: h("2"), requestDigest: d("2") };
+    const evidenceClaim = { operationHandle: h("3"), requestDigest: d("3") };
+    const data = createDockerResourceSpec({ kind: "data_network", ...dataClaim, runId, selectedTargetHandle: selectedTarget.handle });
+    const evidence = createDockerResourceSpec({ kind: "evidence_volume", ...evidenceClaim, runId, selectedTargetHandle: selectedTarget.handle });
+    const artifact = createDockerArtifactSpec({ artifactManifestDigest: d("4"), imageDigest: d("5"),
+        imageReference: `registry.example/world@${d("5")}`, operationHandle: h("4"), requestDigest: d("4"),
+        selectedTargetHandle: selectedTarget.handle });
+    const authorization = createWorldServiceAuthorization({ dataNetworkHandle: data.resultHandle, descriptorDigest: d("6"),
+        evidenceMountPath: "/run/world/evidence", evidenceVolumeHandle: evidence.resultHandle, operationHandle: h("6"),
+        requestDigest: d("6"), runId, secretBindingsHandle: h("7"), selectedTarget, worldArtifactHandle: artifact.resultHandle });
+    const resolution = parseWorldServiceResolution({ artifact: { artifact_manifest_digest: d("4"), identity_kind: "oci_image_manifest",
+            image_digest: artifact.imageDigest, image_reference: artifact.imageReference, operation_handle: h("4"),
+            request_digest: d("4"), result_handle: artifact.resultHandle }, authorization });
+    const resources = worldServiceResourceBindings({ dataNetworkClaim: dataClaim, evidenceVolumeClaim: evidenceClaim, resolution });
+    const spec = worldServiceSpecForBinding({ resolution, resources });
+    const binding = createWorldServiceBinding({ containerId, dataNetwork: resources.data_network, evidenceVolume: resources.evidence_volume,
+        resolution, secretBindings: resources.secret_bindings, spec });
+    const marker = parseWorldServiceActivation({ bundle_digest: d("8"), run_id: runId, state: "activated",
+        topology_receipt_digest: d("9"), topology_request_digest: d("a"), version: "spawnfile.world-service-activation.v1" });
+    const activationDigest = createWorldServiceActivationDigest(marker);
+    const activationReceiptDigest = createTargetTopologyActivationReceiptDigest({ activation_digest: activationDigest,
+        bundle_digest: marker.bundle_digest, receipt_digest: d("0"), run_id: runId, state: "activated",
+        topology_receipt_digest: marker.topology_receipt_digest, topology_request_digest: marker.topology_request_digest,
+        version: "spawnfile.target-topology-activation-receipt.v1" });
+    const request = parseTargetWorldClockRequest({ activation_digest: activationDigest,
+        activation_receipt_digest: activationReceiptDigest, descriptor_digest: authorization.descriptor_digest,
+        endpoint: { internal_port: 4_070, path: "/v1/world/clock" },
+        expected: { document_version: "world.clock-document.v1", world_instance_id: "world-built-clock" }, run_id: runId,
+        selected_target: selectedTarget, topology_receipt_digest: marker.topology_receipt_digest,
+        topology_request_digest: marker.topology_request_digest, version: "spawnfile.target-world-clock.request.v1",
+        world_service_handle: binding.world_service_handle });
+    return { binding, marker, request, spec };
+};
+export const createBuiltWorldClockState = async () => {
+    const root = await realpath(await mkdtemp(path.join(os.tmpdir(), "spawnfile-built-world-clock-")));
+    const home = path.join(root, "home");
+    const callsPath = path.join(root, "docker-calls.ndjson");
+    const modePath = path.join(root, "mode");
+    const scenariosPath = path.join(root, "scenarios.json");
+    const fakeDocker = path.join(root, "docker-clock");
+    const requestPath = path.join(root, "request.json");
+    const { binding, marker, request, spec } = fixture();
+    const store = await initializeWorldServiceAuthorityStore(path.join(home, "target", "world-authority"));
+    await store.bindService(binding);
+    const observation = { action_count: 0, clock: { completed_tick: 1, next_tick: 2, state: "running" },
+        run_id: request.run_id, version: request.expected.document_version, world_instance_id: request.expected.world_instance_id };
+    const topologyMarker = parseWorldServiceActivation({ ...marker, topology_receipt_digest: d("b") });
+    const activationMarker = parseWorldServiceActivation({ ...marker, bundle_digest: d("c") });
+    const scenarios = {
+        success: { marker: createCanonicalWorldServiceActivationBytes(marker), observation: JSON.stringify(observation) },
+        "tick-zero": { marker: createCanonicalWorldServiceActivationBytes(marker), observation: JSON.stringify({ ...observation,
+                clock: { completed_tick: 0, next_tick: 1, state: "running" } }) },
+        stale: { marker: createCanonicalWorldServiceActivationBytes(marker), observation: JSON.stringify({ ...observation, run_id: "run-stale-clock" }) },
+        topology: { marker: createCanonicalWorldServiceActivationBytes(topologyMarker), observation: JSON.stringify(observation) },
+        activation: { marker: createCanonicalWorldServiceActivationBytes(activationMarker), observation: JSON.stringify(observation) },
+        "nonzero-action": { marker: createCanonicalWorldServiceActivationBytes(marker), observation: JSON.stringify({ ...observation, action_count: 1 }) },
+    };
+    await writeFile(callsPath, "", { mode: 0o600 });
+    await writeFile(modePath, "success", { mode: 0o600 });
+    await writeFile(scenariosPath, JSON.stringify(scenarios), { mode: 0o600 });
+    await writeFile(requestPath, JSON.stringify(request), { mode: 0o600 });
+    await writeFile(fakeDocker, `#!${process.execPath}
+const fs=require("node:fs");const args=process.argv.slice(2);
+fs.appendFileSync(${JSON.stringify(callsPath)},JSON.stringify(args)+"\\n");
+const all=JSON.parse(fs.readFileSync(${JSON.stringify(scenariosPath)},"utf8"));
+const current=all[fs.readFileSync(${JSON.stringify(modePath)},"utf8").trim()];
+if(args[2]==="container"&&args[3]==="inspect")process.stdout.write(${JSON.stringify(JSON.stringify([inspection(spec)]))});
+else if(args[2]==="container"&&args[3]==="exec"&&args.includes("/bin/cat"))process.stdout.write(current.marker);
+else if(args[2]==="container"&&args[3]==="exec"&&args.includes("/usr/local/bin/node"))process.stdout.write(current.observation);
+else{process.stderr.write("unexpected fake Docker command\\n");process.exitCode=71;}
+`, { mode: 0o700 });
+    await chmod(fakeDocker, 0o700);
+    return { callsPath, config: { context: "built_clock", dockerCommand: fakeDocker,
+            evidenceDestination: path.join(root, "unused.tar"), timeoutMs: 10_000,
+            version: "spawnfile.target-default-config.v1" }, home, modePath, request, requestPath, root };
+};
+export const selectBuiltWorldClockMode = async (state, mode) => { await writeFile(state.modePath, mode, { mode: 0o600 }); };

package/dist/cli/targetWorldReadinessCommand.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from "commander";
+import { type TargetWorldReadinessRequest, type TargetWorldReadinessReceipt } from "../target/worldReadiness.js";
+export interface TargetWorldReadinessSession {
+    queryWorldReadiness?(request: TargetWorldReadinessRequest): Promise<TargetWorldReadinessReceipt>;
+}
+export type TargetWorldReadinessSessionLoader = (configInput: unknown) => Promise<TargetWorldReadinessSession>;
+export declare const registerTargetWorldReadinessCommand: (target: Command, session: TargetWorldReadinessSession | TargetWorldReadinessSessionLoader, streams: {
+    readonly stderr: (message: string) => void;
+    readonly stdout: (message: string) => void;
+}, setExitCode: (exitCode: 1 | 2) => void) => void;

package/dist/cli/targetWorldReadinessCommand.js

@@ -0,0 +1,43 @@
+import { createCanonicalTargetWorldReadinessReceiptBytes, verifyTargetWorldReadinessReceipt } from "../target/worldReadiness.js";
+import { formatCaughtTargetCliError } from "./targetReceiptOutput.js";
+import { readTargetWorldReadinessRequestFile } from "./targetRequestFile.js";
+export const registerTargetWorldReadinessCommand = (target, session, streams, setExitCode) => {
+    target.command("query_world_readiness")
+        .description("Query one exact running world's public readiness document")
+        .argument("<request-file>", "Strict world readiness request JSON file")
+        .action(async (requestFile) => {
+        let request;
+        try {
+            request = await readTargetWorldReadinessRequestFile(requestFile);
+        }
+        catch {
+            streams.stderr("error: Invalid world readiness request");
+            setExitCode(2);
+            return;
+        }
+        let activeSession;
+        try {
+            activeSession = typeof session === "function"
+                ? await session(target.opts().config)
+                : session;
+            if (typeof activeSession.queryWorldReadiness !== "function")
+                throw new TypeError();
+        }
+        catch {
+            streams.stderr("error: Invalid target configuration");
+            setExitCode(2);
+            return;
+        }
+        try {
+            const receipt = verifyTargetWorldReadinessReceipt({
+                receipt: await activeSession.queryWorldReadiness(request),
+                request
+            });
+            streams.stdout(createCanonicalTargetWorldReadinessReceiptBytes(receipt));
+        }
+        catch (error) {
+            streams.stderr(formatCaughtTargetCliError(error, "Target world readiness query crashed"));
+            setExitCode(1);
+        }
+    });
+};

package/dist/cli/upCommand.d.ts

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

package/dist/cli/upCommand.js

@@ -0,0 +1,133 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { createDeploymentInstanceDigest, readDeploymentRecord, recordLifecycleOutcomeEvidence } from "../deployment/index.js";
+import { SpawnfileError } from "../shared/index.js";
+import { requireMachineLifecycle, runMachineLifecycle } from "./lifecycleMachine.js";
+import { resolveCommandInput } from "./resolveCommandInput.js";
+import { runImageUpCommand } from "./upImageCommand.js";
+import { createUpLifecycleInvocation, createUpProjectOptions } from "./upLifecycleInvocation.js";
+import { reconcileUpLifecycle } from "./upLifecycleRecovery.js";
+const readSelectedTargetReceipt = async (file) => {
+    if (typeof file !== "string" || file.length < 1 || Buffer.byteLength(file, "utf8") > 4096) {
+        throw new SpawnfileError("validation_error", "Invalid selected target receipt");
+    }
+    let handle;
+    try {
+        handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size < 1 || stat.size > 65_536)
+            throw new Error();
+        return JSON.parse(await handle.readFile("utf8"));
+    }
+    catch {
+        throw new SpawnfileError("validation_error", "Invalid selected target receipt");
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+};
+export const registerUpCommand = (program, handlers, streams) => {
+    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("--world-bindings <file>", "Path to a versioned world-bindings artifact")
+        .option("--selected-target-receipt-digest <digest>", "Selected target receipt digest for an organization handoff")
+        .option("--selected-target-receipt <file>", "Selected target receipt for an organization handoff")
+        .option("--network-attachment-handle <handle>", "Opaque network attachment handle for an organization handoff")
+        .option("--organization-handoff-run-id <id>", "Authorized run id for an organization handoff")
+        .option("--descriptor-digest <digest>", "Production descriptor digest for an organization handoff")
+        .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")
+        .option("--json", "Render a spawnfile.up-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 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") {
+            if (options.selectedTargetReceiptDigest !== undefined ||
+                options.selectedTargetReceipt !== undefined ||
+                options.networkAttachmentHandle !== undefined ||
+                options.organizationHandoffRunId !== undefined ||
+                options.descriptorDigest !== undefined) {
+                throw new SpawnfileError("validation_error", "Organization handoff inputs are only supported for project-mode deployments");
+            }
+            if (options.worldBindings !== undefined) {
+                throw new SpawnfileError("validation_error", "`--world-bindings` is only supported for project-mode deployments");
+            }
+            if (options.json) {
+                throw new SpawnfileError("validation_error", "`spawnfile up --json` is not yet supported for image-mode deployments " +
+                    "(there is no source Spawnfile to derive compiled_schedule from).");
+            }
+            await runImageUpCommand(upInput.ref, options, handlers, streams);
+            return;
+        }
+        const handoffValues = [
+            options.descriptorDigest,
+            options.organizationHandoffRunId,
+            options.selectedTargetReceipt,
+            options.selectedTargetReceiptDigest,
+            options.networkAttachmentHandle,
+            options.worldBindings
+        ];
+        if (handoffValues.some((value) => value !== undefined) &&
+            handoffValues.some((value) => value === undefined)) {
+            throw new SpawnfileError("validation_error", "Organization handoff requires --organization-handoff-run-id, --descriptor-digest, --selected-target-receipt, --selected-target-receipt-digest, --network-attachment-handle, and --world-bindings");
+        }
+        if (options.lifecycleInvocation !== undefined &&
+            (!options.detach ||
+                !options.deployment ||
+                handoffValues.some((value) => value === undefined))) {
+            throw new SpawnfileError("validation_error", "Machine lifecycle up requires a detached deployment with durable organization handoff authority");
+        }
+        if (options.json) {
+            const exactInvocation = options.lifecycleInvocation === undefined
+                ? undefined
+                : createUpLifecycleInvocation(inputPath, {
+                    ...options,
+                    forceImage: options.image,
+                    lifecycleInvocation: options.lifecycleInvocation
+                });
+            const render = async (capability) => {
+                const selectedTargetReceipt = options.selectedTargetReceipt === undefined
+                    ? undefined
+                    : await readSelectedTargetReceipt(options.selectedTargetReceipt);
+                const result = await handlers.upProject(inputPath, createUpProjectOptions({ ...options, selectedTargetReceipt }));
+                const receipt = await handlers.buildUpReceipt(inputPath, result);
+                const bytes = JSON.stringify(receipt, null, 2);
+                if (exactInvocation && capability) {
+                    await recordLifecycleOutcomeEvidence(exactInvocation, bytes, capability, result.deploymentRecordPath
+                        ? createDeploymentInstanceDigest(await readDeploymentRecord(result.deploymentRecordPath))
+                        : "");
+                }
+                return bytes;
+            };
+            const output = options.lifecycleInvocation === undefined
+                ? await render()
+                : await runMachineLifecycle(exactInvocation, render, () => reconcileUpLifecycle(inputPath, options, exactInvocation));
+            streams.stdout(output);
+            return;
+        }
+        const result = await handlers.upProject(inputPath, createUpProjectOptions(options));
+        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}`);
+        }
+    });
+};

package/dist/cli/upImageCommand.d.ts

@@ -0,0 +1,11 @@
+import type { CliHandlers, CliStreams } from "./runCli.js";
+interface ImageUpOptions {
+    authProfile?: string;
+    context?: string;
+    deployment?: string;
+    dockerCommand?: string;
+    envFile?: string;
+    pull?: boolean;
+}
+export declare const runImageUpCommand: (ref: string, options: ImageUpOptions, handlers: CliHandlers, streams: CliStreams) => Promise<void>;
+export {};

package/dist/cli/upImageCommand.js

@@ -0,0 +1,41 @@
+import { readRunEnvFile } from "../compiler/runProjectAuth.js";
+const shortDigest = (digest) => digest ? digest.replace(/^sha256:/, "").slice(0, 12) : "unknown";
+const redeploySummary = (previous, newRef, newDigest) => {
+    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 runImageUpCommand = async (ref, options, handlers, streams) => {
+    const authProfile = options.authProfile && handlers.requireAuthProfile
+        ? await handlers.requireAuthProfile(options.authProfile)
+        : null;
+    const envFileEnv = await readRunEnvFile(options.envFile);
+    const consumed = await handlers.consumeImageUp(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 digest = consumed.record.source.kind === "image"
+            ? consumed.record.source.digest
+            : null;
+        streams.stdout(redeploySummary(consumed.previous, consumed.imageRef, digest));
+    }
+    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`);
+};

package/dist/cli/upLifecycleInvocation.d.ts

@@ -0,0 +1,41 @@
+import type { LifecycleInvocation } from "../deployment/index.js";
+export interface UpLifecycleOptions {
+    authProfile?: string;
+    context?: string;
+    deployment?: string;
+    descriptorDigest?: string;
+    detach?: boolean;
+    dockerCommand?: string;
+    envFile?: string;
+    forceImage?: boolean;
+    lifecycleInvocation?: string;
+    name?: string;
+    networkAttachmentHandle?: string;
+    organizationHandoffRunId?: string;
+    out?: string;
+    pull?: boolean;
+    selectedTargetReceipt?: unknown;
+    selectedTargetReceiptDigest?: string;
+    tag?: string;
+    worldBindings?: string;
+}
+export declare const createUpLifecycleInvocation: (inputPath: string, options: UpLifecycleOptions & {
+    lifecycleInvocation: string;
+}) => LifecycleInvocation;
+export declare const createUpProjectOptions: (options: UpLifecycleOptions) => {
+    worldBindingsPath?: string | undefined;
+    selectedTargetReceipt?: {} | null | undefined;
+    selectedTargetReceiptDigest?: string | undefined;
+    networkAttachmentHandle?: string | undefined;
+    authProfile: string | undefined;
+    containerName: string | undefined;
+    detach: boolean | undefined;
+    deploymentName: string | undefined;
+    dockerCommand: string | undefined;
+    dockerContext: string | undefined;
+    descriptorDigest: string | undefined;
+    envFilePath: string | undefined;
+    imageTag: string | undefined;
+    organizationHandoffRunId: string | undefined;
+    outputDirectory: string | undefined;
+};

package/dist/cli/upLifecycleInvocation.js

@@ -0,0 +1,48 @@
+import path from "node:path";
+import { createLifecycleInvocation, digestLifecycleBinding, } from "./lifecycleMachine.js";
+export const createUpLifecycleInvocation = (inputPath, options) => createLifecycleInvocation(options.lifecycleInvocation, "up", {
+    input_kind: "project",
+    project_path: path.resolve(inputPath),
+}, {
+    auth_profile_digest: digestLifecycleBinding(options.authProfile),
+    container_name: options.name ?? null,
+    deployment: options.deployment ?? null,
+    detach: options.detach ?? false,
+    docker_command_digest: digestLifecycleBinding(options.dockerCommand),
+    docker_context: options.context ?? null,
+    descriptor_digest: options.descriptorDigest ?? null,
+    env_file_digest: digestLifecycleBinding(options.envFile),
+    force_image: options.forceImage ?? false,
+    image_tag: options.tag ?? null,
+    network_attachment_handle_digest: digestLifecycleBinding(options.networkAttachmentHandle),
+    organization_handoff_run_id: options.organizationHandoffRunId ?? null,
+    output_directory: options.out ? path.resolve(options.out) : null,
+    pull: options.pull ?? false,
+    selected_target_receipt_digest: options.selectedTargetReceiptDigest ?? null,
+    world_bindings_digest: digestLifecycleBinding(options.worldBindings),
+});
+export const createUpProjectOptions = (options) => ({
+    authProfile: options.authProfile,
+    containerName: options.name,
+    detach: options.detach,
+    deploymentName: options.deployment,
+    dockerCommand: options.dockerCommand,
+    dockerContext: options.context,
+    descriptorDigest: options.descriptorDigest,
+    envFilePath: options.envFile,
+    imageTag: options.tag,
+    organizationHandoffRunId: options.organizationHandoffRunId,
+    outputDirectory: options.out,
+    ...(options.networkAttachmentHandle !== undefined
+        ? { networkAttachmentHandle: options.networkAttachmentHandle }
+        : {}),
+    ...(options.selectedTargetReceiptDigest !== undefined
+        ? { selectedTargetReceiptDigest: options.selectedTargetReceiptDigest }
+        : {}),
+    ...(options.selectedTargetReceipt !== undefined
+        ? { selectedTargetReceipt: options.selectedTargetReceipt }
+        : {}),
+    ...(options.worldBindings !== undefined
+        ? { worldBindingsPath: options.worldBindings }
+        : {}),
+});

package/dist/cli/upLifecycleRecovery.d.ts

@@ -0,0 +1,4 @@
+import { findLifecycleOutcomeEvidence } from "../deployment/index.js";
+import type { LifecycleReconciliation } from "./lifecycleMachine.js";
+import type { UpLifecycleOptions } from "./upLifecycleInvocation.js";
+export declare const reconcileUpLifecycle: (inputPath: string, options: UpLifecycleOptions, invocation: Parameters<typeof findLifecycleOutcomeEvidence>[0]) => Promise<LifecycleReconciliation>;