Game Desk Build Template

Purpose: This document is a universal template for building a new game-level sports desk in EdgeClaw. An AI reading this should know exactly what to build, how to wire it up, and what questions to ask before starting.

Reference implementations: MLB Desk (docs/mlb-desk-construction-spec.md), MLB Player Props Desk (docs/mlb-player-props-desk-construction-spec.md)

The Pipeline Pattern

Every game desk follows the same 4-table pipeline:

Table 1: Kalshi Data (soft book — what we trade against)
    ↓
Table 2: Anchor Book Data (sharp book — our fair value reference)
    ↓
Table 3: Probability Curves (book curve + model curve vs Kalshi price)
    ↓
Table 4: Edge Scanner Output (mispricings found)

The rule: Each table is sport-specific. No mixing data across sports. Each desk gets its own isolated databases.

Table 1 — Kalshi Data

What: Raw contract prices pulled from the Kalshi API for this sport's game-level markets.

Database: kalshi-{sport}-prices.db Table name: kalshi_{sport}_prices

Standard columns:

Data quality rules:

• Same-day only — only store prices for today's games
• No settled prices — filter out bid <= 5 or bid >= 95
• No live/in-game data — skip games that have already started
• Tag every row with scan_type so you know which collection window it came from

Kalshi API notes:

• REST base: https://api.elections.kalshi.com/trade-api/v2
• Auth: RSA-PSS signing
• Ticker format: SERIES-DATECODETEAMS-DETAIL
• Paginate properly — some sports need multiple pages (5+ for MLB props). Always check if there are more pages.
• Rate limit: 500ms-2s delay between API calls to avoid 429 errors

Table 2 — Anchor Book Data

What: Sharp book odds that serve as our fair value reference. This is the "truth" we compare Kalshi against.

For game desks, the anchor is typically Pinnacle (sharpest game book). Other options: opening lines from offshore books, consensus lines from SBR.

Database: pinnacle-{sport}.db (or {anchor}-{sport}.db) Table name: pinnacle_{sport}_odds

Standard columns:

Key principle: The anchor book provides the de-vigged fair value. De-vig the over/under (or home/away) prices to get the true implied probability at the posted line. This probability anchors the curve.

Table 3 — Probability Curves

What: For each game, build TWO probability curves and compare both against every Kalshi alt-line price:

1. Book curve — Derived from the anchor book's de-vigged fair value. The anchor book gives you the probability at ONE point (their posted line). You extend this into a full curve across all thresholds using a statistical distribution.

2. Model curve — Derived from the desk's own model (power ratings, team quality composites, pitching matchups, whatever the sport uses). This is an independent estimate that doesn't rely on the books at all.

Both curves are compared against Kalshi's price at each threshold. When either curve says a Kalshi contract is mispriced by more than the fee (typically 7%), that's an edge.

Database: {sport}-edges.db Table name: {sport}_probability_curves

Standard columns:

Distribution selection (game-level):

The model curve uses whatever the sport's desk model produces. For MLB this is quality composites, SP matchups, park factors. For NBA it might be pace-adjusted efficiency. The template can't prescribe this — it depends on the sport. See "Questions to Ask" below.

Table 4 — Edge Scanner Output

What: The final output — mispricings found by comparing Kalshi prices against the book curve and model curve.

Database: {sport}-edges.db (same DB as curves) Table name: sports_edges (filtered by sport column)

Standard columns:

Edge summary table: sports_edge_summary

• Per-day, per-market-type edge counts and averages
• Used for dashboard overview and performance tracking

Scheduling

Everything runs on Eastern Time (ET). The schedule has 3 layers:

Layer 1 — Data Collection (top of hour)

Game-day windows: 6 AM, 8 AM, 10 AM, 2 PM, 6 PM ET Closing snapshot: 1 minute before each game's start time (staggered per game, not all at once)

Layer 2 — Stats & Baselines (daily morning)

Three staggered groups so raw data finishes before computation starts:

Layer 3 — Edge Detection (after data lands)

Critical: Edge scanner must run AFTER curves are built, which must run AFTER data collection. The 10-minute offset ensures fresh data is available. Never run the edge scanner at :00 — the data won't be there yet.

Layer 4 — Futures & Season Markets (adaptive)

For long-term markets (futures, win totals, division winners):

Set sport-specific transition dates. Include an expiry_date column in futures databases — scanning stops after expiry.

