spawnfile 0.1.14 → 0.1.17

package/dist/compiler/upProject.js

@@ -1,18 +1,17 @@
 import path from "node:path";
-import { createHash } from "node:crypto";
 import { rm } from "node:fs/promises";
-import { createOrganizationReadinessPending, createDockerOrganizationHandoffSession, createDockerDeploymentRecord, initializeOrganizationHandoffAuthorityStore, parseCanonicalSha256Digest, probeDockerOrganizationReadiness, readDeploymentRecord, resolveDockerDeploymentTarget, resolveDeploymentRecordPath, writeDeploymentRecord, writeDockerDeploymentRecordForRun } from "../deployment/index.js";
-import { createCanonicalSelectedTargetReceiptBytes, parseOpaqueTargetHandle, parseRunId, parseSelectedTargetReceipt, selectTarget } from "../target/index.js";
+import { createOrganizationReadinessPending, createDockerDeploymentRecord, probeDockerOrganizationReadiness, readDeploymentRecord, resolveDockerDeploymentTarget, resolveDeploymentRecordPath, writeDeploymentRecord, writeDockerDeploymentRecordForRun, } from "../deployment/index.js";
 import { buildProject } from "./buildProject.js";
 import { createDockerRunInvocation, resolveDetachedDeploymentOptions, runDockerContainer } from "./runProject.js";
 import { executeDockerRunWithSupportCleanup } from "./runProjectLifecycle.js";
 import { requireAuthProfile } from "../auth/index.js";
 import { DEFAULT_OUTPUT_DIRECTORY, SpawnfileError } from "../shared/index.js";
+import { assertNoDeclaredVolumeNames, resolveDeploymentLineage } from "./deploymentLineage.js";
 import { ensureNoopolisRunId, resolveNoopolisRunId } from "../runtime/index.js";
 import { fileExists } from "../filesystem/index.js";
 import { resolveHostCliCredential } from "./runProjectAuth.js";
-const handoffInputError = () => new SpawnfileError("validation_error", "Organization handoff requires authorized run id, selected target receipt, descriptor digest, selected target receipt digest, network attachment handle, and world bindings");
-const handoffRecoveryIncompleteError = () => new SpawnfileError("runtime_error", "Organization handoff recovery is incomplete; redeploy with explicit authorization");
+import { defaultDockerTargetExecFile } from "../target/dockerTargetExecFile.js";
+import { compileOrganizationHandoff, executeOrganizationHandoff, organizationHandoffInputError, resolveRequestedOrganizationHandoff, verifyRequestedOrganizationHandoffTarget, } from "./upProjectHandoff.js";
 const stableRecord = (record) => {
     const { created_at: _createdAt, export_index: _exportIndex, organization_ready: _organizationReady, ...stable } = record;
     return stable;
@@ -26,85 +25,17 @@ const canonicalJson = (value) => {
     }
     const serialized = JSON.stringify(value);
     if (serialized === undefined)
-        throw handoffInputError();
+        throw organizationHandoffInputError();
     return serialized;
 };
