spawnfile 0.1.13 → 0.1.17

package/dist/cli/targetWorldReadinessCommand.js

@@ -0,0 +1,43 @@
+import { createCanonicalTargetWorldReadinessReceiptBytes, verifyTargetWorldReadinessReceipt } from "../target/worldReadiness.js";
+import { formatCaughtTargetCliError } from "./targetReceiptOutput.js";
+import { readTargetWorldReadinessRequestFile } from "./targetRequestFile.js";
+export const registerTargetWorldReadinessCommand = (target, session, streams, setExitCode) => {
+    target.command("query_world_readiness")
+        .description("Query one exact running world's public readiness document")
+        .argument("<request-file>", "Strict world readiness request JSON file")
+        .action(async (requestFile) => {
+        let request;
+        try {
+            request = await readTargetWorldReadinessRequestFile(requestFile);
+        }
+        catch {
+            streams.stderr("error: Invalid world readiness request");
+            setExitCode(2);
+            return;
+        }
+        let activeSession;
+        try {
+            activeSession = typeof session === "function"
+                ? await session(target.opts().config)
+                : session;
+            if (typeof activeSession.queryWorldReadiness !== "function")
+                throw new TypeError();
+        }
+        catch {
+            streams.stderr("error: Invalid target configuration");
+            setExitCode(2);
+            return;
+        }
+        try {
+            const receipt = verifyTargetWorldReadinessReceipt({
+                receipt: await activeSession.queryWorldReadiness(request),
+                request
+            });
+            streams.stdout(createCanonicalTargetWorldReadinessReceiptBytes(receipt));
+        }
+        catch (error) {
+            streams.stderr(formatCaughtTargetCliError(error, "Target world readiness query crashed"));
+            setExitCode(1);
+        }
+    });
+};

package/dist/cli/trainCommand.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { CliHandlers, CliStreams } from "./runCli.js";
+export declare const registerTrainCommand: (program: Command, handlers: CliHandlers, streams: CliStreams, packageVersion: string, setExitCode: (code: number) => void, signal?: AbortSignal) => void;

package/dist/cli/trainCommand.js

@@ -0,0 +1,61 @@
+import { SpawnfileError } from "../shared/index.js";
+const forwarded = ["train", "test", "editable", "resource", "judge", "judge-citation-repairs", "validation-group", "optimizer-model",
+    "bridge-command", "out", "max-trials", "max-proposals", "seed", "timeout-ms", "view", "cost-config"];
+const repeated = new Set(["editable", "resource", "judge", "judge-citation-repairs", "validation-group"]);
+const key = (name) => name.replace(/-([a-z])/gu, (_, letter) => letter.toUpperCase());
+export const registerTrainCommand = (program, handlers, streams, packageVersion, setExitCode, signal) => {
+    const command = program.command("train")
+        .description("Train one canonical agent through Paideia's isolated native integration")
+        .argument("[path]", "Canonical project directory or Spawnfile path", process.cwd())
+        .option("--agent <id>", "Exact canonical agent node id (inferred only for a single-agent project)")
+        .option("--paideia-command <executable>", "Installed Paideia executable; no shell or automatic install", "paideia")
+        .option("--training-image <immutable-image>", "Pinned image containing the complete training environment")
+        .option("--training-config <json>", "V2 image recipe and declared inputs, or advanced v1 local bindings")
+        .option("--dry-run", "Validate and estimate without compiling, authenticating or starting models")
+        .option("--repair-measurements <parent-out>", "Fork captured work into a fresh output for authorized measurement repair")
+        .option("--repair-witness <manifest>", "Explicit verified image witness for a legacy parent")
+        .option("--resume", "Resume the exact persisted training experiment in --out");
+    for (const name of forwarded) {
+        const flag = `--${name} <value>`;
+        if (repeated.has(name))
+            command.option(flag, `Paideia ${name}; repeatable`, (value, previous) => [...previous, value], []);
+        else if (name === "train")
+            command.requiredOption(flag, `Paideia ${name}`);
+        else
+            command.option(flag, `Paideia ${name}`);
+    }
+    command.action(async (inputPath, options) => {
+        if (options.dryRun !== true && typeof options.out !== "string") {
+            throw new SpawnfileError("validation_error", "Actual training requires --out; dry-run does not write an output directory");
+        }
+        if (options.dryRun !== true && typeof options.trainingConfig !== "string") {
+            throw new SpawnfileError("validation_error", "Actual training requires --training-config; v1 additionally requires --training-image; host execution is disabled");
+        }
+        const timeout = options.timeoutMs === undefined ? 3_600_000 : Number(options.timeoutMs);
+        if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 3_600_000 ||
+            (options.timeoutMs !== undefined && !/^\d+$/u.test(String(options.timeoutMs)))) {
+            throw new SpawnfileError("validation_error", "--timeout-ms must be an integer from 1 to 3600000");
+        }
+        const context = await handlers.createTrainingContext(inputPath, {
+            agent: options.agent, packageVersion
+        });
+        const args = [];
+        for (const name of forwarded) {
+            const value = options[key(name)];
+            if (typeof value === "string")
+                args.push(`--${name}`, value);
+            else if (Array.isArray(value))
+                for (const item of value)
+                    args.push(`--${name}`, item);
+        }
+        if (options.dryRun === true)
+            args.push("--dry-run");
+        if (options.resume === true)
+            args.push("--resume");
+        setExitCode(await handlers.delegatePaideiaTraining({ context, args,
+            repairMeasurements: options.repairMeasurements, repairWitness: options.repairWitness,
+            trainingImage: options.trainingImage, trainingConfig: options.trainingConfig,
+            command: options.paideiaCommand, dryRun: options.dryRun === true,
+            timeoutMs: timeout + 5000, streams, signal }));
+    });
+};

