spawnfile 0.1.14 → 0.1.18

package/dist/deployment/canaryCutover.js

@@ -0,0 +1,140 @@
+import { createHash } from "node:crypto";
+import { execFile as execFileCallback } from "node:child_process";
+import { link, open, readFile, rm } from "node:fs/promises";
+import { promisify } from "node:util";
+import path from "node:path";
+import { z } from "zod";
+import { SpawnfileError } from "../shared/index.js";
+import { parseUpReceipt } from "./upReceiptTypes.js";
+import { parseDownReceipt } from "./downReceiptTypes.js";
+const execFile = promisify(execFileCallback);
+const digest = z.string().regex(/^sha256:[a-f0-9]{64}$/u), runId = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/u), nonce = z.string().regex(/^[a-f0-9]{32}$/u);
+const ingressReceiptSchema = z.object({ version: z.literal("spawnfile.ingress-cutover-receipt.v1"), state: z.literal("switched"), nonce, from_deployment: z.string().min(1), to_deployment: z.string().min(1), target_run_id: runId, readiness_sha256: digest }).strict();
+const decisionReceiptSchema = z.object({ version: z.literal("spawnfile.canary-decision-receipt.v1"), decision: z.literal("cutover"), nonce, target_run_id: runId, deployment_mode: z.enum(["project", "image"]), target_identity_sha256: digest, ingress_receipt_sha256: digest, teardown_checkpoint_sha256: digest, down_receipt_sha256: digest }).strict();
+const reportSchema = z.object({
+    persistent_mounts: z.array(z.object({
+        id: z.string().min(1),
+        lifecycle: z.literal("exclusive-reattach").optional()
+    }).passthrough()).max(4096).optional().default([]),
+    published_ports: z.array(z.number().int().min(1).max(65535)).max(64)
+}).passthrough();
+export const deploymentIdentitySchema = z.object({ version: z.literal("spawnfile.deployment-identity.v1"), run_id: runId, fingerprint: z.string().min(1), deployment_name: z.string().min(1), deployment_mode: z.enum(["project", "image"]), image_id: z.string().regex(/^sha256:[a-f0-9]{64}$/u), organization_unit_id: z.string().min(1), organization_compile_fingerprint: z.string().min(1), organization_world_binding_digest: digest.nullable(), topology_sha256: digest }).strict();
+const execute = async (command, args) => (await execFile(command, args, { encoding: "utf8", timeout: 30_000, maxBuffer: 1_048_576 })).stdout;
+const inspect = async (command, args) => (await execFile(command, args, { encoding: "utf8", timeout: 10_000, maxBuffer: 1_048_576 })).stdout;
+const sha = (bytes) => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+const canonical = (value) => JSON.stringify(value, (_key, item) => item && typeof item === "object" && !Array.isArray(item) ? Object.fromEntries(Object.entries(item).sort(([left], [right]) => left.localeCompare(right))) : item);
+const topologyDigest = (receipt) => sha(canonical({ compiled_schedule: receipt.compiled_schedule, engines: receipt.engines ?? [], moltnet_release: receipt.moltnet_release ?? null }));
+export const verifyCandidatePortIsolation = (liveReport, candidateReport) => {
+    const liveReportValue = reportSchema.parse(liveReport), candidateReportValue = reportSchema.parse(candidateReport);
+    const live = new Set(liveReportValue.published_ports), candidate = candidateReportValue.published_ports;
+    if (candidate.some((port) => live.has(port)) || new Set(candidate).size !== candidate.length)
+        throw new SpawnfileError("validation_error", "Candidate published ports are not mechanically isolated from live");
+    const liveMounts = new Map(liveReportValue.persistent_mounts.map((mount) => [mount.id, mount]));
+    const sharedExclusive = candidateReportValue.persistent_mounts.find((mount) => liveMounts.has(mount.id)
+        && (mount.lifecycle === "exclusive-reattach" || liveMounts.get(mount.id)?.lifecycle === "exclusive-reattach"));
+    if (sharedExclusive)
+        throw new SpawnfileError("validation_error", `Candidate shares exclusive persistent mount ${sharedExclusive.id}; use stop-and-reattach deployment instead of concurrent canary`);
+    return candidate;
+};
+const verifyIdentity = (receipt, expected) => {
+    const ready = receipt.organization_ready;
+    if (receipt.run_id !== expected.run_id || receipt.fingerprint !== expected.fingerprint || receipt.deployment.name !== expected.deployment_name || ready?.state !== "ready" || ready.unit_id !== expected.organization_unit_id || ready.compile_fingerprint !== expected.organization_compile_fingerprint || ready.world_binding_digest !== expected.organization_world_binding_digest || topologyDigest(receipt) !== expected.topology_sha256)
+        throw new SpawnfileError("validation_error", "Readiness does not bind the exact intended deployment identity and topology");
+};
+export const issueDeploymentIdentity = async (readinessPath, deploymentMode, dockerCommand, imageInspect = inspect) => {
+    const receipt = parseUpReceipt(JSON.parse(await readFile(readinessPath, "utf8"))), ready = receipt.organization_ready;
+    if (receipt.run_id === null || receipt.deployment.name === null || receipt.deployment.container_ids.length < 1 || ready?.state !== "ready")
+        throw new SpawnfileError("validation_error", "Deployment is not identity-ready");
+    const images = await Promise.all(receipt.deployment.container_ids.map(async (container) => (await imageInspect(dockerCommand, ["inspect", "--format", "{{.Image}}", container])).trim()));
+    if (!images[0] || images.some((image) => image !== images[0]))
+        throw new SpawnfileError("validation_error", "Deployment containers do not share one exact image identity");
+    return deploymentIdentitySchema.parse({ version: "spawnfile.deployment-identity.v1", run_id: receipt.run_id, fingerprint: receipt.fingerprint, deployment_name: receipt.deployment.name, deployment_mode: deploymentMode, image_id: images[0], organization_unit_id: ready.unit_id, organization_compile_fingerprint: ready.compile_fingerprint, organization_world_binding_digest: ready.world_binding_digest, topology_sha256: topologyDigest(receipt) });
+};
+const syncParent = async (filePath) => { const directory = await open(path.dirname(filePath), "r"); try {
+    await directory.sync();
+}
+finally {
+    await directory.close();
+} };
+const publishExclusive = async (filePath, value) => { const temporary = `${filePath}.tmp-${process.pid}`; const file = await open(temporary, "wx", 0o600); try {
+    await file.writeFile(`${JSON.stringify(value)}\n`);
+    await file.sync();
+}
+finally {
+    await file.close();
+} try {
+    await link(temporary, filePath);
+    await syncParent(filePath);
+}
+finally {
+    await rm(temporary, { force: true });
+    await syncParent(filePath);
+} };
+const exists = async (filePath) => await readFile(filePath).then(() => true, (error) => error.code === "ENOENT" ? false : Promise.reject(error));
+export const runCanaryCutover = async (input, runner = execute, imageInspect = inspect) => {
+    const expected = deploymentIdentitySchema.parse(input.expectedIdentity), operationNonce = nonce.parse(input.nonce);
+    if (input.ingressArgs.length > 32 || input.teardownArgs.length > 32 || [...input.ingressArgs, ...input.teardownArgs].some((arg) => arg.length > 4096))
+        throw new SpawnfileError("validation_error", "Canary command arguments exceed bounds");
+    const lifecycleId = `lci_canary_${operationNonce}`, exportIndex = input.teardownArgs.indexOf("--export-to"), prefix = ["down", input.teardownProjectPath, "--compiled", input.teardownCompiledPath, "--deployment", input.fromDeployment], expectedTeardownArgs = input.teardownPolicy === "export" ? [...prefix, "--export-to", input.teardownArgs[exportIndex + 1] ?? "", "--json", "--lifecycle-invocation", lifecycleId] : [...prefix, "--force", "--json", "--lifecycle-invocation", lifecycleId];
+    const canonicalPath = (value) => path.isAbsolute(value) && path.resolve(value) === value && path.normalize(value) === value;
+    if (!canonicalPath(input.teardownProjectPath) || !canonicalPath(input.teardownCompiledPath) || path.basename(input.teardownCommand) !== "spawnfile" || (input.teardownPolicy === "export" && (exportIndex < 0 || !expectedTeardownArgs[7])) || canonical(input.teardownArgs) !== canonical(expectedTeardownArgs))
+        throw new SpawnfileError("validation_error", "Teardown is not the exact canonical Spawnfile lifecycle down operation");
+    verifyCandidatePortIsolation(JSON.parse(await readFile(input.liveReportPath, "utf8")), JSON.parse(await readFile(input.candidateReportPath, "utf8")));
+    const readinessBytes = await readFile(input.readinessPath), readiness = parseUpReceipt(JSON.parse(readinessBytes.toString("utf8")));
+    verifyIdentity(readiness, expected);
+    if (readiness.deployment.container_ids.length < 1)
+        throw new SpawnfileError("validation_error", "Ready deployment has no image-bearing containers");
+    for (const container of readiness.deployment.container_ids)
+        if ((await imageInspect(input.dockerCommand, ["inspect", "--format", "{{.Image}}", container])).trim() !== expected.image_id)
+            throw new SpawnfileError("validation_error", "Ready deployment image does not match intended identity");
+    const binding = sha(canonical({ ...input, expectedIdentity: expected }));
+    const transaction = { version: "spawnfile.canary-transaction.v1", state: "reserved", nonce: operationNonce, binding_sha256: binding };
+    const recovering = await exists(input.transactionPath);
+    if (recovering) {
+        const prior = JSON.parse(await readFile(input.transactionPath, "utf8"));
+        if (prior.version !== transaction.version || prior.nonce !== operationNonce || prior.binding_sha256 !== binding)
+            throw new SpawnfileError("validation_error", "Canary transaction authority does not match");
+    }
+    else {
+        if (await exists(input.ingressReceiptPath) || await exists(input.decisionReceiptPath))
+            throw new SpawnfileError("validation_error", "Stale canary receipt exists before transaction reservation");
+        await publishExclusive(input.transactionPath, transaction);
+    }
+    if (!await exists(input.ingressReceiptPath))
+        await runner(input.ingressCommand, input.ingressArgs);
+    const ingressBytes = await readFile(input.ingressReceiptPath), ingress = ingressReceiptSchema.parse(JSON.parse(ingressBytes.toString("utf8")));
+    if (ingress.nonce !== operationNonce || ingress.from_deployment !== input.fromDeployment || ingress.to_deployment !== input.toDeployment || ingress.target_run_id !== expected.run_id || ingress.readiness_sha256 !== sha(readinessBytes))
+        throw new SpawnfileError("validation_error", "Ingress receipt does not bind the exact ready target and transaction nonce");
+    const teardownStartedPath = `${input.transactionPath}.teardown-started`, teardownReceiptPath = `${input.transactionPath}.teardown-receipt`, teardownCheckpointPath = `${input.transactionPath}.teardown-complete`, checkpointBase = { nonce: operationNonce, binding_sha256: binding, ingress_receipt_sha256: sha(ingressBytes), lifecycle_invocation: lifecycleId };
+    if (!await exists(teardownCheckpointPath)) {
+        if (await exists(input.decisionReceiptPath))
+            throw new SpawnfileError("validation_error", "Canary decision exists without its teardown checkpoint");
+        if (!await exists(teardownStartedPath))
+            await publishExclusive(teardownStartedPath, { version: "spawnfile.canary-teardown-started.v1", ...checkpointBase });
+        if (!await exists(teardownReceiptPath)) {
+            const output = await runner(input.teardownCommand, input.teardownArgs), down = parseDownReceipt(JSON.parse(typeof output === "string" ? output : ""));
+            if (down.deployment !== input.fromDeployment || down.errors.length !== 0)
+                throw new SpawnfileError("validation_error", "Down receipt does not prove exact teardown completion");
+            await publishExclusive(teardownReceiptPath, down);
+        }
+        const downBytes = await readFile(teardownReceiptPath), down = parseDownReceipt(JSON.parse(downBytes.toString("utf8")));
+        if (down.deployment !== input.fromDeployment || down.errors.length !== 0)
+            throw new SpawnfileError("validation_error", "Stored down receipt does not bind the teardown operation");
+        await publishExclusive(teardownCheckpointPath, { version: "spawnfile.canary-teardown-checkpoint.v1", ...checkpointBase, down_receipt_sha256: sha(downBytes) });
+    }
+    else {
+        const downBytes = await readFile(teardownReceiptPath), down = parseDownReceipt(JSON.parse(downBytes.toString("utf8"))), expectedCheckpoint = { version: "spawnfile.canary-teardown-checkpoint.v1", ...checkpointBase, down_receipt_sha256: sha(downBytes) };
+        if (down.deployment !== input.fromDeployment || down.errors.length !== 0 || canonical(JSON.parse(await readFile(teardownCheckpointPath, "utf8"))) !== canonical(expectedCheckpoint))
+            throw new SpawnfileError("validation_error", "Canary teardown checkpoint does not match the recovered transaction");
+    }
+    const checkpointBytes = await readFile(teardownCheckpointPath), downBytes = await readFile(teardownReceiptPath), decision = { version: "spawnfile.canary-decision-receipt.v1", decision: "cutover", nonce: operationNonce, target_run_id: expected.run_id, deployment_mode: expected.deployment_mode, target_identity_sha256: sha(canonical(expected)), ingress_receipt_sha256: sha(ingressBytes), teardown_checkpoint_sha256: sha(checkpointBytes), down_receipt_sha256: sha(downBytes) };
+    if (!await exists(input.decisionReceiptPath)) {
+        await publishExclusive(input.decisionReceiptPath, decision);
+        return decision;
+    }
+    const priorDecision = decisionReceiptSchema.parse(JSON.parse(await readFile(input.decisionReceiptPath, "utf8")));
+    if (canonical(priorDecision) !== canonical(decision))
+        throw new SpawnfileError("validation_error", "Canary decision receipt does not match the recovered transaction");
+    return priorDecision;
+};
+export const verifyEquivalentRollbackReadiness = async (rollbackReadinessPath, expectedIdentity) => { const expected = deploymentIdentitySchema.parse(expectedIdentity), rollback = parseUpReceipt(JSON.parse(await readFile(rollbackReadinessPath, "utf8"))); verifyIdentity(rollback, expected); };