Dashboard Wiring

desk-config.ts

Every desk needs an entry in src/pipeline/data-status/desk-config.ts:

{
  name: '{Sport Name}',
  slug: '{sport-slug}',
  kalshi: [{
    category: 'Sports / {Category} / {Sport}',
    hasScraper: true,
    scraperName: 'collector.ts (Kalshi sports cron)',
    freshnessKey: 'kalshi-{sport}',
    series: [
      { ticker: 'KXSERIES1', label: 'Human Label', dataViewKey: 'kalshi-{sport}-type1' },
      // one per Kalshi series for this sport
    ],
  }],
  sources: [
    // Sources organized by group — see Standard Groups below
  ],
}

Standard Groups for Game Desks

Every game desk should have these groups on the dashboard. Order matters — this is how they appear on the page:

1. Edge Detection — Edge scanner results (per market type), probability curves, implied curves
2. Game-Day — Kalshi game lines, anchor book odds, other book data, sharp money indicators
3. Futures — Season-long markets (if applicable): win totals, division winners, championship futures
4. Ratings & Predictions — External model predictions, power ratings, simulations
5. Pitching / Offense / Defense (sport-specific) — Player/team stats relevant to modeling
6. Game Context — Park/venue factors, weather, referee/umpire tendencies, schedule, injuries
7. Computed Analytics — Model outputs: quality composites, variance, fatigue, derived metrics

source-tables.ts

Every freshnessKey in desk-config needs a mapping in src/pipeline/data-status/source-tables.ts:

'freshnessKey': {
  db: 'database-name',        // SQLite DB file (without .db extension)
  tables: ['table_name'],     // Which table(s) to query
  filter?: {                  // Optional: filter to specific rows
    column: 'column_name',
    value: 'filter_value',
  },
  parentKey?: 'parent-key',   // Optional: inherit freshness from parent
}

Naming convention for freshnessKeys:

• kalshi-{sport} — top-level Kalshi data
• kalshi-{sport}-{market} — filtered by market type (spreads, totals, etc.)
• pinnacle-{sport} — anchor book data
• edge-scanner-{sport} — all edges
• edge-scanner-{sport}-{market} — edges filtered by market type
• {sport}-{metric}-curves — probability curves
• {sport}-team-variance, {sport}-fatigue-metrics — computed analytics
• scrape-{source}-{sport} — external data scrapes

scheduler.ts

Register cron jobs in src/cron/scheduler.ts. Pattern:

const task = cron.schedule('CRON_PATTERN', async () => {
  try {
    // 1. Import the scraper/calculator
    // 2. Run it
    // 3. Update freshness
    const { updateFreshnessAutoHash: uf } = await import('../pipeline/data-freshness.js');
    uf(getPipelineDb(), 'freshnessKey', 'fresh', rowCount);
  } catch (e) {
    logger.error(`Cron error: ${e instanceof Error ? e.message : e}`);
    uf(getPipelineDb(), 'freshnessKey', 'error', undefined, e.message);
  }
}, { timezone: 'America/New_York' });
this.tasks.set('task-name', task);

Freshness Tracking

Freshness is automatic — the dashboard discovers sources from desk-config and checks data_freshness table. Each cron job calls updateFreshnessAutoHash() after running. No separate registration needed.

Thresholds:

Telegram alert fires after 2 consecutive misses.

Isolation Checklist

Before a desk is considered done, every item must pass:

Things to Watch Out For

Hard-won lessons from building the MLB desk. Read these before starting any new desk.

1. Player/team name mismatch across sources. Kalshi, Pinnacle, FanDuel, stats APIs — they all spell names differently. Kalshi uses tickers like "KXMLBHR-26APR07-A.BREGMAN-O1", FanDuel uses "Alex Bregman", stats APIs use "Bregman, Alex". You NEED a crosswalk table that maps names across sources. Build it early. Strip Jr./Sr. suffixes. Handle misspellings (Kalshi had "SUREZ" for Suarez).

2. Wrong scanner wired to cron. When the MLB prop edge scanner was first deployed, the cron job was calling the generic scanner instead of the MLB-specific one. The edges table was empty for days before anyone noticed. Always verify the cron is calling the right function — test it manually after wiring.

3. Filters too aggressive. The initial minimum price filter (5 cents) was dropping valid alt lines. Had to lower to 1 cent. Don't over-filter — you can always filter on the dashboard side. Be conservative with data-side filters.