package/dist/cli/upCommand.d.ts

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

package/dist/cli/upCommand.js

@@ -0,0 +1,162 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+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";
+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");
+    }
+    let handle;
+    try {
+        handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size < 1 || stat.size > 65_536)
+            throw new Error();
+        return JSON.parse(await handle.readFile("utf8"));
+    }
+    catch {
+        throw new SpawnfileError("validation_error", "Invalid selected target receipt");
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+};
+export const registerUpCommand = (program, handlers, streams) => {
+    program
+        .command("up")
+        .description("Deploy an organization from a project or a published image reference")
+        .argument("[path]", "Project directory, Spawnfile path, or image reference", process.cwd())
+        .option("-o, --out <directory>", "Output directory")
+        .option("-t, --tag <image>", "Docker image tag")
+        .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("--name <container>", "Docker container name")
+        .option("--env-file <file>", "Path to an env file for runtime secrets")
+        .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")
+        .option("--network-attachment-handle <handle>", "Opaque network attachment handle for an organization handoff")
+        .option("--organization-handoff-run-id <id>", "Authorized run id for an organization handoff")
+        .option("--descriptor-digest <digest>", "Production descriptor digest for an organization handoff")
+        .option("--image", "Interpret the argument as an image reference")
+        .option("--pull", "Pull the image before deploying")
+        .option("-d, --detach", "Run the container in detached mode")
+        .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) => {
+        requireMachineLifecycle(options.lifecycleInvocation, options.json);
+        const upInput = resolveCommandInput(inputPath, { forceImage: options.image });
+        if (upInput.kind === "invalid") {
+            throw new SpawnfileError("validation_error", `Cannot resolve "${inputPath}" as a project path or image reference. ` +
+                "Pass a project directory, a Spawnfile path, or an image like 'name:tag' (use --image to force image mode).");
+        }
+        if (upInput.kind === "image") {
+            if (options.selectedTargetReceiptDigest !== undefined ||
+                options.selectedTargetReceipt !== undefined ||
+                options.networkAttachmentHandle !== undefined ||
+                options.organizationHandoffRunId !== undefined ||
+                options.descriptorDigest !== undefined) {
+                throw new SpawnfileError("validation_error", "Organization handoff inputs are only supported for project-mode deployments");
+            }
+            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", "Machine-readable lifecycle up is supported only for project deployments; use the project deployment contract");
+            }
+            await runImageUpCommand(upInput.ref, options, handlers, streams);
+            return;
+        }
+        const handoffValues = [
+            options.descriptorDigest,
+            options.organizationHandoffRunId,
+            options.selectedTargetReceipt,
+            options.selectedTargetReceiptDigest,
+            options.networkAttachmentHandle,
+            options.worldBindings
+        ];
+        if (handoffValues.some((value) => value !== undefined) &&
+            handoffValues.some((value) => value === undefined)) {
+            throw new SpawnfileError("validation_error", "Organization handoff requires --organization-handoff-run-id, --descriptor-digest, --selected-target-receipt, --selected-target-receipt-digest, --network-attachment-handle, and --world-bindings");
+        }
+        if (options.lifecycleInvocation !== undefined &&
+            (!options.detach ||
+                !options.deployment ||
+                handoffValues.some((value) => value === undefined))) {
+            throw new SpawnfileError("validation_error", "Machine lifecycle up requires a detached deployment with durable organization handoff authority");
+        }
+        if (options.json) {
+            const exactInvocation = options.lifecycleInvocation === undefined
+                ? undefined
+                : createUpLifecycleInvocation(inputPath, {
+                    ...options,
+                    forceImage: options.image,
+                    lifecycleInvocation: options.lifecycleInvocation
+                });
+            const render = async (capability, lifecycleRecovery) => {
+                const selectedTargetReceipt = options.selectedTargetReceipt === undefined
+                    ? undefined
+                    : await readSelectedTargetReceipt(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) {
+                    await recordLifecycleOutcomeEvidence(exactInvocation, bytes, capability, result.deploymentRecordPath
+                        ? createDeploymentInstanceDigest(await readDeploymentRecord(result.deploymentRecordPath))
+                        : "");
+                }
+                return bytes;
+            };
+            if (exactInvocation)
+                await admitLifecyclePlan(exactInvocation);
+            const output = options.lifecycleInvocation === undefined
+                ? await render()
+                : await runMachineLifecycle(exactInvocation, render, (capability) => reconcileUpLifecycle(inputPath, options, exactInvocation, capability));
+            streams.stdout(output);
+            return;
+        }
+        const result = await handlers.upProject(inputPath, createUpProjectOptions(options));
+        streams.stdout(`built image ${result.imageTag}`);
+        streams.stdout(`compiled to ${result.outputDirectory}`);
+        streams.stdout(`report: ${result.reportPath}`);
+        if (options.detach) {
+            streams.stdout(`running container ${result.containerName ?? "unknown"}`);
+            streams.stdout(`image: ${result.imageTag}`);
+        }
+    });
+};

