spawnfile 0.1.13 → 0.1.17

package/dist/compiler/updateProjectSurfaces.js

@@ -1,25 +1,20 @@
 import path from "node:path";
-import { getCanonicalManifestPath, getManifestPath, getProjectRoot, writeUtf8File } from "../filesystem/index.js";
-import { loadManifest, renderSpawnfile } from "../manifest/index.js";
+import { getManifestPath, writeUtf8File } from "../filesystem/index.js";
+import { isReferencedMember, loadManifest, materializeInlineAgentManifest, renderSpawnfile } from "../manifest/index.js";
 import { assertSurfaceMutationAllowed, removeSurface, updateSurfaceAccess, upsertSurface, validateAgentSurfaceSupport } from "./surfaceDefinitions.js";
+import { collectProjectManifestPaths, createInlineAgentSource, rewriteInlineAgentMembers } from "./projectManifestGraph.js";
 const resolveTargetManifestPath = (inputPath) => getManifestPath(path.resolve(inputPath ?? process.cwd()));
-const collectManifestPaths = async (manifestPath, recursive, visited = new Set()) => {
-    const canonicalPath = getCanonicalManifestPath(manifestPath);
-    if (visited.has(canonicalPath)) {
-        return [];
+const manifestChanged = (current, next) => JSON.stringify(current) !== JSON.stringify(next);
+const mutateAgentDeclarations = (manifest, manifestPath, recursive, mutate) => {
+    if (manifest.kind === "agent") {
+        return mutate(manifest, manifestPath);
     }
-    visited.add(canonicalPath);
     if (!recursive) {
-        return [canonicalPath];
+        assertSurfaceMutationAllowed(manifest, recursive);
+        return null;
     }
-    const loadedManifest = await loadManifest(canonicalPath);
-    const childRefs = loadedManifest.manifest.kind === "team"
-        ? loadedManifest.manifest.members.map((member) => member.ref)
-        : (loadedManifest.manifest.subagents ?? []).map((subagent) => subagent.ref);
-    const nestedPaths = await Promise.all(childRefs.map((ref) => collectManifestPaths(getManifestPath(path.resolve(getProjectRoot(canonicalPath), ref)), true, visited)));
-    return [canonicalPath, ...nestedPaths.flat()];
+    return rewriteInlineAgentMembers(manifest, (member) => mutate(member, createInlineAgentSource(manifestPath, member.id)) ?? member);
 };
-const manifestChanged = (current, next) => JSON.stringify(current) !== JSON.stringify(next);
 const rewriteTouchedManifests = async (manifestPaths, mutate) => {
     const rewrites = [];
     for (const manifestPath of manifestPaths) {
@@ -31,6 +26,13 @@ const rewriteTouchedManifests = async (manifestPaths, mutate) => {
         if (nextManifest.kind === "agent") {
             validateAgentSurfaceSupport(nextManifest);
         }
+        else {
+            for (const member of nextManifest.members) {
+                if (!isReferencedMember(member)) {
+                    validateAgentSurfaceSupport(materializeInlineAgentManifest(nextManifest, member));
+                }
+            }
+        }
         rewrites.push({
             manifest: nextManifest,
             manifestPath
@@ -46,53 +48,57 @@ const rewriteTouchedManifests = async (manifestPaths, mutate) => {
 export { resolvePortableSurfaceName } from "./surfaceDefinitions.js";
 export const addProjectSurface = async (options) => {
     const recursive = options.recursive ?? false;
-    const manifestPaths = await collectManifestPaths(resolveTargetManifestPath(options.path), recursive);
-    return rewriteTouchedManifests(manifestPaths, (manifest) => {
-        if (!assertSurfaceMutationAllowed(manifest, recursive)) {
-            return null;
-        }
-        return {
-            ...manifest,
-            surfaces: upsertSurface(manifest.surfaces, options)
-        };
+    const manifestPaths = await collectProjectManifestPaths(resolveTargetManifestPath(options.path), recursive);
+    return rewriteTouchedManifests(manifestPaths, (manifest, manifestPath) => {
+        return mutateAgentDeclarations(manifest, manifestPath, recursive, (declaration) => ({
+            ...declaration,
+            surfaces: upsertSurface(declaration.surfaces, options)
+        }));
     });
 };
 export const setProjectSurfaceAccess = async (options) => {
     const recursive = options.recursive ?? false;
-    const manifestPaths = await collectManifestPaths(resolveTargetManifestPath(options.path), recursive);
+    const manifestPaths = await collectProjectManifestPaths(resolveTargetManifestPath(options.path), recursive);
     return rewriteTouchedManifests(manifestPaths, (manifest, manifestPath) => {
-        if (!assertSurfaceMutationAllowed(manifest, recursive)) {
-            return null;
-        }
-        const nextSurfaces = updateSurfaceAccess(manifest.surfaces, options, manifestPath, recursive);
-        if (!nextSurfaces) {
-            return null;
-        }
-        return {
-            ...manifest,
-            surfaces: nextSurfaces
-        };
+        return mutateAgentDeclarations(manifest, manifestPath, recursive, (declaration, source) => {
+            const nextSurfaces = updateSurfaceAccess(declaration.surfaces, options, source, recursive);
+            if (!nextSurfaces) {
+                return null;
+            }
+            return {
+                ...declaration,
+                surfaces: nextSurfaces
+            };
+        });
     });
 };
 export const removeProjectSurface = async (options) => {
     const recursive = options.recursive ?? false;
-    const manifestPaths = await collectManifestPaths(resolveTargetManifestPath(options.path), recursive);
-    return rewriteTouchedManifests(manifestPaths, (manifest) => {
-        if (!assertSurfaceMutationAllowed(manifest, recursive)) {
-            return null;
-        }
-        return {
-            ...manifest,
-            surfaces: removeSurface(manifest.surfaces, options.surface)
-        };
+    const manifestPaths = await collectProjectManifestPaths(resolveTargetManifestPath(options.path), recursive);
+    return rewriteTouchedManifests(manifestPaths, (manifest, manifestPath) => {
+        return mutateAgentDeclarations(manifest, manifestPath, recursive, (declaration) => ({
+            ...declaration,
+            surfaces: removeSurface(declaration.surfaces, options.surface)
+        }));
     });
 };
 export const showProjectSurfaces = async (options = {}) => {
-    const manifestPaths = await collectManifestPaths(resolveTargetManifestPath(options.path), options.recursive ?? false);
+    const manifestPaths = await collectProjectManifestPaths(resolveTargetManifestPath(options.path), options.recursive ?? false);
     const entries = [];
     for (const manifestPath of manifestPaths) {
         const loadedManifest = await loadManifest(manifestPath);
-        if (options.recursive && loadedManifest.manifest.kind !== "agent") {
+        if (options.recursive && loadedManifest.manifest.kind === "team") {
+            for (const member of loadedManifest.manifest.members) {
+                if (isReferencedMember(member)) {
+                    continue;
+                }
+                entries.push({
+                    kind: "agent",
+                    manifestPath: createInlineAgentSource(manifestPath, member.id),
+                    name: member.id,
+                    surfaces: member.surfaces
+                });
+            }
             continue;
         }
         entries.push({

package/dist/compiler/view/types.d.ts

@@ -10,7 +10,7 @@ export interface OrganizationViewSkillSummary {
 }
 export interface OrganizationViewResourceSummary {
     id: string;
-    kind: "git" | "volume";
+    kind: "bundle" | "git" | "volume";
     mode: "mutable" | "readonly";
     mount: string;
     sharing: "per_agent" | "team";

package/dist/compiler/workspaceBundleArtifacts.d.ts

@@ -0,0 +1,3 @@
+import type { CompilePlan } from "./types.js";
+export declare const validateWorkspaceBundleTar: (bytes: Buffer) => void;
+export declare const stageWorkspaceBundles: (outputDirectory: string, plan: CompilePlan) => Promise<boolean>;

package/dist/compiler/workspaceBundleArtifacts.js

@@ -0,0 +1,106 @@
+import { createHash } from "node:crypto";
+import { copyFile, mkdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { SpawnfileError } from "../shared/index.js";
+// Sanity bound for an operator-declared local tar; integrity comes from its digest, not its size.
+const CAP = 536_870_912, BLOCK = 512;
+// Sanity bound on an operator-declared local tar; integrity comes from the declared digest.
+const MAX_WORKSPACE_BUNDLE_ENTRIES = 65_536;
+const fail = (message = "Workspace bundle contains an invalid or unsafe tar entry") => { throw new SpawnfileError("validation_error", message); };
+const textField = (field) => { const nul = field.indexOf(0); return field.subarray(0, nul < 0 ? field.length : nul).toString("utf8"); };
+const octal = (field, allowEmpty = false) => {
+    const value = field.toString("ascii").replace(/\0.*$/u, "").trim();
+    if (value === "" && allowEmpty)
+        return 0;
+    if (!/^[0-7]+$/u.test(value))
+        fail();
+    const parsed = Number.parseInt(value, 8);
+    if (!Number.isSafeInteger(parsed) || parsed < 0)
+        fail();
+    return parsed;
+};
+const validPath = (value, directory) => {
+    const name = directory && value.endsWith("/") ? value.slice(0, -1) : value;
+    if (!name || name.startsWith("/") || name.includes("\\") || name.includes("\0"))
+        fail();
+    const parts = name.split("/");
+    if (parts.some((part) => !part || part === "." || part === ".."))
+        fail();
+    return parts.join("/");
+};
+const validChecksum = (header) => {
+    const expected = octal(header.subarray(148, 156));
+    let actual = 0;
+    for (let index = 0; index < BLOCK; index += 1)
+        actual += index >= 148 && index < 156 ? 32 : header[index];
+    return actual === expected;
+};
+export const validateWorkspaceBundleTar = (bytes) => {
+    if (bytes.length < BLOCK * 2 || bytes.length % BLOCK !== 0)
+        fail("Workspace bundle is truncated or lacks exact ustar termination");
+    let offset = 0, entries = 0, terminated = false;
+    const names = new Set();
+    while (offset + BLOCK <= bytes.length) {
+        const header = bytes.subarray(offset, offset + BLOCK);
+        if (header.every((byte) => byte === 0)) {
+            if (offset + BLOCK * 2 > bytes.length || !bytes.subarray(offset, offset + BLOCK * 2).every((byte) => byte === 0) || !bytes.subarray(offset + BLOCK * 2).every((byte) => byte === 0))
+                fail("Workspace bundle has invalid termination or trailing bytes");
+            terminated = true;
+            break;
+        }
+        if (textField(header.subarray(257, 263)) !== "ustar" || !validChecksum(header))
+            fail();
+        for (const [start, end, empty] of [[100, 108, false], [108, 116, true], [116, 124, true], [124, 136, false], [136, 148, true], [329, 337, true], [337, 345, true]])
+            octal(header.subarray(start, end), empty);
+        const type = header[156] === 0 ? "0" : String.fromCharCode(header[156]);
+        if (type !== "0" && type !== "5")
+            fail();
+        const size = octal(header.subarray(124, 136));
+        if (type === "5" && size !== 0)
+            fail();
+        const prefix = textField(header.subarray(345, 500)), rawName = textField(header.subarray(0, 100));
+        const effective = validPath(prefix ? `${prefix}/${rawName}` : rawName, type === "5");
+        if (names.has(effective))
+            fail("Workspace bundle contains duplicate effective paths");
+        names.add(effective);
+        offset += BLOCK + Math.ceil(size / BLOCK) * BLOCK;
+        entries += 1;
+        if (offset > bytes.length)
+            fail("Workspace bundle is truncated or exceeds entry bounds");
+        if (entries > MAX_WORKSPACE_BUNDLE_ENTRIES)
+            fail("Workspace bundle exceeds the maximum entry count");
+    }
+    if (!terminated)
+        fail("Workspace bundle is truncated or lacks exact ustar termination");
+    if (entries === 0)
+        fail("Workspace bundle is empty");
+};
+export const stageWorkspaceBundles = async (outputDirectory, plan) => {
+    const bundles = new Map();
+    for (const node of plan.nodes)
+        if (node.kind === "agent")
+            for (const resource of node.value.workspaceResources ?? []) {
+                if (resource.kind !== "bundle")
+                    continue;
+                const source = path.resolve(path.dirname(resource.scope.key), resource.source), prior = bundles.get(resource.sha256);
+                if (prior && prior !== source)
+                    throw new SpawnfileError("validation_error", "Workspace bundle digest maps to multiple sources");
+                bundles.set(resource.sha256, source);
+            }
+    if (bundles.size === 0)
+        return false;
+    const destination = path.join(outputDirectory, "container/workspace-bundles");
+    await mkdir(destination, { recursive: true });
+    for (const [identity, source] of bundles) {
+        const info = await stat(source);
+        if (!info.isFile() || info.size < 1 || info.size > CAP)
+            throw new SpawnfileError("validation_error", "Workspace bundle must be a bounded regular tar file");
+        const bytes = await readFile(source);
+        const actual = `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+        if (actual !== identity)
+            throw new SpawnfileError("validation_error", "Workspace bundle checksum mismatch");
+        validateWorkspaceBundleTar(bytes);
+        await copyFile(source, path.join(destination, `${identity.slice(7)}.tar`));
+    }
+    return true;
+};

package/dist/compiler/workspaceResources.d.ts

@@ -10,16 +10,19 @@ export type ResolvedWorkspaceResource = TeamWorkspaceResource & {
     sharing: WorkspaceResourceSharing;
 };
 export interface WorkspaceResourcePlan {
+    archivePath?: string;
     backingPath: string;
     branch?: string;
     id: string;
-    kind: "git" | "volume";
+    kind: "bundle" | "git" | "volume";
     linkPath: string;
     mode: "mutable" | "readonly";
     mount: string;
     name?: string;
     ref?: string;
     sharing: WorkspaceResourceSharing;
+    sha256?: string;
+    source?: string;
     tag?: string;
     url?: string;
 }

package/dist/compiler/workspaceResources.js

@@ -14,6 +14,8 @@ const normalizeMount = (value) => {
     return collapsed.length > 1 ? collapsed.replace(/\/+$/u, "") : "/";
 };
 const normalizeResourceIdentity = (resource) => {
+    if (resource.kind === "bundle")
+        return JSON.stringify({ kind: resource.kind, mode: resource.mode, mount: normalizeMount(resource.mount), sha256: resource.sha256, source: resource.source, sharing: resource.sharing });
     if (resource.kind === "git") {
         return JSON.stringify({
             branch: resource.branch?.trim() ?? "",
@@ -39,12 +41,9 @@ const mountsOverlap = (left, right) => left === right ||
     left.startsWith(`${right}/`) ||
     right.startsWith(`${left}/`);
 const resolveSharing = (resource) => resource.sharing ?? "per_agent";
-const toResolvedResource = (resource, scope) => ({
-    ...resource,
-    mount: normalizeMount(resource.mount),
-    scope,
-    sharing: resolveSharing(resource)
-});
+const toResolvedResource = (resource, scope) => resource.kind === "bundle"
+    ? { ...resource, mount: normalizeMount(resource.mount), scope, sharing: "per_agent" }
+    : { ...resource, mount: normalizeMount(resource.mount), scope, sharing: resolveSharing(resource) };
 const createPathSegment = (value) => {
     const slug = slugify(value);
     const hash = createShortHash(value);
@@ -103,7 +102,13 @@ export const toWorkspaceResourcePlan = (resource, context) => resource.kind ===
         ...(resource.tag ? { tag: resource.tag } : {}),
         url: resource.url
     }
-    : {
+    : resource.kind === "bundle" ? {
+        archivePath: `/opt/spawnfile/workspace-bundles/${resource.sha256.slice(7)}.tar`,
+        backingPath: resolveBackingPath(resource, context.targetId), id: resource.id, kind: "bundle",
+        linkPath: resolveLinkPath(normalizeMount(resource.mount), context.workspacePath), mode: resource.mode,
+        mount: normalizeMount(resource.mount), sharing: resource.sharing, sha256: resource.sha256,
+        source: path.resolve(path.dirname(resource.scope.key), resource.source)
+    } : {
         backingPath: resolveBackingPath(resource, context.targetId),
         id: resource.id,
         kind: "volume",

package/dist/compiler/worldBindings.d.ts

@@ -0,0 +1,39 @@
+import type { CompilePlan } from "./types.js";
+export declare const SIMFILE_WORLD_BINDINGS_VERSION: "simfile.world-bindings.v1";
+export declare const WORLD_BINDINGS_OUTPUT_FILE = "world-bindings.json";
+export interface SimfileWorldBindingV1 {
+    readonly member: {
+        readonly id: string;
+        readonly principal_id: string;
+    };
+    readonly run_id: string;
+    readonly world_instance_id: string;
+    readonly capability_manifest_digest: string;
+    readonly token_env: string;
+    readonly json: {
+        readonly auth: "bearer";
+        readonly url: string;
+    };
+    readonly mcp: {
+        readonly auth: "bearer";
+        readonly transport: "streamable_http";
+        readonly url: string;
+    };
+}
+export interface SimfileWorldBindingsV1 {
+    readonly schema: typeof SIMFILE_WORLD_BINDINGS_VERSION;
+    readonly bindings: readonly SimfileWorldBindingV1[];
+}
+export interface ResolvedWorldBindingAssignment {
+    readonly binding: SimfileWorldBindingV1;
+    readonly nodeId: string;
+}
+export interface ResolvedWorldBindings {
+    readonly artifact: SimfileWorldBindingsV1;
+    readonly assignments: readonly ResolvedWorldBindingAssignment[];
+    readonly canonicalBytes: string;
+}
+export declare const parseSimfileWorldBindings: (raw: unknown) => SimfileWorldBindingsV1;
+export declare const renderSimfileWorldBindings: (artifact: SimfileWorldBindingsV1) => string;
+export declare const resolveWorldBindings: (plan: CompilePlan, raw: unknown) => ResolvedWorldBindings;
+export declare const findWorldBindingForNode: (resolved: ResolvedWorldBindings | undefined, nodeId: string) => SimfileWorldBindingV1 | undefined;

package/dist/compiler/worldBindings.js

@@ -0,0 +1,247 @@
+import { Buffer } from "node:buffer";
+import { types as nodeTypes } from "node:util";
+import { SpawnfileError } from "../shared/index.js";
+import { MAX_ORGANIZATION_AGENT_MEMBERS, MAX_ORGANIZATION_MEMBER_ID_BYTES, ORGANIZATION_MEMBER_ID_PATTERN_SOURCE, resolveCanonicalAgentMemberId } from "./organizationIdentity.js";
+export const SIMFILE_WORLD_BINDINGS_VERSION = "simfile.world-bindings.v1";
+export const WORLD_BINDINGS_OUTPUT_FILE = "world-bindings.json";
+const MEMBER_ID = new RegExp(ORGANIZATION_MEMBER_ID_PATTERN_SOURCE, "u");
+const BINDING_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const ENV_NAME = /^[A-Z_][A-Z0-9_]{0,127}$/u;
+const MAX_ENDPOINT_BYTES = 2_048;
+const MAX_HOSTILE_DEPTH = 16;
+const MAX_HOSTILE_NODES = 2_048;
+const fail = (message) => {
+    throw new SpawnfileError("validation_error", `invalid ${SIMFILE_WORLD_BINDINGS_VERSION}: ${message}`);
+};
+const compareAscii = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const rejectUnsafeGraph = (value, state = { nodes: 0, seen: new WeakSet() }, depth = 0) => {
+    if (value === null || typeof value !== "object")
+        return;
+    if (nodeTypes.isProxy(value))
+        fail("proxy values are not allowed");
+    if (depth > MAX_HOSTILE_DEPTH)
+        fail(`object depth exceeds ${MAX_HOSTILE_DEPTH}`);
+    state.nodes += 1;
+    if (state.nodes > MAX_HOSTILE_NODES)
+        fail(`object node count exceeds ${MAX_HOSTILE_NODES}`);
+    if (state.seen.has(value))
+        fail("aliases and cycles are not allowed");
+    state.seen.add(value);
+    if (Array.isArray(value)) {
+        if (Object.getPrototypeOf(value) !== Array.prototype)
+            fail("array prototype is not canonical");
+        const length = Object.getOwnPropertyDescriptor(value, "length");
+        if (!length || !("value" in length) || !Number.isSafeInteger(length.value)) {
+            return fail("array length is unsafe");
+        }
+        const count = length.value;
+        if (count > MAX_ORGANIZATION_AGENT_MEMBERS)
+            fail("binding cardinality exceeds organization limit");
+        const keys = Reflect.ownKeys(value);
+        if (keys.length !== count + 1 || keys.some((key) => key !== "length" && (typeof key !== "string" || !/^(?:0|[1-9][0-9]*)$/u.test(key)))) {
+            fail("array contains extended properties");
+        }
+        for (let index = 0; index < count; index += 1) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+            if (!descriptor?.enumerable || !("value" in descriptor)) {
+                return fail("sparse or accessor array");
+            }
+            rejectUnsafeGraph(descriptor.value, state, depth + 1);
+        }
+        return;
+    }
+    const keys = Reflect.ownKeys(value);
+    if (keys.length > 32)
+        fail("object property count exceeds 32");
+    for (const key of keys) {
+        if (typeof key !== "string")
+            fail("symbol properties are not allowed");
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor?.enumerable || !("value" in descriptor)) {
+            return fail("accessor or non-enumerable property");
+        }
+        rejectUnsafeGraph(descriptor.value, state, depth + 1);
+    }
+};
+const exactObject = (value, fields, label) => {
+    if (value === null || typeof value !== "object" || Array.isArray(value)
+        || Object.getPrototypeOf(value) !== Object.prototype) {
+        return fail(`${label} must be a plain object`);
+    }
+    const keys = Object.getOwnPropertyNames(value);
+    if (keys.length !== fields.length || Object.keys(value).length !== fields.length
+        || keys.some((key) => !fields.includes(key))
+        || fields.some((field) => !Object.hasOwn(value, field))) {
+        return fail(`${label} keys must be ${fields.join(",")}`);
+    }
+    return value;
+};
+const exactArray = (value, label) => {
+    if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype) {
+        return fail(`${label} must be a plain array`);
+    }
+    return value;
+};
+const boundedId = (value, label) => {
+    if (typeof value !== "string" || !BINDING_ID.test(value)
+        || Buffer.byteLength(value, "ascii") > 128) {
+        return fail(`${label} is invalid`);
+    }
+    return value;
+};
+const canonicalEndpoint = (value, label) => {
+    if (typeof value !== "string" || value.length === 0
+        || Buffer.byteLength(value, "utf8") > MAX_ENDPOINT_BYTES) {
+        return fail(`${label} endpoint is invalid`);
+    }
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        return fail(`${label} endpoint is invalid`);
+    }
+    if ((parsed.protocol !== "http:" && parsed.protocol !== "https:")
+        || parsed.username !== "" || parsed.password !== ""
+        || parsed.search !== "" || parsed.hash !== "" || parsed.hostname === ""
+        || value.includes("?") || value.includes("#")
+        || parsed.href !== value || parsed.pathname.endsWith("/")) {
+        return fail(`${label} endpoint must be a canonical credential-free http(s) URL`);
+    }
+    if (label === "json" && !parsed.pathname.endsWith("/v1/world")) {
+        return fail("json endpoint must end with /v1/world");
+    }
+    return value;
+};
+const parseBinding = (value, index) => {
+    const entry = exactObject(value, [
+        "member",
+        "run_id",
+        "world_instance_id",
+        "capability_manifest_digest",
+        "token_env",
+        "json",
+        "mcp"
+    ], `bindings[${index}]`);
+    const member = exactObject(entry.member, ["id", "principal_id"], `bindings[${index}].member`);
+    const memberId = typeof member.id === "string" ? member.id : "";
+    if (!MEMBER_ID.test(memberId)
+        || Buffer.byteLength(memberId, "ascii") > MAX_ORGANIZATION_MEMBER_ID_BYTES
+        || member.principal_id !== `agent:${memberId}`) {
+        return fail(`bindings[${index}] member identity is invalid`);
+    }
+    const digest = entry.capability_manifest_digest;
+    if (typeof digest !== "string" || !DIGEST.test(digest)) {
+        return fail(`bindings[${index}] capability manifest digest is invalid`);
+    }
+    const tokenEnv = entry.token_env;
+    if (typeof tokenEnv !== "string" || !ENV_NAME.test(tokenEnv)) {
+        return fail(`bindings[${index}] token env is invalid`);
+    }
+    const json = exactObject(entry.json, ["auth", "url"], `bindings[${index}].json`);
+    const mcp = exactObject(entry.mcp, ["auth", "transport", "url"], `bindings[${index}].mcp`);
+    if (json.auth !== "bearer" || mcp.auth !== "bearer" || mcp.transport !== "streamable_http") {
+        return fail(`bindings[${index}] endpoint authentication is invalid`);
+    }
+    return {
+        member: { id: memberId, principal_id: member.principal_id },
+        run_id: boundedId(entry.run_id, `bindings[${index}].run_id`),
+        world_instance_id: boundedId(entry.world_instance_id, `bindings[${index}].world_instance_id`),
+        capability_manifest_digest: digest,
+        token_env: tokenEnv,
+        json: { auth: "bearer", url: canonicalEndpoint(json.url, "json") },
+        mcp: { auth: "bearer", transport: "streamable_http", url: canonicalEndpoint(mcp.url, "mcp") }
+    };
+};
+const freezeCopy = (value) => {
+    const copy = structuredClone(value);
+    const freeze = (current) => {
+        if (current === null || typeof current !== "object" || Object.isFrozen(current))
+            return;
+        Object.freeze(current);
+        for (const child of Object.values(current))
+            freeze(child);
+    };
+    freeze(copy);
+    return copy;
+};
+export const parseSimfileWorldBindings = (raw) => {
+    rejectUnsafeGraph(raw);
+    const root = exactObject(raw, ["schema", "bindings"], "root");
+    if (root.schema !== SIMFILE_WORLD_BINDINGS_VERSION)
+        fail("schema is invalid");
+    const input = exactArray(root.bindings, "bindings");
+    if (input.length === 0 || input.length > MAX_ORGANIZATION_AGENT_MEMBERS) {
+        fail("bindings must contain 1 to 128 entries");
+    }
+    const bindings = input.map((entry, index) => parseBinding(entry, index));
+    const members = new Set();
+    const principals = new Set();
+    const tokenEnvs = new Set();
+    const first = bindings[0];
+    for (const binding of bindings) {
+        if (members.has(binding.member.id) || principals.has(binding.member.principal_id)
+            || tokenEnvs.has(binding.token_env)) {
+            fail("bindings contain a duplicate member, principal, or token env");
+        }
+        if (binding.run_id !== first.run_id || binding.world_instance_id !== first.world_instance_id) {
+            fail("bindings must share one run and world instance");
+        }
+        members.add(binding.member.id);
+        principals.add(binding.member.principal_id);
+        tokenEnvs.add(binding.token_env);
+    }
+    bindings.sort((left, right) => compareAscii(left.member.principal_id, right.member.principal_id)
+        || compareAscii(left.member.id, right.member.id));
+    return freezeCopy({ schema: SIMFILE_WORLD_BINDINGS_VERSION, bindings });
+};
+export const renderSimfileWorldBindings = (artifact) => `${JSON.stringify(parseSimfileWorldBindings(artifact), null, 2)}\n`;
+export const resolveWorldBindings = (plan, raw) => {
+    const artifact = parseSimfileWorldBindings(raw);
+    const identity = plan.organizationIdentity;
+    if (!identity)
+        return fail("organization identity is required");
+    const authorityByMember = new Map(identity.agentMembers.map((member) => [member.memberId, member]));
+    const nodeByMember = new Map();
+    for (const node of plan.nodes) {
+        if (node.kind !== "agent")
+            continue;
+        const memberId = resolveCanonicalAgentMemberId(plan, node.value.source);
+        if (memberId === undefined)
+            continue;
+        const authority = authorityByMember.get(memberId);
+        if (!authority || authority.principalId !== `agent:${memberId}` || nodeByMember.has(memberId)) {
+            fail(`organization identity does not resolve exactly once for ${memberId}`);
+        }
+        nodeByMember.set(memberId, node.id);
+    }
+    if (nodeByMember.size !== identity.agentMembers.length
+        || artifact.bindings.length !== identity.agentMembers.length) {
+        fail("binding and organization cardinality do not match");
+    }
+    const assignments = artifact.bindings.map((binding) => {
+        const authority = authorityByMember.get(binding.member.id);
+        const nodeId = nodeByMember.get(binding.member.id);
+        if (!authority || authority.principalId !== binding.member.principal_id || !nodeId) {
+            return fail(`binding does not join organization member ${binding.member.id}`);
+        }
+        return { binding: freezeCopy(binding), nodeId };
+    });
+    if (new Set(assignments.map((assignment) => assignment.nodeId)).size !== assignments.length) {
+        fail("binding assignments contain a duplicate node");
+    }
+    return freezeCopy({
+        artifact,
+        assignments,
+        canonicalBytes: renderSimfileWorldBindings(artifact)
+    });
+};
+export const findWorldBindingForNode = (resolved, nodeId) => {
+    if (!resolved)
+        return undefined;
+    const matches = resolved.assignments.filter((assignment) => assignment.nodeId === nodeId);
+    if (matches.length > 1)
+        fail(`node ${nodeId} has duplicate binding assignments`);
+    return matches[0]?.binding;
+};

package/dist/compiler/worldBindingsFile.d.ts

@@ -0,0 +1,5 @@
+import type { CompilePlan } from "./types.js";
+import { type ResolvedWorldBindings } from "./worldBindings.js";
+export declare const MAX_WORLD_BINDINGS_FILE_BYTES = 1048576;
+export declare const readSimfileWorldBindingsFile: (inputPath: string) => Promise<unknown>;
+export declare const loadWorldBindingsForCompile: (plan: CompilePlan, inputPath: string, expectedRunId: string | undefined) => Promise<ResolvedWorldBindings>;