4. Kalshi API pagination and rate limits. The initial Kalshi pull only fetched 1 page of results and missed most of the data. Some sports have 5+ pages of contracts. Always check if there are more pages. Add rate limit delays (500ms+) between page requests. Kalshi returns 429 (too many requests) if you hit their API too fast — when scanning multiple series in a loop, use at least 2-second delays between calls. Don't retry 429s immediately, wait and try on the next cron cycle.

5. Sign convention bleeding across market types. Spreads use negative signs (home -1.5), totals don't. A bug caused the total's model anchor to get a negative sign from the spread logic. Keep spread/total/moneyline code paths completely separate.

6. Live and settled data leaking in. Without explicit checks, the scraper will collect prices for games that have already started (live) or already ended (settled). This corrupts your curves. Always check game start time and skip games that have started. Filter bid <= 5 / bid >= 95 for settled contracts.

7. Edge scanner running before data lands. If the edge scanner fires at :00 (same time as data collection), it reads stale data from the previous window. The scanner MUST run after data collection finishes — at least :10 past the hour.

8. Staggered scheduling is critical. Raw data (Group 1, 9:00 AM) must finish before baselines (Group 2, 9:05 AM), which must finish before derived metrics (Group 3, 9:10 AM). If you don't stagger, derived metrics compute on yesterday's baselines.

Questions to Ask Before Building

An AI starting a new game desk MUST ask and get answers for these before writing any code:

Sport-Specific

1. What Kalshi ticker series exist for this sport? (e.g., KXMLB, KXNBA, KXNHL)
2. What market types does Kalshi offer? (moneyline, spread, total, team total, F5/first half, period-specific, etc.)
3. Does this sport have doubleheaders, split games, or other scheduling quirks?
4. Are there overtime/extra innings/shootout rules that affect totals?
5. What is the typical scoring range? (Affects distribution choice — low-scoring = Poisson, high-scoring = Normal)
6. Does this sport have a first-half/first-period equivalent to MLB's F5?

Anchor Book

