spawnfile 0.1.17 → 0.1.18

package/dist/deployment/homeStore.js

@@ -1,84 +1,47 @@
 import path from "node:path";
-import { open, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { readdir } from "node:fs/promises";
 import { resolveSpawnfileHome } from "../auth/index.js";
-import { ensureDirectory, readUtf8File } from "../filesystem/index.js";
+import { ensureDirectory, readUtf8File, writeDurableFile } from "../filesystem/index.js";
 import { SpawnfileError } from "../shared/index.js";
 import { normalizeDeploymentName } from "./names.js";
+import { acquirePidLock, PidLockBusyError } from "./pidLock.js";
 import { parseDeploymentRecord } from "./record.js";
+import { bindDeploymentRecording, publishDeploymentRecord, writeAtomicDeploymentFile } from "./recordPublication.js";
+export { HomeDeploymentRecordingError } from "./recordPublication.js";
 export const resolveHomeDeploymentsDirectory = () => path.join(resolveSpawnfileHome(), "deployments");
 export const resolveHomeDeploymentDirectory = (deploymentName) => path.join(resolveHomeDeploymentsDirectory(), normalizeDeploymentName(deploymentName));
 export const resolveHomeRecordPath = (deploymentName) => path.join(resolveHomeDeploymentDirectory(deploymentName), "record.json");
 export const resolveHomeReportPath = (deploymentName) => path.join(resolveHomeDeploymentDirectory(deploymentName), "spawnfile-report.json");
 /**
  * Acquires an exclusive lock for a home deployment so concurrent `up`
- * invocations cannot race on the same record (and orphan each other's
- * containers). Returns a release function. Throws if the deployment is already
- * locked by another in-flight operation.
+ * invocations (and a drained release holding it across its swap) cannot race
+ * on the same record or orphan each other's containers. Returns a release
+ * function. Throws if a live operation holds the lock; a lock left by a
+ * process that is gone is reclaimed. See `pidLock.ts`.
  */
-const isProcessAlive = (pid) => {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        // ESRCH means no such process (stale); EPERM means it exists but is ours to
-        // not signal — treat as alive to stay safe.
-        return error.code === "EPERM";
-    }
-};
 export const acquireHomeDeploymentLock = async (deploymentName) => {
     const directory = resolveHomeDeploymentDirectory(deploymentName);
     await ensureDirectory(directory);
-    const lockPath = path.join(directory, ".lock");
-    const write = async () => {
-        const handle = await open(lockPath, "wx");
-        try {
-            await handle.write(JSON.stringify({ pid: process.pid }));
-        }
-        finally {
-            await handle.close();
-        }
-    };
     try {
-        await write();
+        return await acquirePidLock(path.join(directory, ".lock"));
     }
     catch (error) {
-        if (error.code !== "EEXIST") {
-            throw error;
-        }
-        // A lock exists. Reclaim it only if the owning process is gone (a crashed
-        // deploy must not lock the deployment forever); otherwise it is genuinely busy.
-        let ownerPid = null;
-        try {
-            ownerPid = JSON.parse(await readUtf8File(lockPath)).pid ?? null;
-        }
-        catch {
-            ownerPid = null;
-        }
-        if (ownerPid !== null && isProcessAlive(ownerPid)) {
+        if (error instanceof PidLockBusyError) {
             throw new SpawnfileError("runtime_error", `Deployment "${normalizeDeploymentName(deploymentName)}" is already being modified by another operation`);
         }
-        await rm(lockPath, { force: true });
-        await write();
+        throw error;
     }
-    return async () => {
-        await rm(lockPath, { force: true });
-    };
-};
-const writeAtomic = async (filePath, content) => {
-    const temporaryPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
-    await writeFile(temporaryPath, content, "utf8");
-    await rename(temporaryPath, filePath);
 };
 /** Writes the record and the cached distribution report together, record last. */
-export const writeHomeDeployment = async (record, report) => {
+export const writeHomeDeployment = async (record, report, previous) => {
     const parsed = parseDeploymentRecord(record);
     const directory = resolveHomeDeploymentDirectory(parsed.name);
     await ensureDirectory(directory);
     const reportPath = resolveHomeReportPath(parsed.name);
     const recordPath = resolveHomeRecordPath(parsed.name);
-    await writeAtomic(reportPath, `${JSON.stringify(report, null, 2)}\n`);
-    await writeAtomic(recordPath, `${JSON.stringify(parsed, null, 2)}\n`);
+    const reportBytes = `${JSON.stringify(report, null, 2)}\n`;
+    const bound = parseDeploymentRecord(bindDeploymentRecording(recordPath, parsed, report, reportBytes));
+    await publishDeploymentRecord(recordPath, bound, (durable) => (durable ? writeDurableFile : writeAtomicDeploymentFile)(reportPath, reportBytes), previous);
     return { recordPath, reportPath };
 };
 export const readHomeDeploymentRecord = async (deploymentName) => {

package/dist/deployment/index.d.ts

@@ -5,6 +5,7 @@ export * from "./artifactsExportTypes.js";
 export * from "./privateArtifactsExport.js";
 export * from "./buildImageCacheStore.js";
 export * from "./candidateDiagnostics.js";
+export * from "./candidateRecording.js";
 export * from "./dockerLabels.js";
 export * from "./dockerInspect.js";
 export * from "./dockerLogs.js";
@@ -23,8 +24,13 @@ export * from "./organizationHandoffTypes.js";
 export * from "./organizationHandoffAuthorityTypes.js";
 export * from "./organizationHandoffAuthorityStore.js";
 export * from "./organizationReady.js";
+export * from "./pidLock.js";
 export * from "./canaryCutover.js";
 export * from "./productStateClone.js";
 export * from "./record.js";
+export * from "./recordedMemoryRetention.js";
 export * from "./target.js";
 export * from "./upReceiptTypes.js";
+export * from "./resourceLog.js";
+export * from "./activation.js";
+export { bindDeploymentRecording, reconcileDeploymentResources } from "./recordPublication.js";

package/dist/deployment/index.js

@@ -5,6 +5,7 @@ export * from "./artifactsExportTypes.js";
 export * from "./privateArtifactsExport.js";
 export * from "./buildImageCacheStore.js";
 export * from "./candidateDiagnostics.js";
+export * from "./candidateRecording.js";
 export * from "./dockerLabels.js";
 export * from "./dockerInspect.js";
 export * from "./dockerLogs.js";
@@ -23,9 +24,14 @@ export * from "./organizationHandoffTypes.js";
 export * from "./organizationHandoffAuthorityTypes.js";
 export * from "./organizationHandoffAuthorityStore.js";
 export * from "./organizationReady.js";
+export * from "./pidLock.js";
 export * from "./canaryCutover.js";
 export * from "./productStateClone.js";
 export * from "./record.js";
+export * from "./recordedMemoryRetention.js";
 // Compatibility target exports remain available from this legacy deployment barrel.
 export * from "./target.js";
 export * from "./upReceiptTypes.js";
+export * from "./resourceLog.js";
+export * from "./activation.js";
+export { bindDeploymentRecording, reconcileDeploymentResources } from "./recordPublication.js";

package/dist/deployment/pidLock.d.ts

@@ -0,0 +1,25 @@
+/** Thrown when a live process holds the lock (or won a race for it). */
+export declare class PidLockBusyError extends Error {
+    readonly ownerPid: number | null;
+    constructor(ownerPid: number | null);
+}
+export interface PidLockHooks {
+    /** Test seam: runs between reading a stale lock and moving it aside. */
+    afterStaleRead?: () => Promise<void>;
+}
+/**
+ * An exclusive lock file that names its owner from the instant it exists:
+ * the content is written aside and hard-linked into place, and `link` fails
+ * when the path exists, so no reader ever sees an empty lock and calls it
+ * stale. A lock whose owner process is gone is moved aside under a unique
+ * name and checked: if what was moved is not the stale lock that was read,
+ * another process replaced it in between, and it is put back.
+ *
+ * Residual: pid locks cannot be made race-free for stale reclamation without
+ * kernel locks. Three contenders arriving within microseconds of each other,
+ * all after a crashed owner, can still overlap. Run unattended jobs through a
+ * scheduler that does not overlap them.
+ *
+ * Release removes the lock only while it still carries this owner's token.
+ */
+export declare const acquirePidLock: (lockPath: string, hooks?: PidLockHooks) => Promise<() => Promise<void>>;

package/dist/deployment/pidLock.js

@@ -0,0 +1,81 @@
+import { randomUUID } from "node:crypto";
+import { link, readFile, rename, rm, writeFile } from "node:fs/promises";
+/** Thrown when a live process holds the lock (or won a race for it). */
+export class PidLockBusyError extends Error {
+    ownerPid;
+    constructor(ownerPid) {
+        super(ownerPid === null ? "the lock was taken by another process" : `the lock is held by pid ${ownerPid}`);
+        this.ownerPid = ownerPid;
+        this.name = "PidLockBusyError";
+    }
+}
+const isProcessAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // ESRCH: no such process (stale). EPERM: it exists but is not ours to signal.
+        return error.code === "EPERM";
+    }
+};
+/**
+ * An exclusive lock file that names its owner from the instant it exists:
+ * the content is written aside and hard-linked into place, and `link` fails
+ * when the path exists, so no reader ever sees an empty lock and calls it
+ * stale. A lock whose owner process is gone is moved aside under a unique
+ * name and checked: if what was moved is not the stale lock that was read,
+ * another process replaced it in between, and it is put back.
+ *
+ * Residual: pid locks cannot be made race-free for stale reclamation without
+ * kernel locks. Three contenders arriving within microseconds of each other,
+ * all after a crashed owner, can still overlap. Run unattended jobs through a
+ * scheduler that does not overlap them.
+ *
+ * Release removes the lock only while it still carries this owner's token.
+ */
+export const acquirePidLock = async (lockPath, hooks = {}) => {
+    const token = `${process.pid}.${randomUUID()}`;
+    const staged = `${lockPath}.${token}`;
+    await writeFile(staged, JSON.stringify({ pid: process.pid, token }), { mode: 0o600 });
+    try {
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            try {
+                await link(staged, lockPath);
+                return async () => {
+                    const current = await readFile(lockPath, "utf8").catch(() => "");
+                    if (current.includes(token))
+                        await rm(lockPath, { force: true });
+                };
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+            }
+            const seen = await readFile(lockPath, "utf8").catch(() => "");
+            let owner = null;
+            try {
+                owner = JSON.parse(seen).pid ?? null;
+            }
+            catch {
+                owner = null;
+            }
+            if (owner !== null && isProcessAlive(owner))
+                throw new PidLockBusyError(owner);
+            await hooks.afterStaleRead?.();
+            const tombstone = `${lockPath}.stale.${token}`;
+            await rename(lockPath, tombstone).catch(() => undefined);
+            const moved = await readFile(tombstone, "utf8").catch(() => null);
+            if (moved !== null && moved !== seen) {
+                await link(tombstone, lockPath).catch(() => undefined);
+                await rm(tombstone, { force: true });
+                throw new PidLockBusyError(null);
+            }
+            await rm(tombstone, { force: true });
+        }
+        throw new PidLockBusyError(null);
+    }
+    finally {
+        await rm(staged, { force: true });
+    }
+};

