spawnfile 0.1.12 → 0.1.14

package/dist/compiler/containerPackageRender.js

@@ -0,0 +1,63 @@
+import { SpawnfileError } from "../shared/index.js";
+export const createPackageInstallCommand = (packages) => `RUN apt-get update && apt-get install -y --no-install-recommends ${packages.join(" ")} && rm -rf /var/lib/apt/lists/*`;
+export const createNpmPackageInstallCommand = (packages) => `RUN npm install -g --omit=dev --no-fund --no-audit ${packages.join(" ")}`;
+export const createPipxPackageInstallCommand = (packages) => `RUN PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install ${packages.join(" ")}`;
+const packageIdentity = (pkg) => `${pkg.manager}\u0000${pkg.name}\u0000${pkg.version ?? ""}\u0000${pkg.scope ?? ""}`;
+const packageConflictIdentity = (pkg) => `${pkg.manager}\u0000${pkg.name}`;
+const dedupePackages = (packages) => {
+    const seen = new Map();
+    for (const currentPackage of packages) {
+        seen.set(packageIdentity(currentPackage), currentPackage);
+    }
+    return [...seen.values()].sort((left, right) => packageIdentity(left).localeCompare(packageIdentity(right)));
+};
+const assertImagePackageCompatibility = (packages) => {
+    const byName = new Map();
+    for (const currentPackage of packages) {
+        const conflictIdentity = packageConflictIdentity(currentPackage);
+        const existingPackage = byName.get(conflictIdentity);
+        if (!existingPackage) {
+            byName.set(conflictIdentity, currentPackage);
+            continue;
+        }
+        if (packageIdentity(existingPackage) !== packageIdentity(currentPackage)) {
+            throw new SpawnfileError("validation_error", `Generated container declares conflicting package definitions for ${currentPackage.manager} package ${currentPackage.name}`);
+        }
+    }
+};
+export const createAptPackageInstallItem = (pkg) => pkg.version ? `${pkg.name}=${pkg.version}` : pkg.name;
+export const createNpmPackageInstallItem = (pkg) => pkg.version ? `${pkg.name}@${pkg.version}` : pkg.name;
+export const createPipxPackageInstallItem = (pkg) => pkg.version ? `${pkg.name}==${pkg.version}` : pkg.name;
+export const getNpmInstallItemName = (item) => {
+    if (!item.startsWith("@")) {
+        const versionMarker = item.indexOf("@");
+        return versionMarker === -1 ? item : item.slice(0, versionMarker);
+    }
+    const slashIndex = item.indexOf("/");
+    if (slashIndex === -1) {
+        return item;
+    }
+    const versionMarker = item.indexOf("@", slashIndex);
+    return versionMarker === -1 ? item : item.slice(0, versionMarker);
+};
+export const collectPackagesByManager = (runtimePlans) => {
+    const packagesByManager = {
+        apt: [],
+        npm: [],
+        pipx: []
+    };
+    const imagePackages = runtimePlans.flatMap((plan) => plan.packages ?? []);
+    assertImagePackageCompatibility(imagePackages);
+    for (const packageConfig of dedupePackages(imagePackages)) {
+        if (packageConfig.manager === "apt") {
+            packagesByManager.apt.push(packageConfig);
+            continue;
+        }
+        if (packageConfig.manager === "npm") {
+            packagesByManager.npm.push(packageConfig);
+            continue;
+        }
+        packagesByManager.pipx.push(packageConfig);
+    }
+    return packagesByManager;
+};

package/dist/compiler/containerTargetPlanResolution.d.ts

