spawnfile 0.1.14 → 0.1.18

package/dist/auth/trainingGrokWriteback.js

@@ -0,0 +1,119 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, realpath, rename, unlink } from "node:fs/promises";
+import path from "node:path";
+import { acquireTrainingGrokWritebackLock } from "./trainingGrokWritebackLock.js";
+const failure = () => Error("Training Grok credential writeback failed");
+const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+/** Reads only private, bounded, canonical leaves. Errors never include credential bytes. */
+export const readTrainingGrokLeaf = async (file) => {
+    if (await realpath(file) !== path.resolve(file))
+        throw failure();
+    const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const before = await handle.stat({ bigint: true });
+        if (!before.isFile() || before.nlink !== 1n || (before.mode & 511n) !== 384n || before.size < 2n || before.size > 65536n)
+            throw failure();
+        const bytes = Buffer.alloc(Number(before.size) + 1);
+        let length = 0;
+        while (length < bytes.length) {
+            const result = await handle.read(bytes, length, bytes.length - length, null);
+            if (!result.bytesRead)
+                break;
+            length += result.bytesRead;
+        }
+        const after = await handle.stat({ bigint: true });
+        if (BigInt(length) !== before.size || after.mtimeNs !== before.mtimeNs || after.ctimeNs !== before.ctimeNs) {
+            bytes.fill(0);
+            throw failure();
+        }
+        return bytes.subarray(0, length);
+    }
+    finally {
+        await handle.close();
+    }
+};
+const expiry = (bytes) => {
+    try {
+        const rows = Object.entries(JSON.parse(bytes.toString("utf8")))
+            .filter(([key]) => /^https:\/\/auth\.x\.ai::/u.test(key)).map(([, value]) => value);
+        const row = rows[0];
+        if (rows.length !== 1 || typeof row?.key !== "string" || !row.key.trim() || typeof row.refresh_token !== "string" || !row.refresh_token.trim() || typeof row.expires_at !== "string")
+            throw failure();
+        const value = Date.parse(row.expires_at);
+        if (!Number.isFinite(value))
+            throw failure();
+        return value;
+    }
+    catch {
+        throw failure();
+    }
+};
+/** A settled journal proves rotation; native expiry orders credentials across independent realms. */
+export const writeBackTrainingGrokCredential = async (profile, candidate, journalFile) => {
+    const release = await acquireTrainingGrokWritebackLock(profile, 30_000).catch(() => { throw failure(); });
+    const temporary = path.join(path.dirname(profile), `.grok-writeback-${randomUUID()}`);
+    let current, renewed, journalBytes;
+    try {
+        current = await readTrainingGrokLeaf(profile);
+        renewed = await readTrainingGrokLeaf(candidate);
+        if (digest(current) === digest(renewed))
+            return false;
+        journalBytes = await readTrainingGrokLeaf(journalFile);
+        const journal = JSON.parse(journalBytes.toString("utf8"));
+        if (journal.version !== "noopolis.daimon.broker-credential-journal.v1" || journal.state !== "promoted" ||
+            !Number.isSafeInteger(journal.generation) || journal.generation < 1 ||
+            typeof journal.sourceDigest !== "string" || !/^[a-f0-9]{64}$/u.test(journal.sourceDigest) || journal.promotedDigest !== digest(renewed))
+            throw failure();
+        const renewedExpiry = expiry(renewed), currentExpiry = expiry(current);
+        const ancestors = journal.ancestorDigests ?? [];
+        if (!Array.isArray(ancestors) || ancestors.length > 900 || ancestors.some((entry) => typeof entry !== "string" || !/^[a-f0-9]{64}$/u.test(entry)))
+            throw failure();
+        if (renewedExpiry < currentExpiry || (renewedExpiry === currentExpiry && journal.sourceDigest !== digest(current) && !ancestors.includes(digest(current))))
+            return false;
+        const identity = await lstat(profile, { bigint: true });
+        const output = await open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+        try {
+            await output.writeFile(renewed);
+            await output.sync();
+        }
+        finally {
+            await output.close();
+        }
+        // Import and writeback hold the same lock through publication. This check
+        // also detects non-cooperating edits made before validation, not after it.
+        const check = await readTrainingGrokLeaf(profile);
+        try {
+            const now = await lstat(profile, { bigint: true });
+            if (digest(check) !== digest(current) || now.ino !== identity.ino || now.dev !== identity.dev || now.ctimeNs !== identity.ctimeNs)
+                throw failure();
+        }
+        finally {
+            check.fill(0);
+        }
+        await rename(temporary, profile);
+        const directory = await open(path.dirname(profile), constants.O_RDONLY);
+        try {
+            await directory.sync();
+        }
+        finally {
+            await directory.close();
+        }
+        return true;
+    }
+    catch {
+        throw failure();
+    }
+    finally {
+        current?.fill(0);
+        renewed?.fill(0);
+        journalBytes?.fill(0);
+        try {
+            await unlink(temporary).catch((error) => { if (error.code !== "ENOENT")
+                throw error; });
+        }
+        finally {
+            release();
+        }
+    }
+};

