spawnfile 0.1.14 → 0.1.18

package/dist/cli/upCommand.js

@@ -1,12 +1,13 @@
 import { constants } from "node:fs";
 import { open } from "node:fs/promises";
-import { createDeploymentInstanceDigest, readDeploymentRecord, recordLifecycleOutcomeEvidence } from "../deployment/index.js";
+import { createDeploymentInstanceDigest, admitLifecyclePlan, LIFECYCLE_UP_EXTRA_LABELS, recordLifecycleUpReservation, recordLifecycleUpStart, readDeploymentRecord, recordLifecycleOutcomeEvidence } from "../deployment/index.js";
 import { SpawnfileError } from "../shared/index.js";
 import { requireMachineLifecycle, runMachineLifecycle } from "./lifecycleMachine.js";
 import { resolveCommandInput } from "./resolveCommandInput.js";
 import { runImageUpCommand } from "./upImageCommand.js";
 import { createUpLifecycleInvocation, createUpProjectOptions } from "./upLifecycleInvocation.js";
 import { reconcileUpLifecycle } from "./upLifecycleRecovery.js";
+import { envFileAliasOption, resolveEnvFileOption, runtimeEnvFileOption } from "./envFileOption.js";
 const readSelectedTargetReceipt = async (file) => {
     if (typeof file !== "string" || file.length < 1 || Buffer.byteLength(file, "utf8") > 4096) {
         throw new SpawnfileError("validation_error", "Invalid selected target receipt");
@@ -38,7 +39,8 @@ export const registerUpCommand = (program, handlers, streams) => {
         .option("--deployment <name>", "Detached deployment record name")
         .option("--docker-command <command>", "Docker command")
         .option("--name <container>", "Docker container name")
-        .option("--env-file <file>", "Path to an env file for runtime secrets")
+        .addOption(runtimeEnvFileOption("Path to an env file for runtime secrets"))
+        .addOption(envFileAliasOption())
         .option("--world-bindings <file>", "Path to a versioned world-bindings artifact")
         .option("--selected-target-receipt-digest <digest>", "Selected target receipt digest for an organization handoff")
         .option("--selected-target-receipt <file>", "Selected target receipt for an organization handoff")
@@ -51,6 +53,8 @@ export const registerUpCommand = (program, handlers, streams) => {
         .option("--json", "Render a spawnfile.up-receipt.v1 machine-readable receipt")
         .option("--lifecycle-invocation <id>", "Durably bind this exact JSON lifecycle invocation")
         .action(async (inputPath, options) => {
+        options.envFile = resolveEnvFileOption(options);
+        delete options.runtimeEnvFile;
         requireMachineLifecycle(options.lifecycleInvocation, options.json);
         const upInput = resolveCommandInput(inputPath, { forceImage: options.image });
         if (upInput.kind === "invalid") {
@@ -68,9 +72,11 @@ export const registerUpCommand = (program, handlers, streams) => {
             if (options.worldBindings !== undefined) {
                 throw new SpawnfileError("validation_error", "`--world-bindings` is only supported for project-mode deployments");
             }
+            if (options.lifecycleInvocation !== undefined) {
+                throw new SpawnfileError("validation_error", "Machine lifecycle image up is not supported; use the project deployment contract");
+            }
             if (options.json) {
-                throw new SpawnfileError("validation_error", "`spawnfile up --json` is not yet supported for image-mode deployments " +
-                    "(there is no source Spawnfile to derive compiled_schedule from).");
+                throw new SpawnfileError("validation_error", "Machine-readable lifecycle up is supported only for project deployments; use the project deployment contract");
             }
             await runImageUpCommand(upInput.ref, options, handlers, streams);
             return;
@@ -101,11 +107,36 @@ export const registerUpCommand = (program, handlers, streams) => {
                     forceImage: options.image,
                     lifecycleInvocation: options.lifecycleInvocation
                 });
-            const render = async (capability) => {
+            const render = async (capability, lifecycleRecovery) => {
                 const selectedTargetReceipt = options.selectedTargetReceipt === undefined
                     ? undefined
                     : await readSelectedTargetReceipt(options.selectedTargetReceipt);
-                const result = await handlers.upProject(inputPath, createUpProjectOptions({ ...options, selectedTargetReceipt }));
+                const projectOptions = createUpProjectOptions({ ...options, selectedTargetReceipt });
+                const lifecycleProjectOptions = exactInvocation && capability
+                    ? {
+                        ...projectOptions,
+                        ...(lifecycleRecovery === undefined ? {} : { lifecycleRecovery }),
+                        onDetachedReservation: async (reserved) => recordLifecycleUpReservation(exactInvocation, {
+                            container_name: reserved.containerName,
+                            docker_command: reserved.dockerCommand,
+                            docker_context: reserved.dockerContext,
+                            label_authority: {
+                                permitted_extra_labels: LIFECYCLE_UP_EXTRA_LABELS,
+                                required: reserved.deploymentLabels,
+                            },
+                        }, capability),
+                        onDetachedStarted: async (started) => recordLifecycleUpStart(exactInvocation, {
+                            container_id: started.containerId,
+                            container_name: started.containerName,
+                            image_id: started.imageId,
+                            label_authority: {
+                                permitted_extra_labels: LIFECYCLE_UP_EXTRA_LABELS,
+                                required: started.deploymentLabels,
+                            },
+                        }, capability)
+                    }
+                    : projectOptions;
+                const result = await handlers.upProject(inputPath, lifecycleProjectOptions);
                 const receipt = await handlers.buildUpReceipt(inputPath, result);
                 const bytes = JSON.stringify(receipt, null, 2);
                 if (exactInvocation && capability) {
@@ -115,9 +146,11 @@ export const registerUpCommand = (program, handlers, streams) => {
                 }
                 return bytes;
             };
+            if (exactInvocation)
+                await admitLifecyclePlan(exactInvocation);
             const output = options.lifecycleInvocation === undefined
                 ? await render()
-                : await runMachineLifecycle(exactInvocation, render, () => reconcileUpLifecycle(inputPath, options, exactInvocation));
+                : await runMachineLifecycle(exactInvocation, render, (capability) => reconcileUpLifecycle(inputPath, options, exactInvocation, capability));
             streams.stdout(output);
             return;
         }

package/dist/cli/upLifecycleRecovery.d.ts

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

package/dist/cli/upLifecycleRecovery.js

@@ -1,53 +1,197 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { lstat } from "node:fs/promises";
 import path from "node:path";
-import { findLifecycleOutcomeEvidence, createDeploymentInstanceDigest, readDeploymentRecord, resolveDeploymentRecordPath, } from "../deployment/index.js";
-import { resolveProjectOutputDirectory } from "../filesystem/index.js";
+import { promisify } from "node:util";
+import { createDeploymentInstanceDigest, findLifecycleOutcomeEvidence, findLifecycleUpReservation, findLifecycleUpStart, readDeploymentRecord, recordLifecycleUpStart, resolveDeploymentRecordPath, } from "../deployment/index.js";
+import { deploymentRecordRecovery, detachedContainerRecovery, noDockerMutationRecovery, } from "../deployment/upLifecycleRecoveryState.js";
+import { readUtf8File, resolveProjectOutputDirectory } from "../filesystem/index.js";
 import { DEFAULT_OUTPUT_DIRECTORY, REPORT_FILENAME } from "../shared/index.js";
-import { readUtf8File } from "../filesystem/index.js";
-const ambiguous = (reason) => ({
-    reason,
-    status: "ambiguous",
-});
-const exactHandoff = (record, options) => record.organization_handoff !== undefined &&
-    record.organization_handoff_handle !== undefined &&
-    record.organization_handoff.network_attachment_handle ===
-        options.networkAttachmentHandle &&
-    record.organization_handoff.selected_target_receipt_digest ===
-        options.selectedTargetReceiptDigest;
-export const reconcileUpLifecycle = async (inputPath, options, invocation) => {
-    const outputDirectory = resolveProjectOutputDirectory(inputPath, options.out, DEFAULT_OUTPUT_DIRECTORY);
-    const deployment = options.deployment;
-    if (!deployment)
-        return ambiguous("up_deployment_not_bound");
-    const recordPath = resolveDeploymentRecordPath(outputDirectory, deployment);
+const execFile = promisify(execFileCallback);
+const inspectFormat = "{{json .Id}}\n{{json .Name}}\n{{json .Image}}\n{{json .Config.Labels}}";
+const imageFormat = "{{json .Id}}\n{{json .Config.Labels}}";
+const ambiguous = (reason) => ({ reason, status: "ambiguous" });
+const canonical = (value) => value === null || typeof value !== "object"
+    ? JSON.stringify(value)
+    : Array.isArray(value) ? `[${value.map(canonical).join(",")}]`
+        : `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(",")}}`;
+const isRecord = (value) => value !== null
+    && typeof value === "object" && !Array.isArray(value)
+    && Object.values(value).every((entry) => typeof entry === "string");
+const exactHandoff = (record, options) => record.organization_handoff !== undefined
+    && record.organization_handoff_handle !== undefined
+    && record.organization_handoff.network_attachment_handle === options.networkAttachmentHandle
+    && record.organization_handoff.selected_target_receipt_digest === options.selectedTargetReceiptDigest;
+const exactNoSuchContainer = (error) => /(?:No such container|No such object)/u.test(error instanceof Error ? error.message : String(error));
+const missingDeploymentRecord = async (recordPath) => {
+    try {
+        await lstat(recordPath);
+        return false;
+    }
+    catch (error) {
+        return error.code === "ENOENT";
+    }
+};
+const dockerArgs = (reservation, args) => [
+    ...(reservation.docker_context ? ["--context", reservation.docker_context] : []), ...args,
+];
+const reservationMatchesRequest = (reservation, options) => reservation.docker_context === (options.context ?? null)
+    && reservation.docker_command === (options.dockerCommand ?? "docker");
+const inspectContainer = async (reservation, reference) => {
+    try {
+        const result = await execFile(reservation.docker_command, dockerArgs(reservation, [
+            "container", "inspect", "--format", inspectFormat, reference,
+        ]), { timeout: 10_000 });
+        const [id, name, image, labels, ...extra] = result.stdout.trim().split("\n");
+        const containerId = id ? JSON.parse(id) : undefined;
+        const containerName = name ? JSON.parse(name) : undefined;
+        const imageId = image ? JSON.parse(image) : undefined;
+        const parsedLabels = labels ? JSON.parse(labels) : undefined;
+        if (extra.length || typeof containerId !== "string" || !/^[a-f0-9]{64}$/u.test(containerId)
+            || typeof containerName !== "string" || !containerName.startsWith("/") || containerName.length < 2
+            || typeof imageId !== "string"
+            || !/^sha256:[a-f0-9]{64}$/u.test(imageId) || !isRecord(parsedLabels))
+            throw new Error("invalid inspect");
+        return { container_id: containerId, container_name: containerName.slice(1), image_id: imageId, labels: parsedLabels };
+    }
+    catch (error) {
+        if (exactNoSuchContainer(error))
+            return null;
+        throw error;
+    }
+};
+const verifyImageLabels = async (reservation, observed) => {
+    const result = await execFile(reservation.docker_command, dockerArgs(reservation, [
+        "image", "inspect", "--format", imageFormat, observed.image_id,
+    ]), { timeout: 10_000 });
+    const [id, labels, ...extra] = result.stdout.trim().split("\n");
+    const imageId = id ? JSON.parse(id) : undefined;
+    const parsedLabels = labels ? JSON.parse(labels) : {};
+    const imageLabels = parsedLabels === null ? {} : parsedLabels;
+    if (extra.length || imageId !== observed.image_id || !isRecord(imageLabels))
+        return false;
+    const required = reservation.label_authority.required;
+    const expected = { ...imageLabels, ...required };
+    return canonical(observed.labels) === canonical(expected);
+};
+const verifyObserved = async (reservation, observed, expectedId, expectedImageId) => observed !== null
+    && observed.container_name === reservation.container_name
+    && (expectedId === undefined || observed.container_id === expectedId)
+    && (expectedImageId === undefined || observed.image_id === expectedImageId)
+    && await verifyImageLabels(reservation, observed);
+const recoverRecordedDetachedContainer = async (reservation, state) => {
+    const start = state.start;
+    if (start.container_name !== reservation.container_name
+        || canonical(start.label_authority) !== canonical(reservation.label_authority)) {
+        return ambiguous("up_started_container_authority_drifted");
+    }
+    try {
+        const observed = await inspectContainer(reservation, start.container_id);
+        if (observed === null)
+            return ambiguous("up_started_container_missing");
+        if (!await verifyObserved(reservation, observed, start.container_id, start.image_id)) {
+            return ambiguous("up_started_container_drifted");
+        }
+        return {
+            recovery: detachedContainerRecovery({
+                containerId: observed.container_id,
+                containerName: observed.container_name,
+                deploymentLabels: reservation.label_authority.required,
+                imageId: observed.image_id,
+            }),
+            status: "resume_safe",
+        };
+    }
+    catch {
+        return ambiguous("up_started_container_reconciliation_failed");
+    }
+};
+const reconcileUnrecordedStart = async (invocation, options, capability) => {
+    let reservation;
+    try {
+        reservation = await findLifecycleUpReservation(invocation);
+    }
+    catch {
+        return ambiguous("up_reservation_invalid");
+    }
+    // A current implementation performs no Docker effect before publishing this
+    // fsynced reservation, so its absence is restart-safe but never called not-applied.
+    if (reservation === null)
+        return { status: "resume_safe" };
+    if (!reservationMatchesRequest(reservation, options))
+        return ambiguous("up_reservation_request_drifted");
     try {
-        const record = await readDeploymentRecord(recordPath);
-        const report = JSON.parse(await readUtf8File(path.join(outputDirectory, REPORT_FILENAME)));
-        const requestedRoot = path.resolve(inputPath);
-        if (record.name !== deployment ||
-            record.output_directory !== outputDirectory ||
-            record.source.kind !== "project" ||
-            path.resolve(record.source.root) !== requestedRoot ||
-            record.compile_fingerprint !== report.compile_fingerprint ||
-            record.auth_profile !== (options.authProfile ?? null) ||
-            (options.context !== undefined &&
-                (record.target.kind !== "context" ||
-                    record.target.name !== options.context)) ||
-            (options.name !== undefined &&
-                record.units[0]?.container_name !== options.name) ||
-            !exactHandoff(record, options))
-            return ambiguous("up_durable_evidence_drifted");
-        const evidence = await findLifecycleOutcomeEvidence(invocation);
-        if (!evidence)
-            return ambiguous("up_receipt_evidence_absent");
-        if (evidence.deployment_instance_digest !==
-            createDeploymentInstanceDigest(record))
-            return ambiguous("up_deployment_instance_changed");
+        const observed = await inspectContainer(reservation, reservation.container_name);
+        if (observed === null) {
+            return { recovery: noDockerMutationRecovery(), status: "provably_not_applied" };
+        }
+        if (!await verifyObserved(reservation, observed))
+            return ambiguous("up_reserved_container_drifted");
+        await recordLifecycleUpStart(invocation, {
+            container_id: observed.container_id,
+            container_name: observed.container_name,
+            image_id: observed.image_id,
+            label_authority: reservation.label_authority,
+        }, capability);
         return {
-            outcomeBytes: evidence.completion.outcome_bytes,
-            status: "completed",
+            recovery: detachedContainerRecovery({
+                containerId: observed.container_id,
+                containerName: observed.container_name,
+                deploymentLabels: reservation.label_authority.required,
+                imageId: observed.image_id,
+            }),
+            status: "resume_safe",
         };
     }
     catch {
-        return ambiguous("up_durable_evidence_absent_or_invalid");
+        return ambiguous("up_reserved_container_reconciliation_failed");
+    }
+};
+export const reconcileUpLifecycle = async (inputPath, options, invocation, capability) => {
+    const outputDirectory = resolveProjectOutputDirectory(inputPath, options.out, DEFAULT_OUTPUT_DIRECTORY);
+    if (!options.deployment)
+        return ambiguous("up_deployment_not_bound");
+    const recordPath = resolveDeploymentRecordPath(outputDirectory, options.deployment);
+    if (!await missingDeploymentRecord(recordPath)) {
+        let record;
+        try {
+            record = await readDeploymentRecord(recordPath);
+        }
+        catch {
+            return ambiguous("up_durable_evidence_absent_or_invalid");
+        }
+        try {
+            const report = JSON.parse(await readUtf8File(path.join(outputDirectory, REPORT_FILENAME)));
+            if (record.name !== options.deployment || record.output_directory !== outputDirectory
+                || record.source.kind !== "project" || path.resolve(record.source.root) !== path.resolve(inputPath)
+                || record.compile_fingerprint !== report.compile_fingerprint
+                || record.auth_profile !== (options.authProfile ?? null)
+                || (options.context !== undefined && (record.target.kind !== "context" || record.target.name !== options.context))
+                || (options.name !== undefined && record.units[0]?.container_name !== options.name)
+                || !exactHandoff(record, options))
+                return ambiguous("up_durable_evidence_drifted");
+            const evidence = await findLifecycleOutcomeEvidence(invocation);
+            if (!evidence)
+                return { recovery: deploymentRecordRecovery(), status: "resume_safe" };
+            return evidence.deployment_instance_digest === createDeploymentInstanceDigest(record)
+                ? { outcomeBytes: evidence.completion.outcome_bytes, status: "completed" }
+                : ambiguous("up_deployment_instance_changed");
+        }
+        catch {
+            return ambiguous("up_durable_evidence_absent_or_invalid");
+        }
+    }
+    let started;
+    try {
+        started = await findLifecycleUpStart(invocation);
+    }
+    catch {
+        return ambiguous("up_start_record_unreadable");
+    }
+    if (started) {
+        const reservation = await findLifecycleUpReservation(invocation).catch(() => null);
+        return reservation === null || !reservationMatchesRequest(reservation, options)
+            ? ambiguous("up_start_reservation_unavailable")
+            : recoverRecordedDetachedContainer(reservation, started);
     }
+    return reconcileUnrecordedStart(invocation, options, capability);
 };

package/dist/cli/usageCommand.d.ts

@@ -0,0 +1,40 @@
+import { Command } from "commander";
+import type { CliStreams } from "./runCli.js";
+import { type UsageCommandLiveHandlers } from "./usageCommandLive.js";
+/**
+ * `spawnfile usage` — what did this organization consume.
+ *
+ * A separate command from `status` on purpose. `status` answers "is it
+ * healthy"; usage answers "what did it consume". Different question, different
+ * cadence, and `status` must not read a growing ledger on every invocation.
+ *
+ * Every number this command prints is a LOWER BOUND. Neither metered engine's
+ * stream carries an incompleteness marker — grok's `streaming-messages-json`
+ * and AGY's `stream-json` both zero-fill a bucket they cannot account for — so
+ * a turn whose usage was partially zero-filled sums to a plausible total and is
+ * indistinguishable from a real one. Counts are therefore reported as `>=`, and
+ * coverage is always stated explicitly. AGY additionally reports no cost at
+ * all, so its notional column is always `—`.
+ */
+export interface UsageCommandOptions {
+    agent?: string;
+    exported?: string;
+    by?: string;
+    deployment?: string;
+    dockerCommand?: string;
+    json?: boolean;
+    out?: string;
+    since?: string;
+    timeout?: string;
+    top?: string;
+}
+export interface UsageCommandResult {
+    error?: string;
+    /** The shared CLI convention (specs/SPEC.md §9.1, `errorExitCode`): 0 on
+     * success, 2 for a usage/input error, 1 for a runtime failure that surfaced
+     * after validation. */
+    exitCode: 0 | 1 | 2;
+    output?: string;
+}
+export declare const executeUsageCommand: (inputPath: string, options: UsageCommandOptions, handlers?: UsageCommandLiveHandlers) => Promise<UsageCommandResult>;
+export declare const registerUsageCommand: (program: Command, streams: CliStreams, setExitCode: (exitCode: 0 | 1 | 2) => void, handlers?: UsageCommandLiveHandlers) => void;