@@ -0,0 +1,20 @@
+import type { ModelAuthMethod } from "../shared/index.js";
+import type { ContainerTarget, ContainerTargetInput, EmittedFile, RuntimeContainerMeta } from "../runtime/index.js";
+import type { ResolvedPackage } from "./types.js";
+export declare const createDefaultTargets: (inputs: ContainerTargetInput[]) => ContainerTarget[];
+export declare const resolveTargetEnvFiles: (configPath: string, target: ContainerTarget) => Array<{
+    envName: string;
+    filePath: string;
+}>;
+export declare const resolveTargetConfigEnvBindings: (meta: RuntimeContainerMeta, target: ContainerTarget) => RuntimeContainerMeta["configEnvBindings"];
+export declare const assertTargetHasConfig: (runtimeName: string, targetId: string, meta: RuntimeContainerMeta, files: EmittedFile[]) => void;
+export declare const resolveTargetPackages: (target: ContainerTarget, inputs: ContainerTargetInput[]) => ResolvedPackage[];
+export declare const resolveInstancePaths: (runtimeName: string, targetId: string, meta: RuntimeContainerMeta) => {
+    configPath: string;
+    homePath?: string;
+    instanceRoot: string;
+    workspacePath: string;
+};
+export declare const resolveTargetModelSecrets: (target: ContainerTarget, inputs: ContainerTargetInput[]) => string[];
+export declare const resolveTargetModelAuthMethods: (target: ContainerTarget, inputs: ContainerTargetInput[]) => Record<string, ModelAuthMethod>;
+export declare const resolveTargetExposure: (target: ContainerTarget, inputs: ContainerTargetInput[]) => boolean;

package/dist/compiler/containerTargetPlanResolution.js

@@ -0,0 +1,97 @@
+import path from "node:path";
+import { SpawnfileError } from "../shared/index.js";
+import { listExecutionModelSecretNames, resolveExecutionModelAuthMethods } from "./modelEnv.js";
+const CONFIG_FILE_PLACEHOLDER = "<config-file>";
+const INSTANCE_ROOT_PLACEHOLDER = "<instance-root>";
+export const createDefaultTargets = (inputs) => inputs.map((input) => ({
+    files: input.emittedFiles,
+    id: `${input.kind}-${input.slug}`,
+    sourceIds: [input.id]
+}));
+export const resolveTargetEnvFiles = (configPath, target) => (target.envFiles ?? []).map((binding) => ({
+    envName: binding.envName,
+    filePath: path.posix.join(path.posix.dirname(configPath), binding.relativePath)
+}));
+export const resolveTargetConfigEnvBindings = (meta, target) => [...(meta.configEnvBindings ?? []), ...(target.configEnvBindings ?? [])];
+export const assertTargetHasConfig = (runtimeName, targetId, meta, files) => {
+    if (!files.some((file) => file.path === meta.configFileName)) {
+        throw new SpawnfileError("runtime_error", `Container target ${targetId} for ${runtimeName} is missing ${meta.configFileName}`);
+    }
+};
+const createPackageIdentity = (pkg) => `${pkg.manager}\u0000${pkg.name}\u0000${pkg.version ?? ""}\u0000${pkg.scope ?? ""}`;
+const createPackageConflictIdentity = (pkg) => `${pkg.manager}\u0000${pkg.name}`;
+const createPackageLabel = (pkg) => `${pkg.manager} package ${pkg.name}`;
+export const resolveTargetPackages = (target, inputs) => {
+    const sourceIds = new Set(target.sourceIds ?? []);
+    if (sourceIds.size === 0)
+        return [];
+    const byIdentity = new Map();
+    for (const input of inputs) {
+        if (!sourceIds.has(input.id) || input.value.kind !== "agent")
+            continue;
+        for (const currentPackage of input.value.packages ?? []) {
+            const conflictIdentity = createPackageConflictIdentity(currentPackage);
+            const existingPackage = byIdentity.get(conflictIdentity);
+            if (!existingPackage) {
+                byIdentity.set(conflictIdentity, currentPackage);
+                continue;
+            }
+            if (createPackageIdentity(existingPackage) !== createPackageIdentity(currentPackage)) {
+                throw new SpawnfileError("validation_error", `Container target ${target.id} declares conflicting package definitions for ${createPackageLabel(currentPackage)}`);
+            }
+        }
+    }
+    return [...byIdentity.values()].sort((left, right) => createPackageIdentity(left).localeCompare(createPackageIdentity(right)));
+};
+const replaceContainerPathTemplate = (template, instanceRoot, configFileName) => template
+    .replaceAll(INSTANCE_ROOT_PLACEHOLDER, instanceRoot)
+    .replaceAll(CONFIG_FILE_PLACEHOLDER, configFileName);
+export const resolveInstancePaths = (runtimeName, targetId, meta) => {
+    const instanceRoot = `/var/lib/spawnfile/instances/${runtimeName}/${targetId}`;
+    return {
+        configPath: replaceContainerPathTemplate(meta.instancePaths.configPathTemplate, instanceRoot, meta.configFileName),
+        homePath: meta.instancePaths.homePathTemplate
+            ? replaceContainerPathTemplate(meta.instancePaths.homePathTemplate, instanceRoot, meta.configFileName)
+            : undefined,
+        instanceRoot,
+        workspacePath: replaceContainerPathTemplate(meta.instancePaths.workspacePathTemplate, instanceRoot, meta.configFileName)
+    };
+};
+export const resolveTargetModelSecrets = (target, inputs) => {
+    const sourceIds = new Set(target.sourceIds ?? []);
+    if (sourceIds.size === 0)
+        return [];
+    const secretNames = new Set();
+    for (const input of inputs) {
+        if (!sourceIds.has(input.id) || input.value.kind !== "agent")
+            continue;
+        for (const secretName of listExecutionModelSecretNames(input.value.execution)) {
+            secretNames.add(secretName);
+        }
+    }
+    return [...secretNames].sort();
+};
+export const resolveTargetModelAuthMethods = (target, inputs) => {
+    const sourceIds = new Set(target.sourceIds ?? []);
+    if (sourceIds.size === 0)
+        return {};
+    const methods = new Map();
+    for (const input of inputs) {
+        if (!sourceIds.has(input.id) || input.value.kind !== "agent")
+            continue;
+        for (const [provider, method] of Object.entries(resolveExecutionModelAuthMethods(input.value.execution))) {
+            const existingMethod = methods.get(provider);
+            if (existingMethod && existingMethod !== method) {
+                throw new SpawnfileError("validation_error", `Container target ${target.id} declares conflicting auth methods for provider ${provider}`);
+            }
+            methods.set(provider, method);
+        }
+    }
+    return Object.fromEntries([...methods.entries()].sort(([left], [right]) => left.localeCompare(right)));
+};
+export const resolveTargetExposure = (target, inputs) => {
+    const sourceIds = new Set(target.sourceIds ?? []);
+    if (sourceIds.size === 0)
+        return false;
+    return inputs.some((input) => sourceIds.has(input.id) && input.value.kind === "agent" && input.value.expose === true);
+};

