@cueai/omni-reader-mcp 1.1.2 → 1.2.0

package/dist/operation-journal.js

@@ -1,8 +1,48 @@
-import { createCipheriv, createDecipheriv, createHash, randomBytes, randomUUID, } from "node:crypto";
+import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes, randomUUID, timingSafeEqual, } from "node:crypto";
 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";
+import { GROUNDING_SCHEMA_VERSION, RESULT_BUNDLE_PROTOCOL_VERSION, normalizeRepresentation, } from "./protocol.js";
+// D2-D item 4-6: v3 records persist keyed identities instead of unkeyed
+// request/source hashes. requestIdentityHmac and sourceLocatorHmac are
+// lowercase full hex of HMAC-SHA-256 over the journal secret with the exact
+// domain prefixes below; they are never returned in tool output and never
+// stored in any legacy unkeyed form. Legacy v1/v2 records are migrated in
+// memory only (see migrateLegacyRecord) and only normalize to text/none/none.
+const REQUEST_IDENTITY_DOMAIN = "omni-request-identity-v1";
+const SOURCE_LOCATOR_DOMAIN = "omni-source-locator-v1";
+// D2-D item 4: the persisted v3 key set is exact. Records with extra fields
+// (for example legacy unkeyed requestHash) or missing fields are rejected.
+const PERSISTED_V3_KEYS = [
+    "version",
+    "clientRequestId",
+    "requestIdentityHmac",
+    "sourceLocatorHmac",
+    "sourceKind",
+    "detail",
+    "groundingSchemaVersion",
+    "bundleProtocolVersion",
+    "operationId",
+    "operationToken",
+    "state",
+    "createdAt",
+    "updatedAt",
+    "expiresAt",
+    "stage",
+    "progressPercent",
+    "progress",
+    "fileUploaded",
+    "parserStarted",
+    "billed",
+    "contentReleased",
+    "processingCopy",
+    "temporaryData",
+    "deliveryResult",
+    "resultId",
+    "resultExpiresAt",
+    "errorCode",
+];
 const JOURNAL_STATES = new Set([
     "CREATED",
     "GRANT_PENDING",
@@ -43,6 +83,11 @@ const DELIVERY_STATES = new Set([
 ]);
 const RECORD_FILE_PATTERN = /^[0-9a-f]{64}(?:\.issued)?\.json$/u;
 const LOCK_STALE_MS = 30_000;
+const HEX_64_PATTERN = /^[0-9a-f]{64}$/u;
+const TEXT_REPRESENTATION = normalizeRepresentation();
+// Terminal source-free recovery failure for legacy records whose request
+// identity cannot be reconstructed from safe canonical source facts.
+export const LEGACY_RECOVERY_FAILURE_CODE = "SOURCE_FACTS_NOT_RECOVERABLE";
 function bridgeError(code, message, retryable) {
     return new OmniBridgeError({
         code,
@@ -162,28 +207,157 @@ function parseVersionTwoRecord(value) {
         progressPercent: value.progressPercent ?? 0,
     };
 }
+function parseVersionThreeRecord(value) {
+    const keys = Object.keys(value);
+    if (keys.length !== PERSISTED_V3_KEYS.length ||
+        PERSISTED_V3_KEYS.some((key) => !(key in value))) {
+        throw new Error("version-3 record fields are invalid");
+    }
+    if (value.version !== 3 ||
+        typeof value.clientRequestId !== "string" ||
+        typeof value.requestIdentityHmac !== "string" ||
+        !HEX_64_PATTERN.test(value.requestIdentityHmac) ||
+        !(value.sourceLocatorHmac === null ||
+            (typeof value.sourceLocatorHmac === "string" && HEX_64_PATTERN.test(value.sourceLocatorHmac))) ||
+        (value.sourceKind !== "local" && value.sourceKind !== "url") ||
+        (value.detail !== "text" && value.detail !== "grounded" && value.detail !== "layout") ||
+        (value.groundingSchemaVersion !== "none" &&
+            value.groundingSchemaVersion !== GROUNDING_SCHEMA_VERSION) ||
+        (value.bundleProtocolVersion !== "none" &&
+            value.bundleProtocolVersion !== RESULT_BUNDLE_PROTOCOL_VERSION) ||
+        !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) ||
+        !(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-3 record fields are invalid");
+    }
+    return value;
+}
 function parsePersistedRecord(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
         throw new Error("record is not an object");
     }
     const record = value;
-    return record.version === 1 ? parseLegacyRecord(record) : parseVersionTwoRecord(record);
-}
-function migrateRecord(record) {
+    if (record.version === 1)
+        return parseLegacyRecord(record);
     if (record.version === 2)
-        return record;
+        return parseVersionTwoRecord(record);
+    if (record.version === 3)
+        return parseVersionThreeRecord(record);
+    throw new Error("record version is invalid");
+}
+function migrateInMemory(stored) {
+    if (stored.version === 3) {
+        return {
+            version: 3,
+            clientRequestId: stored.clientRequestId,
+            requestIdentityHmac: stored.requestIdentityHmac,
+            sourceLocatorHmac: stored.sourceLocatorHmac,
+            requestHash: null,
+            sourceLocatorHash: null,
+            uploadUrl: null,
+            sourceKind: stored.sourceKind,
+            detail: stored.detail,
+            groundingSchemaVersion: stored.groundingSchemaVersion,
+            bundleProtocolVersion: stored.bundleProtocolVersion,
+            operationId: stored.operationId,
+            operationToken: stored.operationToken,
+            state: stored.state,
+            createdAt: stored.createdAt,
+            updatedAt: stored.updatedAt,
+            expiresAt: stored.expiresAt,
+            stage: stored.stage,
+            progressPercent: stored.progressPercent,
+            progress: stored.progress,
+            fileUploaded: stored.fileUploaded,
+            parserStarted: stored.parserStarted,
+            billed: stored.billed,
+            contentReleased: stored.contentReleased,
+            processingCopy: stored.processingCopy,
+            temporaryData: stored.temporaryData,
+            deliveryResult: stored.deliveryResult,
+            resultId: stored.resultId,
+            resultExpiresAt: stored.resultExpiresAt,
+            errorCode: stored.errorCode,
+        };
+    }
+    if (stored.version === 2) {
+        // Legacy v2 text records normalize only to text/none/none; keyed handles
+        // are recomputed only when safe canonical source facts reconstruct the
+        // stored unkeyed requestHash (see #reconstructLegacy).
+        return {
+            version: 3,
+            clientRequestId: stored.clientRequestId,
+            requestIdentityHmac: null,
+            sourceLocatorHmac: null,
+            requestHash: stored.requestHash,
+            sourceLocatorHash: stored.sourceLocatorHash,
+            uploadUrl: null,
+            sourceKind: stored.sourceKind,
+            detail: "text",
+            groundingSchemaVersion: "none",
+            bundleProtocolVersion: "none",
+            operationId: stored.operationId,
+            operationToken: stored.operationToken,
+            state: stored.state,
+            createdAt: stored.createdAt,
+            updatedAt: stored.updatedAt,
+            expiresAt: stored.expiresAt,
+            stage: stored.stage,
+            progressPercent: stored.progressPercent,
+            progress: stored.progress,
+            fileUploaded: stored.fileUploaded,
+            parserStarted: stored.parserStarted,
+            billed: stored.billed,
+            contentReleased: stored.contentReleased,
+            processingCopy: stored.processingCopy,
+            temporaryData: stored.temporaryData,
+            deliveryResult: stored.deliveryResult,
+            resultId: stored.resultId,
+            resultExpiresAt: stored.resultExpiresAt,
+            errorCode: stored.errorCode,
+        };
+    }
     return {
-        version: 2,
-        clientRequestId: record.clientRequestId,
-        requestHash: record.requestHash,
+        version: 3,
+        clientRequestId: stored.clientRequestId,
+        requestIdentityHmac: null,
+        sourceLocatorHmac: null,
+        requestHash: stored.requestHash,
         sourceLocatorHash: null,
+        uploadUrl: stored.uploadUrl,
         sourceKind: "local",
-        operationId: record.operationId,
-        operationToken: record.operationToken,
-        state: record.state,
-        createdAt: record.createdAt,
-        updatedAt: record.createdAt,
-        expiresAt: record.expiresAt,
+        detail: "text",
+        groundingSchemaVersion: "none",
+        bundleProtocolVersion: "none",
+        operationId: stored.operationId,
+        operationToken: stored.operationToken,
+        state: stored.state,
+        createdAt: stored.createdAt,
+        updatedAt: stored.createdAt,
+        expiresAt: stored.expiresAt,
         stage: null,
         progressPercent: 0,
         progress: null,
@@ -255,6 +429,11 @@ function assertStableTransition(current, updated) {
         }
     }
 }
+function hmacEqual(left, right) {
+    if (left.length !== right.length)
+        return false;
+    return timingSafeEqual(Buffer.from(left, "hex"), Buffer.from(right, "hex"));
+}
 export class OperationJournal {
     #rootDirectory;
     #now;
@@ -263,19 +442,40 @@ export class OperationJournal {
         this.#rootDirectory = options.rootDirectory ?? defaultRootDirectory();
         this.#now = options.now ?? (() => new Date());
     }
-    async beginIntent(clientRequestId, requestHash, sourceKind = "local", sourceLocatorHash = null) {
+    // Public keyed-identity derivation. HMAC-SHA-256 over the journal secret
+    // with the exact domain prefix; lowercase full hex. The value is a keyed
+    // handle and is never returned in tool output or stored unkeyed.
+    async requestIdentityHmac(canonicalIdentityJson) {
+        return this.#hmac(REQUEST_IDENTITY_DOMAIN, canonicalIdentityJson);
+    }
+    async sourceLocatorHmac(sourceLocator) {
+        return this.#hmac(SOURCE_LOCATOR_DOMAIN, sourceLocator);
+    }
+    // v3 intent creation. canonicalIdentityJson is the exact canonical
+    // serialization of {source_kind, source_facts} (which includes the
+    // normalized representation tuple); the journal derives the keyed identity
+    // from it and persists only the HMAC, never the payload or any unkeyed hash.
+    async beginIntent(clientRequestId, canonicalIdentityJson, sourceKind = "local", sourceLocator = null, representation = TEXT_REPRESENTATION) {
         validateClientRequestId(clientRequestId);
         const existing = await this.#readRecord(clientRequestId);
         if (existing !== null) {
-            return this.#requireMatchingRequest(clientRequestId, requestHash, existing);
+            return this.#requireMatchingRequest(clientRequestId, canonicalIdentityJson, sourceLocator, existing);
         }
         const createdAt = this.#now().toISOString();
         const created = {
-            version: 2,
+            version: 3,
             clientRequestId,
-            requestHash,
-            sourceLocatorHash,
+            requestIdentityHmac: await this.#hmac(REQUEST_IDENTITY_DOMAIN, canonicalIdentityJson),
+            sourceLocatorHmac: sourceLocator === null
+                ? null
+                : await this.#hmac(SOURCE_LOCATOR_DOMAIN, sourceLocator),
+            requestHash: null,
+            sourceLocatorHash: null,
+            uploadUrl: null,
             sourceKind,
+            detail: representation.detail,
+            groundingSchemaVersion: representation.groundingSchemaVersion,
+            bundleProtocolVersion: representation.bundleProtocolVersion,
             operationId: null,
             operationToken: null,
             state: "CREATED",
@@ -297,13 +497,39 @@ export class OperationJournal {
             errorCode: null,
         };
         if (await this.#createRecord(created, this.#recordPath(clientRequestId))) {
-            return this.#recordToPublic(clientRequestId, created);
+            return this.#recordFromInMemory(clientRequestId, created);
         }
         const raced = await this.#readRecord(clientRequestId);
         if (raced === null) {
             throw bridgeError("JOURNAL_WRITE_FAILED", "The local operation journal could not be saved.", true);
         }
-        return this.#requireMatchingRequest(clientRequestId, requestHash, raced);
+        return this.#requireMatchingRequest(clientRequestId, canonicalIdentityJson, sourceLocator, raced);
+    }
+    // Migrate a legacy v1/v2 record using the caller's safe canonical source
+    // facts. When the facts reconstruct the stored unkeyed requestHash, the
+    // record migrates to v3 (durably) with domain-separated HMACs and keeps its
+    // state; otherwise it becomes a terminal source-free recovery failure and
+    // never copies the unkeyed hashes. Returns null when no record exists.
+    async migrateLegacyRecord(clientRequestId, canonicalIdentityJson, sourceLocator = null) {
+        validateClientRequestId(clientRequestId);
+        const stored = await this.#readRecord(clientRequestId);
+        if (stored === null)
+            return null;
+        if (stored.version === 3)
+            return this.#recordToPublic(clientRequestId, stored);
+        const expected = `sha256:${createHash("sha256").update(canonicalIdentityJson, "utf8").digest("hex")}`;
+        if (stored.requestHash === expected) {
+            const migrated = await this.#reconstructLegacy(stored, canonicalIdentityJson, sourceLocator);
+            await this.#replaceRecord(await this.#persistedFromInMemory(migrated), this.#recordPath(clientRequestId));
+            return this.#recordFromInMemory(clientRequestId, migrated);
+        }
+        const failed = migrateInMemory(stored);
+        failed.state = "FAILED";
+        failed.errorCode = LEGACY_RECOVERY_FAILURE_CODE;
+        failed.operationToken = null;
+        failed.stage = "failed";
+        failed.uploadUrl = null;
+        return this.#recordFromInMemory(clientRequestId, failed);
     }
     async transition(clientRequestId, expectedState, nextState, patch) {
         validateClientRequestId(clientRequestId);
@@ -343,34 +569,81 @@ export class OperationJournal {
             return null;
         return (await this.#listRecords()).find((record) => record.operationId === operationId) ?? null;
     }
-    async loadLatestByRequestHash(requestHash) {
+    async loadLatestByRequestIdentityHmac(requestIdentityHmac) {
         return (await this.#listRecords())
-            .filter((record) => record.requestHash === requestHash)
+            .filter((record) => record.requestIdentityHmac === requestIdentityHmac)
             .at(-1) ?? null;
     }
-    async loadLatestBySourceLocatorHash(sourceLocatorHash) {
+    async loadLatestBySourceLocatorHmac(sourceLocatorHmac) {
         return (await this.#listRecords())
-            .filter((record) => record.sourceLocatorHash === sourceLocatorHash)
+            .filter((record) => record.sourceLocatorHmac === sourceLocatorHmac)
             .at(-1) ?? null;
     }
     async listRecoverable() {
-        return (await this.#listRecords()).filter((record) => !TERMINAL_STATES.has(record.state));
+        return (await this.#listRecords()).filter((record) => !TERMINAL_STATES.has(record.state) && record.requestIdentityHmac !== null);
     }
     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", {});
+        validateClientRequestId(clientRequestId);
+        const existing = await this.#readRecord(clientRequestId);
+        if (existing !== null) {
+            return this.#requireMatchingCubeRequest(clientRequestId, requestHash, existing);
         }
-        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;
+        // Legacy Cube path: the grant request hash is the safe canonical identity
+        // the journal receives, so the keyed handle is derived over that value.
+        const createdAt = this.#now().toISOString();
+        const created = {
+            version: 3,
+            clientRequestId,
+            requestIdentityHmac: await this.#hmac(REQUEST_IDENTITY_DOMAIN, requestHash),
+            sourceLocatorHmac: null,
+            requestHash: null,
+            sourceLocatorHash: null,
+            uploadUrl: null,
+            sourceKind: "local",
+            detail: "text",
+            groundingSchemaVersion: "none",
+            bundleProtocolVersion: "none",
+            operationId: null,
+            operationToken: null,
+            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(created, this.#recordPath(clientRequestId))) {
+            const intent = await this.#recordFromInMemory(clientRequestId, created);
+            if (intent.state !== "CREATED")
+                return intent;
+            try {
+                return await this.transition(clientRequestId, "CREATED", "GRANT_PENDING", {});
+            }
+            catch (error) {
+                if (!(error instanceof OmniBridgeError) || error.code !== "JOURNAL_STATE_CONFLICT")
+                    throw error;
+                const raced = await this.#readRecord(clientRequestId);
+                if (raced === null)
+                    throw error;
+                return this.#requireMatchingCubeRequest(clientRequestId, requestHash, raced);
+            }
         }
+        const raced = await this.#readRecord(clientRequestId);
+        if (raced === null) {
+            throw bridgeError("JOURNAL_WRITE_FAILED", "The local operation journal could not be saved.", true);
+        }
+        return this.#requireMatchingCubeRequest(clientRequestId, requestHash, raced);
     }
     async markGrantIssued(clientRequestId, fields) {
         const current = await this.loadByRequestId(clientRequestId);
@@ -425,11 +698,19 @@ export class OperationJournal {
     }
     async #persistedRecord(record) {
         return {
-            version: 2,
+            version: 3,
             clientRequestId: record.clientRequestId,
-            requestHash: record.requestHash,
-            sourceLocatorHash: record.sourceLocatorHash,
+            // A legacy record persisted before reconstruction (for example a
+            // source-free recovery failure) gets the deterministic keyed handle of
+            // the empty identity; it can never match a real submission.
+            requestIdentityHmac: record.requestIdentityHmac === null
+                ? await this.#hmac(REQUEST_IDENTITY_DOMAIN, "")
+                : record.requestIdentityHmac,
+            sourceLocatorHmac: record.sourceLocatorHmac,
             sourceKind: record.sourceKind,
+            detail: record.detail,
+            groundingSchemaVersion: record.groundingSchemaVersion,
+            bundleProtocolVersion: record.bundleProtocolVersion,
             operationId: record.operationId,
             operationToken: record.operationToken === null
                 ? null
@@ -453,43 +734,116 @@ export class OperationJournal {
             errorCode: record.errorCode,
         };
     }
+    async #persistedFromInMemory(record) {
+        return {
+            version: 3,
+            clientRequestId: record.clientRequestId,
+            requestIdentityHmac: record.requestIdentityHmac === null
+                ? await this.#hmac(REQUEST_IDENTITY_DOMAIN, "")
+                : record.requestIdentityHmac,
+            sourceLocatorHmac: record.sourceLocatorHmac,
+            sourceKind: record.sourceKind,
+            detail: record.detail,
+            groundingSchemaVersion: record.groundingSchemaVersion,
+            bundleProtocolVersion: record.bundleProtocolVersion,
+            operationId: record.operationId,
+            operationToken: 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
+        return this.#recordFromInMemory(clientRequestId, migrateInMemory(stored));
+    }
+    async #recordFromInMemory(clientRequestId, migrated) {
+        const operationToken = migrated.operationToken === null
             ? null
-            : await this.#decryptToken(clientRequestId, persisted.operationToken);
+            : await this.#decryptToken(clientRequestId, migrated.operationToken);
         return {
-            clientRequestId: persisted.clientRequestId,
-            requestHash: persisted.requestHash,
-            sourceLocatorHash: persisted.sourceLocatorHash,
-            sourceKind: persisted.sourceKind,
-            operationId: persisted.operationId,
+            clientRequestId: migrated.clientRequestId,
+            requestIdentityHmac: migrated.requestIdentityHmac,
+            sourceLocatorHmac: migrated.sourceLocatorHmac,
+            requestHash: migrated.requestHash,
+            sourceLocatorHash: migrated.sourceLocatorHash,
+            sourceKind: migrated.sourceKind,
+            detail: migrated.detail,
+            groundingSchemaVersion: migrated.groundingSchemaVersion,
+            bundleProtocolVersion: migrated.bundleProtocolVersion,
+            operationId: migrated.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,
+            uploadUrl: migrated.uploadUrl,
+            state: migrated.state,
+            createdAt: migrated.createdAt,
+            updatedAt: migrated.updatedAt,
+            expiresAt: migrated.expiresAt,
+            stage: migrated.stage,
+            progressPercent: migrated.progressPercent,
+            progress: migrated.progress,
+            fileUploaded: migrated.fileUploaded,
+            parserStarted: migrated.parserStarted,
+            billed: migrated.billed,
+            contentReleased: migrated.contentReleased,
+            processingCopy: migrated.processingCopy,
+            temporaryData: migrated.temporaryData,
+            deliveryResult: migrated.deliveryResult,
+            resultId: migrated.resultId,
+            resultExpiresAt: migrated.resultExpiresAt,
+            errorCode: migrated.errorCode,
         };
     }
-    async #requireMatchingRequest(clientRequestId, requestHash, persisted) {
-        if (persisted.requestHash !== requestHash) {
-            throw bridgeError("IDEMPOTENCY_COLLISION", "This local operation request identifier is already bound to different metadata.", false);
+    // Recompute domain-separated HMACs from safe canonical source facts and drop
+    // the legacy unkeyed hashes from the in-memory record.
+    async #reconstructLegacy(stored, hmacPayload, sourceLocator) {
+        const migrated = migrateInMemory(stored);
+        migrated.requestIdentityHmac = await this.#hmac(REQUEST_IDENTITY_DOMAIN, hmacPayload);
+        migrated.sourceLocatorHmac = sourceLocator === null
+            ? null
+            : await this.#hmac(SOURCE_LOCATOR_DOMAIN, sourceLocator);
+        migrated.requestHash = null;
+        migrated.sourceLocatorHash = null;
+        return migrated;
+    }
+    async #requireMatchingRequest(clientRequestId, canonicalIdentityJson, sourceLocator, persisted) {
+        if (persisted.version === 3) {
+            const expected = await this.#hmacExisting(REQUEST_IDENTITY_DOMAIN, canonicalIdentityJson);
+            if (!hmacEqual(persisted.requestIdentityHmac, expected)) {
+                throw bridgeError("IDEMPOTENCY_COLLISION", "This local operation request identifier is already bound to different metadata.", false);
+            }
+            return this.#recordToPublic(clientRequestId, persisted);
         }
-        return this.#recordToPublic(clientRequestId, persisted);
+        if (persisted.requestHash ===
+            `sha256:${createHash("sha256").update(canonicalIdentityJson, "utf8").digest("hex")}`) {
+            return this.#recordFromInMemory(clientRequestId, await this.#reconstructLegacy(persisted, canonicalIdentityJson, sourceLocator));
+        }
+        throw bridgeError("IDEMPOTENCY_COLLISION", "This local operation request identifier is already bound to different metadata.", false);
+    }
+    async #requireMatchingCubeRequest(clientRequestId, requestHash, persisted) {
+        if (persisted.version === 3) {
+            const expected = await this.#hmacExisting(REQUEST_IDENTITY_DOMAIN, requestHash);
+            if (!hmacEqual(persisted.requestIdentityHmac, expected)) {
+                throw bridgeError("IDEMPOTENCY_COLLISION", "This local operation request identifier is already bound to different metadata.", false);
+            }
+            return this.#recordToPublic(clientRequestId, persisted);
+        }
+        if (persisted.requestHash === requestHash) {
+            return this.#recordFromInMemory(clientRequestId, await this.#reconstructLegacy(persisted, requestHash, null));
+        }
+        throw bridgeError("IDEMPOTENCY_COLLISION", "This local operation request identifier is already bound to different metadata.", false);
     }
     #requireMatchingGrant(current, fields) {
         if (current.operationId !== fields.operationId ||
@@ -515,7 +869,7 @@ export class OperationJournal {
     }
     async #readRecord(clientRequestId) {
         const current = await this.#readRecordFile(clientRequestId, this.#recordPath(clientRequestId));
-        if (current?.version === 2)
+        if (current !== null && current.version >= 2)
             return current;
         const legacyIssued = await this.#readRecordFile(clientRequestId, this.#legacyIssuedRecordPath(clientRequestId));
         return legacyIssued ?? current;
@@ -548,7 +902,7 @@ export class OperationJournal {
         let handle;
         try {
             handle = await open(temporaryPath, "wx", 0o600);
-            await handle.writeFile(`${JSON.stringify(record)}\n`, "utf8");
+            await handle.writeFile(`${JSON.stringify(await this.#persistedFromInMemory(record))}\n`, "utf8");
             await handle.sync();
             await handle.close();
             handle = undefined;
@@ -687,6 +1041,14 @@ export class OperationJournal {
             await unlink(temporaryPath).catch(() => undefined);
         }
     }
+    async #hmac(domain, payload) {
+        const key = await this.#journalKey();
+        return createHmac("sha256", key).update(domain, "utf8").update(payload, "utf8").digest("hex");
+    }
+    async #hmacExisting(domain, payload) {
+        const key = await this.#existingJournalKey();
+        return createHmac("sha256", key).update(domain, "utf8").update(payload, "utf8").digest("hex");
+    }
     async #encryptToken(clientRequestId, operationToken) {
         const key = await this.#journalKey();
         const nonce = randomBytes(12);