package/dist/deployment/record.d.ts

@@ -12,6 +12,90 @@ declare const recordSourceSchema: z.ZodUnion<readonly [z.ZodObject<{
 }, z.core.$strict>]>;
 export type DeploymentRecordSource = z.infer<typeof recordSourceSchema>;
 export declare const deploymentRecordSchema: z.ZodObject<{
+    activated_at: z.ZodOptional<z.ZodISODateTime>;
+    activation_exact: z.ZodOptional<z.ZodBoolean>;
+    activation_note: z.ZodOptional<z.ZodString>;
+    recording: z.ZodOptional<z.ZodObject<{
+        keep_ms: z.ZodNumber;
+        memory_mount_ids: z.ZodArray<z.ZodString>;
+        recording_mount_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        agents: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            node_id: z.ZodString;
+            slug: z.ZodString;
+            directory: z.ZodString;
+            keep_ms: z.ZodNumber;
+            networks: z.ZodArray<z.ZodString>;
+            memory: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                declared_by: z.ZodString;
+                ledger_path: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>>;
+            feeds: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                volume_name: z.ZodString;
+            }, z.core.$strict>>;
+            resources: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                kind: z.ZodEnum<{
+                    git: "git";
+                    bundle: "bundle";
+                }>;
+            }, z.core.$strict>>;
+            snapshots: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    resource_snapshot: z.ZodOptional<z.ZodObject<{
+        version: z.ZodLiteral<"spawnfile.deploy-resources.v1">;
+        deployment: z.ZodString;
+        deployment_id: z.ZodString;
+        activated_at: z.ZodISODateTime;
+        activation_exact: z.ZodBoolean;
+        activation_note: z.ZodOptional<z.ZodString>;
+        rolled_back_at: z.ZodOptional<z.ZodISODateTime>;
+        exact: z.ZodOptional<z.ZodLiteral<false>>;
+        deployed_at: z.ZodISODateTime;
+        report_sha256: z.ZodString;
+        resources: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodLiteral<"git">;
+            commit: z.ZodString;
+            sha256: z.ZodString;
+            url: z.ZodOptional<z.ZodString>;
+            agent_node_ids: z.ZodArray<z.ZodString>;
+            declared_by: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodLiteral<"bundle">;
+            sha256: z.ZodString;
+            origin: z.ZodOptional<z.ZodString>;
+            agent_node_ids: z.ZodArray<z.ZodString>;
+            declared_by: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>], "kind">>;
+        recording_agents: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            node_id: z.ZodString;
+            slug: z.ZodString;
+            directory: z.ZodString;
+            keep_ms: z.ZodNumber;
+            networks: z.ZodArray<z.ZodString>;
+            memory: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                declared_by: z.ZodString;
+                ledger_path: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>>;
+            feeds: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                volume_name: z.ZodString;
+            }, z.core.$strict>>;
+            resources: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                kind: z.ZodEnum<{
+                    git: "git";
+                    bundle: "bundle";
+                }>;
+            }, z.core.$strict>>;
+            snapshots: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
     auth_profile: z.ZodNullable<z.ZodString>;
     compile_fingerprint: z.ZodString;
     created_at: z.ZodString;