package/dist/deployment/candidateDiagnostics.d.ts

@@ -0,0 +1,15 @@
+import type { DockerCommandRunner } from "../distribution/dockerRunner.js";
+export interface CandidateDiagnosticsInput {
+    candidateId: string;
+    deploymentName: string;
+    runDocker: DockerCommandRunner;
+    secretValues: string[];
+}
+export interface CandidateDiagnosticsResult {
+    path: string | null;
+    summary: string;
+}
+/** Redaction is best effort; diagnostic artifacts remain private operator data. */
+export declare const sanitizeCandidateDiagnostic: (text: string, secrets: string[]) => string;
+/** Collect before rollback deletes the only container-local startup evidence. */
+export declare const captureCandidateDiagnostics: (input: CandidateDiagnosticsInput) => Promise<CandidateDiagnosticsResult>;

package/dist/deployment/candidateDiagnostics.js

@@ -0,0 +1,90 @@
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { resolveSpawnfileHome } from "../auth/index.js";
+import { redactDockerLogText } from "./dockerLogs.js";
+import { resolveHomeDeploymentDirectory } from "./homeStore.js";
+const outputLimit = 64 * 1024;
+const commandOptions = { captureStderr: true, maxOutputBytes: outputLimit, timeoutMs: 5_000 };
+const containerIdPattern = /^[a-f0-9]{64}$/u;
+/** Redaction is best effort; diagnostic artifacts remain private operator data. */
+export const sanitizeCandidateDiagnostic = (text, secrets) => redactDockerLogText(text, secrets)
+    .replace(/-----BEGIN [^-]*PRIVATE KEY-----[\s\S]*?(?:-----END [^-]*PRIVATE KEY-----|$)/gu, "[REDACTED PRIVATE KEY]")
+    .replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/gu, "[REDACTED JWT]")
+    .replace(/https?:\/\/[^\s<>"']+/giu, "[REDACTED URL]")
+    .replace(/\b([a-z0-9_-]*(?:authorization|cookie|password|secret|token|api[_-]?key)[a-z0-9_-]*)["']?\s*[:=]\s*[^\r\n]+/giu, "$1: [REDACTED]");
+const collect = async (runDocker, args) => {
+    try {
+        const bytes = await runDocker(args, commandOptions);
+        // Injectable runners must obey the same limit as the default Docker runner.
+        if (bytes.length > outputLimit)
+            throw new Error("limit");
+        return { available: true, text: bytes.toString("utf8") };
+    }
+    catch {
+        // Docker transport errors can contain command/env details; never persist them.
+        return { available: false, text: "Diagnostic command failed, timed out, or exceeded its byte limit" };
+    }
+};
+const summarizeState = (raw, secrets) => {
+    try {
+        const state = JSON.parse(raw);
+        const health = state.Health?.Status;
+        const status = ["created", "running", "paused", "restarting", "removing", "exited", "dead"].includes(String(state.Status))
+            ? state.Status : "unknown";
+        const parts = [`state=${status}`];
+        if (["starting", "healthy", "unhealthy"].includes(String(health)))
+            parts.push(`health=${health}`);
+        if (Number.isSafeInteger(state.ExitCode))
+            parts.push(`exit=${state.ExitCode}`);
+        if (state.OOMKilled === true)
+            parts.push("oom-killed");
+        const healthState = state.Health;
+        const text = (value) => typeof value === "string"
+            ? sanitizeCandidateDiagnostic(value, secrets).slice(0, 4_096) : "";
+        return { available: true, summary: parts.join(", "), error: text(state.Error),
+            healthOutput: Array.isArray(healthState?.Log) ? healthState.Log.slice(-3).map((entry) => text(entry && typeof entry === "object" ? entry.Output : null)) : [] };
+    }
+    catch {
+        return { available: false, summary: "state unavailable", error: "", healthOutput: [] };
+    }
+};
+/** Collect before rollback deletes the only container-local startup evidence. */
+export const captureCandidateDiagnostics = async (input) => {
+    if (!containerIdPattern.test(input.candidateId))
+        return { path: null, summary: "invalid candidate identity" };
+    const [state, logs] = await Promise.all([
+        collect(input.runDocker, ["container", "inspect", "--format", "{{json .State}}", input.candidateId]),
+        collect(input.runDocker, ["logs", "--tail", "100", input.candidateId])
+    ]);
+    const health = summarizeState(state.available ? state.text : "", input.secretValues);
+    const summary = health.summary;
+    try {
+        const deploymentDirectory = resolveHomeDeploymentDirectory(input.deploymentName);
+        for (const parent of [resolveSpawnfileHome(), path.dirname(deploymentDirectory), deploymentDirectory]) {
+            const info = await lstat(parent);
+            if (!info.isDirectory() || info.isSymbolicLink() || (info.mode & 0o022) !== 0
+                || (process.getuid && info.uid !== process.getuid()))
+                throw new Error("unsafe diagnostics parent");
+        }
+        const directory = path.join(deploymentDirectory, "diagnostics");
+        await mkdir(directory, { mode: 0o700 }).catch((error) => {
+            if (error.code !== "EEXIST")
+                throw error;
+        });
+        const info = await lstat(directory);
+        if (!info.isDirectory() || info.isSymbolicLink() || (info.mode & 0o777) !== 0o700
+            || (process.getuid && info.uid !== process.getuid()))
+            throw new Error("unsafe diagnostics directory");
+        const destination = path.join(directory, `candidate-${Date.now()}-${randomUUID()}.json`);
+        await writeFile(destination, `${JSON.stringify({
+            version: "spawnfile.candidate-diagnostics.v1", capturedAt: new Date().toISOString(),
+            candidateId: input.candidateId, deployment: input.deploymentName, summary, health,
+            logs: { available: logs.available, text: sanitizeCandidateDiagnostic(logs.text, input.secretValues) }
+        }, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+        return { path: destination, summary };
+    }
+    catch {
+        return { path: null, summary };
+    }
+};

package/dist/deployment/candidateRecording.d.ts

@@ -0,0 +1,8 @@
+import { type DeploymentActivation, type DeployResourceReport, type DeployResources } from "./resourceLog.js";
+/** A candidate may execute turns before failing readiness/publication. Preserve its pins
+ * after rollback, without replacing the still-authoritative predecessor's record. */
+export declare const recordDeploymentRollback: (recordPath: string, record: DeploymentActivation & {
+    name: string;
+    created_at: string;
+    resource_snapshot?: DeployResources;
+}, report: DeployResourceReport, reportBytes: string, rolledBackAt: string) => Promise<void>;

package/dist/deployment/candidateRecording.js

@@ -0,0 +1,22 @@
+import path from "node:path";
+import { ensureDirectory } from "../filesystem/index.js";
+import { acquirePidLock } from "./pidLock.js";
+import { createDeployResources, ensureDeployResources } from "./resourceLog.js";
+/** A candidate may execute turns before failing readiness/publication. Preserve its pins
+ * after rollback, without replacing the still-authoritative predecessor's record. */
+export const recordDeploymentRollback = async (recordPath, record, report, reportBytes, rolledBackAt) => {
+    if (!report.recording)
+        return;
+    await ensureDirectory(path.dirname(recordPath));
+    const release = await acquirePidLock(`${recordPath}.resource-log.lock`);
+    try {
+        ensureDeployResources(recordPath, {
+            ...(record.resource_snapshot ?? createDeployResources(recordPath, record, report, reportBytes)),
+            rolled_back_at: rolledBackAt, activation_exact: false, exact: false,
+            activation_note: "Candidate ran before rollback; its turns cannot be distinguished from predecessor turns"
+        }, report.recording.keep_ms);
+    }
+    finally {
+        await release();
+    }
+};

package/dist/deployment/dockerLogs.js

@@ -15,10 +15,13 @@ const withDockerTarget = (record, args) => {
     return args;
 };
 const normalizeTail = (tail) => typeof tail === "number" && Number.isInteger(tail) && tail > 0 ? tail : 100;
+const stripTerminalControls = (value) => value.replace(/\x1b\[[0-?]*[ -/]*[@-~]|[\x00-\x08\x0b-\x1f\x7f]/gu, "");
 const redactKnownSecrets = (text, secretValues) => secretValues
+    .map(stripTerminalControls)
     .filter((secret) => secret.length > 0)
+    .sort((left, right) => right.length - left.length)
     .reduce((redacted, secret) => redacted.replaceAll(secret, "[REDACTED]"), text);
-export const redactDockerLogText = (text, secretValues = []) => redactSensitiveText(redactKnownSecrets(text, secretValues));
+export const redactDockerLogText = (text, secretValues = []) => redactSensitiveText(redactKnownSecrets(stripTerminalControls(text), secretValues));
 const combineLogStreams = (stdout, stderr) => {
     if (!stdout) {
         return stderr;

package/dist/deployment/dockerManager.d.ts

@@ -1,5 +1,6 @@
 import type { DeploymentRecordSource } from "./record.js";
 import type { OrganizationReadinessEvidence } from "../compiler/organizationReadyEvidence.js";
+import type { DeploymentActivation, DeployResourceReport } from "./resourceLog.js";
 import { type DockerProbeExecFile } from "./dockerProbeGateway.js";
 import { type OrganizationReadiness } from "./organizationReady.js";
 import { type DockerDeploymentTarget, type DockerTargetExecFile } from "./target.js";
@@ -22,7 +23,7 @@ export interface DockerDeploymentRunInvocationInput {
     dockerContext?: string | null;
     dockerHost?: string | null;
 }
-export interface DockerDeploymentReportInput {
+export interface DockerDeploymentReportInput extends DeployResourceReport {
     compile_fingerprint?: string;
     container?: {
         moltnet?: {
@@ -38,7 +39,7 @@ export interface DockerDeploymentReportInput {
     nodes: DockerDeploymentNodeInput[];
     root: string;
 }
-export interface WriteDockerDeploymentRecordInput {
+export interface WriteDockerDeploymentRecordInput extends DeploymentActivation {
     authProfileName: string | null;
     compileFingerprint: string;
     containerName: string | null;
@@ -82,7 +83,8 @@ export declare const createDockerDeploymentUnitId: (deploymentName: string) => s
 export declare const createDockerDeploymentRecord: (input: WriteDockerDeploymentRecordInput) => DeploymentRecord;
 export declare const createDockerProjectLabel: (projectRoot: string, projectName?: string) => string;
 export declare const writeDockerDeploymentRecord: (input: WriteDockerDeploymentRecordInput) => Promise<string>;
-export declare const writeDockerDeploymentRecordForRun: (input: {
+export declare const writeDockerDeploymentRecordForRun: (input: DeploymentActivation & {
+    previousRecord?: DeploymentRecord;
     authProfileName: string | null;
     envFilePath?: string;
     imageTag: string;

package/dist/deployment/dockerManager.js

@@ -3,7 +3,10 @@ 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 { bindDeploymentRecording } from "./recordPublication.js";
+import { readUtf8File } from "../filesystem/index.js";
+import { REPORT_FILENAME } from "../shared/index.js";
+import { normalizeDeploymentName, resolveDeploymentRecordPath } from "./names.js";
 import { createDockerProbeGateway } from "./dockerProbeGateway.js";
 import { organizationReadinessFromProbeError, reconcileOrganizationReadiness } from "./organizationReady.js";
 import { resolveDockerDeploymentTarget } from "./target.js";
@@ -40,6 +43,7 @@ export const createDockerDeploymentRecord = (input) => {
         auth_profile: input.authProfileName,
         compile_fingerprint: input.compileFingerprint,
         created_at: new Date().toISOString(),
+        ...(input.activated_at ? { activated_at: input.activated_at, activation_exact: input.activation_exact, activation_note: input.activation_note } : {}),
         ...(input.envFilePath ? { env_file: path.resolve(input.envFilePath) } : {}),
         manager: "docker",
         name,
@@ -85,7 +89,8 @@ export const writeDockerDeploymentRecordForRun = async (input) => {
     if (!input.invocation.detach || !input.invocation.deploymentName) {
         return null;
     }
-    return writeDockerDeploymentRecord({
+    const record = createDockerDeploymentRecord({
+        activated_at: input.activated_at, activation_exact: input.activation_exact, activation_note: input.activation_note,
         authProfileName: input.authProfileName,
         compileFingerprint: requireCompileFingerprint(input.report.compile_fingerprint),
         containerName: input.invocation.containerName,
@@ -116,6 +121,11 @@ export const writeDockerDeploymentRecordForRun = async (input) => {
             timeoutMs: input.targetTimeoutMs
         })
     });
+    const recordPath = resolveDeploymentRecordPath(input.outputDirectory, record.name);
+    const bound = input.report.recording
+        ? bindDeploymentRecording(recordPath, record, input.report, await readUtf8File(path.join(input.outputDirectory, REPORT_FILENAME)))
+        : record;
+    return writeDeploymentRecord(input.outputDirectory, bound, input.previousRecord);
 };
 const recordCorrelation = (record) => ({
     compileFingerprint: record.compile_fingerprint,
@@ -151,7 +161,7 @@ export const probeDockerOrganizationReadiness = async (input) => {
             timeoutMs: input.timeoutMs
         });
         const inspection = await gateway.inspectUnit();
-        if (input.evidence.hasExternalMoltnet || !input.evidence.worldBindings) {
+        if (input.evidence.hasExternalMoltnet) {
             return reconcileOrganizationReadiness({
                 evidence: input.evidence, inspection, probe: null, record: correlation
             });
@@ -173,17 +183,23 @@ export const probeDockerOrganizationReadiness = async (input) => {
             });
         }
         const configs = new Map();
+        const attachmentReceipts = 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 receipt = await gateway.exec(["cat", node.receiptPath]);
+                attachmentReceipts.set(node.receiptPath, receipt.stdout);
             }
         }
-        const bindings = await gateway.exec(["cat", input.evidence.worldBindings.artifactPath]);
+        const daimonReceipt = input.evidence.daimon == null ? null : (await gateway.exec(["cat", input.evidence.daimon.receiptPath])).stdout;
+        const bindings = input.evidence.worldBindings === null
+            ? null
+            : await gateway.exec(["cat", input.evidence.worldBindings.artifactPath]);
         return reconcileOrganizationReadiness({
             evidence: input.evidence,
             inspection,
-            probe: { configs, networks, worldBindings: bindings.stdout },
+            probe: { attachmentReceipts, configs, daimonReceipt, networks, worldBindings: bindings?.stdout ?? null },
             record: correlation
         });
     }

package/dist/deployment/dockerProbeGateway.d.ts

@@ -1,7 +1,21 @@
 import type { RuntimeProbeGateway } from "../runtime/index.js";
 import type { DeploymentRecord } from "./record.js";
 import type { DockerUnitInspection } from "./dockerInspect.js";
+/**
+ * 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 declare const DEFAULT_DOCKER_PROBE_MAX_BUFFER_BYTES: number;
 export type DockerProbeExecFile = (file: string, args: string[], options: {
+    maxBuffer?: number;
     timeout: number;
 }) => Promise<{
     stderr: string;
@@ -11,6 +25,9 @@ export interface DockerProbeGatewayOptions {
     dockerCommand?: string;
     execFile?: DockerProbeExecFile;
     inspection: DockerUnitInspection;
+    /** Overrides Node's 1 MiB `execFile` default `maxBuffer`. Defaults to
+     * {@link DEFAULT_DOCKER_PROBE_MAX_BUFFER_BYTES}. */
+    maxBufferBytes?: number;
     timeoutMs?: number;
 }
 export declare const createDockerProbeGateway: (record: DeploymentRecord, unit: DeploymentRecord["units"][number], options: DockerProbeGatewayOptions) => RuntimeProbeGateway;

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) {
@@ -80,9 +94,10 @@ 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,
@@ -93,7 +108,7 @@ export const createDockerProbeGateway = (record, unit, options) => {
             const url = `http://127.0.0.1:${port}${requestPath.startsWith("/") ? requestPath : `/${requestPath}`}`;
             try {
                 const targetRef = targetRefForUnit(unit);
-                const result = await runExec(dockerCommand, withDockerTarget(record, httpProbeArgs(targetRef, imageRefForUnit(unit), url)), { timeout });
+                const result = await runExec(dockerCommand, withDockerTarget(record, httpProbeArgs(targetRef, imageRefForUnit(unit), url)), { maxBuffer, timeout });
                 return parseCurlHttpOutput(result.stdout);
             }
             catch (error) {

package/dist/deployment/downDeployment.d.ts

@@ -1,6 +1,7 @@
 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`. */
@@ -20,9 +21,15 @@ export interface DownDeploymentOptions {
      * 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;
+    /** Explicitly permits deleting memory ledgers used by recording agents. */
+    discardRecordedMemory?: 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