spawnfile 0.1.14 → 0.1.17

package/dist/cli/capabilitiesReceipt.d.ts

@@ -0,0 +1,56 @@
+import { CREDENTIAL_PROVISIONING_REQUEST_VERSION } from "../auth/index.js";
+import { PREPARED_EVIDENCE_HELPER_RECEIPT_VERSION } from "../evidenceExportHelper/index.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 { COMPOSED_LIFECYCLE_CONTRACT_SET_VERSION, type ComposedLifecycleCommandContract } from "./composedLifecycleContractSet.js";
+import { TARGET_DEFAULT_CONFIG_STDIN_VERSION } from "./targetDefaultConfigStdin.js";
+import { TARGET_CONFIG_DIGEST_VERSION, TARGET_CONFIG_PREPARED_PLAN_ABI_VERSION, TARGET_CONFIG_RESOLUTION_VERSION } from "./targetConfigResolver.js";
+import { TARGET_CONFIG_RESOLVER_COMMAND } from "./targetConfigResolverCommand.js";
+export { COMPOSED_LIFECYCLE_CONTRACT_SET_VERSION } from "./composedLifecycleContractSet.js";
+export declare const CAPABILITIES_RECEIPT_VERSION: "spawnfile.capabilities.v1";
+export interface CapabilitiesReceipt {
+    readonly capabilities: {
+        readonly evidence_export_helper: {
+            readonly identity: "docker-image-config-digest";
+            readonly local_context_only: true;
+            readonly prepare_command: readonly [
+                "helper",
+                "prepare-evidence-export",
+                "--context",
+                "<name>",
+                "--json"
+            ];
+            readonly receipt_version: typeof PREPARED_EVIDENCE_HELPER_RECEIPT_VERSION;
+            readonly resolver_option: "--prepare-evidence-helper";
+            readonly provisioning: "spawnfile-owned-target-local";
+        };
+        readonly composed_lifecycle: {
+            readonly command_set_version: typeof COMPOSED_LIFECYCLE_CONTRACT_SET_VERSION;
+            readonly commands: readonly ComposedLifecycleCommandContract[];
+            readonly complete: true;
+        };
+        readonly optional_model_auth: {
+            readonly request_version: typeof CREDENTIAL_PROVISIONING_REQUEST_VERSION;
+            readonly required: false;
+        };
+        readonly target_config_resolver: {
+            readonly command: readonly ["target", typeof TARGET_CONFIG_RESOLVER_COMMAND];
+            readonly output_version: typeof TARGET_CONFIG_RESOLUTION_VERSION;
+            readonly prepared_plan_version: typeof TARGET_CONFIG_PREPARED_PLAN_ABI_VERSION;
+            readonly target_config_digest_version: typeof TARGET_CONFIG_DIGEST_VERSION;
+            readonly target_config_version: typeof TARGET_DEFAULT_CONFIG_STDIN_VERSION;
+        };
+        readonly terminal_public_artifact: {
+            readonly not_present_version: typeof TARGET_PUBLIC_ARTIFACT_SNAPSHOT_NOT_PRESENT_VERSION;
+            readonly request_version: typeof TARGET_PUBLIC_ARTIFACT_SNAPSHOT_REQUEST_VERSION;
+            readonly snapshot_version: typeof TARGET_PUBLIC_ARTIFACT_SNAPSHOT_VERSION;
+        };
+    };
+    readonly implementation: {
+        readonly cli: "spawnfile";
+        readonly package: "spawnfile";
+        readonly version: string;
+    };
+    readonly version: typeof CAPABILITIES_RECEIPT_VERSION;
+}
+export declare const createCapabilitiesReceipt: (packageVersion: string) => CapabilitiesReceipt;
+export declare const createCapabilitiesReceiptBytes: (receipt: CapabilitiesReceipt) => string;

package/dist/cli/capabilitiesReceipt.js