-const resolveRequestedHandoff = (options) => {
-    const values = [
-        options.descriptorDigest,
-        options.organizationHandoffRunId,
-        options.selectedTargetReceiptDigest,
-        options.selectedTargetReceipt,
-        options.networkAttachmentHandle,
-        options.worldBindingsPath
-    ];
-    if (values.every((value) => value === undefined))
-        return null;
-    if (values.some((value) => value === undefined) || !options.detach)
-        throw handoffInputError();
-    try {
-        const selectedTarget = parseSelectedTargetReceipt(options.selectedTargetReceipt);
-        const selectedDigest = parseCanonicalSha256Digest(options.selectedTargetReceiptDigest, "selected_target_receipt_digest");
-        const computedDigest = `sha256:${createHash("sha256").update(createCanonicalSelectedTargetReceiptBytes(selectedTarget), "utf8").digest("hex")}`;
-        if (selectedDigest !== computedDigest)
-            throw new Error("selected receipt digest mismatch");
-        return {
-            descriptorDigest: parseCanonicalSha256Digest(options.descriptorDigest, "descriptor_digest"),
-            runId: parseRunId(options.organizationHandoffRunId),
-            networkAttachmentHandle: parseOpaqueTargetHandle(options.networkAttachmentHandle),
-            selectedTarget,
-            selectedTargetReceiptDigest: selectedDigest
-        };
-    }
-    catch {
-        throw handoffInputError();
-    }
-};
-const verifyRequestedHandoffTarget = async (requested, resolved, options) => {
-    if (!requested)
-        return;
-    if (typeof resolved.dockerContext !== "string" || resolved.dockerContext.length === 0
-        || resolved.dockerHost != null || process.env.DOCKER_HOST != null)
-        throw handoffInputError();
-    try {
-        const actual = await selectTarget({
-            context: resolved.dockerContext,
-            dockerCommand: options.dockerCommand,
-            execFile: options.targetExecFile
-        });
-        if (createCanonicalSelectedTargetReceiptBytes(actual)
-            !== createCanonicalSelectedTargetReceiptBytes(requested.selectedTarget))
-            throw new Error("target mismatch");
-    }
-    catch {
-        throw handoffInputError();
-    }
-};
-const resolveCompiledHandoff = (requested, buildResult) => {
-    if (!requested)
-        return undefined;
-    try {
-        const bindingDigest = buildResult.organizationReadinessEvidence.worldBindings?.digest;
-        if (!bindingDigest)
-            throw new Error("missing compiled binding evidence");
-        const bindingDigestParsed = parseCanonicalSha256Digest(bindingDigest, "binding_digest");
-        return { authority: { ...requested, bindingDigest: bindingDigestParsed }, organizationHandoff: {
-                bindingDigest: bindingDigestParsed, networkAttachmentHandle: requested.networkAttachmentHandle,
-                selectedTargetReceiptDigest: requested.selectedTargetReceiptDigest
-            } };
-    }
-    catch {
-        throw handoffInputError();
-    }
-};
 export const upProject = async (inputPath, options = {}) => {
     // Parse caller authority before any target or build work. Target identity is
     // verified below from the resolved detached options, including exact record reuse.
-    const requestedHandoff = resolveRequestedHandoff(options);
+    const requestedHandoff = resolveRequestedOrganizationHandoff(options);
     // Handoff reservation identity must survive a process crash.  Unlike an
     // ordinary deployment run, it may never silently mint a fresh run id.
     if (requestedHandoff && resolveNoopolisRunId(process.env) !== requestedHandoff.runId)
-        throw handoffInputError();
+        throw organizationHandoffInputError();
     const resolvedOptions = await resolveDetachedDeploymentOptions(path.resolve(options.outputDirectory ?? DEFAULT_OUTPUT_DIRECTORY), {
         authProfile: options.authProfile,
         containerName: options.containerName,
@@ -117,7 +48,7 @@ export const upProject = async (inputPath, options = {}) => {
         imageTag: options.imageTag,
         targetExecFile: options.targetExecFile
     });
-    await verifyRequestedHandoffTarget(requestedHandoff, resolvedOptions, options);
+    await verifyRequestedOrganizationHandoffTarget(requestedHandoff, resolvedOptions, options);
     // Every authority container compiled for this deployment must stamp
     // causal events under the same real run id (see specs/CAUSAL.md).
     // buildProject/compileProject stay deterministic functions of the host
@@ -132,6 +63,7 @@ export const upProject = async (inputPath, options = {}) => {
         containerArchitecture: options.containerArchitecture,
         dockerContext: resolvedOptions.dockerContext,
         dockerCommand: options.dockerCommand,
+        deploymentLineage: resolveDeploymentLineage(resolvedOptions.deploymentName ?? "default", options.deploymentLineageNamespace),
         imageTag: resolvedOptions.imageTag,
         outputDirectory: options.outputDirectory,
         runtimePackageOverrides: options.runtimePackageOverrides,
@@ -139,7 +71,12 @@ export const upProject = async (inputPath, options = {}) => {
             ? { worldBindingsPath: options.worldBindingsPath }
             : {})
     });
-    const handoff = resolveCompiledHandoff(requestedHandoff, buildResult);
+    // Before anything starts: a namespaced (dev) deployment must not silently
+    // attach production's author-declared volumes by name.
+    if (options.deploymentLineageNamespace && !options.allowDeclaredVolumeNames) {
+        assertNoDeclaredVolumeNames(buildResult.report.container?.persistent_mounts ?? []);
+    }
+    const handoff = compileOrganizationHandoff(requestedHandoff, buildResult);
     const authProfile = resolvedOptions.authProfile
         ? await requireAuthProfile(resolvedOptions.authProfile)
         : null;
@@ -156,124 +93,113 @@ export const upProject = async (inputPath, options = {}) => {
         dockerHost: resolvedOptions.dockerHost,
         envFilePath: resolvedOptions.envFilePath
     });
