spawnfile 0.1.12 → 0.1.14

package/dist/target/dockerWorldServiceAuthority.d.ts

@@ -0,0 +1,80 @@
+import { type OpaqueTargetHandle } from "./contracts.js";
+export declare const WORLD_SERVICE_AUTHORIZATION_VERSION: "spawnfile.target-world-service.authorization.v1";
+export declare const WORLD_SERVICE_ERROR = "Docker world-service lifecycle failed";
+export interface WorldServiceAuthorization {
+    readonly data_network_handle: OpaqueTargetHandle;
+    readonly descriptor_digest: string;
+    readonly evidence_mount_path: string;
+    readonly evidence_volume_handle: OpaqueTargetHandle;
+    readonly operation_handle: OpaqueTargetHandle;
+    readonly request_digest: string;
+    readonly run_id: string;
+    readonly secret_bindings_handle: OpaqueTargetHandle;
+    readonly selected_target: {
+        readonly fingerprint: string;
+        readonly handle: OpaqueTargetHandle;
+    };
+    readonly version: typeof WORLD_SERVICE_AUTHORIZATION_VERSION;
+    readonly world_artifact_handle: OpaqueTargetHandle;
+}
+export interface ResolvedOciWorldArtifactBinding {
+    readonly artifact_manifest_digest: string;
+    /** Legacy in-memory fixtures may omit this; parsed authority packets may not. */
+    readonly identity_kind?: "oci_image_manifest";
+    readonly image_digest: string;
+    readonly image_reference: string;
+    readonly operation_handle: OpaqueTargetHandle;
+    readonly request_digest: string;
+    readonly result_handle: OpaqueTargetHandle;
+}
+export interface ResolvedConfigWorldArtifactBinding {
+    readonly archive_digest: string;
+    readonly artifact_manifest_digest: string;
+    readonly base_image_config_digest: string;
+    readonly build_policy_digest: string;
+    readonly bundle_digest: string;
+    readonly config_id: string;
+    readonly daemon_epoch: string;
+    readonly entrypoint: string;
+    readonly gc_tag: string;
+    readonly identity_kind: "docker_image_config_digest";
+    readonly image_digest: string;
+    readonly image_reference: string;
+    readonly launcher_digest: string;
+    readonly network_alias: string;
+    readonly operation_handle: OpaqueTargetHandle;
+    readonly platform: {
+        readonly architecture: "amd64" | "arm64";
+        readonly os: "linux";
+    };
+    readonly platform_digest: string;
+    readonly prepared_operation_handle: OpaqueTargetHandle;
+    readonly prepared_request_digest: string;
+    readonly request_digest: string;
+    readonly result_handle: OpaqueTargetHandle;
+}
+export type ResolvedWorldArtifactBinding = ResolvedOciWorldArtifactBinding | ResolvedConfigWorldArtifactBinding;
+export interface WorldServiceResolution {
+    readonly artifact: ResolvedWorldArtifactBinding;
+    readonly authorization: WorldServiceAuthorization;
+}
+export interface WorldServiceResolver {
+    resolve(input: {
+        readonly authorization: WorldServiceAuthorization;
+        readonly signal?: AbortSignal;
+    }): Promise<unknown>;
+}
+export declare const createWorldServiceAuthorization: (input: {
+    readonly dataNetworkHandle: unknown;
+    readonly descriptorDigest: unknown;
+    readonly evidenceMountPath: unknown;
+    readonly evidenceVolumeHandle: unknown;
+    readonly operationHandle: unknown;
+    readonly requestDigest: unknown;
+    readonly runId: unknown;
+    readonly secretBindingsHandle: unknown;
+    readonly selectedTarget: unknown;
+    readonly worldArtifactHandle: unknown;
+}) => WorldServiceAuthorization;
+export declare const parseWorldServiceAuthorization: (raw: unknown) => WorldServiceAuthorization;
+export declare const parseWorldServiceResolution: (raw: unknown) => WorldServiceResolution;

