spawnfile 0.1.13 → 0.1.17

package/dist/cli/composedLifecycleContractSet.js

@@ -0,0 +1,204 @@
+import { CREDENTIAL_PROVISIONING_RECEIPT_VERSION, CREDENTIAL_PROVISIONING_REQUEST_VERSION, RESOLVED_WORLD_GRANTS_VERSION, } from "../auth/index.js";
+import { DOWN_RECEIPT_VERSION, EXPORT_INDEX_VERSION, LIFECYCLE_INVOCATION_VERSION, LIFECYCLE_LOOKUP_VERSION, UP_RECEIPT_VERSION, } from "../deployment/index.js";
+import { PREPARED_EVIDENCE_HELPER_RECEIPT_VERSION } from "../evidenceExportHelper/index.js";
+import { COMPOSED_PREPARATION_RECEIPT_VERSION, COMPOSED_PREPARATION_REQUEST_VERSION, SELECTED_TARGET_VERSION, TARGET_EXPORT_INDEX_VERSION, TARGET_OPERATION_LOOKUP_VERSION, TARGET_RESOURCE_RECEIPT_VERSION, TARGET_RESOURCE_REQUEST_VERSION, TARGET_TOPOLOGY_ATTESTATION_REQUEST_VERSION, TARGET_TOPOLOGY_RECEIPT_VERSION, TARGET_WORLD_CLOCK_RECEIPT_VERSION, TARGET_WORLD_CLOCK_REQUEST_VERSION, TARGET_WORLD_READINESS_RECEIPT_VERSION, TARGET_WORLD_READINESS_REQUEST_VERSION, } from "../target/index.js";
+import { TARGET_LOCAL_BUNDLE_LOOKUP_VERSION, TARGET_LOCAL_BUNDLE_PREPARE_RECEIPT_VERSION, TARGET_LOCAL_BUNDLE_PREPARE_REQUEST_VERSION, } from "../target/containerBundleContracts.js";
+import { TARGET_LOCAL_CONTAINER_BUNDLE_POLICY } from "../target/containerBundlePolicy.js";
+import { TARGET_PUBLIC_ARTIFACT_SNAPSHOT_NOT_PRESENT_VERSION, TARGET_PUBLIC_ARTIFACT_SNAPSHOT_REQUEST_VERSION, TARGET_PUBLIC_ARTIFACT_SNAPSHOT_VERSION, } from "../target/publicArtifactSnapshot.js";
+import { TARGET_TOPOLOGY_ACTIVATION_RECEIPT_VERSION } from "../target/topologyActivation.js";
+import { LIFECYCLE_PLAN_REQUEST_VERSION, } from "./lifecyclePlan.js";
+import { TARGET_DEFAULT_CONFIG_STDIN_VERSION, TARGET_LOOKUP_CONFIG_STDIN_VERSION, } from "./targetDefaultConfigStdin.js";
+import { TARGET_CONFIG_PREPARED_PLAN_ABI_VERSION, TARGET_CONFIG_RESOLUTION_VERSION, } from "./targetConfigResolver.js";
+import { TARGET_SECRET_SOURCE_GRANT_REQUEST_VERSION, TARGET_SECRET_SOURCE_RECEIPT_VERSION, TARGET_SECRET_SOURCE_REQUEST_VERSION, } from "./targetSecretSourceInput.js";
+export const COMPOSED_LIFECYCLE_CONTRACT_SET_VERSION = "spawnfile.composed-lifecycle-contract-set.v1";
+const immutable = (values = []) => Object.freeze([...values]);
+const command = (argv, versions) => Object.freeze({
+    argv: immutable(argv),
+    invocation_versions: immutable(versions.invocation_versions),
+    pending_versions: immutable(versions.pending_versions),
+    receipt_versions: immutable(versions.receipt_versions),
+    request_versions: immutable(versions.request_versions),
+    stdin_versions: immutable(versions.stdin_versions),
+    stdout: versions.stdout,
+});
+const targetMutation = (operation, receiptVersions = [TARGET_RESOURCE_RECEIPT_VERSION]) => command(["target", "--config", "-", operation, "<request-file>"], {
+    receipt_versions: receiptVersions,
+    request_versions: [TARGET_RESOURCE_REQUEST_VERSION],
+    stdin_versions: [TARGET_DEFAULT_CONFIG_STDIN_VERSION],
+    stdout: "json",
+});
+const machineLifecycle = (argv, receiptVersion) => command(argv, {
+    invocation_versions: [LIFECYCLE_INVOCATION_VERSION],
+    pending_versions: [LIFECYCLE_LOOKUP_VERSION],
+    receipt_versions: [receiptVersion],
+    stdout: "json",
+});
+/**
+ * Closed inventory for consumers that compose only public CLI and receipt
+ * contracts. `argv` records one canonical invocation form, not every
+ * presentation-only optional flag accepted by Commander.
+ */
+export const COMPOSED_LIFECYCLE_COMMANDS = Object.freeze([
+    command(["capabilities", "--json"], {
+        receipt_versions: ["spawnfile.capabilities.v1"], stdout: "json",
+    }),
+    command(["validate", "<project>"], { stdout: "text" }),
+    command(["compile", "<project>", "--out", "<directory>"], { stdout: "text" }),
+    command(["auth", "provision", "<request-file>"], {
+        receipt_versions: [CREDENTIAL_PROVISIONING_RECEIPT_VERSION],
+        request_versions: [CREDENTIAL_PROVISIONING_REQUEST_VERSION, RESOLVED_WORLD_GRANTS_VERSION],
+        stdout: "json",
+    }),
+    command(["auth", "target-secret", "author"], {
+        receipt_versions: [TARGET_SECRET_SOURCE_RECEIPT_VERSION], stdout: "json",
+    }),
+    command(["auth", "target-secret", "grant", "<request-file>"], {
+        receipt_versions: [TARGET_SECRET_SOURCE_RECEIPT_VERSION],
+        request_versions: [TARGET_SECRET_SOURCE_GRANT_REQUEST_VERSION],
+        stdout: "json",
+    }),
+    command(["auth", "target-secret", "rotate", "<request-file>"], {
+        receipt_versions: [TARGET_SECRET_SOURCE_RECEIPT_VERSION],
+        request_versions: [TARGET_SECRET_SOURCE_REQUEST_VERSION],
+        stdout: "json",
+    }),
+    command(["auth", "target-secret", "revoke-grant", "<request-file>"], {
+        receipt_versions: [TARGET_SECRET_SOURCE_RECEIPT_VERSION],
+        request_versions: [TARGET_SECRET_SOURCE_REQUEST_VERSION],
+        stdout: "json",
+    }),
+    command(["auth", "target-secret", "revoke-version", "<request-file>"], {
+        receipt_versions: [TARGET_SECRET_SOURCE_RECEIPT_VERSION],
+        request_versions: [TARGET_SECRET_SOURCE_REQUEST_VERSION],
+        stdout: "json",
+    }),
+    command(["helper", "prepare-evidence-export", "--context", "<name>", "--json"], {
+        receipt_versions: [PREPARED_EVIDENCE_HELPER_RECEIPT_VERSION], stdout: "json",
+    }),
+    command(["target", "resolve_config", "--evidence-destination", "<absolute-path>"], {
+        receipt_versions: [TARGET_CONFIG_RESOLUTION_VERSION], stdout: "json",
+    }),
+    command([
+        "target", "resolve_config", "--evidence-destination", "<absolute-path>",
+        "--prepared-plan", "<private-plan>",
+    ], {
+        receipt_versions: [TARGET_CONFIG_RESOLUTION_VERSION],
+        request_versions: [TARGET_CONFIG_PREPARED_PLAN_ABI_VERSION],
+        stdout: "json",
+    }),
+    command([
+        "target", "resolve_config", "--context", "<local-context>",
+        "--evidence-destination", "<absolute-path>", "--prepare-evidence-helper",
+    ], {
+        receipt_versions: [TARGET_CONFIG_RESOLUTION_VERSION, PREPARED_EVIDENCE_HELPER_RECEIPT_VERSION],
+        stdout: "json",
+    }),
+    command(["target", "--config", "-", "select_target", "<request-file>"], {
+        receipt_versions: [SELECTED_TARGET_VERSION],
+        request_versions: [TARGET_RESOURCE_REQUEST_VERSION],
+        stdin_versions: [TARGET_DEFAULT_CONFIG_STDIN_VERSION],
+        stdout: "json",
+    }),
+    ...[
+        "resolve_world_artifact", "prepare_secret_bindings", "create_data_network",
+        "create_evidence_volume", "attach_organization", "create_world_service",
+        "start_world_service", "stop_world_service",
+        "revoke_secret_bindings", "detach_organization", "cleanup_run", "recover_operation",
+    ].map((operation) => targetMutation(operation)),
+    command(["target", "--config", "-", "prepare_composed_run", "<request-file>"], {
+        receipt_versions: [COMPOSED_PREPARATION_RECEIPT_VERSION],
+        request_versions: [COMPOSED_PREPARATION_REQUEST_VERSION],
+        stdin_versions: [TARGET_DEFAULT_CONFIG_STDIN_VERSION],
+        stdout: "json",
+    }),
+    command(["target", "--config", "-", "attest_topology", "<request-file>"], {
+        receipt_versions: [TARGET_TOPOLOGY_RECEIPT_VERSION],
+        request_versions: [TARGET_TOPOLOGY_ATTESTATION_REQUEST_VERSION],
+        stdin_versions: [TARGET_DEFAULT_CONFIG_STDIN_VERSION],
+        stdout: "json",
+    }),
+    command(["target", "--config", "-", "activate_topology", "<request-file>"], {
+        receipt_versions: [TARGET_TOPOLOGY_ACTIVATION_RECEIPT_VERSION],
+        request_versions: [TARGET_TOPOLOGY_ATTESTATION_REQUEST_VERSION],
+        stdin_versions: [TARGET_DEFAULT_CONFIG_STDIN_VERSION],
+        stdout: "json",
+    }),
+    command(["target", "--config", "-", "query_world_readiness", "<request-file>"], {
+        receipt_versions: [TARGET_WORLD_READINESS_RECEIPT_VERSION],
+        request_versions: [TARGET_WORLD_READINESS_REQUEST_VERSION],
+        stdin_versions: [TARGET_DEFAULT_CONFIG_STDIN_VERSION],
+        stdout: "json",
+    }),
+    command(["target", "--config", "-", "query_world_clock", "<request-file>"], {
+        receipt_versions: [TARGET_WORLD_CLOCK_RECEIPT_VERSION],
+        request_versions: [TARGET_WORLD_CLOCK_REQUEST_VERSION],
+        stdin_versions: [TARGET_DEFAULT_CONFIG_STDIN_VERSION],
+        stdout: "json",
+    }),
+    command(["target", "--config", "-", "snapshot_public_artifact", "<request-file>"], {
+        receipt_versions: [
+            TARGET_PUBLIC_ARTIFACT_SNAPSHOT_VERSION,
+            TARGET_PUBLIC_ARTIFACT_SNAPSHOT_NOT_PRESENT_VERSION,
+        ],
+        request_versions: [TARGET_PUBLIC_ARTIFACT_SNAPSHOT_REQUEST_VERSION],
+        stdin_versions: [TARGET_DEFAULT_CONFIG_STDIN_VERSION],
+        stdout: "json",
+    }),
+    command(["target", "--config", "-", "lookup_operation", "<request-file>"], {
+        pending_versions: [TARGET_OPERATION_LOOKUP_VERSION],
+        receipt_versions: [TARGET_OPERATION_LOOKUP_VERSION],
+        request_versions: [TARGET_RESOURCE_REQUEST_VERSION],
+        stdin_versions: [TARGET_LOOKUP_CONFIG_STDIN_VERSION],
+        stdout: "json",
+    }),
+    command(["target", "--config", "-", "derive_container_bundle_policy", "<claims-file>"], {
+        receipt_versions: [TARGET_LOCAL_CONTAINER_BUNDLE_POLICY.version], stdout: "json",
+    }),
+    command(["target", "--config", "-", "prepare_container_bundle", "<request-file>"], {
+        receipt_versions: [TARGET_LOCAL_BUNDLE_PREPARE_RECEIPT_VERSION],
+        request_versions: [TARGET_LOCAL_BUNDLE_PREPARE_REQUEST_VERSION],
+        stdin_versions: [TARGET_DEFAULT_CONFIG_STDIN_VERSION],
+        stdout: "json",
+    }),
+    command(["target", "--config", "-", "recover_container_bundle", "<request-file>"], {
+        receipt_versions: [TARGET_LOCAL_BUNDLE_PREPARE_RECEIPT_VERSION],
+        request_versions: [TARGET_LOCAL_BUNDLE_PREPARE_REQUEST_VERSION],
+        stdin_versions: [TARGET_DEFAULT_CONFIG_STDIN_VERSION],
+        stdout: "json",
+    }),
+    command(["target", "--config", "-", "lookup_container_bundle", "<lookup-file>"], {
+        pending_versions: [TARGET_LOCAL_BUNDLE_LOOKUP_VERSION],
+        receipt_versions: [TARGET_LOCAL_BUNDLE_LOOKUP_VERSION],
+        request_versions: [TARGET_LOCAL_BUNDLE_LOOKUP_VERSION],
+        stdin_versions: [TARGET_DEFAULT_CONFIG_STDIN_VERSION],
+        stdout: "json",
+    }),
+    command(["lifecycle", "plan", "--request", "<file|->"], {
+        receipt_versions: [LIFECYCLE_INVOCATION_VERSION],
+        request_versions: [LIFECYCLE_PLAN_REQUEST_VERSION],
+        stdout: "json",
+    }),
+    command(["lifecycle", "lookup", "<id>"], {
+        pending_versions: [LIFECYCLE_LOOKUP_VERSION],
+        receipt_versions: [LIFECYCLE_LOOKUP_VERSION],
+        stdout: "json",
+    }),
+    machineLifecycle([
+        "up", "<project>", "--detach", "--deployment", "<name>", "--json",
+        "--lifecycle-invocation", "<id>", "--organization-handoff-run-id", "<run-id>",
+        "--descriptor-digest", "<digest>", "--selected-target-receipt", "<file>",
+        "--selected-target-receipt-digest", "<digest>", "--network-attachment-handle", "<handle>",
+        "--world-bindings", "<file>",
+    ], UP_RECEIPT_VERSION),
+    machineLifecycle([
+        "artifacts", "export", "<project>", "--out", "<directory>", "--json",
+        "--lifecycle-invocation", "<id>",
+    ], EXPORT_INDEX_VERSION),
+    machineLifecycle([
+        "down", "<project>", "--deployment", "<name>", "--json",
+        "--lifecycle-invocation", "<id>",
+    ], DOWN_RECEIPT_VERSION),
+    targetMutation("export_evidence_volume", [
+        TARGET_RESOURCE_RECEIPT_VERSION, TARGET_EXPORT_INDEX_VERSION,
+    ]),
+]);

