spawnfile 0.1.13 → 0.1.14

package/dist/target/composedPreparation.js

@@ -0,0 +1,223 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { assertOrdinaryJsonGraph, parseSelectedTargetReceipt, parseTargetResourceReceipt, parseTargetResourceRequest, } from "./contracts.js";
+import { createCanonicalTargetReceiptBytes, createTargetReceiptDigest, createTargetRequestDigest, } from "./handles.js";
+export const COMPOSED_PREPARATION_REQUEST_VERSION = "spawnfile.composed-preparation.request.v1";
+export const COMPOSED_PREPARATION_RECEIPT_VERSION = "spawnfile.composed-preparation.receipt.v1";
+const identifier = z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/u);
+const runId = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u);
+const digest = z.string().regex(/^sha256:[a-f0-9]{64}$/u);
+const idempotencyKey = z.string().regex(/^idem_[a-z0-9]{16,64}$/u);
+const opaqueHandle = z.string().regex(/^opaque_[a-z0-9]{16,64}$/u);
+export const composedPreparationRequestSchema = z.object({
+    auth_profile: identifier,
+    descriptor_digest: digest,
+    idempotency_key: idempotencyKey,
+    organization: z.object({
+        artifact_digest: digest,
+        world_bindings_digest: digest,
+    }).strict(),
+    run_id: runId,
+    secret_bindings: z.array(z.object({
+        name: identifier,
+        scope: identifier,
+        source_handle: opaqueHandle,
+    }).strict()).min(1).max(32),
+    target_selector: identifier,
+    version: z.literal(COMPOSED_PREPARATION_REQUEST_VERSION),
+    world: z.object({
+        artifact_manifest_digest: digest,
+        bundle_digest: digest,
+    }).strict(),
+}).strict();
+const selectedTarget = z.object({
+    fingerprint: z.string().regex(/^sha256:[a-f0-9]{32}$/u),
+    handle: opaqueHandle,
+    version: z.literal("spawnfile.target-resource.selected-target.v1"),
+}).strict();
+const mutationReceipt = z.object({
+    cleanup_state: z.enum(["not_requested", "preserved", "removed", "incomplete"]).nullable(),
+    descriptor_digest: digest,
+    export_state: z.enum(["not_requested", "exported", "incomplete"]).nullable(),
+    labels: z.array(z.object({ key: identifier, value: identifier }).strict()).max(16),
+    operation: z.enum([
+        "resolve_world_artifact", "prepare_secret_bindings",
+        "create_data_network", "create_evidence_volume",
+    ]),
+    operation_handle: opaqueHandle,
+    receipt_digest: digest,
+    request_digest: digest,
+    result_handle: opaqueHandle,
+    resulting_revision: z.number().int().min(1).max(4),
+    run_id: runId,
+    selected_target: selectedTarget.omit({ version: true }),
+    version: z.literal("spawnfile.target-resource.receipt.v1"),
+}).strict();
+export const composedPreparationReceiptSchema = z.object({
+    auth_profile: identifier,
+    descriptor_digest: digest,
+    organization: z.object({
+        artifact_digest: digest,
+        world_bindings_digest: digest,
+    }).strict(),
+    receipt_digest: digest,
+    request_digest: digest,
+    resources: z.object({
+        data_network: mutationReceipt,
+        evidence_volume: mutationReceipt,
+        secret_bindings: mutationReceipt,
+        world_artifact: mutationReceipt,
+    }).strict(),
+    run_id: runId,
+    selected_target: selectedTarget,
+    target_selector: identifier,
+    version: z.literal(COMPOSED_PREPARATION_RECEIPT_VERSION),
+    world: z.object({
+        artifact_manifest_digest: digest,
+        bundle_digest: digest,
+    }).strict(),
+}).strict().superRefine((value, context) => {
+    const ordered = [
+        ["world_artifact", "resolve_world_artifact", 1],
+        ["secret_bindings", "prepare_secret_bindings", 2],
+        ["data_network", "create_data_network", 3],
+        ["evidence_volume", "create_evidence_volume", 4],
+    ];
+    for (const [key, operation, revision] of ordered) {
+        const receipt = value.resources[key];
+        if (receipt.operation !== operation || receipt.resulting_revision !== revision
+            || receipt.run_id !== value.run_id
+            || receipt.descriptor_digest !== value.descriptor_digest
+            || receipt.selected_target.handle !== value.selected_target.handle
+            || receipt.selected_target.fingerprint !== value.selected_target.fingerprint) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `composed preparation ${key} correlation is invalid`,
+            });
+        }
+    }
+    if (value.resources.world_artifact.result_handle === value.resources.secret_bindings.result_handle
+        || new Set(ordered.map(([key]) => value.resources[key].operation_handle)).size !== ordered.length
+        || new Set(ordered.map(([key]) => value.resources[key].result_handle)).size !== ordered.length) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "composed preparation resource identities are not unique",
+        });
+    }
+});
+const canonical = (value) => {
+    assertOrdinaryJsonGraph(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        const record = value;
+        return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonical(record[key])}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+};
+const hash = (domain, value) => `sha256:${createHash("sha256").update(`${domain}\0${canonical(value)}`).digest("hex")}`;
+export const parseComposedPreparationRequest = (raw) => {
+    assertOrdinaryJsonGraph(raw);
+    return composedPreparationRequestSchema.parse(raw);
+};
+export const createComposedPreparationRequestDigest = (raw) => hash(COMPOSED_PREPARATION_REQUEST_VERSION, parseComposedPreparationRequest(raw));
+export const parseComposedPreparationReceipt = (raw) => {
+    assertOrdinaryJsonGraph(raw);
+    const receipt = composedPreparationReceiptSchema.parse(raw);
+    const { receipt_digest: _digest, ...body } = receipt;
+    if (receipt.receipt_digest !== hash(COMPOSED_PREPARATION_RECEIPT_VERSION, body)) {
+        throw new TypeError("Composed preparation receipt digest is invalid");
+    }
+    return Object.freeze(receipt);
+};
+export const createCanonicalComposedPreparationReceiptBytes = (raw) => canonical(parseComposedPreparationReceipt(raw));
+const operationKey = (request, operation) => `idem_${createHash("sha256")
+    .update(`${request.idempotency_key}\0${operation}`, "utf8").digest("hex").slice(0, 32)}`;
+const selectionRequest = (request) => parseTargetResourceRequest({
+    idempotency_key: operationKey(request, "select_target"),
+    operation: "select_target",
+    target_reference: request.target_selector,
+    version: "spawnfile.target-resource.request.v1",
+});
+const mutationEnvelope = (request, target, operation, revision) => ({
+    descriptor_digest: request.descriptor_digest,
+    expected_revision: revision,
+    idempotency_key: operationKey(request, operation),
+    run_id: request.run_id,
+    selected_target: { fingerprint: target.fingerprint, handle: target.handle },
+    version: "spawnfile.target-resource.request.v1",
+});
+const validateMutation = (raw, request, expectedRevision) => {
+    const receipt = parseTargetResourceReceipt(raw.receipt);
+    if (typeof raw.receiptBytes !== "string"
+        || raw.receiptBytes !== createCanonicalTargetReceiptBytes(receipt)
+        || receipt.receipt_digest !== createTargetReceiptDigest(receipt)
+        || receipt.request_digest !== createTargetRequestDigest(request)
+        || receipt.operation !== request.operation
+        || receipt.run_id !== ("run_id" in request ? request.run_id : null)
+        || receipt.descriptor_digest !== ("descriptor_digest" in request ? request.descriptor_digest : null)
+        || receipt.resulting_revision !== expectedRevision
+        || receipt.result_handle === null) {
+        throw new TypeError("Composed preparation operation receipt is invalid");
+    }
+    return receipt;
+};
+const sameSelectedTarget = (receipt, target) => canonical(receipt.selected_target) === canonical({
+    fingerprint: target.fingerprint,
+    handle: target.handle,
+});
+export const prepareComposedRun = async (handlers, raw) => {
+    const request = parseComposedPreparationRequest(raw);
+    const selected = parseSelectedTargetReceipt(await handlers.select_target(selectionRequest(request)));
+    const requests = [
+        parseTargetResourceRequest({
+            ...mutationEnvelope(request, selected, "resolve_world_artifact", 0),
+            artifact_manifest_digest: request.world.artifact_manifest_digest,
+            operation: "resolve_world_artifact",
+        }),
+        parseTargetResourceRequest({
+            ...mutationEnvelope(request, selected, "prepare_secret_bindings", 1),
+            bindings: request.secret_bindings,
+            operation: "prepare_secret_bindings",
+        }),
+        parseTargetResourceRequest({
+            ...mutationEnvelope(request, selected, "create_data_network", 2),
+            operation: "create_data_network",
+        }),
+        parseTargetResourceRequest({
+            ...mutationEnvelope(request, selected, "create_evidence_volume", 3),
+            operation: "create_evidence_volume",
+        }),
+    ];
+    const receipts = [];
+    for (const [index, operationRequest] of requests.entries()) {
+        const handler = handlers[operationRequest.operation];
+        const receipt = validateMutation(await handler(operationRequest), operationRequest, index + 1);
+        if (!sameSelectedTarget(receipt, selected)) {
+            throw new TypeError("Composed preparation selected target changed");
+        }
+        receipts.push(receipt);
+    }
+    const body = {
+        auth_profile: request.auth_profile,
+        descriptor_digest: request.descriptor_digest,
+        organization: request.organization,
+        receipt_digest: `sha256:${"0".repeat(64)}`,
+        request_digest: createComposedPreparationRequestDigest(request),
+        resources: {
+            data_network: receipts[2],
+            evidence_volume: receipts[3],
+            secret_bindings: receipts[1],
+            world_artifact: receipts[0],
+        },
+        run_id: request.run_id,
+        selected_target: selected,
+        target_selector: request.target_selector,
+        version: COMPOSED_PREPARATION_RECEIPT_VERSION,
+        world: request.world,
+    };
+    return parseComposedPreparationReceipt({
+        ...body,
+        receipt_digest: hash(COMPOSED_PREPARATION_RECEIPT_VERSION, (({ receipt_digest: _receiptDigest, ...unsigned }) => unsigned)(body)),
+    });
+};