package/dist/target/dockerWorldServiceAuthority.js

@@ -0,0 +1,182 @@
+import { assertOrdinaryJsonGraph, parseOpaqueTargetHandle, parseRunId, parseSelectedTargetReceipt } from "./contracts.js";
+import { createDockerArtifactSpec, createDockerConfigArtifactSpec } from "./dockerArtifactsProvider.js";
+export const WORLD_SERVICE_AUTHORIZATION_VERSION = "spawnfile.target-world-service.authorization.v1";
+export const WORLD_SERVICE_ERROR = "Docker world-service lifecycle failed";
+const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/u;
+const FINGERPRINT_PATTERN = /^sha256:[a-f0-9]{32}$/u;
+const fail = () => { throw new Error(WORLD_SERVICE_ERROR); };
+const ordinary = (raw) => {
+    try {
+        assertOrdinaryJsonGraph(raw);
+    }
+    catch {
+        return fail();
+    }
+};
+const record = (raw) => raw !== null && typeof raw === "object" && !Array.isArray(raw)
+    && Object.getPrototypeOf(raw) === Object.prototype;
+const exactKeys = (raw, expected) => {
+    const actual = Object.keys(raw).sort();
+    const wanted = [...expected].sort();
+    return actual.length === wanted.length
+        && actual.every((key, index) => key === wanted[index]);
+};
+const digest = (raw) => {
+    if (typeof raw !== "string" || !DIGEST_PATTERN.test(raw))
+        return fail();
+    return raw;
+};
+const containerPath = (raw) => {
+    if (typeof raw !== "string" || raw.length > 255
+        || !/^\/(?:run|var\/lib)\/[A-Za-z0-9][A-Za-z0-9._/-]*$/u.test(raw) || raw.includes("//")
+        || raw.endsWith("/") || raw.split("/").some((part) => part === "." || part === "..")
+        || raw === "/run/spawnfile-secrets" || raw.startsWith("/run/spawnfile-secrets/")
+        || "/run/spawnfile-secrets".startsWith(`${raw}/`))
+        return fail();
+    return raw;
+};
+export const createWorldServiceAuthorization = (input) => {
+    try {
+        const selected = parseSelectedTargetReceipt({
+            ...(record(input.selectedTarget) ? input.selectedTarget : {}),
+            version: "spawnfile.target-resource.selected-target.v1"
+        });
+        return Object.freeze({
+            data_network_handle: parseOpaqueTargetHandle(input.dataNetworkHandle),
+            descriptor_digest: digest(input.descriptorDigest),
+            evidence_mount_path: containerPath(input.evidenceMountPath),
+            evidence_volume_handle: parseOpaqueTargetHandle(input.evidenceVolumeHandle),
+            operation_handle: parseOpaqueTargetHandle(input.operationHandle),
+            request_digest: digest(input.requestDigest),
+            run_id: parseRunId(input.runId),
+            secret_bindings_handle: parseOpaqueTargetHandle(input.secretBindingsHandle),
+            selected_target: Object.freeze({
+                fingerprint: selected.fingerprint,
+                handle: selected.handle
+            }),
+            version: WORLD_SERVICE_AUTHORIZATION_VERSION,
+            world_artifact_handle: parseOpaqueTargetHandle(input.worldArtifactHandle)
+        });
+    }
+    catch {
+        return fail();
+    }
+};
+export const parseWorldServiceAuthorization = (raw) => {
+    try {
+        ordinary(raw);
+        if (!record(raw) || !exactKeys(raw, [
+            "data_network_handle", "descriptor_digest", "evidence_mount_path", "evidence_volume_handle",
+            "operation_handle", "request_digest", "run_id", "secret_bindings_handle",
+            "selected_target", "version", "world_artifact_handle"
+        ]) || raw.version !== WORLD_SERVICE_AUTHORIZATION_VERSION
+            || !record(raw.selected_target)
+            || !exactKeys(raw.selected_target, ["fingerprint", "handle"])
+            || typeof raw.selected_target.fingerprint !== "string"
+            || !FINGERPRINT_PATTERN.test(raw.selected_target.fingerprint))
+            return fail();
+        return createWorldServiceAuthorization({
+            dataNetworkHandle: raw.data_network_handle,
+            descriptorDigest: raw.descriptor_digest,
+            evidenceMountPath: raw.evidence_mount_path,
+            evidenceVolumeHandle: raw.evidence_volume_handle,
+            operationHandle: raw.operation_handle,
+            requestDigest: raw.request_digest,
+            runId: raw.run_id,
+            secretBindingsHandle: raw.secret_bindings_handle,
+            selectedTarget: raw.selected_target,
+            worldArtifactHandle: raw.world_artifact_handle
+        });
+    }
+    catch {
+        return fail();
+    }
+};
+const parseArtifact = (raw, authorization) => {
+    if (!record(raw) || raw.identity_kind !== undefined && typeof raw.identity_kind !== "string")
+        return fail();
+    let artifact;
+    let spec;
+    try {
+        if (raw.identity_kind === "oci_image_manifest" || raw.identity_kind === undefined) {
+            const legacy = raw.identity_kind === undefined;
+            if (!exactKeys(raw, legacy ? ["artifact_manifest_digest", "image_digest", "image_reference", "operation_handle", "request_digest", "result_handle"]
+                : ["artifact_manifest_digest", "identity_kind", "image_digest", "image_reference", "operation_handle", "request_digest", "result_handle"]))
+                return fail();
+            artifact = Object.freeze({ artifact_manifest_digest: digest(raw.artifact_manifest_digest),
+                identity_kind: "oci_image_manifest", image_digest: digest(raw.image_digest),
+                image_reference: typeof raw.image_reference === "string" ? raw.image_reference : fail(),
+                operation_handle: parseOpaqueTargetHandle(raw.operation_handle), request_digest: digest(raw.request_digest),
+                result_handle: parseOpaqueTargetHandle(raw.result_handle) });
+            spec = createDockerArtifactSpec({ artifactManifestDigest: artifact.artifact_manifest_digest,
+                imageDigest: artifact.image_digest, imageReference: artifact.image_reference,
+                operationHandle: artifact.operation_handle, requestDigest: artifact.request_digest,
+                selectedTargetHandle: authorization.selected_target.handle });
+        }
+        else if (raw.identity_kind === "docker_image_config_digest") {
+            if (!exactKeys(raw, ["archive_digest", "artifact_manifest_digest", "base_image_config_digest",
+                "build_policy_digest", "bundle_digest", "config_id", "daemon_epoch", "entrypoint", "gc_tag", "identity_kind",
+                "image_digest", "image_reference", "launcher_digest", "network_alias", "operation_handle", "platform",
+                "platform_digest", "prepared_operation_handle", "prepared_request_digest", "request_digest", "result_handle"]))
+                return fail();
+            const configId = digest(raw.config_id);
+            const platform = raw.platform;
+            if (!record(platform) || !exactKeys(platform, ["architecture", "os"])
+                || (platform.architecture !== "amd64" && platform.architecture !== "arm64") || platform.os !== "linux"
+                || typeof raw.entrypoint !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._/-]{0,239}$/u.test(raw.entrypoint)
+                || raw.entrypoint.includes("//") || raw.entrypoint.split("/").some((part) => part === "." || part === "..")
+                || typeof raw.network_alias !== "string" || !/^[a-z][a-z0-9-]{0,62}$/u.test(raw.network_alias))
+                return fail();
+            artifact = Object.freeze({ archive_digest: digest(raw.archive_digest),
+                artifact_manifest_digest: digest(raw.artifact_manifest_digest),
+                base_image_config_digest: digest(raw.base_image_config_digest),
+                build_policy_digest: digest(raw.build_policy_digest), bundle_digest: digest(raw.bundle_digest),
+                config_id: configId, daemon_epoch: digest(raw.daemon_epoch), entrypoint: raw.entrypoint,
+                gc_tag: typeof raw.gc_tag === "string" && /^spfb_[a-f0-9]{58}$/u.test(raw.gc_tag) ? raw.gc_tag : fail(),
+                identity_kind: "docker_image_config_digest",
+                image_digest: digest(raw.image_digest), image_reference: typeof raw.image_reference === "string" ? raw.image_reference : fail(),
+                launcher_digest: digest(raw.launcher_digest), network_alias: raw.network_alias,
+                operation_handle: parseOpaqueTargetHandle(raw.operation_handle), request_digest: digest(raw.request_digest),
+                prepared_operation_handle: parseOpaqueTargetHandle(raw.prepared_operation_handle),
+                prepared_request_digest: digest(raw.prepared_request_digest),
+                result_handle: parseOpaqueTargetHandle(raw.result_handle),
+                platform: Object.freeze({ architecture: platform.architecture, os: platform.os }),
+                platform_digest: digest(raw.platform_digest) });
+            if (artifact.image_digest !== configId || artifact.image_reference !== configId)
+                return fail();
+            spec = createDockerConfigArtifactSpec({ archiveDigest: artifact.archive_digest,
+                artifactManifestDigest: artifact.artifact_manifest_digest,
+                baseImageConfigDigest: artifact.base_image_config_digest,
+                buildPolicyDigest: artifact.build_policy_digest, bundleDigest: artifact.bundle_digest,
+                configId, daemonEpoch: artifact.daemon_epoch, entrypoint: artifact.entrypoint,
+                launcherDigest: artifact.launcher_digest, networkAlias: artifact.network_alias,
+                operationHandle: artifact.operation_handle, requestDigest: artifact.request_digest,
+                selectedTargetHandle: authorization.selected_target.handle, platform: artifact.platform,
+                platformDigest: artifact.platform_digest });
+        }
+        else
+            return fail();
+    }
+    catch {
+        return fail();
+    }
+    if (spec.resultHandle !== artifact.result_handle
+        || artifact.result_handle !== authorization.world_artifact_handle)
+        return fail();
+    return artifact;
+};
+export const parseWorldServiceResolution = (raw) => {
+    try {
+        ordinary(raw);
+        if (!record(raw) || !exactKeys(raw, ["artifact", "authorization"]))
+            return fail();
+        const authorization = parseWorldServiceAuthorization(raw.authorization);
+        return Object.freeze({
+            artifact: parseArtifact(raw.artifact, authorization),
+            authorization
+        });
+    }
+    catch {
+        return fail();
+    }
+};

