spawnfile 0.1.14 → 0.1.18

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

@@ -1,4 +1,5 @@
 import { InvalidArgumentError } from "commander";
+import { envFileAliasOption, resolveEnvFileOption, runtimeEnvFileOption } from "./envFileOption.js";
 const parsePositiveIntegerOption = (value) => {
     if (!/^[1-9]\d*$/u.test(value)) {
         throw new InvalidArgumentError("must be a positive integer");
@@ -11,22 +12,25 @@ 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")
         .option("--docker-command <command>", "Docker command")
-        .option("--env-file <file>", "Path to an env file for runtime secrets")
+        .addOption(runtimeEnvFileOption("Path to an env file for runtime secrets"))
+        .addOption(envFileAliasOption())
         .option("--name <container>", "Docker container name")
         .option("-o, --out <directory>", "Dev output directory")
         .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,
             dockerCommand: options.dockerCommand,
             dockerContext: options.context,
-            envFilePath: options.envFile,
+            envFilePath: resolveEnvFileOption(options),
             imageTag: options.tag,
             outputDirectory: options.out
         });

package/dist/cli/downCommand.d.ts

@@ -4,6 +4,7 @@ import type { CliHandlers, CliStreams } from "./runCli.js";
 export interface DownOptions {
     compiled?: string;
     deployment: string;
+    discardRecordedMemory?: boolean;
     dockerCommand?: string;
     exportTo?: string;
     force?: boolean;
@@ -20,6 +21,7 @@ export declare const createDownLifecyclePolicy: (options: DownOptions) => {
     reader_image: string | null;
     remove_volumes: boolean;
     timeout_ms: number | null;
+    discard_recorded_memory?: boolean | undefined;
 };
 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

@@ -1,10 +1,11 @@
 import path from "node:path";
-import { createDeploymentLifecycleCorrelation, findLifecycleInvocation, readDeploymentRecordFromOutput, } from "../deployment/index.js";
+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) => ({
+    ...(options.discardRecordedMemory ? { discard_recorded_memory: true } : {}),
     docker_command: options.dockerCommand ?? null,
     export_to: options.exportTo ? path.resolve(options.exportTo) : null,
     force: options.force ?? false,
@@ -52,9 +53,10 @@ export const registerDownCommand = (program, handlers, streams) => {
         .option("--docker-command <command>", "Docker command")
         .option("--export-to <directory>", "Export first, then tear down")
         .option("--force", "Discard un-exported artifacts")
+        .option("--discard-recorded-memory", "Allow --volumes to discard memory ledgers used by recording agents")
         .option("--reader-image <image>", "Image used to read named volumes during auto export")
         .option("--timeout <ms>", "Bound each Docker call in milliseconds")
-        .option("--volumes", "Also remove named volumes")
+        .option("--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) => {
@@ -62,11 +64,12 @@ export const registerDownCommand = (program, handlers, streams) => {
         const compiled = resolveProjectOutputDirectory(inputPath, options.compiled, DEFAULT_OUTPUT_DIRECTORY);
         const render = async (expected) => {
             const expectedUnits = expected
-                ? (await readDeploymentRecordFromOutput(compiled, options.deployment)).units.map((unit) => unit.id).sort()
+                ? (await readCanonicalDownRecord(compiled, options.deployment)).record.units.map((unit) => unit.id).sort()
                 : undefined;
             const receipt = await handlers.downDeployment({
                 compiledOutputDirectory: compiled,
                 deploymentName: options.deployment,
+                discardRecordedMemory: options.discardRecordedMemory,
                 dockerCommand: options.dockerCommand,
                 exportTo: options.exportTo,
                 force: options.force,
@@ -75,10 +78,15 @@ export const registerDownCommand = (program, handlers, streams) => {
                 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 &&
-                        receipt.retained_volumes.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");
@@ -95,13 +103,13 @@ export const registerDownCommand = (program, handlers, streams) => {
                 correlation = correlationFrom(stored);
             }
             else {
-                const record = await readDeploymentRecordFromOutput(compiled, options.deployment);
+                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 readDeploymentRecordFromOutput(compiled, options.deployment));
+                    const current = createDeploymentLifecycleCorrelation((await readCanonicalDownRecord(compiled, options.deployment)).record);
                     return canonicalLifecycleJson(current) ===
                         canonicalLifecycleJson(correlation)
                         ? { status: "resume_safe" }
@@ -128,7 +136,13 @@ export const registerDownCommand = (program, handlers, streams) => {
         const receipt = JSON.parse(output);
         streams.stdout(`deployment: ${receipt.deployment}`);
         receipt.units_stopped.forEach((unit) => streams.stdout(`stopped: ${unit}`));
-        receipt.retained_volumes.forEach((volume) => streams.stdout(`retained volume: ${volume}`));
+        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/envFileOption.d.ts

@@ -0,0 +1,18 @@
+import { Option } from "commander";
+/**
+ * Node reads `--env-file` from the WHOLE argv, script arguments included
+ * (verified on 22.23 and 24.21): `node dist/cli/index.js up --env-file x`
+ * dies with `node: x: not found` (exit 9) before Spawnfile runs when x is
+ * missing or unreadable, and a `NODE_OPTIONS=` line in x is applied to the
+ * Spawnfile process itself. `--runtime-env-file` is the spelling Node does not
+ * claim; `--env-file` stays as a hidden alias for existing callers.
+ */
+export declare const RUNTIME_ENV_FILE_FLAG = "--runtime-env-file";
+export interface EnvFileOptions {
+    envFile?: string;
+    runtimeEnvFile?: string;
+}
+export declare const runtimeEnvFileOption: (description: string, valueName?: string) => Option;
+export declare const envFileAliasOption: (valueName?: string) => Option;
+/** One env file: either spelling, never two different files. */
+export declare const resolveEnvFileOption: (options: EnvFileOptions) => string | undefined;

package/dist/cli/envFileOption.js

@@ -0,0 +1,20 @@
+import { Option } from "commander";
+import { SpawnfileError } from "../shared/index.js";
+/**
+ * Node reads `--env-file` from the WHOLE argv, script arguments included
+ * (verified on 22.23 and 24.21): `node dist/cli/index.js up --env-file x`
+ * dies with `node: x: not found` (exit 9) before Spawnfile runs when x is
+ * missing or unreadable, and a `NODE_OPTIONS=` line in x is applied to the
+ * Spawnfile process itself. `--runtime-env-file` is the spelling Node does not
+ * claim; `--env-file` stays as a hidden alias for existing callers.
+ */
+export const RUNTIME_ENV_FILE_FLAG = "--runtime-env-file";
+export const runtimeEnvFileOption = (description, valueName = "file") => new Option(`${RUNTIME_ENV_FILE_FLAG} <${valueName}>`, description);
+export const envFileAliasOption = (valueName = "file") => new Option(`--env-file <${valueName}>`, `Alias of ${RUNTIME_ENV_FILE_FLAG}`).hideHelp();
+/** One env file: either spelling, never two different files. */
+export const resolveEnvFileOption = (options) => {
+    if (options.runtimeEnvFile !== undefined && options.envFile !== undefined && options.runtimeEnvFile !== options.envFile) {
+        throw new SpawnfileError("validation_error", `${RUNTIME_ENV_FILE_FLAG} and --env-file name different files; pass one`);
+    }
+    return options.runtimeEnvFile ?? options.envFile;
+};

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,7 +1,16 @@
 #!/usr/bin/env node
 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 = isTargetLookupInvocation(argv)
-    ? await (await import("./targetLookupCli.js")).runTargetLookupCli(argv)
-    : await (await import("./runCli.js")).runCli(argv);
+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, stdin: AsyncIterable<unknown>) => void;
+export declare const registerLifecycleCommands: (program: Command, handlers: CliHandlers, streams: CliStreams, stdin: AsyncIterable<unknown>, setExitCode?: (code: number) => void) => void;

package/dist/cli/lifecycleCommands.js

@@ -1,12 +1,14 @@
 import { registerCompileBuildCommands } from "./compileBuildCommands.js";
 import { registerDownCommand } from "./downCommand.js";
 import { registerLifecyclePlanningCommands } from "./lifecyclePlanningCommands.js";
+import { registerReleaseCommand } from "./releaseCommand.js";
 import { registerRunPublishCommands } from "./runPublishCommands.js";
 import { registerUpCommand } from "./upCommand.js";
-export const registerLifecycleCommands = (program, handlers, streams, stdin) => {
+export const registerLifecycleCommands = (program, handlers, streams, stdin, setExitCode = () => undefined) => {
     registerLifecyclePlanningCommands(program, streams, stdin);
     registerCompileBuildCommands(program, handlers, streams);
     registerRunPublishCommands(program, handlers, streams);
     registerUpCommand(program, handlers, streams);
     registerDownCommand(program, handlers, streams);
+    registerReleaseCommand(program, streams, setExitCode);
 };

package/dist/cli/lifecycleMachine.d.ts

@@ -1,12 +1,15 @@
 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;
@@ -15,5 +18,8 @@ export type LifecycleReconciliation = {
 export declare const runMachineLifecycle: (invocation: LifecycleInvocation, owner: (capability: {
     epoch: string;
     role: "initial" | "recovery";
-}) => Promise<string>, reconcile?: () => Promise<LifecycleReconciliation>) => Promise<string>;
+}, 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

@@ -51,13 +51,13 @@ export const runMachineLifecycle = async (invocation, owner, reconcile) => {
             throw new SpawnfileError("runtime_error", "Lifecycle replay completion disappeared");
         }
         if (recovery.status === "owner") {
-            const verdict = await withLifecycleHeartbeat(invocation, recovery.capability, reconcile);
+            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)), recovery.capability)).outcome_bytes;
+                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}`);

package/dist/cli/lifecyclePlan.d.ts

@@ -17,6 +17,7 @@ export declare const lifecyclePlanRequestSchema: z.ZodDiscriminatedUnion<[z.ZodO
     version: z.ZodLiteral<"spawnfile.lifecycle-plan-request.v1">;
 }, z.core.$strict>, z.ZodObject<{
     deployment: z.ZodString;
+    discard_recorded_memory: z.ZodOptional<z.ZodBoolean>;
     export_to: z.ZodNullable<z.ZodString>;
     force: z.ZodBoolean;
     operation: z.ZodLiteral<"down">;

package/dist/cli/lifecyclePlan.js

@@ -35,6 +35,7 @@ export const lifecyclePlanRequestSchema = z.discriminatedUnion("operation", [
         .object({
         ...common,
         deployment: z.string().min(1).max(128),
+        discard_recorded_memory: z.boolean().optional(),
         export_to: z.string().min(1).max(4096).nullable(),
         force: z.boolean(),
         operation: z.literal("down"),
@@ -225,6 +226,7 @@ export const createPlannedLifecycleInvocation = async (request) => {
     const options = {
         compiled: request.compiled ?? undefined,
         deployment: request.deployment,
+        discardRecordedMemory: request.discard_recorded_memory,
         dockerCommand: request.docker_command ?? undefined,
         exportTo: request.export_to ?? undefined,
         force: request.force,

package/dist/cli/paideiaDelegation.d.ts

@@ -0,0 +1,18 @@
+import { type TrainingContext, type TrainingExecution } from "../compiler/training/index.js";
+import type { CliStreams } from "./runCli.js";
+export interface DelegatePaideiaTrainingOptions {
+    context: TrainingContext;
+    execution?: TrainingExecution;
+    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>;