spawnfile 0.1.13 → 0.1.14

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

package/dist/deployment/artifactsExportDocker.d.ts

@@ -0,0 +1,48 @@
+import type { DeploymentRecord } from "./record.js";
+/** Same injectable exec shape as `dockerInspect.ts`/`dockerLogs.ts` — real Docker calls
+ * are the default, tests inject a fake. */
+export type DockerArtifactExecFile = (file: string, args: string[], options: {
+    timeout: number;
+}) => Promise<{
+    stderr: string;
+    stdout: string;
+}>;
+export interface DockerRunnerOptions {
+    dockerCommand: string;
+    execFile: DockerArtifactExecFile;
+    timeoutMs: number;
+}
+/**
+ * True when `containerRef` (an id or name) still exists in Docker, false when Docker
+ * reports it missing (a stopped-and-removed container, or one never created). Any other
+ * Docker failure (daemon unreachable, context misconfigured, ...) is re-thrown rather than
+ * folded into "missing" — export-before-teardown detection must not misreport a genuine
+ * Docker connectivity problem as "this deployment was already torn down".
+ */
+export declare const containerExists: (target: DeploymentRecord["target"], containerRef: string, options: DockerRunnerOptions) => Promise<boolean>;
+/** `docker cp <containerRef>:<containerPath> <hostPath>` — best-effort, returns false
+ * instead of throwing (a single missing file inside an otherwise-live container is a
+ * per-file concern, handled by the caller via each planned file's `optional` flag). */
+export declare const copyContainerFileToHost: (input: {
+    containerPath: string;
+    containerRef: string;
+    hostPath: string;
+    target: DeploymentRecord["target"];
+} & DockerRunnerOptions) => Promise<boolean>;
+/**
+ * Reads one file out of a named Docker volume without needing the volume's original
+ * container: creates a throwaway container (never started — its own entrypoint never
+ * runs) with the volume read-only mounted, `docker cp`s the single file out, then always
+ * removes the throwaway container. `readerImage` is expected to be an image already
+ * present locally (the deployment's own `unit.image_tag` is the natural choice — it is
+ * guaranteed to exist wherever the deployment itself ran, so this never needs to pull a
+ * new "tiny image" from a registry).
+ */
+export declare const copyVolumeFileToHost: (input: {
+    hostPath: string;
+    readerImage: string;
+    target: DeploymentRecord["target"];
+    volumeName: string;
+    volumePath: string;
+} & DockerRunnerOptions) => Promise<boolean>;
+export declare const defaultDockerArtifactExecFile: DockerArtifactExecFile;

package/dist/deployment/artifactsExportDocker.js

@@ -0,0 +1,91 @@
+import { randomUUID } from "node:crypto";
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+import { dockerContextNameForTarget } from "./target.js";
+const execFile = promisify(execFileCallback);
+const withDockerTarget = (target, args) => {
+    const context = dockerContextNameForTarget(target);
+    if (context) {
+        return ["--context", context, ...args];
+    }
+    if (target.kind === "host") {
+        return ["--host", target.value, ...args];
+    }
+    return args;
+};
+const toErrorMessage = (error) => {
+    if (typeof error === "object" && error !== null && "stderr" in error) {
+        const stderr = error.stderr;
+        if (typeof stderr === "string" && stderr.length > 0) {
+            return stderr.trim();
+        }
+    }
+    return error instanceof Error ? error.message : String(error);
+};
+/**
+ * True when `containerRef` (an id or name) still exists in Docker, false when Docker
+ * reports it missing (a stopped-and-removed container, or one never created). Any other
+ * Docker failure (daemon unreachable, context misconfigured, ...) is re-thrown rather than
+ * folded into "missing" — export-before-teardown detection must not misreport a genuine
+ * Docker connectivity problem as "this deployment was already torn down".
+ */
+export const containerExists = async (target, containerRef, options) => {
+    try {
+        await options.execFile(options.dockerCommand, withDockerTarget(target, ["inspect", "--type", "container", containerRef]), { timeout: options.timeoutMs });
+        return true;
+    }
+    catch (error) {
+        const message = toErrorMessage(error);
+        if (/No such (?:object|container)/i.test(message)) {
+            return false;
+        }
+        throw new Error(`Unable to check whether container "${containerRef}" exists: ${message}`);
+    }
+};
+/** `docker cp <containerRef>:<containerPath> <hostPath>` — best-effort, returns false
+ * instead of throwing (a single missing file inside an otherwise-live container is a
+ * per-file concern, handled by the caller via each planned file's `optional` flag). */
+export const copyContainerFileToHost = async (input) => {
+    try {
+        await input.execFile(input.dockerCommand, withDockerTarget(input.target, ["cp", `${input.containerRef}:${input.containerPath}`, input.hostPath]), { timeout: input.timeoutMs });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Reads one file out of a named Docker volume without needing the volume's original
+ * container: creates a throwaway container (never started — its own entrypoint never
+ * runs) with the volume read-only mounted, `docker cp`s the single file out, then always
+ * removes the throwaway container. `readerImage` is expected to be an image already
+ * present locally (the deployment's own `unit.image_tag` is the natural choice — it is
+ * guaranteed to exist wherever the deployment itself ran, so this never needs to pull a
+ * new "tiny image" from a registry).
+ */
+export const copyVolumeFileToHost = async (input) => {
+    const mountPoint = "/spawnfile-export-src";
+    const readerContainerName = `spawnfile-artifacts-export-${randomUUID()}`;
+    try {
+        await input.execFile(input.dockerCommand, withDockerTarget(input.target, [
+            "create",
+            "--name", readerContainerName,
+            "-v", `${input.volumeName}:${mountPoint}:ro`,
+            input.readerImage
+        ]), { timeout: input.timeoutMs });
+    }
+    catch {
+        return false;
+    }
+    try {
+        await input.execFile(input.dockerCommand, withDockerTarget(input.target, ["cp", `${readerContainerName}:${mountPoint}/${input.volumePath}`, input.hostPath]), { timeout: input.timeoutMs });
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        await input.execFile(input.dockerCommand, withDockerTarget(input.target, ["rm", "-f", readerContainerName]), { timeout: input.timeoutMs }).catch(() => undefined);
+    }
+};
+export const defaultDockerArtifactExecFile = execFile;

package/dist/deployment/artifactsExportPlan.d.ts

@@ -0,0 +1,24 @@
+import type { CompileReport } from "../report/index.js";
+/** One durable-artifact file `spawnfile artifacts export` egresses, and where it lands
+ * under `<out>` (Decision 21 §2 run-dir layout). Pure planning data — no Docker/IO here;
+ * `artifactsExport.ts` executes each plan entry and `artifactsExportDocker.ts` knows how. */
+export interface PlannedExportFile {
+    /** Path relative to the export destination directory, e.g. "raw/moltnet/causal.jsonl". */
+    relativePath: string;
+    source: {
+        kind: "volume";
+        volumeName: string;
+        volumePath: string;
+    } | {
+        kind: "container";
+        containerPath: string;
+    };
+    /** True when the file may legitimately be absent (e.g. a bank's causal.jsonl before any
+     * recall event, or events.jsonl before any memory write) — a missing optional file is a
+     * silent skip, never a diagnostic. Non-optional sources missing is worth flagging. */
+    optional: boolean;
+}
+/** Resolves every durable artifact file this run's compile report declares, and where each
+ * one is read from. Pure function of the compile report alone (no deployment record, no
+ * Docker) — `artifactsExport.ts` supplies the live container name at execution time. */
+export declare const planArtifactExports: (report: CompileReport) => PlannedExportFile[];