spawnfile 0.1.14 → 0.1.17

package/dist/cli/targetDefaultConfig.js

@@ -3,6 +3,8 @@ import { lstat, mkdir, open, realpath } from "node:fs/promises";
 import path from "node:path";
 import { types as nodeTypes } from "node:util";
 import { resolveSpawnfileHome } from "../auth/index.js";
+import { parsePreparedEvidenceHelperReceipt, } from "../evidenceExportHelper/index.js";
+import { parseDockerBaseImageReference } from "../target/dockerBaseImage.js";
 import { parseDockerArtifactMappings } from "../target/dockerArtifactsProvider.js";
 export { resolveTargetDefaultJournalRoot } from "../target/journalRoot.js";
 export const TARGET_DEFAULT_CONFIG_ERROR = "Target configuration failed";
@@ -16,7 +18,8 @@ const CHILD_ROOTS = Object.freeze([
     "secret-authority",
     "attachment-authority",
     "world-authority",
-    "evidence-export"
+    "evidence-export",
+    "evidence-helper"
 ]);
 const fail = () => { throw new Error(TARGET_DEFAULT_CONFIG_ERROR); };
 const byteLength = (value) => Buffer.byteLength(value, "utf8");
@@ -25,7 +28,7 @@ const descriptorValues = (raw) => {
         || Object.getPrototypeOf(raw) !== Object.prototype)
         return fail();
     const expected = [
-        "artifactMappings", "containerBundleStoreRoot", "context", "dockerCommand", "evidenceDestination",
+        "artifactMappings", "containerBundleStoreRoot", "context", "dockerCommand", "evidenceDestination", "evidenceHelperBaseImage", "preparedEvidenceHelper",
         "helperArtifactManifestDigest", "preparedArtifactMappings", "timeoutMs"
     ];
     const required = ["context", "dockerCommand", "evidenceDestination", "timeoutMs"];
@@ -38,7 +41,7 @@ const descriptorValues = (raw) => {
         return fail();
     return Object.fromEntries(expected.filter((key) => Object.hasOwn(descriptors, key)).map((key) => [key, descriptors[key].value]));
 };