7. Which book is the sharp anchor for this sport? (Pinnacle for most, but could vary)
8. Does the anchor book offer all the same market types as Kalshi? (Pinnacle doesn't offer MLB team totals — they have to be derived)
9. Are there any scraping issues with the anchor? (Pinnacle F5 lines were unreliable for MLB — had to derive from full-game)

Model

10. What model does this sport's desk use? (Power ratings, Elo, quality composites, etc.)
11. What data feeds the model? (Stats API, external ratings, player logs, etc.)
12. What distribution should each market type use for the model curve?
13. Are there sport-specific adjustments? (Park factors for MLB, altitude for NBA, ice conditions for NHL, etc.)

Futures

14. Does Kalshi offer futures for this sport? (Championship, division, win totals, etc.)
15. What is the season timeline? (Start date, key transition dates, end date — for adaptive scheduling)
16. Does the anchor book offer futures for cross-reference?

Data Sources

17. What external stats APIs exist for this sport? (MLB Stats API, NBA Stats API, etc.)
18. What web scrapes are needed? (Baseball Reference, Basketball Reference, etc.)
19. What computed metrics does the model need? (Fatigue, variance, situational splits, etc.)

Dashboard

20. What groups should appear on the dashboard? (Use standard groups as starting point, add sport-specific ones)
21. Any special sub-views needed? (Per-market-type filtered views, per-team views, etc.)

Document Control

This template is updated as new desks are built and new lessons are learned. The "Things to Watch Out For" section grows with every desk.

Last updated: 2026-04-08

Changelog

Running log of changes and decisions for the game-level desk pipeline. Each entry has two sections:

• Changes — what was done technically (bugs, fixes, new features, files touched)
• Boss Notes — what the boss wants, likes, doesn't like, and why he made certain decisions. This is the vision for the system. Follow it.

If you're building this from scratch, read every Boss Notes section first — that's how the boss thinks about this system.

2026-04-08 — Initial changelog added

Changes:

No game desk bugs fixed this session. Changelog format established to match player props desk template.

Boss Notes:

• Reviews data quality by eyeballing dashboard columns at /data-status/view/. If something looks off (all zeros, weird names, missing data), he flags it. The dashboard is his primary QA tool.
• Wants these changelogs maintained so a future builder can replicate everything in one pass without asking questions.
• Prefers keeping raw data and calculated output in separate databases — don't merge pipeline stages. Raw ingredients and finished product stay apart.
• Catches issues by browsing data viewer pages directly, not by reading logs or code.

2026-04-11 — Virtual scroll data view, directional rungs, anchor_diff column

Changes:

• Directional rung calculation — Rung 0 is now the threshold whose Pinnacle implied odds are closest to 50/50. Positive rungs = YES price up (over easier), negative = NO price up (under easier). Step size auto-detected. Both research-pipeline.db and mlb-edges.db recalculated. (edge-scanner.ts)
• anchor_diff column — New computed column showing pinnacle_anchor - model_anchor, positioned between Pin W/L and Model Anchor. (data-view.ts, table-config.ts)
• Virtual scroll data view — New page at /data-status/v/:source renders only ~50 DOM rows regardless of dataset size. Server APIs: /data (paginated JSON, 44ms), /summary (SQL aggregates, 26ms), /filter-values (14ms). Scales to 100K+ rows. (virtual-view.ts, data-api.ts, routes.ts)
• Server-side filter/sort — DB column filters via SQL WHERE, computed column filters client-side. Sort via SQL ORDER BY. Summary recalculates from filtered data. (data-api.ts, virtual-view.ts)
• Display formatting — Probabilities and prices show as percentages. Edges show with % and red/green coloring. Column widths auto-sized from content. (virtual-view.ts)

Boss Notes:

• Boss caught that rung was not directional — just 0,1,2,3 with no negatives. Wanted it to show which way the line moved: positive = YES price up, negative = NO price up.
• Boss specified: rung 0 = closest to 50/50 implied odds from Pinnacle, not just closest to the anchor number.
• Boss wanted anchor_diff between Pin W/L and Model Anchor columns specifically.
• Boss reported page was sluggish with ~2K rows. Council (5 AI advisors, unanimous) recommended virtual scrolling. Boss chose custom vanilla JS over Tabulator library.
• Boss required summary stats to use ALL filtered data, not just displayed rows. Confirmed by testing model_best_side=no + result=NO filter → 100% win rate.

2026-04-10 — Summary bar fixes, model_best_side, result columns, F5 tie tracking

Changes:

• Summary bar bug fixes — Our Model edge was 100x inflated (missing /100). Win% was using Pinnacle's outcome instead of checking model's own best side vs result. Both models now use same logic: compare best_side to Result column. (data-view.ts)
• New model_best_side column — Each model now has its own best side column. best_side renamed to "Pin Best Side", new model_best_side = "Model Best Side" based on model edges. Backfilled 3291+2419 rows. (edge-scanner.ts, table-config.ts, data-view.ts)
• Result columns for spreads and ML — Spreads get final_margin + result (team covered? YES/NO). ML gets result (team won? YES/NO). Totals already had this. (data-view.ts)
• View-specific column hiding — Totals/spreads/ML views hide actual_outcome and settled_result (replaced by computed Result). Other views keep them. (data-view.ts)
• F5 MLB tie tracking — Edge scanner now records TIE contracts using Poisson tie probability from mlb_probability_curves. New is_tie column flags games that tied after 5 innings. Settlement detects TIE ticker settling YES and flags all team contracts for that game. (edge-scanner.ts, scanner-bridge.ts)

Boss Notes:

• Boss caught that Pinnacle and Our Model summary stats were using the same win/loss determination — should be independent. Each model's best side vs the actual Result column.
• Boss identified that best_side was only for Pinnacle, not the edge model. Needed two separate columns.
• Boss wants F5 tie data recorded so the model can learn tie probabilities. Kalshi has 3 contracts per F5 ML game (Team A, Team B, TIE) — we were only scanning 2. Now scanning all 3.
• F5 results can't use final game scores (no inning-by-inning data). Kalshi settlement is source of truth for F5.

2026-04-08 — Settlement columns added to Table 3 standard schema

Changes:

Added settlement and tracking columns to the probability curves standard schema (Table 3): is_main_line, actual_result, outcome, book_was_right, model_was_right, book_error, model_error, settled_at. These match the player props desk implementation. No game desk code changed — this is a template update so future game desks include these columns from the start.

Boss Notes:

• Probability curves are for beating the books — settlement proves whether the model is actually sharper than the book over time. Every desk needs this.
• Same design as player props: is_main_line flag (not a value on every row), settlement runs as games finish (not morning batch), both book and model accuracy tracked.