package/dist/target/containerBundle.d.ts

@@ -0,0 +1,82 @@
+import { type ParsedContainerBundleArchive } from "./containerBundleArchive.js";
+import type { AuthorizedContainerBundlePlan, ContainerBundlePreparationAuthority } from "./containerBundleAuthority.js";
+import { type TargetLocalBundlePrepareReceipt, type TargetLocalBundlePrepareRequest } from "./containerBundleContracts.js";
+import type { TargetLocalBundlePrivateMapping, TargetLocalBundleStore } from "./containerBundleStore.js";
+export declare const TARGET_LOCAL_CONTAINER_BUNDLE_ERROR = "Target-local container bundle preparation failed";
+export interface DockerTargetLocalBundleBuilder {
+    build(input: {
+        readonly archive: ParsedContainerBundleArchive;
+        readonly base_image_config_digest: string;
+        readonly entrypoint: string;
+        readonly gc_tag: string;
+        readonly labels: Readonly<Record<string, string>>;
+        readonly platform: {
+            readonly architecture: "amd64" | "arm64";
+            readonly os: "linux";
+        };
+    }): Promise<{
+        readonly config_id: string;
+        readonly labels: Readonly<Record<string, string>>;
+        readonly platform: {
+            readonly architecture: "amd64" | "arm64";
+            readonly os: "linux";
+        };
+    }>;
+    inspect(input: {
+        readonly config_id: string;
+        readonly gc_tag: string;
+        readonly labels: Readonly<Record<string, string>>;
+        readonly platform: {
+            readonly architecture: "amd64" | "arm64";
+            readonly os: "linux";
+        };
+    }): Promise<{
+        readonly config_id: string;
+        readonly labels: Readonly<Record<string, string>>;
+        readonly platform: {
+            readonly architecture: "amd64" | "arm64";
+            readonly os: "linux";
+        };
+    } | null>;
+    /** Finds only this deterministic anchor. `missing` means no tag existed before an effect. */
+    inspectAnchor(input: {
+        readonly gc_tag: string;
+        readonly labels: Readonly<Record<string, string>>;
+        readonly platform: {
+            readonly architecture: "amd64" | "arm64";
+            readonly os: "linux";
+        };
+    }): Promise<{
+        readonly config_id: string;
+        readonly labels: Readonly<Record<string, string>>;
+        readonly platform: {
+            readonly architecture: "amd64" | "arm64";
+            readonly os: "linux";
+        };
+    } | "missing" | null>;
+    /** A fresh selected-target + daemon attestation. It is called before and after any Docker action. */
+    attestTarget(input: {
+        readonly selected_target: TargetLocalBundlePrepareRequest["selected_target"];
+    }): Promise<{
+        readonly daemon_epoch: string;
+    } | null>;
+}
+export interface TargetLocalContainerBundleOperations {
+    lookup(input: {
+        readonly idempotency_key: unknown;
+        readonly request_digest: unknown;
+    }): ReturnType<TargetLocalBundleStore["lookup"]>;
+    prepare(raw: unknown): Promise<TargetLocalBundlePrepareReceipt>;
+    recover(raw: unknown): Promise<TargetLocalBundlePrepareReceipt>;
+}
+export declare const targetLocalBundleGcTag: (requestDigest: string) => string;
+type BundleLabelPlan = Pick<AuthorizedContainerBundlePlan, "archive_digest" | "artifact_digest" | "base_image_config_digest" | "build_policy_digest" | "bundle_digest" | "entrypoint" | "launcher_digest" | "network_alias" | "platform_digest">;
+export declare const targetLocalBundleLabels: (plan: BundleLabelPlan, daemonEpoch: string, requestDigest: string) => Readonly<Record<string, string>>;
+/** Re-attests the exact private anchor before an image config becomes usable. */
+export declare const attestTargetLocalBundleMapping: (builder: DockerTargetLocalBundleBuilder, value: TargetLocalBundlePrivateMapping) => Promise<void>;
+export declare const createTargetLocalContainerBundleOperations: (input: {
+    readonly authority: ContainerBundlePreparationAuthority;
+    readonly builder: DockerTargetLocalBundleBuilder;
+    readonly store: TargetLocalBundleStore;
+}) => TargetLocalContainerBundleOperations;
+export {};

