@openclaw/signal 2026.9.4 → 2026.9.6

package/node_modules/@openclaw/fs-safe/dist/json-durable-queue-ownership.js

@@ -0,0 +1,355 @@
+import { randomUUID } from "node:crypto";
+import { withSidecarLock } from "./sidecar-lock.js";
+import fsSync, {} from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { syncDirectory } from "./directory-durability.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup, sha256Hex } from "./file-identity.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { serializePathWrite } from "./write-queue.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+const validatedDurableQueueEntryPaths = new WeakSet();
+function assertQueuePathString(value, label) {
+    if (typeof value !== "string") {
+        throw new FsSafeError("invalid-path", `${label} must be a string`);
+    }
+}
+export function validateDurableQueueEntryPaths(paths) {
+    const jsonPath = paths.jsonPath;
+    const deliveredPath = paths.deliveredPath;
+    const requestedProcessingPath = paths.processingPath;
+    assertQueuePathString(jsonPath, "queue JSON path");
+    assertQueuePathString(deliveredPath, "queue delivered path");
+    if (requestedProcessingPath !== undefined) {
+        assertQueuePathString(requestedProcessingPath, "queue processing path");
+    }
+    assertNoWindowsPathAlias(jsonPath);
+    assertNoWindowsPathAlias(deliveredPath);
+    if (requestedProcessingPath !== undefined) {
+        assertNoWindowsPathAlias(requestedProcessingPath);
+    }
+    const processingPath = requestedProcessingPath || processingPathFromJsonPath(jsonPath);
+    const validated = Object.freeze({ deliveredPath, jsonPath, processingPath });
+    validatedDurableQueueEntryPaths.add(validated);
+    return validated;
+}
+function ownDurableQueueEntryPaths(paths) {
+    if (validatedDurableQueueEntryPaths.has(paths)) {
+        return paths;
+    }
+    return validateDurableQueueEntryPaths(paths);
+}
+function processingPathFromJsonPath(jsonPath) {
+    return jsonPath.endsWith(".json")
+        ? `${jsonPath.slice(0, -".json".length)}.processing`
+        : `${jsonPath}.processing`;
+}
+function regularQueueFileIdentity(filePath, subject = "entry") {
+    const identity = lstatOrNull(filePath);
+    if (!identity)
+        return null;
+    if (identity.isSymbolicLink() || !identity.isFile()) {
+        throw subject === "retirement"
+            ? new FsSafeError("path-mismatch", "queue retirement path is not a regular file")
+            : new Error(`queue entry is not a regular file: ${filePath}`);
+    }
+    return identity;
+}
+async function withQueueEntryLock(paths, run) {
+    const resolvedJsonPath = path.resolve(paths.jsonPath);
+    assertNoWindowsPathAlias(resolvedJsonPath);
+    return await serializePathWrite(paths.jsonPath, async () => await withQueueTransferLock(resolvedJsonPath, run));
+}
+async function claimDurableQueueEntryUnlocked(paths, options = {}) {
+    const processingPath = paths.processingPath;
+    await recoverDurableQueueRetirement({ jsonPath: paths.jsonPath, processingPath });
+    const existingProcessing = regularQueueFileIdentity(processingPath);
+    if (existingProcessing) {
+        const pending = lstatOrNull(paths.jsonPath);
+        const retiresPending = pending !== null &&
+            !pending.isSymbolicLink() &&
+            pending.isFile() &&
+            sameFileIdentityForCleanup(pending, existingProcessing);
+        if (!retiresPending ||
+            path.resolve(path.dirname(processingPath)) !== path.resolve(path.dirname(paths.jsonPath))) {
+            // An existing claim can contain a migration whose publication sync failed.
+            // Retirement already syncs this edge when both names share a parent.
+            await syncDirectory(path.dirname(processingPath));
+        }
+        if (retiresPending) {
+            await retireDurableQueueSource({ jsonPath: paths.jsonPath, processingPath });
+        }
+        return processingPath;
+    }
+    const pending = lstatOrNull(paths.jsonPath);
+    if (!pending || pending.isSymbolicLink() || !pending.isFile())
+        return null;
+    if (pending.nlink > 1n || !sameFileIdentityForCleanup(pending, pending)) {
+        // Batch admission may skip unowned input, never a failed owned transition.
+        if (options.skipUnowned)
+            return null;
+        throw new FsSafeError("path-mismatch", "queue entry is not exclusively owned");
+    }
+    try {
+        await fs.link(paths.jsonPath, processingPath);
+    }
+    catch (error) {
+        if (getErrorCode(error) === "EEXIST") {
+            if (!regularQueueFileIdentity(processingPath))
+                return null;
+            await syncDirectory(path.dirname(processingPath));
+            return processingPath;
+        }
+        if (getErrorCode(error) === "ENOENT")
+            return null;
+        throw error;
+    }
+    await syncDirectory(path.dirname(processingPath));
+    const claimed = regularQueueFileIdentity(processingPath);
+    if (!claimed || claimed.nlink > 2n) {
+        throw new FsSafeError("path-mismatch", "queue claim is not an owned regular file");
+    }
+    await retireDurableQueueSource({ jsonPath: paths.jsonPath, processingPath });
+    return processingPath;
+}
+export async function claimDurableQueueEntry(paths, options = {}) {
+    const validatedPaths = ownDurableQueueEntryPaths(paths);
+    if (!lstatOrNull(path.dirname(validatedPaths.jsonPath)))
+        return null;
+    return await withQueueEntryLock(validatedPaths, async () => await claimDurableQueueEntryUnlocked(validatedPaths, options));
+}
+// The caller retains its read pin until this owner releases it or migration settles.
+export async function migrateDurableQueueEntry(paths, expected, releaseReadPin, run) {
+    const validatedPaths = ownDurableQueueEntryPaths(paths);
+    return await withQueueEntryLock(validatedPaths, async () => {
+        const processingPath = validatedPaths.processingPath;
+        const assertCurrent = () => {
+            try {
+                inspectFileIdentitySync(() => {
+                    const current = fsSync.lstatSync(processingPath, { bigint: true });
+                    if (current.isSymbolicLink() || !current.isFile() || current.nlink !== 1n) {
+                        throw new FsSafeError("path-mismatch", "queue migration requires its original processing claim");
+                    }
+                    return current;
+                }, expected);
+            }
+            catch (error) {
+                if (getErrorCode(error) === "ENOENT") {
+                    throw new FsSafeError("path-mismatch", "queue processing claim disappeared before migration", { cause: error });
+                }
+                throw error;
+            }
+        };
+        assertCurrent();
+        return await run(processingPath, async () => {
+            assertCurrent();
+            if (process.platform === "win32") {
+                // Windows cannot replace our still-open target. Keep the transfer lock
+                // across release and reject changes made while the async close settles.
+                await releaseReadPin();
+                assertCurrent();
+            }
+        });
+    });
+}
+export async function completeDeliveredQueueEntry(paths) {
+    const validatedPaths = ownDurableQueueEntryPaths(paths);
+    if (!lstatOrNull(path.dirname(validatedPaths.deliveredPath)))
+        return false;
+    return await withQueueEntryLock(validatedPaths, async () => {
+        if (!regularQueueFileIdentity(validatedPaths.deliveredPath))
+            return false;
+        const processing = regularQueueFileIdentity(validatedPaths.processingPath);
+        await fs.unlink(validatedPaths.deliveredPath);
+        await syncDirectory(path.dirname(validatedPaths.deliveredPath));
+        return !processing;
+    });
+}
+export async function acknowledgeDurableQueueEntry(paths) {
+    const validatedPaths = ownDurableQueueEntryPaths(paths);
+    if (!lstatOrNull(path.dirname(validatedPaths.jsonPath)))
+        return;
+    await withQueueEntryLock(validatedPaths, async () => {
+        const processingPath = validatedPaths.processingPath;
+        const processing = regularQueueFileIdentity(processingPath);
+        const delivered = regularQueueFileIdentity(validatedPaths.deliveredPath);
+        if (!processing) {
+            if (delivered) {
+                await fs.unlink(validatedPaths.deliveredPath);
+            }
+            await syncDirectory(path.dirname(validatedPaths.deliveredPath));
+            if (regularQueueFileIdentity(validatedPaths.jsonPath)) {
+                throw new FsSafeError("path-mismatch", "queue acknowledgement requires a processing claim");
+            }
+            return;
+        }
+        if (delivered)
+            await fs.unlink(validatedPaths.deliveredPath);
+        await fs.rename(processingPath, validatedPaths.deliveredPath);
+        await syncDirectory(path.dirname(validatedPaths.deliveredPath));
+        await fs.unlink(validatedPaths.deliveredPath);
+        await syncDirectory(path.dirname(validatedPaths.deliveredPath));
+    });
+}
+export async function moveDurableQueueEntryToFailed(params) {
+    const pathsInput = params.paths;
+    const paths = ownDurableQueueEntryPaths(pathsInput);
+    const failedPath = params.failedPath;
+    assertQueuePathString(failedPath, "failed queue path");
+    assertNoWindowsPathAlias(failedPath);
+    await withQueueEntryLock(paths, async () => {
+        const processingPath = paths.processingPath;
+        const processing = regularQueueFileIdentity(processingPath);
+        const existingFailed = regularQueueFileIdentity(failedPath);
+        if (!processing && existingFailed) {
+            await syncDirectory(path.dirname(failedPath));
+            await syncDirectory(path.dirname(processingPath));
+            const recoveredFailed = regularQueueFileIdentity(failedPath);
+            if (!recoveredFailed ||
+                !sameFileIdentityForCleanup(existingFailed, recoveredFailed)) {
+                throw new FsSafeError("path-mismatch", "failed queue destination changed during recovery");
+            }
+            if (regularQueueFileIdentity(paths.jsonPath)) {
+                throw new FsSafeError("already-exists", "failed queue destination already exists");
+            }
+            return;
+        }
+        const sourcePath = processing
+            ? processingPath
+            : await claimDurableQueueEntryUnlocked(paths);
+        if (!sourcePath) {
+            throw Object.assign(new Error("queue entry does not exist"), { code: "ENOENT" });
+        }
+        const source = regularQueueFileIdentity(sourcePath);
+        const failed = regularQueueFileIdentity(failedPath);
+        if (failed && (!source || !sameFileIdentityForCleanup(source, failed))) {
+            throw new FsSafeError("already-exists", "failed queue destination already exists");
+        }
+        if (!failed)
+            await fs.link(sourcePath, failedPath);
+        await syncDirectory(path.dirname(failedPath));
+        await fs.unlink(sourcePath);
+        await syncDirectory(path.dirname(sourcePath));
+    });
+}
+const RETIREMENT_ROOT_NAME = ".fs-safe-retirements";
+const RETIREMENT_ENTRY_NAME = "entry";
+export function getErrorCode(error) {
+    return error && typeof error === "object" && "code" in error
+        ? String(error.code)
+        : null;
+}
+function lstatOrNull(filePath) {
+    try {
+        return fsSync.lstatSync(filePath, { bigint: true });
+    }
+    catch (error) {
+        if (getErrorCode(error) === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function assertDirectory(identity, label) {
+    if (identity.isSymbolicLink() || !identity.isDirectory()) {
+        throw new FsSafeError("path-mismatch", `${label} is not an owned directory`);
+    }
+}
+function retirementPaths(jsonPath) {
+    const rootPath = path.join(path.dirname(jsonPath), RETIREMENT_ROOT_NAME);
+    const dirPath = path.join(rootPath, path.basename(jsonPath));
+    return { dirPath, entryPath: path.join(dirPath, RETIREMENT_ENTRY_NAME), rootPath };
+}
+async function ensureRetirementRoot(jsonPath) {
+    const parentPath = path.dirname(jsonPath);
+    const rootPath = retirementPaths(jsonPath).rootPath;
+    await fs.mkdir(rootPath, { mode: 0o700 }).catch((error) => {
+        if (getErrorCode(error) !== "EEXIST")
+            throw error;
+    });
+    const root = fsSync.lstatSync(rootPath, { bigint: true });
+    assertDirectory(root, "queue retirement root");
+    await syncDirectory(parentPath);
+    return rootPath;
+}
+async function removeRetirementRecord(params) {
+    await fs.rmdir(params.dirPath).catch((error) => {
+        if (getErrorCode(error) !== "ENOENT")
+            throw error;
+    });
+    await syncDirectory(params.rootPath);
+}
+async function recoverDurableQueueRetirement(params) {
+    const { rootPath, dirPath, entryPath } = retirementPaths(params.jsonPath);
+    const root = lstatOrNull(rootPath);
+    if (!root)
+        return;
+    assertDirectory(root, "queue retirement root");
+    const dir = lstatOrNull(dirPath);
+    if (!dir)
+        return;
+    assertDirectory(dir, "queue retirement record");
+    const names = await fs.readdir(dirPath);
+    if (names.length === 0) {
+        await removeRetirementRecord({ dirPath, rootPath });
+        return;
+    }
+    if (names.length !== 1 || names[0] !== RETIREMENT_ENTRY_NAME) {
+        throw new FsSafeError("path-mismatch", "queue retirement record is ambiguous");
+    }
+    const entry = regularQueueFileIdentity(entryPath, "retirement");
+    const processing = regularQueueFileIdentity(params.processingPath, "retirement");
+    if (!entry || !processing) {
+        throw new FsSafeError("path-mismatch", "queue retirement ownership is incomplete");
+    }
+    if (!sameFileIdentityForCleanup(entry, processing)) {
+        const pending = regularQueueFileIdentity(params.jsonPath, "retirement");
+        if (!pending) {
+            await fs.link(entryPath, params.jsonPath);
+            await syncDirectory(path.dirname(params.jsonPath));
+        }
+        else if (sameFileIdentityForCleanup(pending, entry)) {
+            await syncDirectory(path.dirname(params.jsonPath));
+        }
+        else if (pending.nlink > 1n) {
+            throw new FsSafeError("path-mismatch", "queue replacement identity is ambiguous");
+        }
+    }
+    await fs.unlink(entryPath);
+    await syncDirectory(dirPath);
+    await removeRetirementRecord({ dirPath, rootPath });
+}
+async function retireDurableQueueSource(params) {
+    await recoverDurableQueueRetirement(params);
+    const rootPath = await ensureRetirementRoot(params.jsonPath);
+    const { dirPath, entryPath } = retirementPaths(params.jsonPath);
+    await fs.mkdir(dirPath, { mode: 0o700 });
+    await syncDirectory(rootPath);
+    try {
+        await fs.rename(params.jsonPath, entryPath);
+    }
+    catch (error) {
+        if (getErrorCode(error) !== "ENOENT")
+            throw error;
+        await removeRetirementRecord({ dirPath, rootPath });
+        return;
+    }
+    await syncDirectory(dirPath);
+    await syncDirectory(path.dirname(params.jsonPath));
+    await recoverDurableQueueRetirement(params);
+}
+async function withQueueTransferLock(filePath, run) {
+    const lockPath = path.join(path.dirname(filePath), `.fs-safe-transfer-${sha256Hex(path.basename(filePath)).slice(0, 32)}.lock`);
+    return await withSidecarLock(filePath, {
+        managerKey: "fs-safe.queue-transfer",
+        lockPath,
+        staleMs: 30_000,
+        staleRecovery: "fail-closed",
+        timeoutMs: 45_000,
+        payload: () => ({
+            ownerToken: randomUUID(),
+            createdAt: new Date().toISOString(),
+        }),
+        retry: { retries: 180, minTimeout: 25, maxTimeout: 250, factor: 1.1 },
+    }, run);
+}

package/node_modules/@openclaw/fs-safe/dist/json-durable-queue-read.d.ts

@@ -0,0 +1,5 @@
+import { type BigIntStats } from "node:fs";
+export declare const DEFAULT_JSON_DURABLE_QUEUE_ENTRY_MAX_BYTES: number;
+export declare function withJsonDurableQueueEntry<T, R>(filePath: string, options: {
+    maxBytes?: number;
+}, run: (entry: T, identity: BigIntStats, releaseReadPin: () => Promise<void>) => Promise<R>): Promise<R>;

package/node_modules/@openclaw/fs-safe/dist/json-durable-queue-read.js

@@ -0,0 +1,65 @@
+import fs, {} from "node:fs";
+import { normalizeMaxBytes } from "./byte-budget.js";
+import { readBoundedAsync } from "./bounded-read.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+export const DEFAULT_JSON_DURABLE_QUEUE_ENTRY_MAX_BYTES = 16 * 1024 * 1024;
+function inspectQueueEntry(inspect, maxBytes, expected) {
+    let inspectionFailed = false;
+    try {
+        return inspectFileIdentitySync(() => {
+            try {
+                const stat = inspect();
+                if (stat.isSymbolicLink() || !stat.isFile()) {
+                    throw new Error("queue entry is not a regular file");
+                }
+                if (stat.nlink > 1n)
+                    throw new Error("queue entry hardlinks are not allowed");
+                if (stat.size > maxBytes)
+                    throw new Error(`queue entry exceeds ${maxBytes} bytes`);
+                return stat;
+            }
+            catch (error) {
+                inspectionFailed = true;
+                throw error;
+            }
+        }, expected);
+    }
+    catch (error) {
+        // Translate only the identity helper's rejection, never inspection errors.
+        if (inspectionFailed)
+            throw error;
+        throw new Error("queue entry changed during read", { cause: error });
+    }
+}
+export async function withJsonDurableQueueEntry(filePath, options, run) {
+    const maxBytes = normalizeMaxBytes(options.maxBytes, {
+        defaultValue: DEFAULT_JSON_DURABLE_QUEUE_ENTRY_MAX_BYTES,
+    });
+    assertNoWindowsPathAlias(filePath);
+    const inspectPath = () => fs.lstatSync(filePath, { bigint: true });
+    const initialStat = inspectQueueEntry(inspectPath, maxBytes);
+    const handle = await fs.promises.open(filePath, resolveReadOpenFlags());
+    let closePromise;
+    const releaseReadPin = () => closePromise ??= (async () => { await handle.close(); })();
+    let result;
+    try {
+        const openedStat = inspectQueueEntry(() => fs.fstatSync(handle.fd, { bigint: true }), maxBytes, initialStat);
+        inspectQueueEntry(inspectPath, maxBytes, openedStat);
+        const bytes = await readBoundedAsync(maxBytes, async (buffer, length) => (await handle.read(buffer, 0, length, null)).bytesRead, {
+            initialSize: openedStat.size >= 0n && Number.isSafeInteger(Number(openedStat.size))
+                ? Number(openedStat.size) : undefined,
+            createLimitError: () => new Error(`queue entry exceeds ${maxBytes} bytes`),
+        });
+        // The migration owner may release this pin only at the verified publication
+        // boundary; until then an unlinked inode cannot be recycled into a new claim.
+        result = await run(JSON.parse(bytes.toString("utf8")), openedStat, releaseReadPin);
+    }
+    catch (error) {
+        await releaseReadPin().catch(() => undefined);
+        throw error;
+    }
+    await releaseReadPin();
+    return result;
+}

package/node_modules/@openclaw/fs-safe/dist/json-durable-queue.d.ts

@@ -0,0 +1,45 @@
+export { DEFAULT_JSON_DURABLE_QUEUE_ENTRY_MAX_BYTES } from "./json-durable-queue-read.js";
+export type JsonDurableQueueEntryPaths = {
+    jsonPath: string;
+    deliveredPath: string;
+    processingPath?: string;
+};
+export type JsonDurableQueueReadResult<T> = {
+    entry: T;
+    migrated?: boolean;
+};
+export type JsonDurableQueueLoadOptions<T> = {
+    queueDir: string;
+    tempPrefix: string;
+    read?: (entry: T, filePath: string) => Promise<JsonDurableQueueReadResult<T>>;
+    cleanupTmpMaxAgeMs?: number;
+    maxBytes?: number;
+};
+export declare function unlinkBestEffort(filePath: string): Promise<void>;
+export declare function jsonDurableQueueEntryExists(filePath: string): Promise<boolean>;
+export declare function resolveJsonDurableQueueEntryPaths(queueDir: string, id: string): JsonDurableQueueEntryPaths;
+export declare function ensureJsonDurableQueueDirs(params: {
+    queueDir: string;
+    failedDir: string;
+}): Promise<void>;
+export declare function writeJsonDurableQueueEntry(params: {
+    filePath: string;
+    entry: unknown;
+    tempPrefix: string;
+}): Promise<void>;
+export declare function readJsonDurableQueueEntry<T>(filePath: string, options?: {
+    maxBytes?: number;
+}): Promise<T>;
+export declare function ackJsonDurableQueueEntry(paths: JsonDurableQueueEntryPaths): Promise<void>;
+export declare function loadJsonDurableQueueEntry<T>(params: {
+    paths: JsonDurableQueueEntryPaths;
+    tempPrefix: string;
+    read?: (entry: T, filePath: string) => Promise<JsonDurableQueueReadResult<T>>;
+    maxBytes?: number;
+}): Promise<T | null>;
+export declare function loadPendingJsonDurableQueueEntries<T>(options: JsonDurableQueueLoadOptions<T>): Promise<T[]>;
+export declare function moveJsonDurableQueueEntryToFailed(params: {
+    queueDir: string;
+    failedDir: string;
+    id: string;
+}): Promise<void>;

package/node_modules/@openclaw/fs-safe/dist/json-durable-queue.js

@@ -0,0 +1,215 @@
+import fs, {} from "node:fs";
+import path from "node:path";
+import { syncDirectory } from "./directory-durability.js";
+import { queueDirectories } from "./json-durable-queue-directory.js";
+import { getErrorCode, acknowledgeDurableQueueEntry, claimDurableQueueEntry, completeDeliveredQueueEntry, migrateDurableQueueEntry, moveDurableQueueEntryToFailed, validateDurableQueueEntryPaths, } from "./json-durable-queue-ownership.js";
+import { withJsonDurableQueueEntry } from "./json-durable-queue-read.js";
+import { stringifyJsonDocument } from "./json-stringify.js";
+import { replaceFileAtomicWithDirectorySync } from "./replace-file.js";
+import { assertSafePathSegment } from "./safe-path-segment.js";
+import { admitStandalonePublicationPath, assertNoWindowsPathAlias, hasWindowsPathAlias, } from "./windows-path-alias.js";
+export { DEFAULT_JSON_DURABLE_QUEUE_ENTRY_MAX_BYTES } from "./json-durable-queue-read.js";
+function assertSafeQueueEntryId(id) {
+    assertSafePathSegment(id, { label: "queue entry id" });
+}
+export async function unlinkBestEffort(filePath) {
+    if (hasWindowsPathAlias(filePath, "filesystem"))
+        return;
+    await fs.promises.unlink(filePath).catch(() => undefined);
+}
+export async function jsonDurableQueueEntryExists(filePath) {
+    assertNoWindowsPathAlias(filePath);
+    try {
+        const stat = fs.lstatSync(filePath);
+        return stat.isFile();
+    }
+    catch (error) {
+        if (getErrorCode(error) === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+async function unlinkStaleTmpBestEffort(filePath, now, maxAgeMs) {
+    try {
+        const stat = fs.statSync(filePath);
+        if (stat.isFile() && now - stat.mtimeMs >= maxAgeMs) {
+            await unlinkBestEffort(filePath);
+        }
+    }
+    catch (error) {
+        if (getErrorCode(error) !== "ENOENT") {
+            throw error;
+        }
+    }
+}
+export function resolveJsonDurableQueueEntryPaths(queueDir, id) {
+    assertSafeQueueEntryId(id);
+    assertNoWindowsPathAlias(queueDir);
+    return {
+        jsonPath: path.join(queueDir, `${id}.json`),
+        deliveredPath: path.join(queueDir, `${id}.delivered`),
+        processingPath: path.join(queueDir, `${id}.processing`),
+    };
+}
+export async function ensureJsonDurableQueueDirs(params) {
+    const queueDir = params.queueDir;
+    const failedDir = params.failedDir;
+    assertNoWindowsPathAlias(queueDir);
+    assertNoWindowsPathAlias(failedDir);
+    const directories = await queueDirectories(queueDir, failedDir);
+    await directories.queue.ensure();
+    await directories.failed.ensure();
+}
+export async function writeJsonDurableQueueEntry(params) {
+    await writeQueueEntry(params);
+}
+async function writeQueueEntry(params, beforeRename) {
+    const filePath = admitStandalonePublicationPath(params.filePath);
+    const entry = params.entry;
+    const tempPrefix = params.tempPrefix;
+    await replaceFileAtomicWithDirectorySync({
+        filePath,
+        content: stringifyJsonDocument(entry, null, 2),
+        mode: 0o600,
+        tempPrefix,
+        syncTempFile: true,
+        beforeRename,
+    }, syncDirectory);
+}
+export async function readJsonDurableQueueEntry(filePath, options = {}) {
+    return await withJsonDurableQueueEntry(filePath, options, async (entry) => entry);
+}
+async function migrateClaimedQueueEntry(params) {
+    await migrateDurableQueueEntry(params.paths, params.identity, params.releaseReadPin, async (filePath, beforePublish) => {
+        await writeQueueEntry({ filePath, entry: params.entry, tempPrefix: params.tempPrefix }, beforePublish);
+    });
+}
+export async function ackJsonDurableQueueEntry(paths) {
+    await acknowledgeDurableQueueEntry(paths);
+}
+export async function loadJsonDurableQueueEntry(params) {
+    const pathsInput = params.paths;
+    const paths = validateDurableQueueEntryPaths(pathsInput);
+    const claimedPath = await claimDurableQueueEntry(paths);
+    if (!claimedPath)
+        return null;
+    const readOptions = { maxBytes: params.maxBytes };
+    let processingStarted = false;
+    try {
+        return await withJsonDurableQueueEntry(claimedPath, readOptions, async (raw, identity, releaseReadPin) => {
+            processingStarted = true;
+            const read = params.read;
+            const result = read ? await Reflect.apply(read, params, [raw, paths.jsonPath]) : { entry: raw };
+            if (result.migrated) {
+                await migrateClaimedQueueEntry({
+                    paths, identity, releaseReadPin, entry: result.entry, tempPrefix: params.tempPrefix,
+                });
+            }
+            return result.entry;
+        });
+    }
+    catch (error) {
+        if (!processingStarted && getErrorCode(error) === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function loadPendingJsonDurableQueueEntries(options) {
+    const queueDir = options.queueDir;
+    assertNoWindowsPathAlias(queueDir);
+    let files;
+    try {
+        files = await fs.promises.readdir(queueDir);
+    }
+    catch (error) {
+        if (getErrorCode(error) === "ENOENT") {
+            return [];
+        }
+        throw error;
+    }
+    const now = Date.now();
+    for (const file of files) {
+        if (file.endsWith(".delivered")) {
+            const id = file.slice(0, -".delivered".length);
+            try {
+                assertSafeQueueEntryId(id);
+            }
+            catch {
+                continue;
+            }
+            const paths = validateDurableQueueEntryPaths(resolveJsonDurableQueueEntryPaths(queueDir, id));
+            await completeDeliveredQueueEntry(paths);
+        }
+        else if (options.cleanupTmpMaxAgeMs !== undefined && file.endsWith(".tmp")) {
+            await unlinkStaleTmpBestEffort(path.join(queueDir, file), now, options.cleanupTmpMaxAgeMs);
+        }
+    }
+    const ids = [];
+    const seenIds = new Set();
+    for (const file of files) {
+        const suffix = file.endsWith(".processing")
+            ? ".processing"
+            : file.endsWith(".json")
+                ? ".json"
+                : null;
+        if (!suffix)
+            continue;
+        const id = file.slice(0, -suffix.length);
+        try {
+            assertSafeQueueEntryId(id);
+        }
+        catch {
+            continue;
+        }
+        if (seenIds.has(id))
+            continue;
+        seenIds.add(id);
+        ids.push(id);
+    }
+    const entries = [];
+    for (const id of ids) {
+        const paths = validateDurableQueueEntryPaths(resolveJsonDurableQueueEntryPaths(queueDir, id));
+        const claimedPath = await claimDurableQueueEntry(paths, { skipUnowned: true });
+        if (!claimedPath)
+            continue;
+        let migrationStarted = false;
+        try {
+            const entry = await withJsonDurableQueueEntry(claimedPath, { maxBytes: options.maxBytes }, async (raw, identity, releaseReadPin) => {
+                const read = options.read;
+                const result = read ? await Reflect.apply(read, options, [raw, paths.jsonPath]) : { entry: raw };
+                if (result.migrated) {
+                    migrationStarted = true;
+                    await migrateClaimedQueueEntry({
+                        paths, identity, releaseReadPin, entry: result.entry, tempPrefix: options.tempPrefix,
+                    });
+                }
+                return result.entry;
+            });
+            entries.push(entry);
+        }
+        catch (error) {
+            if (migrationStarted)
+                throw error;
+            continue;
+        }
+    }
+    return entries;
+}
+export async function moveJsonDurableQueueEntryToFailed(params) {
+    const id = params.id;
+    const queueDir = params.queueDir;
+    const failedDir = params.failedDir;
+    assertSafeQueueEntryId(id);
+    assertNoWindowsPathAlias(queueDir);
+    assertNoWindowsPathAlias(failedDir);
+    const directories = await queueDirectories(queueDir, failedDir);
+    await directories.queue.assert();
+    await directories.failed.ensure();
+    const paths = validateDurableQueueEntryPaths(resolveJsonDurableQueueEntryPaths(queueDir, id));
+    await moveDurableQueueEntryToFailed({
+        paths,
+        failedPath: path.join(failedDir, `${id}.json`),
+    });
+}