Enumify StalenessStatus and StalenessTier

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: ronshapiro

precomputed/rsi_state/staleness.test.ts

@@ -6,6 +6,8 @@ import {
   editDistance,
   hashNormalizedText,
   resolveWithClassification,
+  StalenessStatus,
+  StalenessTier,
 } from "./staleness";
 
 test("editDistance is 0 for identical strings", () => {
@@ -41,24 +43,24 @@ test("hashNormalizedText differs on a real word change", () => {
 
 test("checkTextStaleness Tier 0: cosmetic-only change (punctuation/whitespace) is fresh", () => {
   const result = checkTextStaleness("שלום, עולם!", "שלום עולם");
-  expect(result).toEqual({status: "fresh", tier: 0});
+  expect(result).toEqual({status: StalenessStatus.Fresh, tier: StalenessTier.Fingerprint});
 });
 
 test("checkTextStaleness Tier 1: small real edit under the cosmetic threshold is fresh", () => {
   const stored = "a".repeat(100);
   const current = `${"a".repeat(97)}bbb`; // ~3% edit ratio once padded — see ratio math below
   const result = checkTextStaleness(stored, current, DEFAULT_STALENESS_THRESHOLDS);
-  expect(result.tier).toBe(1);
-  expect(result.status).toBe("fresh");
+  expect(result.tier).toBe(StalenessTier.EditDistance);
+  expect(result.status).toBe(StalenessStatus.Fresh);
   expect(result.editRatio).toBeLessThanOrEqual(DEFAULT_STALENESS_THRESHOLDS.cosmeticMaxRatio);
 });
 
 test("checkTextStaleness Tier 2: mid-range edit needs classification", () => {
   const stored = "The quick brown fox jumps over the lazy dog and keeps running";
   const current = "The quick brown fox leaps over the lazy dog and keeps walking";
   const result = checkTextStaleness(stored, current, DEFAULT_STALENESS_THRESHOLDS);
-  expect(result.status).toBe("needsClassification");
-  expect(result.tier).toBe(2);
+  expect(result.status).toBe(StalenessStatus.NeedsClassification);
+  expect(result.tier).toBe(StalenessTier.AgenticClassification);
   expect(result.editRatio).toBeGreaterThan(DEFAULT_STALENESS_THRESHOLDS.cosmeticMaxRatio);
   expect(result.editRatio).toBeLessThan(DEFAULT_STALENESS_THRESHOLDS.structuralMinRatio);
 });
@@ -69,20 +71,19 @@ test("checkTextStaleness Tier 3: large rewrite is stale without classification",
     "Completely different content that shares almost nothing with before.",
     DEFAULT_STALENESS_THRESHOLDS,
   );
-  expect(result.status).toBe("stale");
-  expect(result.tier).toBe(3);
+  expect(result.status).toBe(StalenessStatus.Stale);
+  expect(result.tier).toBe(StalenessTier.StructuralBreak);
 });
 
 test("resolveWithClassification marks stillValid as fresh at tier 2", () => {
   const pending = checkTextStaleness(
     "The quick brown fox jumps over the lazy dog and keeps running",
-    "The quick brown fox leaps over the lazy dog and keeps walking",
-  );
+    "The quick brown fox leaps over the lazy dog and keeps walking");
   const resolved = resolveWithClassification(
     pending, {stillValid: true, reason: "meaning preserved"});
   expect(resolved).toEqual({
-    status: "fresh",
-    tier: 2,
+    status: StalenessStatus.Fresh,
+    tier: StalenessTier.AgenticClassification,
     editRatio: pending.editRatio,
     reason: "meaning preserved",
   });
@@ -91,11 +92,10 @@ test("resolveWithClassification marks stillValid as fresh at tier 2", () => {
 test("resolveWithClassification marks !stillValid as stale at tier 2", () => {
   const pending = checkTextStaleness(
     "The quick brown fox jumps over the lazy dog and keeps running",
-    "The quick brown fox leaps over the lazy dog and keeps walking",
-  );
+    "The quick brown fox leaps over the lazy dog and keeps walking");
   const resolved = resolveWithClassification(
     pending, {stillValid: false, reason: "meaning changed"});
-  expect(resolved.status).toBe("stale");
+  expect(resolved.status).toBe(StalenessStatus.Stale);
 });
 
 test("resolveWithClassification throws when called on a non-pending result", () => {
@@ -105,13 +105,14 @@ test("resolveWithClassification throws when called on a non-pending result", ()
 });
 
 test("checkSegmentCountStaleness: unchanged count is fresh", () => {
-  expect(checkSegmentCountStaleness(5, 5)).toEqual({status: "fresh", tier: 0});
+  expect(checkSegmentCountStaleness(5, 5))
+    .toEqual({status: StalenessStatus.Fresh, tier: StalenessTier.Fingerprint});
 });
 
 test("checkSegmentCountStaleness: changed count is a Tier 3 structural break", () => {
   const result = checkSegmentCountStaleness(5, 6);
-  expect(result.status).toBe("stale");
-  expect(result.tier).toBe(3);
+  expect(result.status).toBe(StalenessStatus.Stale);
+  expect(result.tier).toBe(StalenessTier.StructuralBreak);
   expect(result.reason).toContain("5");
   expect(result.reason).toContain("6");
 });

precomputed/rsi_state/staleness.ts

@@ -26,11 +26,22 @@ function normalizeForStalenessFingerprint(text: string): string {
     .trim();
 }
 
-export type StalenessStatus = "fresh" | "stale" | "needsClassification";
+export enum StalenessStatus {
+  Fresh = "fresh",
+  Stale = "stale",
+  NeedsClassification = "needsClassification",
+}
+
+export enum StalenessTier {
+  Fingerprint = 0,
+  EditDistance = 1,
+  AgenticClassification = 2,
+  StructuralBreak = 3,
+}
 
 export interface StalenessResult {
   status: StalenessStatus;
-  tier: 0 | 1 | 2 | 3;
+  tier: StalenessTier;
   editRatio?: number;
   reason?: string;
 }
@@ -99,17 +110,26 @@ export function checkTextStaleness(
   thresholds: StalenessThresholds = DEFAULT_STALENESS_THRESHOLDS,
 ): StalenessResult {
   if (hashNormalizedText(currentSourceText) === hashNormalizedText(storedSourceText)) {
-    return {status: "fresh", tier: 0};
+    return {status: StalenessStatus.Fresh, tier: StalenessTier.Fingerprint};
   }
 
   const editRatio = computeEditRatio(storedSourceText, currentSourceText);
   if (editRatio <= thresholds.cosmeticMaxRatio) {
-    return {status: "fresh", tier: 1, editRatio};
+    return {status: StalenessStatus.Fresh, tier: StalenessTier.EditDistance, editRatio};
   }
   if (editRatio >= thresholds.structuralMinRatio) {
-    return {status: "stale", tier: 3, editRatio, reason: "edit ratio above structural threshold"};
+    return {
+      status: StalenessStatus.Stale,
+      tier: StalenessTier.StructuralBreak,
+      editRatio,
+      reason: "edit ratio above structural threshold",
+    };
   }
-  return {status: "needsClassification", tier: 2, editRatio};
+  return {
+    status: StalenessStatus.NeedsClassification,
+    tier: StalenessTier.AgenticClassification,
+    editRatio,
+  };
 }
 
 /**
@@ -123,13 +143,13 @@ export function resolveWithClassification(
   pending: StalenessResult,
   classifierVerdict: {stillValid: boolean; reason: string},
 ): StalenessResult {
-  if (pending.status !== "needsClassification") {
+  if (pending.status !== StalenessStatus.NeedsClassification) {
     throw new Error(`resolveWithClassification called on a tier-${pending.tier} result that `
       + `wasn't needsClassification`);
   }
   return {
-    status: classifierVerdict.stillValid ? "fresh" : "stale",
-    tier: 2,
+    status: classifierVerdict.stillValid ? StalenessStatus.Fresh : StalenessStatus.Stale,
+    tier: StalenessTier.AgenticClassification,
     editRatio: pending.editRatio,
     reason: classifierVerdict.reason,
   };
@@ -145,11 +165,11 @@ export function checkSegmentCountStaleness(
   currentSegmentCount: number,
 ): StalenessResult {
   if (storedSegmentCount === currentSegmentCount) {
-    return {status: "fresh", tier: 0};
+    return {status: StalenessStatus.Fresh, tier: StalenessTier.Fingerprint};
   }
   return {
-    status: "stale",
-    tier: 3,
+    status: StalenessStatus.Stale,
+    tier: StalenessTier.StructuralBreak,
     reason: `segment count changed from ${storedSegmentCount} to ${currentSegmentCount}`,
   };
 }

rsi_orchestrator/rashi_tosafot_translation.ts

@@ -5,7 +5,11 @@ import {cachedOutputFilePath} from "../cached_outputs";
 import {readUtf8} from "../files";
 import {Edit} from "../precomputed/ai_edits";
 import {readGenerationRecord, upsertGenerationRecord} from "../precomputed/rsi_state/generation_record";
-import {checkTextStaleness, DEFAULT_STALENESS_THRESHOLDS} from "../precomputed/rsi_state/staleness";
+import {
+  checkTextStaleness,
+  DEFAULT_STALENESS_THRESHOLDS,
+  StalenessStatus,
+} from "../precomputed/rsi_state/staleness";
 import {toFlatArray} from "../sefariaTextType";
 import {HeadlessClaudeError, runHeadlessClaude} from "./headless_claude";
 
@@ -141,7 +145,7 @@ export function isFreshTranslation(candidate: TranslationCandidate): boolean {
   if (!record) return false;
   const result = checkTextStaleness(
     record.sourceText, candidate.hebrewSource, DEFAULT_STALENESS_THRESHOLDS);
-  return result.status === "fresh";
+  return result.status === StalenessStatus.Fresh;
 }
 
 function generationPrompt(candidate: TranslationCandidate, priorFeedback?: string): string {