package/dist/target/containerBundle.js

@@ -0,0 +1,243 @@
+import { createHash } from "node:crypto";
+import { Buffer } from "node:buffer";
+import { parseContainerBundleArchive, validateContainerBundleEnvelope } from "./containerBundleArchive.js";
+import { createTargetLocalBundleReceiptDigest, createTargetLocalBundleRequestDigest, parseTargetLocalBundlePrepareRequest } from "./containerBundleContracts.js";
+import { parseOpaqueTargetHandle } from "./contracts.js";
+export const TARGET_LOCAL_CONTAINER_BUNDLE_ERROR = "Target-local container bundle preparation failed";
+const fail = () => { throw new Error(TARGET_LOCAL_CONTAINER_BUNDLE_ERROR); };
+export const targetLocalBundleGcTag = (requestDigest) => `spfb_${createHash("sha256")
+    .update("spawnfile.target-local-container-bundle.gc-tag.v1\0", "utf8").update(requestDigest).digest("hex").slice(0, 58)}`;
+export const targetLocalBundleLabels = (plan, daemonEpoch, requestDigest) => Object.freeze({
+    spawnfile_target_bundle_v1_archive: plan.archive_digest,
+    spawnfile_target_bundle_v1_alias: plan.network_alias,
+    spawnfile_target_bundle_v1_artifact: plan.artifact_digest,
+    spawnfile_target_bundle_v1_base: plan.base_image_config_digest,
+    spawnfile_target_bundle_v1_bundle: plan.bundle_digest,
+    spawnfile_target_bundle_v1_daemon: daemonEpoch,
+    spawnfile_target_bundle_v1_entrypoint: plan.entrypoint,
+    spawnfile_target_bundle_v1_launcher: plan.launcher_digest,
+    spawnfile_target_bundle_v1_platform: plan.platform_digest,
+    spawnfile_target_bundle_v1_policy: plan.build_policy_digest,
+    spawnfile_target_bundle_v1_request: requestDigest,
+    spawnfile_target_bundle_v1_version: "v1"
+});
+const exactLabels = (actual, expected) => Object.keys(actual).length === Object.keys(expected).length && Object.entries(expected).every(([key, value]) => actual[key] === value);
+const receipt = (request, requestDigest, operation, mapping) => {
+    const raw = { archive_digest: request.archive_digest, artifact_digest: request.artifact_digest,
+        build_policy_digest: request.build_policy_digest, bundle_digest: request.bundle_digest,
+        launcher_digest: request.launcher_digest, mapping_handle: mapping, network_alias: request.network_alias,
+        operation_handle: operation, platform: request.platform, platform_digest: request.platform_digest,
+        receipt_digest: `sha256:${"0".repeat(64)}`, request_digest: requestDigest,
+        selected_target: request.selected_target, version: "spawnfile.target-local-container-bundle.prepare-receipt.v1" };
+    return { ...raw, mapping_handle: parseOpaqueTargetHandle(mapping),
+        operation_handle: parseOpaqueTargetHandle(operation), receipt_digest: createTargetLocalBundleReceiptDigest(raw) };
+};
+const mappingHandle = (operation, requestDigest) => `opaque_${createHash("sha256")
+    .update("spawnfile.target-local-container-bundle.mapping.v1\0", "utf8").update(`${operation}\0${requestDigest}`, "utf8").digest("hex")}`;
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const mapping = (plan, request, daemonEpoch, reservation, configId) => ({
+    archive_digest: plan.archive_digest, artifact_digest: plan.artifact_digest,
+    base_image_config_digest: plan.base_image_config_digest, build_policy_digest: plan.build_policy_digest,
+    bundle_digest: plan.bundle_digest, config_id: configId, daemon_epoch: daemonEpoch,
+    entrypoint: plan.entrypoint, gc_tag: targetLocalBundleGcTag(reservation.request_digest), identity_kind: "docker_image_config_digest",
+    launcher_digest: plan.launcher_digest, network_alias: plan.network_alias,
+    operation_handle: reservation.operation_handle, platform: plan.platform, platform_digest: plan.platform_digest,
+    request_digest: reservation.request_digest, selected_target: request.selected_target
+});
+const compatibleMapping = (value, plan, request, requestDigest) => value.request_digest === requestDigest && value.archive_digest === plan.archive_digest && value.artifact_digest === plan.artifact_digest
+    && value.base_image_config_digest === plan.base_image_config_digest && value.build_policy_digest === plan.build_policy_digest
+    && value.bundle_digest === plan.bundle_digest && value.entrypoint === plan.entrypoint && value.launcher_digest === plan.launcher_digest
+    && value.network_alias === plan.network_alias && value.platform_digest === plan.platform_digest
+    && same(value.platform, plan.platform) && same(value.selected_target, request.selected_target);
+/** Re-attests the exact private anchor before an image config becomes usable. */
+export const attestTargetLocalBundleMapping = async (builder, value) => {
+    if (value.gc_tag !== targetLocalBundleGcTag(value.request_digest))
+        fail();
+    const first = await builder.attestTarget({ selected_target: value.selected_target });
+    if (!first || first.daemon_epoch !== value.daemon_epoch)
+        fail();
+    const expected = targetLocalBundleLabels(value, value.daemon_epoch, value.request_digest);
+    const inspected = await builder.inspect({ config_id: value.config_id, gc_tag: value.gc_tag, labels: expected, platform: value.platform });
+    if (!inspected || inspected.config_id !== value.config_id || !exactLabels(inspected.labels, expected)
+        || !same(inspected.platform, value.platform))
+        fail();
+    const second = await builder.attestTarget({ selected_target: value.selected_target });
+    if (!second || second.daemon_epoch !== value.daemon_epoch)
+        fail();
+};
+export const createTargetLocalContainerBundleOperations = (input) => {
+    if (!input?.authority || typeof input.authority.authorize !== "function" || !input.builder || !input.store)
+        fail();
+    const attest = async (request) => {
+        const result = await input.builder.attestTarget({ selected_target: request.selected_target });
+        if (!result || !/^sha256:[a-f0-9]{64}$/u.test(result.daemon_epoch))
+            fail();
+        return result.daemon_epoch;
+    };
+    const withHeartbeat = async (lease, action) => {
+        let current = lease;
+        let failure;
+        let renewing = Promise.resolve();
+        const beat = () => { renewing = renewing.then(async () => { try {
+            current = await input.store.renew({ lease: current });
+        }
+        catch (error) {
+            failure = error;
+        } }); };
+        const timer = setInterval(beat, 5_000);
+        try {
+            const value = await action();
+            await renewing;
+            if (failure)
+                fail();
+            return { lease: current, value };
+        }
+        finally {
+            clearInterval(timer);
+        }
+    };
+    const replayAnchor = async (value, plan, request) => {
+        const privateMapping = value.mapping;
+        if (!compatibleMapping(privateMapping, plan, request, value.receipt.request_digest)
+            || privateMapping.operation_handle !== value.receipt.operation_handle
+            || privateMapping.gc_tag !== targetLocalBundleGcTag(privateMapping.request_digest))
+            fail();
+        const first = await input.builder.attestTarget({ selected_target: privateMapping.selected_target });
+        if (!first || first.daemon_epoch !== privateMapping.daemon_epoch)
+            fail();
+        const expected = targetLocalBundleLabels(privateMapping, privateMapping.daemon_epoch, privateMapping.request_digest);
+        const inspected = await input.builder.inspectAnchor({ gc_tag: privateMapping.gc_tag, labels: expected, platform: privateMapping.platform });
+        const second = await input.builder.attestTarget({ selected_target: privateMapping.selected_target });
+        if (!second || second.daemon_epoch !== privateMapping.daemon_epoch)
+            fail();
+        if (inspected === "missing")
+            return "missing";
+        if (!inspected || inspected.config_id !== privateMapping.config_id || !exactLabels(inspected.labels, expected)
+            || !same(inspected.platform, privateMapping.platform))
+            fail();
+        return "intact";
+    };
+    const reserveAttested = async (request, plan, joinPending) => {
+        let reservation = await input.store.reserve(request);
+        let mayJoin = joinPending;
+        for (let attempt = 0; attempt < 4; attempt += 1) {
+            if (reservation.kind === "replay") {
+                if (await replayAnchor(reservation, plan, request) === "intact")
+                    return reservation;
+                reservation = await input.store.retryMissingCompleted({ generation: reservation.generation,
+                    operation_handle: reservation.receipt.operation_handle, request_digest: reservation.receipt.request_digest });
+                mayJoin = true;
+                continue;
+            }
+            if (reservation.kind === "pending" && mayJoin) {
+                const waited = await input.store.awaitReplay({ idempotency_key: request.idempotency_key,
+                    maximum_wait_ms: 30_000, request_digest: createTargetLocalBundleRequestDigest(request) });
+                if (waited.status !== "completed")
+                    return reservation;
+                reservation = await input.store.reserve(request);
+                continue;
+            }
+            return reservation;
+        }
+        return fail();
+    };
+    const buildOwner = async (request, plan, owner) => {
+        const archive = parseContainerBundleArchive(Buffer.from(request.archive_base64, "base64"), request.archive_entries, request.archive_digest);
+        validateContainerBundleEnvelope(archive, plan);
+        let buildLease = await input.store.beginBuild({ lease: owner.lease });
+        const daemonEpoch = await attest(request);
+        const expected = targetLocalBundleLabels(plan, daemonEpoch, owner.request_digest);
+        buildLease = await input.store.renew({ lease: buildLease });
+        const heartbeated = await withHeartbeat(buildLease, () => input.builder.build({ archive, base_image_config_digest: plan.base_image_config_digest,
+            entrypoint: plan.entrypoint, gc_tag: targetLocalBundleGcTag(owner.request_digest), labels: expected, platform: plan.platform }));
+        buildLease = heartbeated.lease;
+        const built = heartbeated.value;
+        buildLease = await input.store.renew({ lease: buildLease });
+        if (!/^sha256:[a-f0-9]{64}$/u.test(built.config_id) || !exactLabels(built.labels, expected) || !same(built.platform, plan.platform)
+            || await attest(request) !== daemonEpoch) {
+            await input.store.markIncomplete({ lease: buildLease, operation_handle: owner.operation_handle, request_digest: owner.request_digest });
+            fail();
+        }
+        const privateMapping = mapping(plan, request, daemonEpoch, owner, built.config_id);
+        const postbuildLease = await input.store.stagePostbuild({ lease: buildLease, mapping: privateMapping });
+        try {
+            await attestTargetLocalBundleMapping(input.builder, privateMapping);
+        }
+        catch {
+            await input.store.markIncomplete({ lease: postbuildLease, operation_handle: owner.operation_handle, request_digest: owner.request_digest });
+            fail();
+        }
+        return input.store.complete({ lease: postbuildLease, mapping: privateMapping,
+            receipt: receipt(request, owner.request_digest, owner.operation_handle, mappingHandle(owner.operation_handle, owner.request_digest)) });
+    };
+    const completePostbuild = async (request, plan, owner) => {
+        const recovered = owner.mapping;
+        if (recovered === undefined || owner.state !== "postbuild")
+            return fail();
+        const daemonEpoch = await attest(request);
+        if (!compatibleMapping(recovered, plan, request, owner.request_digest) || recovered.daemon_epoch !== daemonEpoch)
+            fail();
+        await attestTargetLocalBundleMapping(input.builder, recovered);
+        return input.store.complete({ lease: owner.lease, mapping: recovered,
+            receipt: receipt(request, owner.request_digest, owner.operation_handle, mappingHandle(owner.operation_handle, owner.request_digest)) });
+    };
+    const recover = async (raw) => {
+        const request = parseTargetLocalBundlePrepareRequest(raw);
+        const plan = input.authority.authorize(request);
+        const reservation = await reserveAttested(request, plan, false);
+        if (reservation.kind === "replay")
+            return reservation.receipt;
+        if (reservation.kind !== "owner")
+            fail();
+        const owner = reservation;
+        if (owner.state === "prebuild")
+            return buildOwner(request, plan, owner);
+        const recovered = owner.mapping;
+        if (owner.state === "inflight" && recovered === undefined) {
+            const daemonEpoch = await attest(request);
+            const expected = targetLocalBundleLabels(plan, daemonEpoch, owner.request_digest);
+            const anchor = await input.builder.inspectAnchor({ gc_tag: targetLocalBundleGcTag(owner.request_digest), labels: expected, platform: plan.platform });
+            if (anchor && anchor !== "missing") {
+                const adopted = mapping(plan, request, daemonEpoch, owner, anchor.config_id);
+                const postbuild = await input.store.stagePostbuild({ lease: owner.lease, mapping: adopted });
+                await attestTargetLocalBundleMapping(input.builder, adopted);
+                return input.store.complete({ lease: postbuild, mapping: adopted,
+                    receipt: receipt(request, owner.request_digest, owner.operation_handle, mappingHandle(owner.operation_handle, owner.request_digest)) });
+            }
+            if (anchor !== "missing")
+                fail(); // Existing but non-exact is ambiguous drift, never a retry.
+            const retryLease = await input.store.retryPrebuild({ lease: owner.lease });
+            return buildOwner(request, plan, { ...owner, lease: retryLease, state: "prebuild" });
+        }
+        return completePostbuild(request, plan, owner);
+    };
+    const prepare = async (raw) => {
+        const request = parseTargetLocalBundlePrepareRequest(raw);
+        const plan = input.authority.authorize(request);
+        const reservation = await reserveAttested(request, plan, true);
+        if (reservation.kind === "replay")
+            return reservation.receipt;
+        if (reservation.kind !== "owner")
+            fail();
+        const owner = reservation;
+        if (owner.state === "postbuild")
+            return completePostbuild(request, plan, owner);
+        /* An expired/reclaimed inflight record is ambiguous; never erase it from a fresh caller. */
+        if (owner.state !== "prebuild")
+            fail();
+        return buildOwner(request, plan, owner);
+    };
+    /* Join only byte-identical work inside this process; the durable store remains the authority across restarts. */
+    const active = new Map();
+    const joinedPrepare = async (raw) => {
+        const key = createTargetLocalBundleRequestDigest(parseTargetLocalBundlePrepareRequest(raw));
+        const prior = active.get(key);
+        if (prior)
+            return prior;
+        const task = prepare(raw).finally(() => { if (active.get(key) === task)
+            active.delete(key); });
+        active.set(key, task);
+        return task;
+    };
+    return Object.freeze({ lookup: (value) => input.store.lookup(value), prepare: joinedPrepare, recover });
+};