package/dist/target/dockerWorldServiceLifecycle.d.ts

@@ -0,0 +1,41 @@
+import { type OpaqueTargetHandle, type TargetResourceReceipt, type TargetResourceRequest } from "./contracts.js";
+import { type TargetJournalClaim, type TargetJournalStore } from "./journal.js";
+import { type WorldServiceResolution, type WorldServiceResolver } from "./dockerWorldServiceAuthority.js";
+import { type DockerWorldServiceExecutor, type DockerWorldServiceInspection, type DockerWorldServiceSpec } from "./dockerWorldServiceProvider.js";
+import { type WorldServiceAuthorityStore, type WorldServiceBinding } from "./dockerWorldServiceStore.js";
+type ServiceRequest = Extract<TargetResourceRequest, {
+    operation: "create_world_service" | "start_world_service" | "stop_world_service";
+}>;
+type CreateRequest = Extract<ServiceRequest, {
+    operation: "create_world_service";
+}>;
+export interface WorldServiceCleanupContext {
+    readonly context: string;
+    readonly executor: DockerWorldServiceExecutor;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs: number;
+}
+export interface WorldServiceLifecycleContext extends WorldServiceCleanupContext {
+    readonly authorityStore: WorldServiceAuthorityStore;
+    readonly journal: TargetJournalStore;
+    readonly resolver: WorldServiceResolver;
+}
+export declare const sameWorldServiceValue: (left: unknown, right: unknown) => boolean;
+export declare const selectedWorldServiceContextMatches: (request: ServiceRequest, options: WorldServiceLifecycleContext) => Promise<void>;
+export declare const resolveWorldServiceCreate: (request: CreateRequest, claim: TargetJournalClaim, options: WorldServiceLifecycleContext) => Promise<{
+    readonly resolution: WorldServiceResolution;
+    readonly resources: WorldServiceBinding["resources"];
+}>;
+export declare const verifyWorldServiceResources: (binding: Pick<WorldServiceBinding, "resolution" | "resources">, options: WorldServiceLifecycleContext) => Promise<void>;
+export declare const worldServiceSpecForBinding: (binding: Pick<WorldServiceBinding, "resolution" | "resources">) => DockerWorldServiceSpec;
+export declare const inspectDockerWorldService: (reference: string, spec: DockerWorldServiceSpec, options: WorldServiceCleanupContext) => Promise<DockerWorldServiceInspection | null>;
+export declare const mutateDockerWorldService: (args: string[], options: WorldServiceCleanupContext) => Promise<string>;
+export declare const removeExactDockerWorldService: (rawBinding: unknown, options: WorldServiceCleanupContext) => Promise<void>;
+export declare const createWorldServiceReceipt: (input: {
+    readonly claim: TargetJournalClaim;
+    readonly journal: TargetJournalStore;
+    readonly labels: Readonly<Record<string, string>>;
+    readonly request: ServiceRequest;
+    readonly resultHandle: OpaqueTargetHandle | null;
+}) => Promise<TargetResourceReceipt>;
+export {};

