codex-overleaf-link 2.4.1 → 2.5.1

package/extension/src/shared/undoOperations.js

@@ -1,10 +1,10 @@
 (function initUndoOperations(root, factory) {
   if (typeof module === 'object' && module.exports) {
-    module.exports = factory();
+    module.exports = factory(require('./staleGuard'));
   } else {
-    root.CodexOverleafUndoOperations = factory();
+    root.CodexOverleafUndoOperations = factory(root.CodexOverleafStaleGuard);
   }
-})(typeof globalThis !== 'undefined' ? globalThis : window, function undoOperationsFactory() {
+})(typeof globalThis !== 'undefined' ? globalThis : window, function undoOperationsFactory(StaleGuard) {
   'use strict';
 
   function buildUndoOperations(project, appliedOperations) {
@@ -15,6 +15,7 @@
       }
     }
 
+    const sourceFilesByPath = new Map(workingFilesByPath);
     const undo = [];
     const fullRestoreEditPaths = new Set();
 
@@ -29,7 +30,8 @@
         }
         const currentBeforeEdit = workingFilesByPath.get(operation.path);
         if (!fullRestoreEditPaths.has(operation.path)) {
-          const inversePatches = buildInverseTextPatches(currentBeforeEdit, operation.patches);
+          const inversePatches = buildInverseTextPatches(sourceFilesByPath.get(operation.path), operation.patches,
+            operation.verifiedContent, operation.path);
           if (inversePatches.length) {
             undo.push(normalizeUndoOperation({
               type: 'edit',
@@ -70,10 +72,13 @@
         if (!operation.path || !operation.to) {
           continue;
         }
+        if (operation.moveProof && !operation.moveProof.targetEntityId) continue;
         undo.push(normalizeUndoOperation({
           type: 'move',
           path: operation.to,
           to: operation.path,
+          ...(operation.moveProof ? { moveProof: { ...operation.moveProof,
+            sourceEntityId: operation.moveProof.targetEntityId, targetEntityId: operation.moveProof.sourceEntityId } } : {}),
           reason: 'Undo move'
         }));
       } else if (operation.type === 'delete') {
@@ -89,12 +94,13 @@
       }
 
       applyOperationToFiles(workingFilesByPath, operation);
+      applyOperationToFiles(sourceFilesByPath, { ...operation, verifiedContent: undefined });
     }
 
     return undo.reverse();
   }
 
-  function buildInverseTextPatches(textBeforeEdit, patches) {
+  function buildInverseTextPatches(textBeforeEdit, patches, verifiedContent, path) {
     if (!Array.isArray(patches) || !patches.length) {
       return [];
     }
@@ -108,7 +114,7 @@
     }
 
     let offset = 0;
-    return normalized.patches.map(patch => {
+    const inverse = normalized.patches.map(patch => {
       const from = patch.from + offset;
       const to = from + patch.insert.length;
       offset += patch.insert.length - (patch.to - patch.from);
@@ -119,6 +125,41 @@
         insert: patch.expected
       };
     });
+    if (typeof verifiedContent !== 'string' || verifiedContent === applied.text) return inverse;
+    // The stored checkpoint uses the verified editor post-image. Its inverse
+    // must use those same offsets, while Native patches retain their source
+    // representation for later operations in the batch.
+    const prepared = StaleGuard.prepareOperationPatches({ type: 'edit', path, patches: inverse }, verifiedContent,
+      StaleGuard.buildBaseFileLookup([{ path, content: applied.text }]));
+    return prepared.ok && applyTextPatches(verifiedContent, prepared.patches).ok ? prepared.patches : [];
+  }
+
+  function selectExpectedFilesForTrackedUndo(project, operations = [], trackedChanges = [], previousExpectedFiles = []) {
+    const paths = new Set();
+    for (const change of trackedChanges || []) if (change?.path) paths.add(change.path);
+    for (const operation of operations || []) {
+      if (operation?.path) paths.add(operation.path);
+      if (operation?.to) paths.add(operation.to);
+    }
+    const expectedByPath = new Map();
+    for (const file of previousExpectedFiles || []) {
+      if (paths.has(file?.path) && typeof file?.content === 'string' && !expectedByPath.has(file.path)) {
+        expectedByPath.set(file.path, { path: file.path, content: file.content });
+      }
+    }
+    // Reconstruct the pre-image with the same inverse patches as plain Undo.
+    // This preserves the editor's unchanged line endings and collaborator
+    // content, including when the ZIP baseline used a different representation.
+    const hasVerifiedPatches = operations.some(operation => typeof operation?.verifiedContent === 'string'
+      && Array.isArray(operation.patches) && operation.patches.length);
+    const checkpoint = hasVerifiedPatches ? buildUndoCheckpoint(project, operations) : null;
+    const restored = checkpoint ? buildExpectedFilesAfterOperations({ files: checkpoint.undoBaseFiles }, checkpoint.undoOperations) : new Map();
+    for (const file of project?.files || []) {
+      if (paths.has(file?.path) && typeof file?.content === 'string' && !expectedByPath.has(file.path)) {
+        expectedByPath.set(file.path, { path: file.path, content: restored.get(file.path) ?? file.content });
+      }
+    }
+    return Array.from(expectedByPath.values());
   }
 
   function buildUndoCheckpoint(project, appliedOperations) {
@@ -130,6 +171,166 @@
     };
   }
 
+  // File creation has its own inverse even when text edits use Reviewing.
+  // Store post-images, never infer an empty pre-image for a missing file.
+  function buildCreatedFileUndoCheckpoint(project, appliedOperations, previous = {}) {
+    const originalPaths = new Set((project?.files || []).map(file => file?.path));
+    const priorFiles = filesListToMap(previous.undoBaseFiles);
+    const created = new Map();
+    for (const operation of previous.undoOperations || []) {
+      const proof = operation?.undoCreatedFile;
+      if (operation?.type !== 'delete' || proof?.v !== 1) continue;
+      if (proof.kind === 'text' && priorFiles.has(operation.path)) {
+        created.set(operation.path, { kind: 'text', content: priorFiles.get(operation.path), createdDirectories: proof.createdDirectories });
+      } else if (proof.kind === 'binary' && /^[a-f0-9]{64}$/i.test(proof.sha256 || '')) {
+        created.set(operation.path, { kind: 'binary', sha256: proof.sha256.toLowerCase(), createdDirectories: proof.createdDirectories });
+      }
+    }
+    for (const operation of appliedOperations || []) {
+      if (!operation?.path) continue;
+      const path = operation.path;
+      if (operation.type === 'create' || operation.type === 'binary-create') {
+        if (originalPaths.has(path) && !created.has(path)) continue;
+        if (operation.type === 'create' && typeof operation.content === 'string') {
+          created.set(path, { kind: 'text', content: typeof operation.verifiedContent === 'string'
+            ? operation.verifiedContent : operation.content, createdDirectories: operation.createdDirectories });
+        } else {
+          const hash = operation.sha256 || operation.assetRef?.sha256;
+          if (operation.previousExists !== true && /^[a-f0-9]{64}$/i.test(hash || '')) {
+            created.set(path, { kind: 'binary', sha256: hash.toLowerCase(), createdDirectories: operation.createdDirectories });
+          }
+        }
+      } else if (operation.type === 'edit' && created.get(path)?.kind === 'text') {
+        const files = new Map([[path, created.get(path).content]]);
+        applyOperationToFiles(files, operation);
+        created.set(path, { ...created.get(path), kind: 'text', content: files.get(path) });
+      } else if (['delete', 'rename', 'move', 'overwrite-binary'].includes(operation.type)) {
+        // Existing rename/overwrite recovery retains ownership of these cases.
+        created.delete(path);
+        if (operation.to) created.delete(operation.to);
+      }
+    }
+    const undoBaseFiles = [], undoOperations = [];
+    for (const [path, proof] of Array.from(created).reverse()) {
+      const undoCreatedFile = proof.kind === 'binary'
+        ? { v: 1, kind: 'binary', sha256: proof.sha256 } : { v: 1, kind: 'text' };
+      if (Array.isArray(proof.createdDirectories) && proof.createdDirectories.length) {
+        undoCreatedFile.createdDirectories = proof.createdDirectories.map(item => ({ ...item }));
+      }
+      undoOperations.push({ ...normalizeUndoOperation({ type: 'delete', path, reason: 'Undo create' }), undoCreatedFile });
+      if (proof.kind === 'text') undoBaseFiles.push({ path, content: proof.content });
+    }
+    // Reviewing has no text insertion/deletion refs for a native metadata move.
+    // Keep its identity-bound inverse with the other file-level proofs.
+    undoOperations.push(...buildUndoOperations(project, appliedOperations).filter(operation => operation.type === 'move' && operation.moveProof));
+    return { undoOperations, undoBaseFiles };
+  }
+
+  function isFileUndoOperation(operation) {
+    return operation?.undoCreatedFile?.v === 1
+      || (operation?.type === 'move' && operation.moveProof?.v === 1)
+      || (operation?.type === 'create' && typeof operation.content === 'string');
+  }
+
+  // A deleted original has no editor post-image. Its inverse is a guarded
+  // file creation, backed by both the forward delete and the captured original.
+  // This also recovers older Track-on records that omitted that inverse.
+  function getFileUndoOperations(run = {}) {
+    const operations = (run.undoOperations || []).filter(isFileUndoOperation);
+    const before = filesListToMap(run.undoExpectedFiles);
+    const after = buildExpectedFilesAfterOperations({ files: run.undoExpectedFiles }, run.appliedOperations);
+    const deleted = new Set((run.appliedOperations || []).filter(operation => operation?.type === 'delete'
+      && before.has(operation.path) && !after.has(operation.path)).map(operation => operation.path));
+    return [...operations.filter(operation => !deleted.has(operation.path)), ...Array.from(deleted, path =>
+      normalizeUndoOperation({ type: 'create', path, content: before.get(path), reason: 'Undo delete' }))];
+  }
+
+  function prepareRunUndo(run = {}) {
+    const files = getFileUndoOperations(run);
+    const restored = new Set(files.filter(operation => operation.type === 'create').map(operation => operation.path));
+    const pending = [...files], operations = [];
+    for (const operation of run.undoOperations || []) {
+      if (isFileUndoOperation(operation)) {
+        const index = pending.findIndex(file => file.path === operation.path && file.type === operation.type);
+        if (index >= 0) operations.push(...pending.splice(index, 1));
+      } else if (!restored.has(operation.path)) operations.push(operation);
+    }
+    return { ...run, undoOperations: [...operations, ...pending] };
+  }
+
+  function textUndoRun(run = {}) {
+    const restored = new Set(getFileUndoOperations(run).flatMap(operation => operation.type === 'create' ? [operation.path]
+      : operation.type === 'move' ? [operation.path, operation.to] : []));
+    return { ...run,
+      undoExpectedFiles: (run.undoExpectedFiles || []).filter(file => !restored.has(file.path)),
+      undoTrackedChanges: (run.undoTrackedChanges || []).filter(ref => !restored.has(ref.path))
+    };
+  }
+
+  function mergeFileUndoResult(textResult, fileResult, operations) {
+    const applied = [...(textResult.applied || []), ...(fileResult.applied || [])];
+    const skipped = [...(textResult.skipped || []), ...(fileResult.skipped || [])];
+    for (const operation of operations) {
+      if (!(fileResult.applied || []).some(entry => entry.operation?.path === operation.path
+        && entry.operation?.type === operation.type && entry.result?.ok === true && entry.result?.verified === true
+        && entry.result.verification === 'overleaf-zip')
+        && !(fileResult.skipped || []).some(entry => entry.operation?.path === operation.path)) {
+        skipped.push({ operation, result: { ok: false, code: 'undo_operation_failed',
+          reason: 'The file restoration has no verified server receipt.' } });
+      }
+    }
+    return { ...textResult, ok: textResult.ok !== false && fileResult.ok !== false && !skipped.length, applied, skipped };
+  }
+
+  // Consume only independently verified rollback receipts. Forward writes
+  // remain audit evidence; recovery arrays describe only unfinished work.
+  function advanceUndoCheckpoint(run = {}, result = {}, verifyText = () => false) {
+    const operations = Array.isArray(run?.undoOperations) ? run.undoOperations : [];
+    const applied = Array.isArray(result.applied) ? result.applied : [];
+    const skipped = Array.isArray(result.skipped) ? result.skipped : [];
+    const failed = path => skipped.some(entry => {
+      const target = entry?.operation?.path || entry?.trackedChange?.path || entry?.result?.failure?.file;
+      return !target || target === path;
+    });
+    if (result.failure || result.error) return run;
+    const textPaths = new Set((run.undoExpectedFiles || [])
+      .filter(file => file?.path && typeof file.content === 'string' && !failed(file.path)
+        && typeof verifyText === 'function' && verifyText(file) === true)
+      .map(file => file.path));
+    const deletedPaths = new Set(operations.filter(operation => operation?.type === 'delete'
+      && operation.undoCreatedFile?.v === 1 && !failed(operation.path)
+      && applied.some(entry => entry?.operation?.type === 'delete' && entry.operation.path === operation.path
+        && JSON.stringify(entry.operation.undoCreatedFile) === JSON.stringify(operation.undoCreatedFile)
+        && entry.result?.ok === true && entry.result.verified === true
+        && entry.result.verification === 'overleaf-zip')).map(operation => operation.path));
+    const restoredPaths = new Set(operations.filter(operation => operation?.type === 'create'
+      && !failed(operation.path) && applied.some(entry => entry?.operation?.type === 'create'
+        && entry.operation.path === operation.path && entry.operation.content === operation.content
+        && entry.result?.ok === true && entry.result.verified === true
+        && entry.result.verification === 'overleaf-zip')).map(operation => operation.path));
+    const movedPaths = new Set(operations.filter(operation => operation?.type === 'move' && operation.moveProof?.v === 1
+      && !failed(operation.path) && applied.some(entry => entry?.operation?.type === 'move'
+        && entry.operation.path === operation.path && entry.operation.to === operation.to
+        && JSON.stringify(entry.operation.moveProof) === JSON.stringify(operation.moveProof)
+        && entry.result?.ok === true && entry.result.verified === true && entry.result.verification === 'overleaf-zip'))
+      .flatMap(operation => [operation.path, operation.to]));
+    for (const path of restoredPaths) textPaths.add(path);
+    for (const path of movedPaths) textPaths.add(path);
+    if (!textPaths.size && !deletedPaths.size) return run;
+    const pending = operations.filter(operation => !restoredPaths.has(operation.path) && !(operation?.type === 'edit' && textPaths.has(operation.path))
+      && !(operation?.type === 'move' && movedPaths.has(operation.path))
+      && !(operation?.type === 'delete' && operation.undoCreatedFile?.v === 1 && deletedPaths.has(operation.path)));
+    const needed = new Set(pending.flatMap(operation => [operation?.path, operation?.to]).filter(Boolean));
+    return { ...run,
+      undoOperations: pending,
+      undoBaseFiles: (run.undoBaseFiles || []).filter(file => needed.has(file?.path)
+        || (!textPaths.has(file?.path) && !deletedPaths.has(file?.path))),
+      undoExpectedFiles: (run.undoExpectedFiles || []).filter(file => !textPaths.has(file?.path)),
+      undoTrackedChanges: (run.undoTrackedChanges || []).filter(ref => !textPaths.has(ref?.path)),
+      trackedChangeCaptures: (run.trackedChangeCaptures || []).filter(capture => !textPaths.has(capture?.path))
+    };
+  }
+
   function buildSnapshotRestoreUndo(run = {}) {
     const undoOperations = Array.isArray(run.undoOperations) ? run.undoOperations : [];
     const originalByPath = buildOriginalFilesForSnapshotUndo(run, undoOperations);
@@ -311,6 +512,7 @@
         insert: String(patch.insert ?? '')
       }));
     }
