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

import fs from 'node:fs';
import path from 'node:path';
import { describe, expect, it } from 'vitest';
import {
  asChangesState, asSnapshotState, coveragePhaseForCommitment, mintEnumerationCommitment,
} from '../states';

describe('state token certification', () => {
  it('rejects everything a parsed JSON body could hand over that is not a token', () => {
    // The brand certifies PROVENANCE; this check certifies SHAPE. Without it a
    // `null` or a number could be laundered into something the engine treats as a
    // cursor forever.
    for (const bad of [null, undefined, 0, 1, '', {}, [], true]) {
      expect(() => asChangesState(bad)).toThrow(TypeError);
      expect(() => asSnapshotState(bad)).toThrow(TypeError);
    }
  });

  it('accepts a non-empty string', () => {
    expect(asChangesState('s1')).toBe('s1');
    expect(asSnapshotState('s1')).toBe('s1');
  });
});

describe('EnumerationCommitment', () => {
  it('is constructible - the symbol tag must be a real runtime Symbol', () => {
    // `declare const tag: unique symbol` is type-level only and emits no runtime
    // value, so using it as a computed key throws ReferenceError the first time
    // the mint runs. That mistake is in the superseded design document; this test
    // is what catches it.
    const commitment = mintEnumerationCommitment({
      jmapAccountId: 'a',
      snapshot: asSnapshotState('snap'),
      targetFrom: '2026-01-01T00:00:00.000Z',
      sweepFloor: '2026-01-01T00:00:00.000Z',
      kind: 'bootstrap',
    });
    expect(commitment.snapshot).toBe('snap');
    expect(commitment.kind).toBe('bootstrap');
  });

  it('maps its kind onto the coverage phase', () => {
    const base = {
      jmapAccountId: 'a',
      snapshot: asSnapshotState('snap'),
      targetFrom: 'x',
      sweepFloor: 'x',
    } as const;
    expect(coveragePhaseForCommitment(mintEnumerationCommitment({ ...base, kind: 'bootstrap' })))
      .toBe('scanning');
    expect(coveragePhaseForCommitment(mintEnumerationCommitment({ ...base, kind: 'reconcile' })))
      .toBe('reconciling');
  });

  it('does not export its tag, so no object literal elsewhere can forge the type', () => {
    const source = fs.readFileSync(path.join(__dirname, '..', 'states.ts'), 'utf8');
    expect(source).toContain("const enumerationCommitmentTag = Symbol('EnumerationCommitment')");
    expect(source).not.toMatch(/export\s+(const|let)\s+enumerationCommitmentTag/);
    // And it must be a real Symbol() call, not the type-only declaration form.
    expect(source).not.toMatch(/declare\s+const\s+enumerationCommitmentTag/);
  });
});

describe('cursor provenance is greppable, not just documented', () => {
  const replicaDir = path.join(__dirname, '..');

  function sourceFiles(): string[] {
    return fs
      .readdirSync(replicaDir)
      .filter((f) => f.endsWith('.ts'))
      .map((f) => path.join(replicaDir, f));
  }

  it('mints branded states ONLY in jmap.ts (the response parser)', () => {
    // This is the rule the whole brand exists to enforce. The mobile client's
    // defect D4 was a snapshot state adopted as a /changes cursor after a
    // transient 503; a cast anywhere outside the parser is how that comes back.
    for (const file of sourceFiles()) {
      const base = path.basename(file);
      if (base === 'states.ts' || base === 'jmap.ts') continue;
      const source = fs.readFileSync(file, 'utf8');
      expect(source, `${base} must not mint a ChangesState`).not.toMatch(/asChangesState\s*\(/);
      expect(source, `${base} must not mint a SnapshotState`).not.toMatch(/asSnapshotState\s*\(/);
      expect(source, `${base} must not cast to a branded state`).not.toMatch(
        /as\s+(ChangesState|SnapshotState)\b/,
      );
    }
  });

  it('mints an EnumerationCommitment ONLY where an enumeration is actually started', () => {
    // A commitment is a promise to enumerate. Minting one anywhere that does not
    // then enumerate makes the seed path's teeth meaningless.
    const callers = sourceFiles().filter((file) => {
      if (path.basename(file) === 'states.ts') return false;
      return /mintEnumerationCommitment\s*\(/.test(fs.readFileSync(file, 'utf8'));
    });
    expect(callers.map((f) => path.basename(f))).toEqual(['sync.ts']);
  });
});