package/dist/target/dockerWorldServiceLifecycle.js

@@ -0,0 +1,275 @@
+import { SpawnfileError } from "../shared/index.js";
+import { selectTarget } from "./dockerTarget.js";
+import { createTargetReceiptDigest } from "./handles.js";
+import { createDockerResourceSpec, executeDockerResource, isExpectedDockerResource } from "./dockerResourcesProvider.js";
+import { createExistingDockerSecretSpec, executeDockerSecretCommand, isExpectedDockerSecretVolume } from "./dockerSecretsProvider.js";
+import { WORLD_SERVICE_ERROR, createWorldServiceAuthorization, parseWorldServiceResolution } from "./dockerWorldServiceAuthority.js";
+import { DockerWorldServiceProviderError, createDockerWorldServiceSpec, executeDockerWorldService, parseExpectedDockerWorldService } from "./dockerWorldServiceProvider.js";
+import { parseWorldServiceBinding, worldServiceResourceBindings } from "./dockerWorldServiceStore.js";
+const fail = () => {
+    throw new SpawnfileError("runtime_error", WORLD_SERVICE_ERROR);
+};
+export const sameWorldServiceValue = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+export const selectedWorldServiceContextMatches = async (request, options) => {
+    const selected = await selectTarget({
+        context: options.context,
+        dockerCommand: "docker",
+        execFile: async (_file, args, commandOptions) => executeDockerWorldService({
+            args,
+            executor: options.executor,
+            signal: commandOptions.signal,
+            timeoutMs: commandOptions.timeout
+        }),
+        signal: options.signal,
+        timeoutMs: options.timeoutMs
+    });
+    if (!sameWorldServiceValue({ fingerprint: selected.fingerprint, handle: selected.handle }, request.selected_target))
+        return fail();
+};
+const findResourceClaim = async (input) => {
+    const operation = input.kind === "data_network"
+        ? "create_data_network" : "create_evidence_volume";
+    const journal = await input.journal.read();
+    const matches = journal.entries.filter((entry) => {
+        if (entry.operation !== operation || entry.state !== "completed")
+            return false;
+        try {
+            return createDockerResourceSpec({
+                kind: input.kind,
+                operationHandle: entry.operation_handle,
+                requestDigest: entry.request_digest,
+                runId: input.runId,
+                selectedTargetHandle: input.selectedTargetHandle
+            }).resultHandle === input.handle;
+        }
+        catch {
+            return false;
+        }
+    });
+    if (matches.length !== 1)
+        return fail();
+    return {
+        operationHandle: matches[0].operation_handle,
+        requestDigest: matches[0].request_digest
+    };
+};
+export const resolveWorldServiceCreate = async (request, claim, options) => {
+    const authorization = createWorldServiceAuthorization({
+        dataNetworkHandle: request.data_network_handle,
+        descriptorDigest: request.descriptor_digest,
+        evidenceMountPath: request.evidence_mount_path,
+        evidenceVolumeHandle: request.evidence_volume_handle,
+        operationHandle: claim.operationHandle,
+        requestDigest: claim.requestDigest,
+        runId: request.run_id,
+        secretBindingsHandle: request.secret_bindings_handle,
+        selectedTarget: request.selected_target,
+        worldArtifactHandle: request.world_artifact_handle
+    });
+    const resolution = parseWorldServiceResolution(await options.resolver.resolve({
+        authorization,
+        signal: options.signal
+    }));
+    if (!sameWorldServiceValue(resolution.authorization, authorization))
+        return fail();
+    const journal = await options.journal.read();
+    const artifactClaims = journal.entries.filter((entry) => entry.operation === "resolve_world_artifact" && entry.state === "completed"
+        && entry.operation_handle === resolution.artifact.operation_handle
+        && entry.request_digest === resolution.artifact.request_digest);
+    if (artifactClaims.length !== 1)
+        return fail();
+    const dataNetworkClaim = await findResourceClaim({
+        handle: request.data_network_handle,
+        journal: options.journal,
+        kind: "data_network",
+        runId: request.run_id,
+        selectedTargetHandle: request.selected_target.handle
+    });
+    const evidenceVolumeClaim = await findResourceClaim({
+        handle: request.evidence_volume_handle,
+        journal: options.journal,
+        kind: "evidence_volume",
+        runId: request.run_id,
+        selectedTargetHandle: request.selected_target.handle
+    });
+    const resources = worldServiceResourceBindings({
+        dataNetworkClaim,
+        evidenceVolumeClaim,
+        resolution
+    });
+    await options.authorityStore.bindResolution(resolution);
+    return { resolution, resources };
+};
+export const verifyWorldServiceResources = async (binding, options) => {
+    const authorization = binding.resolution.authorization;
+    for (const [kind, resource] of [
+        ["data_network", binding.resources.data_network],
+        ["evidence_volume", binding.resources.evidence_volume]
+    ]) {
+        const claim = await findResourceClaim({
+            handle: resource.handle,
+            journal: options.journal,
+            kind,
+            runId: authorization.run_id,
+            selectedTargetHandle: authorization.selected_target.handle
+        });
+        const spec = createDockerResourceSpec({
+            kind,
+            ...claim,
+            runId: authorization.run_id,
+            selectedTargetHandle: authorization.selected_target.handle
+        });
+        const result = await executeDockerResource({
+            args: ["--context", options.context,
+                kind === "data_network" ? "network" : "volume", "inspect",
+                "--format", spec.inspectionFormat, spec.name],
+            executor: options.executor,
+            signal: options.signal,
+            timeoutMs: options.timeoutMs
+        });
+        if (!isExpectedDockerResource(result.stdout, spec))
+            return fail();
+    }
+    const secretSpec = createExistingDockerSecretSpec({
+        bindingsHandle: binding.resources.secret_bindings.handle,
+        runId: authorization.run_id,
+        selectedTargetHandle: authorization.selected_target.handle
+    });
+    const secret = await executeDockerSecretCommand({
+        args: ["--context", options.context, "volume", "inspect", "--format",
+            secretSpec.volumeInspectionFormat, secretSpec.volumeName],
+        executor: options.executor,
+        signal: options.signal,
+        timeoutMs: options.timeoutMs
+    });
+    if (!isExpectedDockerSecretVolume(secret.stdout, secretSpec))
+        return fail();
+};
+export const worldServiceSpecForBinding = (binding) => {
+    const authorization = binding.resolution.authorization;
+    return createDockerWorldServiceSpec({
+        dataNetwork: binding.resources.data_network,
+        evidenceMountPath: authorization.evidence_mount_path,
+        evidenceVolume: binding.resources.evidence_volume,
+        imageDigest: binding.resolution.artifact.image_digest,
+        imageReference: binding.resolution.artifact.image_reference,
+        operationHandle: authorization.operation_handle,
+        requestDigest: authorization.request_digest,
+        runId: authorization.run_id,
+        secretBindings: binding.resources.secret_bindings,
+        selectedTargetHandle: authorization.selected_target.handle,
+        ...(binding.resolution.artifact.identity_kind === "docker_image_config_digest"
+            ? { networkAlias: binding.resolution.artifact.network_alias } : {})
+    });
+};
+export const inspectDockerWorldService = async (reference, spec, options) => {
+    try {
+        const result = await executeDockerWorldService({
+            args: ["--context", options.context, "container", "inspect", "--format",
+                spec.inspectionFormat, reference],
+            executor: options.executor,
+            signal: options.signal,
+            timeoutMs: options.timeoutMs
+        });
+        return parseExpectedDockerWorldService(result.stdout, spec) ?? fail();
+    }
+    catch (error) {
+        if (error instanceof DockerWorldServiceProviderError && error.kind === "not_found") {
+            return null;
+        }
+        throw error;
+    }
+};
+export const mutateDockerWorldService = async (args, options) => {
+    const result = await executeDockerWorldService({
+        args: ["--context", options.context, ...args],
+        executor: options.executor,
+        signal: options.signal,
+        timeoutMs: options.timeoutMs
+    });
+    if (result.stderr !== "")
+        return fail();
+    return result.stdout;
+};
+const activeWorldStatus = (status) => status === "running" || status === "paused" || status === "restarting";
+const exactWorldAck = (value, containerId) => value === `${containerId}\n`;
+const inspectedWorld = async (binding, spec, options) => {
+    const current = await inspectDockerWorldService(binding.container_id, spec, options);
+    if (current && current.containerId !== binding.container_id)
+        return fail();
+    return current;
+};
+export const removeExactDockerWorldService = async (rawBinding, options) => {
+    try {
+        if (!options || typeof options.context !== "string"
+            || !/^[a-z][a-z0-9_-]{0,63}$/u.test(options.context)
+            || typeof options.executor !== "function" || !Number.isSafeInteger(options.timeoutMs)
+            || options.timeoutMs < 1 || options.timeoutMs > 120_000)
+            return fail();
+        const binding = parseWorldServiceBinding(rawBinding);
+        const spec = worldServiceSpecForBinding(binding);
+        if (spec.resultHandle !== binding.world_service_handle)
+            return fail();
+        let current = await inspectedWorld(binding, spec, options);
+        if (current === null)
+            return;
+        if (current.status === "removing")
+            return fail();
+        if (activeWorldStatus(current.status)) {
+            let stopError;
+            let stopAck;
+            try {
+                stopAck = await mutateDockerWorldService(["container", "stop", "--timeout", "10", binding.container_id], options);
+            }
+            catch (error) {
+                stopError = error;
+            }
+            if (stopAck !== undefined && !exactWorldAck(stopAck, binding.container_id))
+                return fail();
+            current = await inspectedWorld(binding, spec, options);
+            if (current === null)
+                return;
+            if (activeWorldStatus(current.status) || current.status === "removing") {
+                if (stopError)
+                    throw stopError;
+                return fail();
+            }
+        }
+        let removeError;
+        let removeAck;
+        try {
+            removeAck = await mutateDockerWorldService(["container", "rm", binding.container_id], options);
+        }
+        catch (error) {
+            removeError = error;
+        }
+        if (removeAck !== undefined && !exactWorldAck(removeAck, binding.container_id))
+            return fail();
+        if (await inspectedWorld(binding, spec, options) !== null) {
+            if (removeError)
+                throw removeError;
+            return fail();
+        }
+    }
+    catch {
+        return fail();
+    }
+};
+export const createWorldServiceReceipt = async (input) => {
+    const raw = {
+        cleanup_state: "not_requested",
+        descriptor_digest: input.request.descriptor_digest,
+        export_state: "not_requested",
+        labels: Object.entries(input.labels).map(([key, value]) => ({ key, value })),
+        operation: input.request.operation,
+        operation_handle: input.claim.operationHandle,
+        receipt_digest: `sha256:${"0".repeat(64)}`,
+        request_digest: input.claim.requestDigest,
+        result_handle: input.resultHandle,
+        resulting_revision: (await input.journal.read()).revision + 1,
+        run_id: input.request.run_id,
+        selected_target: input.request.selected_target,
+        version: "spawnfile.target-resource.receipt.v1"
+    };
+    return { ...raw, receipt_digest: createTargetReceiptDigest(raw) };
+};