+    if (operation.type === 'move' && operation.moveProof?.v === 1) normalized.moveProof = JSON.parse(JSON.stringify(operation.moveProof));
     return normalized;
   }
 
@@ -369,9 +571,17 @@
   }
 
   return {
+    isFileUndoOperation,
+    getFileUndoOperations,
+    prepareRunUndo,
+    textUndoRun,
+    mergeFileUndoResult,
     buildUndoCheckpoint,
+    buildCreatedFileUndoCheckpoint,
+    advanceUndoCheckpoint,
     buildExpectedFilesAfterOperations,
     buildUndoOperations,
+    selectExpectedFilesForTrackedUndo,
     buildSnapshotRestoreUndo
   };
 });

package/extension/src/shared/updateConsent.js

@@ -13,6 +13,7 @@
     'idle',
     'checking',
     'update_available',
+    'manual_install_required',
     'downloading',
     'staged',
     'waiting_for_idle',
@@ -41,6 +42,7 @@
     idle: { value: 0, determinate: true, phase: 'idle' },
     checking: { value: 0, determinate: false, phase: 'checking' },
     update_available: { value: 0, determinate: true, phase: 'available' },
+    manual_install_required: { value: 0, determinate: true, phase: 'manual' },
     downloading: { value: 35, determinate: false, phase: 'downloading' },
     staged: { value: 65, determinate: true, phase: 'staged' },
     waiting_for_idle: { value: 65, determinate: true, phase: 'waiting' },