package/dist/compiler/containerTargetResources.js

@@ -4,13 +4,15 @@ import { mergeWorkspaceResourcePlans } from "./workspaceResources.js";
 const CONFIG_FILE_PLACEHOLDER = "<config-file>";
 const INSTANCE_ROOT_PLACEHOLDER = "<instance-root>";
 const SOURCE_AGENT_PLACEHOLDER = "<agent-name>";
+const SOURCE_SLUG_PLACEHOLDER = "<source-slug>";
 const replaceSourceWorkspacePathTemplate = (template, input, instancePaths, meta) => {
     const agentName = input.value.kind === "agent" ? input.value.name : input.slug;
     const instanceRoot = instancePaths.instanceRoot ?? path.posix.dirname(instancePaths.workspacePath);
     return template
         .replaceAll(INSTANCE_ROOT_PLACEHOLDER, instanceRoot)
         .replaceAll(CONFIG_FILE_PLACEHOLDER, meta.configFileName)
-        .replaceAll(SOURCE_AGENT_PLACEHOLDER, agentName);
+        .replaceAll(SOURCE_AGENT_PLACEHOLDER, agentName)
+        .replaceAll(SOURCE_SLUG_PLACEHOLDER, input.slug);
 };
 const resolveSourceWorkspacePath = (input, instancePaths, meta) => meta.instancePaths.sourceWorkspacePathTemplate
     ? replaceSourceWorkspacePathTemplate(meta.instancePaths.sourceWorkspacePathTemplate, input, instancePaths, meta)

package/dist/compiler/daimonTelemetryArtifacts.d.ts