@@ -97,5 +181,5 @@ export declare const listDeploymentRecords: (outputDirectory: string) => Promise
     path: string;
     record: DeploymentRecord;
 }>>;
-export declare const writeDeploymentRecord: (outputDirectory: string, record: DeploymentRecord) => Promise<string>;
+export declare const writeDeploymentRecord: (outputDirectory: string, record: DeploymentRecord, previous?: DeploymentRecord | null) => Promise<string>;
 export {};

package/dist/deployment/record.js

@@ -1,8 +1,11 @@
 import path from "node:path";
-import { readdir, rename, writeFile } from "node:fs/promises";
+import { readdir } from "node:fs/promises";
 import { z } from "zod";
 import { ensureDirectory, readUtf8File } from "../filesystem/index.js";
+import { deployResourcesSchema } from "./resourceLog.js";
+import { publishDeploymentRecord } from "./recordPublication.js";
 import { SpawnfileError } from "../shared/index.js";
+import { recordingReportSchema } from "../report/index.js";
 import { parseOrganizationHandoff } from "./organizationHandoffTypes.js";
 import { parseOpaqueTargetHandle } from "../target/index.js";
 import { normalizeDeploymentName, resolveDeploymentRecordPath, resolveDeploymentRecordsDirectory } from "./names.js";