package/dist/cli/upImageCommand.d.ts

@@ -0,0 +1,11 @@
+import type { CliHandlers, CliStreams } from "./runCli.js";
+interface ImageUpOptions {
+    authProfile?: string;
+    context?: string;
+    deployment?: string;
+    dockerCommand?: string;
+    envFile?: string;
+    pull?: boolean;
+}
+export declare const runImageUpCommand: (ref: string, options: ImageUpOptions, handlers: CliHandlers, streams: CliStreams) => Promise<void>;
+export {};

package/dist/cli/upImageCommand.js

@@ -0,0 +1,41 @@
+import { readRunEnvFile } from "../compiler/runProjectAuth.js";
+const shortDigest = (digest) => digest ? digest.replace(/^sha256:/, "").slice(0, 12) : "unknown";
+const redeploySummary = (previous, newRef, newDigest) => {
+    if (previous.ref === newRef &&
+        newDigest !== null &&
+        previous.digest === newDigest) {
+        return `redeployed image ${newRef} (digest unchanged ${shortDigest(newDigest)})`;
+    }
+    return (`redeployed image: ${previous.ref} (${shortDigest(previous.digest)}) ` +
+        `→ ${newRef} (${shortDigest(newDigest)})`);
+};
+export const runImageUpCommand = async (ref, options, handlers, streams) => {
+    const authProfile = options.authProfile && handlers.requireAuthProfile
+        ? await handlers.requireAuthProfile(options.authProfile)
+        : null;
+    const envFileEnv = await readRunEnvFile(options.envFile);
+    const consumed = await handlers.consumeImageUp(ref, {
+        authProfile,
+        authProfileName: options.authProfile ?? null,
+        authValues: authProfile?.env ?? {},
+        deploymentName: options.deployment,
+        dockerCommand: options.dockerCommand,
+        dockerContext: options.context,
+        envFileEnv,
+        envFilePath: options.envFile ?? null,
+        pull: options.pull,
+    });
+    if (consumed.previous) {
+        const digest = consumed.record.source.kind === "image"
+            ? consumed.record.source.digest
+            : null;
+        streams.stdout(redeploySummary(consumed.previous, consumed.imageRef, digest));
+    }
+    else {
+        streams.stdout(`deployed image ${consumed.imageRef}`);
+    }
+    streams.stdout(`deployment: ${consumed.deploymentName}`);
+    streams.stdout(`running container ${consumed.containerName}`);
+    streams.stdout(`record: ${consumed.recordPath}`);
+    streams.stdout(`next: spawnfile status --deployment ${consumed.deploymentName} --live`);
+};

package/dist/cli/upLifecycleInvocation.d.ts