@@ -66,6 +68,9 @@
       blocker: blockers[0] || '',
       blockers,
       transactionId: safeId(value.transactionId),
+      operationId: safeId(value.operationId),
+      cancelRequested: value.cancelRequested === true,
+      recoveryPending: value.recoveryPending === true,
       initiatedBy: ['automatic', 'manual'].includes(value.initiatedBy) ? value.initiatedBy : '',
       lastCheckedAt: finiteNumber(value.lastCheckedAt),
       stagedAt: finiteNumber(value.stagedAt),
@@ -73,11 +78,24 @@
       deadlineAt: finiteNumber(value.deadlineAt),
       heartbeatAt: finiteNumber(value.heartbeatAt),
       postponeUntil: finiteNumber(value.postponeUntil),
+      cooldownUntil: finiteNumber(value.cooldownUntil),
       code: safeToken(value.code),
-      message: String(value.message || '').replace(/\s+/g, ' ').trim().slice(0, 300)
+      message: String(value.message || '').replace(/\s+/g, ' ').trim().slice(0, 300),
+      manualReason: normalizeManualReason(value.manualReason)
     };
   }
 
+  // Signed per-locale reason a release needs a one-time reinstall.
+  function normalizeManualReason(value) {
+    if (!value || typeof value !== 'object') return {};
+    const out = {};
+    for (const locale of ['en', 'zh']) {
+      const text = String(value[locale] || '').replace(/\s+/g, ' ').trim().slice(0, 400);
+      if (text) out[locale] = text;
+    }
+    return out;
+  }
+
   function normalizeConsentState(value = {}) {
     return {
       schemaVersion: 1,
@@ -101,11 +119,19 @@
     const state = normalizeUpdateState(updateValue, options.currentVersion);
     const consent = normalizeConsentState(consentValue);
     const newer = compareStableVersions(state.latestVersion, state.currentVersion) > 0;
-    const snoozed = newer &&
-      consent.snoozedVersion === state.latestVersion &&
-      consent.snoozedUntil > now;
     const execution = EXECUTION_STATES.has(state.state);
     const available = state.state === 'update_available' && newer;
+    // A newer release that only a reinstall can apply. It is shown even after
+    // an automatic check, because no Update now button can ever resolve it.
+    // Compare with the running version: after the reinstall the stored state
+    // still names the old one, and the notice must clear by itself.
+    const runningVersion = safeVersion(options.currentVersion) || state.currentVersion;
+    const manualInstall = state.state === 'manual_install_required'
+      && (compareStableVersions(state.latestVersion, runningVersion) > 0
+        || (state.code === 'prerelease_promotion_requires_manual_update'
+          && state.latestVersion === runningVersion));
+    const snoozed = (newer || manualInstall) &&
+      consent.snoozedVersion === state.latestVersion && consent.snoozedUntil > now;
     const progress = getProgressModel(state);
     const quietFailure = state.state === 'failed' &&
       state.initiatedBy !== 'manual' &&
@@ -124,16 +150,21 @@
       },
       progress,
       available,
+      manualInstall,
       snoozed,
       execution,
-      showPanel: (available && !snoozed) || execution || state.state === 'rolled_back' ||
-        visibleFailure,
-      badge: getBadge(state, { available, snoozed }),
+      showPanel: state.cancelRequested || state.recoveryPending
+        || (state.state === 'checking' && state.initiatedBy === 'manual')
+        || ((available || manualInstall) && !snoozed) || execution || state.state === 'rolled_back' || visibleFailure,
+      badge: getBadge(state, { available: available || manualInstall, snoozed }),
       actions: {
-        check: ['idle', 'committed', 'rolled_back', 'failed'].includes(state.state),
-        install: available,
-        later: available || ['staged', 'waiting_for_idle'].includes(state.state),
-        retry: ['failed', 'rolled_back'].includes(state.state)
+        check: !state.cancelRequested && !state.recoveryPending && ['idle', 'committed', 'rolled_back', 'failed', 'manual_install_required'].includes(state.state),
+        copyInstall: manualInstall,
+        install: available && !state.cancelRequested && !state.recoveryPending,
+        later: !state.recoveryPending && (available || manualInstall || ['staged', 'waiting_for_idle'].includes(state.state)),
+        cancel: !state.recoveryPending && (state.cancelRequested || ['checking', 'downloading', 'staged', 'waiting_for_idle'].includes(state.state)),
+        recover: state.recoveryPending,
+        retry: !state.cancelRequested && !state.recoveryPending && ['failed', 'rolled_back'].includes(state.state)
       }
     };
   }

