spawnfile 0.1.12 → 0.1.14

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>;

package/dist/compiler/worldBindingsFile.js

@@ -0,0 +1,162 @@
+import path from "node:path";
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { SpawnfileError } from "../shared/index.js";
+import { resolveWorldBindings, SIMFILE_WORLD_BINDINGS_VERSION } from "./worldBindings.js";
+export const MAX_WORLD_BINDINGS_FILE_BYTES = 1_048_576;
+class DuplicateJsonKeyError extends Error {
+}
+const fail = (message) => {
+    throw new SpawnfileError("validation_error", `invalid ${SIMFILE_WORLD_BINDINGS_VERSION} file: ${message}`);
+};
+const assertNoDuplicateJsonKeys = (source) => {
+    let offset = 0;
+    const whitespace = () => {
+        while (/\s/u.test(source[offset] ?? ""))
+            offset += 1;
+    };
+    const string = () => {
+        const start = offset;
+        offset += 1;
+        while (offset < source.length) {
+            if (source[offset] === "\\") {
+                offset += 2;
+            }
+            else if (source[offset] === "\"") {
+                offset += 1;
+                return JSON.parse(source.slice(start, offset));
+            }
+            else {
+                offset += 1;
+            }
+        }
+        return fail("JSON is malformed");
+    };
+    const value = () => {
+        whitespace();
+        if (source[offset] === "{") {
+            object();
+            return;
+        }
+        if (source[offset] === "[") {
+            array();
+            return;
+        }
+        if (source[offset] === "\"") {
+            string();
+            return;
+        }
+        while (offset < source.length && !/[\s,\]}]/u.test(source[offset] ?? "")) {
+            offset += 1;
+        }
+    };
+    const object = () => {
+        offset += 1;
+        whitespace();
+        const keys = new Set();
+        if (source[offset] === "}") {
+            offset += 1;
+            return;
+        }
+        while (offset < source.length) {
+            const key = string();
+            if (keys.has(key))
+                throw new DuplicateJsonKeyError();
+            keys.add(key);
+            whitespace();
+            offset += 1;
+            value();
+            whitespace();
+            if (source[offset] === "}") {
+                offset += 1;
+                return;
+            }
+            offset += 1;
+            whitespace();
+        }
+    };
+    const array = () => {
+        offset += 1;
+        whitespace();
+        if (source[offset] === "]") {
+            offset += 1;
+            return;
+        }
+        while (offset < source.length) {
+            value();
+            whitespace();
+            if (source[offset] === "]") {
+                offset += 1;
+                return;
+            }
+            offset += 1;
+            whitespace();
+        }
+    };
+    value();
+    whitespace();
+    if (offset !== source.length)
+        fail("JSON must contain exactly one value");
+};
+const decodeJson = (bytes) => {
+    let source;
+    try {
+        source = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        return fail("content must be valid UTF-8");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch {
+        return fail("content must be exactly one valid JSON value");
+    }
+    try {
+        assertNoDuplicateJsonKeys(source);
+    }
+    catch (error) {
+        if (error instanceof DuplicateJsonKeyError)
+            return fail("duplicate JSON keys are not allowed");
+        throw error;
+    }
+    return parsed;
+};
+export const readSimfileWorldBindingsFile = async (inputPath) => {
+    const filePath = path.resolve(inputPath);
+    let handle;
+    try {
+        handle = await open(filePath, constants.O_RDONLY | constants.O_NONBLOCK);
+        const metadata = await handle.stat();
+        if (!metadata.isFile() || metadata.size <= 0
+            || metadata.size > MAX_WORLD_BINDINGS_FILE_BYTES) {
+            return fail(`content must be a non-empty regular file no larger than ${MAX_WORLD_BINDINGS_FILE_BYTES} bytes`);
+        }
+        const buffer = new Uint8Array(MAX_WORLD_BINDINGS_FILE_BYTES + 1);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.byteLength, 0);
+        const afterRead = await handle.stat();
+        if (bytesRead !== metadata.size || afterRead.size !== metadata.size
+            || bytesRead > MAX_WORLD_BINDINGS_FILE_BYTES) {
+            return fail("content changed while it was being read or exceeds the byte limit");
+        }
+        return decodeJson(buffer.subarray(0, bytesRead));
+    }
+    catch (error) {
+        if (error instanceof SpawnfileError)
+            throw error;
+        return fail("content could not be read");
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+};
+export const loadWorldBindingsForCompile = async (plan, inputPath, expectedRunId) => {
+    if (!expectedRunId)
+        return fail("NOOPOLIS_RUN_ID must be set before compile");
+    const resolved = resolveWorldBindings(plan, await readSimfileWorldBindingsFile(inputPath));
+    if (resolved.artifact.bindings[0]?.run_id !== expectedRunId) {
+        return fail("binding run_id does not match the compile NOOPOLIS_RUN_ID");
+    }
+    return resolved;
+};

package/dist/deployment/artifactsExport.d.ts

@@ -0,0 +1,49 @@
+import { type DockerArtifactExecFile } from "./artifactsExportDocker.js";
+import { type ExportIndex } from "./artifactsExportTypes.js";
+import { type DeploymentLifecycleCorrelation } from "./deploymentLifecycleCorrelation.js";
+export interface ExportRunArtifactsOptions {
+    /** Where the deployment record + compile report already live (the compile's own
+     * `--out` directory) — NOT the export destination. */
+    compiledOutputDirectory: string;
+    deploymentName?: string;
+    /** Where `raw/**` and `spawnfile/export-index.json` are written. */
+    destinationDirectory: string;
+    dockerCommand?: string;
+    execFile?: DockerArtifactExecFile;
+    /** Explicitly export unredacted private runtime training artifacts. */
+    includePrivate?: boolean;
+    /** Overrides the image used to read named volumes; defaults to the deployment's own
+     * recorded `image_tag` (already present locally — see artifactsExportDocker.ts). */
+    readerImage?: string;
+    runId?: string;
+    timeoutMs?: number;
+    expectedLifecycleCorrelation?: DeploymentLifecycleCorrelation;
+}
+export interface ExportRunArtifactsResult {
+    deploymentName: string;
+    /** Planned files that failed to copy despite the container/volume being reachable
+     * (a real per-file problem, worth surfacing — as opposed to `missingOptionalFiles`). */
+    failedFiles: string[];
+    index: ExportIndex;
+    indexPath: string;
+    /** Planned files that were legitimately absent (e.g. no recall yet) — not failures. */
+    missingOptionalFiles: string[];
+}
+export declare const resolveArtifactsExportLifecycleCorrelation: (options: Pick<ExportRunArtifactsOptions, "compiledOutputDirectory" | "deploymentName" | "runId">) => Promise<DeploymentLifecycleCorrelation>;
+/**
+ * `spawnfile artifacts export` — mechanical egress of a run's durable artifacts (moltnet
+ * causal log, mneme bank ledgers, daimon per-agent telemetry) into the compose-and-observe
+ * run-dir layout (`decisions.md` Decision 21 §2), plus the `spawnfile.export-index.v1`
+ * index simfile's observer folds into its own run manifest.
+ *
+ * As of Piece 4b, every planned file is volume-sourced (moltnet + mneme already were;
+ * daimon telemetry joined them — see `artifactsExportPlan.ts`'s `planDaimonFiles`), and a
+ * named volume outlives its container across a plain `docker rm` (no `--volumes`). So this
+ * no longer requires the deployment's container to still be alive in the general case: the
+ * container-liveness check below (`requiresLiveContainer`) only runs when the plan actually
+ * contains a `kind: "container"` file, which today only happens for a legacy pre-Piece-4b
+ * compile report. This is the real relaxation of the export-before-teardown invariant
+ * Piece 4b unlocks: `spawnfile down` (without `--volumes`) can run BEFORE `spawnfile
+ * artifacts export`, and export still recovers everything from the named volumes.
+ */
+export declare const exportRunArtifacts: (options: ExportRunArtifactsOptions) => Promise<ExportRunArtifactsResult>;

package/dist/deployment/artifactsExport.js

@@ -0,0 +1,217 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { readFile, rm } from "node:fs/promises";
+import { ensureDirectory, fileExists, readUtf8File, writeUtf8File } from "../filesystem/index.js";
+import { SpawnfileError } from "../shared/index.js";
+import { REPORT_FILENAME } from "../shared/index.js";
+import { containerExists, copyContainerFileToHost, copyVolumeFileToHost, defaultDockerArtifactExecFile } from "./artifactsExportDocker.js";
+import { EXPORT_INDEX_VERSION } from "./artifactsExportTypes.js";
+import { planArtifactExports } from "./artifactsExportPlan.js";
+import { exportPrivateRuntimeArtifacts } from "./privateArtifactsExport.js";
+import { assertDeploymentLifecycleCorrelation, createDeploymentLifecycleCorrelation, } from "./deploymentLifecycleCorrelation.js";
+import { listDeploymentRecords, readDeploymentRecordFromOutput, writeDeploymentRecord } from "./record.js";
+const sha256Hex = (buffer) => createHash("sha256").update(buffer).digest("hex");
+const targetRefForUnit = (unit) => unit.container_id ?? unit.container_name;
+const resolveDeploymentRecord = async (compiledOutputDirectory, options) => {
+    if (options.deploymentName && options.runId) {
+        throw new SpawnfileError("validation_error", "spawnfile artifacts export accepts only one of --deployment or --run-id");
+    }
+    if (!options.deploymentName && !options.runId) {
+        throw new SpawnfileError("validation_error", "spawnfile artifacts export requires --deployment <name> or --run-id <id>");
+    }
+    if (options.deploymentName) {
+        try {
+            return await readDeploymentRecordFromOutput(compiledOutputDirectory, options.deploymentName);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new SpawnfileError("runtime_error", `No deployment record named "${options.deploymentName}" under ${compiledOutputDirectory}. ` +
+                `Has it already been torn down, or never brought up with --detach? (${reason})`);
+        }
+    }
+    const records = await listDeploymentRecords(compiledOutputDirectory);
+    const match = records.find((entry) => entry.record.run_id === options.runId);
+    if (!match) {
+        const known = records.map((entry) => entry.record.name).sort().join(", ") || "none";
+        throw new SpawnfileError("runtime_error", `No deployment record found for run id "${options.runId}" under ${compiledOutputDirectory}. ` +
+            `Known deployments: ${known}`);
+    }
+    return match.record;
+};
+export const resolveArtifactsExportLifecycleCorrelation = async (options) => createDeploymentLifecycleCorrelation(await resolveDeploymentRecord(path.resolve(options.compiledOutputDirectory), options));
+const readCompileReport = async (compiledOutputDirectory) => {
+    const reportPath = path.join(compiledOutputDirectory, REPORT_FILENAME);
+    if (!(await fileExists(reportPath))) {
+        throw new SpawnfileError("validation_error", `No compile report found at ${reportPath}; recompile the project before exporting artifacts.`);
+    }
+    const parsed = JSON.parse(await readUtf8File(reportPath));
+    if (!parsed.container) {
+        throw new SpawnfileError("validation_error", `Compile report at ${reportPath} has no container section; nothing to export.`);
+    }
+    return parsed;
+};
+const hostPathFor = (destinationDirectory, relativePath) => path.join(destinationDirectory, ...relativePath.split("/"));
+const exportOnePlannedFile = async (input) => {
+    const hostPath = hostPathFor(input.destinationDirectory, input.plan.relativePath);
+    await ensureDirectory(path.dirname(hostPath));
+    const runnerOptions = { dockerCommand: input.dockerCommand, execFile: input.execFile, timeoutMs: input.timeoutMs };
+    let copied;
+    let source;
+    if (input.plan.source.kind === "container") {
+        copied = await copyContainerFileToHost({
+            containerPath: input.plan.source.containerPath,
+            containerRef: input.containerRef,
+            hostPath,
+            target: input.target,
+            ...runnerOptions
+        });
+        source = { kind: "container", ref: `${input.containerRef}:${input.plan.source.containerPath}` };
+    }
+    else {
+        copied = await copyVolumeFileToHost({
+            hostPath,
+            readerImage: input.readerImage,
+            target: input.target,
+            volumeName: input.plan.source.volumeName,
+            volumePath: input.plan.source.volumePath,
+            ...runnerOptions
+        });
+        source = { kind: "volume", ref: `${input.plan.source.volumeName}:/${input.plan.source.volumePath}` };
+    }
+    if (!copied) {
+        // docker cp never creates a partial file on failure, but be defensive: never leave a
+        // stray empty file behind for a copy this function considers failed.
+        await rm(hostPath, { force: true });
+        return null;
+    }
+    const buffer = await readFile(hostPath);
+    return {
+        bytes: buffer.byteLength,
+        path: input.plan.relativePath,
+        sha256: sha256Hex(buffer),
+        source
+    };
+};
+/**
+ * `spawnfile artifacts export` — mechanical egress of a run's durable artifacts (moltnet
+ * causal log, mneme bank ledgers, daimon per-agent telemetry) into the compose-and-observe
+ * run-dir layout (`decisions.md` Decision 21 §2), plus the `spawnfile.export-index.v1`
+ * index simfile's observer folds into its own run manifest.
+ *
+ * As of Piece 4b, every planned file is volume-sourced (moltnet + mneme already were;
+ * daimon telemetry joined them — see `artifactsExportPlan.ts`'s `planDaimonFiles`), and a
+ * named volume outlives its container across a plain `docker rm` (no `--volumes`). So this
+ * no longer requires the deployment's container to still be alive in the general case: the
+ * container-liveness check below (`requiresLiveContainer`) only runs when the plan actually
+ * contains a `kind: "container"` file, which today only happens for a legacy pre-Piece-4b
+ * compile report. This is the real relaxation of the export-before-teardown invariant
+ * Piece 4b unlocks: `spawnfile down` (without `--volumes`) can run BEFORE `spawnfile
+ * artifacts export`, and export still recovers everything from the named volumes.
+ */
+export const exportRunArtifacts = async (options) => {
+    const compiledOutputDirectory = path.resolve(options.compiledOutputDirectory);
+    const destinationDirectory = path.resolve(options.destinationDirectory);
+    const dockerCommand = options.dockerCommand ?? "docker";
+    const execFileImpl = options.execFile ?? defaultDockerArtifactExecFile;
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    const record = await resolveDeploymentRecord(compiledOutputDirectory, options);
+    assertDeploymentLifecycleCorrelation(record, options.expectedLifecycleCorrelation);
+    const unit = record.units[0];
+    if (!unit) {
+        throw new SpawnfileError("validation_error", `Deployment "${record.name}" has no recorded container unit`);
+    }
+    const containerRef = targetRefForUnit(unit);
+    if (!containerRef) {
+        throw new SpawnfileError("validation_error", `Deployment "${record.name}" has no recorded container id or name`);
+    }
+    const runId = record.run_id;
+    if (!runId) {
+        throw new SpawnfileError("validation_error", `Deployment "${record.name}" has no recorded run id (it predates run-id tracking, or was ` +
+            "compiled with no NOOPOLIS_RUN_ID set), so a conformant export-index.json cannot be " +
+            "written. Recompile and redeploy the project (with NOOPOLIS_RUN_ID set, or via a plain " +
+            "`spawnfile up --detach`, which always generates one) before exporting artifacts.");
+    }
+    const report = await readCompileReport(compiledOutputDirectory);
+    const planned = planArtifactExports(report);
+    // Only a `kind: "container"` planned file needs the live container (see this function's
+    // own doc comment) — every other source reads a named volume, which survives a plain
+    // `docker rm` on its own. Gating on this, rather than checking unconditionally, is the
+    // actual export-before-teardown relaxation Piece 4b delivers.
+    const requiresLiveContainer = options.includePrivate === true
+        || planned.some((entry) => entry.source.kind === "container");
+    if (requiresLiveContainer) {
+        const exists = await containerExists(record.target, containerRef, {
+            dockerCommand,
+            execFile: execFileImpl,
+            timeoutMs
+        });
+        if (!exists) {
+            throw new SpawnfileError("runtime_error", `Deployment "${record.name}" has no live container ("${containerRef}"), and its planned export ` +
+                "includes at least one file that can only be read from a live container (a legacy, " +
+                "pre-Piece-4b compile report — recompile to move it onto a durable volume). Run " +
+                "`spawnfile artifacts export` BEFORE `spawnfile down` removes the container, or recompile.");
+        }
+    }
+    const readerImage = options.readerImage ?? unit.image_tag;
+    const files = [];
+    const missingOptionalFiles = [];
+    const failedFiles = [];
+    for (const plan of planned) {
+        const entry = await exportOnePlannedFile({
+            containerRef,
+            destinationDirectory,
+            dockerCommand,
+            execFile: execFileImpl,
+            plan,
+            readerImage,
+            target: record.target,
+            timeoutMs
+        });
+        if (entry) {
+            files.push(entry);
+        }
+        else if (plan.optional) {
+            missingOptionalFiles.push(plan.relativePath);
+        }
+        else {
+            failedFiles.push(plan.relativePath);
+        }
+    }
+    if (options.includePrivate === true) {
+        const privateResult = await exportPrivateRuntimeArtifacts({
+            containerRef,
+            destinationDirectory,
+            dockerCommand,
+            execFile: execFileImpl,
+            report,
+            target: record.target,
+            timeoutMs,
+        });
+        files.push(...privateResult.files);
+        failedFiles.push(...privateResult.missing);
+    }
+    const index = {
+        deployment: record.name,
+        exported_at: new Date().toISOString(),
+        files: files.sort((left, right) => left.path.localeCompare(right.path)),
+        run_id: runId,
+        version: EXPORT_INDEX_VERSION
+    };
+    const indexPath = path.join(destinationDirectory, "spawnfile", "export-index.json");
+    await ensureDirectory(path.dirname(indexPath));
+    await writeUtf8File(indexPath, `${JSON.stringify(index, null, 2)}\n`);
+    // Stamp the export-before-teardown marker onto the SAME deployment record `spawnfile
+    // down` resolves (record.ts's `export_index`), so down never needs a second, out-of-band
+    // way to learn that this run's artifacts are already safe to discard the container for.
+    await writeDeploymentRecord(compiledOutputDirectory, {
+        ...record,
+        export_index: { exported_at: index.exported_at, path: indexPath, run_id: runId }
+    });
+    return {
+        deploymentName: record.name,
+        failedFiles,
+        index,
+        indexPath,
+        missingOptionalFiles
+    };
+};