@caupulican/pi-adaptative 0.85.3 → 0.85.8

package/dist/core/tools/file-mutation-intent.d.ts

@@ -16,55 +16,82 @@ export interface FileMutationIntentOperations {
     access(path: string, mode: number): Promise<void>;
     copyFileExclusive(sourcePath: string, targetPath: string): Promise<void>;
     hashFile(path: string, signal?: AbortSignal): Promise<string>;
+    readPayload(path: string): Promise<string>;
     removeFile(path: string): Promise<void>;
+    stagePayload(content: string, ttlMs: number): Promise<string>;
 }
-export interface PreparedFileMutation {
-    intentId: string;
+export interface FileMutationLease {
     kind: FileMutationKind;
     path: string;
     displayPath: string;
-}
-export interface FileMutationLease extends PreparedFileMutation {
     identity?: FilePathIdentity;
 }
 export interface FileContentReference {
     contentRef: string;
     byteLength: number;
 }
+export interface FileMutationPayloadReference {
+    payloadRef: string;
+    byteLength: number;
+}
+export type FileMutationPreflightFailureReason = "write_collision" | "edit_missing" | "edit_not_file";
+export declare class FileMutationPreflightError extends Error {
+    readonly reason: FileMutationPreflightFailureReason;
+    constructor(reason: FileMutationPreflightFailureReason, message: string);
+}
 export interface FileMutationIntentControllerOptions {
     operations?: FileMutationIntentOperations;
-    intentLimit?: number;
     contentReferenceLimit?: number;
-    intentTtlMs?: number;
     contentReferenceTtlMs?: number;
+    mutationPayloadLimit?: number;
+    mutationPayloadByteLimit?: number;
+    mutationPayloadTtlMs?: number;
     now?: () => number;
 }
 export declare const localFileMutationIntentOperations: FileMutationIntentOperations;
 /**
- * Session-owned authority for two-phase file mutation intents and bounded exact-content references.
- * It retains only fixed-size metadata; file bytes remain owned by the filesystem.
+ * Session-owned harness authority for file-mutation preflight, stale-target checks,
+ * and bounded exact-content references. It retains only fixed-size metadata; file
+ * bytes remain owned by the filesystem.
  */
 export declare class FileMutationIntentController {
     private readonly operations;
-    private readonly intentLimit;
     private readonly contentReferenceLimit;
-    private readonly intentTtlMs;
     private readonly contentReferenceTtlMs;
+    private readonly mutationPayloadLimit;
+    private readonly mutationPayloadByteLimit;
+    private readonly mutationPayloadTtlMs;
     private readonly now;
-    private readonly intents;
-    private readonly intentByPath;
     private readonly contentReferences;
+    private readonly mutationPayloads;
+    private mutationPayloadBytes;
+    private lastMutationPayloadExpiresAt;
+    private mutationPayloadOperationTail;
     constructor(options?: FileMutationIntentControllerOptions);
-    prepare(kind: FileMutationKind, path: string, signal?: AbortSignal, displayPath?: string): Promise<PreparedFileMutation>;
-    consume(intentId: string, kind: FileMutationKind, path: string): FileMutationLease;
+    prepare(kind: FileMutationKind, path: string, signal?: AbortSignal, displayPath?: string): Promise<FileMutationLease>;
     assertCurrent(lease: FileMutationLease, signal?: AbortSignal): Promise<void>;
     rememberContent(sourcePath: string, content: string): FileContentReference;
+    retainMutationPayload(kind: FileMutationKind, payload: string): Promise<FileMutationPayloadReference | undefined>;
+    readMutationPayload(payloadRef: string, kind: FileMutationKind, signal?: AbortSignal): Promise<string>;
+    assertMutationPayload(payloadRef: string, kind: FileMutationKind, signal?: AbortSignal): Promise<void>;
+    assertContentReference(contentRef: string, signal?: AbortSignal): Promise<void>;
+    copyMutationPayload(payloadRef: string, targetPath: string, signal?: AbortSignal): Promise<FileContentReference>;
+    discardMutationPayload(payloadRef: string): Promise<void>;
+    /** Release every payload owned by this controller without touching another controller's files. */
+    dispose(): Promise<void>;
     copyReferencedContent(contentRef: string, targetPath: string, signal?: AbortSignal): Promise<FileContentReference>;
+    private requireVerifiedContentReference;
+    private requireMutationPayload;
+    private requireVerifiedMutationPayload;
+    private verifySource;
+    private copyVerifiedSource;
     private assertCreatableParent;
     private rememberContentDigest;
     private touchContentReference;
     private removeFailedCopy;
-    private deleteIntent;
+    private deleteMutationPayload;
+    private runMutationPayloadOperation;
+    private pruneExpiredMutationPayloads;
     private pruneExpired;
 }
 //# sourceMappingURL=file-mutation-intent.d.ts.map

package/dist/core/tools/file-mutation-intent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-mutation-intent.d.ts","sourceRoot":"","sources":["../../../src/core/tools/file-mutation-intent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"file-mutation-intent.d.ts","sourceRoot":"","sources":["../../../src/core/tools/file-mutation-intent.ts"],"names":[],"mappings":"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"}

