spawnfile 0.1.13 → 0.1.17

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,10 @@ export * from "./buildProject.js";
 export * from "./publishProject.js";
 export * from "./upProject.js";
 export * from "./compileProject.js";
+export * from "./containerBackedMountRender.js";
+export * from "./deploymentLineage.js";
+export * from "./dockerBuildContext.js";
+export * from "./dockerBuildSkip.js";
 export * from "./initProject.js";
 export * from "./moltnetRoomMemberships.js";
 export * from "./runProject.js";
@@ -12,4 +16,7 @@ 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";
+export * from "./training/index.js";

package/dist/compiler/index.js

@@ -4,6 +4,10 @@ export * from "./buildProject.js";
 export * from "./publishProject.js";
 export * from "./upProject.js";
 export * from "./compileProject.js";
+export * from "./containerBackedMountRender.js";
+export * from "./deploymentLineage.js";
+export * from "./dockerBuildContext.js";
+export * from "./dockerBuildSkip.js";
 export * from "./initProject.js";
 export * from "./moltnetRoomMemberships.js";
 export * from "./runProject.js";
@@ -12,4 +16,7 @@ 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";
+export * from "./training/index.js";

package/dist/compiler/initProject.d.ts

@@ -2,7 +2,9 @@ export interface InitProjectOptions {
     directory?: string;
     runtime?: string;
     team?: boolean;
+    template?: string;
 }