-    let authority;
+    if (options.onDetachedStarted) {
+        const started = options.onDetachedStarted;
+        invocation.onDetachedStarted = async (result) => {
+            if (!result.containerId || !result.containerName || !result.imageId || !result.deploymentLabels) {
+                throw new SpawnfileError("runtime_error", "Detached deployment metadata is incomplete");
+            }
+            await started({ ...result, containerId: result.containerId, containerName: result.containerName, imageId: result.imageId, deploymentLabels: result.deploymentLabels });
+        };
+    }
     let deploymentRecordPath;
-    let recovered = false;
-    let dockerLifecycleInvoked = false;
-    try {
-        let pending;
-        if (handoff) {
-            if (!invocation.deploymentLabels || !invocation.containerName)
-                throw handoffInputError();
-            const session = createDockerOrganizationHandoffSession({
-                bindingDigest: handoff.authority.bindingDigest,
+    if (handoff) {
+        const executed = await executeOrganizationHandoff({
+            dockerCommand: options.dockerCommand,
+            handoff,
+            invocation,
+            lifecycleRecovery: options.lifecycleRecovery,
+            onDetachedReservation: options.onDetachedReservation,
+            runRunner: options.runRunner ?? runDockerContainer,
+            targetExecFile: options.targetExecFile,
+        });
+        const { organizationHandoffHandle, runMetadata } = executed;
+        const existingRecordPath = invocation.detach && invocation.deploymentName
+            ? resolveDeploymentRecordPath(buildResult.outputDirectory, invocation.deploymentName)
+            : null;
+        if (existingRecordPath && await fileExists(existingRecordPath)) {
+            const existing = await readDeploymentRecord(existingRecordPath);
+            const target = await resolveDockerDeploymentTarget({
+                context: invocation.dockerContext ?? undefined,
+                dockerCommand: invocation.command,
+                dockerHost: invocation.dockerHost ?? undefined,
+                execFile: options.targetExecFile,
+            });
+            const expected = createDockerDeploymentRecord({
+                authProfileName: authProfile?.name ?? null,
+                compileFingerprint: buildResult.report.compile_fingerprint ?? "",
                 containerName: invocation.containerName,
-                deploymentLabels: invocation.deploymentLabels,
-                descriptorDigest: handoff.authority.descriptorDigest,
+                deploymentName: invocation.deploymentName ?? undefined,
+                envFilePath: resolvedOptions.envFilePath,
+                imageTag,
+                networkIds: buildResult.report.container?.moltnet?.server_plans
+                    .filter((server) => server.mode === "managed").map((server) => server.network_id),
+                nodes: buildResult.report.nodes,
                 organizationHandoff: handoff.organizationHandoff,
+                organizationHandoffHandle,
+                outputDirectory: buildResult.outputDirectory,
+                projectRoot: buildResult.report.root,
                 runId: handoff.authority.runId,
-                selectedTarget: handoff.authority.selectedTarget,
-                selectedTargetReceiptDigest: handoff.authority.selectedTargetReceiptDigest
+                runMetadata,
+                runtimeInstanceIds: buildResult.report.container?.runtime_instances.map((instance) => instance.id) ?? [],
+                target,
             });
-            authority = await initializeOrganizationHandoffAuthorityStore();
-            const begun = await authority.begin(session.authorityInput);
-            pending = begun.pending;
-            recovered = !begun.created;
-        }
-        let runMetadata = undefined;
-        if (!recovered) {
-            dockerLifecycleInvoked = true;
-            runMetadata = await executeDockerRunWithSupportCleanup(invocation, options.runRunner ?? runDockerContainer);
+            if (canonicalJson(stableRecord(existing)) !== canonicalJson(stableRecord(expected))) {
+                throw organizationHandoffInputError();
+            }
+            deploymentRecordPath = existingRecordPath;
         }
-        const observed = recovered && authority && pending
-            ? await authority.readDockerMutation(pending.pending_key)
-            : undefined;
-        if (recovered && !observed)
-            throw handoffRecoveryIncompleteError();
-        const recoveredMetadata = observed
-            ? { containerId: observed.container_id, deploymentLabels: observed.deployment_labels, imageId: observed.image_id }
-            : undefined;
-        const exactRunMetadata = runMetadata ?? recoveredMetadata;
-        let organizationHandoffHandle;
-        if (handoff) {
-            if (!exactRunMetadata?.containerId || !exactRunMetadata.deploymentLabels || !exactRunMetadata.imageId || !authority || !pending)
-                throw handoffInputError();
-            if (!recovered)
-                await authority.observeDockerMutation(pending.pending_key, {
-                    containerId: exactRunMetadata.containerId, deploymentLabels: exactRunMetadata.deploymentLabels, imageId: exactRunMetadata.imageId
-                });
-            const finalized = await authority.finalize(pending.pending_key, { containerId: exactRunMetadata.containerId, deploymentLabels: exactRunMetadata.deploymentLabels });
-            organizationHandoffHandle = finalized.organization_handoff_handle;
-            const existingRecordPath = invocation.detach && invocation.deploymentName
-                ? resolveDeploymentRecordPath(buildResult.outputDirectory, invocation.deploymentName)
-                : null;
-            if (existingRecordPath && await fileExists(existingRecordPath)) {
-                const existing = await readDeploymentRecord(existingRecordPath);
-                const target = await resolveDockerDeploymentTarget({
-                    context: invocation.dockerContext ?? undefined,
-                    dockerCommand: invocation.command,
-                    dockerHost: invocation.dockerHost ?? undefined,
-                    execFile: options.targetExecFile
-                });
-                const expected = createDockerDeploymentRecord({
+        else {
+            deploymentRecordPath = invocation.detach && invocation.deploymentName
+                ? await writeDockerDeploymentRecordForRun({
                     authProfileName: authProfile?.name ?? null,
-                    compileFingerprint: buildResult.report.compile_fingerprint ?? "",
-                    containerName: invocation.containerName,
-                    deploymentName: invocation.deploymentName ?? undefined,
                     envFilePath: resolvedOptions.envFilePath,
                     imageTag,
-                    networkIds: buildResult.report.container?.moltnet?.server_plans
-                        .filter((server) => server.mode === "managed").map((server) => server.network_id),
-                    nodes: buildResult.report.nodes,
+                    invocation,
                     organizationHandoff: handoff.organizationHandoff,
                     organizationHandoffHandle,
                     outputDirectory: buildResult.outputDirectory,
-                    projectRoot: buildResult.report.root,
-                    runId: handoff.authority.runId,
-                    runMetadata: exactRunMetadata,
-                    runtimeInstanceIds: buildResult.report.container?.runtime_instances.map((instance) => instance.id) ?? [],
-                    target
+                    report: buildResult.report,
+                    runMetadata,
+                    targetExecFile: options.targetExecFile,
+                })
+                : null;
+        }
+    }
+    else {
+        let dockerLifecycleInvoked = false;
+        try {
+            if (options.onDetachedReservation) {
+                if (!invocation.detach || !invocation.containerName || !invocation.deploymentLabels) {
+                    throw new SpawnfileError("runtime_error", "Detached deployment authority is incomplete");
+                }
+                await options.onDetachedReservation({
+                    containerName: invocation.containerName,
+                    deploymentLabels: invocation.deploymentLabels,
+                    dockerCommand: invocation.command,
+                    dockerContext: invocation.dockerContext ?? null,
                 });
-                if (canonicalJson(stableRecord(existing)) !== canonicalJson(stableRecord(expected)))
-                    throw handoffInputError();
-                deploymentRecordPath = existingRecordPath;
             }
-            else
-                deploymentRecordPath = invocation.detach && invocation.deploymentName
-                    ? await writeDockerDeploymentRecordForRun({ authProfileName: authProfile?.name ?? null, envFilePath: resolvedOptions.envFilePath,
-                        imageTag, invocation, outputDirectory: buildResult.outputDirectory,
-                        organizationHandoff: handoff.organizationHandoff, organizationHandoffHandle, report: buildResult.report,
-                        runMetadata: exactRunMetadata, targetExecFile: options.targetExecFile })
-                    : null;
-        }
-        else
+            dockerLifecycleInvoked = true;
+            const runMetadata = await executeDockerRunWithSupportCleanup(invocation, options.runRunner ?? runDockerContainer);
             deploymentRecordPath = invocation.detach && invocation.deploymentName
-                ? await writeDockerDeploymentRecordForRun({ authProfileName: authProfile?.name ?? null, envFilePath: resolvedOptions.envFilePath,
-                    imageTag, invocation, outputDirectory: buildResult.outputDirectory, report: buildResult.report,
-                    runMetadata: runMetadata ?? undefined, targetExecFile: options.targetExecFile })
+                ? await writeDockerDeploymentRecordForRun({
+                    authProfileName: authProfile?.name ?? null,
+                    envFilePath: resolvedOptions.envFilePath,
+                    imageTag,
+                    invocation,
+                    outputDirectory: buildResult.outputDirectory,
+                    report: buildResult.report,
+                    runMetadata: runMetadata ?? undefined,
+                    targetExecFile: options.targetExecFile,
+                })
                 : null;
-    }
-    finally {
-        // Replay creates a fresh support directory but does not invoke the normal
-        // Docker lifecycle wrapper. Preserve its detached credential cleanup
-        // semantics without deleting bind-mount support files.
-        let cleanupError;
-        try {
-            if (invocation.detach && !dockerLifecycleInvoked)
-                await rm(invocation.envFilePath, { force: true });
-        }
-        catch (error) {
-            cleanupError = error;
         }
-        try {
-            await authority?.dispose();
-        }
-        catch (error) {
-            if (cleanupError === undefined)
-                throw error;
+        finally {
+            if (invocation.detach && !dockerLifecycleInvoked) {
+                await rm(invocation.envFilePath, { force: true });
+            }
         }
-        if (cleanupError !== undefined)
-            throw cleanupError;
     }
     if (deploymentRecordPath && buildResult.organizationReadinessEvidence) {
         const record = await readDeploymentRecord(deploymentRecordPath);
@@ -292,6 +218,19 @@ export const upProject = async (inputPath, options = {}) => {
             execFile: options.targetExecFile,
             record: pendingRecord
         });
+        if (organizationReady.state === "failed" || organizationReady.state === "cancelled") {
+            const unit = record.units[0];
+            const reference = unit?.container_id ?? unit?.container_name;
+            if (reference) {
+                const prefix = invocation.dockerContext
+                    ? ["--context", invocation.dockerContext]
+                    : invocation.dockerHost ? ["--host", invocation.dockerHost] : [];
+                await (options.targetExecFile ?? defaultDockerTargetExecFile)(invocation.command, [...prefix, "container", "rm", "--force", reference], { timeout: 30_000 });
+            }
+            await rm(invocation.supportDirectory, { recursive: true, force: true });
+            await rm(deploymentRecordPath, { force: true });
+            throw new SpawnfileError("runtime_error", "Detached deployment failed organization readiness and was rolled back");
+        }
         await writeDeploymentRecord(buildResult.outputDirectory, {
             ...pendingRecord,
             organization_ready: organizationReady

package/dist/compiler/upProjectHandoff.d.ts

@@ -0,0 +1,62 @@
+import { type DockerTargetExecFile, type OrganizationHandoffInput } from "../deployment/index.js";
+import { type OpaqueTargetHandle, type SelectedTargetReceipt } from "../target/index.js";
+import type { UpLifecycleRecovery } from "../deployment/upLifecycleRecoveryState.js";
+import { SpawnfileError } from "../shared/index.js";
+import type { BuildProjectResult } from "./buildProject.js";
+import { type DockerRunInvocation, type DockerRunResult, type DockerRunRunner } from "./runProject.js";
+export interface OrganizationHandoffRequestOptions {
+    readonly descriptorDigest?: string;
+    readonly detach?: boolean;
+    readonly networkAttachmentHandle?: string;
+    readonly organizationHandoffRunId?: string;
+    readonly selectedTargetReceipt?: unknown;
+    readonly selectedTargetReceiptDigest?: string;
+    readonly worldBindingsPath?: string;
+}
+export interface RequestedOrganizationHandoff extends Omit<OrganizationHandoffInput, "bindingDigest"> {
+    readonly descriptorDigest: string;
+    readonly runId: string;
+    readonly selectedTarget: SelectedTargetReceipt;
+}
+export interface CompiledOrganizationHandoff {
+    readonly authority: RequestedOrganizationHandoff & {
+        readonly bindingDigest: string;
+    };
+    readonly organizationHandoff: OrganizationHandoffInput;
+}
+export interface DetachedReservation {
+    readonly containerName: string;
+    readonly deploymentLabels: Readonly<Record<string, string>>;
+    readonly dockerCommand: string;
+    readonly dockerContext: string | null;
+}
+export declare const organizationHandoffInputError: () => SpawnfileError;
+export declare const resolveRequestedOrganizationHandoff: (options: OrganizationHandoffRequestOptions) => RequestedOrganizationHandoff | null;
+export declare const verifyRequestedOrganizationHandoffTarget: (requested: RequestedOrganizationHandoff | null, resolved: {
+    readonly dockerContext?: string | null;
+    readonly dockerHost?: string | null;
+}, options: Pick<OrganizationHandoffExecutionOptions, "dockerCommand" | "targetExecFile">) => Promise<void>;
+export declare const compileOrganizationHandoff: (requested: RequestedOrganizationHandoff | null, buildResult: BuildProjectResult) => CompiledOrganizationHandoff | undefined;
+interface OrganizationHandoffExecutionOptions {
+    readonly dockerCommand?: string;
+    readonly lifecycleRecovery?: UpLifecycleRecovery;
+    readonly targetExecFile?: DockerTargetExecFile;
+}
+export interface ExecuteOrganizationHandoffOptions extends OrganizationHandoffExecutionOptions {
+    readonly handoff: CompiledOrganizationHandoff;
+    readonly invocation: DockerRunInvocation;
+    readonly onDetachedReservation?: (authority: DetachedReservation) => Promise<void>;
+    readonly runRunner: DockerRunRunner;
+}
+interface ExactRunMetadata extends DockerRunResult {
+    readonly containerId: string;
+    readonly containerName: string;
+    readonly deploymentLabels: Readonly<Record<string, string>>;
+    readonly imageId: string;
+}
+/** Resumes only lifecycle-verified state, never stale authority observations. */
+export declare const executeOrganizationHandoff: (input: ExecuteOrganizationHandoffOptions) => Promise<{
+    readonly organizationHandoffHandle: OpaqueTargetHandle;
+    readonly runMetadata: ExactRunMetadata;
+}>;
+export {};

package/dist/compiler/upProjectHandoff.js

@@ -0,0 +1,204 @@
+import { createHash } from "node:crypto";
+import { rm } from "node:fs/promises";
+import { createDockerOrganizationHandoffSession, initializeOrganizationHandoffAuthorityStore, parseCanonicalSha256Digest, } from "../deployment/index.js";
+import { createCanonicalSelectedTargetReceiptBytes, parseOpaqueTargetHandle, parseRunId, parseSelectedTargetReceipt, selectTarget, } from "../target/index.js";
+import { isTrustedUpLifecycleRecovery } from "../deployment/upLifecycleRecoveryState.js";
+import { SpawnfileError } from "../shared/index.js";
+import { executeDockerRunWithSupportCleanup } from "./runProjectLifecycle.js";
+import { recoverDetachedDockerRun, } from "./runProject.js";
+export const organizationHandoffInputError = () => new SpawnfileError("validation_error", "Organization handoff requires authorized run id, selected target receipt, descriptor digest, selected target receipt digest, network attachment handle, and world bindings");
+const recoveryError = () => new SpawnfileError("runtime_error", "Organization handoff recovery is incomplete; redeploy with explicit authorization");
+export const resolveRequestedOrganizationHandoff = (options) => {
+    const values = [
+        options.descriptorDigest,
+        options.organizationHandoffRunId,
+        options.selectedTargetReceiptDigest,
+        options.selectedTargetReceipt,
+        options.networkAttachmentHandle,
+        options.worldBindingsPath,
+    ];
+    if (values.every((value) => value === undefined))
+        return null;
+    if (values.some((value) => value === undefined) || !options.detach)
+        throw organizationHandoffInputError();
+    try {
+        const selectedTarget = parseSelectedTargetReceipt(options.selectedTargetReceipt);
+        const selectedDigest = parseCanonicalSha256Digest(options.selectedTargetReceiptDigest, "selected_target_receipt_digest");
+        const computedDigest = `sha256:${createHash("sha256").update(createCanonicalSelectedTargetReceiptBytes(selectedTarget), "utf8").digest("hex")}`;
+        if (selectedDigest !== computedDigest)
+            throw new Error("selected receipt digest mismatch");
+        return {
+            descriptorDigest: parseCanonicalSha256Digest(options.descriptorDigest, "descriptor_digest"),
+            runId: parseRunId(options.organizationHandoffRunId),
+            networkAttachmentHandle: parseOpaqueTargetHandle(options.networkAttachmentHandle),
+            selectedTarget,
+            selectedTargetReceiptDigest: selectedDigest,
+        };
+    }
+    catch {
+        throw organizationHandoffInputError();
+    }
+};
+export const verifyRequestedOrganizationHandoffTarget = async (requested, resolved, options) => {
+    if (!requested)
+        return;
+    if (typeof resolved.dockerContext !== "string" || resolved.dockerContext.length === 0
+        || resolved.dockerHost != null || process.env.DOCKER_HOST != null)
+        throw organizationHandoffInputError();
+    try {
+        const actual = await selectTarget({
+            context: resolved.dockerContext,
+            dockerCommand: options.dockerCommand,
+            execFile: options.targetExecFile,
+        });
+        if (createCanonicalSelectedTargetReceiptBytes(actual)
+            !== createCanonicalSelectedTargetReceiptBytes(requested.selectedTarget))
+            throw new Error("target mismatch");
+    }
+    catch {
+        throw organizationHandoffInputError();
+    }
+};
+export const compileOrganizationHandoff = (requested, buildResult) => {
+    if (!requested)
+        return undefined;
+    try {
+        const bindingDigest = buildResult.organizationReadinessEvidence.worldBindings?.digest;
+        if (!bindingDigest)
+            throw new Error("missing compiled binding evidence");
+        const parsedBindingDigest = parseCanonicalSha256Digest(bindingDigest, "binding_digest");
+        return {
+            authority: { ...requested, bindingDigest: parsedBindingDigest },
+            organizationHandoff: {
+                bindingDigest: parsedBindingDigest,
+                networkAttachmentHandle: requested.networkAttachmentHandle,
+                selectedTargetReceiptDigest: requested.selectedTargetReceiptDigest,
+            },
+        };
+    }
+    catch {
+        throw organizationHandoffInputError();
+    }
+};
+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 same = (left, right) => canonical(left) === canonical(right);
+const exactRunMetadata = (value) => {
+    if (!value?.containerId || !value.containerName || !value.imageId || !value.deploymentLabels) {
+        throw organizationHandoffInputError();
+    }
+    return value;
+};
+const reattestRecoveredRun = async (invocation, expected) => {
+    const actual = exactRunMetadata(await recoverDetachedDockerRun(invocation, expected.containerId));
+    if (actual.containerName !== expected.containerName || actual.imageId !== expected.imageId
+        || !same(actual.deploymentLabels, expected.deploymentLabels))
+        throw recoveryError();
+    return actual;
+};
+const recovery = (value) => {
+    if (value !== undefined && !isTrustedUpLifecycleRecovery(value))
+        throw organizationHandoffInputError();
+    return value;
+};
+const reserveDetachedRun = async (invocation, reserve) => {
+    if (!reserve)
+        return;
+    if (!invocation.detach || !invocation.containerName || !invocation.deploymentLabels) {
+        throw new SpawnfileError("runtime_error", "Detached deployment authority is incomplete");
+    }
+    await reserve({
+        containerName: invocation.containerName,
+        deploymentLabels: invocation.deploymentLabels,
+        dockerCommand: invocation.command,
+        dockerContext: invocation.dockerContext ?? null,
+    });
+};
+/** Resumes only lifecycle-verified state, never stale authority observations. */
+export const executeOrganizationHandoff = async (input) => {
+    const { handoff, invocation } = input;
+    if (!invocation.deploymentLabels || !invocation.containerName)
+        throw organizationHandoffInputError();
+    const lifecycleRecovery = recovery(input.lifecycleRecovery);
+    const session = createDockerOrganizationHandoffSession({
+        bindingDigest: handoff.authority.bindingDigest,
+        containerName: invocation.containerName,
+        deploymentLabels: invocation.deploymentLabels,
+        descriptorDigest: handoff.authority.descriptorDigest,
+        organizationHandoff: handoff.organizationHandoff,
+        runId: handoff.authority.runId,
+        selectedTarget: handoff.authority.selectedTarget,
+        selectedTargetReceiptDigest: handoff.authority.selectedTargetReceiptDigest,
+    });
+    let authority;
+    let dockerLifecycleInvoked = false;
+    try {
+        // Persist the lifecycle reservation first. A post-begin crash can then be
+        // distinguished as no-start, exact-container, or ambiguous on restart.
+        if (lifecycleRecovery?.kind !== "deployment_record") {
+            await reserveDetachedRun(invocation, input.onDetachedReservation);
+        }
+        authority = await initializeOrganizationHandoffAuthorityStore();
+        const begun = await authority.begin(session.authorityInput);
+        let runMetadata;
+        if (begun.created) {
+            if (lifecycleRecovery?.kind === "detached_container"
+                || lifecycleRecovery?.kind === "deployment_record")
+                throw recoveryError();
+            dockerLifecycleInvoked = true;
+            runMetadata = exactRunMetadata(await executeDockerRunWithSupportCleanup(invocation, input.runRunner));
+        }
+        else {
+            const observed = await authority.readDockerMutation(begun.pending.pending_key);
+            if (observed) {
+                if (lifecycleRecovery?.kind === "no_docker_mutation")
+                    throw recoveryError();
+                const expected = {
+                    containerId: observed.container_id,
+                    containerName: invocation.containerName,
+                    deploymentLabels: observed.deployment_labels,
+                    imageId: observed.image_id,
+                };
+                if (lifecycleRecovery?.kind === "detached_container" && (lifecycleRecovery.containerId !== expected.containerId
+                    || lifecycleRecovery.containerName !== expected.containerName
+                    || lifecycleRecovery.imageId !== expected.imageId
+                    || !same(lifecycleRecovery.deploymentLabels, expected.deploymentLabels)))
+                    throw recoveryError();
+                runMetadata = await reattestRecoveredRun(invocation, expected);
+            }
+            else if (lifecycleRecovery?.kind === "detached_container") {
+                runMetadata = await reattestRecoveredRun(invocation, lifecycleRecovery);
+            }
+            else if (lifecycleRecovery?.kind === "no_docker_mutation") {
+                dockerLifecycleInvoked = true;
+                runMetadata = exactRunMetadata(await executeDockerRunWithSupportCleanup(invocation, input.runRunner));
+            }
+            else
+                throw recoveryError();
+        }
+        await authority.observeDockerMutation(begun.pending.pending_key, runMetadata);
+        const finalized = await authority.finalize(begun.pending.pending_key, runMetadata);
+        return { organizationHandoffHandle: finalized.organization_handoff_handle, runMetadata };
+    }
+    finally {
+        let cleanupError;
+        try {
+            if (invocation.detach && !dockerLifecycleInvoked)
+                await rm(invocation.envFilePath, { force: true });
+        }
+        catch (error) {
+            cleanupError = error;
+        }
+        try {
+            await authority?.dispose();
+        }
+        catch (error) {
+            if (cleanupError === undefined)
+                throw error;
+        }
+        if (cleanupError !== undefined)
+            throw cleanupError;
+    }
+};