codex-overleaf-link 2.2.1 → 2.3.1

package/extension/src/shared/sessionState.js

@@ -1,18 +1,30 @@
 (function initSessionState(root, factory) {
   if (typeof module === 'object' && module.exports) {
-    module.exports = factory();
+    module.exports = factory(
+      require('./i18n'),
+      require('./settlementFacts'),
+      require('./runInputQueue'),
+      require('./lineReferences'),
+      require('./pathRedaction')
+    );
   } else {
-    root.CodexOverleafSessionState = factory();
-  }
-})(typeof globalThis !== 'undefined' ? globalThis : window, function sessionStateFactory() {
+    root.CodexOverleafModuleRegistry.define(
+      'SessionState',
+      ['I18n', 'SettlementFacts', 'RunInputQueue', 'LineReferences', 'PathRedaction'],
+      factory
+    );
+  }
+})(typeof globalThis !== 'undefined' ? globalThis : window, function sessionStateFactory(
+  i18n,
+  SettlementFacts,
+  RunInputQueue,
+  LineReferences,
+  PathRedaction
+) {
   'use strict';
 
-  const i18n = (typeof module === 'object' && module.exports)
-    ? require('./i18n')
-    : (typeof globalThis !== 'undefined' ? globalThis : window).CodexOverleafI18n;
-
   const DEFAULT_PANEL_STATE = {
-    mode: 'confirm',
+    mode: 'ask',
     providerId: 'builtin',
     model: 'gpt-5.4',
     reasoningEffort: 'high',
@@ -35,7 +47,7 @@
     customInstructionsByProject: {}
   };
 
-  const VALID_MODES = new Set(['ask', 'confirm', 'auto']);
+  const VALID_MODES = new Set(['ask', 'auto']);
   // Keep the persisted/session-level contract aligned with the model picker
   // and native provider bridge. Custom providers can explicitly disable
   // reasoning (`none`) or expose the lightest Codex tier (`minimal`). Dropping
@@ -109,18 +121,13 @@
     /\b(?:sk|pk)-[A-Za-z0-9][A-Za-z0-9_-]{7,}\b/g,
     /\b(?:api[_-]?key|token|password|passwd|secret)\b\s*[:=]\s*["']?[^"'\s,;]+["']?/gi
   ];
-  const LineReferences = loadLineReferences();
-  const PathRedaction = loadPathRedaction();
-
   function normalizePanelState(input = {}, options = {}) {
     const state = {
       ...DEFAULT_PANEL_STATE,
       ...input
     };
 
-    if (!VALID_MODES.has(state.mode)) {
-      state.mode = DEFAULT_PANEL_STATE.mode;
-    }
+    state.mode = normalizeMode(state.mode);
     if (!VALID_REASONING.has(state.reasoningEffort)) {
       state.reasoningEffort = DEFAULT_PANEL_STATE.reasoningEffort;
     }
@@ -212,7 +219,7 @@
       history,
       runs,
       task: sanitizeAssistantVisibleText(session.task),
-      mode: VALID_MODES.has(session.mode) ? session.mode : fallbackState.mode,
+      mode: normalizeMode(session.mode, fallbackState.mode),
       providerId: typeof session.providerId === 'string' && session.providerId.trim()
         ? session.providerId.trim()
         : (fallbackState.providerId || 'builtin'),
@@ -225,8 +232,17 @@
         : fallbackState.speedTier,
       requireReviewing: session.requireReviewing !== false,
       focusFiles: normalizeFocusFiles(session.focusFiles),
+      projectReferenceFiles: normalizeProjectReferenceFiles(session.projectReferenceFiles),
       codexThreadId: typeof session.codexThreadId === 'string' ? session.codexThreadId : '',
-      pendingInputs: normalizePendingInputs(session.pendingInputs, options.restoreRunningRuns === true)
+      pendingInputs: normalizePendingInputs(
+        session.pendingInputs,
+        options.restoreRunningRuns === true,
+        {
+          ...fallbackState,
+          ...session,
+          focusFiles: normalizeFocusFiles(session.focusFiles)
+        }
+      )
     };
   }
 
@@ -294,13 +310,14 @@
       id: active.id,
       history: Array.isArray(active.history) ? active.history.slice(-10) : [],
       focusFiles: normalizeFocusFiles(active.focusFiles),