package/dist/auth/trainingGrokWritebackLock.d.ts

@@ -0,0 +1,5 @@
+/** A persistent, non-secret SQLite file owns the OS lock, never the directory.
+ * SQLite releases it on process death. Do not unlink the file/directory: another
+ * writer may already have the same inode open. Legacy empty lock dirs are safe.
+ */
+export declare const acquireTrainingGrokWritebackLock: (profile: string, timeoutMs?: number) => Promise<() => void>;

package/dist/auth/trainingGrokWritebackLock.js

@@ -0,0 +1,56 @@
+import { closeSync, constants, openSync } from "node:fs";
+import { lstat, mkdir, realpath } from "node:fs/promises";
+import path from "node:path";
+import { setTimeout } from "node:timers/promises";
+/** A persistent, non-secret SQLite file owns the OS lock, never the directory.
+ * SQLite releases it on process death. Do not unlink the file/directory: another
+ * writer may already have the same inode open. Legacy empty lock dirs are safe.
+ */
+export const acquireTrainingGrokWritebackLock = async (profile, timeoutMs = 0) => {
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0)
+        throw Error("Invalid writeback lock timeout");
+    const root = `${profile}.training-writeback.lock`;
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    const directory = await lstat(root);
+    if (await realpath(root) !== path.resolve(root) || !directory.isDirectory() ||
+        directory.uid !== process.getuid?.() || (directory.mode & 0o777) !== 0o700)
+        throw Error("Unsafe writeback lock");
+    const file = path.join(root, "lock.sqlite");
+    // Closing an independently opened fd can drop this process's POSIX locks.
+    // Only open when creating; SQLite owns every fd for an existing lock file.
+    // Creation and close must not yield to another acquisition in this process.
+    try {
+        closeSync(openSync(file, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600));
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    const entry = await lstat(file);
+    if (!entry.isFile() || entry.nlink !== 1 || entry.uid !== process.getuid?.() || (entry.mode & 0o777) !== 0o600)
+        throw Error("Unsafe writeback lock");
+    const { DatabaseSync } = await import("node:sqlite");
+    const database = new DatabaseSync(file);
+    const deadline = performance.now() + timeoutMs;
+    try {
+        // SQLite's synchronous busy timeout would block a same-process holder
+        // from finishing its async publication. Yield between acquisition attempts.
+        database.exec("PRAGMA busy_timeout = 0");
+        for (;;) {
+            try {
+                database.exec("BEGIN EXCLUSIVE");
+                return () => { database.close(); };
+            }
+            catch (error) {
+                const remaining = deadline - performance.now();
+                if (error.errcode !== 5 || remaining <= 0)
+                    throw error;
+                await setTimeout(Math.min(25, remaining));
+            }
+        }
+    }
+    catch (error) {
+        database.close();
+        throw error;
+    }
+};