package/extension/src/shared/updateRuntimeIdentity.js

@@ -18,7 +18,7 @@
     if (!status.managed || !result.installedVersion || !result.nativeVersion ||
         !result.extensionVersion || !result.runtimeVersion) return result;
     if (['authorized', 'bound'].includes(status.authorization?.state) ||
-        ['staged', 'activation_pending', 'applying', 'awaiting_health'].includes(status.transaction?.state)) {
+        ['staged', 'activation_pending', 'applying', 'bootstrap_pending', 'bootstrap_rolling_back', 'awaiting_health', 'rolling_back'].includes(status.transaction?.state)) {
       return { ...result, state: 'transaction_active' };
     }
     if (status.installedAligned !== true) return { ...result, state: 'repair_required' };

package/extension/src/shared/writebackIntent.js

@@ -0,0 +1,78 @@
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory(require('./undoOperations'));
+  else root.CodexOverleafModuleRegistry.define('WritebackIntent', ['UndoOperations'], factory);
+})(typeof globalThis !== 'undefined' ? globalThis : window, function (Undo) {
+  'use strict';
+  const MAX_BYTES = 300 * 1024;
+  const types = new Set(['edit', 'create', 'delete', 'rename', 'move', 'binary-create', 'overwrite-binary']);
+  const path = value => typeof value === 'string' && value && !value.startsWith('/')
+    && !/^[A-Za-z]:/.test(value) && !value.replace(/\\/g, '/').split('/').some(part => !part || part === '.' || part === '..');
+  function normalize(value) {
+    if (!value || typeof value !== 'object' || !value.id || !value.projectId || !value.accountScopeId
+      || !value.sessionId || !value.runId || !Array.isArray(value.operations) || value.operations.length > 100) return null;
+    const operations = [];
+    for (const input of value.operations) {
+      if (!types.has(input?.type) || !path(input.path) || (input.to && !path(input.to))) return null;
+      const op = { type: input.type, path: input.path };
+      for (const key of ['to', 'content', 'replaceAll', 'find', 'replace', 'sha256', 'mimeType']) {
+        if (typeof input[key] === 'string') op[key] = input[key];
+      }
+      if (Number.isSafeInteger(input.size)) op.size = input.size;
+      if (input.moveProof !== undefined) {
+        const proof = input.moveProof;
+        if (input.type !== 'move' || proof?.v !== 1 || !['text', 'binary'].includes(proof.kind)
+          || !/^[a-f0-9]{64}$/i.test(proof.sha256 || '')) return null;
+        op.moveProof = { v: 1, kind: proof.kind, sha256: proof.sha256.toLowerCase() };
+        if (proof.entityType !== undefined) {
+          if (!['doc', 'file'].includes(proof.entityType)) return null;
+          op.moveProof.entityType = proof.entityType;
+        }
+        for (const key of ['sourceEntityId', 'targetEntityId']) {
+          if (proof[key] !== undefined) {
+            if (typeof proof[key] !== 'string' || !proof[key] || proof[key].length > 160 || /[\0\r\n]/.test(proof[key])) return null;
+            op.moveProof[key] = proof[key];
+          }
+        }
+      }
+      if (Array.isArray(input.patches)) {
+        if (input.patches.length > 1000) return null;
+        op.patches = input.patches.map(p => ({ from: p.from, to: p.to, expected: String(p.expected ?? ''), insert: String(p.insert ?? '') }));
+        if (op.patches.some(p => !Number.isSafeInteger(p.from) || !Number.isSafeInteger(p.to) || p.from < 0 || p.to < p.from)) return null;
+      }
+      operations.push(op);
+    }
+    const paths = new Set(operations.flatMap(op => [op.path, op.to].filter(Boolean)));
+    const baseFiles = (Array.isArray(value.baseFiles) ? value.baseFiles : [])
+      .filter(file => paths.has(file?.path) && typeof file.content === 'string')
+      .map(file => ({ path: file.path, content: file.content }));
+    const result = { v: 1, id: String(value.id).slice(0, 160), projectId: String(value.projectId).slice(0, 160),
+      accountScopeId: String(value.accountScopeId).slice(0, 160), sessionId: String(value.sessionId).slice(0, 160),
+      runId: String(value.runId).slice(0, 160), createdAt: String(value.createdAt || '').slice(0, 64),
+      requireReviewing: value.requireReviewing === true, operations, baseFiles };
+    if (typeof value.requestId === 'string') result.requestId = value.requestId.slice(0, 160);
+    const size = typeof TextEncoder === 'function' ? new TextEncoder().encode(JSON.stringify(result)).length : JSON.stringify(result).length * 2;
+    return size <= MAX_BYTES ? result : null;
+  }
+  function expectedFiles(value) {
+    return Undo.buildExpectedFilesAfterOperations({ files: value.baseFiles }, value.operations.filter(op => !op.type.includes('binary')));
+  }
+  function normalizeSaveCheck(value) {
+    if (!value?.projectId || !value.accountScopeId || !value.sessionId || !value.runId
+      || !Array.isArray(value.files) || value.files.length > 1000) return null;
+    const files = [];
+    for (const file of value.files) {
+      if (!path(file?.path)) return null;
+      if (file.absent === true) files.push({ path: file.path, absent: true });
+      else if (/^[a-f0-9]{64}$/i.test(file.sha256 || '')) {
+        if (file.kind !== undefined && !['text', 'binary'].includes(file.kind)) return null;
+        files.push({ path: file.path, sha256: file.sha256.toLowerCase(),
+          ...(file.kind ? { kind: file.kind } : {}) });
+      }
+      else return null;
+    }
+    return files.length ? { v: 1, projectId: String(value.projectId).slice(0, 160),
+      accountScopeId: String(value.accountScopeId).slice(0, 160), sessionId: String(value.sessionId).slice(0, 160),
+      runId: String(value.runId).slice(0, 160), createdAt: String(value.createdAt || '').slice(0, 64), files } : null;
+  }
+  return { normalize, normalizeSaveCheck, expectedFiles, MAX_BYTES };
+});

