Build 1: the settled/live gate — unresolved is paid, resolved is free

Serving/gating change only. src/services/ untouched (git diff empty): no grade,
model or settlement-logic change. Pricing and migration are Builds 2 and 3.
Push scoring untouched.

THE RULE: a grade is PAID while its outcome is unknown and becomes FREE the
moment it resolves.

Resolution is read ONLY from a written outcome — never from time, game status or
gradedAt. A game can be final long before the settle pass runs, so treating
"probably over" as settled is exactly how a live edge would leak; a test asserts
an hours-old gradedAt with no outcome is still LIVE. void and unrecoverable ARE
resolutions (terminal results, no live edge left). isResolved FAILS CLOSED:
null outcome, {} with no result, and empty-string result all read as LIVE, so a
settlement failure withholds content rather than exposing it — the same
direction resolveTierFromRequest fails.

FREE/ANON: settled grades pass through IN FULL, reasoning and kill conditions
included — settled reads are the proof product and cost nothing once the outcome
is known. That also converts the previously-unenforced board reasoning leak into
a deliberate rule rather than an oversight.

LIVE grades for unentitled tiers are reduced to a shell: every piece of model
JUDGMENT is dropped (grade, confidence, confidence_basis, reasoning,
kill_conditions_triggered, projection, edge_pct, matchup_grade, form, alt_lines,
kelly) and `locked: true` is stamped so the card renders the unlock prompt. The
free-side DATA stays so the tease is real rather than empty: player, market,
line, book_odds, fair_odds, season/last10 stats, archetype, gradedAt, history.
fair_odds deliberately survives — the de-vigged fair number is the free hook and
is never the paywall. A test asserts the serialized free row carries no trace of
the withheld judgment.

THE TEASE IS AGGREGATE ONLY: live_locked = {count, tiers} computed from the
ungated rows and never joined back to one, and no gated row carries a grade — so
a free viewer learns that N reads exist and their tier shape without being able
to work out WHICH prop is the A.

Gate order in the route: stripModelPrice (S67) first, then gateLiveGrades.
Entitled tiers get the array back by reference — zero cost, zero change.

Floor: 319 suites / 3971 tests green (10 new), web build exit 0.

One test note: the route-level supertest case was removed deliberately — it
needs a live Redis and hangs on ioredis' reconnect timer in a single-suite local
run (known behaviour, CLAUDE.md). The gate contract is fully covered by pure
tests; the wire is verified against prod anonymously in the fingerprint.

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

src/routes/snapshot.js

@@ -19,7 +19,7 @@ const { indexRosterLogs, attachLast10Dots } = require('../services/last10Dots');
 // Session 67 — the model price never leaves the server for an unentitled
 // viewer. This endpoint is PUBLIC, so the Session-66 gate on /api/analyze was
 // being bypassed here on every graded row. Same layer as the CLV gate.
-const { stripModelPrice } = require('../utils/snapshotGating');
+const { stripModelPrice, gateLiveGrades, liveLockedSummary, entitledToLiveGrades } = require('../utils/snapshotGating');
 const { resolveTierFromRequest } = require('../utils/requestTier');
 
 const router = express.Router();