+      projectReferenceFiles: normalizeProjectReferenceFiles(active.projectReferenceFiles),
       codexThreadId: active.codexThreadId || '',
       providerId: state.providerId || 'builtin'
     };
     state.runs = Array.isArray(active.runs) ? active.runs : [];
     state.task = typeof active.task === 'string' ? active.task : '';
     state.focusFiles = normalizeFocusFiles(active.focusFiles);
-    state.mode = VALID_MODES.has(active.mode) ? active.mode : DEFAULT_PANEL_STATE.mode;
+    state.mode = normalizeMode(active.mode);
     state.requireReviewing = active.requireReviewing !== false;
 
     return state;
@@ -322,7 +339,7 @@
       history: normalizeHistoryEntries(overrides.history),
       runs,
       task: sanitizeAssistantVisibleText(overrides.task),
-      mode: VALID_MODES.has(overrides.mode) ? overrides.mode : DEFAULT_PANEL_STATE.mode,
+      mode: normalizeMode(overrides.mode),
       providerId: typeof overrides.providerId === 'string' && overrides.providerId.trim()
         ? overrides.providerId.trim()
         : 'builtin',
@@ -335,6 +352,7 @@
         : DEFAULT_PANEL_STATE.speedTier,
       requireReviewing: overrides.requireReviewing !== false,
       focusFiles: normalizeFocusFiles(overrides.focusFiles),
+      projectReferenceFiles: normalizeProjectReferenceFiles(overrides.projectReferenceFiles),
       codexThreadId: typeof overrides.codexThreadId === 'string' ? overrides.codexThreadId : '',
       pendingInputs: normalizePendingInputs(overrides.pendingInputs)
     };
@@ -626,6 +644,18 @@
       interruptedDraft: run.interruptedDraft ? sanitizeAssistantVisibleValue(run.interruptedDraft) : undefined
     };
 
+    if (run.executionSnapshot && typeof run.executionSnapshot === 'object') {
+      normalized.executionSnapshot = sanitizeAssistantVisibleValue(run.executionSnapshot);
+    }
+    const storedSettlement = run.settlement && typeof run.settlement === 'object'
+      ? run.settlement
+      : run.settlementFacts;
+    if (storedSettlement && typeof storedSettlement === 'object') {
+      normalized.settlement = sanitizeAssistantVisibleValue(storedSettlement);
+    }
+    if (run.changedDocument === true) {
+      normalized.changedDocument = true;
+    }
     applyTrackedChangeStatus(normalized, run.trackedChangeStatus);
 
     return normalized;
@@ -658,7 +688,7 @@
     // the run returns to the legacy-undo world. A terminal status with no refs
     // is kept — step 3 already empties terminal payloads and the label stays
     // meaningful.
-    if (!hasRefs && status !== undefined && !TERMINAL_TRACKED_CHANGE_STATUS.has(status)) {
+    if (!hasRefs && status === 'pending') {
       status = undefined;
     }
 
@@ -875,6 +905,33 @@
     return files.slice(0, 5);
   }
 