@@ -0,0 +1,22 @@
+import type { ContainerPersistentMountReport } from "../report/index.js";
+import type { CompiledNodeArtifact, RuntimeTargetPlan } from "./containerArtifactsTypes.js";
+import type { CompilePlan } from "./types.js";
+export interface DaimonTelemetryArtifactBundle {
+    /** One durable volume per pi/daimon agent, mounted onto its telemetry directory. */
+    mounts: ContainerPersistentMountReport[];
+    /** Runtime target plan id (e.g. "pi-app") -> { node id -> telemetry persistent mount id
+     * }, so `containerArtifacts.ts` can stamp `runtime_instances[].telemetry_mount_ids` and
+     * `artifactsExportPlan.ts`'s `planDaimonFiles` can resolve each agent's telemetry volume
+     * without re-deriving container paths of its own. */
+    telemetryMountIdsByInstance: Map<string, Record<string, string>>;
+}
+/**
+ * Registers one run-scoped durable volume per pi/daimon agent for its daimon turn/wake
+ * causal telemetry directory (`<instanceRoot>/runtime/agents/<slug>/telemetry` — the parent
+ * of `causal.jsonl`, see `appCoreSource.ts`'s `runtimeHomePath`/`instanceRoot`), mirroring
+ * exactly how `moltnetArtifacts.ts` mounts the Moltnet causal directory (Piece 4b,
+ * Decision 21: daimon inner-truth telemetry was container-local — `docker cp` only — until
+ * now). Daimon's own write path is untouched: this only makes the HOST side of that same
+ * directory a named volume, so `docker rm` no longer discards it.
+ */
+export declare const createDaimonTelemetryArtifacts: (plan: CompilePlan, runtimePlans: RuntimeTargetPlan[], compiledNodes: CompiledNodeArtifact[]) => DaimonTelemetryArtifactBundle;

package/dist/compiler/daimonTelemetryArtifacts.js

@@ -0,0 +1,61 @@
+import path from "node:path/posix";
+import { resolveNoopolisRunId } from "../runtime/index.js";
+import { createPersistentVolumeName } from "./moltnetArtifactPaths.js";
+/** Runtime names whose generated app is `src/runtime/pi/appCoreSource.ts` (the pi harness
+ * and its `daimonAdapter` alias — see `src/runtime/pi/adapter.ts`'s
+ * `export const daimonAdapter: RuntimeAdapter = { ...piAdapter, name: "daimon" }`, which
+ * shares `piAdapter.container`/`createContainerTargets` byte-for-byte). Both write daimon
+ * turn/wake causal telemetry the same way, under `runtimeHomePath` (appCoreSource.ts:189),
+ * so both need the telemetry mount, not just the literal "pi" runtime name. */
+const DAIMON_TELEMETRY_RUNTIME_NAMES = new Set(["daimon", "pi"]);
+const createTelemetryMountId = (agentSlug) => `agent-${agentSlug}-daimon-telemetry`;
+/**
+ * Registers one run-scoped durable volume per pi/daimon agent for its daimon turn/wake
+ * causal telemetry directory (`<instanceRoot>/runtime/agents/<slug>/telemetry` — the parent
+ * of `causal.jsonl`, see `appCoreSource.ts`'s `runtimeHomePath`/`instanceRoot`), mirroring
+ * exactly how `moltnetArtifacts.ts` mounts the Moltnet causal directory (Piece 4b,
+ * Decision 21: daimon inner-truth telemetry was container-local — `docker cp` only — until
+ * now). Daimon's own write path is untouched: this only makes the HOST side of that same
+ * directory a named volume, so `docker rm` no longer discards it.
+ */
+export const createDaimonTelemetryArtifacts = (plan, runtimePlans, compiledNodes) => {
+    // Same run-scoping key as every other durable mount (see
+    // moltnetArtifactPaths.ts's createPersistentVolumeName doc comment): present for
+    // `spawnfile run`/`up` (which always call ensureNoopolisRunId() first), absent for a
+    // bare `spawnfile compile`/`build`, keeping those byte-identical to before this module
+    // existed.
+    const runId = resolveNoopolisRunId(process.env);
+    const agentSlugByNodeId = new Map(compiledNodes
+        .filter((node) => node.kind === "agent" && Boolean(node.id))
+        .map((node) => [node.id, node.slug]));
+    const mounts = [];
+    const telemetryMountIdsByInstance = new Map();
+    for (const runtimePlan of runtimePlans) {
+        if (!DAIMON_TELEMETRY_RUNTIME_NAMES.has(runtimePlan.runtimeName) || !runtimePlan.instancePaths.homePath) {
+            continue;
+        }
+        const instanceRoot = runtimePlan.instancePaths.instanceRoot ?? path.dirname(runtimePlan.instancePaths.homePath);
+        const mountIdsByNodeId = {};
+        for (const nodeId of runtimePlan.sourceIds ?? []) {
+            const agentSlug = agentSlugByNodeId.get(nodeId);
+            if (!agentSlug) {
+                continue;
+            }
+            const mountId = createTelemetryMountId(agentSlug);
+            mounts.push({
+                id: mountId,
+                mount_path: path.join(instanceRoot, "runtime", "agents", agentSlug, "telemetry"),
+                reason: `daimon turn/wake causal telemetry for ${agentSlug}`,
+                volume_name: createPersistentVolumeName(plan.root, mountId, undefined, runId)
+            });
+            mountIdsByNodeId[nodeId] = mountId;
+        }
+        if (Object.keys(mountIdsByNodeId).length > 0) {
+            telemetryMountIdsByInstance.set(runtimePlan.id, mountIdsByNodeId);
+        }
+    }
+    return {
+        mounts: mounts.sort((left, right) => left.id.localeCompare(right.id)),
+        telemetryMountIdsByInstance
+    };
+};

