Summarize

The summarize Lambda reads ALL.json from the records bucket, computes site-wide statistics, and writes summary artifacts to the records bucket. It also writes full rivalry pair data (with user IDs) to the private ops bucket. It runs daily at 06:00 UTC so analytics stay current even mid-week as new games complete.

Source: src/functions/summarize.ts. Pure helpers and unit tests: src/functions/summarizeHelpers.ts, summarizeHelpers.test.ts.

Input

1. ALL.json — full array of APGameRecord from the records cron
2. mvtimes.json — move-time seasonality (produced by records-move-times at 03:00 UTC)
3. Live DynamoDB — USERS partition query for country codes (geo stats)

Output

Per-player slices are written by player-summary-fanout (daily 06:15 UTC), which enqueues one SQS message per user; player-summary-worker performs the S3 puts.

Typed as StatSummary in src/types/stats/StatSummary.ts. See also S3 outputs.

Top-level fields (StatSummary)

Processing stages

Segmentation

Each record is indexed by:

• Meta game name (rec.header.game.name)
• Player user IDs
• Date range (oldestRec, newestRec)
• Timeout vs abandoned moves (via summarizeHelpers)
• Play context (casual vs event)
• Pie invocation and multi-player counts where supported

Meta statistics (metaStats)

For each meta game (and variant subgroup when multiple variant combinations exist), computes two-player stats:

• Game count (n)
• Average and median move count (lenAvg, lenMedian)
• First-player win rate (winsFirst)
• Draw rate (drawRate)

Only games with exactly two players and more than two moves are included.

Timeout vs abandoned

Detection uses recordHasTimeout / recordHasAbandoned and findTimeoutPlayerSeat in summarizeHelpers.ts.

H-index metrics

• hMeta — per-meta-game h-index (breadth of player participation)
• players.h, players.hOpp — player h-index and opponent h-index site-wide

Uses gameinfo from gameslib to map display names to meta UIDs.

Ratings (ratings)

For each meta game (and variant subgroup), runs three rating engines from @abstractplay/recranks:

Outputs:

• ratings.highest — per user/game rows with Elo (rating), W/L/D, full glicko (GlickoStats), and trueskill. Legacy name — rows are all rated players, not “highest only”; the enriched glicko object is canonical for Glicko consumers (use ratingLow, provisional, etc.).
• ratings.avg — simple Elo averages across metas per user
• ratings.weighted — Elo weighted by games played per user
• ratings.glickoByGame — flat Glicko-only rows: { user, game, glicko } (same pool as highest)
• ratings.glickoSite — per-user cross-meta composite: weighted rating, rd, ratingLow / ratingHigh, n, plus provisional / established (true if any game row matches)
• ratings.glickoMeta — thresholds, periodMs, generatedAt, and run counts (counts.byGame, counts.site)

Glicko row shape (GlickoStats)

Each glicko object on ratings.highest and ratings.glickoByGame:

glickoMeta repeats the threshold constants (establishedRd, provisionalRd, minGamesEstablished, minGamesProvisional) so consumers can apply stricter rules without redeploying crons.

Tiered exports

The monolith remains the full contract. Three tier files are views for lazy front-end loading (see S3 outputs):

Each tier/slice includes generated (ISO timestamp). Uploaded with Content-Type: application/json and Cache-Control: public, max-age=0, must-revalidate (see S3 outputs — CloudFront and caching).

Player rankings (players, topPlayers)

• social — players with the most distinct opponents
• eclectic — players who played the widest variety of meta games
• allPlays — total games played
• timeoutStats — per-user clock-timeout aggregates (count, latestTimeoutMs; not abandonments). Weekly charts use histograms.playerTimeouts.

Histograms (histograms)

Week buckets align from oldestRec; the right-most bucket may be partial.

activeMovers vs allPlayers: finishers vs players who moved in any game that week (including in-progress async games). Sourced from mvtimes.json; only ~365 days of move timestamps are available, so early buckets may be zero.

Recent activity (recent)

Games with the most recent date-end values.

Hours per move (hoursPer)

Structured object (HoursPerStats):

Excludes games ending by clock timeout or abandonment and games with fewer than two move rounds. Per-game rates are winsorized at the 2nd and 98th percentiles so extreme outliers (very slow correspondence games, bad timestamps) do not dominate the summary.

Geographic stats

• geoStats — all registered users with a recognized country on their profile (pk=USERS query, isoToCountryCode)
• activeGeoStats — players who completed at least one game in the past 30 days (from ALL.json completion timestamps), grouped by the same country mapping

Play context (playContext)

Counts games with no event/tournament linkage (casual) vs those tied to an org or tournament event (event).

Pie rates (pieRates)

For meta games whose gameslib flags include pie or pie-even: total games, count where pie was invoked (header.pied or header["pie-invoked"]), and rate.

Player count mix (playerCountMix)

For meta games that support more than two players: histogram of completed games by player count.

Rivalries

Two-player completed games only. Pairs are canonicalized (userA < userB). Only pairs with at least 5 shared games (RIVALRY_MIN_GAMES) are included.

Private ops (stats/rivalries.json): every qualifying pair with { userA, nameA, userB, nameB, n } — user IDs and display names (not anonymized).

Public (_summary.json → rivalries): every pair with at least 50 shared games (RIVALRY_PUBLIC_MIN_GAMES), ordered by n. Pairs are anonymized as { rank, label: "Pair N", n } unless both players have publicRivalries: true on their USERS record. Opted-in pairs include players: [{ id, name }, { id, name }] and label as "NameA vs NameB".

{ "rank": 1, "label": "Pair 1", "n": 42 }

{
  "rank": 1,
  "label": "Alice vs Bob",
  "n": 42,
  "players": [
    { "id": "…", "name": "Alice" },
    { "id": "…", "name": "Bob" }
  ]
}

{
  "generated": "2026-08-14T12:00:00.000Z",
  "minGames": 5,
  "pairs": [{ "userA": "…", "nameA": "Alice", "userB": "…", "nameB": "Bob", "n": 42 }]
}

Seasonality (seasonality)

Not computed in this Lambda. Copied from mvtimes.json → seasonality, which is built by records-move-times from per-move _timestamp values on the game stack (last 365 days). This reflects when players actually move, not when async games finish.

See moveSeasonality.ts.

Helper module

summarizeHelpers.ts exports:

Custom JSON serialization

Uses replacer from gameslib serialization when stringifying nested maps in rating output.

Related

• S3 outputs
• Recranks — rating engines and record schema
• Records pipeline