+  function normalizeProjectReferenceFiles(value) {
+    const seen = new Set();
+    const files = [];
+    for (const item of Array.isArray(value) ? value : []) {
+      const rawPath = typeof item === 'string' ? item : item?.path;
+      if (typeof rawPath !== 'string' || !rawPath.trim() || rawPath.length > 512) {
+        continue;
+      }
+      if (/^(?:[A-Za-z]:|[\\/])/.test(rawPath) || rawPath.includes('\0')) {
+        continue;
+      }
+      const path = rawPath.replace(/\\/g, '/').replace(/\/+/g, '/').replace(/^\.\//, '').trim();
+      if (!path || path.split('/').some(segment => !segment || segment === '.' || segment === '..') || seen.has(path)) {
+        continue;
+      }
+      seen.add(path);
+      files.push({
+        path,
+        kind: item?.kind === 'binary' ? 'binary' : 'text'
+      });
+      if (files.length >= 5000) {
+        break;
+      }
+    }
+    return files;
+  }
+
   function normalizeCustomInstructionsByProject(value) {
     const result = {};
     if (!value || typeof value !== 'object' || Array.isArray(value)) {
@@ -965,7 +1022,7 @@
       // Skills page was reopened.
       codexOverleafSkills: compactCodexOverleafSkillsForStorage(source.codexOverleafSkills),
       composerAttachments: normalizeComposerAttachmentsForPersistence(source.composerAttachments),
-      mode: VALID_MODES.has(active?.mode) ? active.mode : normalizeMode(source.mode),
+      mode: normalizeMode(active?.mode, source.mode),
       providerId: typeof source.providerId === 'string' && source.providerId.trim()
         ? source.providerId.trim()
         : 'builtin',
@@ -1063,6 +1120,7 @@
       speedTier: normalizeSpeedTier(session.speedTier || fallbackState.speedTier),
       requireReviewing: session.requireReviewing !== false,
       focusFiles: normalizeFocusFiles(session.focusFiles),
+      projectReferenceFiles: normalizeProjectReferenceFiles(session.projectReferenceFiles),
       codexThreadId: typeof session.codexThreadId === 'string' ? session.codexThreadId : '',
       pendingInputs: normalizePendingInputs(session.pendingInputs)
     };
@@ -1121,10 +1179,18 @@
       .filter(run => Array.isArray(run.undoOperations) && run.undoOperations.length)
       .slice(0, limits.maxUndoRunsPerSession)
       .map(run => run.id));
-    return selectedRuns.map(run => compactRunForStorage(run, limits, undoRunIds.has(run.id)));
+    const settlementFactsByRunId = SettlementFacts.compactSessionSettlementFacts(selectedRuns, {
+      sanitize: sanitizeAssistantVisibleValue
+    });
+    return selectedRuns.map(run => compactRunForStorage(
+      run,
+      limits,
+      undoRunIds.has(run.id),
+      settlementFactsByRunId.get(run.id)
+    ));
   }
 
-  function compactRunForStorage(run, limits, keepUndoPayload) {
+  function compactRunForStorage(run, limits, keepUndoPayload, settlementFacts = null) {
     const undoPayload = compactUndoPayload(run, limits, keepUndoPayload);
     const compact = {
       id: run.id,
@@ -1151,6 +1217,15 @@
       nativeEventSeq: Number.isFinite(Number(run.nativeEventSeq)) ? Number(run.nativeEventSeq) : 0,
       queueItemId: normalizeTextField(run.queueItemId, 160)
     };
+    if (run.executionSnapshot && typeof run.executionSnapshot === 'object') {
+      compact.executionSnapshot = sanitizeAssistantVisibleValue(run.executionSnapshot);
+    }
+    if (settlementFacts && typeof settlementFacts === 'object') {
+      compact.settlement = settlementFacts;
+    }
+    if (run.changedDocument === true) {
+      compact.changedDocument = true;
+    }
     if (run.interruptedDraft) {
       compact.interruptedDraft = sanitizeAssistantVisibleValue(run.interruptedDraft);
     }
@@ -1293,8 +1368,14 @@
     };
   }
 
-  function normalizeMode(mode) {
-    return VALID_MODES.has(mode) ? mode : DEFAULT_PANEL_STATE.mode;
+  function normalizeMode(mode, fallback = DEFAULT_PANEL_STATE.mode) {
+    if (mode === 'confirm') {
+      return 'ask';
+    }
+    if (VALID_MODES.has(mode)) {
+      return mode;
+    }
+    return VALID_MODES.has(fallback) ? fallback : DEFAULT_PANEL_STATE.mode;
   }
 
   function normalizeReasoning(reasoningEffort) {
@@ -1384,11 +1465,9 @@
       }));
   }
 