package/dist/compiler/dockerBuildContext.d.ts

@@ -0,0 +1,16 @@
+export declare const DOCKER_BUILD_CONTEXT_IGNORE_PATTERNS: readonly ["runtimes/", "spawnfile-report.json", "deployments/"];
+export interface DockerBuildContextFile {
+    mode: number;
+    path: string;
+    size: number;
+}
+export interface DockerBuildContextIgnoreViolation {
+    pattern: string;
+    source: string;
+}
+export declare const matchesDockerBuildIgnorePattern: (relativePath: string, pattern: string) => boolean;
+export declare const createDockerIgnoreContent: () => string;
+export declare const listDockerBuildContextFiles: (directory: string) => Promise<DockerBuildContextFile[]>;
+export declare const createDockerBuildContextDigest: (directory: string) => Promise<string>;
+export declare const extractDockerBuildContextSources: (dockerfile: string) => string[];
+export declare const findIgnoredDockerBuildSources: (dockerfile: string, patterns?: readonly string[]) => DockerBuildContextIgnoreViolation[];

package/dist/compiler/dockerBuildContext.js

@@ -0,0 +1,159 @@
+import { createHash } from "node:crypto";
+import { readFile, readdir, stat } from "node:fs/promises";
+import path from "node:path";
+export const DOCKER_BUILD_CONTEXT_IGNORE_PATTERNS = Object.freeze([
+    "runtimes/",
+    "spawnfile-report.json",
+    "deployments/"
+]);
+const compareBytes = (left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right));
+const normalizeContextPath = (relativePath) => relativePath.replaceAll(path.sep, "/").replace(/^\.\/+/u, "");
+const normalizeContextPathForContainment = (relativePath) => {
+    const normalized = path.posix.normalize(normalizeContextPath(relativePath));
+    return normalized === "." ? "" : normalized.replace(/\/+$/u, "");
+};
+export const matchesDockerBuildIgnorePattern = (relativePath, pattern) => {
+    const normalizedPath = normalizeContextPath(relativePath).replace(/\/+$/u, "");
+    const normalizedPattern = normalizeContextPath(pattern);
+    if (normalizedPattern.endsWith("/")) {
+        const directory = normalizedPattern.replace(/\/+$/u, "");
+        return normalizedPath === directory || normalizedPath.startsWith(`${directory}/`);
+    }
+    return normalizedPath === normalizedPattern;
+};
+export const createDockerIgnoreContent = () => `${DOCKER_BUILD_CONTEXT_IGNORE_PATTERNS.join("\n")}\n`;
+const isIgnoredContextPath = (relativePath) => DOCKER_BUILD_CONTEXT_IGNORE_PATTERNS.some((pattern) => matchesDockerBuildIgnorePattern(relativePath, pattern));
+const walkContextFiles = async (directory, relativeDirectory = "") => {
+    const entries = await readdir(path.join(directory, relativeDirectory), {
+        withFileTypes: true
+    });
+    const files = [];
+    for (const entry of entries) {
+        const relativePath = normalizeContextPath(path.join(relativeDirectory, entry.name));
+        if (isIgnoredContextPath(relativePath)) {
+            continue;
+        }
+        if (entry.isDirectory()) {
+            files.push(...await walkContextFiles(directory, relativePath));
+            continue;
+        }
+        const metadata = await stat(path.join(directory, relativePath));
+        if (metadata.isFile()) {
+            files.push({
+                mode: metadata.mode & 0o777,
+                path: relativePath,
+                size: metadata.size
+            });
+        }
+    }
+    return files;
+};
+export const listDockerBuildContextFiles = async (directory) => (await walkContextFiles(path.resolve(directory))).sort((left, right) => compareBytes(left.path, right.path));
+const canonicalJson = (value) => {
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => canonicalJson(entry)).join(",")}]`;
+    }
+    if (value !== null && typeof value === "object") {
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => compareBytes(left, right))
+            .map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+};
+const createFileContentHash = async (directory, relativePath) => {
+    const content = await readFile(path.join(directory, relativePath));
+    if (relativePath !== "distribution-report.json") {
+        return createHash("sha256").update(content).digest("hex");
+    }
+    const report = JSON.parse(content.toString("utf8"));
+    const { generated_at: _generatedAt, ...normalizedReport } = report;
+    return createHash("sha256")
+        .update(canonicalJson(normalizedReport))
+        .digest("hex");
+};
+export const createDockerBuildContextDigest = async (directory) => {
+    const resolvedDirectory = path.resolve(directory);
+    const digest = createHash("sha256");
+    for (const file of await listDockerBuildContextFiles(resolvedDirectory)) {
+        const contentHash = await createFileContentHash(resolvedDirectory, file.path);
+        digest.update(`${file.path}\0${file.mode}\0${contentHash}`);
+    }
+    return `sha256:${digest.digest("hex")}`;
+};
+const createLogicalDockerfileLines = (dockerfile) => {
+    const logicalLines = [];
+    let current = "";
+    for (const line of dockerfile.split(/\r?\n/u)) {
+        const trimmed = line.trim();
+        current = current.length === 0 ? trimmed : `${current} ${trimmed}`;
+        if (current.endsWith("\\")) {
+            current = current.slice(0, -1).trimEnd();
+            continue;
+        }
+        logicalLines.push(current);
+        current = "";
+    }
+    if (current.length > 0) {
+        logicalLines.push(current);
+    }
+    return logicalLines;
+};
+const tokenizeDockerInstruction = (source) => {
+    const tokens = [];
+    const pattern = /"((?:\\.|[^"])*)"|'([^']*)'|([^\s]+)/gu;
+    for (const match of source.matchAll(pattern)) {
+        if (match[1] !== undefined) {
+            tokens.push(JSON.parse(`"${match[1]}"`));
+        }
+        else {
+            tokens.push(match[2] ?? match[3] ?? "");
+        }
+    }
+    return tokens;
+};
+const stripInstructionFlags = (tokens) => {
+    let index = 0;
+    while (tokens[index]?.startsWith("--")) {
+        index += tokens[index]?.includes("=") ? 1 : 2;
+    }
+    return tokens.slice(index);
+};
+export const extractDockerBuildContextSources = (dockerfile) => {
+    const sources = [];
+    for (const line of createLogicalDockerfileLines(dockerfile)) {
+        const match = line.match(/^(COPY|ADD)\s+(.+)$/iu);
+        if (!match) {
+            continue;
+        }
+        const instruction = match[1].toUpperCase();
+        const argumentsSource = match[2].trim();
+        const rawTokens = argumentsSource.startsWith("[")
+            ? JSON.parse(argumentsSource)
+            : tokenizeDockerInstruction(argumentsSource);
+        if (instruction === "COPY"
+            && rawTokens.some((token) => token === "--from" || token.startsWith("--from="))) {
+            continue;
+        }
+        const tokens = stripInstructionFlags(rawTokens);
+        for (const source of tokens.slice(0, -1)) {
+            if (instruction === "ADD" && /^(?:https?|git):\/\//u.test(source)) {
+                continue;
+            }
+            sources.push(normalizeContextPath(source));
+        }
+    }
+    return sources;
+};
+export const findIgnoredDockerBuildSources = (dockerfile, patterns = DOCKER_BUILD_CONTEXT_IGNORE_PATTERNS) => extractDockerBuildContextSources(dockerfile).flatMap((source) => {
+    const normalizedSource = normalizeContextPathForContainment(source);
+    return patterns.flatMap((pattern) => {
+        const normalizedPattern = normalizeContextPathForContainment(pattern);
+        const swallowsIgnoredPath = normalizedSource.length === 0
+            || normalizedPattern === normalizedSource
+            || normalizedPattern.startsWith(`${normalizedSource}/`);
+        return matchesDockerBuildIgnorePattern(source, pattern) || swallowsIgnoredPath
+            ? [{ pattern, source }]
+            : [];
+    });
+});

package/dist/compiler/dockerBuildSkip.d.ts

@@ -0,0 +1,30 @@
+import type { BuildImageCacheEntry } from "../deployment/buildImageCacheStore.js";
+export declare const DOCKER_IMAGE_INSPECT_MAX_OUTPUT_BYTES: number;
+export declare const DOCKER_IMAGE_INSPECT_TIMEOUT_MS = 5000;
+export interface DockerImageInspection {
+    id: string;
+    labels: Record<string, string>;
+}
+export interface DockerImageInspectInput {
+    dockerCommand?: string;
+    dockerContext?: string | null;
+    imageTag: string;
+}
+export interface DockerImageInspectCommandOptions {
+    encoding: "utf8";
+    maxBuffer: number;
+    timeout: number;
+}
+export type DockerImageInspectCommandRunner = (command: string, args: string[], options: DockerImageInspectCommandOptions) => Promise<{
+    stdout: string;
+}>;
+export type DockerImageInspector = (input: DockerImageInspectInput) => Promise<DockerImageInspection | null>;
+export declare const createDockerImageInspector: (runner?: DockerImageInspectCommandRunner) => DockerImageInspector;
+export declare const inspectDockerImage: DockerImageInspector;
+export interface DockerBuildSkipInput extends DockerImageInspectInput {
+    cacheEntry: BuildImageCacheEntry | null;
+    compileFingerprint: string;
+    contextDigest: string;
+    imageInspector?: DockerImageInspector;
+}
+export declare const shouldSkipDockerBuild: (input: DockerBuildSkipInput) => Promise<boolean>;

package/dist/compiler/dockerBuildSkip.js

@@ -0,0 +1,81 @@
+import { execFile as execFileCallback } from "node:child_process";
+export const DOCKER_IMAGE_INSPECT_MAX_OUTPUT_BYTES = 64 * 1024;
+export const DOCKER_IMAGE_INSPECT_TIMEOUT_MS = 5_000;
+const runDockerImageInspectCommand = async (command, args, options) => new Promise((resolve, reject) => {
+    execFileCallback(command, args, options, (error, stdout) => {
+        if (error) {
+            reject(error);
+            return;
+        }
+        resolve({ stdout });
+    });
+});
+const parseDockerImageInspection = (source) => {
+    try {
+        const parsed = JSON.parse(source);
+        if (typeof parsed.id !== "string" || parsed.id.length === 0) {
+            return null;
+        }
+        if (parsed.labels === null || parsed.labels === undefined) {
+            return { id: parsed.id, labels: {} };
+        }
+        if (typeof parsed.labels !== "object" || Array.isArray(parsed.labels)) {
+            return null;
+        }
+        const labels = Object.fromEntries(Object.entries(parsed.labels).filter((entry) => typeof entry[1] === "string"));
+        if (Object.keys(labels).length !== Object.keys(parsed.labels).length) {
+            return null;
+        }
+        return { id: parsed.id, labels };
+    }
+    catch {
+        return null;
+    }
+};
+export const createDockerImageInspector = (runner = runDockerImageInspectCommand) => async (input) => {
+    const args = input.dockerContext
+        ? ["--context", input.dockerContext, "image", "inspect", input.imageTag]
+        : ["image", "inspect", input.imageTag];
+    args.push("--format", '{"id":{{json .Id}},"labels":{{json .Config.Labels}}}');
+    try {
+        const { stdout } = await runner(input.dockerCommand ?? "docker", args, {
+            encoding: "utf8",
+            maxBuffer: DOCKER_IMAGE_INSPECT_MAX_OUTPUT_BYTES,
+            timeout: DOCKER_IMAGE_INSPECT_TIMEOUT_MS
+        });
+        if (Buffer.byteLength(stdout) > DOCKER_IMAGE_INSPECT_MAX_OUTPUT_BYTES) {
+            return null;
+        }
+        return parseDockerImageInspection(stdout);
+    }
+    catch {
+        return null;
+    }
+};
+export const inspectDockerImage = createDockerImageInspector();
+export const shouldSkipDockerBuild = async (input) => {
+    const entry = input.cacheEntry;
+    if (!entry) {
+        return false;
+    }
+    if (entry.contextDigest !== input.contextDigest) {
+        return false;
+    }
+    if (entry.imageTag !== input.imageTag) {
+        return false;
+    }
+    if (entry.compileFingerprint !== input.compileFingerprint) {
+        return false;
+    }
+    if (entry.dockerContext !== (input.dockerContext ?? null)) {
+        return false;
+    }
+    try {
+        const inspection = await (input.imageInspector ?? inspectDockerImage)(input);
+        return inspection?.id === entry.imageId
+            && inspection.labels["com.spawnfile.compile_fingerprint"] === entry.compileFingerprint;
+    }
+    catch {
+        return false;
+    }
+};

package/dist/compiler/index.d.ts

@@ -4,6 +4,8 @@ export * from "./buildProject.js";
 export * from "./publishProject.js";
 export * from "./upProject.js";
 export * from "./compileProject.js";
+export * from "./dockerBuildContext.js";
+export * from "./dockerBuildSkip.js";
 export * from "./initProject.js";
 export * from "./moltnetRoomMemberships.js";
 export * from "./runProject.js";
@@ -12,4 +14,6 @@ export * from "./types.js";
 export * from "./updateProjectModels.js";
 export * from "./updateProjectRuntime.js";
 export * from "./updateProjectSurfaces.js";
+export * from "./upReceipt.js";
+export * from "./worldBindings.js";
 export * from "./view/index.js";

package/dist/compiler/index.js

@@ -4,6 +4,8 @@ export * from "./buildProject.js";
 export * from "./publishProject.js";
 export * from "./upProject.js";
 export * from "./compileProject.js";
+export * from "./dockerBuildContext.js";
+export * from "./dockerBuildSkip.js";
 export * from "./initProject.js";
 export * from "./moltnetRoomMemberships.js";
 export * from "./runProject.js";
@@ -12,4 +14,6 @@ export * from "./types.js";
 export * from "./updateProjectModels.js";
 export * from "./updateProjectRuntime.js";
 export * from "./updateProjectSurfaces.js";
+export * from "./upReceipt.js";
+export * from "./worldBindings.js";
 export * from "./view/index.js";

package/dist/compiler/memoryArtifacts.d.ts

@@ -0,0 +1,26 @@
+import type { CompilePlan, ResolvedMemoryBank } from "./types.js";
+import type { ContainerMemoryTransport, ContainerPersistentMountReport } from "../report/types.js";
+type MemoryStoreKind = "json" | "memory" | "postgres" | "sqlite";
+type MemoryArtifactSummary = {
+    id: string;
+    declaring_node_id: string;
+    accessible_node_ids: string[];
+    store: {
+        kind: MemoryStoreKind;
+        path?: string;
+        persistence?: "durable" | "ephemeral";
+        persistent_mount_id?: string;
+        dsn_secret?: string;
+    };
+    index: ResolvedMemoryBank["index"];
+    consolidation: ResolvedMemoryBank["consolidation"];
+    retention: ResolvedMemoryBank["retention"];
+    transport_by_node_id: Record<string, ContainerMemoryTransport>;
+};
+export interface MemoryArtifactBundle {
+    mountPathMemoryMap: Map<string, string>;
+    mounts: ContainerPersistentMountReport[];
+    memories: MemoryArtifactSummary[];
+}
+export declare const createMemoryArtifactBundle: (plan: CompilePlan) => MemoryArtifactBundle;
+export {};