spawnfile 0.1.13 → 0.1.17

package/dist/deployment/dockerProbeGateway.js

@@ -1,7 +1,21 @@
 import { execFile as execFileCallback } from "node:child_process";
 import { promisify } from "node:util";
+import { DAIMON_GROK_TURN_USAGE_LEDGER } from "../runtime/daimon/contractManifest.js";
 import { dockerContextNameForTarget } from "./target.js";
 const execFile = promisify(execFileCallback);
+/**
+ * The ledger this gateway reads (`spawnfile usage`) rotates once a generation
+ * reaches `DAIMON_GROK_TURN_USAGE_LEDGER.rotateBytes`, and rotation happens on
+ * the append *after* that threshold is crossed — so a rotated generation is
+ * always at least the bound and the crossing line pushes it over. A maxBuffer
+ * merely equal to the bound therefore rejects the exact read this feature
+ * exists to perform (Node's `execFile` accepts a payload of exactly
+ * `maxBuffer` bytes and fails the next one with
+ * `ERR_CHILD_PROCESS_STDIO_MAXBUFFER`). Doubling the bound leaves a full
+ * generation of headroom, and is derived from the ledger constant rather than
+ * restated so the two cannot drift apart.
+ */
+export const DEFAULT_DOCKER_PROBE_MAX_BUFFER_BYTES = 2 * DAIMON_GROK_TURN_USAGE_LEDGER.rotateBytes;
 const targetRefForUnit = (unit) => {
     const targetRef = unit.container_id ?? unit.container_name;
     if (!targetRef) {
@@ -19,26 +33,86 @@ const withDockerTarget = (record, args) => {
     }
     return args;
 };
+const imageRefForUnit = (unit) => unit.image_id
+    ? (/^[a-f0-9]{64}$/u.test(unit.image_id) ? `sha256:${unit.image_id}` : unit.image_id)
+    : unit.image_tag;
+const redactProbeText = (value, limit) => value
+    .replace(/\s+/gu, " ")
+    .replace(/(bearer|token|password|passwd|secret|authorization)[=: ]+(?:bearer[ ]+)?[^ ]+/giu, "$1=[redacted]")
+    .replace(/https?:\/\/[^ ]+/giu, "[url redacted]")
+    .slice(0, limit);
+const boundedProbeFailure = (error) => {
+    if (!error || typeof error !== "object")
+        return redactProbeText(String(error), 240) || "probe failed";
+    const candidate = error;
+    const hasStatus = typeof candidate.status === "number" || typeof candidate.status === "string";
+    const hasCode = typeof candidate.code === "number" || typeof candidate.code === "string";
+    const status = hasStatus
+        ? `status ${String(candidate.status)}`
+        : hasCode
+            ? `exit ${String(candidate.code)}`
+            : "failed";
+    const stderr = typeof candidate.stderr === "string"
+        ? redactProbeText(candidate.stderr, 240)
+        : "";
+    const message = typeof candidate.message === "string" ? redactProbeText(candidate.message, 160) : "";
+    if (error instanceof Error && !stderr)
+        return message || "probe failed";
+    if (stderr)
+        return `docker probe ${status}: ${stderr}`;
+    if (message)
+        return hasStatus || hasCode ? `docker probe ${status}: ${message}` : message;
+    return `docker probe ${status}`;
+};
+const parseCurlHttpOutput = (stdout) => {
+    const match = /\n(\d{3})$/u.exec(stdout);
+    if (!match || match.index === undefined) {
+        return { body: "", error: "malformed HTTP probe response", ok: false };
+    }
+    const status = Number(match[1]);
+    const body = stdout.slice(0, match.index);
+    return status >= 200 && status <= 299
+        ? { body, ok: true }
+        : { body, error: `HTTP ${status}`, ok: false };
+};
+const httpProbeArgs = (targetRef, imageRef, url) => [
+    "run",
+    "--rm",
+    "--network",
+    `container:${targetRef}`,
+    "--entrypoint",
+    "curl",
+    imageRef,
+    "-sS",
+    "--output",
+    "-",
+    "--write-out",
+    "\\n%{http_code}",
+    url
+];
 export const createDockerProbeGateway = (record, unit, options) => {
     const dockerCommand = options.dockerCommand ?? "docker";
     const runExec = options.execFile ?? execFile;
     const timeout = options.timeoutMs ?? 10_000;
+    const maxBuffer = options.maxBufferBytes ?? DEFAULT_DOCKER_PROBE_MAX_BUFFER_BYTES;
     const exec = async (command) => {
         const targetRef = targetRefForUnit(unit);
-        return runExec(dockerCommand, withDockerTarget(record, ["exec", targetRef, ...command]), { timeout });
+        return runExec(dockerCommand, withDockerTarget(record, ["exec", targetRef, ...command]), { maxBuffer, timeout });
     };
     return {
         exec,
         async httpGet(port, requestPath, headers = {}) {
+            if (Object.keys(headers).length > 0) {
+                return { body: "", error: "HTTP probe headers are forbidden", ok: false };
+            }
             const url = `http://127.0.0.1:${port}${requestPath.startsWith("/") ? requestPath : `/${requestPath}`}`;
             try {
-                const headerArgs = Object.entries(headers).flatMap(([name, value]) => ["-H", `${name}: ${value}`]);
-                const result = await exec(["curl", "-fsS", ...headerArgs, url]);
-                return { body: result.stdout, ok: true };
+                const targetRef = targetRefForUnit(unit);
+                const result = await runExec(dockerCommand, withDockerTarget(record, httpProbeArgs(targetRef, imageRefForUnit(unit), url)), { maxBuffer, timeout });
+                return parseCurlHttpOutput(result.stdout);
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                return { body: "", error: message, ok: false };
+                return { body: "", error: boundedProbeFailure(error), ok: false };
             }
         },
         async inspectUnit() {

package/dist/deployment/dockerRecover.js

@@ -62,6 +62,7 @@ const groupByDeployment = (inspections, options, target) => {
         }
         const name = deploymentNameFor(labels);
         const compileFingerprint = labels[dockerDeploymentLabelKeys.compileFingerprint];
+        const runId = labels[dockerDeploymentLabelKeys.runId];
         if (!name || !compileFingerprint) {
             continue;
         }
@@ -75,13 +76,20 @@ const groupByDeployment = (inspections, options, target) => {
         }
         seenUnits.add(unit.id);
         unitsByDeployment.set(name, seenUnits);
-        const record = records.get(name) ?? {
+        const existing = records.get(name);
+        if (existing
+            && (existing.compile_fingerprint !== compileFingerprint
+                || existing.run_id !== runId)) {
+            throw new SpawnfileError("validation_error", `Recovered deployment "${name}" has inconsistent identity labels`);
+        }
+        const record = existing ?? {
             auth_profile: null,
             compile_fingerprint: compileFingerprint,
             created_at: toStringOrNull(inspection.Created) ?? new Date().toISOString(),
             manager: "docker",
             name,
             output_directory: options.outputDirectory,
+            ...(runId ? { run_id: runId } : {}),
             source: { kind: "project", root: options.sourceRoot },
             target,
             units: [],

package/dist/deployment/dockerTeardown.d.ts

@@ -0,0 +1,32 @@
+import type { DeploymentRecord } from "./record.js";
+/** Same injectable exec shape as `artifactsExportDocker.ts`/`dockerInspect.ts` — real
+ * Docker calls are the default, tests inject a fake. */
+export type DockerTeardownExecFile = (file: string, args: string[], options: {
+    timeout: number;
+}) => Promise<{
+    stderr: string;
+    stdout: string;
+}>;
+export interface DockerTeardownRunnerOptions {
+    dockerCommand: string;
+    execFile: DockerTeardownExecFile;
+    timeoutMs: number;
+}
+export interface DockerRemovalOutcome {
+    error: string | null;
+    removed: boolean;
+}
+/**
+ * `docker rm -f <containerRef>` — force-removes a container whether it is running or
+ * already stopped. A container Docker reports as already gone ("No such container")
+ * counts as removed: `spawnfile down` is idempotent (calling it twice, or after the
+ * container died on its own, is a success, not a partial failure).
+ */
+export declare const removeDockerContainer: (target: DeploymentRecord["target"], containerRef: string, options: DockerTeardownRunnerOptions) => Promise<DockerRemovalOutcome>;
+/**
+ * `docker volume rm -f <volumeName>` — only called when the caller explicitly opts into
+ * volume removal (`spawnfile down --volumes`; the default is to retain volumes). A volume
+ * Docker reports as already gone ("No such volume") also counts as removed.
+ */
+export declare const removeDockerVolume: (target: DeploymentRecord["target"], volumeName: string, options: DockerTeardownRunnerOptions) => Promise<DockerRemovalOutcome>;
+export declare const defaultDockerTeardownExecFile: DockerTeardownExecFile;

package/dist/deployment/dockerTeardown.js

@@ -0,0 +1,61 @@
+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);
+};
+/**
+ * `docker rm -f <containerRef>` — force-removes a container whether it is running or
+ * already stopped. A container Docker reports as already gone ("No such container")
+ * counts as removed: `spawnfile down` is idempotent (calling it twice, or after the
+ * container died on its own, is a success, not a partial failure).
+ */
+export const removeDockerContainer = async (target, containerRef, options) => {
+    try {
+        await options.execFile(options.dockerCommand, withDockerTarget(target, ["rm", "-f", containerRef]), { timeout: options.timeoutMs });
+        return { error: null, removed: true };
+    }
+    catch (error) {
+        const message = toErrorMessage(error);
+        if (/No such container/i.test(message)) {
+            return { error: null, removed: true };
+        }
+        return { error: message, removed: false };
+    }
+};
+/**
+ * `docker volume rm -f <volumeName>` — only called when the caller explicitly opts into
+ * volume removal (`spawnfile down --volumes`; the default is to retain volumes). A volume
+ * Docker reports as already gone ("No such volume") also counts as removed.
+ */
+export const removeDockerVolume = async (target, volumeName, options) => {
+    try {
+        await options.execFile(options.dockerCommand, withDockerTarget(target, ["volume", "rm", "-f", volumeName]), { timeout: options.timeoutMs });
+        return { error: null, removed: true };
+    }
+    catch (error) {
+        const message = toErrorMessage(error);
+        if (/No such volume/i.test(message)) {
+            return { error: null, removed: true };
+        }
+        return { error: message, removed: false };
+    }
+};
+export const defaultDockerTeardownExecFile = execFile;

package/dist/deployment/downDeployment.d.ts

@@ -0,0 +1,39 @@
+import { type DeploymentLifecycleCorrelation } from "./deploymentLifecycleCorrelation.js";
+import { type DockerTeardownExecFile } from "./dockerTeardown.js";
+import { type DownReceipt } from "./downReceiptTypes.js";
+import type { DeploymentRecord } from "./record.js";
+export interface DownDeploymentOptions {
+    /** Where the deployment record + compile report already live (the compile's own
+     * `--out` directory) — same convention as `exportRunArtifacts`'s `compiledOutputDirectory`. */
+    compiledOutputDirectory: string;
+    deploymentName: string;
+    dockerCommand?: string;
+    execFile?: DockerTeardownExecFile;
+    /** Auto-runs `spawnfile artifacts export` to this directory before tearing down, when
+     * this run has no export-index yet. Mutually satisfying with `force` — either one
+     * clears the export-before-teardown guard, `exportTo` by doing the export, `force` by
+     * deliberately skipping it. */
+    exportTo?: string;
+    /** Deliberately discards un-exported artifacts and proceeds without exporting. */
+    force?: boolean;
+    readerImage?: string;
+    /** Also removes this deployment's named volumes. Default: retain (see CLAUDE.md's
+     * folder rule — this is the only reversible-by-default lifecycle boundary spawnfile
+     * has: containers are cheap to recreate, the durable stores are not). */
+    removeVolumes?: boolean;
+    expectedLifecycleCorrelation?: DeploymentLifecycleCorrelation;
+    timeoutMs?: number;
+}
+export declare const readCanonicalDownRecord: (compiledOutputDirectory: string, deploymentName: string) => Promise<{
+    mode: "image" | "project";
+    record: DeploymentRecord;
+}>;
+/**
+ * `spawnfile down` — record-driven teardown: resolves the deployment record, enforces the
+ * export-before-teardown invariant, `docker rm -f`s every recorded container unit, and
+ * (only with `--volumes`) removes named volumes. Always returns a `spawnfile.down-
+ * receipt.v1`, even when some units/volumes failed to remove (`errors` carries the
+ * per-item failures; a partial failure is never silently swallowed, but it also never
+ * stops the rest of the teardown from being attempted).
+ */
+export declare const downDeployment: (options: DownDeploymentOptions) => Promise<DownReceipt>;

package/dist/deployment/downDeployment.js

@@ -0,0 +1,248 @@
+import path from "node:path";
+import { fileExists, readUtf8File } from "../filesystem/index.js";
+import { derivePersistentMountVolumeName, parseDistributionReport } from "../distribution/index.js";
+import { REPORT_FILENAME, SpawnfileError } from "../shared/index.js";
+import { exportRunArtifacts } from "./artifactsExport.js";
+import { assertDeploymentLifecycleCorrelation, } from "./deploymentLifecycleCorrelation.js";
+import { defaultDockerTeardownExecFile, removeDockerContainer, removeDockerVolume, } from "./dockerTeardown.js";
+import { DOWN_RECEIPT_VERSION } from "./downReceiptTypes.js";
+import { initializeOrganizationHandoffAuthorityStore, } from "./organizationHandoffAuthorityStore.js";
+import { readDeploymentRecordFromOutput } from "./record.js";
+import { readHomeDeploymentRecord, readHomeDeploymentReport, resolveHomeRecordPath } from "./homeStore.js";
+import { resolveDeploymentRecordPath } from "./names.js";
+import { dockerContextNameForTarget } from "./target.js";
+export const readCanonicalDownRecord = async (compiledOutputDirectory, deploymentName) => {
+    const projectPath = resolveDeploymentRecordPath(path.resolve(compiledOutputDirectory), deploymentName);
+    const homePath = resolveHomeRecordPath(deploymentName);
+    const [projectExists, homeExists] = await Promise.all([fileExists(projectPath), fileExists(homePath)]);
+    if (projectExists && homeExists)
+        throw new SpawnfileError("runtime_error", "Deployment record is ambiguous between project and image stores");
+    if (projectExists) {
+        const record = await readDeploymentRecordFromOutput(path.resolve(compiledOutputDirectory), deploymentName);
+        if (record.source.kind !== "project")
+            throw new SpawnfileError("runtime_error", "Project deployment store contains a non-project record");
+        return { mode: "project", record };
+    }
+    if (homeExists) {
+        const record = await readHomeDeploymentRecord(deploymentName);
+        if (record.source.kind !== "image")
+            throw new SpawnfileError("runtime_error", "Image deployment store contains a non-image record");
+        return { mode: "image", record };
+    }
+    throw new SpawnfileError("validation_error", `No recorded deployment named ${deploymentName}`);
+};
+const imageDown = async (record, options, runner) => {
+    if (record.source.kind !== "image" || record.units.length !== 1)
+        throw new SpawnfileError("runtime_error", "Image deployment record is invalid for teardown");
+    if (!record.export_index && !options.force)
+        throw new SpawnfileError("runtime_error", "Image deployment artifact export is unsupported; pass --force to discard unexported artifacts");
+    const unit = record.units[0];
+    if (!unit.container_id || !unit.image_id)
+        throw new SpawnfileError("runtime_error", "Image deployment has no exact recorded container or image identity");
+    const context = dockerContextNameForTarget(record.target);
+    const prefix = context ? ["--context", context] : record.target.kind === "host" ? ["--host", record.target.value] : [];
+    const inspected = await runner.execFile(runner.dockerCommand, [...prefix, "container", "inspect", "--format", "{{json .Id}}\n{{json .Name}}\n{{json .Image}}\n{{json .Config.Labels}}", unit.container_id], { timeout: runner.timeoutMs });
+    let identity;
+    try {
+        const [idLine, nameLine, imageLine, labelsLine, ...extra] = inspected.stdout.trim().split("\n");
+        if (!idLine || !nameLine || !imageLine || !labelsLine || extra.length)
+            throw new Error();
+        identity = { id: JSON.parse(idLine), imageId: JSON.parse(imageLine), name: JSON.parse(nameLine), labels: JSON.parse(labelsLine) };
+    }
+    catch {
+        throw new SpawnfileError("runtime_error", "Image deployment container identity is malformed");
+    }
+    if (identity.id !== unit.container_id || identity.name !== `/${unit.container_name}` || identity.imageId !== unit.image_id
+        || identity.labels["com.spawnfile.deployment"] !== record.name
+        || identity.labels["com.spawnfile.compile_fingerprint"] !== record.compile_fingerprint
+        || identity.labels["com.spawnfile.unit"] !== unit.id) {
+        throw new SpawnfileError("runtime_error", "Image deployment container identity does not match its record");
+    }
+    let reportValue;
+    try {
+        reportValue = JSON.parse(await readHomeDeploymentReport(record.name));
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new SpawnfileError("runtime_error", `Cached image distribution report is unreadable: ${reason}`);
+    }
+    const report = parseDistributionReport(reportValue, "cached image distribution report");
+    if (report.compile_fingerprint !== record.compile_fingerprint)
+        throw new SpawnfileError("runtime_error", "Cached image distribution report does not match its deployment record");
+    const { owned, skipped } = partitionDeclaredVolumes(report.persistent_mounts, (mount) => derivePersistentMountVolumeName(record.name, mount));
+    const volumes = [...owned, ...skipped].sort();
+    const removed = await removeDockerContainer(record.target, unit.container_id, runner);
+    if (!removed.removed)
+        return { deployment: record.name, errors: [`unable to remove container ${unit.container_id} (unit ${unit.id}): ${removed.error}`], retained_volumes: volumes, units_stopped: [], version: DOWN_RECEIPT_VERSION, ...(skipped.length > 0 ? { skipped_volumes: skipped } : {}) };
+    const errors = [], retained = [...skipped];
+    if (options.removeVolumes)
+        for (const volume of owned) {
+            const result = await removeDockerVolume(record.target, volume, runner);
+            if (!result.removed) {
+                errors.push(`unable to remove volume ${volume}: ${result.error}`);
+                retained.push(volume);
+            }
+        }
+    else
+        retained.push(...owned);
+    return { deployment: record.name, errors, retained_volumes: retained.sort(), units_stopped: [unit.id], version: DOWN_RECEIPT_VERSION, ...(skipped.length > 0 ? { skipped_volumes: skipped } : {}) };
+};
+/**
+ * Splits the volumes a `--volumes` teardown found into the ones this deployment
+ * owns and the author-declared ones it shares with every other deployment of the
+ * project. See downReceiptTypes.ts for why the declared ones are never removed.
+ */
+const partitionDeclaredVolumes = (mounts, volumeNameOf) => {
+    const skipped = new Set();
+    const owned = new Set();
+    for (const mount of mounts) {
+        (mount.declared_volume_name?.trim() ? skipped : owned).add(volumeNameOf(mount));
+    }
+    // A name claimed by both is shared state, and the compiler already rejects that
+    // collision; fail safe here regardless by never removing it.
+    for (const name of skipped)
+        owned.delete(name);
+    return { owned: [...owned].sort(), skipped: [...skipped].sort() };
+};
+const targetRefForUnit = (unit) => unit.container_id ?? unit.container_name;
+const readCompileReport = async (compiledOutputDirectory) => {
+    const reportPath = path.join(compiledOutputDirectory, REPORT_FILENAME);
+    if (!(await fileExists(reportPath))) {
+        return null;
+    }
+    return JSON.parse(await readUtf8File(reportPath));
+};
+const explainRefusal = (deploymentName) => `Deployment "${deploymentName}" has no export-index: its durable artifacts (moltnet ` +
+    "causal log, mneme bank ledgers, daimon telemetry) have not been exported yet, and " +
+    "`spawnfile down` would destroy the container they live in before anyone reads them. " +
+    `Run \`spawnfile artifacts export --deployment ${deploymentName} --out <dir>\` first, ` +
+    "or pass `--export-to <dir>` to export-then-down in one call, or `--force` to " +
+    "deliberately discard the un-exported artifacts.";
+/** Enforces the export-before-teardown invariant (Decision 21): resolves whether this
+ * deployment's record already carries an `export_index` marker (stamped by
+ * `exportRunArtifacts` — see record.ts), and if not, either refuses, auto-exports, or
+ * (with `--force`) proceeds anyway. Returns the record `spawnfile down` should act on —
+ * re-read after an auto-export, since that call updates the record on disk. */
+const ensureExported = async (record, options) => {
+    if (record.export_index || options.force) {
+        return record;
+    }
+    const exportTo = options.exportTo;
+    if (!exportTo) {
+        throw new SpawnfileError("runtime_error", explainRefusal(options.deploymentName));
+    }
+    await exportRunArtifacts({
+        compiledOutputDirectory: options.compiledOutputDirectory,
+        deploymentName: options.deploymentName,
+        destinationDirectory: exportTo,
+        dockerCommand: options.dockerCommand,
+        // Structurally identical exec-call shape as DockerArtifactExecFile (see
+        // artifactsExportDocker.ts) — forwarded so an injected fake/override execFile covers
+        // the auto-export step too, not just container/volume removal.
+        execFile: options.execFile,
+        readerImage: options.readerImage,
+        timeoutMs: options.timeoutMs,
+    });
+    return readDeploymentRecordFromOutput(options.compiledOutputDirectory, options.deploymentName);
+};
+const closeOrganizationHandoff = async (record) => {
+    const hasPublicHandoff = record.organization_handoff !== undefined;
+    const hasPrivateHandle = record.organization_handoff_handle !== undefined;
+    if (hasPublicHandoff !== hasPrivateHandle) {
+        throw new SpawnfileError("runtime_error", "Deployment organization handoff authority is incomplete; refusing teardown");
+    }
+    if (!hasPrivateHandle ||
+        record.organization_handoff === undefined ||
+        record.organization_handoff_handle === undefined)
+        return;
+    let authority;
+    let failed = false;
+    try {
+        authority = await initializeOrganizationHandoffAuthorityStore();
+        await authority.close({
+            expectedHandoff: record.organization_handoff,
+            organizationHandoffHandle: record.organization_handoff_handle,
+        });
+    }
+    catch {
+        failed = true;
+    }
+    finally {
+        try {
+            await authority?.dispose();
+        }
+        catch {
+            failed = true;
+        }
+    }
+    if (failed) {
+        throw new SpawnfileError("runtime_error", "Unable to close organization handoff authority before deployment teardown");
+    }
+};
+/**
+ * `spawnfile down` — record-driven teardown: resolves the deployment record, enforces the
+ * export-before-teardown invariant, `docker rm -f`s every recorded container unit, and
+ * (only with `--volumes`) removes named volumes. Always returns a `spawnfile.down-
+ * receipt.v1`, even when some units/volumes failed to remove (`errors` carries the
+ * per-item failures; a partial failure is never silently swallowed, but it also never
+ * stops the rest of the teardown from being attempted).
+ */
+export const downDeployment = async (options) => {
+    const compiledOutputDirectory = path.resolve(options.compiledOutputDirectory);
+    const dockerCommand = options.dockerCommand ?? "docker";
+    const execFileImpl = options.execFile ?? defaultDockerTeardownExecFile;
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    const resolved = await readCanonicalDownRecord(compiledOutputDirectory, options.deploymentName);
+    const initialRecord = resolved.record;
+    assertDeploymentLifecycleCorrelation(initialRecord, options.expectedLifecycleCorrelation);
+    const runnerOptions = { dockerCommand, execFile: execFileImpl, timeoutMs };
+    if (resolved.mode === "image")
+        return imageDown(initialRecord, options, runnerOptions);
+    const record = await ensureExported(initialRecord, {
+        ...options,
+        compiledOutputDirectory,
+    });
+    assertDeploymentLifecycleCorrelation(record, options.expectedLifecycleCorrelation);
+    await closeOrganizationHandoff(record);
+    const unitsStopped = [];
+    const errors = [];
+    for (const unit of record.units) {
+        const containerRef = targetRefForUnit(unit);
+        if (!containerRef) {
+            errors.push(`unit ${unit.id} has no recorded container id or name; nothing to remove`);
+            continue;
+        }
+        const outcome = await removeDockerContainer(record.target, containerRef, runnerOptions);
+        if (outcome.removed) {
+            unitsStopped.push(unit.id);
+        }
+        else {
+            errors.push(`unable to remove container ${containerRef} (unit ${unit.id}): ${outcome.error}`);
+        }
+    }
+    const report = await readCompileReport(compiledOutputDirectory);
+    const { owned, skipped } = partitionDeclaredVolumes(report?.container?.persistent_mounts ?? [], (mount) => mount.volume_name);
+    // Declared volumes are retained unconditionally: they are shared project
+    // state, not this deployment's, so `--volumes` must never destroy them.
+    const retainedVolumes = [...skipped];
+    if (options.removeVolumes) {
+        for (const volumeName of owned) {
+            const outcome = await removeDockerVolume(record.target, volumeName, runnerOptions);
+            if (!outcome.removed) {
+                errors.push(`unable to remove volume ${volumeName}: ${outcome.error}`);
+                retainedVolumes.push(volumeName);
+            }
+        }
+    }
+    else {
+        retainedVolumes.push(...owned);
+    }
+    return {
+        deployment: record.name,
+        errors,
+        retained_volumes: retainedVolumes.sort(),
+        ...(skipped.length > 0 ? { skipped_volumes: skipped } : {}),
+        units_stopped: unitsStopped.sort(),
+        version: DOWN_RECEIPT_VERSION,
+    };
+};

package/dist/deployment/downReceiptTypes.d.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+/**
+ * `spawnfile.down-receipt.v1` — the machine contract `spawnfile down --json` writes to
+ * stdout (contracts.md's Spawnfile down-receipt registry row; Decision 21's Piece 4).
+ * `units_stopped` names the deployment record's own unit ids (`record.ts`'s
+ * `unit.id`, e.g. `"<deployment>-container"`), not raw Docker container ids, so a caller
+ * can cross-reference the up-receipt/deployment record without re-deriving anything.
+ * `retained_volumes` is "named volumes still present on disk after this call returns" —
+ * true whether they were never touched (the default), survived an attempted
+ * `--volumes` removal that failed (surfaced in `errors`, not silently dropped), or
+ * were deliberately skipped as shared project state (`skipped_volumes`).
+ *
+ * `skipped_volumes` is the third outcome this contract originally could not express.
+ * An author-declared volume name (a workspace resource `name`, a
+ * `store.persistence.name`, a memory bank's `persistence.name`) is verbatim in every
+ * mode and every deployment, so it is NOT "this deployment's named volume" — a
+ * `down --volumes` of a dev or scratch deployment would otherwise destroy the
+ * production state that same name refers to, whenever production happens to be
+ * stopped (Docker only refuses a volume that is currently in use). Those volumes are
+ * skipped, listed here AND in `retained_volumes`, and removing one is a deliberate
+ * project-level act: `docker volume rm <name>`.
+ *
+ * The field is OMITTED when nothing was skipped, so every receipt that could be
+ * produced before this existed is still byte-identical.
+ */
+export declare const DOWN_RECEIPT_VERSION: "spawnfile.down-receipt.v1";
+export declare const downReceiptSchema: z.ZodObject<{
+    version: z.ZodLiteral<"spawnfile.down-receipt.v1">;
+    deployment: z.ZodString;
+    units_stopped: z.ZodArray<z.ZodString>;
+    retained_volumes: z.ZodArray<z.ZodString>;
+    skipped_volumes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    errors: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type DownReceipt = z.infer<typeof downReceiptSchema>;
+export declare const parseDownReceipt: (raw: unknown) => DownReceipt;

package/dist/deployment/downReceiptTypes.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+/**
+ * `spawnfile.down-receipt.v1` — the machine contract `spawnfile down --json` writes to
+ * stdout (contracts.md's Spawnfile down-receipt registry row; Decision 21's Piece 4).
+ * `units_stopped` names the deployment record's own unit ids (`record.ts`'s
+ * `unit.id`, e.g. `"<deployment>-container"`), not raw Docker container ids, so a caller
+ * can cross-reference the up-receipt/deployment record without re-deriving anything.
+ * `retained_volumes` is "named volumes still present on disk after this call returns" —
+ * true whether they were never touched (the default), survived an attempted
+ * `--volumes` removal that failed (surfaced in `errors`, not silently dropped), or
+ * were deliberately skipped as shared project state (`skipped_volumes`).
+ *
+ * `skipped_volumes` is the third outcome this contract originally could not express.
+ * An author-declared volume name (a workspace resource `name`, a
+ * `store.persistence.name`, a memory bank's `persistence.name`) is verbatim in every
+ * mode and every deployment, so it is NOT "this deployment's named volume" — a
+ * `down --volumes` of a dev or scratch deployment would otherwise destroy the
+ * production state that same name refers to, whenever production happens to be
+ * stopped (Docker only refuses a volume that is currently in use). Those volumes are
+ * skipped, listed here AND in `retained_volumes`, and removing one is a deliberate
+ * project-level act: `docker volume rm <name>`.
+ *
+ * The field is OMITTED when nothing was skipped, so every receipt that could be
+ * produced before this existed is still byte-identical.
+ */
+export const DOWN_RECEIPT_VERSION = "spawnfile.down-receipt.v1";
+export const downReceiptSchema = z
+    .object({
+    version: z.literal(DOWN_RECEIPT_VERSION),
+    deployment: z.string().min(1),
+    units_stopped: z.array(z.string().min(1)),
+    retained_volumes: z.array(z.string().min(1)),
+    skipped_volumes: z.array(z.string().min(1)).optional(),
+    errors: z.array(z.string().min(1))
+})
+    .strict();
+export const parseDownReceipt = (raw) => {
+    const result = downReceiptSchema.safeParse(raw);
+    if (!result.success) {
+        throw new Error(`invalid ${DOWN_RECEIPT_VERSION}: ${result.error.issues
+            .map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`)
+            .join("; ")}`);
+    }
+    return result.data;
+};

package/dist/deployment/index.d.ts

@@ -1,10 +1,30 @@
+export * from "./artifactsExport.js";
+export * from "./artifactsExportDocker.js";
+export * from "./artifactsExportPlan.js";
+export * from "./artifactsExportTypes.js";
+export * from "./privateArtifactsExport.js";
+export * from "./buildImageCacheStore.js";
+export * from "./candidateDiagnostics.js";
 export * from "./dockerLabels.js";
 export * from "./dockerInspect.js";
 export * from "./dockerLogs.js";
 export * from "./dockerManager.js";
 export * from "./dockerProbeGateway.js";
 export * from "./dockerRecover.js";
+export * from "./dockerTeardown.js";
+export * from "./deploymentLifecycleCorrelation.js";
+export * from "./downDeployment.js";
+export * from "./downReceiptTypes.js";
 export * from "./homeStore.js";
+export * from "./lifecycleCompletion.js";
+export * from "./lifecycleUpRecords.js";
 export * from "./names.js";
+export * from "./organizationHandoffTypes.js";
+export * from "./organizationHandoffAuthorityTypes.js";
+export * from "./organizationHandoffAuthorityStore.js";
+export * from "./organizationReady.js";
+export * from "./canaryCutover.js";
+export * from "./productStateClone.js";
 export * from "./record.js";
 export * from "./target.js";
+export * from "./upReceiptTypes.js";