@openclaw/crabline 0.1.11 → 0.1.12

package/dist/src/providers/recorder.js

@@ -1,6 +1,12 @@
-import { lstat, mkdir, open, readFile, readlink, realpath } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import { chmod, lstat, mkdir, open, readFile, readlink, realpath } from "node:fs/promises";
+import { userInfo } from "node:os";
 import path from "node:path";
 import { lock } from "proper-lockfile";
+import { createProcessOwnedLockFileSystem } from "../platform/process-owned-lock.js";
+import { isManagedRecorderDirectory } from "../platform/recorder-directory.js";
+import { createOwnerOnlyWindowsDirectory, readWindowsDirectoryNamespaceSecuritySnapshot, readWindowsDirectorySecuritySnapshot, } from "../platform/windows-acl.js";
+import { secureCachedWindowsLockRoot, } from "../platform/windows-lock-root.js";
 function sleep(ms, signal) {
     if (signal?.aborted) {
         return Promise.resolve();
@@ -17,6 +23,8 @@ function sleep(ms, signal) {
 }
 const pendingAppends = new Map();
 const recordIdentityIndexes = new Map();
+const securedWindowsLockRoots = new Map();
+const securedWindowsRecorderDirectories = new Map();
 const MAX_RECORD_IDENTITY_INDEXES = 128;
 const MAX_RECENT_RECORD_KEYS = 4096;
 const RECORDER_BATCH_VERSION = 1;
@@ -25,6 +33,14 @@ const RECORDER_LOCK_UPDATE_MS = 10_000;
 const RECORDER_ROTATION_ATTEMPTS = 3;
 class RecorderRotatedError extends Error {
 }
+export class ProviderRecorderCommittedError extends AggregateError {
+    committed = true;
+    indeterminate = true;
+    constructor(filePath, cause, relatedErrors = []) {
+        super([cause, ...relatedErrors], `Provider recorder append was published for "${filePath}", but durability or identity confirmation failed.`, { cause });
+        this.name = "ProviderRecorderCommittedError";
+    }
+}
 const CONTINUITY_BYTES = 4096;
 const MAX_INCREMENTAL_READ_BYTES = 256 * 1024;
 const MAX_PENDING_RECORD_BYTES = 4 * 1024 * 1024;
@@ -38,6 +54,20 @@ function createIncrementalReadState() {
         pending: Buffer.alloc(0),
     };
 }
+function snapshotIncrementalReadState(state) {
+    return {
+        ...state,
+        identity: state.identity ? { ...state.identity } : undefined,
+    };
+}
+function restoreIncrementalReadState(state, snapshot) {
+    state.caughtUp = snapshot.caughtUp;
+    state.continuity = snapshot.continuity;
+    state.generation = snapshot.generation;
+    state.identity = snapshot.identity;
+    state.offset = snapshot.offset;
+    state.pending = snapshot.pending;
+}
 export function createRecordedInboundCursor() {
     return {
         buffered: [],
@@ -188,11 +218,11 @@ function consumeRecordedChunk(state, chunk) {
     }
     return events;
 }
-async function appendJsonLine(filePath, line) {
+async function appendJsonLine(filePath, line, firstCreatedDirectory) {
     for (let attempt = 0;; attempt++) {
         try {
-            await serializeAppend(filePath, async (publicationPath, logicalPath) => {
-                await appendCommittedLine(publicationPath, logicalPath, line, true);
+            await serializeAppend(filePath, async (publicationPath, logicalPath, _lockCreatedFile, lockedIdentity) => {
+                await appendCommittedLine(publicationPath, logicalPath, line, true, lockedIdentity, firstCreatedDirectory);
             });
             return;
         }
@@ -212,6 +242,7 @@ async function readRecorderFileIdentity(filePath) {
         return {
             dev: stats.dev,
             ino: stats.ino,
+            nlink: stats.nlink,
         };
     }
     catch (error) {
@@ -224,6 +255,19 @@ async function readRecorderFileIdentity(filePath) {
 function sameRecorderFileIdentity(left, right) {
     return left?.dev === right?.dev && left?.ino === right?.ino;
 }
+function sameRecorderLockIdentity(left, right) {
+    return sameRecorderFileIdentity(left, right) && left?.nlink === right?.nlink;
+}
+function requireRecorderHandleIdentity(stats) {
+    if (stats.isFile?.() === false) {
+        throw new Error("Recorder path is not a regular file.");
+    }
+    return {
+        dev: stats.dev,
+        ino: stats.ino,
+        nlink: stats.nlink,
+    };
+}
 async function resolveRecorderPublicationPath(filePath) {
     try {
         return await realpath(filePath);
@@ -247,6 +291,94 @@ async function resolveRecorderPublicationPath(filePath) {
     }
     return path.join(await realpath(path.dirname(filePath)), path.basename(filePath));
 }
+async function openRecorderForAppend(filePath) {
+    const createFlags = process.platform === "win32"
+        ? "wx+"
+        : fsConstants.O_RDWR |
+            fsConstants.O_APPEND |
+            fsConstants.O_CREAT |
+            fsConstants.O_EXCL |
+            fsConstants.O_NONBLOCK |
+            fsConstants.O_NOFOLLOW;
+    const existingFlags = process.platform === "win32"
+        ? "r+"
+        : fsConstants.O_RDWR | fsConstants.O_APPEND | fsConstants.O_NONBLOCK | fsConstants.O_NOFOLLOW;
+    try {
+        return {
+            created: true,
+            handle: await open(filePath, createFlags, 0o600),
+        };
+    }
+    catch (error) {
+        if (error.code !== "EEXIST") {
+            throw error;
+        }
+        return {
+            created: false,
+            handle: await open(filePath, existingFlags, 0o600),
+        };
+    }
+}
+async function appendRecorderData(handle, data) {
+    if (process.platform !== "win32") {
+        await handle.writeFile(data, "utf8");
+        return;
+    }
+    const bytes = Buffer.from(data, "utf8");
+    const position = (await handle.stat()).size;
+    let offset = 0;
+    while (offset < bytes.length) {
+        const { bytesWritten } = await handle.write(bytes, offset, bytes.length - offset, position + offset);
+        if (bytesWritten === 0) {
+            throw new Error("Could not append recorder data.");
+        }
+        offset += bytesWritten;
+    }
+}
+async function syncParentDirectory(filePath) {
+    if (process.platform === "win32") {
+        return;
+    }
+    const directory = await open(path.dirname(filePath), "r");
+    try {
+        await directory.sync();
+    }
+    finally {
+        await directory.close();
+    }
+}
+async function syncRecorderPathAncestry(filePath, firstCreatedDirectory) {
+    if (process.platform === "win32") {
+        return;
+    }
+    const resolvedFilePath = path.resolve(filePath);
+    let currentPath = resolvedFilePath;
+    const syncThroughPath = firstCreatedDirectory === undefined ? undefined : path.resolve(firstCreatedDirectory);
+    for (;;) {
+        const directoryPath = path.dirname(currentPath);
+        const mandatory = syncThroughPath !== undefined || currentPath === resolvedFilePath;
+        try {
+            await syncParentDirectory(currentPath);
+        }
+        catch (error) {
+            const code = error.code;
+            if (!mandatory && (code === "EACCES" || code === "EPERM")) {
+                return;
+            }
+            throw error;
+        }
+        if (syncThroughPath === undefined) {
+            return;
+        }
+        if (currentPath === syncThroughPath) {
+            return;
+        }
+        if (path.dirname(directoryPath) === directoryPath) {
+            return;
+        }
+        currentPath = directoryPath;
+    }
+}
 async function prepareRecorderTailForAppend(handle) {
     const stats = await handle.stat();
     if (stats.size === 0) {
@@ -265,8 +397,8 @@ async function prepareRecorderTailForAppend(handle) {
     const tailStart = stats.size - windowSize + lastNewline + 1;
     const tail = tailWindow.subarray(lastNewline + 1).toString("utf8");
     try {
-        JSON.parse(tail);
-        await handle.writeFile("\n", "utf8");
+        parseRecordedLine(tail);
+        await appendRecorderData(handle, "\n");
         return true;
     }
     catch (error) {
@@ -277,11 +409,15 @@ async function prepareRecorderTailForAppend(handle) {
         return true;
     }
 }
-async function prepareRecorderPathForAppend(publicationPath, logicalPath, durable) {
-    const handle = await open(publicationPath, "a+");
-    const identity = await handle.stat({ bigint: true });
-    const recorderIdentity = { dev: identity.dev, ino: identity.ino };
+async function prepareRecorderPathForAppend(publicationPath, logicalPath, durable, expectedIdentity) {
+    const opened = await openRecorderForAppend(publicationPath);
+    const { handle } = opened;
+    const recorderIdentity = requireRecorderHandleIdentity(await handle.stat({ bigint: true }));
     try {
+        if (expectedIdentity !== undefined &&
+            !sameRecorderFileIdentity(expectedIdentity, recorderIdentity)) {
+            throw new RecorderRotatedError("Recorder rotated before preparing a committed line.");
+        }
         const changed = await prepareRecorderTailForAppend(handle);
         if (changed && durable) {
             await handle.sync();
@@ -293,35 +429,299 @@ async function prepareRecorderPathForAppend(publicationPath, logicalPath, durabl
     if (!sameRecorderFileIdentity(recorderIdentity, await readRecorderFileIdentity(await resolveRecorderPublicationPath(logicalPath)))) {
         throw new RecorderRotatedError("Recorder rotated while preparing a committed line.");
     }
-    return recorderIdentity;
+    return { created: opened.created, identity: recorderIdentity };
 }
-async function appendCommittedLine(publicationPath, logicalPath, line, durable, expectedIdentity) {
-    const handle = await open(publicationPath, "a+");
-    const identity = await handle.stat({ bigint: true });
-    const recorderIdentity = { dev: identity.dev, ino: identity.ino };
+function providerRecorderCloseError(filePath, operationError, closeError) {
+    return new AggregateError([operationError, closeError], `Provider recorder operation and file close both failed for "${filePath}".`, { cause: closeError });
+}
+async function appendCommittedLine(publicationPath, logicalPath, line, durable, expectedIdentity, firstCreatedDirectory) {
+    const opened = await openRecorderForAppend(publicationPath);
+    const { handle } = opened;
+    const recorderIdentity = requireRecorderHandleIdentity(await handle.stat({ bigint: true }));
+    let published = false;
+    let operationError;
     try {
         if (expectedIdentity !== undefined &&
             !sameRecorderFileIdentity(expectedIdentity, recorderIdentity)) {
             throw new RecorderRotatedError("Recorder rotated before appending a committed line.");
         }
         await prepareRecorderTailForAppend(handle);
-        await handle.writeFile(line, "utf8");
+        published = true;
+        await appendRecorderData(handle, line);
         if (durable) {
             await handle.sync();
         }
+        if (durable) {
+            const firstCreatedPath = firstCreatedDirectory ?? (opened.created ? publicationPath : undefined);
+            await syncRecorderPathAncestry(publicationPath, firstCreatedPath);
+        }
     }
-    finally {
+    catch (error) {
+        operationError = published ? new ProviderRecorderCommittedError(logicalPath, error) : error;
+    }
+    try {
         await handle.close();
     }
-    if (!sameRecorderFileIdentity(recorderIdentity, await readRecorderFileIdentity(await resolveRecorderPublicationPath(logicalPath)))) {
+    catch (closeError) {
+        if (operationError !== undefined) {
+            if (published) {
+                throw new ProviderRecorderCommittedError(logicalPath, operationError, [closeError]);
+            }
+            throw providerRecorderCloseError(logicalPath, operationError, closeError);
+        }
+        throw published ? new ProviderRecorderCommittedError(logicalPath, closeError) : closeError;
+    }
+    if (operationError !== undefined) {
+        throw operationError;
+    }
+    let publishedIdentity;
+    try {
+        publishedIdentity = await readRecorderFileIdentity(await resolveRecorderPublicationPath(logicalPath));
+    }
+    catch (error) {
+        throw new ProviderRecorderCommittedError(logicalPath, error);
+    }
+    if (!sameRecorderFileIdentity(recorderIdentity, publishedIdentity)) {
         throw new RecorderRotatedError("Recorder rotated while appending a committed line.");
     }
 }
-function recorderLockReleaseError(filePath, operationError, releaseError) {
-    return new AggregateError([operationError, releaseError], `Recorder append and lock release both failed for "${filePath}".`, { cause: operationError });
+function recorderLockReleaseError(filePath, operationError, releaseErrors) {
+    return new AggregateError([operationError, ...releaseErrors], `Recorder append and lock release both failed for "${filePath}".`, { cause: operationError });
 }
-async function withRecorderLock(filePath, operation) {
-    const release = await lock(filePath, {
+function recorderErrorDetail(error) {
+    if (error instanceof AggregateError) {
+        return error.errors.map(recorderErrorDetail).join("; ");
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+function reportRecorderLockReleaseFailure(filePath, releaseError) {
+    const detail = recorderErrorDetail(releaseError);
+    try {
+        process.emitWarning(`Provider recorder append committed but lock cleanup failed for "${filePath}": ${detail}`, {
+            code: "CRABLINE_RECORDER_LOCK_CLEANUP",
+            type: "ProviderRecorderWarning",
+        });
+    }
+    catch {
+        // Cleanup reporting must not change the result of a committed append.
+    }
+}
+async function verifyProviderRecorderLockAncestry(directory, currentUserId) {
+    let currentPath = path.resolve(directory);
+    for (;;) {
+        const current = await lstat(currentPath, { bigint: true });
+        const ownerIsTrusted = current.uid === BigInt(currentUserId) || current.uid === 0n;
+        if (current.isSymbolicLink()) {
+            if (!ownerIsTrusted) {
+                throw new Error("Provider recorder lock directory parent namespace is not trusted.");
+            }
+        }
+        else {
+            const peerWritable = (current.mode & 18n) !== 0n;
+            const sticky = (current.mode & 512n) !== 0n;
+            if (!current.isDirectory() || !ownerIsTrusted || (peerWritable && !sticky)) {
+                throw new Error("Provider recorder lock directory parent namespace is not trusted.");
+            }
+        }
+        const parent = path.dirname(currentPath);
+        if (parent === currentPath) {
+            return;
+        }
+        currentPath = parent;
+    }
+}
+async function prepareProviderRecorderLockRoot(root, currentUserId) {
+    let existingPath = path.resolve(root);
+    const missingComponents = [];
+    for (;;) {
+        try {
+            await lstat(existingPath);
+            break;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+            const parent = path.dirname(existingPath);
+            if (parent === existingPath) {
+                throw error;
+            }
+            missingComponents.unshift(path.basename(existingPath));
+            existingPath = parent;
+        }
+    }
+    await verifyProviderRecorderLockAncestry(existingPath, currentUserId);
+    let canonicalPath = await realpath(existingPath);
+    if (canonicalPath !== existingPath) {
+        await verifyProviderRecorderLockAncestry(canonicalPath, currentUserId);
+    }
+    for (const component of missingComponents) {
+        canonicalPath = path.join(canonicalPath, component);
+        try {
+            await mkdir(canonicalPath, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST") {
+                throw error;
+            }
+        }
+        const identity = await lstat(canonicalPath, { bigint: true });
+        if (!identity.isDirectory() ||
+            identity.isSymbolicLink() ||
+            identity.uid !== BigInt(currentUserId)) {
+            throw new Error("Provider recorder lock directory is not privately owned.");
+        }
+        await chmod(canonicalPath, 0o700);
+    }
+    return canonicalPath;
+}
+export async function secureProviderRecorderLockRoot(root, currentUserId, options = {}) {
+    if ((options.platform ?? process.platform) === "win32") {
+        const cacheKey = path.win32.normalize(path.resolve(root)).toLowerCase();
+        return secureCachedWindowsLockRoot({
+            cache: securedWindowsLockRoots,
+            cacheKey,
+            createDirectory: () => (options.createWindowsDirectory ?? createOwnerOnlyWindowsDirectory)(root),
+            errorPrefix: "Provider recorder lock directory",
+            readSecuritySnapshot: () => (options.readWindowsDirectorySecuritySnapshot ?? readWindowsDirectorySecuritySnapshot)(root),
+            root,
+        });
+    }
+    if (currentUserId === undefined) {
+        throw new Error("Provider recorder identity locking requires a current user id.");
+    }
+    const canonicalRoot = await prepareProviderRecorderLockRoot(root, currentUserId);
+    const handle = await open(canonicalRoot, fsConstants.O_RDONLY | fsConstants.O_DIRECTORY | fsConstants.O_NOFOLLOW);
+    try {
+        const identity = await handle.stat({ bigint: true });
+        const current = await lstat(canonicalRoot, { bigint: true });
+        if (!identity.isDirectory() ||
+            !current.isDirectory() ||
+            identity.dev !== current.dev ||
+            identity.ino !== current.ino ||
+            identity.uid !== BigInt(currentUserId) ||
+            current.uid !== BigInt(currentUserId)) {
+            throw new Error("Provider recorder lock directory is not privately owned.");
+        }
+        if ((identity.mode & 511n) !== 448n) {
+            await handle.chmod(0o700);
+            const secured = await handle.stat({ bigint: true });
+            if ((secured.mode & 511n) !== 448n) {
+                throw new Error("Provider recorder lock directory permissions are not private.");
+            }
+        }
+    }
+    finally {
+        await handle.close();
+    }
+    return canonicalRoot;
+}
+async function secureProviderRecorderWindowsDirectory(root) {
+    const cacheKey = path.win32.normalize(path.resolve(root)).toLowerCase();
+    return secureCachedWindowsLockRoot({
+        cache: securedWindowsRecorderDirectories,
+        cacheKey,
+        createDirectory: async () => {
+            try {
+                const identity = await lstat(root);
+                if (!identity.isDirectory() || identity.isSymbolicLink()) {
+                    throw new Error("Provider recorder Windows directory is not a private directory.");
+                }
+                if (isManagedRecorderDirectory(root)) {
+                    await createOwnerOnlyWindowsDirectory(root);
+                }
+            }
+            catch (error) {
+                if (error.code !== "ENOENT") {
+                    throw error;
+                }
+                await createOwnerOnlyWindowsDirectory(root);
+            }
+        },
+        errorPrefix: "Provider recorder Windows directory",
+        readSecuritySnapshot: () => readWindowsDirectoryNamespaceSecuritySnapshot(root),
+        root,
+    });
+}
+async function prepareRecorderDirectory(filePath) {
+    const directory = path.dirname(filePath);
+    if (process.platform === "win32") {
+        await secureProviderRecorderWindowsDirectory(directory);
+        return undefined;
+    }
+    const createdDirectory = await mkdir(directory, { recursive: true });
+    return createdDirectory === undefined ? undefined : await realpath(createdDirectory);
+}
+function recorderLockRootUnavailable(error) {
+    const code = error.code;
+    return (code === "EACCES" ||
+        code === "EDQUOT" ||
+        code === "ENOSPC" ||
+        code === "EPERM" ||
+        code === "EROFS");
+}
+function adjacentRecorderLockRoot(filePath, currentUserId) {
+    return path.join(path.dirname(filePath), currentUserId === undefined
+        ? ".crabline-provider-recorder-locks"
+        : `.crabline-provider-recorder-locks-${currentUserId}`);
+}
+function recorderIdentityLockPath(root, identity) {
+    return path.join(root, `recorder-${identity.dev}-${identity.ino}`);
+}
+async function recorderIdentityLockTargets(filePath, identity) {
+    const currentUserId = process.platform === "win32" ? undefined : process.geteuid?.();
+    let sharedRoot;
+    try {
+        const account = userInfo();
+        sharedRoot =
+            process.platform === "win32"
+                ? path.join(account.homedir, "AppData", "Local", "Crabline", "locks", "provider-recorder")
+                : path.join(account.homedir, ".cache", "crabline", "locks", "provider-recorder");
+    }
+    catch {
+        // Arbitrary container UIDs may not have an OS account entry.
+    }
+    if (sharedRoot) {
+        try {
+            return {
+                ...(identity.nlink === 1n
+                    ? { fallbackRoot: adjacentRecorderLockRoot(filePath, currentUserId) }
+                    : {}),
+                preferred: recorderIdentityLockPath(await secureProviderRecorderLockRoot(sharedRoot, currentUserId), identity),
+                userId: currentUserId,
+            };
+        }
+        catch (error) {
+            if (!recorderLockRootUnavailable(error)) {
+                throw error;
+            }
+        }
+    }
+    if (identity.nlink > 1n) {
+        throw new Error("Provider recorder hardlinks require a writable shared per-user lock directory.");
+    }
+    const adjacentRoot = await secureProviderRecorderLockRoot(adjacentRecorderLockRoot(filePath, currentUserId), currentUserId);
+    return {
+        preferred: recorderIdentityLockPath(adjacentRoot, identity),
+        userId: currentUserId,
+    };
+}
+async function acquireRecorderIdentityLock(filePath, identity) {
+    const targets = await recorderIdentityLockTargets(filePath, identity);
+    try {
+        return await acquireRecorderLock(targets.preferred);
+    }
+    catch (error) {
+        if (!targets.fallbackRoot || !recorderLockRootUnavailable(error)) {
+            throw error;
+        }
+        const fallbackRoot = await secureProviderRecorderLockRoot(targets.fallbackRoot, targets.userId);
+        return await acquireRecorderLock(recorderIdentityLockPath(fallbackRoot, identity));
+    }
+}
+async function acquireRecorderLock(filePath) {
+    return await lock(filePath, {
+        fs: createProcessOwnedLockFileSystem(),
         realpath: false,
         retries: {
             factor: 1,
@@ -332,28 +732,97 @@ async function withRecorderLock(filePath, operation) {
         stale: RECORDER_LOCK_STALE_MS,
         update: RECORDER_LOCK_UPDATE_MS,
     });
+}
+async function ensureRecorderExistsForLock(filePath) {
+    if (await readRecorderFileIdentity(filePath)) {
+        return false;
+    }
+    let handle;
+    try {
+        handle = await open(filePath, "ax", 0o600);
+    }
+    catch (error) {
+        if (error.code === "EEXIST") {
+            return false;
+        }
+        throw error;
+    }
+    await handle.close();
+    return true;
+}
+async function releaseRecorderLocks(releases) {
+    const errors = [];
+    for (const release of releases.reverse()) {
+        try {
+            await release();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+    }
+    return errors;
+}
+async function withRecorderLock(filePath, operation) {
+    const releases = [];
+    let lockCreatedFile = false;
+    let lockedIdentity;
+    try {
+        releases.push(await acquireRecorderLock(filePath));
+        for (let attempt = 0; attempt < RECORDER_ROTATION_ATTEMPTS; attempt += 1) {
+            lockCreatedFile = await ensureRecorderExistsForLock(filePath);
+            const identity = await readRecorderFileIdentity(filePath);
+            if (!identity) {
+                continue;
+            }
+            const releaseIdentityLock = await acquireRecorderIdentityLock(filePath, identity);
+            releases.push(releaseIdentityLock);
+            const currentIdentity = await readRecorderFileIdentity(filePath);
+            if (sameRecorderLockIdentity(identity, currentIdentity)) {
+                lockedIdentity = identity;
+                break;
+            }
+            const registeredIdentityRelease = releases.pop();
+            const releaseErrors = await releaseRecorderLocks(registeredIdentityRelease ? [registeredIdentityRelease] : []);
+            if (releaseErrors.length > 0) {
+                throw recorderLockReleaseError(filePath, new RecorderRotatedError("Recorder rotated while acquiring its identity lock."), releaseErrors);
+            }
+            if (attempt + 1 >= RECORDER_ROTATION_ATTEMPTS) {
+                throw new RecorderRotatedError("Recorder kept rotating while acquiring its identity lock.");
+            }
+        }
+        if (!lockedIdentity) {
+            throw new RecorderRotatedError("Recorder disappeared while acquiring its identity lock.");
+        }
+    }
+    catch (error) {
+        const releaseErrors = await releaseRecorderLocks(releases);
+        if (releaseErrors.length > 0) {
+            throw recorderLockReleaseError(filePath, error, releaseErrors);
+        }
+        throw error;
+    }
     let operationFailed = false;
     let operationError;
     let result;
     try {
-        result = await operation();
+        result = await operation(lockCreatedFile, lockedIdentity);
     }
     catch (error) {
         operationFailed = true;
         operationError = error;
     }
-    try {
-        await release();
-    }
-    catch (releaseError) {
-        if (operationFailed) {
-            throw recorderLockReleaseError(filePath, operationError, releaseError);
-        }
-        throw releaseError;
-    }
+    const releaseErrors = await releaseRecorderLocks(releases);
     if (operationFailed) {
+        if (releaseErrors.length > 0) {
+            throw recorderLockReleaseError(filePath, operationError, releaseErrors);
+        }
         throw operationError;
     }
+    if (releaseErrors.length > 0) {
+        reportRecorderLockReleaseFailure(filePath, releaseErrors.length === 1
+            ? releaseErrors[0]
+            : new AggregateError(releaseErrors, "Multiple recorder lock cleanup operations failed."));
+    }
     return result;
 }
 async function serializeAppend(filePath, operation) {
@@ -364,7 +833,7 @@ async function serializeAppend(filePath, operation) {
     const current = previous
         .catch(() => { })
         .then(async () => {
-        result = await withRecorderLock(key, async () => await operation(key, logicalPath));
+        result = await withRecorderLock(key, async (lockCreatedFile, lockedIdentity) => await operation(key, logicalPath, lockCreatedFile, lockedIdentity));
     });
     pendingAppends.set(key, current);
     try {
@@ -378,6 +847,7 @@ async function serializeAppend(filePath, operation) {
     }
 }
 async function readRecordedInboundAppend(filePath, state) {
+    const snapshot = snapshotIncrementalReadState(state);
     let handle;
     try {
         handle = await open(filePath, "r");
@@ -393,7 +863,8 @@ async function readRecordedInboundAppend(filePath, state) {
     }
     try {
         const stats = await handle.stat();
-        const identity = { dev: stats.dev, ino: stats.ino };
+        const identityStats = await handle.stat({ bigint: true });
+        const identity = { dev: identityStats.dev, ino: identityStats.ino };
         const sameFile = state.identity?.dev === identity.dev && state.identity.ino === identity.ino;
         const rotated = state.identity !== undefined && !sameFile;
         let hasContinuity = stats.size >= state.offset;
@@ -430,12 +901,16 @@ async function readRecordedInboundAppend(filePath, state) {
         state.caughtUp = reachedUnexpectedEof || position >= stats.size;
         return events;
     }
+    catch (error) {
+        restoreIncrementalReadState(state, snapshot);
+        throw error;
+    }
     finally {
         await handle.close();
     }
 }
 export async function appendRecordedInbound(filePath, event) {
-    await mkdir(path.dirname(filePath), { recursive: true });
+    const firstCreatedDirectory = await prepareRecorderDirectory(filePath);
     const recorded = {
         ...event,
         recordedAt: new Date().toISOString(),
@@ -444,18 +919,18 @@ export async function appendRecordedInbound(filePath, event) {
     if (Buffer.byteLength(line) > MAX_PENDING_RECORD_BYTES) {
         throw new Error(`Recorder record exceeded ${MAX_PENDING_RECORD_BYTES} bytes without a newline.`);
     }
-    await appendJsonLine(filePath, line);
+    await appendJsonLine(filePath, line, firstCreatedDirectory);
     return recorded;
 }
 export async function appendRecordedInboundBatch(filePath, events) {
     if (events.length === 0) {
         return [];
     }
-    await mkdir(path.dirname(filePath), { recursive: true });
+    const firstCreatedDirectory = await prepareRecorderDirectory(filePath);
     for (let attempt = 0;; attempt++) {
         try {
-            return await serializeAppend(filePath, async (publicationPath, logicalPath) => {
-                const generation = await prepareRecorderPathForAppend(publicationPath, logicalPath, true);
+            return await serializeAppend(filePath, async (publicationPath, logicalPath, _lockCreatedFile, lockedIdentity) => {
+                const generation = await prepareRecorderPathForAppend(publicationPath, logicalPath, true, lockedIdentity);
                 const seen = await syncRecordIdentityIndex(publicationPath);
                 const pendingIdentities = new Set();
                 const recorded = [];
@@ -480,10 +955,10 @@ export async function appendRecordedInboundBatch(filePath, events) {
                     if (Buffer.byteLength(line) > MAX_PENDING_RECORD_BYTES) {
                         throw new Error(`Recorder record exceeded ${MAX_PENDING_RECORD_BYTES} bytes without a newline.`);
                     }
-                    await appendCommittedLine(publicationPath, logicalPath, line, true, generation);
+                    await appendCommittedLine(publicationPath, logicalPath, line, true, generation.identity, firstCreatedDirectory);
                     await syncRecordIdentityIndex(publicationPath);
                 }
-                else if (!sameRecorderFileIdentity(generation, await readRecorderFileIdentity(await resolveRecorderPublicationPath(logicalPath)))) {
+                else if (!sameRecorderFileIdentity(generation.identity, await readRecorderFileIdentity(await resolveRecorderPublicationPath(logicalPath)))) {
                     throw new RecorderRotatedError("Recorder rotated before confirming a duplicate batch.");
                 }
                 return recorded;
@@ -519,6 +994,11 @@ async function syncRecordIdentityIndex(filePath) {
         if (index.readState.generation !== generation) {
             index.seen.clear();
             generation = index.readState.generation;
+            index.readState.caughtUp = false;
+            index.readState.continuity = Buffer.alloc(0);
+            index.readState.offset = 0;
+            index.readState.pending = Buffer.alloc(0);
+            continue;
         }
         for (const event of appended) {
             rememberRecentRecord(index.seen, event);