package/dist/cli/containerBundleCommand.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from "commander";
+/** Production-only command. Its stdout is the secret-free canonical receipt. */
+export declare const registerContainerBundleCommand: (target: Command, stdin: AsyncIterable<unknown>, streams: {
+    stderr(message: string): void;
+    stdout(message: string): void;
+}, setExitCode: (value: 1 | 2) => void) => void;

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/devCommands.js

@@ -11,6 +11,7 @@ export const registerDevCommands = (program, handlers, streams) => {
         .command("up")
         .description("Compile, build, and start a detached dev deployment under .spawn-dev")
         .argument("[path]", "Project directory or Spawnfile path", process.cwd())
+        .option("--allow-declared-volumes", "Attach author-declared volumes by name, which a production deployment of this project also uses")
         .option("--auth-profile <name>", "Local Spawnfile auth profile")
         .option("--context <name>", "Docker context for the deployment target")
         .option("--deployment <name>", "Detached deployment record name")
@@ -21,6 +22,7 @@ export const registerDevCommands = (program, handlers, streams) => {
         .option("-t, --tag <image>", "Docker image tag")
         .action(async (inputPath, options) => {
         const result = await handlers.devUpProject(inputPath, {
+            allowDeclaredVolumeNames: options.allowDeclaredVolumes,
             authProfile: options.authProfile,
             containerName: options.name,
             deploymentName: options.deployment,

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,145 @@
+import path from "node:path";
+import { createDeploymentLifecycleCorrelation, findLifecycleInvocation, readCanonicalDownRecord, } 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 this deployment's own named volumes (author-declared names are shared project state and are always skipped)")
+        .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 readCanonicalDownRecord(compiled, options.deployment)).record.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 } : {}),
+            });
+            // A deliberately skipped declared volume is shared project state, not
+            // an incomplete teardown: retrying can never remove it, so counting it
+            // as incompleteness would make a `--volumes` lifecycle down of any
+            // project with a declared name retry forever.
+            const skipped = new Set(receipt.skipped_volumes ?? []);
+            const unexpectedlyRetained = receipt.retained_volumes.filter((volume) => !skipped.has(volume));
+            if (expectedUnits !== undefined &&
+                (receipt.errors.length !== 0 ||
+                    (options.volumes === true && unexpectedlyRetained.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 readCanonicalDownRecord(compiled, options.deployment)).record;
+                correlation = createDeploymentLifecycleCorrelation(record);
+                exact = createDownLifecycleInvocation(options.lifecycleInvocation, compiled, options, correlation);
+            }
+            const output = await runMachineLifecycle(exact, () => render(correlation), async () => {
+                try {
+                    const current = createDeploymentLifecycleCorrelation((await readCanonicalDownRecord(compiled, options.deployment)).record);
+                    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}`));
+        const skippedVolumes = new Set(receipt.skipped_volumes ?? []);
+        receipt.retained_volumes.forEach((volume) => streams.stdout(skippedVolumes.has(volume)
+            ? `skipped volume (author-declared, shared with every deployment of this project): ${volume}`
+            : `retained volume: ${volume}`));
+        if (skippedVolumes.size > 0) {
+            streams.stdout(`remove shared project state deliberately: docker volume rm ${[...skippedVolumes].join(" ")}`);
+        }
+        receipt.errors.forEach((error) => streams.stderr(`error: ${error}`));
+    });
+};

package/dist/cli/evidenceExportHelperCommand.d.ts

@@ -0,0 +1,13 @@
+import type { Command } from "commander";
+import { type PreparedEvidenceHelperReceipt } from "../evidenceExportHelper/index.js";
+import type { DockerArtifactExecutor } from "../target/dockerArtifactsProvider.js";
+import type { CliStreams } from "./runCli.js";
+export interface PrepareEvidenceExportHelperInput {
+    readonly baseImage: string;
+    readonly context: string;
+    readonly dockerCommand: string;
+    readonly timeoutMs: number;
+}
+export type PrepareEvidenceExportHelper = (input: PrepareEvidenceExportHelperInput) => Promise<PreparedEvidenceHelperReceipt>;
+export declare const createDefaultEvidenceExportHelperPreparer: (executorFor?: (dockerCommand: string) => DockerArtifactExecutor) => PrepareEvidenceExportHelper;
+export declare const registerEvidenceExportHelperCommand: (program: Command, streams: CliStreams, setExitCode: (value: 1 | 2) => void, preparer?: PrepareEvidenceExportHelper) => void;

package/dist/cli/evidenceExportHelperCommand.js

@@ -0,0 +1,51 @@
+import { createPreparedEvidenceHelperExecutor, prepareEvidenceExportHelper, } from "../evidenceExportHelper/index.js";
+import { resolveSpawnfileHome } from "../auth/index.js";
+import path from "node:path";
+import { STANDARD_WORLD_BASE_IMAGE } from "./targetConfigResolver.js";
+const timeout = (raw) => {
+    if (!/^[1-9][0-9]{0,5}$/u.test(raw))
+        throw new TypeError();
+    const value = Number(raw);
+    if (value > 120_000)
+        throw new TypeError();
+    return value;
+};
+export const createDefaultEvidenceExportHelperPreparer = (executorFor = createPreparedEvidenceHelperExecutor) => async (input) => prepareEvidenceExportHelper({
+    baseImage: input.baseImage,
+    context: input.context,
+    executor: executorFor(input.dockerCommand),
+    privateRoot: path.join(resolveSpawnfileHome(), "target", "evidence-helper"),
+    timeoutMs: input.timeoutMs,
+});
+const defaultPreparer = createDefaultEvidenceExportHelperPreparer();
+export const registerEvidenceExportHelperCommand = (program, streams, setExitCode, preparer = defaultPreparer) => {
+    const helper = program.command("helper")
+        .description("Prepare package-owned local development helpers");
+    helper.command("prepare-evidence-export")
+        .description("Prepare Spawnfile-owned local evidence export helper")
+        .requiredOption("--context <name>", "Explicit local Docker context")
+        .option("--base-image <reference>", "Already-present Node base image", STANDARD_WORLD_BASE_IMAGE)
+        .option("--docker-command <command>", "Docker-compatible command", "docker")
+        .option("--timeout-ms <milliseconds>", "Bounded command timeout", "120000")
+        .requiredOption("--json", "Emit the versioned opaque receipt JSON")
+        .action(async (options) => {
+        let timeoutMs;
+        try {
+            timeoutMs = timeout(options.timeoutMs);
+        }
+        catch {
+            streams.stderr("error: Invalid local evidence-export helper options");
+            setExitCode(2);
+            return;
+        }
+        try {
+            const receipt = await preparer({ baseImage: options.baseImage, context: options.context,
+                dockerCommand: options.dockerCommand, timeoutMs });
+            streams.stdout(JSON.stringify(receipt));
+        }
+        catch {
+            streams.stderr("error: Prepared evidence-export helper failed");
+            setExitCode(1);
+        }
+    });
+};

package/dist/cli/index.js

@@ -1,4 +1,16 @@
 #!/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";
+import { isWorkspaceResourceMigrationInvocation } from "./workspaceResourceMigrationCommand.js";
+import { isProductStateCloneInvocation } from "./productStateCloneCommand.js";
+import { isCanaryCutoverInvocation } from "./canaryCutoverCommand.js";
+const argv = process.argv.slice(2);
+const exitCode = isCanaryCutoverInvocation(argv)
+    ? await (await import("./canaryCutoverCommand.js")).runCanaryCutoverCommand(argv)
+    : isProductStateCloneInvocation(argv)
+        ? await (await import("./productStateCloneCommand.js")).runProductStateCloneCommand(argv)
+        : isWorkspaceResourceMigrationInvocation(argv)
+            ? await (await import("./workspaceResourceMigrationCommand.js")).runWorkspaceResourceMigrationCommand(argv)
+            : 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;