spawnfile 0.1.13 → 0.1.17

package/dist/target/organizationAttachmentStore.js

@@ -0,0 +1,316 @@
+import { Buffer } from "node:buffer";
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { chmod, link, lstat, mkdir, open, unlink } from "node:fs/promises";
+import path from "node:path";
+import { assertOrdinaryJsonGraph, parseOpaqueTargetHandle } from "./contracts.js";
+import { ORGANIZATION_ATTACHMENT_ERROR, createDockerOrganizationAttachmentSpec, parseOrganizationContainerId } from "./organizationAttachmentProvider.js";
+import { parseOrganizationAttachmentResolution } from "./organizationAttachmentAuthority.js";
+const RESOLUTION_VERSION = "spawnfile.target-organization-attachment.private-resolution.v1";
+const ATTACHMENT_VERSION = "spawnfile.target-organization-attachment.private-binding.v1";
+const MUTATION_ADMISSION_VERSION = "spawnfile.target-organization-attachment.private-mutation-admission.v1";
+const MAX_RECORD_BYTES = 32_768;
+const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/u;
+const NAME_PATTERN = /^spfn_[a-f0-9]{58}$/u;
+const fail = () => { throw new Error(ORGANIZATION_ATTACHMENT_ERROR); };
+const ordinary = (raw) => {
+    try {
+        assertOrdinaryJsonGraph(raw);
+    }
+    catch {
+        return fail();
+    }
+};
+const bytes = (value) => Buffer.byteLength(value, "utf8");
+const exactRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
+    && Object.getPrototypeOf(value) === Object.prototype;
+const exactKeys = (value, expected) => {
+    const actual = Object.keys(value).sort();
+    const sorted = [...expected].sort();
+    return actual.length === sorted.length
+        && actual.every((key, index) => key === sorted[index]);
+};
+const exactStringRecord = (raw) => {
+    if (!exactRecord(raw))
+        return fail();
+    for (const [key, value] of Object.entries(raw)) {
+        if (typeof value !== "string" || key.length < 1 || key.length > 128
+            || value.length < 1 || value.length > 128)
+            return fail();
+    }
+    return Object.freeze({ ...raw });
+};
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const key = (domain, value) => createHash("sha256")
+    .update(`spawnfile.target-organization-attachment.${domain}.v1\0`, "utf8")
+    .update(value, "utf8")
+    .digest("hex");
+export const createOrganizationAttachmentBinding = (input) => {
+    const resolution = parseOrganizationAttachmentResolution(input.resolution);
+    const networkId = parseOrganizationContainerId(input.networkId);
+    if (!DIGEST_PATTERN.test(input.dataNetworkRequestDigest))
+        return fail();
+    const expected = createDockerOrganizationAttachmentSpec({
+        containerId: resolution.network_attachment.container_id,
+        dataNetworkOperationHandle: input.dataNetworkOperationHandle,
+        dataNetworkRequestDigest: input.dataNetworkRequestDigest,
+        deploymentLabels: resolution.network_attachment.deployment_labels,
+        operationHandle: resolution.authorization.operation_handle,
+        organizationHandoffHandle: resolution.authorization.organization_handoff_handle,
+        requestDigest: resolution.authorization.request_digest,
+        runId: resolution.authorization.run_id,
+        selectedTargetHandle: resolution.authorization.selected_target.handle
+    });
+    if (!same(expected, input.spec))
+        return fail();
+    return Object.freeze({
+        attachment_handle: expected.resultHandle,
+        data_network: Object.freeze({
+            handle: expected.network.resultHandle,
+            id: networkId,
+            labels: expected.network.labels,
+            name: expected.network.name,
+            operation_handle: parseOpaqueTargetHandle(input.dataNetworkOperationHandle),
+            request_digest: input.dataNetworkRequestDigest
+        }),
+        receipt_labels: expected.receiptLabels,
+        resolution,
+        version: ATTACHMENT_VERSION
+    });
+};
+export const parseOrganizationAttachmentBinding = (raw) => {
+    ordinary(raw);
+    if (!exactRecord(raw) || !exactKeys(raw, [
+        "attachment_handle", "data_network", "receipt_labels", "resolution", "version"
+    ]) || raw.version !== ATTACHMENT_VERSION || !exactRecord(raw.data_network)
+        || !exactKeys(raw.data_network, [
+            "handle", "id", "labels", "name", "operation_handle", "request_digest"
+        ]) || typeof raw.data_network.name !== "string"
+        || !NAME_PATTERN.test(raw.data_network.name)
+        || typeof raw.data_network.request_digest !== "string"
+        || !DIGEST_PATTERN.test(raw.data_network.request_digest))
+        return fail();
+    const resolution = parseOrganizationAttachmentResolution(raw.resolution);
+    const spec = createDockerOrganizationAttachmentSpec({
+        containerId: resolution.network_attachment.container_id,
+        dataNetworkOperationHandle: parseOpaqueTargetHandle(raw.data_network.operation_handle),
+        dataNetworkRequestDigest: raw.data_network.request_digest,
+        deploymentLabels: resolution.network_attachment.deployment_labels,
+        operationHandle: resolution.authorization.operation_handle,
+        organizationHandoffHandle: resolution.authorization.organization_handoff_handle,
+        requestDigest: resolution.authorization.request_digest,
+        runId: resolution.authorization.run_id,
+        selectedTargetHandle: resolution.authorization.selected_target.handle
+    });
+    const networkLabels = exactStringRecord(raw.data_network.labels);
+    const receiptLabels = exactStringRecord(raw.receipt_labels);
+    if (raw.attachment_handle !== spec.resultHandle
+        || raw.data_network.handle !== spec.network.resultHandle
+        || raw.data_network.name !== spec.network.name
+        || !same(networkLabels, spec.network.labels)
+        || !same(receiptLabels, spec.receiptLabels))
+        return fail();
+    return Object.freeze({
+        attachment_handle: parseOpaqueTargetHandle(raw.attachment_handle),
+        data_network: Object.freeze({
+            handle: parseOpaqueTargetHandle(raw.data_network.handle),
+            id: parseOrganizationContainerId(raw.data_network.id),
+            labels: networkLabels,
+            name: raw.data_network.name,
+            operation_handle: parseOpaqueTargetHandle(raw.data_network.operation_handle),
+            request_digest: raw.data_network.request_digest
+        }),
+        receipt_labels: receiptLabels,
+        resolution,
+        version: ATTACHMENT_VERSION
+    });
+};
+export const createOrganizationAttachmentMutationAdmission = (input) => {
+    const binding = parseOrganizationAttachmentBinding(input.binding);
+    if (input.operation !== "attach_organization" && input.operation !== "detach_organization"
+        || !DIGEST_PATTERN.test(input.requestDigest))
+        return fail();
+    const operationHandle = parseOpaqueTargetHandle(input.operationHandle);
+    if (input.operation === "attach_organization"
+        && (operationHandle !== binding.resolution.authorization.operation_handle
+            || input.requestDigest !== binding.resolution.authorization.request_digest))
+        return fail();
+    return Object.freeze({
+        attachment_handle: binding.attachment_handle,
+        container_id: binding.resolution.network_attachment.container_id,
+        data_network_id: binding.data_network.id,
+        operation: input.operation,
+        operation_handle: operationHandle,
+        request_digest: input.requestDigest,
+        version: MUTATION_ADMISSION_VERSION
+    });
+};
+const parseMutationAdmission = (raw) => {
+    ordinary(raw);
+    if (!exactRecord(raw) || !exactKeys(raw, [
+        "attachment_handle", "container_id", "data_network_id", "operation",
+        "operation_handle", "request_digest", "version"
+    ]) || raw.version !== MUTATION_ADMISSION_VERSION
+        || raw.operation !== "attach_organization" && raw.operation !== "detach_organization"
+        || typeof raw.request_digest !== "string" || !DIGEST_PATTERN.test(raw.request_digest)) {
+        return fail();
+    }
+    return Object.freeze({
+        attachment_handle: parseOpaqueTargetHandle(raw.attachment_handle),
+        container_id: parseOrganizationContainerId(raw.container_id),
+        data_network_id: parseOrganizationContainerId(raw.data_network_id),
+        operation: raw.operation,
+        operation_handle: parseOpaqueTargetHandle(raw.operation_handle),
+        request_digest: raw.request_digest,
+        version: MUTATION_ADMISSION_VERSION
+    });
+};
+const checkRoot = async (raw) => {
+    if (typeof raw !== "string" || raw.length < 1 || bytes(raw) > 4_096)
+        return fail();
+    const root = path.resolve(raw);
+    const parsed = path.parse(root);
+    let current = parsed.root;
+    for (const part of root.slice(parsed.root.length).split(path.sep).filter(Boolean)) {
+        current = path.join(current, part);
+        let stats;
+        try {
+            stats = await lstat(current);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                return fail();
+            await mkdir(current, { mode: 0o700 }).catch((mkdirError) => {
+                if (mkdirError.code !== "EEXIST")
+                    return fail();
+            });
+            stats = await lstat(current).catch(fail);
+        }
+        if (!stats.isDirectory() || stats.isSymbolicLink())
+            return fail();
+    }
+    await chmod(root, 0o700).catch(fail);
+    return root;
+};
+const readPrivate = async (filePath) => {
+    let stats;
+    try {
+        stats = await lstat(filePath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        return fail();
+    }
+    if (!stats.isFile() || stats.isSymbolicLink() || stats.size > MAX_RECORD_BYTES
+        || (stats.mode & 0o077) !== 0)
+        return fail();
+    let handle;
+    try {
+        handle = await open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch {
+        return fail();
+    }
+    try {
+        const current = await handle.stat();
+        if (!current.isFile() || current.size > MAX_RECORD_BYTES || (current.mode & 0o077) !== 0)
+            return fail();
+        return await handle.readFile({ encoding: "utf8" });
+    }
+    catch {
+        return fail();
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+};
+const syncDirectory = async (directory) => {
+    const handle = await open(directory, constants.O_RDONLY);
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+};
+const createImmutable = async (root, fileName, content) => {
+    if (bytes(content) > MAX_RECORD_BYTES)
+        return fail();
+    const finalPath = path.join(root, fileName);
+    const existing = await readPrivate(finalPath);
+    if (existing !== null) {
+        if (existing !== content)
+            return fail();
+        return;
+    }
+    const temporaryPath = path.join(root, `.${fileName}.${process.pid}.${randomUUID()}.tmp`);
+    let handle;
+    try {
+        handle = await open(temporaryPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+        await handle.chmod(0o600);
+        await handle.writeFile(content, "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        try {
+            await link(temporaryPath, finalPath);
+            await syncDirectory(root);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+    }
+    finally {
+        if (handle)
+            await handle.close().catch(() => undefined);
+        await unlink(temporaryPath).catch((error) => {
+            if (error.code !== "ENOENT")
+                throw error;
+        });
+        await syncDirectory(root);
+    }
+    if (await readPrivate(finalPath) !== content)
+        return fail();
+};
+class FileOrganizationAttachmentAuthorityStore {
+    #root;
+    constructor(root) { this.#root = root; }
+    async bindResolution(raw) {
+        const resolution = parseOrganizationAttachmentResolution(raw);
+        const content = JSON.stringify({ resolution, version: RESOLUTION_VERSION });
+        const fileName = `${key("resolution", resolution.authorization.organization_handoff_handle)}.resolution.json`;
+        await createImmutable(this.#root, fileName, content);
+    }
+    async bindAttachment(raw) {
+        const binding = parseOrganizationAttachmentBinding(raw);
+        const fileName = `${key("binding", binding.attachment_handle)}.attachment.json`;
+        await createImmutable(this.#root, fileName, JSON.stringify(binding));
+    }
+    async bindMutationAdmission(raw) {
+        const admission = parseMutationAdmission(raw);
+        const fileName = `${key("mutation-admission", admission.operation_handle)}.admission.json`;
+        await createImmutable(this.#root, fileName, JSON.stringify(admission));
+    }
+    async loadAttachment(handle) {
+        const parsed = parseOpaqueTargetHandle(handle);
+        const fileName = `${key("binding", parsed)}.attachment.json`;
+        const content = await readPrivate(path.join(this.#root, fileName));
+        if (content === null)
+            return fail();
+        try {
+            return parseOrganizationAttachmentBinding(JSON.parse(content));
+        }
+        catch {
+            return fail();
+        }
+    }
+    async requireMutationAdmission(raw) {
+        const admission = parseMutationAdmission(raw);
+        const fileName = `${key("mutation-admission", admission.operation_handle)}.admission.json`;
+        if (await readPrivate(path.join(this.#root, fileName)) !== JSON.stringify(admission))
+            return fail();
+    }
+}
+export const initializeOrganizationAttachmentAuthorityStore = async (root) => new FileOrganizationAttachmentAuthorityStore(await checkRoot(root));

package/dist/target/publicArtifactSnapshot.d.ts

@@ -0,0 +1,72 @@
+import { z } from "zod";
+export declare const TARGET_PUBLIC_ARTIFACT_SNAPSHOT_REQUEST_VERSION: "spawnfile.target-public-artifact-snapshot.request.v1";
+export declare const TARGET_PUBLIC_ARTIFACT_SNAPSHOT_VERSION: "spawnfile.target-public-artifact-snapshot.v1";
+export declare const TARGET_PUBLIC_ARTIFACT_SNAPSHOT_NOT_PRESENT_VERSION: "spawnfile.target-public-artifact-snapshot.not-present.v1";
+export declare const TARGET_PUBLIC_ARTIFACT_ROOT: "/tmp/spawnfile-public";
+export declare const MAX_TARGET_PUBLIC_ARTIFACT_BYTES = 131072;
+export declare const isTargetPublicArtifactPath: (value: unknown) => value is string;
+export declare const targetPublicArtifactSnapshotRequestSchema: z.ZodObject<{
+    artifact: z.ZodObject<{
+        id: z.ZodString;
+        max_bytes: z.ZodNumber;
+        media_type: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strict>;
+    descriptor_digest: z.ZodString;
+    run_id: z.ZodPipe<z.ZodString, z.ZodTransform<import("./contracts.js").RunId, string>>;
+    selected_target: z.ZodObject<{
+        fingerprint: z.ZodString;
+        handle: z.ZodPipe<z.ZodString, z.ZodTransform<import("./contracts.js").OpaqueTargetHandle, string>>;
+    }, z.core.$strict>;
+    version: z.ZodLiteral<"spawnfile.target-public-artifact-snapshot.request.v1">;
+    world_service_handle: z.ZodPipe<z.ZodString, z.ZodTransform<import("./contracts.js").OpaqueTargetHandle, string>>;
+}, z.core.$strict>;
+export declare const targetPublicArtifactSnapshotSchema: z.ZodObject<{
+    artifact_id: z.ZodString;
+    content_base64: z.ZodString;
+    content_digest: z.ZodString;
+    media_type: z.ZodString;
+    request_digest: z.ZodString;
+    run_id: z.ZodPipe<z.ZodString, z.ZodTransform<import("./contracts.js").RunId, string>>;
+    size_bytes: z.ZodNumber;
+    version: z.ZodLiteral<"spawnfile.target-public-artifact-snapshot.v1">;
+}, z.core.$strict>;
+export declare const targetPublicArtifactSnapshotNotPresentSchema: z.ZodObject<{
+    artifact_id: z.ZodString;
+    request_digest: z.ZodString;
+    run_id: z.ZodPipe<z.ZodString, z.ZodTransform<import("./contracts.js").RunId, string>>;
+    status: z.ZodLiteral<"not_present">;
+    version: z.ZodLiteral<"spawnfile.target-public-artifact-snapshot.not-present.v1">;
+}, z.core.$strict>;
+export declare const targetPublicArtifactSnapshotResultSchema: z.ZodUnion<readonly [z.ZodObject<{
+    artifact_id: z.ZodString;
+    content_base64: z.ZodString;
+    content_digest: z.ZodString;
+    media_type: z.ZodString;
+    request_digest: z.ZodString;
+    run_id: z.ZodPipe<z.ZodString, z.ZodTransform<import("./contracts.js").RunId, string>>;
+    size_bytes: z.ZodNumber;
+    version: z.ZodLiteral<"spawnfile.target-public-artifact-snapshot.v1">;
+}, z.core.$strict>, z.ZodObject<{
+    artifact_id: z.ZodString;
+    request_digest: z.ZodString;
+    run_id: z.ZodPipe<z.ZodString, z.ZodTransform<import("./contracts.js").RunId, string>>;
+    status: z.ZodLiteral<"not_present">;
+    version: z.ZodLiteral<"spawnfile.target-public-artifact-snapshot.not-present.v1">;
+}, z.core.$strict>]>;
+export type TargetPublicArtifactSnapshotRequest = z.infer<typeof targetPublicArtifactSnapshotRequestSchema>;
+export type TargetPublicArtifactSnapshot = z.infer<typeof targetPublicArtifactSnapshotSchema>;
+export type TargetPublicArtifactSnapshotNotPresent = z.infer<typeof targetPublicArtifactSnapshotNotPresentSchema>;
+export type TargetPublicArtifactSnapshotResult = z.infer<typeof targetPublicArtifactSnapshotResultSchema>;
+export declare const parseTargetPublicArtifactSnapshotRequest: (raw: unknown) => TargetPublicArtifactSnapshotRequest;
+export declare const parseTargetPublicArtifactSnapshot: (raw: unknown) => TargetPublicArtifactSnapshot;
+export declare const parseTargetPublicArtifactSnapshotNotPresent: (raw: unknown) => TargetPublicArtifactSnapshotNotPresent;
+export declare const parseTargetPublicArtifactSnapshotResult: (raw: unknown) => TargetPublicArtifactSnapshotResult;
+export declare const createTargetPublicArtifactSnapshotRequestDigest: (raw: unknown) => `sha256:${string}`;
+export declare const createTargetPublicArtifactSnapshot: (input: {
+    readonly content: Uint8Array;
+    readonly request: TargetPublicArtifactSnapshotRequest;
+}) => TargetPublicArtifactSnapshot;
+export declare const createTargetPublicArtifactSnapshotNotPresent: (raw: unknown) => TargetPublicArtifactSnapshotNotPresent;
+export declare const createCanonicalTargetPublicArtifactSnapshotBytes: (raw: unknown) => string;
+export declare const createCanonicalTargetPublicArtifactSnapshotResultBytes: (raw: unknown) => string;

package/dist/target/publicArtifactSnapshot.js

@@ -0,0 +1,184 @@
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+import { types as nodeTypes } from "node:util";
+import { z } from "zod";
+import { assertOrdinaryJsonGraph, opaqueTargetHandleSchema, runIdSchema, selectedTargetSchema } from "./contracts.js";
+export const TARGET_PUBLIC_ARTIFACT_SNAPSHOT_REQUEST_VERSION = "spawnfile.target-public-artifact-snapshot.request.v1";
+export const TARGET_PUBLIC_ARTIFACT_SNAPSHOT_VERSION = "spawnfile.target-public-artifact-snapshot.v1";
+export const TARGET_PUBLIC_ARTIFACT_SNAPSHOT_NOT_PRESENT_VERSION = "spawnfile.target-public-artifact-snapshot.not-present.v1";
+export const TARGET_PUBLIC_ARTIFACT_ROOT = "/tmp/spawnfile-public";
+export const MAX_TARGET_PUBLIC_ARTIFACT_BYTES = 131_072;
+const digestSchema = z.string().regex(/^sha256:[0-9a-f]{64}$/u);
+const identifierSchema = z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/u);
+const mediaTypeSchema = z.string()
+    .max(127)
+    .regex(/^[a-z][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/u);
+const PUBLIC_ARTIFACT_PATH = /^\/tmp\/spawnfile-public\/[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+const publicPathSchema = z.string().max(255)
+    // This is intentionally a direct child of the isolated public tmpfs.  A
+    // nested path would require a recursive openat-style resolver to keep every
+    // parent below the mount while an untrusted world is writing its output.
+    .regex(PUBLIC_ARTIFACT_PATH);
+export const isTargetPublicArtifactPath = (value) => typeof value === "string" && value.length <= 255 && PUBLIC_ARTIFACT_PATH.test(value);
+export const targetPublicArtifactSnapshotRequestSchema = z.object({
+    artifact: z.object({
+        id: identifierSchema,
+        max_bytes: z.number().int().min(1).max(MAX_TARGET_PUBLIC_ARTIFACT_BYTES),
+        media_type: mediaTypeSchema,
+        path: publicPathSchema
+    }).strict(),
+    descriptor_digest: digestSchema,
+    run_id: runIdSchema,
+    selected_target: selectedTargetSchema,
+    version: z.literal(TARGET_PUBLIC_ARTIFACT_SNAPSHOT_REQUEST_VERSION),
+    world_service_handle: opaqueTargetHandleSchema
+}).strict();
+export const targetPublicArtifactSnapshotSchema = z.object({
+    artifact_id: identifierSchema,
+    content_base64: z.string().max(Math.ceil(MAX_TARGET_PUBLIC_ARTIFACT_BYTES / 3) * 4),
+    content_digest: digestSchema,
+    media_type: mediaTypeSchema,
+    request_digest: digestSchema,
+    run_id: runIdSchema,
+    size_bytes: z.number().int().min(0).max(MAX_TARGET_PUBLIC_ARTIFACT_BYTES),
+    version: z.literal(TARGET_PUBLIC_ARTIFACT_SNAPSHOT_VERSION)
+}).strict().superRefine((value, context) => {
+    let bytes;
+    try {
+        bytes = Buffer.from(value.content_base64, "base64");
+    }
+    catch {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "invalid base64 content" });
+        return;
+    }
+    if (bytes.toString("base64") !== value.content_base64
+        || bytes.byteLength !== value.size_bytes
+        || `sha256:${createHash("sha256").update(bytes).digest("hex")}` !== value.content_digest) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "artifact content mismatch" });
+    }
+});
+export const targetPublicArtifactSnapshotNotPresentSchema = z.object({
+    artifact_id: identifierSchema,
+    request_digest: digestSchema,
+    run_id: runIdSchema,
+    status: z.literal("not_present"),
+    version: z.literal(TARGET_PUBLIC_ARTIFACT_SNAPSHOT_NOT_PRESENT_VERSION)
+}).strict();
+export const targetPublicArtifactSnapshotResultSchema = z.union([
+    targetPublicArtifactSnapshotSchema,
+    targetPublicArtifactSnapshotNotPresentSchema
+]);
+const canonicalJsonValue = (value) => {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJsonValue).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        const record = value;
+        return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJsonValue(record[key])}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+};
+const canonicalJson = (value) => {
+    assertOrdinaryJsonGraph(value);
+    return canonicalJsonValue(value);
+};
+/*
+ * Public artifact snapshots are deliberately one flat envelope.  Their base64
+ * payload can be larger than the generic JSON graph's aggregate 64 KiB string
+ * allowance, so admit that one field without relaxing the shared graph guard.
+ * Descriptor inspection happens before Zod is allowed to read any property.
+ */
+const assertOrdinaryPublicArtifactSnapshot = (raw) => {
+    try {
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw)
+            || nodeTypes.isProxy(raw))
+            throw new Error();
+        const prototype = Object.getPrototypeOf(raw);
+        if (prototype !== Object.prototype && prototype !== null)
+            throw new Error();
+        const keys = Reflect.ownKeys(raw);
+        if (keys.length > 8)
+            throw new Error();
+        let ordinaryStringBytes = 0;
+        for (const key of keys) {
+            if (typeof key !== "string")
+                throw new Error();
+            const descriptor = Object.getOwnPropertyDescriptor(raw, key);
+            if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) {
+                throw new Error();
+            }
+            ordinaryStringBytes += Buffer.byteLength(key, "utf8");
+            const value = descriptor.value;
+            if (typeof value === "string") {
+                if (key === "content_base64") {
+                    if (Buffer.byteLength(value, "utf8")
+                        > Math.ceil(MAX_TARGET_PUBLIC_ARTIFACT_BYTES / 3) * 4)
+                        throw new Error();
+                }
+                else {
+                    ordinaryStringBytes += Buffer.byteLength(value, "utf8");
+                }
+            }
+            else if (typeof value === "number") {
+                if (!Number.isFinite(value))
+                    throw new Error();
+            }
+            else if (value !== null && typeof value !== "boolean") {
+                throw new Error();
+            }
+        }
+        if (ordinaryStringBytes > 65_536)
+            throw new Error();
+    }
+    catch {
+        throw new TypeError("invalid JSON-like graph");
+    }
+};
+export const parseTargetPublicArtifactSnapshotRequest = (raw) => {
+    assertOrdinaryJsonGraph(raw);
+    return targetPublicArtifactSnapshotRequestSchema.parse(raw);
+};
+export const parseTargetPublicArtifactSnapshot = (raw) => {
+    assertOrdinaryPublicArtifactSnapshot(raw);
+    return targetPublicArtifactSnapshotSchema.parse(raw);
+};
+export const parseTargetPublicArtifactSnapshotNotPresent = (raw) => {
+    assertOrdinaryPublicArtifactSnapshot(raw);
+    return targetPublicArtifactSnapshotNotPresentSchema.parse(raw);
+};
+export const parseTargetPublicArtifactSnapshotResult = (raw) => {
+    assertOrdinaryPublicArtifactSnapshot(raw);
+    return targetPublicArtifactSnapshotResultSchema.parse(raw);
+};
+export const createTargetPublicArtifactSnapshotRequestDigest = (raw) => `sha256:${createHash("sha256")
+    .update("spawnfile.target-public-artifact-snapshot.request.v1\0", "utf8")
+    .update(canonicalJson(parseTargetPublicArtifactSnapshotRequest(raw)), "utf8")
+    .digest("hex")}`;
+export const createTargetPublicArtifactSnapshot = (input) => {
+    const request = parseTargetPublicArtifactSnapshotRequest(input.request);
+    const bytes = Buffer.from(input.content);
+    if (bytes.byteLength > request.artifact.max_bytes) {
+        throw new TypeError("Public artifact exceeds its declared bound");
+    }
+    return parseTargetPublicArtifactSnapshot({
+        artifact_id: request.artifact.id,
+        content_base64: bytes.toString("base64"),
+        content_digest: `sha256:${createHash("sha256").update(bytes).digest("hex")}`,
+        media_type: request.artifact.media_type,
+        request_digest: createTargetPublicArtifactSnapshotRequestDigest(request),
+        run_id: request.run_id,
+        size_bytes: bytes.byteLength,
+        version: TARGET_PUBLIC_ARTIFACT_SNAPSHOT_VERSION
+    });
+};
+export const createTargetPublicArtifactSnapshotNotPresent = (raw) => {
+    const request = parseTargetPublicArtifactSnapshotRequest(raw);
+    return parseTargetPublicArtifactSnapshotNotPresent({
+        artifact_id: request.artifact.id,
+        request_digest: createTargetPublicArtifactSnapshotRequestDigest(request),
+        run_id: request.run_id,
+        status: "not_present",
+        version: TARGET_PUBLIC_ARTIFACT_SNAPSHOT_NOT_PRESENT_VERSION
+    });
+};
+export const createCanonicalTargetPublicArtifactSnapshotBytes = (raw) => canonicalJsonValue(parseTargetPublicArtifactSnapshot(raw));
+export const createCanonicalTargetPublicArtifactSnapshotResultBytes = (raw) => canonicalJsonValue(parseTargetPublicArtifactSnapshotResult(raw));

package/dist/target/topologyActivation.d.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { type TargetTopologyReceipt } from "./contracts.js";
+import { type DockerWorldServiceExecutor } from "./dockerWorldServiceProvider.js";
+import type { WorldServiceBinding } from "./dockerWorldServiceStore.js";
+export declare const WORLD_SERVICE_ACTIVATION_VERSION: "spawnfile.world-service-activation.v1";
+export declare const TARGET_TOPOLOGY_ACTIVATION_RECEIPT_VERSION: "spawnfile.target-topology-activation-receipt.v1";
+export declare const WORLD_SERVICE_ACTIVATION_RELATIVE_PATH: ".spawnfile/world-service-activated.v1";
+declare const markerSchema: z.ZodObject<{
+    bundle_digest: z.ZodString;
+    run_id: z.ZodString;
+    state: z.ZodLiteral<"activated">;
+    topology_receipt_digest: z.ZodString;
+    topology_request_digest: z.ZodString;
+    version: z.ZodLiteral<"spawnfile.world-service-activation.v1">;
+}, z.core.$strict>;
+declare const receiptSchema: z.ZodObject<{
+    activation_digest: z.ZodString;
+    bundle_digest: z.ZodString;
+    receipt_digest: z.ZodString;
+    run_id: z.ZodString;
+    state: z.ZodLiteral<"activated">;
+    topology_receipt_digest: z.ZodString;
+    topology_request_digest: z.ZodString;
+    version: z.ZodLiteral<"spawnfile.target-topology-activation-receipt.v1">;
+}, z.core.$strict>;
+export type WorldServiceActivation = z.infer<typeof markerSchema>;
+export type TargetTopologyActivationReceipt = z.infer<typeof receiptSchema>;
+export interface TargetTopologyActivationResult {
+    readonly receipt: TargetTopologyActivationReceipt;
+    readonly receiptBytes: string;
+}
+export declare const parseWorldServiceActivation: (raw: unknown) => WorldServiceActivation;
+export declare const parseTargetTopologyActivationReceipt: (raw: unknown) => TargetTopologyActivationReceipt;
+export declare const createCanonicalWorldServiceActivationBytes: (raw: unknown) => string;
+export declare const createCanonicalTargetTopologyActivationReceiptBytes: (raw: unknown) => string;
+export declare const createWorldServiceActivationDigest: (raw: unknown) => string;
+export declare const createTargetTopologyActivationReceiptDigest: (raw: unknown) => string;
+/**
+ * Publishes the owner-only lifecycle release through the service's existing
+ * evidence mount. Docker copies exact canonical bytes; no provider traffic or
+ * agent-reachable endpoint participates in activation.
+ */
+export declare const activateDockerWorldService: (input: {
+    readonly executor: DockerWorldServiceExecutor;
+    readonly signal?: AbortSignal;
+    readonly target: readonly string[];
+    readonly timeoutMs: number;
+    readonly topology: TargetTopologyReceipt;
+    readonly world: WorldServiceBinding;
+}) => Promise<TargetTopologyActivationResult>;
+export {};