package/dist/auth/types.d.ts

@@ -1,4 +1,4 @@
-export type ImportedAuthKind = "claude-code" | "codex";
+export type ImportedAuthKind = "claude-code" | "codex" | "grok";
 export interface ImportedAuthEntry {
     kind: ImportedAuthKind;
     relativePath: string;

package/dist/cli/authCommands.d.ts

@@ -1,5 +1,5 @@
 import type { Command } from "commander";
 import type { CliHandlers, CliStreams } from "./runCli.js";
-type AuthCommandHandlers = Pick<CliHandlers, "importClaudeCodeAuth" | "importCodexAuth" | "importEnvFile" | "initializeTargetSecretSourceLifecycle" | "provisionCredentials" | "requireAuthProfile" | "syncProjectAuth">;
+type AuthCommandHandlers = Pick<CliHandlers, "importClaudeCodeAuth" | "importCodexAuth" | "importGrokAuth" | "importEnvFile" | "initializeTargetSecretSourceLifecycle" | "provisionCredentials" | "requireAuthProfile" | "syncProjectAuth">;
 export declare const registerAuthCommands: (program: Command, handlers: AuthCommandHandlers, streams: CliStreams, stdin: AsyncIterable<unknown>) => void;
 export {};

package/dist/cli/authCommands.js

@@ -5,6 +5,7 @@ import { createCanonicalTargetSecretSourceJson } from "../auth/targetSecretSourc
 import { renderSimfileWorldBindings } from "../compiler/worldBindings.js";
 import { MAX_TARGET_SECRET_SOURCE_SECRET_BYTES, TARGET_SECRET_SOURCE_ERROR } from "../auth/targetSecretSourceRecordCommon.js";
 import { createTargetSecretSourceReceiptBytes, readBoundedTargetSecretStdin, readTargetSecretSourceGrantRequestFile, readTargetSecretSourceRequestFile } from "./targetSecretSourceInput.js";
+import { envFileAliasOption, resolveEnvFileOption, runtimeEnvFileOption } from "./envFileOption.js";
 const formatAuthProfileSummary = (profile) => {
     const envKeys = Object.keys(profile.env).sort();
     const importedKinds = Object.keys(profile.imports).sort();
@@ -89,6 +90,15 @@ export const registerAuthCommands = (program, handlers, streams, stdin) => {
         const profile = await handlers.importClaudeCodeAuth(options.profile, options.from);
         emitLines(streams, formatAuthProfileSummary(profile));
     });
+    authImportCommand
+        .command("grok")
+        .description("Import a dedicated training Grok login into a profile")
+        .option("-p, --profile <name>", "Auth profile name", "default")
+        .requiredOption("--from <directory>", "Source Grok config directory holding the dedicated login")
+        .action(async (options) => {
+        const profile = await handlers.importGrokAuth(options.profile, options.from);
+        emitLines(streams, formatAuthProfileSummary(profile));
+    });
     authImportCommand
         .command("codex")
         .description("Import Codex subscription credentials into a profile")
@@ -103,14 +113,15 @@ export const registerAuthCommands = (program, handlers, streams, stdin) => {
         .description("Provision auth material a project requires into a profile")
         .argument("[path]", "Project directory or Spawnfile path", process.cwd())
         .option("-p, --profile <name>", "Auth profile name", "default")
-        .option("--env-file <file>", "Path to an env file with model keys and runtime secrets")
+        .addOption(runtimeEnvFileOption("Path to an env file with model keys and runtime secrets"))
+        .addOption(envFileAliasOption())
         .option("--claude-from <directory>", "Source Claude Code config directory")
         .option("--codex-from <directory>", "Source Codex config directory")
         .action(async (inputPath, options) => {
         const profile = await handlers.syncProjectAuth(inputPath, {
             claudeCodeDirectory: options.claudeFrom,
             codexDirectory: options.codexFrom,
-            envFilePath: options.envFile,
+            envFilePath: resolveEnvFileOption(options),
             profileName: options.profile
         });
         emitLines(streams, formatAuthProfileSummary(profile));
@@ -127,10 +138,12 @@ export const registerAuthCommands = (program, handlers, streams, stdin) => {
         .command("provision")
         .description("Provision a declarative batch of target credentials")
         .argument("<request-file>", "Secret-free credential provisioning request JSON")
-        .option("--env-file <path>", "Create a 0600 environment file")
+        .addOption(runtimeEnvFileOption("Create a 0600 environment file", "path"))
+        .addOption(envFileAliasOption("path"))
         .option("--world-bindings <path>", "Create a resolved world-bindings artifact")
         .option("--resolved-grants <path>", "Resolved world grants used to derive world bindings")
         .action((requestFile, options) => targetSecretAction(async () => {
+        const envFilePath = resolveEnvFileOption(options);
         let materials;
         try {
             const request = await readCredentialProvisioningRequestFile(requestFile);
@@ -144,11 +157,11 @@ export const registerAuthCommands = (program, handlers, streams, stdin) => {
                 await handlers.importCodexAuth(request.model_engine_auth.profile, request.model_engine_auth.from);
                 modelEngineAuth = true;
             }
-            const envFile = options.envFile === undefined
+            const envFile = envFilePath === undefined
                 ? undefined
                 : await writeProvisionedEnvFile({
                     materials,
-                    path: options.envFile,
+                    path: envFilePath,
                     receipt: provisioned.receipt
                 });
             let worldBindingsDigest;

package/dist/cli/canaryCutoverCommand.d.ts

@@ -0,0 +1,2 @@
+export declare const isCanaryCutoverInvocation: (argv: readonly string[]) => boolean;
+export declare const runCanaryCutoverCommand: (argv: readonly string[]) => Promise<number>;

package/dist/cli/canaryCutoverCommand.js

@@ -0,0 +1,30 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { z } from "zod";
+import { issueDeploymentIdentity, runCanaryCutover, verifyEquivalentRollbackReadiness } from "../deployment/canaryCutover.js";
+const boundedArgs = z.array(z.string().max(4096)).max(32);
+const request = z.object({ version: z.literal("spawnfile.canary-cutover-request.v1"), live_report_path: z.string().min(1), candidate_report_path: z.string().min(1), readiness_path: z.string().min(1), expected_identity: z.unknown(), docker_command: z.string().min(1), nonce: z.string().regex(/^[a-f0-9]{32}$/u), transaction_path: z.string().min(1), ingress_command: z.string().min(1), ingress_args: boundedArgs, ingress_receipt_path: z.string().min(1), teardown_command: z.string().min(1), teardown_args: boundedArgs, teardown_policy: z.enum(["export", "force"]), teardown_project_path: z.string().min(1), teardown_compiled_path: z.string().min(1), decision_receipt_path: z.string().min(1), from_deployment: z.string().min(1), to_deployment: z.string().min(1) }).strict();
+const rollback = z.object({ version: z.literal("spawnfile.canary-rollback-readiness-request.v1"), rollback_readiness_path: z.string().min(1), expected_identity: z.unknown() }).strict();
+const identity = z.object({ version: z.literal("spawnfile.deployment-identity-request.v1"), readiness_path: z.string().min(1), deployment_mode: z.enum(["project", "image"]), docker_command: z.string().min(1), receipt_path: z.string().min(1) }).strict();
+export const isCanaryCutoverInvocation = (argv) => argv[0] === "canary" && ["identity", "cutover", "verify-rollback"].includes(argv[1] ?? "");
+export const runCanaryCutoverCommand = async (argv) => {
+    try {
+        const bytes = await readFile(argv[2] ?? "", "utf8");
+        if (argv[1] === "identity") {
+            const value = identity.parse(JSON.parse(bytes)), receipt = await issueDeploymentIdentity(value.readiness_path, value.deployment_mode, value.docker_command);
+            await writeFile(value.receipt_path, `${JSON.stringify(receipt)}\n`, { flag: "wx", mode: 0o600 });
+        }
+        else if (argv[1] === "verify-rollback") {
+            const value = rollback.parse(JSON.parse(bytes));
+            await verifyEquivalentRollbackReadiness(value.rollback_readiness_path, value.expected_identity);
+        }
+        else {
+            const value = request.parse(JSON.parse(bytes));
+            await runCanaryCutover({ liveReportPath: value.live_report_path, candidateReportPath: value.candidate_report_path, readinessPath: value.readiness_path, expectedIdentity: value.expected_identity, dockerCommand: value.docker_command, nonce: value.nonce, transactionPath: value.transaction_path, ingressCommand: value.ingress_command, ingressArgs: value.ingress_args, ingressReceiptPath: value.ingress_receipt_path, teardownCommand: value.teardown_command, teardownArgs: value.teardown_args, teardownPolicy: value.teardown_policy, teardownProjectPath: value.teardown_project_path, teardownCompiledPath: value.teardown_compiled_path, decisionReceiptPath: value.decision_receipt_path, fromDeployment: value.from_deployment, toDeployment: value.to_deployment });
+        }
+        return 0;
+    }
+    catch {
+        process.stderr.write("error: Canary operation failed\n");
+        return 1;
+    }
+};

package/dist/cli/capabilitiesCommand.d.ts

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

package/dist/cli/capabilitiesCommand.js

@@ -0,0 +1,12 @@
+import { SpawnfileError } from "../shared/index.js";
+import { createCapabilitiesReceipt, createCapabilitiesReceiptBytes, } from "./capabilitiesReceipt.js";
+export const registerCapabilitiesCommand = (program, streams, packageVersion) => {
+    program.command("capabilities")
+        .description("Report supported public CLI contracts")
+        .requiredOption("--json", "Emit one strict versioned JSON receipt")
+        .action((options) => {
+        if (options.json !== true)
+            throw new SpawnfileError("validation_error", "`capabilities` requires --json");
+        streams.stdout(createCapabilitiesReceiptBytes(createCapabilitiesReceipt(packageVersion)));
+    });
+};

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")
@@ -5,13 +16,16 @@ export const registerCompileBuildCommands = (program, handlers, streams) => {
         .argument("[path]", "Project directory or Spawnfile path", process.cwd())
         .option("-o, --out <directory>", "Output directory")
         .option("--world-bindings <file>", "Path to a versioned world-bindings artifact")
+        .option("--release", "Build workspace bundles only from clean committed inputs")
         .action(async (inputPath, options) => {
         const result = await handlers.compileProject(inputPath, {
+            ...(options.release ? { bundleIdentity: "release" } : {}),
             outputDirectory: options.out,
             worldBindingsPath: options.worldBindings
         });
         streams.stdout(`compiled to ${result.outputDirectory}`);
         streams.stdout(`report: ${result.reportPath}`);
+        reportDurableMounts(result.report, streams);
     });
     program
         .command("build")
@@ -21,8 +35,10 @@ export const registerCompileBuildCommands = (program, handlers, streams) => {
         .option("--docker-command <command>", "Docker command")
         .option("-o, --out <directory>", "Output directory")
         .option("-t, --tag <image>", "Docker image tag")
+        .option("--release", "Build workspace bundles only from clean committed inputs")
         .action(async (inputPath, options) => {
         const result = await handlers.buildProject(inputPath, {
+            ...(options.release ? { bundleIdentity: "release" } : {}),
             dockerContext: options.context,
             dockerCommand: options.dockerCommand,
             imageTag: options.tag,
@@ -31,5 +47,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[];