-  function normalizePendingInputs(value, recoverActive = false) {
-    const Queue = (typeof globalThis !== 'undefined' ? globalThis.CodexOverleafRunInputQueue : null)
-      || (typeof module === 'object' && module.exports ? require('./runInputQueue') : null);
-    if (Queue?.normalizeQueue) {
-      return Queue.normalizeQueue(value, { recoverActive });
+  function normalizePendingInputs(value, recoverActive = false, fallbackInput = {}) {
+    if (RunInputQueue?.normalizeQueue) {
+      return RunInputQueue.normalizeQueue(value, { recoverActive, fallbackInput });
     }
     return [];
   }
@@ -1442,34 +1521,6 @@
     return /(?:file:\/\/\/?|[A-Za-z]:[\\/]|\/(?:Users|home|private|var|tmp)\/|[\\/]\.codex-overleaf[\\/]projects[\\/]|\.codex-overleaf[\\/]projects[\\/])/i.test(String(value || ''));
   }
 
-  function loadLineReferences() {
-    if (typeof globalThis !== 'undefined' && globalThis.CodexOverleafLineReferences) {
-      return globalThis.CodexOverleafLineReferences;
-    }
-    if (typeof require === 'function') {
-      try {
-        return require('./lineReferences');
-      } catch (_error) {
-        return null;
-      }
-    }
-    return null;
-  }
-
-  function loadPathRedaction() {
-    if (typeof globalThis !== 'undefined' && globalThis.CodexOverleafPathRedaction) {
-      return globalThis.CodexOverleafPathRedaction;
-    }
-    if (typeof require === 'function') {
-      try {
-        return require('./pathRedaction');
-      } catch (_error) {
-        return null;
-      }
-    }
-    return null;
-  }
-
   function fallbackSanitizeLocalReferences(value) {
     return String(value || '')
       .replace(/\[([^\]]*)\]\(([^)]*)\)/g, (_raw, label, target) => {

package/extension/src/shared/settlementFacts.js

@@ -0,0 +1,351 @@
+(function initCodexOverleafSettlementFacts(root, factory) {
+  if (typeof module === 'object' && module.exports) {
+    module.exports = factory(require('./failureReasons'));
+  } else {
+    root.CodexOverleafModuleRegistry.define('SettlementFacts', ['FailureReasons'], factory);
+  }
+})(typeof window !== 'undefined' ? window : globalThis, function settlementFactsFactory(DefaultFailureReasons) {
+  'use strict';
+
+  const SETTLEMENT_FACTS_MAX_BYTES = 32 * 1024;
+  const SESSION_SETTLEMENT_DETAIL_MAX_BYTES = 512 * 1024;
+  const RECOVERY_FIELDS = Object.freeze([
+    'appliedOperations', 'undoOperations', 'undoBaseFiles', 'undoTrackedChanges',
+    'undoExpectedFiles', 'undoStatus', 'interruptedDraft'
+  ]);
+
+  function compactSettlementFacts(value = {}, maxBytes = SETTLEMENT_FACTS_MAX_BYTES) {
+    const legacyFailures = value.primaryFailure && typeof value.primaryFailure === 'object'
+      ? [value.primaryFailure]
+      : [];
+    const facts = {
+      schemaVersion: 1,
+      documentEffect: normalizeDocumentEffect(
+        value.documentEffect || (value.changedDocument === true ? 'changed' : '')
+      ),
+      evidence: normalizeEvidence(value),
+      fileSettlements: normalizeFiles(value.fileSettlements),
+      failures: normalizeFailures(Array.isArray(value.failures) ? value.failures : legacyFailures),
+      recoveryAvailability: normalizeAvailability(value.recoveryAvailability),
+      recoveryDisposition: normalizeDisposition(value.recoveryDisposition),
+      capturedAt: typeof value.capturedAt === 'string' ? value.capturedAt : ''
+    };
+    if (value.compaction && typeof value.compaction === 'object') {
+      facts.compaction = normalizeCompaction(value.compaction);
+    }
+    if (estimateBytes(facts) <= maxBytes) return facts;
+
+    const files = facts.fileSettlements;
+    files.sort((left, right) => importance(left) - importance(right)
+      || left.path.localeCompare(right.path));
+    const omitted = {
+      failureOrRecovery: Number(facts.compaction?.omittedFileSettlements?.failureOrRecovery || 0),
+      changed: Number(facts.compaction?.omittedFileSettlements?.changed || 0),
+      unchangedOrUnknown: Number(facts.compaction?.omittedFileSettlements?.unchangedOrUnknown || 0)
+    };
+    facts.compaction = {
+      ...(facts.compaction || {}),
+      omittedFileSettlements: omitted,
+      omittedFailures: Number(facts.compaction?.omittedFailures || 0)
+    };
+    while (files.length && estimateBytes(facts) > maxBytes) {
+      omitted[category(files.shift())]++;
+    }
+    facts.fileSettlements = files.sort((left, right) => left.path.localeCompare(right.path));
+    if (estimateBytes(facts) > maxBytes) {
+      const primaryFailure = selectPrimaryFailure(facts.failures);
+      facts.failures = facts.failures.map(compactFailure);
+      if (primaryFailure) {
+        const primaryIndex = facts.failures.findIndex(item =>
+          item.code === primaryFailure.code
+          && item.stage === primaryFailure.stage
+          && item.severity === primaryFailure.severity
+          && item.file === primaryFailure.file
+        );
+        if (primaryIndex > 0) {
+          facts.failures.unshift(facts.failures.splice(primaryIndex, 1)[0]);
+        }
+      }
+      while (facts.failures.length > 1 && estimateBytes(facts) > maxBytes) {
+        facts.failures.pop();
+        facts.compaction.omittedFailures++;
+      }
+    }
+    return facts;
+  }
+
+  function compactSessionSettlementFacts(runs = [], options = {}) {
+    const sanitize = options.sanitize instanceof Function ? options.sanitize : cloneValue;
+    const measure = options.estimateBytes instanceof Function ? options.estimateBytes : estimateBytes;
+    const maxDetailBytes = Number.isFinite(options.maxDetailBytes)
+      ? Math.max(0, options.maxDetailBytes)
+      : SESSION_SETTLEMENT_DETAIL_MAX_BYTES;
+    const entries = (Array.isArray(runs) ? runs : [])
+      .filter(run => run?.id && (
+        (run.settlement && typeof run.settlement === 'object')
+        || (run.settlementFacts && typeof run.settlementFacts === 'object')
+      ))
+      .map((run, index) => ({
+        id: run.id,
+        protected: run.status === 'running'
+          || run.trackedChangeStatus === 'pending'
+          || run.trackedChangeStatus === 'needs_review'
+          || index === runs.length - 1,
+        facts: sanitize(run.settlement && typeof run.settlement === 'object'
+          ? run.settlement
+          : run.settlementFacts)
+      }));
+    const detailBytes = () => entries.reduce((total, entry) =>
+      total + measure(entry.facts.fileSettlements || []), 0);
+    const candidates = [
+      ...entries.filter(entry => !entry.protected),
+      ...entries.filter(entry => entry.protected)
+    ];
+    for (const entry of candidates) {
+      if (detailBytes() <= maxDetailBytes) break;
+      compactSettlementFileDetails(entry.facts, () => detailBytes() <= maxDetailBytes);
+    }
+    return new Map(entries.map(entry => [entry.id, entry.facts]));
+  }
+
+  function compactSettlementFileDetails(facts, budgetSatisfied) {
+    const files = Array.isArray(facts?.fileSettlements) ? [...facts.fileSettlements] : [];
+    files.sort((left, right) => importance(left) - importance(right)
+      || String(left?.path || '').localeCompare(String(right?.path || '')));
+    const omitted = {
+      failureOrRecovery: positive(facts?.compaction?.omittedFileSettlements?.failureOrRecovery),
+      changed: positive(facts?.compaction?.omittedFileSettlements?.changed),
+      unchangedOrUnknown: positive(facts?.compaction?.omittedFileSettlements?.unchangedOrUnknown)
+    };
+    while (files.length && !budgetSatisfied()) {
+      omitted[category(files.shift())]++;
+      facts.fileSettlements = [...files].sort((left, right) =>
+        String(left?.path || '').localeCompare(String(right?.path || '')));
+      facts.compaction = { ...(facts.compaction || {}), omittedFileSettlements: omitted };
+    }
+  }
+
+  function projectRunSettlement(run = {}) {
+    const storedFacts = run.settlement && typeof run.settlement === 'object'
+      ? run.settlement
+      : run.settlementFacts;
+    const facts = storedFacts && typeof storedFacts === 'object'
+      ? compactSettlementFacts(storedFacts)
+      : null;
+    const primaryFailure = selectPrimaryFailure(facts?.failures || []);
+    const status = text(run.trackedChangeStatus);
+    const actionable = status === 'pending' || status === 'needs_review';
+    const terminal = status === 'accepted' || status === 'rejected';
+    const payload = run.recoveryPayload && typeof run.recoveryPayload === 'object'
+      ? run.recoveryPayload
+      : run;
+    const tracked = hasItems(payload.undoTrackedChanges);
+    const anyRecovery = tracked
+      || hasItems(payload.undoOperations)
+      || hasItems(payload.undoBaseFiles)
+      || hasItems(payload.undoExpectedFiles)
+      || hasItems(payload.appliedOperations);
+    const canAccept = actionable && tracked;
+    const canUndo = !terminal
+      && run.undoStatus !== 'applied'
+      && (actionable ? anyRecovery : (!status && anyRecovery));
+    const failureTerminalState = normalizeTerminalState(primaryFailure?.terminalState);
+    return {
+      changedDocument: projectDocumentEffect(facts?.documentEffect, run.changedDocument),
+      primaryFailure,
+      failureTerminalState,
+      canAccept,
+      canUndo,
+      canRetry: Boolean(primaryFailure?.retryable),
+      terminalState: failureTerminalState || '',
+      actions: { accept: canAccept, undo: canUndo }
+    };
+  }
+
+  function deriveLegacyProjection(run = {}) {
+    return projectRunSettlement({ ...run, settlement: null, settlementFacts: null });
+  }
+
+  function normalizeEvidence(value = {}) {
+    const evidence = value.evidence && typeof value.evidence === 'object' ? value.evidence : {};
+    const legacySave = value.save && typeof value.save === 'object' ? value.save : {};
+    const savedCandidate = evidence.saved
+      || (legacySave.confidence === 'verified' ? 'verified'
+        : legacySave.confidence === 'quiet-observed' ? 'quiet-observed' : '');
+    return {
+      applied: allowed(evidence.applied, ['none', 'partial', 'complete', 'unknown'], 'unknown'),
+      readBack: allowed(evidence.readBack, ['not-attempted', 'exact', 'partial', 'mismatch', 'unavailable'], 'not-attempted'),
+      saved: allowed(savedCandidate, ['not-attempted', 'not-required', 'quiet-observed', 'verified', 'failed', 'unavailable'], 'not-attempted'),
+      mirrored: normalizeMirror(evidence.mirrored || value.mirror?.state),
+      compiled: normalizeCompile(evidence.compiled || value.compile?.state),
+      settled: allowed(evidence.settled, ['unsettled', 'partial', 'complete', 'needs-review'], 'unsettled')
+    };
+  }
+
+  function normalizeFiles(value) {
+    return (Array.isArray(value) ? value : []).map(file => ({
+      path: safePath(file?.path),
+      operationIds: strings(file?.operationIds, 100),
+      relatedPaths: strings(file?.relatedPaths, 20).map(safePath).filter(Boolean),
+      applied: allowed(file?.applied, ['none', 'partial', 'complete', 'failed', 'unknown'],
+        file?.applied === true ? 'complete' : 'unknown'),
+      documentEffect: normalizeDocumentEffect(file?.documentEffect),
+      readBack: normalizeReadback(file?.readBack),
+      recoveryKind: allowed(file?.recoveryKind,
+        ['tracked-changes', 'editor-history', 'legacy-baseline', 'mixed', 'none'], 'none'),
+      failureCodes: strings(file?.failureCodes, 40)
+    })).filter(file => file.path);
+  }
+
+  function normalizeFailures(value) {
+    return (Array.isArray(value) ? value : []).filter(item => item && typeof item === 'object')
+      .map(item => ({
+        code: text(item.code).slice(0, 120),
+        stage: text(item.stage).slice(0, 40),
+        severity: text(item.severity).slice(0, 40),
+        userMessage: text(item.userMessage).slice(0, 1000),
+        retryable: item.retryable === true,
+        nextAction: text(item.nextAction).slice(0, 1000),
+        file: safePath(item.file),
+        operationType: text(item.operationType).slice(0, 80),
+        changedDocument: item.changedDocument === true,
+        terminalState: normalizeTerminalState(item.terminalState)
+      }));
+  }
+
+  function normalizeDocumentEffect(value) {
+    return allowed(value === 'possible' ? 'possibly-changed' : text(value),
+      ['unchanged', 'changed', 'possibly-changed', 'unknown'], 'unknown');
+  }
+
+  function normalizeReadback(value) {
+    if (value === 'match') return 'exact';
+    if (value === 'missing' || value === 'unknown') return 'unavailable';
+    return allowed(value, ['not-attempted', 'exact', 'mismatch', 'unavailable'], 'not-attempted');
+  }
+
+  function normalizeMirror(value) {
+    if (value === 'not_started' || !value) return 'not-attempted';
+    if (value === 'pending') return 'not-attempted';
+    return allowed(value, ['not-attempted', 'complete', 'partial', 'failed', 'unknown'], 'unknown');
+  }
+
+  function normalizeCompile(value) {
+    if (value === 'success' || value === 'completed') return 'succeeded';
+    if (value === 'not_started' || !value) return 'not-attempted';
+    return allowed(value, ['not-attempted', 'succeeded', 'failed', 'unknown'], 'unknown');
+  }
+
+  function normalizeAvailability(value = {}) {
+    return {
+      trackedChanges: value?.trackedChanges === true,
+      editorHistory: value?.editorHistory === true,
+      legacyBaseline: value?.legacyBaseline === true
+    };
+  }
+
+  function normalizeDisposition(value = {}) {
+    return Object.fromEntries(RECOVERY_FIELDS.map(field => [
+      field, value?.[field] === 'clear' ? 'clear' : 'preserve'
+    ]));
+  }
+
+  function normalizeCompaction(value = {}) {
+    const omitted = value.omittedFileSettlements || {};
+    return {
+      omittedFileSettlements: {
+        failureOrRecovery: positive(omitted.failureOrRecovery),
+        changed: positive(omitted.changed),
+        unchangedOrUnknown: positive(omitted.unchangedOrUnknown)
+      },
+      omittedFailures: positive(value.omittedFailures)
+    };
+  }
+
+  function projectDocumentEffect(effect, legacy) {
+    if (effect === 'changed') return true;
+    if (effect === 'unchanged') return false;
+    if (effect === 'possibly-changed' || effect === 'unknown') return null;
+    return legacy === true ? true : legacy === false ? false : null;
+  }
+
+  function category(file = {}) {
+    if (file.failureCodes?.length || (file.recoveryKind && file.recoveryKind !== 'none')) return 'failureOrRecovery';
+    return file.documentEffect === 'changed' || file.documentEffect === 'possibly-changed'
+      ? 'changed'
+      : 'unchangedOrUnknown';
+  }
+
+  function importance(file) {
+    const value = category(file);
+    return value === 'unchangedOrUnknown' ? 1 : value === 'changed' ? 2 : 3;
+  }
+
+  function compactFailure(item = {}) {
+    const { userMessage, nextAction, ...compact } = item;
+    return compact;
+  }
+
+  function selectPrimaryFailure(failures) {
+    return DefaultFailureReasons?.selectPrimaryFailure instanceof Function
+      ? DefaultFailureReasons.selectPrimaryFailure(failures)
+      : failures[0] || null;
+  }
+
+  function normalizeTerminalState(value) {
+    return allowed(text(value), ['failed', 'blocked', 'degraded', 'needs_review'], null);
+  }
+
+  function safePath(value) {
+    const path = text(value).replace(/\\/g, '/');
+    if (!path || path.startsWith('/') || /^[A-Za-z]:\//.test(path) || path.split('/').includes('..')) return '';
+    return path.slice(0, 300);
+  }
+
+  function strings(value, limit) {
+    return (Array.isArray(value) ? value : []).map(text).filter(Boolean).slice(0, limit);
+  }
+
+  function hasItems(value) {
+    return Array.isArray(value)
+      ? value.length > 0
+      : Boolean(value && typeof value === 'object' && Object.keys(value).length);
+  }
+
+  function estimateBytes(value) {
+    const serialized = JSON.stringify(value);
+    return typeof TextEncoder !== 'undefined'
+      ? new TextEncoder().encode(serialized).length
+      : serialized.length * 2;
+  }
+
+  function cloneValue(value) {
+    try {
+      return JSON.parse(JSON.stringify(value));
+    } catch (_error) {
+      return {};
+    }
+  }
+
+  function allowed(value, values, fallback) {
+    return values.includes(value) ? value : fallback;
+  }
+
+  function positive(value) {
+    return Math.max(0, Number(value) || 0);
+  }
+
+  function text(value) {
+    return typeof value === 'string' ? value.trim() : '';
+  }
+
+  return {
+    RECOVERY_FIELDS,
+    SESSION_SETTLEMENT_DETAIL_MAX_BYTES,
+    SETTLEMENT_FACTS_MAX_BYTES,
+    compactSessionSettlementFacts,
+    compactSettlementFacts,
+    deriveLegacyProjection,
+    projectRunSettlement
+  };
+});