package/dist/core/tools/file-mutation-intent.js

@@ -1,13 +1,38 @@
 import { createHash, randomUUID } from "node:crypto";
-import { constants } from "node:fs";
-import { access, copyFile, lstat, open, stat, unlink } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
-const DEFAULT_INTENT_LIMIT = 64;
+import { constants, rmSync } from "node:fs";
+import { access, copyFile, lstat, mkdtemp, open, readFile, stat, unlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
 const DEFAULT_CONTENT_REFERENCE_LIMIT = 64;
-const DEFAULT_INTENT_TTL_MS = 10 * 60 * 1000;
 const DEFAULT_CONTENT_REFERENCE_TTL_MS = 60 * 60 * 1000;
+const DEFAULT_MUTATION_PAYLOAD_LIMIT = 8;
+const DEFAULT_MUTATION_PAYLOAD_BYTE_LIMIT = 16 * 1024 * 1024;
+const DEFAULT_MUTATION_PAYLOAD_TTL_MS = 10 * 60 * 1000;
 const HASH_BUFFER_BYTES = 64 * 1024;
 const CONTENT_REFERENCE_PREFIX = "file-content:";
+const MUTATION_PAYLOAD_REFERENCE_PREFIX = "file-mutation:";
+const LOCAL_MUTATION_PAYLOAD_DIRECTORY_PREFIX = "pi-file-mutation-payloads-";
+const LOCAL_MUTATION_PAYLOAD_PROCESS_BYTE_LIMIT = 64 * 1024 * 1024;
+const LOCAL_MUTATION_PAYLOAD_PROCESS_FILE_LIMIT = 64;
+let localMutationPayloadDirectoryPromise;
+let localMutationPayloadDirectory;
+let localMutationPayloadCleanupRegistered = false;
+let localMutationPayloadOperationTail = Promise.resolve();
+let localMutationPayloadBytes = 0;
+const localMutationPayloadFiles = new Map();
+class MutationPayloadCapacityError extends Error {
+    constructor() {
+        super("Process mutation payload cache is full.");
+        this.name = "MutationPayloadCapacityError";
+    }
+}
+export class FileMutationPreflightError extends Error {
+    constructor(reason, message) {
+        super(message);
+        this.name = "FileMutationPreflightError";
+        this.reason = reason;
+    }
+}
 function isMissingPathError(error) {
     return (typeof error === "object" &&
         error !== null &&
@@ -19,10 +44,6 @@ function errorCode(error) {
         ? error.code
         : undefined;
 }
-function normalizedPath(path) {
-    const absolutePath = resolve(path);
-    return process.platform === "win32" ? absolutePath.toLocaleLowerCase("en-US") : absolutePath;
-}
 function positiveBound(value, fallback, label) {
     const resolvedValue = value ?? fallback;
     if (!Number.isSafeInteger(resolvedValue) || resolvedValue < 1) {
@@ -85,27 +106,95 @@ async function hashLocalFile(path, signal) {
         await handle.close();
     }
 }
+async function getLocalMutationPayloadDirectory() {
+    localMutationPayloadDirectoryPromise ??= mkdtemp(join(tmpdir(), LOCAL_MUTATION_PAYLOAD_DIRECTORY_PREFIX)).then((path) => {
+        localMutationPayloadDirectory = path;
+        if (!localMutationPayloadCleanupRegistered) {
+            localMutationPayloadCleanupRegistered = true;
+            process.once("exit", () => {
+                if (localMutationPayloadDirectory) {
+                    try {
+                        rmSync(localMutationPayloadDirectory, { recursive: true, force: true });
+                    }
+                    catch {
+                        // Process shutdown cannot safely retry filesystem cleanup.
+                    }
+                }
+            });
+        }
+        return path;
+    });
+    return localMutationPayloadDirectoryPromise;
+}
+async function stageLocalMutationPayload(content, ttlMs) {
+    const byteLength = Buffer.byteLength(content, "utf8");
+    let stagedPath = "";
+    const operation = localMutationPayloadOperationTail.then(async () => {
+        for (const [path, record] of localMutationPayloadFiles) {
+            if (record.expiresAt > Date.now())
+                continue;
+            localMutationPayloadFiles.delete(path);
+            localMutationPayloadBytes -= record.byteLength;
+            try {
+                await unlink(path);
+            }
+            catch (error) {
+                if (!isMissingPathError(error))
+                    throw error;
+            }
+        }
+        if (localMutationPayloadFiles.size >= LOCAL_MUTATION_PAYLOAD_PROCESS_FILE_LIMIT ||
+            localMutationPayloadBytes + byteLength > LOCAL_MUTATION_PAYLOAD_PROCESS_BYTE_LIMIT) {
+            throw new MutationPayloadCapacityError();
+        }
+        stagedPath = join(await getLocalMutationPayloadDirectory(), randomUUID());
+        await writeFile(stagedPath, content, { encoding: "utf8", flag: "wx", mode: 0o600 });
+        localMutationPayloadFiles.set(stagedPath, { byteLength, expiresAt: Date.now() + ttlMs });
+        localMutationPayloadBytes += byteLength;
+    });
+    localMutationPayloadOperationTail = operation.catch(() => { });
+    await operation;
+    return stagedPath;
+}
+async function removeLocalMutationPayloadOrFile(path) {
+    const operation = localMutationPayloadOperationTail.then(async () => {
+        const record = localMutationPayloadFiles.get(path);
+        if (record !== undefined) {
+            localMutationPayloadFiles.delete(path);
+            localMutationPayloadBytes -= record.byteLength;
+        }
+        await unlink(path);
+    });
+    localMutationPayloadOperationTail = operation.catch(() => { });
+    await operation;
+}
 export const localFileMutationIntentOperations = {
     inspect: inspectLocalPath,
     access,
     copyFileExclusive: (sourcePath, targetPath) => copyFile(sourcePath, targetPath, constants.COPYFILE_EXCL),
     hashFile: hashLocalFile,
-    removeFile: unlink,
+    readPayload: (path) => readFile(path, "utf8"),
+    removeFile: removeLocalMutationPayloadOrFile,
+    stagePayload: stageLocalMutationPayload,
 };
 /**
- * Session-owned authority for two-phase file mutation intents and bounded exact-content references.
- * It retains only fixed-size metadata; file bytes remain owned by the filesystem.
+ * Session-owned harness authority for file-mutation preflight, stale-target checks,
+ * and bounded exact-content references. It retains only fixed-size metadata; file
+ * bytes remain owned by the filesystem.
  */
 export class FileMutationIntentController {
     constructor(options = {}) {
-        this.intents = new Map();
-        this.intentByPath = new Map();
         this.contentReferences = new Map();
+        this.mutationPayloads = new Map();
+        this.mutationPayloadBytes = 0;
+        this.lastMutationPayloadExpiresAt = 0;
+        this.mutationPayloadOperationTail = Promise.resolve();
         this.operations = options.operations ?? localFileMutationIntentOperations;
-        this.intentLimit = positiveBound(options.intentLimit, DEFAULT_INTENT_LIMIT, "Intent limit");
         this.contentReferenceLimit = positiveBound(options.contentReferenceLimit, DEFAULT_CONTENT_REFERENCE_LIMIT, "Content reference limit");
-        this.intentTtlMs = positiveBound(options.intentTtlMs, DEFAULT_INTENT_TTL_MS, "Intent TTL");
         this.contentReferenceTtlMs = positiveBound(options.contentReferenceTtlMs, DEFAULT_CONTENT_REFERENCE_TTL_MS, "Content reference TTL");
+        this.mutationPayloadLimit = positiveBound(options.mutationPayloadLimit, DEFAULT_MUTATION_PAYLOAD_LIMIT, "Mutation payload limit");
+        this.mutationPayloadByteLimit = positiveBound(options.mutationPayloadByteLimit, DEFAULT_MUTATION_PAYLOAD_BYTE_LIMIT, "Mutation payload byte limit");
+        this.mutationPayloadTtlMs = positiveBound(options.mutationPayloadTtlMs, DEFAULT_MUTATION_PAYLOAD_TTL_MS, "Mutation payload TTL");
         this.now = options.now ?? Date.now;
     }
     async prepare(kind, path, signal, displayPath = path) {
@@ -116,16 +205,19 @@ export class FileMutationIntentController {
         let identity;
         if (kind === "write") {
             const existing = await this.operations.inspect(absolutePath, false);
-            if (existing)
-                throw new Error(`Write collision: ${displayPath} already exists.`);
+            if (existing) {
+                throw new FileMutationPreflightError("write_collision", `Write collision: ${displayPath} already exists.`);
+            }
             await this.assertCreatableParent(absolutePath);
         }
         else {
             const existing = await this.operations.inspect(absolutePath, true);
-            if (!existing)
-                throw new Error(`Could not edit file: ${displayPath}. Error code: ENOENT.`);
-            if (existing.kind !== "file")
-                throw new Error(`Could not edit file: ${displayPath}. Target is not a regular file.`);
+            if (!existing) {
+                throw new FileMutationPreflightError("edit_missing", `Could not edit file: ${displayPath}. Error code: ENOENT.`);
+            }
+            if (existing.kind !== "file") {
+                throw new FileMutationPreflightError("edit_not_file", `Could not edit file: ${displayPath}. Target is not a regular file.`);
+            }
             try {
                 await this.operations.access(absolutePath, constants.R_OK | constants.W_OK);
             }
@@ -137,46 +229,11 @@ export class FileMutationIntentController {
         }
         if (signal?.aborted)
             throw new Error("Operation aborted");
-        const key = `${kind}\0${normalizedPath(absolutePath)}`;
-        const priorIntentId = this.intentByPath.get(key);
-        if (priorIntentId)
-            this.deleteIntent(priorIntentId);
-        while (this.intents.size >= this.intentLimit) {
-            const oldestIntentId = this.intents.keys().next().value;
-            if (typeof oldestIntentId !== "string")
-                break;
-            this.deleteIntent(oldestIntentId);
-        }
-        const intentId = randomUUID();
-        const record = {
-            intentId,
+        return {
             kind,
             path: absolutePath,
             displayPath,
             ...(identity ? { identity } : {}),
-            expiresAt: this.now() + this.intentTtlMs,
-        };
-        this.intents.set(intentId, record);
-        this.intentByPath.set(key, intentId);
-        return { intentId, kind, path: absolutePath, displayPath };
-    }
-    consume(intentId, kind, path) {
-        this.pruneExpired();
-        const record = this.intents.get(intentId);
-        if (!record)
-            throw new Error("File mutation intent is invalid, expired, or belongs to another session.");
-        this.deleteIntent(intentId);
-        if (record.kind !== kind)
-            throw new Error(`File mutation intent is for ${record.kind}, not ${kind}.`);
-        if (normalizedPath(record.path) !== normalizedPath(path)) {
-            throw new Error("File mutation intent path does not match the commit path.");
-        }
-        return {
-            intentId: record.intentId,
-            kind: record.kind,
-            path: record.path,
-            displayPath: record.displayPath,
-            ...(record.identity ? { identity: record.identity } : {}),
         };
     }
     async assertCurrent(lease, signal) {
@@ -184,16 +241,16 @@ export class FileMutationIntentController {
             throw new Error("Operation aborted");
         if (lease.kind === "write") {
             if (await this.operations.inspect(lease.path, false)) {
-                throw new Error(`Write collision: ${lease.displayPath} already exists; the prepared intent is stale.`);
+                throw new FileMutationPreflightError("write_collision", `Write collision: ${lease.displayPath} became occupied after preflight; no content was overwritten.`);
             }
             return;
         }
         const current = await this.operations.inspect(lease.path, true);
         if (!current || current.kind !== "file") {
-            throw new Error(`Could not edit file: ${lease.displayPath}. The prepared target no longer exists.`);
+            throw new Error(`Could not edit file: ${lease.displayPath}. The target no longer exists after preflight.`);
         }
         if (!identitiesMatch(lease.identity, current.identity)) {
-            throw new Error(`Could not edit file: ${lease.displayPath}. The file changed after preparation; prepare again.`);
+            throw new Error(`Could not edit file: ${lease.displayPath}. The file changed during edit execution; read it again before retrying.`);
         }
         try {
             await this.operations.access(lease.path, constants.R_OK | constants.W_OK);
@@ -207,7 +264,97 @@ export class FileMutationIntentController {
         const digest = createHash("sha256").update(content, "utf8").digest("hex");
         return this.rememberContentDigest(sourcePath, digest, Buffer.byteLength(content, "utf8"));
     }
+    async retainMutationPayload(kind, payload) {
+        return this.runMutationPayloadOperation(async () => {
+            await this.pruneExpiredMutationPayloads();
+            const byteLength = Buffer.byteLength(payload, "utf8");
+            if (byteLength > this.mutationPayloadByteLimit)
+                return undefined;
+            while (this.mutationPayloads.size >= this.mutationPayloadLimit ||
+                this.mutationPayloadBytes + byteLength > this.mutationPayloadByteLimit) {
+                const oldestPayloadRef = this.mutationPayloads.keys().next().value;
+                if (typeof oldestPayloadRef !== "string")
+                    return undefined;
+                await this.deleteMutationPayload(oldestPayloadRef, true);
+            }
+            // Keep insertion and expiry order identical, even if the wall clock moves backward. Expiry
+            // pruning can then stop at the first live record instead of rescanning every retained payload.
+            const expiresAt = Math.max(this.lastMutationPayloadExpiresAt, this.now() + this.mutationPayloadTtlMs);
+            this.lastMutationPayloadExpiresAt = expiresAt;
+            let sourcePath;
+            try {
+                sourcePath = await this.operations.stagePayload(payload, this.mutationPayloadTtlMs);
+            }
+            catch (error) {
+                if (error instanceof MutationPayloadCapacityError)
+                    return undefined;
+                throw error;
+            }
+            const payloadRef = `${MUTATION_PAYLOAD_REFERENCE_PREFIX}${randomUUID()}`;
+            this.mutationPayloads.set(payloadRef, {
+                payloadRef,
+                kind,
+                sourcePath,
+                digest: createHash("sha256").update(payload, "utf8").digest("hex"),
+                byteLength,
+                expiresAt,
+            });
+            this.mutationPayloadBytes += byteLength;
+            return { payloadRef, byteLength };
+        });
+    }
+    async readMutationPayload(payloadRef, kind, signal) {
+        return this.runMutationPayloadOperation(async () => {
+            const record = await this.requireMutationPayload(payloadRef, kind, signal);
+            const payload = await this.operations.readPayload(record.sourcePath);
+            if (createHash("sha256").update(payload, "utf8").digest("hex") !== record.digest) {
+                await this.deleteMutationPayload(payloadRef);
+                throw new Error("Retained file mutation payload changed after it was cached.");
+            }
+            return payload;
+        });
+    }
+    async assertMutationPayload(payloadRef, kind, signal) {
+        await this.runMutationPayloadOperation(async () => {
+            await this.requireVerifiedMutationPayload(payloadRef, kind, signal);
+        });
+    }
+    async assertContentReference(contentRef, signal) {
+        await this.requireVerifiedContentReference(contentRef, signal);
+    }
+    async copyMutationPayload(payloadRef, targetPath, signal) {
+        return this.runMutationPayloadOperation(async () => {
+            const record = await this.requireVerifiedMutationPayload(payloadRef, "write", signal);
+            await this.copyVerifiedSource(record, targetPath, signal);
+            await this.deleteMutationPayload(payloadRef);
+            return this.rememberContentDigest(targetPath, record.digest, record.byteLength);
+        });
+    }
+    async discardMutationPayload(payloadRef) {
+        await this.runMutationPayloadOperation(() => this.deleteMutationPayload(payloadRef));
+    }
+    /** Release every payload owned by this controller without touching another controller's files. */
+    async dispose() {
+        await this.runMutationPayloadOperation(async () => {
+            let firstError;
+            for (const payloadRef of [...this.mutationPayloads.keys()]) {
+                try {
+                    await this.deleteMutationPayload(payloadRef, true);
+                }
+                catch (error) {
+                    firstError ??= error;
+                }
+            }
+            if (firstError)
+                throw firstError;
+        });
+    }
     async copyReferencedContent(contentRef, targetPath, signal) {
+        const record = await this.requireVerifiedContentReference(contentRef, signal);
+        await this.copyVerifiedSource(record, targetPath, signal);
+        return this.rememberContentDigest(targetPath, record.digest, record.byteLength);
+    }
+    async requireVerifiedContentReference(contentRef, signal) {
         this.pruneExpired();
         const record = this.contentReferences.get(contentRef);
         if (!record)
@@ -215,17 +362,51 @@ export class FileMutationIntentController {
         this.touchContentReference(record);
         if (signal?.aborted)
             throw new Error("Operation aborted");
+        try {
+            await this.verifySource(record, signal, "File content reference source");
+        }
+        catch (error) {
+            this.contentReferences.delete(contentRef);
+            throw error;
+        }
+        return record;
+    }
+    async requireMutationPayload(payloadRef, kind, signal) {
+        await this.pruneExpiredMutationPayloads();
+        if (signal?.aborted)
+            throw new Error("Operation aborted");
+        const record = this.mutationPayloads.get(payloadRef);
+        if (!record) {
+            throw new Error("File mutation payload reference is invalid, expired, or belongs to another session.");
+        }
+        if (record.kind !== kind) {
+            throw new Error(`File mutation payload reference is for ${record.kind}, not ${kind}.`);
+        }
+        return record;
+    }
+    async requireVerifiedMutationPayload(payloadRef, kind, signal) {
+        const record = await this.requireMutationPayload(payloadRef, kind, signal);
+        try {
+            await this.verifySource(record, signal, "Retained file mutation payload");
+        }
+        catch (error) {
+            await this.deleteMutationPayload(payloadRef);
+            throw error;
+        }
+        return record;
+    }
+    async verifySource(record, signal, label) {
         let sourceDigest;
         try {
             sourceDigest = await this.operations.hashFile(record.sourcePath, signal);
         }
         catch (error) {
-            throw new Error(`File content reference source is unavailable: ${String(error)}.`);
-        }
-        if (sourceDigest !== record.digest) {
-            this.contentReferences.delete(contentRef);
-            throw new Error("File content reference source changed after it was cached.");
+            throw new Error(`${label} is unavailable: ${String(error)}.`);
         }
+        if (sourceDigest !== record.digest)
+            throw new Error(`${label} changed after it was cached.`);
+    }
+    async copyVerifiedSource(record, targetPath, signal) {
         await this.operations.copyFileExclusive(record.sourcePath, targetPath);
         let targetDigest;
         try {
@@ -239,7 +420,6 @@ export class FileMutationIntentController {
             await this.removeFailedCopy(targetPath, new Error("copied bytes did not match the cached digest"));
             throw new Error("File content copy changed while it was being created; the target was removed.");
         }
-        return this.rememberContentDigest(targetPath, record.digest, record.byteLength);
     }
     async assertCreatableParent(path) {
         let candidate = dirname(path);
@@ -301,21 +481,35 @@ export class FileMutationIntentController {
             throw new Error(`Copied content verification failed (${String(cause)}), and the newly created target could not be removed: ${String(cleanupError)}.`);
         }
     }
-    deleteIntent(intentId) {
-        const record = this.intents.get(intentId);
+    async deleteMutationPayload(payloadRef, strict = false) {
+        const record = this.mutationPayloads.get(payloadRef);
         if (!record)
             return;
-        this.intents.delete(intentId);
-        const key = `${record.kind}\0${normalizedPath(record.path)}`;
-        if (this.intentByPath.get(key) === intentId)
-            this.intentByPath.delete(key);
+        this.mutationPayloads.delete(payloadRef);
+        this.mutationPayloadBytes -= record.byteLength;
+        try {
+            await this.operations.removeFile(record.sourcePath);
+        }
+        catch (error) {
+            if (strict && !isMissingPathError(error))
+                throw error;
+        }
     }
-    pruneExpired() {
+    runMutationPayloadOperation(operation) {
+        const run = this.mutationPayloadOperationTail.then(operation, operation);
+        this.mutationPayloadOperationTail = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async pruneExpiredMutationPayloads() {
         const now = this.now();
-        for (const [intentId, record] of this.intents) {
-            if (record.expiresAt <= now)
-                this.deleteIntent(intentId);
+        for (const [payloadRef, record] of this.mutationPayloads) {
+            if (record.expiresAt > now)
+                break;
+            await this.deleteMutationPayload(payloadRef, true);
         }
+    }
+    pruneExpired() {
+        const now = this.now();
         for (const [contentRef, record] of this.contentReferences) {
             if (record.expiresAt <= now)
                 this.contentReferences.delete(contentRef);