spawnfile 0.1.13 → 0.1.14

package/dist/deployment/dockerManager.js

@@ -1,9 +1,29 @@
 import path from "node:path";
 import { normalizeProjectLabelSlug } from "../distribution/index.js";
+import { resolveNoopolisRunId } from "../runtime/index.js";
 import { SpawnfileError } from "../shared/index.js";
+import { inspectDockerDeployment } from "./dockerInspect.js";
 import { normalizeDeploymentName } from "./names.js";
+import { createDockerProbeGateway } from "./dockerProbeGateway.js";
+import { organizationReadinessFromProbeError, reconcileOrganizationReadiness } from "./organizationReady.js";
 import { resolveDockerDeploymentTarget } from "./target.js";
 import { writeDeploymentRecord } from "./record.js";
+import { createOrganizationHandoff } from "./organizationHandoffTypes.js";
+export const createDockerOrganizationHandoffSession = (input) => {
+    const organizationHandoff = createOrganizationHandoff(input.runId, input.organizationHandoff);
+    return Object.freeze({
+        authorityInput: Object.freeze({
+            bindingDigest: input.bindingDigest,
+            containerName: input.containerName,
+            deploymentLabels: input.deploymentLabels,
+            descriptorDigest: input.descriptorDigest,
+            handoff: organizationHandoff,
+            selectedTarget: input.selectedTarget,
+            selectedTargetReceiptDigest: input.selectedTargetReceiptDigest
+        }),
+        organizationHandoff
+    });
+};
 const resolveProjectSlug = (projectRoot) => {
     const base = path.basename(projectRoot).toLowerCase() === "spawnfile"
         ? path.basename(path.dirname(projectRoot))
@@ -24,13 +44,25 @@ export const createDockerDeploymentRecord = (input) => {
         manager: "docker",
         name,
         output_directory: path.resolve(input.outputDirectory),
+        ...(input.runId ? { run_id: input.runId } : {}),
+        ...(input.runId && input.organizationHandoff
+            ? { organization_handoff: createOrganizationHandoff(input.runId, input.organizationHandoff) }
+            : {}),
+        ...(input.runId && input.organizationHandoff && input.organizationHandoffHandle
+            ? { organization_handoff_handle: input.organizationHandoffHandle }
+            : {}),
         source: input.source ?? { kind: "project", root: path.resolve(input.projectRoot) },
         target: input.target,
         units: [
             {
                 container_id: input.runMetadata?.containerId ?? null,
                 container_name: input.containerName,
-                contains: input.nodes.map((node) => ({ id: node.id, kind: node.kind })),
+                contains: [
+                    ...input.nodes.map((node) => ({ id: node.id, kind: node.kind })),
+                    ...[...new Set(input.networkIds ?? [])]
+                        .sort()
+                        .map((id) => ({ id, kind: "network" }))
+                ],
                 id: createDockerDeploymentUnitId(name),
                 image_id: input.runMetadata?.imageId ?? null,
                 image_tag: input.imageTag,
@@ -60,9 +92,20 @@ export const writeDockerDeploymentRecordForRun = async (input) => {
         deploymentName: input.invocation.deploymentName,
         envFilePath: input.envFilePath,
         imageTag: input.imageTag,
+        networkIds: input.report.container?.moltnet?.server_plans
+            .filter((server) => server.mode === "managed")
+            .map((server) => server.network_id),
         nodes: input.report.nodes,
         outputDirectory: input.outputDirectory,
+        ...(input.organizationHandoff ? { organizationHandoff: input.organizationHandoff } : {}),
+        ...(input.organizationHandoffHandle ? { organizationHandoffHandle: input.organizationHandoffHandle } : {}),
         projectRoot: input.report.root,
+        // Sourced from the host process env at record-write time, not the
+        // compile report: `spawnfile run`/`up --detach` always call
+        // ensureNoopolisRunId() before compiling (src/compiler/CLAUDE.md), so by
+        // the time this record is written the run id — if any — is already on
+        // process.env. A bare host env with no run id yields no `run_id` field.
+        runId: resolveNoopolisRunId(process.env),
         runMetadata: input.runMetadata,
         runtimeInstanceIds: input.report.container?.runtime_instances.map((instance) => instance.id) ?? [],
         target: await resolveDockerDeploymentTarget({
@@ -74,3 +117,77 @@ export const writeDockerDeploymentRecordForRun = async (input) => {
         })
     });
 };
+const recordCorrelation = (record) => ({
+    compileFingerprint: record.compile_fingerprint,
+    deploymentName: record.name,
+    runId: record.run_id ?? null,
+    unitCount: record.units.length,
+    unitId: record.units[0]?.id ?? "invalid-unit"
+});
+/**
+ * Performs the single manager-owned inspection, public health checks, and
+ * bounded artifact reads needed to reconcile immutable compiler evidence.
+ * It deliberately returns a safe value only; upProject owns both persistence writes.
+ */
+export const probeDockerOrganizationReadiness = async (input) => {
+    const correlation = recordCorrelation(input.record);
+    try {
+        const inspections = await inspectDockerDeployment(input.record, {
+            dockerCommand: input.dockerCommand,
+            execFile: input.execFile,
+            timeoutMs: input.timeoutMs
+        });
+        const unit = input.record.units[0];
+        const inspected = unit ? inspections.get(unit.id) ?? null : null;
+        if (!unit || !inspected) {
+            return reconcileOrganizationReadiness({
+                evidence: input.evidence, inspection: null, probe: null, record: correlation
+            });
+        }
+        const gateway = createDockerProbeGateway(input.record, unit, {
+            dockerCommand: input.dockerCommand,
+            execFile: input.execFile,
+            inspection: inspected,
+            timeoutMs: input.timeoutMs
+        });
+        const inspection = await gateway.inspectUnit();
+        if (input.evidence.hasExternalMoltnet || !input.evidence.worldBindings) {
+            return reconcileOrganizationReadiness({
+                evidence: input.evidence, inspection, probe: null, record: correlation
+            });
+        }
+        const networks = [];
+        for (const network of input.evidence.networks) {
+            if (network.mode !== "managed" || network.internalPort === null) {
+                return reconcileOrganizationReadiness({
+                    evidence: input.evidence, inspection, probe: null, record: correlation
+                });
+            }
+            const health = await gateway.httpGet(network.internalPort, "/healthz");
+            if (!health.ok) {
+                return organizationReadinessFromProbeError(input.evidence, correlation, new Error(health.error ?? "probe unavailable"));
+            }
+            networks.push({
+                healthOk: health.ok,
+                id: network.id
+            });
+        }
+        const configs = new Map();
+        for (const network of input.evidence.networks) {
+            for (const node of network.nodes) {
+                const result = await gateway.exec(["cat", node.configPath]);
+                configs.set(node.configPath, result.stdout);
+            }
+        }
+        const bindings = await gateway.exec(["cat", input.evidence.worldBindings.artifactPath]);
+        return reconcileOrganizationReadiness({
+            evidence: input.evidence,
+            inspection,
+            probe: { configs, networks, worldBindings: bindings.stdout },
+            record: correlation
+        });
+    }
+    catch (error) {
+        return organizationReadinessFromProbeError(input.evidence, correlation, error);
+    }
+};

package/dist/deployment/dockerProbeGateway.js

@@ -19,6 +19,63 @@ 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;
@@ -30,15 +87,17 @@ export const createDockerProbeGateway = (record, unit, options) => {
     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)), { 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,34 @@
+import { type DeploymentLifecycleCorrelation } from "./deploymentLifecycleCorrelation.js";
+import { type DockerTeardownExecFile } from "./dockerTeardown.js";
+import { type DownReceipt } from "./downReceiptTypes.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;
+}
+/**
+ * `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,147 @@
+import path from "node:path";
+import { fileExists, readUtf8File } from "../filesystem/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";
+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 initialRecord = await readDeploymentRecordFromOutput(compiledOutputDirectory, options.deploymentName);
+    assertDeploymentLifecycleCorrelation(initialRecord, options.expectedLifecycleCorrelation);
+    const record = await ensureExported(initialRecord, {
+        ...options,
+        compiledOutputDirectory,
+    });
+    assertDeploymentLifecycleCorrelation(record, options.expectedLifecycleCorrelation);
+    await closeOrganizationHandoff(record);
+    const runnerOptions = { dockerCommand, execFile: execFileImpl, timeoutMs };
+    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 volumeNames = [
+        ...new Set((report?.container?.persistent_mounts ?? []).map((mount) => mount.volume_name)),
+    ].sort();
+    const retainedVolumes = [];
+    if (options.removeVolumes) {
+        for (const volumeName of volumeNames) {
+            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(...volumeNames);
+    }
+    return {
+        deployment: record.name,
+        errors,
+        retained_volumes: retainedVolumes.sort(),
+        units_stopped: unitsStopped.sort(),
+        version: DOWN_RECEIPT_VERSION,
+    };
+};

package/dist/deployment/downReceiptTypes.d.ts

@@ -0,0 +1,21 @@
+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) or survived an attempted
+ * `--volumes` removal that failed (surfaced in `errors`, not silently dropped).
+ */
+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>;
+    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,30 @@
+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) or survived an attempted
+ * `--volumes` removal that failed (surfaced in `errors`, not silently dropped).
+ */
+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)),
+    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,26 @@
+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 "./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 "./names.js";
+export * from "./organizationHandoffTypes.js";
+export * from "./organizationHandoffAuthorityTypes.js";
+export * from "./organizationHandoffAuthorityStore.js";
+export * from "./organizationReady.js";
 export * from "./record.js";
 export * from "./target.js";
+export * from "./upReceiptTypes.js";

package/dist/deployment/index.js

@@ -1,10 +1,27 @@
+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 "./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 "./names.js";
+export * from "./organizationHandoffTypes.js";
+export * from "./organizationHandoffAuthorityTypes.js";
+export * from "./organizationHandoffAuthorityStore.js";
+export * from "./organizationReady.js";
 export * from "./record.js";
+// Compatibility target exports remain available from this legacy deployment barrel.
 export * from "./target.js";
+export * from "./upReceiptTypes.js";