SRCmail/lib/offline-replica/__tests__/retention.test.ts

// The clock-jump guard, and the wipe it caused on the mobile client.
//
// The bug being regressed here is not hypothetical: its reproduction on the mobile
// side returned 0 envelopes from a 4-envelope store. The guard DETECTED the jump,
// held the old floor for one cycle - and persisted the JUMPED floor. The next
// chained cycle seconds later computed a floor within seconds of the persisted
// one, so the guard passed, the movement was classified as a NARROW, and every
// envelope below a floor a year in the future was evicted. Unrecoverable, because
// `coveredFrom` then claims the range complete and `/changes` cannot re-deliver
// pre-existing mail.

import { describe, expect, it } from 'vitest';
import {
  adjustForWindow, CLOCK_JUMP_GUARD_MS, computeFloors, floorMovement,
  guardFloorAgainstClockJump,
} from '../retention';

const DAY = 24 * 60 * 60 * 1000;
const T0 = Date.parse('2026-08-05T12:00:00.000Z');

function iso(t: number): string {
  return new Date(t).toISOString();
}

describe('computeFloors', () => {
  it('never lets the body window be wider than the envelope window', () => {
    // A body with no envelope is an orphan by construction, and the whole point of
    // two tiers is envelopes being a superset of bodies.
    const floors = computeFloors({ envelopeDays: 30, bodyDays: 365, maxBodyMB: 100 }, T0);
    expect(floors.bodyFrom).toBe(floors.envelopeFrom);
  });

  it('turns the MB cap into bytes', () => {
    expect(computeFloors({ envelopeDays: 1, bodyDays: 1, maxBodyMB: 2 }, T0).maxBodyBytes)
      .toBe(2 * 1024 * 1024);
  });
});