package/dist/target/dockerWorldServiceProvider.d.ts

@@ -0,0 +1,60 @@
+import { type OpaqueTargetHandle } from "./contracts.js";
+export declare const DOCKER_WORLD_SERVICE_ERROR = "Docker world-service lifecycle failed";
+export declare const WORLD_SECRETS_PATH: "/run/spawnfile-secrets";
+export declare const WORLD_RUNTIME_TMPFS: Readonly<{
+    path: "/tmp";
+    options: "rw,noexec,nosuid,nodev,size=1m,mode=1777";
+}>;
+export type DockerWorldServiceFailureKind = "collision" | "not_found";
+export interface DockerWorldServiceExecutor {
+    (file: string, args: string[], options: {
+        readonly signal?: AbortSignal;
+        readonly timeout: number;
+    }): Promise<{
+        readonly stderr: string;
+        readonly stdout: string;
+    }>;
+}
+export declare class DockerWorldServiceProviderError extends Error {
+    readonly kind: DockerWorldServiceFailureKind;
+    constructor(kind: DockerWorldServiceFailureKind);
+}
+export interface DockerWorldServiceSpec {
+    readonly containerName: string;
+    readonly createArgs: readonly string[];
+    readonly imageDigest: string;
+    readonly imageReference: string;
+    readonly evidenceMountPath: string;
+    readonly networkAlias?: string;
+    readonly inspectionFormat: string;
+    readonly receiptLabels: Readonly<Record<string, string>>;
+    readonly resultHandle: OpaqueTargetHandle;
+}
+export interface DockerWorldServiceInspection {
+    readonly containerId: string;
+    readonly networkId: string;
+    readonly status: "created" | "dead" | "exited" | "paused" | "removing" | "restarting" | "running";
+}
+export declare const createDockerWorldServiceSpec: (input: {
+    readonly operationHandle: unknown;
+    readonly requestDigest: unknown;
+    readonly runId: unknown;
+    readonly selectedTargetHandle: unknown;
+    readonly imageReference: unknown;
+    readonly imageDigest: unknown;
+    readonly dataNetwork: unknown;
+    readonly evidenceVolume: unknown;
+    readonly evidenceMountPath: unknown;
+    readonly secretBindings: unknown;
+    readonly networkAlias?: unknown;
+}) => DockerWorldServiceSpec;
+export declare const executeDockerWorldService: (input: {
+    readonly args: string[];
+    readonly executor: DockerWorldServiceExecutor;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs: number;
+}) => Promise<{
+    readonly stderr: string;
+    readonly stdout: string;
+}>;
+export declare const parseExpectedDockerWorldService: (stdout: string, spec: DockerWorldServiceSpec) => DockerWorldServiceInspection | null;