Retention: fill enrichment fields + page on a zero-write slot

PHASE 1 — cron capture needed NO wiring. Verified in code: the scheduler
tick calls runAll = snapshotService.runAllSnapshots, which loops
runSnapshot per sport, which already carries the onGraded -> retention
hook. The scheduled path and the manual path are the SAME function. The
reason no cron cycle had been captured is simply that no slot has fired
since retention deployed (slots are 14/19/22/1/3 UTC; retention landed
~02:55). Induced proof follows the deploy.

PHASE 2 — archetype/team/opponent were permanently null because retention
persisted at GRADE time, before enrichment attaches them. Retention still
COLLECTS at grade time (the only moment the feature vector exists) but now
PERSISTS after enrichment, merging those three fields via
retentionService.mergeEnrichment. The merge is pure and fills ONLY those
three fields — features and every model output are grade-time values and
must never be rewritten by enrichment; a test asserts that. Unmatched rows
(refusals not in the enriched slate) keep nulls rather than guesses. The
empty-slate early return now persists too: a refusal-only slate is still
history worth keeping.

PHASE 3 — ZERO-WRITE ALARM. opsWatch.retentionZeroWriteAlarm pages at
missed-snapshot severity when a slot GRADED props but retention wrote
fewer rows than the slate (or nothing). runSnapshot now returns
retentionRows so the scheduler can evaluate it. Retention is best-effort
by design so it can never break a snapshot — which means a broken write is
silent by construction. This is the counterweight. A slot that graded
nothing never false-pages; an absent count reads as NOTHING and still
pages, distinct from a reported 0.

Suite 280/3349 green, build exit 0. Outcome stamping deliberately NOT
implemented (depends on the settlement fix).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SmNjJAwEnqHPtXbvSZR8kA

tests/unit/opsWatch.test.js

@@ -239,3 +239,46 @@ describe('dateET', () => {
     expect(dateET(new Date('2026-07-11T15:00:00Z'))).toBe('2026-07-11');
   });
 });
+
+describe('retentionZeroWriteAlarm (Session 64)', () => {
+  const opsWatch = require('../../src/services/opsWatch');
+
+  test('pages when a slot graded props but retention wrote zero rows', () => {
+    const r = opsWatch.retentionZeroWriteAlarm(
+      [{ sport: 'mlb', status: 'ok', gradeCount: 7 }], { mlb: 0 });
+    expect(r.alarm).toBe(true);
+    expect(r.reason).toMatch(/MLB graded 7 but retention wrote 0/);
+  });
+
+  test('an ABSENT count reads as NOTHING, distinct from a reported 0', () => {
+    const r = opsWatch.retentionZeroWriteAlarm(
+      [{ sport: 'mlb', status: 'ok', gradeCount: 7 }], {});
+    expect(r.alarm).toBe(true);
+    expect(r.reason).toMatch(/wrote NOTHING/);
+  });
+
+  test('pages when retention wrote FEWER rows than the graded slate', () => {
+    const r = opsWatch.retentionZeroWriteAlarm(
+      [{ sport: 'wnba', status: 'ok', gradeCount: 25 }], { wnba: 4 });
+    expect(r.alarm).toBe(true);
+    expect(r.reason).toMatch(/wrote 4/);
+  });
+
+  test('quiet when retention wrote at least the slate (both sides + refusals)', () => {
+    const r = opsWatch.retentionZeroWriteAlarm(
+      [{ sport: 'mlb', status: 'ok', gradeCount: 7 }], { mlb: 50 });
+    expect(r.alarm).toBe(false);
+  });
+
+  test('a slot that graded nothing never false-pages', () => {
+    expect(opsWatch.retentionZeroWriteAlarm(
+      [{ sport: 'soccer', status: 'skipped', reason: 'no props', gradeCount: 0 }], {}).alarm).toBe(false);
+    expect(opsWatch.retentionZeroWriteAlarm(
+      [{ sport: 'mlb', status: 'ok', gradeCount: 0 }], { mlb: 0 }).alarm).toBe(false);
+  });
+
+  test('a missing/undefined count is treated as zero, not as fine', () => {
+    const r = opsWatch.retentionZeroWriteAlarm([{ sport: 'mlb', status: 'ok', gradeCount: 7 }], {});
+    expect(r.alarm).toBe(true);
+  });
+});

tests/unit/retentionService.test.js

@@ -138,3 +138,47 @@ describe('persist — best-effort contract', () => {
     await expect(retention.persist([{ a: 1 }], { getClient })).resolves.toMatchObject({ error: 'no client' });
   });
 });
+
+describe('mergeEnrichment (archetype/team/opponent were always null)', () => {
+  const rows = [
+    { player_key: 'jose ramirez', side: 'over', archetype: null, team: null, opponent: null,
+      features: { l5_avg: 0.8 }, grade: 'B', p_win: 0.61 },
+    { player_key: 'jose ramirez', side: 'under', archetype: null, team: null, opponent: null,
+      features: null, grade: null, refused: true },
+    { player_key: 'nobody here', side: 'over', archetype: null, team: null, opponent: null },
+  ];
+  const enriched = [{ player: 'José Ramírez', archetype: 'TORCH', team: 'CLE', opponent: 'NYY' }];
+
+  test('fills archetype/team/opponent from the enriched slate', () => {
+    const [a] = retention.mergeEnrichment(rows, enriched);
+    expect(a.archetype).toBe('TORCH');
+    expect(a.team).toBe('CLE');
+    expect(a.opponent).toBe('NYY');
+  });
+
+  test('NEVER mutates grade-time features or model output', () => {
+    const out = retention.mergeEnrichment(rows, enriched);
+    expect(out[0].features).toEqual({ l5_avg: 0.8 });
+    expect(out[0].grade).toBe('B');
+    expect(out[0].p_win).toBe(0.61);
+    // original array untouched (pure)
+    expect(rows[0].archetype).toBeNull();
+  });
+
+  test('refusals for a matched player still get team context', () => {
+    const out = retention.mergeEnrichment(rows, enriched);
+    expect(out[1].team).toBe('CLE');
+    expect(out[1].features).toBeNull();   // still honestly absent
+  });
+
+  test('unmatched rows stay null — never guessed', () => {
+    const out = retention.mergeEnrichment(rows, enriched);
+    expect(out[2].archetype).toBeNull();
+    expect(out[2].team).toBeNull();
+  });
+
+  test('empty/absent enrichment is a safe no-op', () => {
+    expect(retention.mergeEnrichment(rows, [])).toHaveLength(3);
+    expect(retention.mergeEnrichment([], enriched)).toEqual([]);
+  });
+});