-const preparedMappings = (raw) => {
+export const parseTargetPreparedArtifactMappings = (raw) => {
     if (raw === undefined)
         return Object.freeze([]);
     if (!Array.isArray(raw) || raw.length > 32)
@@ -211,7 +214,7 @@ const prepareRoots = async (containerBundleStoreRoot) => {
         : CHILD_ROOTS;
     const created = await Promise.all(childRoots.map((name) => ensureOwnedRoot(path.join(root, name))));
     const containerBundles = containerBundleStoreRoot === undefined
-        ? created[6]
+        ? created[7]
         : await prepareExplicitContainerBundleRoot(containerBundleStoreRoot, root);
     return Object.freeze({
         root,
@@ -221,6 +224,7 @@ const prepareRoots = async (containerBundleStoreRoot) => {
         attachmentAuthority: created[3],
         worldAuthority: created[4],
         evidenceExport: created[5],
+        evidenceHelper: created[6],
         containerBundles
     });
 };
@@ -270,6 +274,17 @@ export const loadTargetDefaultConfig = async (raw) => {
                 || !DIGEST.test(value.helperArtifactManifestDigest))))
         return fail();
     const dockerCommand = command(value.dockerCommand);
+    const evidenceHelperBaseImage = value.evidenceHelperBaseImage === undefined ? undefined
+        : parseDockerBaseImageReference(value.evidenceHelperBaseImage) ?? fail();
+    const preparedEvidenceHelper = value.preparedEvidenceHelper === undefined ? undefined
+        : (() => { try {
+            return parsePreparedEvidenceHelperReceipt(value.preparedEvidenceHelper);
+        }
+        catch {
+            return fail();
+        } })();
+    if ((evidenceHelperBaseImage === undefined) !== (preparedEvidenceHelper === undefined))
+        return fail();
     let artifactMappings;
     try {
         artifactMappings = value.artifactMappings === undefined
@@ -278,7 +293,7 @@ export const loadTargetDefaultConfig = async (raw) => {
     catch {
         return fail();
     }
-    const preparedArtifactMappings = preparedMappings(value.preparedArtifactMappings);
+    const preparedArtifactMappings = parseTargetPreparedArtifactMappings(value.preparedArtifactMappings);
     if (preparedArtifactMappings.some((prepared) => artifactMappings.some((artifact) => artifact.artifact_manifest_digest === prepared.artifact_manifest_digest)))
         return fail();
     const evidenceDestination = await validateDestination(value.evidenceDestination);
@@ -290,6 +305,8 @@ export const loadTargetDefaultConfig = async (raw) => {
         artifactMappings,
         context: value.context,
         dockerCommand,
+        ...(evidenceHelperBaseImage === undefined ? {} : { evidenceHelperBaseImage }),
+        ...(preparedEvidenceHelper === undefined ? {} : { preparedEvidenceHelper }),
         evidenceDestination,
         ...(matches.length === 1 ? { helperArtifact: matches[0] } : {}),
         preparedArtifactMappings,

package/dist/cli/targetDefaultConfigStdin.js

@@ -92,7 +92,7 @@ const exactDefaultConfigObject = (raw) => {
         || Object.getPrototypeOf(raw) !== Object.prototype)
         return fail();
     const expected = [
-        "artifactMappings", "container_bundle_store_root", "context", "dockerCommand", "evidenceDestination",
+        "artifactMappings", "container_bundle_store_root", "context", "dockerCommand", "evidenceDestination", "evidenceHelperBaseImage", "preparedEvidenceHelper",
         "helperArtifactManifestDigest", "preparedArtifactMappings", "timeoutMs", "version"
     ];
     const required = ["context", "dockerCommand", "evidenceDestination", "timeoutMs", "version"];
@@ -193,6 +193,12 @@ const defaultConfigInputs = (raw) => ({
     context: raw.context,
     dockerCommand: raw.dockerCommand,
     evidenceDestination: raw.evidenceDestination,
+    ...(Object.hasOwn(raw, "evidenceHelperBaseImage") ? {
+        evidenceHelperBaseImage: raw.evidenceHelperBaseImage
+    } : {}),
+    ...(Object.hasOwn(raw, "preparedEvidenceHelper") ? {
+        preparedEvidenceHelper: raw.preparedEvidenceHelper
+    } : {}),
     ...(Object.hasOwn(raw, "helperArtifactManifestDigest") ? {
         helperArtifactManifestDigest: raw.helperArtifactManifestDigest
     } : {}),

package/dist/cli/targetDefaultHandlerFactory.js

@@ -9,7 +9,8 @@ import { createDockerSecretOperations } from "../target/dockerSecrets.js";
 import { selectTarget } from "../target/dockerTarget.js";
 import { createDockerWorldServiceOperations } from "../target/dockerWorldService.js";
 import { createEvidenceExportOperations } from "../target/evidenceExport.js";
-import { EVIDENCE_EXPORT_HELPER_CONTRACT } from "../target/evidenceExportProvider.js";
+import { createEvidenceExportHelper, EVIDENCE_EXPORT_HELPER_CONTRACT } from "../target/evidenceExportProvider.js";
+import { resolvePreparedEvidenceHelperImage } from "../evidenceExportHelper/index.js";
 import { createDockerOrganizationAttachmentOperations } from "../target/organizationAttachment.js";
 import { createTargetEvidenceHelperResolutionRequest } from "./targetEvidenceHelperResolution.js";
 export const targetDefaultHandlerFactories = Object.freeze({
@@ -69,7 +70,7 @@ const requireAuthorities = (raw) => {
     const names = [
         "artifactIdentityStore", "attachmentAuthorityStore",
         "evidenceExportAuthorityStore", "executors", "handoffResolver",
-        "helperArtifactResolver", "journals", "secretAuthorityStore",
+        "helperArtifactResolver", "helperExecutor", "journals", "secretAuthorityStore",
         "secretResolver", "topologyAttestor", "worldAuthorityStore", "worldResolver"
     ];
     if (!raw || typeof raw !== "object" || Array.isArray(raw) || nodeTypes.isProxy(raw)
@@ -95,6 +96,9 @@ const requireAuthorities = (raw) => {
     if (executorNames.some((name) => typeof executors[name] !== "function")) {
         throw new Error("Target handler initialization failed");
     }
+    if (typeof values.helperExecutor !== "function") {
+        throw new Error("Target handler initialization failed");
+    }
     for (const name of [
         "handoffResolver", "journals", "secretResolver", "worldResolver"
     ]) {
@@ -180,6 +184,23 @@ const execute = async (expected, factories, authorities, config, raw) => {
                 }).execute(request);
             case "export_evidence_volume":
             case "recover_operation": {
+                if (config.evidenceHelperBaseImage && config.preparedEvidenceHelper) {
+                    const helperInput = { baseImage: config.evidenceHelperBaseImage, context: config.context,
+                        executor: authorities.helperExecutor, privateRoot: config.paths.evidenceHelper,
+                        timeoutMs: config.timeoutMs };
+                    const image = await resolvePreparedEvidenceHelperImage(helperInput, config.preparedEvidenceHelper);
+                    const localHelper = createEvidenceExportHelper({ artifactManifestDigest: config.preparedEvidenceHelper.digest,
+                        imageDigest: image.configDigest, imageReference: image.imageReference, resultHandle: config.preparedEvidenceHelper.handle });
+                    const operations = factories.evidence({
+                        ...common, artifactIdentityStore: authorities.artifactIdentityStore,
+                        authorityStore: authorities.evidenceExportAuthorityStore, executor: authorities.executors.resource,
+                        exportExecutor: authorities.executors.evidenceExport, helperArtifactContract: EVIDENCE_EXPORT_HELPER_CONTRACT,
+                        helperArtifactManifestDigest: config.preparedEvidenceHelper.digest, localHelper
+                    });
+                    return request.operation === "recover_operation"
+                        ? operations.recover(request, config.evidenceDestination)
+                        : operations.execute(request, config.evidenceDestination);
+                }
                 if (!config.helperArtifact || !authorities.helperArtifactResolver) {
                     throw new Error("Target evidence helper is not configured");
                 }

package/dist/cli/targetDefaultHandlers.d.ts

@@ -1,6 +1,6 @@
 import type { TargetTopologyAttestationRequest } from "../target/contracts.js";
 import type { TargetTopologyAttestationResult } from "../target/topologyAttestation.js";
-import type { TargetPublicArtifactSnapshot, TargetPublicArtifactSnapshotRequest } from "../target/publicArtifactSnapshot.js";
+import type { TargetPublicArtifactSnapshotRequest, TargetPublicArtifactSnapshotResult } from "../target/publicArtifactSnapshot.js";
 import type { TargetTopologyActivationResult } from "../target/topologyActivation.js";
 import type { TargetDefaultConfig } from "./targetDefaultConfig.js";
 import type { TargetCommandHandlers } from "./targetCommands.js";
@@ -15,7 +15,7 @@ export declare const withTargetDefaultHandlerSession: <Result>(config: TargetDef
 /** The read-only attestor owns the same private authority graph as mutations. */
 export declare const attestTargetDefaultTopology: (config: TargetDefaultConfig, request: TargetTopologyAttestationRequest) => Promise<TargetTopologyAttestationResult>;
 /** Read one exact, bounded public projection from an attested world service. */
-export declare const snapshotTargetDefaultPublicArtifact: (config: TargetDefaultConfig, request: TargetPublicArtifactSnapshotRequest) => Promise<TargetPublicArtifactSnapshot>;
+export declare const snapshotTargetDefaultPublicArtifact: (config: TargetDefaultConfig, request: TargetPublicArtifactSnapshotRequest) => Promise<TargetPublicArtifactSnapshotResult>;
 export declare const activateTargetDefaultTopology: (config: TargetDefaultConfig, request: TargetTopologyAttestationRequest) => Promise<TargetTopologyActivationResult>;
 /** Internal lifecycle primitive; not re-exported from the package surface. */
 export declare const runTargetDefaultHandlerSession: <Result>(session: TargetDefaultHandlerSession, invoke: (handlers: TargetCommandHandlers) => Promise<Result>, signal?: AbortSignal) => Promise<Result>;

package/dist/cli/targetProductionCommands.d.ts

@@ -0,0 +1,5 @@
+import type { Command } from "commander";
+import type { TargetDefaultConfig } from "./targetDefaultConfig.js";
+import { type SetTargetCommandExitCode, type TargetCommandHandlerSession, type TargetCommandStreams } from "./targetCommands.js";
+export declare const createProductionTargetCommandSession: (config: TargetDefaultConfig) => TargetCommandHandlerSession;
+export declare const registerProductionTargetCommands: (program: Command, streams: TargetCommandStreams, stdin: AsyncIterable<unknown>, setExitCode: SetTargetCommandExitCode) => void;

package/dist/cli/targetProductionCommands.js

@@ -0,0 +1,45 @@
+import { registerContainerBundleCommand } from "./containerBundleCommand.js";
+import { readTargetDefaultConfigStdin, readTargetWorldReadinessConfigStdin, } from "./targetDefaultConfigStdin.js";
+import { createProductionTargetWorldQuerySession } from "./targetDefaultWorldQueries.js";
+import { registerTargetConfigResolverCommand, TARGET_CONFIG_RESOLVER_COMMAND, } from "./targetConfigResolverCommand.js";
+import { createProductionTargetLookupLoader } from "./targetLookupCommands.js";
+import { registerTargetCommands, } from "./targetCommands.js";
+export const createProductionTargetCommandSession = (config) => Object.freeze({
+    activateTopology: async (request) => {
+        const { activateTargetDefaultTopology } = await import("./targetDefaultHandlers.js");
+        return activateTargetDefaultTopology(config, request);
+    },
+    run: async (invokeHandlers) => {
+        const { withTargetDefaultHandlerSession } = await import("./targetDefaultHandlers.js");
+        return withTargetDefaultHandlerSession(config, invokeHandlers);
+    },
+    attestTopology: async (request) => {
+        const { attestTargetDefaultTopology } = await import("./targetDefaultHandlers.js");
+        return attestTargetDefaultTopology(config, request);
+    },
+    queryWorldReadiness: async (request) => {
+        const { queryTargetDefaultWorldReadiness } = await import("./targetDefaultWorldReadiness.js");
+        return queryTargetDefaultWorldReadiness(config, request);
+    },
+    queryWorldClock: async (request) => {
+        const { queryTargetDefaultWorldClock } = await import("./targetDefaultWorldClock.js");
+        return queryTargetDefaultWorldClock(config, request);
+    },
+    snapshotPublicArtifact: async (request) => {
+        const { snapshotTargetDefaultPublicArtifact } = await import("./targetDefaultHandlers.js");
+        return snapshotTargetDefaultPublicArtifact(config, request);
+    },
+});
+export const registerProductionTargetCommands = (program, streams, stdin, setExitCode) => {
+    const target = registerTargetCommands(program, async (configInput) => {
+        if (configInput !== "-")
+            throw new TypeError("Invalid target configuration");
+        return createProductionTargetCommandSession(await readTargetDefaultConfigStdin(stdin));
+    }, streams, setExitCode, createProductionTargetLookupLoader(stdin), async (configInput) => {
+        if (configInput !== "-")
+            throw new TypeError("Invalid target configuration");
+        return createProductionTargetWorldQuerySession(await readTargetWorldReadinessConfigStdin(stdin));
+    }, [TARGET_CONFIG_RESOLVER_COMMAND]);
+    registerContainerBundleCommand(target, stdin, streams, setExitCode);
+    registerTargetConfigResolverCommand(target, streams, setExitCode);
+};

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

@@ -1,6 +1,6 @@
 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";
@@ -68,9 +68,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 +103,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 +142,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);
 };