@cueai/omni-reader-mcp 1.0.2 → 1.1.0

package/dist/operation-journal.js

@@ -1,13 +1,55 @@
 import { createCipheriv, createDecipheriv, createHash, randomBytes, randomUUID, } from "node:crypto";
-import { chmod, link, mkdir, open, readFile, unlink, } from "node:fs/promises";
+import { chmod, link, mkdir, open, readFile, readdir, rename, rm, stat, unlink, } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
 import { OmniBridgeError } from "./errors.js";
+const JOURNAL_STATES = new Set([
+    "CREATED",
+    "GRANT_PENDING",
+    "GRANT_ISSUED",
+    "UPLOADING",
+    "PROCESSING",
+    "RESULT_READY",
+    "ACK_PENDING",
+    "CLEANUP_PENDING",
+    "COMPLETED",
+    "FAILED",
+    "CANCELED",
+    "EXPIRED",
+]);
+const TERMINAL_STATES = new Set([
+    "COMPLETED",
+    "FAILED",
+    "CANCELED",
+    "EXPIRED",
+]);
+const PROGRESS_UNITS = new Set([
+    "page",
+    "sheet",
+    "slide",
+    "frame",
+    "segment",
+]);
+const CLEANUP_STATES = new Set([
+    "not_created",
+    "in_use",
+    "pending",
+    "deleted",
+]);
+const DELIVERY_STATES = new Set([
+    "not_created",
+    "pending",
+    "deleted_after_ack",
+]);
+const RECORD_FILE_PATTERN = /^[0-9a-f]{64}(?:\.issued)?\.json$/u;
+const LOCK_STALE_MS = 30_000;
 function bridgeError(code, message, retryable) {
     return new OmniBridgeError({
         code,
         message,
+        operationCreated: false,
         fileUploaded: false,
+        parserStarted: false,
         billed: false,
         contentReleased: false,
         retryable,
@@ -28,40 +70,166 @@ function recordFileName(clientRequestId) {
 }
 function validateClientRequestId(clientRequestId) {
     if (!/^[A-Za-z0-9._:-]{1,128}$/u.test(clientRequestId)) {
-        throw bridgeError("INVALID_CLIENT_REQUEST_ID", "The local grant request identifier is invalid.", false);
+        throw bridgeError("INVALID_CLIENT_REQUEST_ID", "The local operation request identifier is invalid.", false);
     }
 }
+function isStringOrNull(value) {
+    return value === null || typeof value === "string";
+}
 function isEncryptedToken(value) {
-    if (value === null || typeof value !== "object") {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
         return false;
-    }
     const token = value;
     return (token.algorithm === "aes-256-gcm" &&
         typeof token.nonce === "string" &&
         typeof token.ciphertext === "string" &&
         typeof token.tag === "string");
 }
+function isProgress(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const progress = value;
+    return (typeof progress.unit === "string" &&
+        PROGRESS_UNITS.has(progress.unit) &&
+        Number.isSafeInteger(progress.completed) &&
+        Number.isSafeInteger(progress.total) &&
+        (progress.completed ?? -1) >= 0 &&
+        (progress.total ?? 0) > 0 &&
+        (progress.completed ?? 1) <= (progress.total ?? 0));
+}
+function parseLegacyRecord(value) {
+    if (value.version !== 1 ||
+        typeof value.clientRequestId !== "string" ||
+        typeof value.requestHash !== "string" ||
+        !isStringOrNull(value.operationId) ||
+        !(value.operationToken === null || isEncryptedToken(value.operationToken)) ||
+        !isStringOrNull(value.uploadUrl) ||
+        (value.state !== "GRANT_PENDING" && value.state !== "GRANT_ISSUED") ||
+        typeof value.createdAt !== "string" ||
+        !isStringOrNull(value.expiresAt)) {
+        throw new Error("legacy record fields are invalid");
+    }
+    return value;
+}
+function parseVersionTwoRecord(value) {
+    if (value.version !== 2 ||
+        typeof value.clientRequestId !== "string" ||
+        typeof value.requestHash !== "string" ||
+        !(value.sourceLocatorHash === undefined ||
+            isStringOrNull(value.sourceLocatorHash)) ||
+        !(value.sourceKind === undefined ||
+            value.sourceKind === "local" ||
+            value.sourceKind === "url") ||
+        !isStringOrNull(value.operationId) ||
+        !(value.operationToken === null || isEncryptedToken(value.operationToken)) ||
+        typeof value.state !== "string" ||
+        !JOURNAL_STATES.has(value.state) ||
+        typeof value.createdAt !== "string" ||
+        typeof value.updatedAt !== "string" ||
+        !isStringOrNull(value.expiresAt) ||
+        !isStringOrNull(value.stage) ||
+        !(value.progressPercent === undefined ||
+            (typeof value.progressPercent === "number" &&
+                Number.isFinite(value.progressPercent) &&
+                value.progressPercent >= 0 &&
+                value.progressPercent <= 100)) ||
+        !(value.progress === null || isProgress(value.progress)) ||
+        typeof value.fileUploaded !== "boolean" ||
+        typeof value.parserStarted !== "boolean" ||
+        typeof value.billed !== "boolean" ||
+        typeof value.contentReleased !== "boolean" ||
+        typeof value.processingCopy !== "string" ||
+        !CLEANUP_STATES.has(value.processingCopy) ||
+        typeof value.temporaryData !== "string" ||
+        !CLEANUP_STATES.has(value.temporaryData) ||
+        typeof value.deliveryResult !== "string" ||
+        !DELIVERY_STATES.has(value.deliveryResult) ||
+        !isStringOrNull(value.resultId) ||
+        !isStringOrNull(value.resultExpiresAt) ||
+        !isStringOrNull(value.errorCode)) {
+        throw new Error("version-2 record fields are invalid");
+    }
+    return {
+        ...value,
+        sourceLocatorHash: value.sourceLocatorHash ?? null,
+        sourceKind: value.sourceKind ?? "local",
+        progressPercent: value.progressPercent ?? 0,
+    };
+}
 function parsePersistedRecord(value) {
-    if (value === null || typeof value !== "object") {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
         throw new Error("record is not an object");
     }
     const record = value;
-    if (record.version !== 1 ||
-        typeof record.clientRequestId !== "string" ||
-        typeof record.requestHash !== "string" ||
-        (record.operationId !== null && typeof record.operationId !== "string") ||
-        (record.operationToken !== null && !isEncryptedToken(record.operationToken)) ||
-        (record.uploadUrl !== null && typeof record.uploadUrl !== "string") ||
-        (record.state !== "GRANT_PENDING" && record.state !== "GRANT_ISSUED") ||
-        typeof record.createdAt !== "string" ||
-        (record.expiresAt !== null && typeof record.expiresAt !== "string")) {
-        throw new Error("record fields are invalid");
-    }
-    return record;
+    return record.version === 1 ? parseLegacyRecord(record) : parseVersionTwoRecord(record);
+}
+function migrateRecord(record) {
+    if (record.version === 2)
+        return record;
+    return {
+        version: 2,
+        clientRequestId: record.clientRequestId,
+        requestHash: record.requestHash,
+        sourceLocatorHash: null,
+        sourceKind: "local",
+        operationId: record.operationId,
+        operationToken: record.operationToken,
+        state: record.state,
+        createdAt: record.createdAt,
+        updatedAt: record.createdAt,
+        expiresAt: record.expiresAt,
+        stage: null,
+        progressPercent: 0,
+        progress: null,
+        fileUploaded: false,
+        parserStarted: false,
+        billed: false,
+        contentReleased: false,
+        processingCopy: "not_created",
+        temporaryData: "not_created",
+        deliveryResult: "not_created",
+        resultId: null,
+        resultExpiresAt: null,
+        errorCode: null,
+    };
 }
 async function closeQuietly(handle) {
     await handle?.close().catch(() => undefined);
 }
+function sleep(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+function assertStableTransition(current, updated) {
+    for (const [before, after] of [
+        [current.operationId, updated.operationId],
+        [current.resultId, updated.resultId],
+    ]) {
+        if (before !== null && before !== after) {
+            throw bridgeError("JOURNAL_IDENTITY_CONFLICT", "A stable local operation identifier cannot be replaced.", false);
+        }
+    }
+    if (current.operationToken !== null &&
+        current.operationToken !== updated.operationToken &&
+        !(updated.operationToken === null && TERMINAL_STATES.has(updated.state))) {
+        throw bridgeError("JOURNAL_IDENTITY_CONFLICT", "A recoverable local operation token cannot be replaced.", false);
+    }
+    if (updated.progressPercent < current.progressPercent ||
+        (current.progress !== null && (updated.progress === null ||
+            updated.progress.unit !== current.progress.unit ||
+            updated.progress.completed < current.progress.completed))) {
+        throw bridgeError("JOURNAL_PROGRESS_REGRESSION", "Confirmed local operation progress cannot move backward.", false);
+    }
+    for (const [before, after] of [
+        [current.fileUploaded, updated.fileUploaded],
+        [current.parserStarted, updated.parserStarted],
+        [current.billed, updated.billed],
+        [current.contentReleased, updated.contentReleased],
+    ]) {
+        if (before && !after) {
+            throw bridgeError("JOURNAL_FACT_REGRESSION", "A confirmed local operation fact cannot be reverted.", false);
+        }
+    }
+}
 export class OperationJournal {
     #rootDirectory;
     #now;
@@ -70,105 +238,262 @@ export class OperationJournal {
         this.#rootDirectory = options.rootDirectory ?? defaultRootDirectory();
         this.#now = options.now ?? (() => new Date());
     }
-    async begin(clientRequestId, requestHash) {
+    async beginIntent(clientRequestId, requestHash, sourceKind = "local", sourceLocatorHash = null) {
         validateClientRequestId(clientRequestId);
         const existing = await this.#readRecord(clientRequestId);
         if (existing !== null) {
             return this.#requireMatchingRequest(clientRequestId, requestHash, existing);
         }
-        const pending = {
-            version: 1,
+        const createdAt = this.#now().toISOString();
+        const created = {
+            version: 2,
             clientRequestId,
             requestHash,
+            sourceLocatorHash,
+            sourceKind,
             operationId: null,
             operationToken: null,
-            uploadUrl: null,
-            state: "GRANT_PENDING",
-            createdAt: this.#now().toISOString(),
+            state: "CREATED",
+            createdAt,
+            updatedAt: createdAt,
             expiresAt: null,
+            stage: null,
+            progressPercent: 0,
+            progress: null,
+            fileUploaded: false,
+            parserStarted: false,
+            billed: false,
+            contentReleased: false,
+            processingCopy: "not_created",
+            temporaryData: "not_created",
+            deliveryResult: "not_created",
+            resultId: null,
+            resultExpiresAt: null,
+            errorCode: null,
         };
-        if (await this.#createRecord(pending, this.#pendingRecordPath(clientRequestId))) {
-            return this.#publicRecord(pending, null);
+        if (await this.#createRecord(created, this.#recordPath(clientRequestId))) {
+            return this.#recordToPublic(clientRequestId, created);
         }
         const raced = await this.#readRecord(clientRequestId);
         if (raced === null) {
-            throw bridgeError("JOURNAL_WRITE_FAILED", "The local grant journal could not be saved.", true);
+            throw bridgeError("JOURNAL_WRITE_FAILED", "The local operation journal could not be saved.", true);
         }
         return this.#requireMatchingRequest(clientRequestId, requestHash, raced);
     }
-    async markGrantIssued(clientRequestId, fields) {
+    async transition(clientRequestId, expectedState, nextState, patch) {
+        validateClientRequestId(clientRequestId);
+        if (!JOURNAL_STATES.has(expectedState) || !JOURNAL_STATES.has(nextState)) {
+            throw bridgeError("INVALID_JOURNAL_STATE", "The local operation state is invalid.", false);
+        }
+        return this.#withRecordLock(clientRequestId, async () => {
+            const stored = await this.#readRecord(clientRequestId);
+            if (stored === null) {
+                throw bridgeError("JOURNAL_RECORD_NOT_FOUND", "The local operation journal record is missing.", true);
+            }
+            const current = await this.#recordToPublic(clientRequestId, stored);
+            if (current.state !== expectedState) {
+                throw bridgeError("JOURNAL_STATE_CONFLICT", "The local operation changed before this transition was saved.", true);
+            }
+            const updated = {
+                ...current,
+                ...patch,
+                ...(TERMINAL_STATES.has(nextState) ? { operationToken: null } : {}),
+                uploadUrl: null,
+                state: nextState,
+                updatedAt: this.#now().toISOString(),
+            };
+            assertStableTransition(current, updated);
+            await this.#replaceRecord(await this.#persistedRecord(updated), this.#recordPath(clientRequestId));
+            await unlink(this.#legacyIssuedRecordPath(clientRequestId)).catch(() => undefined);
+            return updated;
+        });
+    }
+    async loadByRequestId(clientRequestId) {
+        validateClientRequestId(clientRequestId);
         const persisted = await this.#readRecord(clientRequestId);
-        if (persisted === null) {
-            throw bridgeError("JOURNAL_RECORD_NOT_FOUND", "The local grant journal record is missing.", true);
+        return persisted === null ? null : this.#recordToPublic(clientRequestId, persisted);
+    }
+    async loadByOperationId(operationId) {
+        if (operationId.length === 0)
+            return null;
+        return (await this.#listRecords()).find((record) => record.operationId === operationId) ?? null;
+    }
+    async loadLatestByRequestHash(requestHash) {
+        return (await this.#listRecords())
+            .filter((record) => record.requestHash === requestHash)
+            .at(-1) ?? null;
+    }
+    async loadLatestBySourceLocatorHash(sourceLocatorHash) {
+        return (await this.#listRecords())
+            .filter((record) => record.sourceLocatorHash === sourceLocatorHash)
+            .at(-1) ?? null;
+    }
+    async listRecoverable() {
+        return (await this.#listRecords()).filter((record) => !TERMINAL_STATES.has(record.state));
+    }
+    async begin(clientRequestId, requestHash) {
+        const intent = await this.beginIntent(clientRequestId, requestHash);
+        if (intent.state !== "CREATED")
+            return intent;
+        try {
+            return await this.transition(clientRequestId, "CREATED", "GRANT_PENDING", {});
         }
-        if (persisted.state === "GRANT_ISSUED") {
-            return this.#requireMatchingGrant(clientRequestId, persisted, fields);
+        catch (error) {
+            if (!(error instanceof OmniBridgeError) || error.code !== "JOURNAL_STATE_CONFLICT")
+                throw error;
+            const raced = await this.loadByRequestId(clientRequestId);
+            if (raced === null || raced.requestHash !== requestHash)
+                throw error;
+            return raced;
         }
-        const operationToken = await this.#encryptToken(clientRequestId, fields.operationToken);
-        const issued = {
-            ...persisted,
-            operationId: fields.operationId,
-            operationToken,
-            uploadUrl: fields.uploadUrl,
-            state: "GRANT_ISSUED",
-            expiresAt: fields.expiresAt,
-        };
-        if (await this.#createRecord(issued, this.#issuedRecordPath(clientRequestId))) {
-            return this.#publicRecord(issued, fields.operationToken);
+    }
+    async markGrantIssued(clientRequestId, fields) {
+        const current = await this.loadByRequestId(clientRequestId);
+        if (current === null) {
+            throw bridgeError("JOURNAL_RECORD_NOT_FOUND", "The local operation journal record is missing.", true);
         }
-        const raced = await this.#readRecord(clientRequestId);
-        if (raced === null || raced.state !== "GRANT_ISSUED") {
-            throw bridgeError("JOURNAL_WRITE_FAILED", "The local grant journal could not be saved.", true);
+        if (current.state !== "GRANT_PENDING")
+            return this.#requireMatchingGrant(current, fields);
+        try {
+            return await this.transition(clientRequestId, "GRANT_PENDING", "GRANT_ISSUED", {
+                operationId: fields.operationId,
+                operationToken: fields.operationToken,
+                expiresAt: fields.expiresAt,
+            });
+        }
+        catch (error) {
+            if (!(error instanceof OmniBridgeError) || error.code !== "JOURNAL_STATE_CONFLICT")
+                throw error;
+            const raced = await this.loadByRequestId(clientRequestId);
+            if (raced === null)
+                throw error;
+            return this.#requireMatchingGrant(raced, fields);
         }
-        return this.#requireMatchingGrant(clientRequestId, raced, fields);
     }
-    async load(clientRequestId) {
-        const persisted = await this.#readRecord(clientRequestId);
-        if (persisted === null) {
-            return null;
+    load(clientRequestId) {
+        return this.loadByRequestId(clientRequestId);
+    }
+    async #listRecords() {
+        let names;
+        try {
+            names = await readdir(this.#rootDirectory);
         }
-        return this.#recordToPublic(clientRequestId, persisted);
+        catch (error) {
+            if (error.code === "ENOENT")
+                return [];
+            throw bridgeError("JOURNAL_READ_FAILED", "The local operation journal could not be read.", true);
+        }
+        const requestIds = new Set();
+        for (const name of names.filter((entry) => RECORD_FILE_PATTERN.test(entry))) {
+            const stored = await this.#readRecordFile(undefined, path.join(this.#rootDirectory, name));
+            if (stored !== null)
+                requestIds.add(stored.clientRequestId);
+        }
+        const records = [];
+        for (const requestId of requestIds) {
+            const record = await this.loadByRequestId(requestId);
+            if (record !== null)
+                records.push(record);
+        }
+        return records.sort((left, right) => left.createdAt.localeCompare(right.createdAt) ||
+            left.clientRequestId.localeCompare(right.clientRequestId));
     }
-    async #recordToPublic(clientRequestId, persisted) {
+    async #persistedRecord(record) {
+        return {
+            version: 2,
+            clientRequestId: record.clientRequestId,
+            requestHash: record.requestHash,
+            sourceLocatorHash: record.sourceLocatorHash,
+            sourceKind: record.sourceKind,
+            operationId: record.operationId,
+            operationToken: record.operationToken === null
+                ? null
+                : await this.#encryptToken(record.clientRequestId, record.operationToken),
+            state: record.state,
+            createdAt: record.createdAt,
+            updatedAt: record.updatedAt,
+            expiresAt: record.expiresAt,
+            stage: record.stage,
+            progressPercent: record.progressPercent,
+            progress: record.progress,
+            fileUploaded: record.fileUploaded,
+            parserStarted: record.parserStarted,
+            billed: record.billed,
+            contentReleased: record.contentReleased,
+            processingCopy: record.processingCopy,
+            temporaryData: record.temporaryData,
+            deliveryResult: record.deliveryResult,
+            resultId: record.resultId,
+            resultExpiresAt: record.resultExpiresAt,
+            errorCode: record.errorCode,
+        };
+    }
+    async #recordToPublic(clientRequestId, stored) {
+        const persisted = migrateRecord(stored);
         const operationToken = persisted.operationToken === null
             ? null
             : await this.#decryptToken(clientRequestId, persisted.operationToken);
-        return this.#publicRecord(persisted, operationToken);
+        return {
+            clientRequestId: persisted.clientRequestId,
+            requestHash: persisted.requestHash,
+            sourceLocatorHash: persisted.sourceLocatorHash,
+            sourceKind: persisted.sourceKind,
+            operationId: persisted.operationId,
+            operationToken,
+            uploadUrl: stored.version === 1 ? stored.uploadUrl : null,
+            state: persisted.state,
+            createdAt: persisted.createdAt,
+            updatedAt: persisted.updatedAt,
+            expiresAt: persisted.expiresAt,
+            stage: persisted.stage,
+            progressPercent: persisted.progressPercent,
+            progress: persisted.progress,
+            fileUploaded: persisted.fileUploaded,
+            parserStarted: persisted.parserStarted,
+            billed: persisted.billed,
+            contentReleased: persisted.contentReleased,
+            processingCopy: persisted.processingCopy,
+            temporaryData: persisted.temporaryData,
+            deliveryResult: persisted.deliveryResult,
+            resultId: persisted.resultId,
+            resultExpiresAt: persisted.resultExpiresAt,
+            errorCode: persisted.errorCode,
+        };
     }
     async #requireMatchingRequest(clientRequestId, requestHash, persisted) {
         if (persisted.requestHash !== requestHash) {
-            throw bridgeError("IDEMPOTENCY_COLLISION", "This local grant request identifier is already bound to different metadata.", false);
+            throw bridgeError("IDEMPOTENCY_COLLISION", "This local operation request identifier is already bound to different metadata.", false);
         }
         return this.#recordToPublic(clientRequestId, persisted);
     }
-    async #requireMatchingGrant(clientRequestId, persisted, fields) {
-        const existing = await this.#recordToPublic(clientRequestId, persisted);
-        if (existing.operationId !== fields.operationId ||
-            existing.operationToken !== fields.operationToken ||
-            existing.uploadUrl !== fields.uploadUrl ||
-            existing.expiresAt !== fields.expiresAt) {
+    #requireMatchingGrant(current, fields) {
+        if (current.operationId !== fields.operationId ||
+            current.operationToken !== fields.operationToken ||
+            current.expiresAt !== fields.expiresAt) {
             throw bridgeError("JOURNAL_GRANT_CONFLICT", "Cube returned conflicting data for the same grant request.", false);
         }
-        return existing;
+        return current;
     }
     async #ensureRoot() {
         await mkdir(this.#rootDirectory, { recursive: true, mode: 0o700 });
-        if (process.platform !== "win32") {
+        if (process.platform !== "win32")
             await chmod(this.#rootDirectory, 0o700);
-        }
     }
-    #pendingRecordPath(clientRequestId) {
+    #recordPath(clientRequestId) {
         return path.join(this.#rootDirectory, recordFileName(clientRequestId));
     }
-    #issuedRecordPath(clientRequestId) {
-        return this.#pendingRecordPath(clientRequestId).replace(/\.json$/u, ".issued.json");
+    #legacyIssuedRecordPath(clientRequestId) {
+        return this.#recordPath(clientRequestId).replace(/\.json$/u, ".issued.json");
+    }
+    #lockPath(clientRequestId) {
+        return this.#recordPath(clientRequestId).replace(/\.json$/u, ".lock");
     }
     async #readRecord(clientRequestId) {
-        const issued = await this.#readRecordFile(clientRequestId, this.#issuedRecordPath(clientRequestId));
-        if (issued !== null) {
-            return issued;
-        }
-        return this.#readRecordFile(clientRequestId, this.#pendingRecordPath(clientRequestId));
+        const current = await this.#readRecordFile(clientRequestId, this.#recordPath(clientRequestId));
+        if (current?.version === 2)
+            return current;
+        const legacyIssued = await this.#readRecordFile(clientRequestId, this.#legacyIssuedRecordPath(clientRequestId));
+        return legacyIssued ?? current;
     }
     async #readRecordFile(clientRequestId, recordPath) {
         let serialized;
@@ -176,20 +501,20 @@ export class OperationJournal {
             serialized = await readFile(recordPath, "utf8");
         }
         catch (error) {
-            if (error.code === "ENOENT") {
+            if (error.code === "ENOENT")
                 return null;
-            }
-            throw bridgeError("JOURNAL_READ_FAILED", "The local grant journal could not be read.", true);
+            throw bridgeError("JOURNAL_READ_FAILED", "The local operation journal could not be read.", true);
         }
         try {
             const persisted = parsePersistedRecord(JSON.parse(serialized));
-            if (persisted.clientRequestId !== clientRequestId) {
+            if (clientRequestId !== undefined && persisted.clientRequestId !== clientRequestId) {
                 throw new Error("record identity mismatch");
             }
+            validateClientRequestId(persisted.clientRequestId);
             return persisted;
         }
         catch {
-            throw bridgeError("JOURNAL_CORRUPT", "The local grant journal is invalid.", false);
+            throw bridgeError("JOURNAL_CORRUPT", "The local operation journal is invalid.", false);
         }
     }
     async #createRecord(record, recordPath) {
@@ -203,42 +528,96 @@ export class OperationJournal {
             await handle.close();
             handle = undefined;
             await link(temporaryPath, recordPath);
-            if (process.platform !== "win32") {
+            if (process.platform !== "win32")
                 await chmod(recordPath, 0o600);
-            }
             await this.#syncDirectory();
             return true;
         }
         catch (error) {
             await closeQuietly(handle);
-            if (error.code === "EEXIST") {
+            if (error.code === "EEXIST")
                 return false;
-            }
-            throw bridgeError("JOURNAL_WRITE_FAILED", "The local grant journal could not be saved.", true);
+            throw bridgeError("JOURNAL_WRITE_FAILED", "The local operation journal could not be saved.", true);
+        }
+        finally {
+            await unlink(temporaryPath).catch(() => undefined);
+        }
+    }
+    async #replaceRecord(record, recordPath) {
+        await this.#ensureRoot();
+        const temporaryPath = path.join(this.#rootDirectory, `.${path.basename(recordPath)}.${randomUUID()}.tmp`);
+        let handle;
+        try {
+            handle = await open(temporaryPath, "wx", 0o600);
+            await handle.writeFile(`${JSON.stringify(record)}\n`, "utf8");
+            await handle.sync();
+            await handle.close();
+            handle = undefined;
+            await rename(temporaryPath, recordPath);
+            if (process.platform !== "win32")
+                await chmod(recordPath, 0o600);
+            await this.#syncDirectory();
+        }
+        catch {
+            await closeQuietly(handle);
+            throw bridgeError("JOURNAL_WRITE_FAILED", "The local operation journal could not be saved.", true);
         }
         finally {
             await unlink(temporaryPath).catch(() => undefined);
         }
     }
+    async #withRecordLock(clientRequestId, action) {
+        await this.#ensureRoot();
+        const lockPath = this.#lockPath(clientRequestId);
+        for (let attempt = 0; attempt < 500; attempt += 1) {
+            try {
+                await mkdir(lockPath, { mode: 0o700 });
+                try {
+                    return await action();
+                }
+                finally {
+                    await rm(lockPath, { recursive: true, force: true });
+                }
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                if (await this.#removeStaleLock(lockPath))
+                    continue;
+                await sleep(10);
+            }
+        }
+        throw bridgeError("JOURNAL_LOCK_TIMEOUT", "The local operation journal remained busy.", true);
+    }
+    async #removeStaleLock(lockPath) {
+        try {
+            const lock = await stat(lockPath);
+            if (Date.now() - lock.mtimeMs <= LOCK_STALE_MS)
+                return false;
+            await rm(lockPath, { recursive: true, force: true });
+            return true;
+        }
+        catch (error) {
+            return error.code === "ENOENT";
+        }
+    }
     async #journalKey() {
         this.#keyPromise ??= this.#loadOrCreateKey();
         return this.#keyPromise;
     }
     async #existingJournalKey() {
-        if (this.#keyPromise !== undefined) {
+        if (this.#keyPromise !== undefined)
             return this.#keyPromise;
-        }
         const keyPath = path.join(this.#rootDirectory, "journal.key");
         try {
             const existing = await readFile(keyPath);
-            if (existing.length !== 32) {
+            if (existing.length !== 32)
                 throw new Error("invalid key length");
-            }
             this.#keyPromise = Promise.resolve(existing);
             return existing;
         }
         catch {
-            throw bridgeError("JOURNAL_KEY_INVALID", "The local grant journal key is missing or invalid.", false);
+            throw bridgeError("JOURNAL_KEY_INVALID", "The local operation journal key is missing or invalid.", false);
         }
     }
     async #loadOrCreateKey() {
@@ -246,14 +625,13 @@ export class OperationJournal {
         const keyPath = path.join(this.#rootDirectory, "journal.key");
         try {
             const existing = await readFile(keyPath);
-            if (existing.length !== 32) {
+            if (existing.length !== 32)
                 throw new Error("invalid key length");
-            }
             return existing;
         }
         catch (error) {
             if (error.code !== "ENOENT") {
-                throw bridgeError("JOURNAL_KEY_INVALID", "The local grant journal key is invalid.", false);
+                throw bridgeError("JOURNAL_KEY_INVALID", "The local operation journal key is invalid.", false);
             }
         }
         const key = randomBytes(32);
@@ -266,9 +644,8 @@ export class OperationJournal {
             await handle.close();
             handle = undefined;
             await link(temporaryPath, keyPath);
-            if (process.platform !== "win32") {
+            if (process.platform !== "win32")
                 await chmod(keyPath, 0o600);
-            }
             await this.#syncDirectory();
             return key;
         }
@@ -276,11 +653,10 @@ export class OperationJournal {
             await closeQuietly(handle);
             if (error.code === "EEXIST") {
                 const existing = await readFile(keyPath);
-                if (existing.length === 32) {
+                if (existing.length === 32)
                     return existing;
-                }
             }
-            throw bridgeError("JOURNAL_KEY_WRITE_FAILED", "The local grant journal key could not be saved.", true);
+            throw bridgeError("JOURNAL_KEY_WRITE_FAILED", "The local operation journal key could not be saved.", true);
         }
         finally {
             await unlink(temporaryPath).catch(() => undefined);
@@ -291,10 +667,7 @@ export class OperationJournal {
         const nonce = randomBytes(12);
         const cipher = createCipheriv("aes-256-gcm", key, nonce);
         cipher.setAAD(Buffer.from(clientRequestId, "utf8"));
-        const ciphertext = Buffer.concat([
-            cipher.update(operationToken, "utf8"),
-            cipher.final(),
-        ]);
+        const ciphertext = Buffer.concat([cipher.update(operationToken, "utf8"), cipher.final()]);
         return {
             algorithm: "aes-256-gcm",
             nonce: nonce.toString("base64url"),
@@ -314,28 +687,14 @@ export class OperationJournal {
             ]).toString("utf8");
         }
         catch (error) {
-            if (error instanceof OmniBridgeError) {
+            if (error instanceof OmniBridgeError)
                 throw error;
-            }
             throw bridgeError("JOURNAL_TOKEN_DECRYPT_FAILED", "The local operation token could not be recovered.", false);
         }
     }
-    #publicRecord(persisted, operationToken) {
-        return {
-            clientRequestId: persisted.clientRequestId,
-            requestHash: persisted.requestHash,
-            operationId: persisted.operationId,
-            operationToken,
-            uploadUrl: persisted.uploadUrl,
-            state: persisted.state,
-            createdAt: persisted.createdAt,
-            expiresAt: persisted.expiresAt,
-        };
-    }
     async #syncDirectory() {
-        if (process.platform === "win32") {
+        if (process.platform === "win32")
             return;
-        }
         let directory;
         try {
             directory = await open(this.#rootDirectory, "r");