@@ -104,7 +104,15 @@ router.get('/:sport', async (req, res) => {
     // downgraded to `private` for authenticated callers — a CDN must never
     // hand a paid payload to an anonymous viewer.
     const tier = await resolveTierFromRequest(req);
-    const gate = (grades) => stripModelPrice(grades, tier);
+    // BUILD 1 (2026-07-31) — THE SETTLED/LIVE GATE. Order matters: strip the model
+    // PRICE first (S67), then withhold tonight's live JUDGMENT for unentitled tiers.
+    // A RESOLVED grade passes through in full — reasoning included — because settled
+    // reads are the free proof product and cost nothing once the outcome is known.
+    const gate = (grades) => gateLiveGrades(stripModelPrice(grades, tier), tier);
+    // The tease is an AGGREGATE ONLY (count + tier shape). It is computed from the
+    // ungated rows and never joined back to one, so a free viewer can see that N
+    // reads exist and their distribution without learning WHICH prop is the A.
+    const teaseFor = (grades) => (entitledToLiveGrades(tier) ? null : liveLockedSummary(grades));
     const cacheHeader = req.headers.authorization ? 'private, max-age=30' : 'public, max-age=30';
     const [snap, outcomeLog, rosterBlob] = await Promise.all([
       cacheGet(`snapshot:${sport}:latest`),
@@ -116,13 +124,15 @@ router.get('/:sport', async (req, res) => {
     const enrich = (grades) => attachLast10Dots(attachOutcomes(grades, idx), roster, sport);
     if (snap && Array.isArray(snap.grades)) {
       res.set('Cache-Control', cacheHeader);
-      return res.json({ sport, updated_at: snap.updated_at, refreshed_at: snap.refreshed_at || snap.updated_at || null, grades: gate(enrich(snap.grades)), deltas: snap.deltas || [] });
+      const enrichedSnap = enrich(snap.grades);
+      return res.json({ sport, updated_at: snap.updated_at, refreshed_at: snap.refreshed_at || snap.updated_at || null, grades: gate(enrichedSnap), deltas: snap.deltas || [], live_locked: teaseFor(enrichedSnap) });
     }
     // Fallback: the grades envelope (no deltas yet).
     const env = await cacheGet(`grades:${sport}`);
     const grades = env && Array.isArray(env.grades) ? env.grades : [];
     res.set('Cache-Control', cacheHeader);
-    return res.json({ sport, updated_at: env && env.updated_at, grades: gate(enrich(grades)), deltas: [] });
+    const enrichedEnv = enrich(grades);
+    return res.json({ sport, updated_at: env && env.updated_at, grades: gate(enrichedEnv), deltas: [], live_locked: teaseFor(enrichedEnv) });
   } catch (err) {
     console.error('[snapshot]', err.message);
     return res.status(200).json({ sport, grades: [], deltas: [] });

src/utils/snapshotGating.js

@@ -70,3 +70,89 @@ module.exports = {
   entitledToModelPrice,
   stripModelPrice,
 };
+
+/* ===========================================================================
+ * BUILD 1 — THE SETTLED/LIVE GATE (2026-07-31, specs/tier-redesign-spec.md)
+ *
+ * THE RULE: a grade is PAID while its outcome is unknown, and becomes FREE the
+ * moment it resolves. Resolution is the flip point, and it is read ONLY from a
+ * written outcome — never from time, game status or `gradedAt`. A game can be
+ * final long before the settle pass runs, so "probably over" is exactly how a
+ * live edge would leak.
+ *
+ * FAIL CLOSED: anything we cannot prove is resolved is treated as LIVE (paid).
+ * A settlement failure therefore WITHHOLDS content rather than exposing it —
+ * the same direction `resolveTierFromRequest` fails.
+ *
+ * THE LOCKED SHELL: an unentitled viewer still sees that tonight's reads EXIST
+ * and their shape — player, market, line, the real book/fair prices, the stats
+ * anyone can already get free — plus an AGGREGATE count and tier distribution.
+ * What is withheld is the model's JUDGMENT. And the distribution is aggregate
+ * ONLY: per-row tier is never emitted, so no one can work out WHICH prop is the A.
+ * ========================================================================= */
+
+/** Model JUDGMENT on a live read. Data stays; the verdict and its argument go. */
+const LIVE_JUDGMENT_FIELDS = Object.freeze([
+  'grade', 'confidence', 'confidence_basis',   // the verdict
+  'reasoning', 'kill_conditions_triggered',    // its argument
+  'projection', 'edge_pct',                    // our number vs the line
+  'matchup_grade', 'form',                     // derived letter/label judgments
+  'alt_lines', 'kelly',                        // Desk tools
+]);
+
+/**
+ * A grade is RESOLVED only when a real outcome is written on it. `void` and
+ * `unrecoverable` ARE resolutions (terminal results, no live edge left).
+ */
+function isResolved(g) {
+  if (!g || typeof g !== 'object') return false;
+  const o = g.outcome;
+  if (!o) return false;
+  if (typeof o === 'string') return o.trim() !== '';
+  return typeof o === 'object' && typeof o.result === 'string' && o.result.trim() !== '';
+}
+
+/** Does this tier get tonight's live reads? (free/anon: no) */
+function entitledToLiveGrades(tierName) {
+  return canAccess(tierName, 'reasoning_visible');
+}
+
+/**
+ * The aggregate tease: how many live reads exist and their tier shape.
+ * Aggregate ONLY — never joined back to a row.
+ */
+function liveLockedSummary(grades) {
+  const live = (Array.isArray(grades) ? grades : []).filter((g) => g && !isResolved(g));
+  const tiers = {};
+  for (const g of live) {
+    const letter = String((g.grade || '')).trim().toUpperCase().charAt(0);
+    if (!letter) continue;
+    tiers[letter] = (tiers[letter] || 0) + 1;
+  }
+  return { count: live.length, tiers };
+}
+
+/**
+ * gateLiveGrades(grades, tierName) — entitled tiers pass through untouched.
+ * Unentitled: resolved grades pass FULL (including reasoning — settled is the
+ * proof product and costs nothing post-resolution); unresolved grades are
+ * reduced to the shell.
+ */
+function gateLiveGrades(grades, tierName) {
+  if (!Array.isArray(grades)) return grades;
+  if (entitledToLiveGrades(tierName)) return grades;
+  return grades.map((g) => {
+    if (!g || typeof g !== 'object') return g;
+    if (isResolved(g)) return g;                 // settled ⇒ free, in full
+    const shell = { ...g };
+    for (const f of LIVE_JUDGMENT_FIELDS) delete shell[f];
+    shell.locked = true;                         // the card renders the unlock prompt
+    return shell;
+  });
+}
+
+module.exports.LIVE_JUDGMENT_FIELDS = LIVE_JUDGMENT_FIELDS;
+module.exports.isResolved = isResolved;
+module.exports.entitledToLiveGrades = entitledToLiveGrades;
+module.exports.liveLockedSummary = liveLockedSummary;
+module.exports.gateLiveGrades = gateLiveGrades;

tests/unit/settledLiveGate.test.js

@@ -0,0 +1,101 @@
+/**
+ * BUILD 1 — the settled/live gate (specs/tier-redesign-spec.md).
+ * The load-bearing monetization boundary: unresolved = paid, resolved = free.
+ */
+const request = require('supertest');
+const g = require('../../src/utils/snapshotGating');
+
+const settled = { player: 'Settled Sam', stat_type: 'points', line: 12.5, book_odds: -110, fair_odds: -104,
+  season_avg: 14, grade: 'A', confidence: 75, reasoning: { summary: 'real why' },
+  kill_conditions_triggered: [{ code: 'X', reason: 'r' }], projection: 15, edge_pct: 20,
+  outcome: { result: 'hit', actual: 14 } };
+const live = { player: 'Live Larry', stat_type: 'assists', line: 5.5, book_odds: -120, fair_odds: -112,
+  season_avg: 6, archetype: { primary: { name: 'CONDUCTOR' } }, gradedAt: { line: 5.5, odds: -120 },
+  grade: 'A', confidence: 75, confidence_basis: 'grade_band', reasoning: { summary: 'secret why' },
+  kill_conditions_triggered: [{ code: 'Y', reason: 'secret' }], projection: 7.1, edge_pct: 29,
+  matchup_grade: 'B', form: 'hot', alt_lines: [{}], kelly: { units: 1 } };
+
+describe('resolution is the flip point — and only a WRITTEN outcome counts', () => {
+  test('a real outcome resolves; void/unrecoverable are terminal ⇒ resolved', () => {
+    expect(g.isResolved(settled)).toBe(true);
+    expect(g.isResolved({ outcome: { result: 'void' } })).toBe(true);
+    expect(g.isResolved({ outcome: 'unrecoverable' })).toBe(true);
+  });
+
+  test('FAILS CLOSED — anything unproven is LIVE (paid), never assumed settled', () => {
+    expect(g.isResolved(live)).toBe(false);
+    expect(g.isResolved({ outcome: null })).toBe(false);
+    expect(g.isResolved({ outcome: {} })).toBe(false);          // no result field
+    expect(g.isResolved({ outcome: { result: '' } })).toBe(false);
+    expect(g.isResolved({})).toBe(false);
+    expect(g.isResolved(null)).toBe(false);
+  });
+
+  test('resolution is NEVER inferred from time or game status', () => {
+    // a grade locked hours ago with no outcome is still LIVE
+    expect(g.isResolved({ gradedAt: { timestamp: '2020-01-01T00:00:00Z' } })).toBe(false);
+  });
+});
+
+describe('free tier — settled is FULL, live is a shell', () => {
+  const out = g.gateLiveGrades([settled, live], 'free');
+
+  test('a SETTLED grade passes through in full, reasoning included (the proof product)', () => {
+    expect(out[0].grade).toBe('A');
+    expect(out[0].reasoning.summary).toBe('real why');
+    expect(out[0].kill_conditions_triggered).toHaveLength(1);
+    expect(out[0].edge_pct).toBe(20);
+    expect(out[0].projection).toBe(15);
+  });
+
+  test('a LIVE grade loses every piece of model JUDGMENT', () => {
+    for (const f of ['grade', 'confidence', 'confidence_basis', 'reasoning', 'kill_conditions_triggered',
+      'projection', 'edge_pct', 'matchup_grade', 'form', 'alt_lines', 'kelly']) {
+      expect(out[1][f]).toBeUndefined();
+    }
+    expect(out[1].locked).toBe(true);
+  });
+
+  test('a LIVE grade KEEPS the free-side data (the tease is real, not empty)', () => {
+    expect(out[1].player).toBe('Live Larry');
+    expect(out[1].stat_type).toBe('assists');
+    expect(out[1].line).toBe(5.5);
+    expect(out[1].book_odds).toBe(-120);
+    expect(out[1].fair_odds).toBe(-112);      // the fair leg is NEVER the paywall
+    expect(out[1].season_avg).toBe(6);
+    expect(out[1].archetype).toBeTruthy();
+  });
+
+  test('the serialized free payload contains no trace of live judgment', () => {
+    const json = JSON.stringify(out[1]);
+    expect(json).not.toMatch(/secret why|secret|grade_band|hot/);
+  });
+});
+
+describe('the tease is AGGREGATE ONLY — never which prop is which tier', () => {
+  test('reports count + tier distribution', () => {
+    const s = g.liveLockedSummary([settled, live, { grade: 'B' }, { grade: 'C' }]);
+    expect(s.count).toBe(3);                 // settled excluded from the live count
+    expect(s.tiers).toEqual({ A: 1, B: 1, C: 1 });
+  });
+
+  test('no gated ROW carries a tier, so the aggregate cannot be joined back', () => {
+    const out = g.gateLiveGrades([live, { player: 'P2', grade: 'B' }], 'free');
+    for (const row of out) expect(row.grade).toBeUndefined();
+  });
+});
+
+describe('entitled tiers are untouched', () => {
+  test('analyst and desk get the array back by reference — zero cost, zero change', () => {
+    const rows = [settled, live];
+    expect(g.gateLiveGrades(rows, 'analyst')).toBe(rows);
+    expect(g.gateLiveGrades(rows, 'desk')).toBe(rows);
+    expect(g.entitledToLiveGrades('free')).toBe(false);
+    expect(g.entitledToLiveGrades(undefined)).toBe(false);   // anonymous
+  });
+});
+
+// NOTE: the route-level assertion is deliberately NOT here. It needs a live Redis,
+// and a single-suite run with redis down hangs on ioredis' reconnect timer (a known
+// local behaviour, see CLAUDE.md). The gate's CONTRACT is fully covered by the pure
+// tests above; the wire is verified against PROD anonymously in the fingerprint.