@@ -79,6 +82,11 @@ const deploymentRecordV1Schema = z.object({
     version: z.literal("spawnfile.deployment.v1")
 }).strict();
 export const deploymentRecordSchema = z.object({
+    activated_at: z.iso.datetime({ offset: true }).optional(),
+    activation_exact: z.boolean().optional(),
+    activation_note: z.string().min(1).optional(),
+    recording: recordingReportSchema.optional(),
+    resource_snapshot: deployResourcesSchema.optional(),
     auth_profile: z.string().min(1).nullable(),
     compile_fingerprint: z.string().min(1),
     created_at: z.string().min(1),
@@ -208,12 +216,10 @@ export const listDeploymentRecords = async (outputDirectory) => {
     }));
     return records.sort((left, right) => left.record.name.localeCompare(right.record.name));
 };
-export const writeDeploymentRecord = async (outputDirectory, record) => {
+export const writeDeploymentRecord = async (outputDirectory, record, previous) => {
     const parsed = parseDeploymentRecord(record);
     const recordPath = resolveDeploymentRecordPath(outputDirectory, parsed.name);
     await ensureDirectory(path.dirname(recordPath));
-    const temporaryPath = path.join(path.dirname(recordPath), `.${path.basename(recordPath)}.${process.pid}.${Date.now()}.tmp`);
-    await writeFile(temporaryPath, `${JSON.stringify(parsed, null, 2)}\n`, "utf8");
-    await rename(temporaryPath, recordPath);
+    await publishDeploymentRecord(recordPath, parsed, undefined, previous);
     return recordPath;
 };

package/dist/deployment/recordPublication.d.ts

@@ -0,0 +1,15 @@
+import { SpawnfileError } from "../shared/index.js";
+import { type DeploymentRecord } from "./record.js";
+import { type DeployResourceReport } from "./resourceLog.js";
+/** Publication succeeded: callers must not roll back its named container. */
+export declare class HomeDeploymentRecordingError extends SpawnfileError {
+    constructor(deployment: string, cause: unknown);
+}
+export declare const bindDeploymentRecording: (recordPath: string, record: DeploymentRecord, report: DeployResourceReport, reportBytes: string) => DeploymentRecord;
+/** Caller holds the publication lock; recover a published snapshot before using its history. */
+export declare const reconcileDeploymentResources: (recordPath: string) => Promise<void>;
+/** The original non-recording publication sequence, including its temporary name and permissions. */
+export declare const writeAtomicDeploymentFile: (file: string, bytes: string) => Promise<void>;
+/** Callers create the directory and pass the predecessor from their existing lifecycle read.
+ * Recording replacements re-read under the lock; off never probes for recording state. */
+export declare const publishDeploymentRecord: (recordPath: string, record: DeploymentRecord, publishReport?: (durable: boolean) => Promise<void>, previous?: DeploymentRecord | null) => Promise<void>;

package/dist/deployment/recordPublication.js

@@ -0,0 +1,76 @@
+import path from "node:path";
+import { readFile, rename, writeFile } from "node:fs/promises";
+import { PublishedFileSyncError, syncFile, writeDurableFile } from "../filesystem/index.js";
+import { SpawnfileError } from "../shared/index.js";
+import { acquirePidLock } from "./pidLock.js";
+import { parseDeploymentRecord } from "./record.js";
+import { createDeployResources, ensureDeployResources } from "./resourceLog.js";
+/** Publication succeeded: callers must not roll back its named container. */
+export class HomeDeploymentRecordingError extends SpawnfileError {
+    constructor(deployment, cause) {
+        super("io_error", `Deployment ${deployment} is published, but recording failed: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    }
+}
+export const bindDeploymentRecording = (recordPath, record, report, reportBytes) => {
+    const { recording: _recording, resource_snapshot: _snapshot, ...base } = record;
+    return report.recording ? { ...base, recording: report.recording,
+        resource_snapshot: createDeployResources(recordPath, record, report, reportBytes) } : base;
+};
+const priorRecord = async (recordPath) => {
+    let bytes;
+    try {
+        bytes = await readFile(recordPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    return parseDeploymentRecord(JSON.parse(bytes), recordPath);
+};
+/** Caller holds the publication lock; recover a published snapshot before using its history. */
+export const reconcileDeploymentResources = async (recordPath) => {
+    const previous = await priorRecord(recordPath);
+    if (previous?.resource_snapshot && previous.recording) {
+        await syncFile(recordPath);
+        ensureDeployResources(recordPath, previous.resource_snapshot, previous.recording.keep_ms);
+    }
+};
+/** The original non-recording publication sequence, including its temporary name and permissions. */
+export const writeAtomicDeploymentFile = async (file, bytes) => {
+    const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${Date.now()}.tmp`);
+    await writeFile(temporary, bytes, "utf8");
+    await rename(temporary, file);
+};
+/** Callers create the directory and pass the predecessor from their existing lifecycle read.
+ * Recording replacements re-read under the lock; off never probes for recording state. */
+export const publishDeploymentRecord = async (recordPath, record, publishReport, previous) => {
+    if (!record.recording && !previous?.recording) {
+        await publishReport?.(false);
+        await writeAtomicDeploymentFile(recordPath, `${JSON.stringify(record, null, 2)}\n`);
+        return;
+    }
+    const release = await acquirePidLock(`${recordPath}.resource-log.lock`);
+    try {
+        await reconcileDeploymentResources(recordPath);
+        await publishReport?.(true);
+        try {
+            await writeDurableFile(recordPath, `${JSON.stringify(record, null, 2)}\n`);
+        }
+        catch (cause) {
+            if (cause instanceof PublishedFileSyncError)
+                throw new HomeDeploymentRecordingError(record.name, cause);
+            throw cause;
+        }
+        try {
+            if (record.resource_snapshot && record.recording)
+                ensureDeployResources(recordPath, record.resource_snapshot, record.recording.keep_ms);
+        }
+        catch (cause) {
+            throw new HomeDeploymentRecordingError(record.name, cause);
+        }
+    }
+    finally {
+        await release();
+    }
+};

package/dist/deployment/recordedMemoryRetention.d.ts

@@ -0,0 +1,18 @@
+import type { RecordingReport } from "../report/index.js";
+import type { DeploymentRecord } from "./record.js";
+export interface RecordedMemoryDeletionOptions {
+    discardRecordedMemory?: boolean;
+    removeVolumes?: boolean;
+}
+/** A recompile cannot revoke deployed protection or change the mount-name mapping. */
+export declare const recordedMemoryForDeletion: (record: Pick<DeploymentRecord, "recording" | "compile_fingerprint">, report: {
+    compile_fingerprint?: string;
+    recording?: RecordingReport;
+} | null, mounts: readonly {
+    id: string;
+}[], options: RecordedMemoryDeletionOptions) => RecordingReport | undefined;
+/** The recording report lists mount ids; deletion operates on resolved names.
+ * Compare names after mapping so aliases cannot bypass the retention guard. */
+export declare const assertRecordedMemoryRetention: <T extends {
+    id: string;
+}>(recording: RecordingReport | undefined, mounts: readonly T[], deleting: readonly string[], nameOf: (mount: T) => string, options: RecordedMemoryDeletionOptions, remedy?: string) => void;

package/dist/deployment/recordedMemoryRetention.js

@@ -0,0 +1,27 @@
+import { SpawnfileError } from "../shared/index.js";
+const protectedMountIds = (recording) => [...recording.memory_mount_ids, ...(recording.recording_mount_ids ?? [])];
+/** A recompile cannot revoke deployed protection or change the mount-name mapping. */
+export const recordedMemoryForDeletion = (record, report, mounts, options) => {
+    if (options.removeVolumes && !options.discardRecordedMemory) {
+        const deployed = record.recording;
+        const mismatch = report?.compile_fingerprint !== record.compile_fingerprint;
+        const weakened = deployed && (!report?.recording || report.recording.keep_ms < deployed.keep_ms
+            || protectedMountIds(deployed).some((id) => !protectedMountIds(report.recording).includes(id) || !mounts.some((mount) => mount.id === id)));
+        if ((deployed && mismatch) || weakened || (report?.recording && mismatch)) {
+            throw new SpawnfileError("runtime_error", "Deployment record and report disagree; recording protection cannot be weakened. Restore the deployed report or pass --discard-recorded-memory with --volumes");
+        }
+    }
+    return record.recording ?? report?.recording;
+};
+/** The recording report lists mount ids; deletion operates on resolved names.
+ * Compare names after mapping so aliases cannot bypass the retention guard. */
+export const assertRecordedMemoryRetention = (recording, mounts, deleting, nameOf, options, remedy = "pass --discard-recorded-memory with --volumes to deliberately discard them") => {
+    if (!recording || !options.removeVolumes || options.discardRecordedMemory)
+        return;
+    const protectedIds = new Set(protectedMountIds(recording));
+    const protectedNames = new Set(mounts.filter((mount) => protectedIds.has(mount.id)).map(nameOf));
+    const protectedDeletions = [...new Set(deleting.filter((name) => protectedNames.has(name)))].sort();
+    if (protectedDeletions.length > 0) {
+        throw new SpawnfileError("runtime_error", `Recording retains memory ledgers and recording stores in ${protectedDeletions.join(", ")}; ${remedy}`);
+    }
+};