@@ -0,0 +1,56 @@
+import { CREDENTIAL_PROVISIONING_REQUEST_VERSION } from "../auth/index.js";
+import { PREPARED_EVIDENCE_HELPER_RECEIPT_VERSION } from "../evidenceExportHelper/index.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 { COMPOSED_LIFECYCLE_COMMANDS, COMPOSED_LIFECYCLE_CONTRACT_SET_VERSION, } from "./composedLifecycleContractSet.js";
+import { TARGET_DEFAULT_CONFIG_STDIN_VERSION, } from "./targetDefaultConfigStdin.js";
+import { TARGET_CONFIG_DIGEST_VERSION, TARGET_CONFIG_PREPARED_PLAN_ABI_VERSION, TARGET_CONFIG_RESOLUTION_VERSION, } from "./targetConfigResolver.js";
+import { TARGET_CONFIG_RESOLVER_COMMAND } from "./targetConfigResolverCommand.js";
+export { COMPOSED_LIFECYCLE_CONTRACT_SET_VERSION } from "./composedLifecycleContractSet.js";
+export const CAPABILITIES_RECEIPT_VERSION = "spawnfile.capabilities.v1";
+const PACKAGE_VERSION = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u;
+export const createCapabilitiesReceipt = (packageVersion) => {
+    if (!PACKAGE_VERSION.test(packageVersion))
+        throw new TypeError("Invalid Spawnfile package version");
+    return Object.freeze({
+        capabilities: Object.freeze({
+            evidence_export_helper: Object.freeze({
+                identity: "docker-image-config-digest",
+                local_context_only: true,
+                prepare_command: Object.freeze([
+                    "helper", "prepare-evidence-export", "--context", "<name>", "--json",
+                ]),
+                receipt_version: PREPARED_EVIDENCE_HELPER_RECEIPT_VERSION,
+                resolver_option: "--prepare-evidence-helper",
+                provisioning: "spawnfile-owned-target-local",
+            }),
+            composed_lifecycle: Object.freeze({
+                command_set_version: COMPOSED_LIFECYCLE_CONTRACT_SET_VERSION,
+                commands: COMPOSED_LIFECYCLE_COMMANDS,
+                complete: true,
+            }),
+            optional_model_auth: Object.freeze({
+                request_version: CREDENTIAL_PROVISIONING_REQUEST_VERSION,
+                required: false,
+            }),
+            target_config_resolver: Object.freeze({
+                command: Object.freeze(["target", TARGET_CONFIG_RESOLVER_COMMAND]),
+                output_version: TARGET_CONFIG_RESOLUTION_VERSION,
+                prepared_plan_version: TARGET_CONFIG_PREPARED_PLAN_ABI_VERSION,
+                target_config_digest_version: TARGET_CONFIG_DIGEST_VERSION,
+                target_config_version: TARGET_DEFAULT_CONFIG_STDIN_VERSION,
+            }),
+            terminal_public_artifact: Object.freeze({
+                not_present_version: TARGET_PUBLIC_ARTIFACT_SNAPSHOT_NOT_PRESENT_VERSION,
+                request_version: TARGET_PUBLIC_ARTIFACT_SNAPSHOT_REQUEST_VERSION,
+                snapshot_version: TARGET_PUBLIC_ARTIFACT_SNAPSHOT_VERSION,
+            }),
+        }),
+        implementation: Object.freeze({
+            cli: "spawnfile",
+            package: "spawnfile",
+            version: packageVersion,
+        }),
+        version: CAPABILITIES_RECEIPT_VERSION,
+    });
+};
+export const createCapabilitiesReceiptBytes = (receipt) => JSON.stringify(receipt);

package/dist/cli/compileBuildCommands.js

@@ -1,3 +1,14 @@
+import { describeBackedMountRequirement } from "../compiler/containerBackedMountRender.js";
+/**
+ * Durable mounts are only attached by `spawnfile run`/`up`/`deploy`. A
+ * hand-rolled `docker run` of the built image gets none of them and the
+ * entrypoint now refuses to start, so say up front how many the launcher owes.
+ */
+const reportDurableMounts = (report, streams) => {
+    const line = describeBackedMountRequirement(report.container?.persistent_mounts ?? []);
+    if (line)
+        streams.stdout(line);
+};
 export const registerCompileBuildCommands = (program, handlers, streams) => {
     program
         .command("compile")
@@ -12,6 +23,7 @@ export const registerCompileBuildCommands = (program, handlers, streams) => {
         });
         streams.stdout(`compiled to ${result.outputDirectory}`);
         streams.stdout(`report: ${result.reportPath}`);
+        reportDurableMounts(result.report, streams);
     });
     program
         .command("build")
@@ -31,5 +43,6 @@ export const registerCompileBuildCommands = (program, handlers, streams) => {
         streams.stdout(`built image ${result.imageTag}`);
         streams.stdout(`compiled to ${result.outputDirectory}`);
         streams.stdout(`report: ${result.reportPath}`);
+        reportDurableMounts(result.report, streams);
     });
 };

package/dist/cli/composedLifecycleContractSet.d.ts

@@ -0,0 +1,21 @@
+export declare const COMPOSED_LIFECYCLE_CONTRACT_SET_VERSION: "spawnfile.composed-lifecycle-contract-set.v1";
+export type LifecycleCommandStdout = "json" | "text";
+/**
+ * One closed machine-facing command surface. Empty version lists are
+ * intentional: they mean the command has no versioned value in that role.
+ */
+export interface ComposedLifecycleCommandContract {
+    readonly argv: readonly string[];
+    readonly invocation_versions: readonly string[];
+    readonly pending_versions: readonly string[];
+    readonly receipt_versions: readonly string[];
+    readonly request_versions: readonly string[];
+    readonly stdin_versions: readonly string[];
+    readonly stdout: LifecycleCommandStdout;
+}
+/**
+ * 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 declare const COMPOSED_LIFECYCLE_COMMANDS: readonly ComposedLifecycleCommandContract[];

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

@@ -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.js

@@ -1,5 +1,5 @@
 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";
@@ -54,7 +54,7 @@ export const registerDownCommand = (program, handlers, streams) => {
         .option("--force", "Discard un-exported artifacts")
         .option("--reader-image <image>", "Image used to read named volumes during auto export")
         .option("--timeout <ms>", "Bound each Docker call in milliseconds")
-        .option("--volumes", "Also remove named volumes")
+        .option("--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,7 +62,7 @@ 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,
@@ -75,10 +75,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 +100,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 +133,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/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/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/paideiaDelegation.d.ts

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