describe('guardFloorAgainstClockJump', () => {
  it('adopts the computed floor when there is no history to compare against', () => {
    const g = guardFloorAgainstClockJump(iso(T0), undefined);
    expect(g.suppressed).toBe(false);
    expect(g.evictionAllowed).toBe(true);
    expect(g.envelopeFrom).toBe(iso(T0));
  });

  it('adopts an ordinary drift - a DST shift must not trip it', () => {
    const g = guardFloorAgainstClockJump(iso(T0 + 60 * 60 * 1000), iso(T0));
    expect(g.suppressed).toBe(false);
    expect(g.evictionAllowed).toBe(true);
  });

  it('suppresses a jump larger than the guard and refuses to authorise deletion', () => {
    const jumped = iso(T0 + 365 * DAY);
    const g = guardFloorAgainstClockJump(jumped, iso(T0));
    expect(g.suppressed).toBe(true);
    expect(g.envelopeFrom).toBe(iso(T0));
    // Suppressing the FLOOR is not the same as suppressing the DELETIONS the
    // floor authorises. Both the retention eviction and the reconcile sweep read
    // this bit.
    expect(g.evictionAllowed).toBe(false);
    expect(g.warning).toBeTruthy();
  });

  it('THE H2 REGRESSION: persists the floor it USED, not the one it rejected', () => {
    // This one assertion is the whole fix. Persisting the computed value here is
    // what legitimised the anomaly on the very next cycle.
    const jumped = iso(T0 + 365 * DAY);
    const g = guardFloorAgainstClockJump(jumped, iso(T0));
    expect(g.nextLastWindowFloor).toBe(iso(T0));
    expect(g.nextLastWindowFloor).not.toBe(jumped);
  });

  it('THE H2 REGRESSION: stays suppressed across MANY chained cycles', () => {
    // The original bug only showed on the SECOND cycle, so a single-cycle test
    // passes against the broken code. Chaining is what reproduces it.
    const stored = iso(T0);
    let lastWindowFloor: string | undefined = stored;
    for (let cycle = 0; cycle < 20; cycle++) {
      // The clock is a year ahead and creeping forward a few seconds per cycle,
      // exactly as a chained sync would observe it.
      const computed = iso(T0 + 365 * DAY + cycle * 5_000);
      const g = guardFloorAgainstClockJump(computed, lastWindowFloor);
      expect(g.suppressed, `cycle ${cycle} must stay suppressed`).toBe(true);
      expect(g.evictionAllowed, `cycle ${cycle} must not authorise deletion`).toBe(false);
      expect(g.envelopeFrom, `cycle ${cycle} must keep the original floor`).toBe(stored);
      lastWindowFloor = g.nextLastWindowFloor;
    }
    // And after 20 cycles the remembered floor is still the trustworthy one, so
    // no later cycle can classify it as a narrow and evict everything.
    expect(lastWindowFloor).toBe(stored);
    expect(floorMovement(lastWindowFloor, stored)).toBe('unchanged');
    expect(adjustForWindow(floorMovement(lastWindowFloor, stored), stored).evictBelow)
      .toBeUndefined();
  });

  it('suppresses a BACKWARD jump too', () => {
    const g = guardFloorAgainstClockJump(iso(T0 - 365 * DAY), iso(T0));
    expect(g.suppressed).toBe(true);
    expect(g.evictionAllowed).toBe(false);
  });

  it('treats an explicit retention change as INTENT and applies it, eviction included', () => {
    // The computed floor moves for two independent reasons - the clock changing
    // and the SETTING changing - and guarding a setting change is wrong. Without
    // this discriminator a Settings edit sits unapplied until something unrelated
    // moves the floor again.
    const widened = iso(T0 - 365 * DAY);
    const g = guardFloorAgainstClockJump(widened, iso(T0), { policyChanged: true });
    expect(g.suppressed).toBe(false);
    expect(g.evictionAllowed).toBe(true);
    expect(g.envelopeFrom).toBe(widened);
    expect(g.nextLastWindowFloor).toBe(widened);
  });

  it('a genuine user NARROW still evicts', () => {
    // The guard must not become a reason nothing is ever deleted.
    const narrowed = iso(T0 + 20 * 60 * 60 * 1000);
    const g = guardFloorAgainstClockJump(narrowed, iso(T0));
    expect(g.evictionAllowed).toBe(true);
    expect(floorMovement(iso(T0), g.envelopeFrom)).toBe('narrowed');
    expect(adjustForWindow('narrowed', g.envelopeFrom).evictBelow).toBe(narrowed);
  });

  it('tolerates an unparseable stored floor without wedging', () => {
    const g = guardFloorAgainstClockJump(iso(T0), 'garbage');
    // Date.parse('garbage') is NaN, so the delta is not finite: adopt rather than
    // suppress forever on a corrupt value.
    expect(g.suppressed).toBe(false);
  });

  it('uses a threshold above a day so a leap second or NTP nudge is invisible', () => {
    expect(CLOCK_JUMP_GUARD_MS).toBeGreaterThan(DAY);
  });
});

describe('floorMovement / adjustForWindow', () => {
  it('a LATER floor keeps less mail and means evict', () => {
    expect(floorMovement(iso(T0), iso(T0 + DAY))).toBe('narrowed');
    expect(adjustForWindow('narrowed', iso(T0 + DAY))).toEqual({ evictBelow: iso(T0 + DAY) });
  });

  it('an EARLIER floor means re-scan, NOT a resync', () => {
    // A widen moves the target back and re-enters coverage scanning. The cursors
    // are untouched - a widen is not a reason to rebuild.
    expect(floorMovement(iso(T0), iso(T0 - DAY))).toBe('widened');
    expect(adjustForWindow('widened', iso(T0 - DAY))).toEqual({ rescanFrom: iso(T0 - DAY) });
  });

  it('does nothing without a previous floor', () => {
    expect(floorMovement(undefined, iso(T0))).toBe('unchanged');
    expect(adjustForWindow('unchanged', iso(T0))).toEqual({});
  });
});