package/dist/target/containerBundleArchive.d.ts

@@ -0,0 +1,31 @@
+export interface ContainerBundleArchiveEntry {
+    readonly bytes: Uint8Array;
+    readonly path: string;
+}
+export interface ParsedContainerBundleArchive {
+    readonly bytes: Uint8Array;
+    readonly entries: readonly ContainerBundleArchiveEntry[];
+}
+export interface ContainerBundleEnvelopeClaims {
+    readonly artifact_digest: string;
+    readonly build_policy_digest: string;
+    readonly bundle_digest: string;
+    readonly entrypoint: string;
+    readonly launcher_digest: string;
+    readonly network_alias: string;
+    readonly platform: {
+        readonly architecture: "amd64" | "arm64";
+        readonly os: "linux";
+    };
+    readonly platform_digest: string;
+}
+/** Validates an uncompressed canonical USTAR bundle before Docker ever receives it. */
+export declare const parseContainerBundleArchive: (raw: unknown, allowedPaths: readonly string[], expectedDigest: string) => ParsedContainerBundleArchive;
+/**
+ * The versioned preparation request is the sealed deployment envelope.
+ * The archive digest already commits every byte. The artifact digest is an
+ * owner-defined semantic identity (for example, a manifest digest), while the
+ * launcher is the one generic executable role whose raw bytes Spawnfile can
+ * and must verify without interpreting provider-private contents.
+ */
+export declare const validateContainerBundleEnvelope: (archive: ParsedContainerBundleArchive, claims: ContainerBundleEnvelopeClaims) => void;