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

src/services/snapshotService.js

@@ -312,18 +312,30 @@ async function runSnapshot(sport, opts = {}) {
     onGraded: collector ? collector.onGraded : undefined,
   });
 
-  // Persist retention BEFORE the early return on an empty slate — a slate that
-  // graded nothing but refused everything is exactly the case worth recording.
-  if (retention && collector && collector.rows.length) {
+  // Retention is COLLECTED here (grade time — features must be exactly what the
+  // model saw) but PERSISTED after enrichment below, so archetype/team/opponent
+  // are filled in. `persistRetention` is called on BOTH exits, including the
+  // empty-slate early return: a slate that graded nothing but refused
+  // everything is exactly the case worth recording.
+  let retentionRows = 0;
+  const persistRetention = async (enrichedGrades) => {
+    if (!retention || !collector || !collector.rows.length) return;
     try {
-      const r = await retention.persist(collector.rows);
+      const rows = retention.mergeEnrichment
+        ? retention.mergeEnrichment(collector.rows, enrichedGrades || [])
+        : collector.rows;
+      const r = await retention.persist(rows);
+      retentionRows = r.written || 0;
       console.log(`[snapshot] retention ${sp}: ${r.written}/${r.attempted} rows${r.skipped ? ' (skipped — no supabase env)' : ''}${r.error ? ` ERROR: ${r.error}` : ''}`);
     } catch (e) {
       console.warn(`[snapshot] retention write failed for ${sp} (snapshot continues):`, e.message);
     }
-  }
+  };
   const rawGraded = (envelope && Array.isArray(envelope.grades)) ? envelope.grades : [];
-  if (rawGraded.length === 0) return { sport: sp, status: 'skipped', reason: 'no grades', gradeCount: 0 };
+  if (rawGraded.length === 0) {
+    await persistRetention([]);   // refusal-only slate is still history
+    return { sport: sp, status: 'skipped', reason: 'no grades', gradeCount: 0 };
+  }
 
   // Session 48 — normalize player display names + dedupe variant grades at the
   // SOURCE so every consumer (GameCard, Explore, leaders, profile) gets clean,
@@ -455,6 +467,11 @@ async function runSnapshot(sport, opts = {}) {
     };
   });
 
+  // Session 64 — retention persists HERE, after enrichment, so archetype/team/
+  // opponent are populated. Feature values were captured at grade time and are
+  // NOT touched by the merge (mergeEnrichment only fills the three null fields).
+  await persistRetention(enriched);
+
   // Line deltas vs the previous snapshot's locked lines.
   const prev = await deps.cacheGet(`snapshot:${sp}:latest`);
   const deltas = computeLineDeltas(enriched, prev && prev.grades);
@@ -510,6 +527,10 @@ async function runSnapshot(sport, opts = {}) {
     status: 'ok',
     gradeCount: enriched.length,
     ledgerWritten,
+    // Session 64 — surfaced so the scheduler can page when retention silently
+    // writes nothing. Retention is best-effort by design, which makes a broken
+    // write invisible without this.
+    retentionRows,
     topGrades: enriched.filter((g) => isTopGrade(g.grade)).slice(0, 5).map((g) => ({
       player: g.player || g.player_name, stat: g.stat_type || g.stat, grade: g.grade, archetype: g.archetype,
     })),