@@ -0,0 +1,41 @@
+import type { LifecycleInvocation } from "../deployment/index.js";
+export interface UpLifecycleOptions {
+    authProfile?: string;
+    context?: string;
+    deployment?: string;
+    descriptorDigest?: string;
+    detach?: boolean;
+    dockerCommand?: string;
+    envFile?: string;
+    forceImage?: boolean;
+    lifecycleInvocation?: string;
+    name?: string;
+    networkAttachmentHandle?: string;
+    organizationHandoffRunId?: string;
+    out?: string;
+    pull?: boolean;
+    selectedTargetReceipt?: unknown;
+    selectedTargetReceiptDigest?: string;
+    tag?: string;
+    worldBindings?: string;
+}
+export declare const createUpLifecycleInvocation: (inputPath: string, options: UpLifecycleOptions & {
+    lifecycleInvocation: string;
+}) => LifecycleInvocation;
+export declare const createUpProjectOptions: (options: UpLifecycleOptions) => {
+    worldBindingsPath?: string | undefined;
+    selectedTargetReceipt?: {} | null | undefined;
+    selectedTargetReceiptDigest?: string | undefined;
+    networkAttachmentHandle?: string | undefined;
+    authProfile: string | undefined;
+    containerName: string | undefined;
+    detach: boolean | undefined;
+    deploymentName: string | undefined;
+    dockerCommand: string | undefined;
+    dockerContext: string | undefined;
+    descriptorDigest: string | undefined;
+    envFilePath: string | undefined;
+    imageTag: string | undefined;
+    organizationHandoffRunId: string | undefined;
+    outputDirectory: string | undefined;
+};

package/dist/cli/upLifecycleInvocation.js

@@ -0,0 +1,48 @@
+import path from "node:path";
+import { createLifecycleInvocation, digestLifecycleBinding, } from "./lifecycleMachine.js";
+export const createUpLifecycleInvocation = (inputPath, options) => createLifecycleInvocation(options.lifecycleInvocation, "up", {
+    input_kind: "project",
+    project_path: path.resolve(inputPath),
+}, {
+    auth_profile_digest: digestLifecycleBinding(options.authProfile),
+    container_name: options.name ?? null,
+    deployment: options.deployment ?? null,
+    detach: options.detach ?? false,
+    docker_command_digest: digestLifecycleBinding(options.dockerCommand),
+    docker_context: options.context ?? null,
+    descriptor_digest: options.descriptorDigest ?? null,
+    env_file_digest: digestLifecycleBinding(options.envFile),
+    force_image: options.forceImage ?? false,
+    image_tag: options.tag ?? null,
+    network_attachment_handle_digest: digestLifecycleBinding(options.networkAttachmentHandle),
+    organization_handoff_run_id: options.organizationHandoffRunId ?? null,
+    output_directory: options.out ? path.resolve(options.out) : null,
+    pull: options.pull ?? false,
+    selected_target_receipt_digest: options.selectedTargetReceiptDigest ?? null,
+    world_bindings_digest: digestLifecycleBinding(options.worldBindings),
+});
+export const createUpProjectOptions = (options) => ({
+    authProfile: options.authProfile,
+    containerName: options.name,
+    detach: options.detach,
+    deploymentName: options.deployment,
+    dockerCommand: options.dockerCommand,
+    dockerContext: options.context,
+    descriptorDigest: options.descriptorDigest,
+    envFilePath: options.envFile,
+    imageTag: options.tag,
+    organizationHandoffRunId: options.organizationHandoffRunId,
+    outputDirectory: options.out,
+    ...(options.networkAttachmentHandle !== undefined
+        ? { networkAttachmentHandle: options.networkAttachmentHandle }
+        : {}),
+    ...(options.selectedTargetReceiptDigest !== undefined
+        ? { selectedTargetReceiptDigest: options.selectedTargetReceiptDigest }
+        : {}),
+    ...(options.selectedTargetReceipt !== undefined
+        ? { selectedTargetReceipt: options.selectedTargetReceipt }
+        : {}),
+    ...(options.worldBindings !== undefined
+        ? { worldBindingsPath: options.worldBindings }
+        : {}),
+});

package/dist/cli/upLifecycleRecovery.d.ts

@@ -0,0 +1,4 @@
+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], capability: LifecycleOwnerCapability) => Promise<LifecycleReconciliation>;

package/dist/cli/upLifecycleRecovery.js

@@ -0,0 +1,197 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { lstat } from "node:fs/promises";
+import path from "node:path";
+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";
+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 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 {
+            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_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);
+};