+export declare const listInitTemplates: () => Promise<string[]>;
 export declare const initProject: (options?: InitProjectOptions) => Promise<{
     createdFiles: string[];
     directory: string;

package/dist/compiler/initProject.js

@@ -1,9 +1,22 @@
 import path from "node:path";
-import { ensureDirectory, ensureGitignoreEntry, fileExists, writeUtf8File } from "../filesystem/index.js";
+import { readdir } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { copyDirectory, ensureDirectory, ensureGitignoreEntry, fileExists, writeUtf8File } from "../filesystem/index.js";
 import { createTeamScaffoldManifest, renderSpawnfile } from "../manifest/index.js";
 import { getRuntimeAdapter } from "../runtime/index.js";
 import { DEFAULT_OUTPUT_DIRECTORY, SpawnfileError } from "../shared/index.js";
 const DEFAULT_AGENT_RUNTIME = "openclaw";
+// Bundled example org projects double as `init --template` starting points.
+// Resolves to the package's examples/ dir in both dev (src/) and the published
+// package (dist/), so examples/ must ship in package.json "files".
+const EXAMPLES_ROOT = fileURLToPath(new URL("../../examples", import.meta.url));
+export const listInitTemplates = async () => {
+    const entries = await readdir(EXAMPLES_ROOT, { withFileTypes: true });
+    return entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort();
+};
 export const initProject = async (options = {}) => {
     const directory = path.resolve(options.directory ?? process.cwd());
     const manifestPath = path.join(directory, "Spawnfile");
@@ -11,10 +24,35 @@ export const initProject = async (options = {}) => {
     if (await fileExists(manifestPath)) {
         throw new SpawnfileError("io_error", `Refusing to overwrite existing Spawnfile at ${manifestPath}`);
     }
+    if (options.template && (options.team || options.runtime)) {
+        throw new SpawnfileError("validation_error", "--template cannot be combined with --team or --runtime");
+    }
     if (options.team && options.runtime) {
         throw new SpawnfileError("validation_error", "Team scaffolds do not accept --runtime");
     }
+    // Resolve and validate the template before creating anything, so an unknown
+    // template name never leaves an empty directory behind.
+    let templateSource;
+    if (options.template) {
+        const templates = await listInitTemplates();
+        if (!templates.includes(options.template)) {
+            throw new SpawnfileError("validation_error", `Unknown template "${options.template}". Available templates: ${templates.join(", ")}`);
+        }
+        templateSource = path.join(EXAMPLES_ROOT, options.template);
+    }
     await ensureDirectory(directory);
+    if (templateSource) {
+        await copyDirectory(templateSource, directory);
+        await ensureGitignoreEntry(directory, `${DEFAULT_OUTPUT_DIRECTORY}/`);
+        // Report only the files this template contributed — never pre-existing
+        // contents of the target directory.
+        const sourceEntries = await readdir(templateSource, { recursive: true, withFileTypes: true });
+        const createdFiles = sourceEntries
+            .filter((entry) => entry.isFile())
+            .map((entry) => path.join(directory, path.relative(templateSource, path.join(entry.parentPath, entry.name))))
+            .sort();
+        return { createdFiles, directory };
+    }
     const createdFiles = [manifestPath];
     const gitignorePath = path.join(directory, ".gitignore");
     const hadGitignore = await fileExists(gitignorePath);

package/dist/compiler/localMoltnetAuthority.d.ts

@@ -0,0 +1,64 @@
+import type { MoltnetTargetArchitecture } from "./moltnetReleaseAuthority.js";
+export interface LocalMoltnetReleaseIdentity {
+    readonly architecture: MoltnetTargetArchitecture;
+    readonly asset: string;
+    readonly asset_sha256: `sha256:${string}`;
+    readonly capabilities: readonly ["daimon-bridge", "pi-bridge"];
+    readonly development: Readonly<{
+        mode: "local-development";
+        non_production: true;
+        unsigned: true;
+        unpublished: true;
+    }>;
+    readonly source_sha256: `sha256:${string}`;
+    readonly source_inputs?: Readonly<{
+        dependencies_sha256: `sha256:${string}`;
+        mode: "source-bundle";
+        source_sha256: `sha256:${string}`;
+        toolchain: string;
+    }>;
+    readonly version: "spawnfile.moltnet-release-identity.v1";
+}
+interface LocalMoltnetReleaseStamp {
+    readonly arch: MoltnetTargetArchitecture;
+    readonly asset: string;
+    readonly capabilities: readonly ["daimon-bridge", "pi-bridge"];
+    readonly development: LocalMoltnetReleaseIdentity["development"];
+    readonly sha256: string;
+    readonly source_sha256: `sha256:${string}`;
+    readonly source_inputs?: LocalMoltnetReleaseIdentity["source_inputs"];
+    readonly stamp_version: "spawnfile.local-moltnet-release-stamp.v1";
+}
+/** @internal Complete synthetic bridge contract used by local artifact verification. */
+export declare const createLocalMoltnetBridgeProbeConfig: (kind: "daimon" | "pi", directory: string) => string;
+/** @internal Strict parser shared with provenance regression tests. */
+export declare const parseLocalReleaseStamp: (raw: string, architecture: MoltnetTargetArchitecture) => LocalMoltnetReleaseStamp;
+/**
+ * The platform actually executing this compile -- never the build target.
+ *
+ * `architecture` is absent when the host CPU is one Spawnfile cannot name as a
+ * Moltnet target (so it can never accidentally equal one), and `platform` is a
+ * raw `process.platform`.
+ */
+export interface MoltnetExecutionHost {
+    readonly architecture?: MoltnetTargetArchitecture;
+    readonly platform: NodeJS.Platform;
+}
+/**
+ * Whether this host can run the built binary directly, deciding between the
+ * direct-exec probe and the Docker cross-platform probe below.
+ *
+ * A local Moltnet build is ALWAYS `GOOS=linux` (the asset is
+ * `moltnet_linux_<arch>.tar.gz`), so matching the architecture alone is not
+ * enough: a darwin/arm64 host and a linux/arm64 binary share a CPU
+ * architecture and share nothing else. Executing that ELF on macOS fails with
+ * ENOEXEC and the probe reports the binary as unprovable, rejecting a
+ * perfectly good build. The host must therefore match on OS *and*
+ * architecture; everything else goes through Docker, which can run a
+ * linux/<arch> image anywhere.
+ *
+ * @internal Exported for the branch-selection tests.
+ */
+export declare const moltnetBinaryIsDirectlyExecutable: (architecture: MoltnetTargetArchitecture, host: MoltnetExecutionHost) => boolean;
+export declare const readLocalMoltnetReleaseIdentity: (releaseDirectory: string, architecture: MoltnetTargetArchitecture, host: MoltnetExecutionHost) => Promise<LocalMoltnetReleaseIdentity>;
+export {};

package/dist/compiler/localMoltnetAuthority.js

@@ -0,0 +1,177 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { chmod, readFile, rm, writeFile } from "node:fs/promises";
+import { promisify } from "node:util";
+import { ensureDirectory, fileExists } from "../filesystem/index.js";
+import { SpawnfileError } from "../shared/index.js";
+const execFile = promisify(execFileCallback);
+const SHA256 = /^[a-f0-9]{64}$/u;
+const exactKeys = (value, keys) => Object.keys(value).sort().join("\0") === [...keys].sort().join("\0");
+const assetName = (architecture) => `moltnet_linux_${architecture}.tar.gz`;
+/** @internal Complete synthetic bridge contract used by local artifact verification. */
+export const createLocalMoltnetBridgeProbeConfig = (kind, directory) => JSON.stringify({
+    attachments: [{
+            agent: { id: `${kind}-capability-probe`, name: `${kind} capability probe` },
+            runtime: kind === "daimon"
+                ? {
+                    control_url: "http://127.0.0.1:9",
+                    kind,
+                    receipt_store_path: path.join(directory, "daimon-receipts", "daimon-capability-probe.json"),
+                    token_env: "SPAWNFILE_DAIMON_CONTROL_TOKEN"
+                }
+                : { control_url: "http://127.0.0.1:9/agents/pi-capability-probe/wake", kind }
+        }],
+    moltnet: { base_url: "http://127.0.0.1:9", network_id: "capability-probe" },
+    version: "moltnet.node.v1"
+});
+const assertBridgeCapability = async (binaryPath, directory, kind) => {
+    const configPath = path.join(directory, `${kind}-bridge-probe.json`);
+    const receiptDirectory = path.join(directory, "daimon-receipts");
+    await ensureDirectory(receiptDirectory);
+    await chmod(receiptDirectory, 0o700);
+    await writeFile(configPath, createLocalMoltnetBridgeProbeConfig(kind, directory), { mode: 0o600 });
+    try {
+        await execFile(binaryPath, ["node", configPath], {
+            env: { ...process.env, SPAWNFILE_DAIMON_CONTROL_TOKEN: "capability-probe" },
+            timeout: 1_000
+        });
+        throw new SpawnfileError("compile_error", `Local Moltnet binary exited before proving its ${kind}-bridge capability`);
+    }
+    catch (error) {
+        if (error instanceof SpawnfileError)
+            throw error;
+        const execution = error;
+        const output = `${String(execution.stdout ?? "")}\n${String(execution.stderr ?? "")}`;
+        if (/unsupported|only supported|required|invalid|unknown runtime/i.test(output)) {
+            throw new SpawnfileError("compile_error", `Local Moltnet binary does not accept ${kind}-bridge configuration`);
+        }
+        if (execution.killed === true || execution.signal === "SIGTERM" || execution.code === "ETIMEDOUT")
+            return;
+        if (/connection refused|connect:|dial tcp|network is unreachable/i.test(output))
+            return;
+        throw new SpawnfileError("compile_error", `Local Moltnet binary could not prove its ${kind}-bridge capability`);
+    }
+};
+/** @internal Strict parser shared with provenance regression tests. */
+export const parseLocalReleaseStamp = (raw, architecture) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new SpawnfileError("compile_error", "Local Moltnet release stamp is not valid JSON");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new SpawnfileError("compile_error", "Local Moltnet release stamp has an invalid shape");
+    }
+    const value = parsed;
+    const development = value.development;
+    const sourceInputs = value.source_inputs;
+    if (!exactKeys(value, ["arch", "asset", "capabilities", "development", "sha256", "source_sha256", "stamp_version", ...(sourceInputs ? ["source_inputs"] : [])])
+        || value.stamp_version !== "spawnfile.local-moltnet-release-stamp.v1"
+        || value.arch !== architecture
+        || value.asset !== assetName(architecture)
+        || !Array.isArray(value.capabilities)
+        || value.capabilities.join("\0") !== "daimon-bridge\0pi-bridge"
+        || !development
+        || !exactKeys(development, ["mode", "non_production", "unsigned", "unpublished"])
+        || development.mode !== "local-development"
+        || development.non_production !== true
+        || development.unsigned !== true
+        || development.unpublished !== true
+        || typeof value.sha256 !== "string"
+        || !SHA256.test(value.sha256)
+        || typeof value.source_sha256 !== "string"
+        || !/^sha256:[a-f0-9]{64}$/u.test(value.source_sha256)
+        || (sourceInputs && (!exactKeys(sourceInputs, ["dependencies_sha256", "mode", "source_sha256", "toolchain"]) || sourceInputs.mode !== "source-bundle" || !/^sha256:[a-f0-9]{64}$/u.test(String(sourceInputs.dependencies_sha256)) || sourceInputs.source_sha256 !== value.source_sha256 || sourceInputs.toolchain !== "golang:1.24-bookworm@sha256:1a6d4452c65dea36aac2e2d606b01b4a029ec90cc1ae53890540ce6173ea77ac"))) {
+        throw new SpawnfileError("compile_error", "Local Moltnet release stamp must be a complete development-only dual-bridge identity");
+    }
+    return value;
+};
+/**
+ * Whether this host can run the built binary directly, deciding between the
+ * direct-exec probe and the Docker cross-platform probe below.
+ *
+ * A local Moltnet build is ALWAYS `GOOS=linux` (the asset is
+ * `moltnet_linux_<arch>.tar.gz`), so matching the architecture alone is not
+ * enough: a darwin/arm64 host and a linux/arm64 binary share a CPU
+ * architecture and share nothing else. Executing that ELF on macOS fails with
+ * ENOEXEC and the probe reports the binary as unprovable, rejecting a
+ * perfectly good build. The host must therefore match on OS *and*
+ * architecture; everything else goes through Docker, which can run a
+ * linux/<arch> image anywhere.
+ *
+ * @internal Exported for the branch-selection tests.
+ */
+export const moltnetBinaryIsDirectlyExecutable = (architecture, host) => host.platform === "linux" && host.architecture === architecture;
+const verifyBuiltMoltnetArchive = async (releaseAssetPath, architecture, host) => {
+    const temporaryDirectory = path.join(path.dirname(releaseAssetPath), `.spawnfile-moltnet-verify-${process.pid}-${Date.now()}`);
+    try {
+        await ensureDirectory(temporaryDirectory);
+        await execFile("tar", ["-C", temporaryDirectory, "-xzf", releaseAssetPath]);
+        const binaryPath = path.join(temporaryDirectory, "moltnet");
+        if (!(await fileExists(binaryPath))) {
+            throw new SpawnfileError("compile_error", "Local Moltnet archive does not contain its moltnet binary");
+        }
+        await chmod(binaryPath, 0o755);
+        if (moltnetBinaryIsDirectlyExecutable(architecture, host)) {
+            const { stdout } = await execFile(binaryPath, ["version"]);
+            if (!stdout.trim())
+                throw new SpawnfileError("compile_error", "Local Moltnet binary did not produce a bounded version identity");
+            await assertBridgeCapability(binaryPath, temporaryDirectory, "pi");
+            await assertBridgeCapability(binaryPath, temporaryDirectory, "daimon");
+        }
+        else {
+            for (const kind of ["pi", "daimon"]) {
+                const configPath = path.join(temporaryDirectory, `${kind}-docker-probe.json`);
+                await writeFile(configPath, createLocalMoltnetBridgeProbeConfig(kind, "/receipts"));
+                const { stdout: rawId } = await execFile("docker", ["create", "--platform", `linux/${architecture}`, "--env", "SPAWNFILE_DAIMON_CONTROL_TOKEN=probe", "node:24-bookworm-slim@sha256:a9f5f7c91a432850b2a8a7797adf5eadb6c733ceed61167806cee7ea7fbc29df", "timeout", "2", "/moltnet", "node", "/config.json"]);
+                const id = rawId.trim();
+                try {
+                    await execFile("docker", ["cp", binaryPath, `${id}:/moltnet`]);
+                    await execFile("docker", ["cp", configPath, `${id}:/config.json`]);
+                    try {
+                        await execFile("docker", ["start", "--attach", id]);
+                    }
+                    catch (error) {
+                        const result = error;
+                        const output = `${String(result.stdout ?? "")}\n${String(result.stderr ?? "")}`;
+                        if (result.code !== 124 && !/connection refused|connect:|dial tcp|network is unreachable/iu.test(output))
+                            throw new SpawnfileError("compile_error", `Local Moltnet cross-host ${kind} capability probe failed`);
+                    }
+                }
+                finally {
+                    await execFile("docker", ["rm", "--force", id]);
+                }
+            }
+        }
+    }
+    finally {
+        await rm(temporaryDirectory, { force: true, recursive: true });
+    }
+};
+export const readLocalMoltnetReleaseIdentity = async (releaseDirectory, architecture, host) => {
+    const asset = assetName(architecture);
+    const assetPath = path.join(releaseDirectory, asset);
+    const stampPath = path.join(releaseDirectory, `local_moltnet_release_stamp_${architecture}.json`);
+    if (!(await fileExists(assetPath)) || !(await fileExists(stampPath))) {
+        throw new SpawnfileError("compile_error", "Local Moltnet release requires its exact archive and development identity stamp");
+    }
+    const stamp = parseLocalReleaseStamp(await readFile(stampPath, "utf8"), architecture);
+    const sha256 = createHash("sha256").update(await readFile(assetPath)).digest("hex");
+    if (stamp.sha256 !== sha256) {
+        throw new SpawnfileError("compile_error", "Local Moltnet development stamp does not match its archive bytes");
+    }
+    await verifyBuiltMoltnetArchive(assetPath, architecture, host);
+    return Object.freeze({
+        architecture,
+        asset,
+        asset_sha256: `sha256:${sha256}`,
+        capabilities: Object.freeze(["daimon-bridge", "pi-bridge"]),
+        development: Object.freeze({ mode: "local-development", non_production: true, unsigned: true, unpublished: true }),
+        source_sha256: stamp.source_sha256,
+        ...(stamp.source_inputs ? { source_inputs: Object.freeze(stamp.source_inputs) } : {}),
+        version: "spawnfile.moltnet-release-identity.v1"
+    });
+};

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, deploymentLineage?: string) => MemoryArtifactBundle;
+export {};