package/extension/src/shared/writebackOperationEvidence.js

@@ -1,10 +1,10 @@
 (function initCodexOverleafWritebackOperationEvidence(root, factory) {
   if (typeof module === 'object' && module.exports) {
-    module.exports = factory();
+    module.exports = factory(require('./failureReasons'));
   } else {
-    root.CodexOverleafModuleRegistry.define('WritebackOperationEvidence', [], factory);
+    root.CodexOverleafModuleRegistry.define('WritebackOperationEvidence', ['FailureReasons'], factory);
   }
-})(typeof window !== 'undefined' ? window : globalThis, function writebackOperationEvidenceFactory() {
+})(typeof window !== 'undefined' ? window : globalThis, function writebackOperationEvidenceFactory(FailureReasons) {
   'use strict';
 
   function normalizeOperationEvidence(operations = [], applyResult = {}) {
@@ -99,18 +99,7 @@
   }
 
   function normalizeFailure(result, operation) {
-    if (result?.failure && typeof result.failure === 'object') return cloneValue(result.failure);
-    if (!result?.code) return null;
-    return {
-      code: result.code,
-      stage: result.stage || 'write',
-      severity: result.severity || 'error',
-      userMessage: result.reason || result.message || result.code,
-      retryable: result.retryable === true,
-      file: operation?.path || operation?.to || '',
-      changedDocument: result.changedDocument === true,
-      terminalState: result.terminalState || ''
-    };
+    return FailureReasons.normalizeWritebackFailure(result, operation);
   }
 
   function normalizeTrackedChanges(value) {