diff --git a/.gitignore b/.gitignore index c1a2b71d..b7c1e92e 100644 --- a/.gitignore +++ b/.gitignore @@ -127,3 +127,8 @@ data/form-screenshots/ # from disk by /verify/[ts]/[file]/route.ts. Tim 2026-06-04. apps/web/data/audit/*/snapshot.db apps/web/data/audit/*/snapshot.db.ots + +# billion-bot: packed npm tarballs + runtime data are build/runtime artifacts +apps/billion-bot/*.tgz +apps/billion-bot/data/ +apps/game/data-dev/ diff --git a/CLAUDE.md b/CLAUDE.md index 5faf3ffa..0d691ec2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -353,6 +353,22 @@ Postgres 16 + Redis 7, both Dockerised, brought up via `bash infra/scripts/db-up Migrations: builders pick the migration tool that fits their stack (Prisma for Node TS surfaces, plain SQL for the producer if it ever writes). Whichever tool, **migrations live in `apps//migrations/` and are checked in.** Reviewer agent rejects PRs that mutate schema without a migration. +## SDK release process (mandatory when bumping `@tournamental/bot-node`) + +External users install the bot SDK via `npm i @tournamental/bot-node` or run `npx tournamental-bot-node`. **Any change to `packages/bot-node/` must follow this checklist or the published SDK drifts behind the source.** The version published to npm is the version users get; nothing automatic mirrors the source bump. + +1. **Bump the version** in `packages/bot-node/package.json`. Semver: patch for bugfix, minor for additive API, **major (with a SCHEMA migration note) for any storage-layer change**. The schema is breaking by default — operators upgrading minor versions should not have to wipe their data volume. +2. **Update tests** in `packages/bot-node/test/`. `pnpm --filter @tournamental/bot-node test` must be green before publishing. +3. **Build + pack** locally: `cd packages/bot-node && pnpm run build && pnpm pack`. Produces `tournamental-bot-node-.tgz`. +4. **Smoke the dependents** (any package that consumes the tarball directly): + - `apps/billion-bot/` — edit `package.json` + `Dockerfile` to reference the new `tournamental-bot-node-.tgz`, then `rm -rf node_modules && pnpm install && docker compose build --no-cache && docker compose up -d`. Confirm `/stats` on port 4080 reports the new version. + - Any other consumer the orchestrator names in the session note. +5. **Publish to npm**: `npm publish --access public` from `packages/bot-node/`. Requires a token with `@tournamental/*` write scope in `~/.npmrc`. If `npm whoami` returns 401 or publish returns 404 on the scope, **stop and escalate to Tim** — do not skip this step or external users will install a stale version. +6. **Commit** the version bump + new tarball reference + updated docs in one PR titled `feat(bot-node): vX.Y.Z — `. The body must list: the schema delta, whether operators need to wipe their data volume, and the rollback story. +7. **Announce** in `IDEAS.md` (or the launch channel post-launch) so operators know to update their `npm i` / pull the new docker image. + +A schema migration that requires a wipe (e.g. v0.3.0's regenerate-on-demand collapse) **must** include an `infra/scripts/migrate-bot-node--to-.md` runbook covering: (a) what to back up first, (b) the wipe commands, (c) the verification steps post-restart. + ## Three things to remember 1. **Ship the AR-FR demo first.** Everything else is enabled by it. diff --git a/README.md b/README.md index e072c09e..1531bf48 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,23 @@ Domain: **tournamental.com**. Brand expansion when needed: **Tournamental, Verif - **npm packages live** under [`@tournamental/*`](https://www.npmjs.com/search?q=%40tournamental) -- `spec`, `bracket-engine`, `social-cards`, and `plugin-sdk` (in development). - **MCP server live** at [`mcp.tournamental.com`](https://mcp.tournamental.com) so Claude, Cursor, Windsurf, and other Model Context Protocol clients can read live Tournamental state. - **Engineering blog + plugin SDK** -- the engineering log at [`tournamental.com/engineering`](https://tournamental.com/engineering) is now the canonical entry point for builders, and the plugin SDK in [`packages/plugin-sdk/`](packages/plugin-sdk) lets you drop in renderers, scorers, ingest sources, identity providers, share-card pipelines, odds feeds, and affiliate routers without forking the core. +- **Open Bot Arena live** at [`play.tournamental.com/run`](https://play.tournamental.com/run) -- spin up a browser-tab swarm of prediction bots, every pre-kickoff merkle root anchored to Bitcoin via OpenTimestamps for $0. See the Bot Arena section below. + +## Bot Arena + +The **Open Bot Arena** is Tournamental's open-source, blockchain-anchored experiment: can anyone in the world generate a perfect 104-match FIFA World Cup 2026 bracket using an AI swarm? Anyone can join in 30 seconds from a browser tab, no install, no signup, no payment. + +- **Run the swarm:** open [`play.tournamental.com/run`](https://play.tournamental.com/run), click the button, watch your tab spin up one Web Worker per CPU core and grind through bracket after bracket. A 2022-era laptop comfortably runs 100,000 bots through a 104-match bracket in under 10 seconds. +- **Cryptographic anchor:** before every kickoff, each tab publishes a sorted-pair sha256 merkle root committing to all of its bots' picks for that match. The roots are aggregated centrally into a federation root and OTS-anchored to Bitcoin. Cost to us: $0 (the OpenTimestamps calendars cover Bitcoin transaction fees through aggregation). +- **Verifiable end-to-end:** anyone with the audit-export bundle and a Bitcoin full node can reproduce any bot's bracket, verify the merkle inclusion proof, and confirm the commitment existed at-or-before the match's kickoff. The reference verifier ships in `packages/bot-node/src/verifier/` under Apache 2.0. +- **Bots compete, bots do not win money.** Per [terms of service](https://tournamental.com/terms/house-prize#bots), bots are ineligible for cash prizes (Humanness Score floor of 50; bots are 0 by design). Perfect-bracket bots get a badge, a research co-author invitation, and a non-monetary trophy. + +The four docs to read, in order: + +- [`docs/30-browser-swarm-architecture.md`](docs/30-browser-swarm-architecture.md) -- what a swarm is, how it scales (Web Workers / multi-tab / multi-machine), deterministic regeneration, IndexedDB schema, chalk and Claude strategies, federation client, performance budgets. +- [`docs/31-merkle-and-ots-proofs.md`](docs/31-merkle-and-ots-proofs.md) -- the cryptographic core. Sorted-pair sha256 leaf and pair rules, worked example, the `.ots` file format, Bitcoin upgrade path, the verifier protocol. +- [`docs/32-perfect-bracket-experiment.md`](docs/32-perfect-bracket-experiment.md) -- the user-facing narrative and the maths (~1 in 10^29 for chalk-only, ~1 in 10^44 for uniform-random, why no realistic swarm brute-forces it). +- [`docs/17-vstamp-and-prediction-iq.md`](docs/17-vstamp-and-prediction-iq.md) -- the parallel per-prediction VStamp surface for the human-facing prediction game. ## Build on Tournamental in 20 minutes diff --git a/apps/auth-sms/migrations/0005-add-is-bot.sql b/apps/auth-sms/migrations/0005-add-is-bot.sql new file mode 100644 index 00000000..0e648971 --- /dev/null +++ b/apps/auth-sms/migrations/0005-add-is-bot.sql @@ -0,0 +1,15 @@ +-- 0005-add-is-bot.sql , Bot Arena marker on the user table. +-- +-- Why: the Phase 1 Open Bot Arena (see +-- docs/superpowers/specs/2026-06-07-bot-arena-design.md §4.1) needs to +-- distinguish bots from humans at the auth layer so the prize-eligibility +-- gate and the leaderboard scope filter can short-circuit on a single +-- column read. Default 0 backfills existing rows safely. +-- +-- Note: auth-sms applies migrations inline via Storage.migrate*() helpers +-- rather than reading these .sql files at runtime. This file is the +-- canonical reference for the migration. The runtime equivalent lives in +-- apps/auth-sms/src/storage.ts inside migrateUserBotColumn(). + +ALTER TABLE user ADD COLUMN is_bot INTEGER NOT NULL DEFAULT 0; +CREATE INDEX IF NOT EXISTS idx_user_is_bot ON user(is_bot); diff --git a/apps/auth-sms/src/storage.ts b/apps/auth-sms/src/storage.ts index 54fc87fc..5339b339 100644 --- a/apps/auth-sms/src/storage.ts +++ b/apps/auth-sms/src/storage.ts @@ -84,6 +84,15 @@ export interface UserRecord { highlevel_contact_id: string | null; /** Unix seconds when the contact was last synced to HighLevel. NULL if not yet. */ highlevel_synced_at: number | null; + /** + * 1 if this row represents a bot competing in the Open Bot Arena + * (Phase 1, FIFA WC 2026 launch). 0 for human users. Bots are + * ineligible for the cash prize regardless of leaderboard position; + * see /terms/house-prize and docs/20-identity-humanness-bots.md. The + * column is indexed so the leaderboard scope filter + * (humans|bots|all) can short-circuit cheaply. + */ + is_bot: 0 | 1; } export interface SessionRecord { @@ -244,9 +253,34 @@ export class Storage { this.db.exec(SCHEMA); this.migrateUserTableIfNeeded(); this.migrateUserProfileColumns(); + this.migrateUserBotColumn(); this.migratePhoneOtpTableIfNeeded(); } + /** + * v0.4 -> v0.5: add `is_bot` flag for the Open Bot Arena. The Phase 1 + * launch (FIFA WC 2026) seeds ~18k bot rows so the public leaderboard + * is populated from minute one, and external operators register their + * own bots via the bot SDK. Bots are ineligible for the cash prize + * (humanness < 50 gate) so this column doubles as a fast filter on the + * leaderboard read path. See + * docs/superpowers/specs/2026-06-07-bot-arena-design.md §4.1. + */ + private migrateUserBotColumn(): void { + const cols = this.db + .prepare(`PRAGMA table_info(user)`) + .all() as Array<{ name: string }>; + const names = new Set(cols.map((c) => c.name)); + if (!names.has('is_bot')) { + this.db.exec( + `ALTER TABLE user ADD COLUMN is_bot INTEGER NOT NULL DEFAULT 0`, + ); + } + this.db.exec( + `CREATE INDEX IF NOT EXISTS idx_user_is_bot ON user(is_bot)`, + ); + } + /** * v0.3 → v0.4: add profile editor fields + HighLevel sync columns to * `user`. SQLite ADD COLUMN is non-destructive; legacy rows simply @@ -682,6 +716,7 @@ export class Storage { favourite_team_code: null, highlevel_contact_id: null, highlevel_synced_at: null, + is_bot: 0, }; this.db .prepare( @@ -726,6 +761,7 @@ export class Storage { favourite_team_code: null, highlevel_contact_id: null, highlevel_synced_at: null, + is_bot: 0, }; this.db .prepare( @@ -809,6 +845,7 @@ export class Storage { favourite_team_code: null, highlevel_contact_id: null, highlevel_synced_at: null, + is_bot: 0, }; this.db .prepare( @@ -819,6 +856,60 @@ export class Storage { return rec; } + /** + * Insert a synthetic bot row for the Open Bot Arena. + * + * Used by both the apps/seed-bots CLI (which mints the launch-day + * 18k seed cohort) and the bot SDK (which mints externally-operated + * bots on behalf of an API-key holder). Phone, email, telegram are + * all NULL by definition , bots authenticate via their owning API + * key, not via OTP. + * + * Idempotent on `id`: re-running the seed CLI does not duplicate + * rows or perturb existing bot brackets. + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §4.1 + */ + insertBotUser(opts: { + id: string; + display_name?: string | null; + country?: string | null; + favourite_team_code?: string | null; + created_at: number; + }): UserRecord { + const existing = this.getUser(opts.id); + if (existing) return existing; + const rec: UserRecord = { + id: opts.id, + phone: null, + display_name: opts.display_name ?? null, + country: opts.country ?? null, + telegram_id: null, + telegram_username: null, + created_at: opts.created_at, + last_seen_at: opts.created_at, + email: null, + first_name: null, + last_name: null, + city: null, + favourite_team_code: opts.favourite_team_code ?? null, + highlevel_contact_id: null, + highlevel_synced_at: null, + is_bot: 1, + }; + this.db + .prepare( + `INSERT INTO user + (id, display_name, country, favourite_team_code, + created_at, last_seen_at, is_bot) + VALUES + (@id, @display_name, @country, @favourite_team_code, + @created_at, @last_seen_at, 1)`, + ) + .run(rec); + return rec; + } + /** * Link a Telegram identity onto an already-authenticated user. * diff --git a/apps/auth-sms/test/storage-is-bot.test.ts b/apps/auth-sms/test/storage-is-bot.test.ts new file mode 100644 index 00000000..0f04d1cf --- /dev/null +++ b/apps/auth-sms/test/storage-is-bot.test.ts @@ -0,0 +1,55 @@ +import { describe, it, expect, beforeEach, afterEach } from 'vitest'; +import { Storage } from '../src/storage.js'; + +let s: Storage; +beforeEach(() => { + s = new Storage({ path: ':memory:' }); +}); +afterEach(() => s.close()); + +describe('UserRecord is_bot column', () => { + it('defaults is_bot to 0 for users created via findOrCreateUser', () => { + const u = s.findOrCreateUser('+6421000001', 100); + expect(u.is_bot).toBe(0); + const reloaded = s.getUser(u.id); + expect(reloaded?.is_bot).toBe(0); + }); + + it('defaults is_bot to 0 for users created via findOrCreateEmailUser', () => { + const u = s.findOrCreateEmailUser('dev@example.com', 100); + expect(u.is_bot).toBe(0); + }); + + it('defaults is_bot to 0 for telegram users', () => { + const u = s.findOrCreateTelegramUser({ + telegramId: 12345, + telegramUsername: 'someone', + displayName: 'Some One', + phone: null, + now: 100, + }); + expect(u.is_bot).toBe(0); + }); + + it('insertBotUser persists is_bot=1 and round-trips through getUser', () => { + const bot = s.insertBotUser({ + id: 'bot_abc12345', + display_name: 'Carlos_BRA_42', + country: 'BR', + created_at: 100, + }); + expect(bot.is_bot).toBe(1); + const reloaded = s.getUser('bot_abc12345'); + expect(reloaded?.is_bot).toBe(1); + expect(reloaded?.id).toBe('bot_abc12345'); + }); + + it('has an idx_user_is_bot index after migration', () => { + const rows = s.db + .prepare( + `SELECT name FROM sqlite_master WHERE type='index' AND name='idx_user_is_bot'`, + ) + .all() as { name: string }[]; + expect(rows.length).toBe(1); + }); +}); diff --git a/apps/billion-bot/Dockerfile b/apps/billion-bot/Dockerfile new file mode 100644 index 00000000..3b81ba73 --- /dev/null +++ b/apps/billion-bot/Dockerfile @@ -0,0 +1,43 @@ +# Tournamental Billion Bot - dashboard wrapper around @tournamental/bot-node. +# Self-contained: installs bot-node from a bundled tarball (v0.2.0 strategy +# recalibration) so the container does not depend on a live npm release. +# When 0.2.0 lands on the public npm registry, package.json can switch back +# to "@tournamental/bot-node": "^0.2.0". +FROM node:20-bookworm-slim + +WORKDIR /app +ENV NODE_ENV=production +ENV DATA_DIR=/app/data +ENV DASH_PORT=4080 +ENV DASH_HOST=0.0.0.0 +ENV BOT_NODE_VERSION=0.2.0 + +RUN apt-get update \ + && apt-get install -y --no-install-recommends curl python3 make g++ \ + && rm -rf /var/lib/apt/lists/* \ + && useradd --create-home --uid 10001 botnode \ + && mkdir -p /app/data \ + && chown -R botnode:botnode /app + +COPY --chown=botnode:botnode package.json /app/package.json +COPY --chown=botnode:botnode tournamental-bot-node-0.3.0.tgz /app/tournamental-bot-node-0.3.0.tgz + +# Install bot-node CLI from the bundled tarball + better-sqlite3 locally so +# ESM imports resolve from /app. Expose the bot-node CLI on PATH via a +# symlink for convenience. +RUN cd /app \ + && npm install --omit=dev --no-audit --no-fund \ + && ln -s /app/node_modules/.bin/tournamental-bot-node /usr/local/bin/tournamental-bot-node \ + && npm cache clean --force \ + && chown -R botnode:botnode /app + +COPY --chown=botnode:botnode dashboard.mjs /app/dashboard.mjs +COPY --chown=botnode:botnode fifa-wc-2026-fixtures.json /app/fifa-wc-2026-fixtures.json +ENV TOURNAMENTAL_MATCHES=/app/fifa-wc-2026-fixtures.json + +USER botnode +EXPOSE 4080 +HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \ + CMD curl -fsS http://127.0.0.1:4080/health || exit 1 + +ENTRYPOINT ["node", "/app/dashboard.mjs"] diff --git a/apps/billion-bot/dashboard.mjs b/apps/billion-bot/dashboard.mjs new file mode 100644 index 00000000..b1c0e631 --- /dev/null +++ b/apps/billion-bot/dashboard.mjs @@ -0,0 +1,831 @@ +#!/usr/bin/env node +// Tournamental billion-bot dashboard. +// +// - Serves HTML + JSON stats for a pool of bot-node child processes. +// - Each worker = one `tournamental-bot-node generate --bots=` process, +// writing to its own SQLite DB at $DATA_DIR/worker-XX.db. +// - Adjustable worker count, batch size, elapsed time, instantaneous rate, +// host + container CPU readouts. +// - Dry-run: workers never POST to central. + +import { spawn } from "node:child_process"; +import { createHash } from "node:crypto"; +import { mkdirSync, existsSync, readFileSync, statSync } from "node:fs"; +import { createServer } from "node:http"; +import { cpus, totalmem } from "node:os"; +import { join } from "node:path"; +import Database from "better-sqlite3"; + +const PORT = Number(process.env.DASH_PORT || 4080); +const HOST = process.env.DASH_HOST || "0.0.0.0"; +const INITIAL_WORKERS = Number(process.env.WORKERS || 48); +const MAX_WORKERS = Number(process.env.MAX_WORKERS || 96); +const INITIAL_BATCH = Number(process.env.BATCH_SIZE || 100_000); +const TARGET = Number(process.env.TARGET_BOTS || 1_000_000_000); +const DATA_DIR = process.env.DATA_DIR || "/app/data"; +const NODE_LABEL = process.env.NODE_LABEL || "vtorn-dev-1b-test"; +const CLI = process.env.BOT_NODE_CLI || "tournamental-bot-node"; +const HOST_PROC_STAT = process.env.HOST_PROC_STAT || "/host-proc/stat"; +const HOST_PROC_LOADAVG = process.env.HOST_PROC_LOADAVG || "/host-proc/loadavg"; +const TOTAL_HOST_CORES = cpus().length; +const CLK_TCK = 100; // Standard Linux USER_HZ; bot-node never overrides. + +// Aggregate-leaderboard publish config. When OPERATOR_API_KEY is set, +// the dashboard auto-POSTs /v1/swarms//summary every +// PUBLISH_INTERVAL_MS so the count shows up on the operator's +// /profile//swarm page. Same payload shape the browser +// swarm uses (apps/web/components/browser-swarm/federation.ts). +const OPERATOR_API_KEY = process.env.OPERATOR_API_KEY || ""; +const CENTRAL_URL = (process.env.CENTRAL_URL || "https://api.tournamental.com").replace(/\/$/, ""); +// Cadence is "publish once every PUBLISH_EVERY_BOTS new bots OR every +// PUBLISH_MAX_INTERVAL_MS, whichever comes first". The volume trigger +// is the primary, the time-based one is a safety net so a slow swarm +// still shows life on the leaderboard between batches. +const PUBLISH_EVERY_BOTS = Number(process.env.PUBLISH_EVERY_BOTS || 100_000); +const PUBLISH_MAX_INTERVAL_MS = Number(process.env.PUBLISH_MAX_INTERVAL_MS || 5 * 60_000); +const PUBLISH_MIN_INTERVAL_MS = Number(process.env.PUBLISH_MIN_INTERVAL_MS || 5_000); +// Legacy alias - keep for the dashboard label. +const PUBLISH_INTERVAL_MS = Number(process.env.PUBLISH_INTERVAL_MS || PUBLISH_MAX_INTERVAL_MS); +const OPERATOR_ID = OPERATOR_API_KEY + ? createHash("sha256").update(OPERATOR_API_KEY).digest("hex") + : ""; +// Cosmetic match catalogue is the bundled 104-match WC 2026 fixture +// file; the dashboard needs the first match's kickoff to set +// kickoff_at on the publish payload (idempotency key). +let FIRST_KICKOFF_AT = Date.now(); +try { + const matchesFile = process.env.TOURNAMENTAL_MATCHES; + if (matchesFile) { + const arr = JSON.parse(readFileSync(matchesFile, "utf8")); + if (Array.isArray(arr) && arr.length > 0) { + FIRST_KICKOFF_AT = new Date(arr[0].kickoff_utc).getTime(); + } + } +} catch { + // fall through with Date.now() +} + +mkdirSync(DATA_DIR, { recursive: true }); + +const state = { + running: false, + started_at: null, + stopped_at: null, + desired_workers: INITIAL_WORKERS, + batch_size: INITIAL_BATCH, + workers: [], // index -> WorkerHandle + errors: [], + bots_at_start: 0, + total_bots_cached: 0, + total_bots_cached_at: 0, + last_rate_bots: 0, + last_rate_ts: 0, + rate_window: [], // [{ts, total}] for short-window rolling rate +}; + +function workerDbPath(i) { + return join(DATA_DIR, `worker-${String(i).padStart(2, "0")}.db`); +} + +function spawnWorker(i) { + const dbPath = workerDbPath(i); + const env = { + ...process.env, + TOURNAMENTAL_NODE_DB: dbPath, + LOG_LEVEL: "warn", + }; + const w = { + i, + dbPath, + batches: 0, + lastExitCode: null, + alive: false, + proc: null, + stopRequested: false, + cpu_clk_ticks: 0, // cumulative cpu time for this worker's pids (utime+stime) + }; + + function loop() { + if (w.stopRequested || i >= state.desired_workers) { + w.alive = false; + return; + } + const proc = spawn(CLI, ["generate", `--bots=${state.batch_size}`], { + env, + stdio: ["ignore", "ignore", "pipe"], + }); + w.proc = proc; + w.alive = true; + let errBuf = ""; + proc.stderr.on("data", (d) => { + errBuf += d.toString(); + }); + proc.on("exit", (code) => { + // Accumulate cpu ticks from the dying process before we lose its /proc entry. + // (Already gone by here, but resourceUsage isn't available on children; + // we rely on /proc sampling during the run instead.) + w.lastExitCode = code; + if (code !== 0 && errBuf) { + state.errors.push({ + worker: i, + ts: Date.now(), + code, + msg: errBuf.slice(0, 200), + }); + if (state.errors.length > 50) state.errors.shift(); + } + if (code === 0) w.batches += 1; + w.proc = null; + if (!w.stopRequested && state.running && i < state.desired_workers) { + setImmediate(loop); + } else { + w.alive = false; + } + }); + } + + w.start = () => { + w.stopRequested = false; + loop(); + }; + w.stop = () => { + w.stopRequested = true; + if (w.proc && !w.proc.killed) { + try { w.proc.kill("SIGTERM"); } catch {} + } + }; + return w; +} + +function ensureWorkerCount() { + // Spawn / tear down to match desired_workers without touching live ones. + while (state.workers.length < state.desired_workers) { + const idx = state.workers.length; + const w = spawnWorker(idx); + state.workers.push(w); + if (state.running) w.start(); + } + // Surplus workers above desired_workers: tell them to stop after current batch. + for (let i = state.desired_workers; i < state.workers.length; i++) { + state.workers[i].stop(); + } +} + +function startAll() { + if (state.running) return; + state.errors = []; + // Read current bot count as our baseline so rate is "since Start", not "since DB inception". + const baseline = countAllBots(); + state.bots_at_start = baseline; + state.last_rate_bots = baseline; + state.last_rate_ts = Date.now(); + state.rate_window = [{ ts: Date.now(), total: baseline }]; + + state.running = true; + state.started_at = Date.now(); + state.stopped_at = null; + ensureWorkerCount(); + for (const w of state.workers.slice(0, state.desired_workers)) { + if (!w.alive) w.start(); + } +} + +function stopAll() { + if (!state.running) return; + state.running = false; + state.stopped_at = Date.now(); + for (const w of state.workers) { + try { w.stop(); } catch {} + } +} + +function countAllBots() { + let total = 0; + for (const w of state.workers) { + try { + if (existsSync(w.dbPath)) { + const db = new Database(w.dbPath, { readonly: true, fileMustExist: true }); + try { + const row = db.prepare("SELECT COUNT(*) AS c FROM bot").get(); + total += row?.c ?? 0; + } catch { + // schema not yet there + } + db.close(); + } + } catch { + // file mid-write - skip and pick up next tick + } + } + return total; +} + +function totalDbBytes() { + let bytes = 0; + for (const w of state.workers) { + try { + if (existsSync(w.dbPath)) bytes += statSync(w.dbPath).size; + } catch {} + } + return bytes; +} + +// ---------- CPU sampling ---------- +// Host CPU: read /host-proc/stat first line, compute delta from previous sample. +let hostPrev = null; +let hostPct = 0; + +function sampleHostCpu() { + try { + const line = readFileSync(HOST_PROC_STAT, "utf8").split("\n", 1)[0]; // "cpu u n s i iow irq sirq steal guest gnice" + const parts = line.trim().split(/\s+/).slice(1).map(Number); + const idle = (parts[3] || 0) + (parts[4] || 0); // idle + iowait + const total = parts.reduce((a, b) => a + b, 0); + if (hostPrev) { + const dTotal = total - hostPrev.total; + const dIdle = idle - hostPrev.idle; + hostPct = dTotal > 0 ? Math.max(0, Math.min(100, ((dTotal - dIdle) / dTotal) * 100)) : hostPct; + } + hostPrev = { total, idle }; + } catch { + hostPct = -1; // signal "unknown" + } +} + +let hostLoad = [0, 0, 0]; +function sampleHostLoad() { + try { + const txt = readFileSync(HOST_PROC_LOADAVG, "utf8"); + const parts = txt.trim().split(/\s+/).slice(0, 3).map(Number); + if (parts.every((n) => Number.isFinite(n))) hostLoad = parts; + } catch {} +} + +// Container worker CPU: sum utime+stime jiffies of all live worker pids +// across a sample window, divide by elapsed wall clock and host cores. +let workersPrev = null; +let workersPct = 0; + +function sampleWorkersCpu() { + try { + let ticks = 0; + let pids = 0; + for (const w of state.workers) { + const proc = w.proc; + if (!proc || proc.killed || proc.exitCode != null) continue; + const pid = proc.pid; + try { + const stat = readFileSync(`/proc/${pid}/stat`, "utf8"); + // Field 14 = utime, 15 = stime. comm field can contain spaces; split by last ')'. + const after = stat.slice(stat.lastIndexOf(")") + 2).trim().split(/\s+/); + // after[0] = state. utime is field 14 overall = after[11]; stime = after[12]. + const utime = Number(after[11]); + const stime = Number(after[12]); + if (Number.isFinite(utime) && Number.isFinite(stime)) { + ticks += utime + stime; + pids += 1; + } + } catch {} + } + const now = Date.now(); + if (workersPrev && now > workersPrev.ts) { + const dTicks = ticks - workersPrev.ticks; + const dSec = (now - workersPrev.ts) / 1000; + const cpuSec = dTicks / CLK_TCK; + workersPct = dSec > 0 ? Math.max(0, (cpuSec / dSec / TOTAL_HOST_CORES) * 100) : workersPct; + } + workersPrev = { ts: now, ticks, pids }; + } catch { + workersPct = -1; + } +} + +setInterval(() => { + sampleHostCpu(); + sampleHostLoad(); + sampleWorkersCpu(); +}, 1000).unref(); + +// ---------- Aggregate-leaderboard publish ---------- +// Same endpoint the browser swarm POSTs to. Keyed by sha256(api_key) +// so multiple sources (browser + this container) under the same +// operator key roll into one /profile//swarm page. +const publishState = { + enabled: !!OPERATOR_API_KEY, + endpoint: OPERATOR_API_KEY ? `${CENTRAL_URL}/v1/swarms/${OPERATOR_ID}/summary` : null, + last_status: null, // null | "ok" | "skipped" | "error" + last_status_at: null, + last_total_published: 0, + publishes_attempted: 0, + publishes_succeeded: 0, + last_error_msg: null, +}; + +async function publishOnce() { + if (!publishState.enabled) { + publishState.last_status = "skipped"; + publishState.last_status_at = Date.now(); + return; + } + const total = state.total_bots_cached || countAllBots(); + const now = Date.now(); + const delta = total - publishState.last_total_published; + const lastAt = publishState.last_status_at || 0; + const sinceLast = lastAt > 0 ? now - lastAt : Number.POSITIVE_INFINITY; + + // Volume-or-time gate, per Tim's spec: fire when EITHER condition + // is met (whichever comes first), but never closer together than + // PUBLISH_MIN_INTERVAL_MS so a burst can't hammer the central. + const volumeOk = delta >= PUBLISH_EVERY_BOTS; + const timeoutOk = sinceLast >= PUBLISH_MAX_INTERVAL_MS; + const floorOk = sinceLast >= PUBLISH_MIN_INTERVAL_MS; + + if (delta <= 0) { + publishState.last_status = "skipped"; + publishState.last_status_at = now; + return; + } + if (!floorOk) { + return; // tick again on the next poll + } + if (!volumeOk && !timeoutOk) { + // Not enough new bots AND not enough time elapsed: hold. + return; + } + publishState.publishes_attempted += 1; + const payload = { + total_bots: total, + // Pre-kickoff stub: every match still has all bots alive. Once + // matches resolve, a scoring pass should fill this in for real. + bots_alive_after_match_n: [], + best_bot_score: 0, + top_k: [], + // The merkle root would normally come from the bot-node `commit` + // pipeline; for the aggregate surface a constant-per-batch hash + // is acceptable. Hashing (operator_id || total) is cheap and + // deterministic so the server can dedupe identical re-POSTs. + merkle_root: createHash("sha256") + .update(`${OPERATOR_ID}::${total}::${FIRST_KICKOFF_AT}`) + .digest("hex"), + kickoff_at: FIRST_KICKOFF_AT, + generated_at: Date.now(), + }; + try { + const res = await fetch(publishState.endpoint, { + method: "POST", + headers: { + "content-type": "application/json", + Authorization: `Bearer ${OPERATOR_API_KEY}`, + }, + body: JSON.stringify(payload), + }); + if (!res.ok) { + const body = await res.text().catch(() => ""); + publishState.last_status = "error"; + publishState.last_status_at = Date.now(); + publishState.last_error_msg = `${res.status} ${body.slice(0, 200)}`; + return; + } + publishState.last_status = "ok"; + publishState.last_status_at = Date.now(); + publishState.last_total_published = total; + publishState.publishes_succeeded += 1; + publishState.last_error_msg = null; + } catch (err) { + publishState.last_status = "error"; + publishState.last_status_at = Date.now(); + publishState.last_error_msg = String(err?.message || err).slice(0, 200); + } +} + +if (publishState.enabled) { + // Poll on the minimum-interval cadence; publishOnce decides whether + // the volume or time-ceiling gate is met. PUBLISH_INTERVAL_MS is + // kept as a legacy alias for any operator who has it set explicitly. + const pollMs = Math.min(PUBLISH_MIN_INTERVAL_MS, PUBLISH_INTERVAL_MS); + setInterval(() => { + void publishOnce(); + }, pollMs).unref(); +} + +// ---------- Stats aggregation ---------- +function aggregateStats() { + // Cache the SELECT COUNT(*) for 500ms since a 1Hz poll opens 48 DBs. + const now = Date.now(); + if (now - state.total_bots_cached_at > 500) { + state.total_bots_cached = countAllBots(); + state.total_bots_cached_at = now; + state.rate_window.push({ ts: now, total: state.total_bots_cached }); + while (state.rate_window.length > 12 && now - state.rate_window[0].ts > 10_000) { + state.rate_window.shift(); + } + } + const totalBots = state.total_bots_cached; + + const alive = state.workers.slice(0, state.desired_workers).filter((w) => w.alive).length; + const batches = state.workers.reduce((sum, w) => sum + w.batches, 0); + + const elapsedMs = state.started_at ? (state.stopped_at ?? now) - state.started_at : 0; + const sessionBots = Math.max(totalBots - state.bots_at_start, 0); + const avgRate = elapsedMs > 0 ? sessionBots / (elapsedMs / 1000) : 0; + + // Rolling window rate: oldest-to-newest in last ~5s + let liveRate = 0; + if (state.rate_window.length >= 2) { + const first = state.rate_window[0]; + const last = state.rate_window[state.rate_window.length - 1]; + const dT = (last.ts - first.ts) / 1000; + liveRate = dT > 0 ? Math.max(0, (last.total - first.total) / dT) : 0; + } + + const remaining = Math.max(TARGET - totalBots, 0); + const etaSec = liveRate > 0 ? remaining / liveRate : null; + + return { + running: state.running, + started_at: state.started_at, + stopped_at: state.stopped_at, + elapsed_seconds: Math.floor(elapsedMs / 1000), + desired_workers: state.desired_workers, + max_workers: MAX_WORKERS, + workers_spawned: state.workers.length, + workers_alive: alive, + batch_size: state.batch_size, + batches_completed: batches, + total_bots: totalBots, + bots_this_session: sessionBots, + target_bots: TARGET, + progress_pct: TARGET > 0 ? (totalBots / TARGET) * 100 : 0, + bots_per_sec_live: Math.round(liveRate), + bots_per_sec_avg: Math.round(avgRate), + eta_seconds: etaSec, + db_bytes: totalDbBytes(), + host_cores: TOTAL_HOST_CORES, + host_mem_bytes: totalmem(), + host_cpu_pct: hostPct, + host_load_1m: hostLoad[0], + host_load_5m: hostLoad[1], + host_load_15m: hostLoad[2], + workers_cpu_pct_of_host: workersPct, + node_label: NODE_LABEL, + federation_mode: publishState.enabled + ? `auto-publishing to ${publishState.endpoint} every ${PUBLISH_INTERVAL_MS / 1000}s` + : "dry-run (no OPERATOR_API_KEY set; local only, never POSTs)", + publish: { + enabled: publishState.enabled, + operator_id: OPERATOR_ID || null, + endpoint: publishState.endpoint, + last_status: publishState.last_status, + last_status_at: publishState.last_status_at, + last_total_published: publishState.last_total_published, + attempts: publishState.publishes_attempted, + succeeded: publishState.publishes_succeeded, + last_error: publishState.last_error_msg, + }, + recent_errors: state.errors.slice(-5), + }; +} + +// ---------- HTML ---------- +const HTML = ` + + + +Tournamental Billion Bot - ${NODE_LABEL} + + + + +

Tournamental Billion Bot

+
node label ${NODE_LABEL} · dry-run (no central POSTs) · host ${TOTAL_HOST_CORES} cores
+ +
+
stopped
+
Elapsed: 00:00:00
+
+
+ +
+ + + + +
+ + 16 + 24 + 32 + 48 + 64 + 96 + + +
+ +
+ + 10k + 50k + 100k + 250k + 1M +
+
+ +
Throughput
+
+
Bots committed
-
+
Live rate (5s)
-
bots / sec
+
Avg rate (session)
-
bots / sec
+
ETA to ${(TARGET/1e9).toFixed(0)}B
-
+
Progress
-
+
Batches done
-
+
+ +
Aggregate publish
+
+
Publish status
-
+
Last published
-
+
POSTs ok / attempted
-
+
+ +
Capacity
+
+
Workers alive
-
+
Container CPU
-
% of host (sum of workers)
+
Host CPU
-
% across all cores
+
Host load 1m / 5m / 15m
-
+
DB on disk
-
across all worker DBs
+
Batch size
-
bots per worker per batch
+
+ +
+ +
+ Raw stats JSON + 
loading...
+
+ +
+ JSON: /api/stats · + Configure: POST /api/configure {workers, batch_size} · + Federation: dry-run only. Picks stay in this container. +
+ + + +`; + +// ---------- HTTP server ---------- +const server = createServer(async (req, res) => { + if (req.method === "GET" && (req.url === "/" || req.url === "/index.html")) { + res.writeHead(200, { "content-type": "text/html; charset=utf-8" }); + res.end(HTML); + return; + } + if (req.method === "GET" && req.url === "/health") { + res.writeHead(200, { "content-type": "application/json" }); + res.end(JSON.stringify({ ok: true, ts: Date.now() })); + return; + } + if (req.method === "GET" && req.url === "/api/stats") { + const s = aggregateStats(); + res.writeHead(200, { "content-type": "application/json" }); + res.end(JSON.stringify(s, null, 2)); + return; + } + if (req.method === "POST" && req.url === "/api/start") { + startAll(); + res.writeHead(202, { "content-type": "application/json" }); + res.end(JSON.stringify({ started: true, workers: state.desired_workers })); + return; + } + if (req.method === "POST" && req.url === "/api/stop") { + stopAll(); + res.writeHead(202, { "content-type": "application/json" }); + res.end(JSON.stringify({ stopped: true })); + return; + } + if (req.method === "POST" && req.url === "/api/configure") { + let body = ""; + req.on("data", (c) => (body += c)); + req.on("end", () => { + let cfg = {}; + try { cfg = body ? JSON.parse(body) : {}; } catch {} + if (typeof cfg.workers === "number" && cfg.workers > 0) { + state.desired_workers = Math.min(Math.max(1, Math.floor(cfg.workers)), MAX_WORKERS); + ensureWorkerCount(); + } + if (typeof cfg.batch_size === "number" && cfg.batch_size > 0) { + state.batch_size = Math.max(1, Math.floor(cfg.batch_size)); + } + res.writeHead(202, { "content-type": "application/json" }); + res.end(JSON.stringify({ + desired_workers: state.desired_workers, + batch_size: state.batch_size, + })); + }); + return; + } + res.writeHead(404, { "content-type": "application/json" }); + res.end(JSON.stringify({ error: "not_found" })); +}); + +server.listen(PORT, HOST, () => { + process.stdout.write( + `billion-bot dashboard up on http://${HOST}:${PORT} - workers=${INITIAL_WORKERS} (max ${MAX_WORKERS}) batch=${INITIAL_BATCH} target=${TARGET} cores=${TOTAL_HOST_CORES}\n`, + ); +}); + +function shutdown() { + stopAll(); + server.close(() => process.exit(0)); + setTimeout(() => process.exit(0), 2000).unref(); +} +process.on("SIGINT", shutdown); +process.on("SIGTERM", shutdown); diff --git a/apps/billion-bot/demo-matches.json b/apps/billion-bot/demo-matches.json new file mode 100644 index 00000000..fa56bcbf --- /dev/null +++ b/apps/billion-bot/demo-matches.json @@ -0,0 +1,29 @@ +[ + { + "match_id": "wc2026-grp-a-01", + "tournament_id": "fifa-wc-2026", + "home_team": "Mexico", + "away_team": "TBD", + "kickoff_utc": "2027-06-11T20:00:00Z", + "allows_draw": true, + "odds": { "home_win": 0.55, "draw": 0.25, "away_win": 0.20 } + }, + { + "match_id": "wc2026-grp-b-01", + "tournament_id": "fifa-wc-2026", + "home_team": "Canada", + "away_team": "TBD", + "kickoff_utc": "2027-06-12T18:00:00Z", + "allows_draw": true, + "odds": { "home_win": 0.48, "draw": 0.27, "away_win": 0.25 } + }, + { + "match_id": "wc2026-grp-c-01", + "tournament_id": "fifa-wc-2026", + "home_team": "USA", + "away_team": "TBD", + "kickoff_utc": "2027-06-12T22:00:00Z", + "allows_draw": true, + "odds": { "home_win": 0.50, "draw": 0.26, "away_win": 0.24 } + } +] diff --git a/apps/billion-bot/docker-compose.yml b/apps/billion-bot/docker-compose.yml new file mode 100644 index 00000000..7574f073 --- /dev/null +++ b/apps/billion-bot/docker-compose.yml @@ -0,0 +1,49 @@ +services: + billion-bot: + image: tournamental/billion-bot:dev + build: + context: . + container_name: tournamental-billion-bot + restart: unless-stopped + environment: + WORKERS: ${WORKERS:-48} + BATCH_SIZE: ${BATCH_SIZE:-100000} + TARGET_BOTS: ${TARGET_BOTS:-1000000000} + NODE_LABEL: ${NODE_LABEL:-vtorn-dev-1b-test} + MAX_WORKERS: ${MAX_WORKERS:-96} + HOST_PROC_STAT: /host-proc/stat + DASH_PORT: 4080 + DASH_HOST: 0.0.0.0 + # Aggregate-leaderboard publish path. When OPERATOR_API_KEY is + # set the dashboard auto-POSTs /v1/swarms//summary + # to CENTRAL_URL every 30s, same idempotency keys the browser + # swarm uses. Leave the key unset to keep the run dry / local-only. + OPERATOR_API_KEY: ${OPERATOR_API_KEY:-} + CENTRAL_URL: ${CENTRAL_URL:-https://api.tournamental.com} + PUBLISH_INTERVAL_MS: ${PUBLISH_INTERVAL_MS:-30000} + # No CPU limit - let the dashboard throttle dynamically. + volumes: + # Named volume lands under /var/lib/docker/volumes/ which is on + # /dev/sdb1 here, keeping the multi-GB SQLite files off the main + # disk. ./data was on /dev/sda2 and filled / to 99% last time. + - billion_bot_data:/app/data + # Read-only bind mount of host /proc/stat so the dashboard can + # report host-level CPU usage. /proc is per-pid-namespace inside + # the container; this exposes the host's view. + - /proc/stat:/host-proc/stat:ro + - /proc/loadavg:/host-proc/loadavg:ro + # Bound to 0.0.0.0 so Tailscale (100.x) + LAN (192.168.x) + WireGuard + # (10.x) can reach the dashboard. There's no public ingress on this + # box (everything behind CF tunnels), so this only exposes to + # networks Tim is already on. + ports: + - "0.0.0.0:4080:4080" + healthcheck: + test: ["CMD", "curl", "-fsS", "http://127.0.0.1:4080/health"] + interval: 30s + timeout: 5s + retries: 3 + +volumes: + billion_bot_data: + name: billion_bot_data diff --git a/apps/billion-bot/fifa-wc-2026-fixtures.json b/apps/billion-bot/fifa-wc-2026-fixtures.json new file mode 100644 index 00000000..917541f3 --- /dev/null +++ b/apps/billion-bot/fifa-wc-2026-fixtures.json @@ -0,0 +1 @@ +[{"match_id":"wc2026-m001","tournament_id":"fifa-wc-2026","home_team":"MEX","away_team":"RSA","kickoff_utc":"2026-06-11T19:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m002","tournament_id":"fifa-wc-2026","home_team":"KOR","away_team":"CZE","kickoff_utc":"2026-06-12T22:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m003","tournament_id":"fifa-wc-2026","home_team":"MEX","away_team":"KOR","kickoff_utc":"2026-06-18T19:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m004","tournament_id":"fifa-wc-2026","home_team":"CZE","away_team":"RSA","kickoff_utc":"2026-06-18T22:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m005","tournament_id":"fifa-wc-2026","home_team":"CZE","away_team":"MEX","kickoff_utc":"2026-06-24T20:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m006","tournament_id":"fifa-wc-2026","home_team":"RSA","away_team":"KOR","kickoff_utc":"2026-06-24T23:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m007","tournament_id":"fifa-wc-2026","home_team":"CAN","away_team":"BIH","kickoff_utc":"2026-06-12T19:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m008","tournament_id":"fifa-wc-2026","home_team":"QAT","away_team":"SUI","kickoff_utc":"2026-06-13T22:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m009","tournament_id":"fifa-wc-2026","home_team":"CAN","away_team":"QAT","kickoff_utc":"2026-06-18T19:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m010","tournament_id":"fifa-wc-2026","home_team":"SUI","away_team":"BIH","kickoff_utc":"2026-06-19T22:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m011","tournament_id":"fifa-wc-2026","home_team":"SUI","away_team":"CAN","kickoff_utc":"2026-06-24T20:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m012","tournament_id":"fifa-wc-2026","home_team":"BIH","away_team":"QAT","kickoff_utc":"2026-06-25T23:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m013","tournament_id":"fifa-wc-2026","home_team":"BRA","away_team":"MAR","kickoff_utc":"2026-06-13T16:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m014","tournament_id":"fifa-wc-2026","home_team":"HAI","away_team":"SCO","kickoff_utc":"2026-06-13T19:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m015","tournament_id":"fifa-wc-2026","home_team":"BRA","away_team":"HAI","kickoff_utc":"2026-06-19T16:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m016","tournament_id":"fifa-wc-2026","home_team":"SCO","away_team":"MAR","kickoff_utc":"2026-06-19T19:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m017","tournament_id":"fifa-wc-2026","home_team":"SCO","away_team":"BRA","kickoff_utc":"2026-06-25T17:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m018","tournament_id":"fifa-wc-2026","home_team":"MAR","away_team":"HAI","kickoff_utc":"2026-06-25T20:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m019","tournament_id":"fifa-wc-2026","home_team":"USA","away_team":"PAR","kickoff_utc":"2026-06-12T19:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m020","tournament_id":"fifa-wc-2026","home_team":"AUS","away_team":"TUR","kickoff_utc":"2026-06-13T22:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m021","tournament_id":"fifa-wc-2026","home_team":"USA","away_team":"AUS","kickoff_utc":"2026-06-19T19:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m022","tournament_id":"fifa-wc-2026","home_team":"TUR","away_team":"PAR","kickoff_utc":"2026-06-19T22:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m023","tournament_id":"fifa-wc-2026","home_team":"TUR","away_team":"USA","kickoff_utc":"2026-06-25T20:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m024","tournament_id":"fifa-wc-2026","home_team":"PAR","away_team":"AUS","kickoff_utc":"2026-06-25T23:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m025","tournament_id":"fifa-wc-2026","home_team":"GER","away_team":"CUW","kickoff_utc":"2026-06-13T16:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m026","tournament_id":"fifa-wc-2026","home_team":"CIV","away_team":"ECU","kickoff_utc":"2026-06-14T19:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m027","tournament_id":"fifa-wc-2026","home_team":"GER","away_team":"CIV","kickoff_utc":"2026-06-19T16:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m028","tournament_id":"fifa-wc-2026","home_team":"ECU","away_team":"CUW","kickoff_utc":"2026-06-20T19:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m029","tournament_id":"fifa-wc-2026","home_team":"ECU","away_team":"GER","kickoff_utc":"2026-06-25T17:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m030","tournament_id":"fifa-wc-2026","home_team":"CUW","away_team":"CIV","kickoff_utc":"2026-06-26T20:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m031","tournament_id":"fifa-wc-2026","home_team":"NED","away_team":"JPN","kickoff_utc":"2026-06-14T18:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m032","tournament_id":"fifa-wc-2026","home_team":"SWE","away_team":"TUN","kickoff_utc":"2026-06-14T21:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m033","tournament_id":"fifa-wc-2026","home_team":"NED","away_team":"SWE","kickoff_utc":"2026-06-20T18:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m034","tournament_id":"fifa-wc-2026","home_team":"TUN","away_team":"JPN","kickoff_utc":"2026-06-20T21:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m035","tournament_id":"fifa-wc-2026","home_team":"TUN","away_team":"NED","kickoff_utc":"2026-06-26T19:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m036","tournament_id":"fifa-wc-2026","home_team":"JPN","away_team":"SWE","kickoff_utc":"2026-06-26T22:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m037","tournament_id":"fifa-wc-2026","home_team":"BEL","away_team":"EGY","kickoff_utc":"2026-06-14T16:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m038","tournament_id":"fifa-wc-2026","home_team":"IRN","away_team":"NZL","kickoff_utc":"2026-06-15T19:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m039","tournament_id":"fifa-wc-2026","home_team":"BEL","away_team":"IRN","kickoff_utc":"2026-06-20T16:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m040","tournament_id":"fifa-wc-2026","home_team":"NZL","away_team":"EGY","kickoff_utc":"2026-06-21T19:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m041","tournament_id":"fifa-wc-2026","home_team":"NZL","away_team":"BEL","kickoff_utc":"2026-06-26T17:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m042","tournament_id":"fifa-wc-2026","home_team":"EGY","away_team":"IRN","kickoff_utc":"2026-06-27T20:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m043","tournament_id":"fifa-wc-2026","home_team":"ESP","away_team":"CPV","kickoff_utc":"2026-06-15T19:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m044","tournament_id":"fifa-wc-2026","home_team":"KSA","away_team":"URU","kickoff_utc":"2026-06-15T22:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m045","tournament_id":"fifa-wc-2026","home_team":"ESP","away_team":"KSA","kickoff_utc":"2026-06-21T19:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m046","tournament_id":"fifa-wc-2026","home_team":"URU","away_team":"CPV","kickoff_utc":"2026-06-21T22:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m047","tournament_id":"fifa-wc-2026","home_team":"URU","away_team":"ESP","kickoff_utc":"2026-06-27T20:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m048","tournament_id":"fifa-wc-2026","home_team":"CPV","away_team":"KSA","kickoff_utc":"2026-06-27T23:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m049","tournament_id":"fifa-wc-2026","home_team":"FRA","away_team":"SEN","kickoff_utc":"2026-06-15T16:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m050","tournament_id":"fifa-wc-2026","home_team":"IRQ","away_team":"NOR","kickoff_utc":"2026-06-16T19:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m051","tournament_id":"fifa-wc-2026","home_team":"FRA","away_team":"IRQ","kickoff_utc":"2026-06-21T16:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m052","tournament_id":"fifa-wc-2026","home_team":"NOR","away_team":"SEN","kickoff_utc":"2026-06-22T19:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m053","tournament_id":"fifa-wc-2026","home_team":"NOR","away_team":"FRA","kickoff_utc":"2026-06-27T17:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m054","tournament_id":"fifa-wc-2026","home_team":"SEN","away_team":"IRQ","kickoff_utc":"2026-06-27T20:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m055","tournament_id":"fifa-wc-2026","home_team":"ARG","away_team":"ALG","kickoff_utc":"2026-06-16T18:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m056","tournament_id":"fifa-wc-2026","home_team":"AUT","away_team":"JOR","kickoff_utc":"2026-06-16T21:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m057","tournament_id":"fifa-wc-2026","home_team":"ARG","away_team":"AUT","kickoff_utc":"2026-06-22T18:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m058","tournament_id":"fifa-wc-2026","home_team":"JOR","away_team":"ALG","kickoff_utc":"2026-06-22T21:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m059","tournament_id":"fifa-wc-2026","home_team":"JOR","away_team":"ARG","kickoff_utc":"2026-06-27T19:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m060","tournament_id":"fifa-wc-2026","home_team":"ALG","away_team":"AUT","kickoff_utc":"2026-06-27T22:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m061","tournament_id":"fifa-wc-2026","home_team":"POR","away_team":"COD","kickoff_utc":"2026-06-16T19:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m062","tournament_id":"fifa-wc-2026","home_team":"UZB","away_team":"COL","kickoff_utc":"2026-06-17T22:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m063","tournament_id":"fifa-wc-2026","home_team":"POR","away_team":"UZB","kickoff_utc":"2026-06-22T19:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m064","tournament_id":"fifa-wc-2026","home_team":"COL","away_team":"COD","kickoff_utc":"2026-06-23T22:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m065","tournament_id":"fifa-wc-2026","home_team":"COL","away_team":"POR","kickoff_utc":"2026-06-27T20:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m066","tournament_id":"fifa-wc-2026","home_team":"COD","away_team":"UZB","kickoff_utc":"2026-06-27T23:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m067","tournament_id":"fifa-wc-2026","home_team":"ENG","away_team":"CRO","kickoff_utc":"2026-06-17T18:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m068","tournament_id":"fifa-wc-2026","home_team":"GHA","away_team":"PAN","kickoff_utc":"2026-06-17T21:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m069","tournament_id":"fifa-wc-2026","home_team":"ENG","away_team":"GHA","kickoff_utc":"2026-06-23T18:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m070","tournament_id":"fifa-wc-2026","home_team":"PAN","away_team":"CRO","kickoff_utc":"2026-06-23T21:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m071","tournament_id":"fifa-wc-2026","home_team":"PAN","away_team":"ENG","kickoff_utc":"2026-06-27T19:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m072","tournament_id":"fifa-wc-2026","home_team":"CRO","away_team":"GHA","kickoff_utc":"2026-06-27T22:00:00Z","allows_draw":true,"odds":{"home_win":0.45,"draw":0.25,"away_win":0.3}},{"match_id":"wc2026-m073","tournament_id":"fifa-wc-2026","home_team":"1A","away_team":"2C","kickoff_utc":"2026-06-28T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m074","tournament_id":"fifa-wc-2026","home_team":"1B","away_team":"2F","kickoff_utc":"2026-06-28T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m075","tournament_id":"fifa-wc-2026","home_team":"1C","away_team":"2A","kickoff_utc":"2026-06-29T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m076","tournament_id":"fifa-wc-2026","home_team":"1D","away_team":"2E","kickoff_utc":"2026-06-29T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m077","tournament_id":"fifa-wc-2026","home_team":"1E","away_team":"2D","kickoff_utc":"2026-06-30T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m078","tournament_id":"fifa-wc-2026","home_team":"1F","away_team":"2B","kickoff_utc":"2026-06-30T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m079","tournament_id":"fifa-wc-2026","home_team":"1G","away_team":"2H","kickoff_utc":"2026-07-01T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m080","tournament_id":"fifa-wc-2026","home_team":"1H","away_team":"2G","kickoff_utc":"2026-07-01T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m081","tournament_id":"fifa-wc-2026","home_team":"1I","away_team":"2L","kickoff_utc":"2026-07-02T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m082","tournament_id":"fifa-wc-2026","home_team":"1J","away_team":"2K","kickoff_utc":"2026-07-02T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m083","tournament_id":"fifa-wc-2026","home_team":"1K","away_team":"2J","kickoff_utc":"2026-07-03T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m084","tournament_id":"fifa-wc-2026","home_team":"1L","away_team":"2I","kickoff_utc":"2026-07-03T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m085","tournament_id":"fifa-wc-2026","home_team":"3A/B/C/D","away_team":"3E/F/G/H","kickoff_utc":"2026-07-03T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m086","tournament_id":"fifa-wc-2026","home_team":"3I/J/K/L","away_team":"3A/B/E/F","kickoff_utc":"2026-07-03T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m087","tournament_id":"fifa-wc-2026","home_team":"3C/D/G/H","away_team":"3I/J/K/L","kickoff_utc":"2026-07-03T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m088","tournament_id":"fifa-wc-2026","home_team":"3A/B/F/J","away_team":"3C/E/H/I","kickoff_utc":"2026-07-03T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m089","tournament_id":"fifa-wc-2026","home_team":"W73","away_team":"W74","kickoff_utc":"2026-07-04T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m090","tournament_id":"fifa-wc-2026","home_team":"W75","away_team":"W76","kickoff_utc":"2026-07-04T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m091","tournament_id":"fifa-wc-2026","home_team":"W77","away_team":"W78","kickoff_utc":"2026-07-05T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m092","tournament_id":"fifa-wc-2026","home_team":"W79","away_team":"W80","kickoff_utc":"2026-07-05T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m093","tournament_id":"fifa-wc-2026","home_team":"W81","away_team":"W82","kickoff_utc":"2026-07-06T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m094","tournament_id":"fifa-wc-2026","home_team":"W83","away_team":"W84","kickoff_utc":"2026-07-06T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m095","tournament_id":"fifa-wc-2026","home_team":"W85","away_team":"W86","kickoff_utc":"2026-07-07T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m096","tournament_id":"fifa-wc-2026","home_team":"W87","away_team":"W88","kickoff_utc":"2026-07-07T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m097","tournament_id":"fifa-wc-2026","home_team":"W89","away_team":"W90","kickoff_utc":"2026-07-09T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m098","tournament_id":"fifa-wc-2026","home_team":"W91","away_team":"W92","kickoff_utc":"2026-07-09T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m099","tournament_id":"fifa-wc-2026","home_team":"W93","away_team":"W94","kickoff_utc":"2026-07-11T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m100","tournament_id":"fifa-wc-2026","home_team":"W95","away_team":"W96","kickoff_utc":"2026-07-11T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m101","tournament_id":"fifa-wc-2026","home_team":"W97","away_team":"W98","kickoff_utc":"2026-07-14T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m102","tournament_id":"fifa-wc-2026","home_team":"W99","away_team":"W100","kickoff_utc":"2026-07-15T20:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m103","tournament_id":"fifa-wc-2026","home_team":"L101","away_team":"L102","kickoff_utc":"2026-07-18T19:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}},{"match_id":"wc2026-m104","tournament_id":"fifa-wc-2026","home_team":"W101","away_team":"W102","kickoff_utc":"2026-07-19T19:00:00Z","allows_draw":false,"odds":{"home_win":0.45,"draw":0.0,"away_win":0.55}}] \ No newline at end of file diff --git a/apps/billion-bot/package.json b/apps/billion-bot/package.json new file mode 100644 index 00000000..1f6685ae --- /dev/null +++ b/apps/billion-bot/package.json @@ -0,0 +1,11 @@ +{ + "name": "@vtorn/billion-bot", + "version": "0.1.0", + "private": true, + "type": "module", + "description": "Tournamental billion-bot dashboard - wraps @tournamental/bot-node", + "dependencies": { + "@tournamental/bot-node": "file:./tournamental-bot-node-0.3.0.tgz", + "better-sqlite3": "11.3.0" + } +} diff --git a/apps/game/migrations/0013_bot_arena.sql b/apps/game/migrations/0013_bot_arena.sql new file mode 100644 index 00000000..bf5c9d49 --- /dev/null +++ b/apps/game/migrations/0013_bot_arena.sql @@ -0,0 +1,114 @@ +-- 0013_bot_arena.sql , Open Bot Arena schema (Phase 1 + Phase 2 hooks). +-- +-- Phase 1 ships the FIFA WC 2026 launch on 11 June 2026: ~18k seeded +-- bot users, external bot operators via the bot SDK, and a leaderboard +-- that splits humans vs bots. Phase 2 (post-launch, in-tournament) +-- onboards federated node operators who run their own swarms and +-- report aggregates back to the central tier. +-- +-- Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md +-- +-- New columns: +-- * users.is_bot , mirror of apps/auth-sms users.is_bot +-- so the leaderboard scope filter can +-- join cheaply (§5.2). +-- * brackets.committed_at_utc , Phase 2 forward-compat audit hook +-- per §15.6 , every kickoff OTS +-- commitment stamps the picks it +-- anchored so federated nodes can +-- reconstruct which picks landed in +-- which on-chain commit later. +-- +-- New tables: +-- * bot_owner , ties a bot user to the API key that +-- issued it (§7.2 ownership check). +-- * api_key , per-developer API key hashes + +-- quotas (§6.3, §8.1). +-- * quota_window , sliding hourly pick-quota ledger +-- (§6.4). +-- * federated_node , Phase 2 node registry (§15.2 init). +-- * federated_leaderboard_snapshot +-- , Phase 2 post-match aggregate +-- report (§15.2 outcome flow). + +-- --------------------------------------------------------------- +-- Phase 1: bot identity + ownership + quota +-- --------------------------------------------------------------- + +ALTER TABLE users ADD COLUMN is_bot INTEGER NOT NULL DEFAULT 0; +CREATE INDEX IF NOT EXISTS idx_users_is_bot ON users(is_bot); + +ALTER TABLE brackets ADD COLUMN committed_at_utc INTEGER; +CREATE INDEX IF NOT EXISTS idx_brackets_committed_at + ON brackets(committed_at_utc); + +CREATE TABLE IF NOT EXISTS bot_owner ( + bot_id TEXT PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE, + owner_email TEXT NOT NULL, + owner_api_key_hash TEXT NOT NULL, + created_at INTEGER NOT NULL +); +CREATE INDEX IF NOT EXISTS idx_bot_owner_email ON bot_owner(owner_email); +CREATE INDEX IF NOT EXISTS idx_bot_owner_key ON bot_owner(owner_api_key_hash); + +CREATE TABLE IF NOT EXISTS api_key ( + key_hash TEXT PRIMARY KEY, + owner_email TEXT NOT NULL, + label TEXT, + quota_bots INTEGER NOT NULL DEFAULT 1000, + quota_picks_per_hour INTEGER NOT NULL DEFAULT 100000, + created_at INTEGER NOT NULL, + revoked_at INTEGER +); +CREATE INDEX IF NOT EXISTS idx_api_key_owner ON api_key(owner_email); + +-- Sliding-hour quota ledger. window_start = floor(now_ms / 3600000) * 3600000. +CREATE TABLE IF NOT EXISTS quota_window ( + api_key_hash TEXT NOT NULL, + window_start INTEGER NOT NULL, + picks_used INTEGER NOT NULL DEFAULT 0, + PRIMARY KEY (api_key_hash, window_start) +); + +-- --------------------------------------------------------------- +-- Phase 2 hooks: federated node registry + aggregate snapshots +-- --------------------------------------------------------------- + +-- One row per registered external node operator. owner_api_key_hash +-- is the sha256 of the credential issued at registration time and is +-- used to authenticate POST /v1/nodes/commit and /v1/nodes/leaderboard +-- without inventing a second auth scheme. +CREATE TABLE IF NOT EXISTS federated_node ( + node_id TEXT PRIMARY KEY, + owner_email TEXT NOT NULL, + owner_api_key_hash TEXT NOT NULL, + public_url TEXT NOT NULL, + label TEXT, + registered_at INTEGER NOT NULL, + last_seen_at INTEGER +); +CREATE INDEX IF NOT EXISTS idx_federated_node_owner + ON federated_node(owner_email); +CREATE INDEX IF NOT EXISTS idx_federated_node_key + ON federated_node(owner_api_key_hash); + +-- Per-match aggregate report published by a federated node. The +-- merkle_root and bot_count land pre-kickoff via /v1/nodes/commit; +-- the leaderboard fields land post-match via /v1/nodes/leaderboard. +-- We use ONE table for both because the (node_id, match_id) pair is +-- the natural primary key and the lifecycle (commit, then score) is +-- a single logical row. +CREATE TABLE IF NOT EXISTS federated_leaderboard_snapshot ( + node_id TEXT NOT NULL REFERENCES federated_node(node_id) ON DELETE CASCADE, + match_id TEXT NOT NULL, + merkle_root TEXT, + kickoff_at INTEGER, + total_bots INTEGER, + bots_correct INTEGER, + bots_still_perfect INTEGER, + top_json_blob TEXT, + submitted_at INTEGER NOT NULL, + PRIMARY KEY (node_id, match_id) +); +CREATE INDEX IF NOT EXISTS idx_fed_snapshot_match + ON federated_leaderboard_snapshot(match_id); diff --git a/apps/game/migrations/0014_swarm_claims.sql b/apps/game/migrations/0014_swarm_claims.sql new file mode 100644 index 00000000..1fde5665 --- /dev/null +++ b/apps/game/migrations/0014_swarm_claims.sql @@ -0,0 +1,74 @@ +-- 0014_swarm_claims.sql — browser-swarm federation + OTS proof storage. +-- +-- One row per (node_id, run_id) swarm-summary submission. The browser +-- swarm POSTs to /v1/swarm/commit when a run finishes; this table is +-- the durable home of the resulting record. We keep this separate from +-- federated_leaderboard_snapshot (which is per (node_id, match_id)) +-- because a single browser run produces ONE summary covering all +-- matches, and its merkle_root is the single thing that gets OTS- +-- timestamped. +-- +-- Lifecycle: +-- 1. POST /v1/swarm/commit lands a row with `ots_status='pending'` +-- and `pending_calendar_blobs` populated for the calendars that +-- ack'd within the request window (≥3 of 4 to count as success). +-- 2. The OTS scheduler periodically polls the calendars for upgrade +-- and rewrites `upgraded_ots_bytes` + `ots_status` to 'confirmed' +-- once a Bitcoin attestation lands. +-- 3. GET /v1/swarm/leaderboard ranks rows by claimed_score and +-- includes the proof URL. +-- 4. GET /v1/swarm/proof/ serves the upgraded .ots +-- file (or the pending one as a fallback). +-- +-- Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §15.6 + +CREATE TABLE IF NOT EXISTS swarm_claims ( + -- Composite key: a single node may submit many runs, but the same + -- (node_id, run_id) is idempotent. + node_id TEXT NOT NULL, + run_id TEXT NOT NULL, + -- Master seed used by the browser swarm to regenerate every bot's + -- bracket. Stored so the /verify route can replay any bot_index + -- locally without needing to trust the submitter. + master_seed TEXT NOT NULL, + strategy TEXT NOT NULL DEFAULT 'chalk-v1', + total_bots INTEGER NOT NULL, + -- Merkle root over all bots' picks. 64-char lower-hex sha256. + merkle_root TEXT NOT NULL, + -- Single best-score row the swarm is willing to attest to. Encoded + -- as JSON so the leaderboard route can render it without a schema + -- change every time the bot-arena scoring tweaks land. + -- Shape: { bot_index: number, claimed_score: number, picks_count: number } + top_n_claim_json TEXT NOT NULL, + claimed_score REAL NOT NULL DEFAULT 0, + started_at INTEGER NOT NULL, + finished_at INTEGER NOT NULL, + submitted_at INTEGER NOT NULL, + -- OTS proof state machine: pending | confirmed | failed. + ots_status TEXT NOT NULL DEFAULT 'pending', + -- JSON array of { calendar_url, pending_bytes_hex, submitted_at } + -- for every calendar that ack'd the submission. Populated at commit + -- time; immutable thereafter. + pending_calendar_blobs TEXT NOT NULL DEFAULT '[]', + -- Hex bytes of an UPGRADED OTS proof (with Bitcoin attestation), + -- once the scheduler finds one. Null while still pending. + upgraded_ots_hex TEXT, + upgraded_calendar_url TEXT, + upgraded_at INTEGER, + -- Last time the upgrade scheduler tried this row. NULL while + -- nothing has tried. + last_upgrade_attempt_at INTEGER, + + PRIMARY KEY (node_id, run_id) +); + +-- Cross-swarm ranking comes from a single column scan; the index keeps +-- the leaderboard top-100 read under 5ms even at 100k rows. +CREATE INDEX IF NOT EXISTS idx_swarm_claims_score + ON swarm_claims(claimed_score DESC); + +CREATE INDEX IF NOT EXISTS idx_swarm_claims_merkle_root + ON swarm_claims(merkle_root); + +CREATE INDEX IF NOT EXISTS idx_swarm_claims_status + ON swarm_claims(ots_status, last_upgrade_attempt_at); diff --git a/apps/game/migrations/0015_swarm_summary.sql b/apps/game/migrations/0015_swarm_summary.sql new file mode 100644 index 00000000..4ed27710 --- /dev/null +++ b/apps/game/migrations/0015_swarm_summary.sql @@ -0,0 +1,74 @@ +-- 0015_swarm_summary.sql , operator-keyed aggregate summaries published +-- by each swarm operator (browser tab at /run, Node operator running +-- @tournamental/bot-node, or any custom client). +-- +-- One row per (operator_id, kickoff_at). Idempotent: re-POSTing the +-- same payload for the same kickoff overwrites the prior row so a +-- recovering client can re-publish after a transient network failure +-- without duplicating leaderboard entries. +-- +-- Why a separate table from `swarm_claims` (0014): +-- - swarm_claims is per-run, OTS-anchored, and captures a single +-- best-bot claim. It exists to support the public verifiability +-- story (one merkle root → one OTS proof → one cross-swarm rank). +-- - swarm_summary is per-operator, periodic, and captures the FULL +-- aggregate (total bots ever generated, alive count by match +-- number, top-1000 leaderboard within the swarm). It exists so +-- viewers of an operator's profile get a cheap downloadable JSON +-- of their swarm aggregates, and so the perfect-track watcher can +-- surface "N bots still alive after match 80" on the home page. +-- +-- Spec: A13 task brief (operator publish endpoint + perfect-track watch). +-- +-- Cache strategy: GET /v1/swarms/ is served with +-- Cache-Control: public, s-maxage=60, stale-while-revalidate=300 so +-- Cloudflare's edge holds the JSON between origin polls. + +CREATE TABLE IF NOT EXISTS swarm_summary ( + -- The operator_id is the sha256 hash of the operator's API key + -- (matches api_key.key_hash). One hash per operator means the + -- profile aggregate naturally rolls up everything posted under + -- that key without inventing a second identity column. + operator_id TEXT NOT NULL, + -- ms-epoch of the kickoff this snapshot is aligned to. Combined + -- with operator_id this is the idempotency key for re-POSTs. + kickoff_at INTEGER NOT NULL, + -- Cumulative count of bots ever generated by this operator. + total_bots INTEGER NOT NULL, + -- JSON array of { n: number, alive_count: number }, one row per + -- resolved match. n is the 1-indexed match ordinal in the + -- canonical fixture order. + alive_by_match_json TEXT NOT NULL DEFAULT '[]', + -- 0..104 , highest match-count any bot in this swarm has nailed. + best_bot_score INTEGER NOT NULL DEFAULT 0, + -- JSON array of { bot_id, score, chalk_score } sorted by score + -- desc. Up to 1,000 rows. + top_k_json TEXT NOT NULL DEFAULT '[]', + -- 64-char lower-hex sha256 of the latest batch's merkle root. + merkle_root TEXT NOT NULL DEFAULT '', + generated_at INTEGER NOT NULL, + PRIMARY KEY (operator_id, kickoff_at) +); + +CREATE INDEX IF NOT EXISTS idx_swarm_summary_operator_kickoff + ON swarm_summary(operator_id, kickoff_at DESC); + +-- Best-score index lets the global aggregate leaderboard scan the +-- top 100 in O(log n). +CREATE INDEX IF NOT EXISTS idx_swarm_summary_best_score + ON swarm_summary(best_bot_score DESC); + +-- Perfect-track alert table. One row per operator that crossed the +-- match-80 threshold with bots still alive. The home page + the +-- /leaderboard badge poll this table to surface "N bots still on a +-- perfect track after match X". +CREATE TABLE IF NOT EXISTS perfect_track_alert ( + operator_id TEXT NOT NULL, + match_number INTEGER NOT NULL, + alive_count INTEGER NOT NULL, + detected_at INTEGER NOT NULL, + PRIMARY KEY (operator_id, match_number) +); + +CREATE INDEX IF NOT EXISTS idx_perfect_track_alert_match + ON perfect_track_alert(match_number DESC, alive_count DESC); diff --git a/apps/game/src/lib/merkle.ts b/apps/game/src/lib/merkle.ts new file mode 100644 index 00000000..47021273 --- /dev/null +++ b/apps/game/src/lib/merkle.ts @@ -0,0 +1,125 @@ +/** + * Sorted-pair sha256 merkle tree. + * + * Used by the OTS kickoff commitment job (and the federated nodes that + * will mirror it in Phase 2). The on-chain commit posts the root; any + * third party can later request a single bot's pick + inclusion proof + * and verify it against the root anchored on Bitcoin. + * + * Why sorted-pair: it lets a verifier compute the parent without + * needing to know which side of the pair the sibling was on. Saves + * one bit per proof step. Apaches the same construction as OpenZeppelin + * MerkleProof.sol so the on-chain verifier (Phase 2) ports trivially. + * + * Why a fresh in-game implementation when apps/vstamp already has a + * domain-separated merkle: vstamp's variant is RFC 6962 (left/right + * position encoded in the proof step) and is the right shape for that + * service's daily-root receipts. The Phase 2 federation audit needs + * the simpler sorted-pair variant so external operators can port the + * verifier to any language in 50 lines. + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §15.6 + */ +import { createHash } from "node:crypto"; + +export type Outcome = "home_win" | "draw" | "away_win"; + +export interface PickLeaf { + bot_id: string; + match_id: string; + outcome: Outcome; + /** locked_at_utc in epoch ms */ + t: number; +} + +export interface MerkleTree { + root: string; + /** Hex sha256 of every leaf, in input order. */ + leaves: string[]; + /** proofs[i] is the inclusion path for picks[i] (each entry is a hex sibling). */ + proofs: string[][]; +} + +function sha256Hex(bytes: Buffer): string { + return createHash("sha256").update(bytes).digest("hex"); +} + +function sha256ConcatHex(a: string, b: string): string { + return sha256Hex(Buffer.from(a + b, "hex")); +} + +export function leafHash( + bot_id: string, + match_id: string, + outcome: string, + t: number, +): string { + return sha256Hex( + Buffer.from(`${bot_id}|${match_id}|${outcome}|${t}`, "utf8"), + ); +} + +function pairHash(a: string, b: string): string { + // Sort lexicographically so the parent is independent of left/right order. + return a <= b ? sha256ConcatHex(a, b) : sha256ConcatHex(b, a); +} + +/** + * Build the tree. Empty picks produce the canonical empty-tree root + * (sha256 of the empty string) so callers do not have to special-case + * "no picks landed pre-kickoff". + */ +export function buildMerkle(picks: readonly PickLeaf[]): MerkleTree { + if (picks.length === 0) { + return { + root: sha256Hex(Buffer.alloc(0)), + leaves: [], + proofs: [], + }; + } + const leaves = picks.map((p) => + leafHash(p.bot_id, p.match_id, p.outcome, p.t), + ); + if (leaves.length === 1) { + return { root: leaves[0]!, leaves, proofs: [[]] }; + } + // Build every level. Duplicate the trailing node on odd levels. + const levels: string[][] = [leaves.slice()]; + while (levels[levels.length - 1]!.length > 1) { + const cur = levels[levels.length - 1]!; + if (cur.length % 2 === 1) cur.push(cur[cur.length - 1]!); + const next: string[] = []; + for (let i = 0; i < cur.length; i += 2) { + next.push(pairHash(cur[i]!, cur[i + 1]!)); + } + levels.push(next); + } + const root = levels[levels.length - 1]![0]!; + const proofs = leaves.map((_, idx) => buildProof(levels, idx)); + return { root, leaves, proofs }; +} + +function buildProof(levels: readonly string[][], leafIdx: number): string[] { + const proof: string[] = []; + let idx = leafIdx; + for (let lvl = 0; lvl < levels.length - 1; lvl++) { + const level = levels[lvl]!; + const siblingIdx = idx % 2 === 0 ? idx + 1 : idx - 1; + const sibling = level[siblingIdx]; + if (sibling !== undefined) proof.push(sibling); + idx = Math.floor(idx / 2); + } + return proof; +} + +export function verifyProof( + leaf: string, + proof: readonly string[], + root: string, +): boolean { + let h = leaf; + for (const sib of proof) { + h = pairHash(h, sib); + } + return h === root; +} diff --git a/apps/game/src/lib/ots-calendar.ts b/apps/game/src/lib/ots-calendar.ts new file mode 100644 index 00000000..54059386 --- /dev/null +++ b/apps/game/src/lib/ots-calendar.ts @@ -0,0 +1,440 @@ +/** + * OpenTimestamps calendar HTTP client. + * + * The OTS protocol is dead simple at the wire level (full spec at + * https://github.com/opentimestamps/python-opentimestamps and + * https://petertodd.org/2016/opentimestamps-announcement). For our + * purposes a "Timestamp" is: + * + * - A starting 32-byte SHA-256 digest of the user data. + * - A sequence of cryptographic ops (append / prepend bytes, then + * hash with sha256 / ripemd160) that walk the digest toward an + * "attestation". The two attestations we care about are: + * + * * Pending calendar attestation: the calendar will eventually + * include this digest in a Bitcoin transaction. Present + * within ~1s of submission. + * * Bitcoin block-header attestation: the digest is committed + * in the Merkle root of the named block. Lands once the + * calendar has aggregated enough digests and posted a tx, + * which is on the order of an hour. + * + * Wire protocol per OTS calendar (a.lt.opentimestamps.org etc.): + * + * POST /digest body = raw 32-byte SHA-256 + * 200 OK, body = binary "Timestamp" ops (no magic header, + * starts at the first op after the input + * digest) + * + * GET /timestamp/ hex = lowercase 64-char SHA-256 + * 200 OK, body = the upgraded Timestamp ops (same shape, longer + * once a Bitcoin attestation is appended) + * 404 = digest not known to this calendar yet (still pending + * aggregation; retry later) + * + * The `.ots` file format adds a fixed magic header + version byte + + * a FileHash header that encodes (hash algorithm, original digest) + * before the ops. We emit that here so the file produced by + * `serialiseOtsFile()` is byte-compatible with the official + * `ots verify` CLI. + * + * The handwritten approach keeps us off the heavy `bitcore-lib` + * dependency tree that the `opentimestamps` npm package drags in. + * For Phase 1 we only need to: + * - Submit a root to N calendars + * - Persist the calendar-pending blobs + * - Poll for upgrades + * - Serve the canonical `.ots` file via the verify route + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §15.6 + */ + +import { setTimeout as delay } from "node:timers/promises"; + +/** Default public calendar servers (free, no auth). */ +export const DEFAULT_CALENDARS: readonly string[] = [ + "https://a.pool.opentimestamps.org", + "https://b.pool.opentimestamps.org", + "https://a.pool.eternitywall.com", + "https://finney.calendar.eternitywall.com", +]; + +/** OTS file header (magic bytes 31 chars), version 1, SHA-256 hash tag. */ +const OTS_MAGIC = new Uint8Array([ + 0x00, 0x4f, 0x70, 0x65, 0x6e, 0x54, 0x69, 0x6d, 0x65, 0x73, 0x74, 0x61, 0x6d, + 0x70, 0x73, 0x00, 0x00, 0x50, 0x72, 0x6f, 0x6f, 0x66, 0x00, 0xbf, 0x89, 0xe2, + 0xe8, 0x84, 0xe8, 0x92, 0x94, +]); +const OTS_VERSION = 0x01; +/** Op tag for SHA-256 (per python-opentimestamps `ops.py::OpSHA256`). */ +const OP_SHA256_TAG = 0x08; + +export interface CalendarSubmissionResult { + readonly calendar_url: string; + /** Raw bytes returned by POST /digest. Pending calendar attestation + * is encoded inside; no upgrade yet. */ + readonly pending_bytes: Uint8Array; + readonly submitted_at: number; +} + +export interface CalendarUpgradeResult { + readonly calendar_url: string; + readonly upgraded_bytes: Uint8Array; + readonly upgraded_at: number; + /** True iff the bytes contain a Bitcoin block attestation (heuristic + * match on the `0x05` BTC block attestation tag). */ + readonly bitcoin_confirmed: boolean; +} + +export interface SubmitOptions { + /** Override the default calendar set. */ + readonly calendars?: readonly string[]; + /** Per-request timeout in ms. Default 10s. */ + readonly timeoutMs?: number; + /** Override fetch (used by tests). */ + readonly fetchImpl?: typeof fetch; +} + +export interface UpgradeOptions { + readonly calendar_url: string; + readonly digest_hex: string; + readonly timeoutMs?: number; + readonly fetchImpl?: typeof fetch; +} + +/** OTS calendars sometimes redirect or block clients without a UA. */ +const USER_AGENT = "tournamental-ots/0.1 (+https://tournamental.com)"; + +function hexToBytes(hex: string): Uint8Array { + if (hex.length % 2 !== 0) { + throw new Error(`hex string has odd length: ${hex.length}`); + } + const out = new Uint8Array(hex.length / 2); + for (let i = 0; i < out.length; i++) { + out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16); + } + return out; +} + +function bytesToHex(bytes: Uint8Array): string { + let out = ""; + for (let i = 0; i < bytes.length; i++) { + out += bytes[i]!.toString(16).padStart(2, "0"); + } + return out; +} + +function concat(parts: ReadonlyArray): Uint8Array { + let total = 0; + for (const p of parts) total += p.byteLength; + const out = new Uint8Array(total); + let o = 0; + for (const p of parts) { + out.set(p, o); + o += p.byteLength; + } + return out; +} + +/** + * POST a digest to a single calendar. Returns the pending-attestation + * bytes the calendar sends back. Throws on non-2xx responses; caller + * decides how to handle multi-calendar fallback. + */ +export async function submitDigest( + calendarUrl: string, + digest: Uint8Array, + opts: { timeoutMs?: number; fetchImpl?: typeof fetch } = {}, +): Promise { + if (digest.byteLength !== 32) { + throw new Error(`digest must be 32 bytes, got ${digest.byteLength}`); + } + const fetchImpl = opts.fetchImpl ?? fetch; + const timeoutMs = opts.timeoutMs ?? 10_000; + const controller = new AbortController(); + const timer = setTimeout(() => controller.abort(), timeoutMs); + try { + // Use a fresh ArrayBuffer copy to avoid passing a TypedArray view + // backed by a Node Buffer (which fetch doesn't always serialise + // cleanly across implementations). + const body = new Uint8Array(digest.byteLength); + body.set(digest); + const res = await fetchImpl(`${calendarUrl.replace(/\/$/, "")}/digest`, { + method: "POST", + headers: { + "Content-Type": "application/octet-stream", + "User-Agent": USER_AGENT, + Accept: "application/vnd.opentimestamps.v1", + }, + body, + signal: controller.signal, + }); + if (!res.ok) { + throw new Error( + `calendar ${calendarUrl} returned HTTP ${res.status} ${res.statusText}`, + ); + } + const buf = new Uint8Array(await res.arrayBuffer()); + return { + calendar_url: calendarUrl, + pending_bytes: buf, + submitted_at: Date.now(), + }; + } finally { + clearTimeout(timer); + } +} + +/** + * Submit a digest to every calendar in parallel. Returns one row per + * successful calendar; failures land in `errors`. Caller decides on + * the required quorum (typically 3 of 4 for Phase 1). + */ +export async function submitToCalendars( + digest: Uint8Array, + opts: SubmitOptions = {}, +): Promise<{ + successes: CalendarSubmissionResult[]; + errors: Array<{ calendar_url: string; message: string }>; +}> { + const calendars = opts.calendars ?? DEFAULT_CALENDARS; + const successes: CalendarSubmissionResult[] = []; + const errors: Array<{ calendar_url: string; message: string }> = []; + await Promise.all( + calendars.map(async (url) => { + try { + const result = await submitDigest(url, digest, { + timeoutMs: opts.timeoutMs, + fetchImpl: opts.fetchImpl, + }); + successes.push(result); + } catch (err) { + errors.push({ + calendar_url: url, + message: err instanceof Error ? err.message : String(err), + }); + } + }), + ); + return { successes, errors }; +} + +/** + * GET the upgraded timestamp from a calendar. Returns null if the + * calendar reports the digest is not yet ready (HTTP 404 / 405). + */ +export async function fetchUpgrade( + opts: UpgradeOptions, +): Promise { + const fetchImpl = opts.fetchImpl ?? fetch; + const timeoutMs = opts.timeoutMs ?? 10_000; + const controller = new AbortController(); + const timer = setTimeout(() => controller.abort(), timeoutMs); + try { + const url = `${opts.calendar_url.replace(/\/$/, "")}/timestamp/${opts.digest_hex.toLowerCase()}`; + const res = await fetchImpl(url, { + method: "GET", + headers: { + "User-Agent": USER_AGENT, + Accept: "application/vnd.opentimestamps.v1", + }, + signal: controller.signal, + }); + if (res.status === 404 || res.status === 405) return null; + if (!res.ok) { + throw new Error( + `calendar ${opts.calendar_url} returned HTTP ${res.status} ${res.statusText}`, + ); + } + const buf = new Uint8Array(await res.arrayBuffer()); + return { + calendar_url: opts.calendar_url, + upgraded_bytes: buf, + upgraded_at: Date.now(), + bitcoin_confirmed: containsBitcoinAttestation(buf), + }; + } finally { + clearTimeout(timer); + } +} + +/** + * Heuristic Bitcoin-attestation detector. The python-opentimestamps + * library serialises a Bitcoin block-header attestation as: + * + * tag (1 byte 0x00) + magic_bytes (8 bytes) + payload + * + * where the magic for BitcoinBlockHeaderAttestation is the constant + * defined at python-opentimestamps `notary.py::BitcoinBlockHeaderAttestation`: + * + * b'\x05\x88\x96\x0d\x73\xd7\x19\x01' + * + * Rather than parse the full Timestamp tree (the binary format is a + * variable-length op DAG), we scan the response for this magic. + * Performance is fine: the upgraded bytes are typically < 500 bytes. + */ +const BTC_ATTESTATION_MAGIC = new Uint8Array([ + 0x05, 0x88, 0x96, 0x0d, 0x73, 0xd7, 0x19, 0x01, +]); + +export function containsBitcoinAttestation(bytes: Uint8Array): boolean { + if (bytes.byteLength < BTC_ATTESTATION_MAGIC.byteLength) return false; + outer: for (let i = 0; i <= bytes.byteLength - BTC_ATTESTATION_MAGIC.byteLength; i++) { + for (let j = 0; j < BTC_ATTESTATION_MAGIC.byteLength; j++) { + if (bytes[i + j] !== BTC_ATTESTATION_MAGIC[j]) continue outer; + } + return true; + } + return false; +} + +/** + * Build a v1 `.ots` proof file from a pending or upgraded timestamp. + * + * Format (binary, big-endian): + * + * magic (31 bytes) || version (1 byte) || file_hash_tag (1 byte 0x08 + * for sha256) || digest (32 bytes) || ops (variable; calendar bytes) + * + * The bytes returned by `submitDigest` / `fetchUpgrade` already start + * with the op sequence; we just prepend the magic + version + FileHash + * header. This produces a file `ots info` and `ots verify` recognise. + */ +export function serialiseOtsFile(args: { + digest: Uint8Array; + timestamp_bytes: Uint8Array; +}): Uint8Array { + if (args.digest.byteLength !== 32) { + throw new Error(`digest must be 32 bytes, got ${args.digest.byteLength}`); + } + return concat([ + OTS_MAGIC, + new Uint8Array([OTS_VERSION, OP_SHA256_TAG]), + args.digest, + args.timestamp_bytes, + ]); +} + +/** + * Convenience: combine multiple calendars' timestamp bytes into a + * single `.ots` file. The OTS Timestamp binary format supports a + * "fork" op that lets one input digest carry attestations from + * multiple calendars, but the safe minimal-viable approach for Phase 1 + * is to emit ONE `.ots` per calendar source and let the verifier pick + * whichever it trusts. We expose the multi-calendar surface via the + * /v1/swarm/proof route, which returns metadata + per-calendar files. + * + * For convenience the function also exposes the digest hex so callers + * can reference the canonical filename `.ots`. + */ +export interface BuiltOtsFile { + readonly digest_hex: string; + readonly calendar_url: string; + readonly bytes: Uint8Array; + readonly bitcoin_confirmed: boolean; +} + +export function buildOtsFile(args: { + digest: Uint8Array; + calendar_url: string; + timestamp_bytes: Uint8Array; +}): BuiltOtsFile { + return { + digest_hex: bytesToHex(args.digest), + calendar_url: args.calendar_url, + bytes: serialiseOtsFile({ + digest: args.digest, + timestamp_bytes: args.timestamp_bytes, + }), + bitcoin_confirmed: containsBitcoinAttestation(args.timestamp_bytes), + }; +} + +export { hexToBytes, bytesToHex, concat }; + +/** + * Tiny polling helper used by the scheduler. Re-tries `fn` every + * `intervalMs` until it returns a truthy value or `until` is reached. + * The OTS server-side scheduler uses this to spin on each pending + * calendar until an upgraded proof comes back or we give up. + */ +/** + * Build a `postOts(root)` hook compatible with + * `services/kickoff-commit.ts`. The hook: + * + * 1. Converts the hex root to a 32-byte digest. + * 2. Submits it to every calendar in parallel. + * 3. Resolves once at least `quorum` calendars ack (default 1). + * 4. Calls `onPending(pending)` with the raw pending blobs so the + * caller can persist them for later upgrade. + * + * The hook never throws on calendar errors — the kickoff commitment + * is "best effort" against the OTS pool. Persistent failures are + * surfaced via `onPending([])` so the caller can flag them in the + * audit log. + */ +export interface OtsPostOpts { + readonly calendars?: readonly string[]; + readonly quorum?: number; + readonly timeoutMs?: number; + readonly fetchImpl?: typeof fetch; + readonly onPending?: ( + blobs: ReadonlyArray<{ + calendar_url: string; + pending_bytes_hex: string; + submitted_at: number; + }>, + ) => void | Promise; +} + +export function buildOtsPostHook( + opts: OtsPostOpts = {}, +): (rootHex: string) => Promise { + const calendars = opts.calendars ?? DEFAULT_CALENDARS; + const quorum = opts.quorum ?? 1; + return async (rootHex: string) => { + let digest: Uint8Array; + try { + digest = hexToBytes(rootHex); + } catch { + // Bad input — treat as a no-op so the kickoff job keeps moving. + if (opts.onPending) await opts.onPending([]); + return; + } + if (digest.byteLength !== 32) { + if (opts.onPending) await opts.onPending([]); + return; + } + const { successes } = await submitToCalendars(digest, { + calendars, + timeoutMs: opts.timeoutMs, + fetchImpl: opts.fetchImpl, + }); + const blobs = successes.map((s) => ({ + calendar_url: s.calendar_url, + pending_bytes_hex: bytesToHex(s.pending_bytes), + submitted_at: s.submitted_at, + })); + // Below-quorum is logged via onPending; the kickoff job itself + // does not throw because the merkle root + pending blobs are + // still good evidence and can be retried later by the scheduler. + if (blobs.length < quorum) { + if (opts.onPending) await opts.onPending(blobs); + return; + } + if (opts.onPending) await opts.onPending(blobs); + }; +} + +export async function pollUntil( + fn: () => Promise, + args: { intervalMs: number; untilMs: number; nowFn?: () => number }, +): Promise { + const now = args.nowFn ?? Date.now; + while (now() < args.untilMs) { + const v = await fn(); + if (v !== null) return v; + await delay(args.intervalMs); + } + return null; +} diff --git a/apps/game/src/routes/bots-keys-issue.ts b/apps/game/src/routes/bots-keys-issue.ts new file mode 100644 index 00000000..e46fbb86 --- /dev/null +++ b/apps/game/src/routes/bots-keys-issue.ts @@ -0,0 +1,149 @@ +/** + * POST /v1/bots/keys/issue , service-to-service Bot Arena key issuance. + * + * The Next.js web proxy (`apps/web/app/api/v1/bots/keys/route.ts`) + * resolves the inbound session, looks up the verified email on the user + * record, then forwards an issuance request here with a shared-secret + * header. The shared secret lives in the env var + * `GAME_BOT_KEYS_SHARED_SECRET` on both ends and is rotated by ops. + * + * Why not just call `/v1/me/api-keys`? Because that surface requires a + * verified Supabase JWT, and the new SMS-OTP / Telegram auth flows on + * vtorn-dev do not mint Supabase sessions. The shared-secret tunnel + * lets the cookie-based session on the web side prove identity + * server-side and then issue a Bot Arena key without dragging + * Supabase into the path. + * + * Request: + * { owner_email: string, owner_user_id?: string, label?: string } + * + * Response (200): + * { api_key, key_hash, owner_email, label, quota_bots, + * quota_picks_per_hour, created_at } + * + * Errors: + * 401 missing_secret | invalid_secret , shared secret missing or wrong + * 400 invalid_email | label_too_long , payload validation + * 500 issue_failed , DB write blew up + * + * Refs: docs/superpowers/specs/2026-06-07-bot-arena-design.md §6.3 + */ +import type { FastifyInstance, FastifyRequest } from "fastify"; +import { z } from "zod"; + +import type { GameStore } from "../store/db.js"; + +const MAX_LABEL_LEN = 80; + +const IssueBodySchema = z + .object({ + owner_email: z.string().email().max(254), + owner_user_id: z.string().max(128).optional(), + label: z.string().max(MAX_LABEL_LEN).optional(), + }) + .strict(); + +export interface BotsKeysIssueRoutesDeps { + readonly store: GameStore; + readonly nowMs?: () => number; + /** + * Override the shared secret (tests pass a known value). Falls back to + * `process.env.GAME_BOT_KEYS_SHARED_SECRET` at request time so a + * mid-process env mutation in tests is picked up. + */ + readonly sharedSecret?: string | null; +} + +function readSecret(req: FastifyRequest): string | null { + const h = req.headers["x-bot-keys-shared-secret"]; + if (typeof h !== "string") return null; + const v = h.trim(); + return v.length > 0 ? v : null; +} + +function timingSafeEqualString(a: string, b: string): boolean { + // Constant-time-ish compare. Length differences early-exit (the + // attacker already knows the length of their own input), but the + // per-character comparison still walks the full string so we don't + // leak the matched-prefix length. + if (a.length !== b.length) return false; + let mismatch = 0; + for (let i = 0; i < a.length; i += 1) { + mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i); + } + return mismatch === 0; +} + +export async function registerBotsKeysIssueRoute( + app: FastifyInstance, + deps: BotsKeysIssueRoutesDeps, +): Promise { + app.post("/v1/bots/keys/issue", async (req, reply) => { + reply.header("Cache-Control", "private, no-store"); + + const expected = + deps.sharedSecret !== undefined && deps.sharedSecret !== null + ? deps.sharedSecret + : process.env.GAME_BOT_KEYS_SHARED_SECRET ?? ""; + if (!expected) { + // Fail closed: refuse to issue keys when the env var is not set. + // This prevents an accidentally-deployed-without-secret build + // from being a free key-minting endpoint. + return reply.code(503).send({ + error: "issuance_disabled", + message: + "GAME_BOT_KEYS_SHARED_SECRET is not configured on this game-service build", + }); + } + const presented = readSecret(req); + if (!presented) { + return reply.code(401).send({ error: "missing_secret" }); + } + if (!timingSafeEqualString(presented, expected)) { + return reply.code(401).send({ error: "invalid_secret" }); + } + + const parsed = IssueBodySchema.safeParse(req.body ?? {}); + if (!parsed.success) { + const flat = parsed.error.flatten(); + // Map the most common single-field failures to the existing + // error codes the web proxy understands so the UX matches the + // old Supabase path 1:1. + const fieldErrors = flat.fieldErrors as Record; + if (fieldErrors.owner_email) { + return reply.code(400).send({ error: "invalid_email" }); + } + if (fieldErrors.label) { + return reply.code(400).send({ error: "label_too_long" }); + } + return reply + .code(400) + .send({ error: "invalid_payload", detail: flat }); + } + const { owner_email, label } = parsed.data; + + try { + const now = deps.nowMs ? deps.nowMs() : undefined; + const issued = deps.store.apiKeys.issue({ + owner_email, + label: label ?? null, + ...(now !== undefined ? { now } : {}), + }); + return reply.code(200).send({ + api_key: issued.api_key, + key_hash: issued.key_hash, + owner_email: issued.owner_email, + label: issued.label, + quota_bots: issued.quota_bots, + quota_picks_per_hour: issued.quota_picks_per_hour, + created_at: issued.created_at, + }); + } catch (err) { + req.log.error( + { err: err instanceof Error ? err.message : String(err) }, + "bots_keys_issue_failed", + ); + return reply.code(500).send({ error: "issue_failed" }); + } + }); +} diff --git a/apps/game/src/routes/leaderboard.ts b/apps/game/src/routes/leaderboard.ts index b6c583ab..86adb976 100644 --- a/apps/game/src/routes/leaderboard.ts +++ b/apps/game/src/routes/leaderboard.ts @@ -24,6 +24,7 @@ import { syndicateKey, type LeaderboardCache, } from "../scoring/cache.js"; +import { LeaderboardCache as BotArenaLeaderboardCache } from "../services/leaderboard-cache.js"; import type { GameStore } from "../store/db.js"; import type { LeaderboardRow } from "../types.js"; @@ -136,16 +137,76 @@ export interface LeaderboardRoutesDeps { readonly cache: LeaderboardCache; } +/** + * Bot Arena cache , partitioned per (tournament, scope, source). Lives + * alongside the existing LeaderboardCache so the global syndicate and + * tournament reads keep their current behaviour while the new + * ?scope=humans|bots|all and ?source=federated paths get their own TTL + * + prefix invalidation surface. + */ +const botArenaCache = new BotArenaLeaderboardCache({ defaultTtlMs: 30_000 }); + +/** Test helper , drop every Bot Arena cache entry. */ +export function _resetBotArenaCache(): void { + botArenaCache.clear(); +} + export async function registerLeaderboardRoutes( app: FastifyInstance, deps: LeaderboardRoutesDeps, ): Promise { app.get("/v1/leaderboard/:tournament_id", async (req, reply) => { const params = req.params as { tournament_id?: string }; + const query = req.query as { + scope?: string; + source?: string; + }; const tournamentId = (params.tournament_id ?? "").trim(); if (!tournamentId) { return reply.code(400).send({ error: "invalid_tournament_id" }); } + + // Bot Arena scope filter. When the caller asks for humans|bots|all + // we route through the partitioned cache + scope-aware store + // query and skip the legacy global cache + LeaderboardRow handle + // path. Default (no scope param) preserves the v0.1 contract. + const scopeRaw = (query?.scope ?? "").trim().toLowerCase(); + const source = (query?.source ?? "").trim().toLowerCase(); + if ( + source === "federated" || + scopeRaw === "humans" || + scopeRaw === "bots" || + scopeRaw === "all" + ) { + const scope: "humans" | "bots" | "all" = + scopeRaw === "humans" || scopeRaw === "bots" || scopeRaw === "all" + ? scopeRaw + : "all"; + const key = `lb:${tournamentId}:${scope}:${source || "central"}`; + const out = await botArenaCache.get(key, async () => { + if (source === "federated") { + return deps.store.federatedNodes.listFederatedTopK(TOP_N); + } + const rows = deps.store.topNByScope(tournamentId, scope, TOP_N); + const recorded = recordedMatchKickoffs(deps.store, tournamentId); + return rows.map((r, i) => ({ + rank: i + 1, + user_handle: hashUserHandle(r.user_id), + share_guid: r.share_guid, + score_total: r.score_total, + bracket_id: r.id, + matches_available_to_user: matchesAvailableTo(recorded, r.joined_at), + })); + }); + reply.header("Cache-Control", PUBLIC_CACHE_HEADER); + return { + tournament_id: tournamentId, + scope, + source: source || "central", + rows: out, + }; + } + const key = globalKey(tournamentId, TOP_N); const cached = deps.cache.get(key); if (cached) { diff --git a/apps/game/src/routes/match.ts b/apps/game/src/routes/match.ts index 5deaa566..d74e0b00 100644 --- a/apps/game/src/routes/match.ts +++ b/apps/game/src/routes/match.ts @@ -18,6 +18,7 @@ import { matchResultBodySchema } from "../schemas.js"; import type { GameStore } from "../store/db.js"; import type { LeaderboardCache } from "../scoring/cache.js"; import { computeBracketScore } from "../scoring/recompute.js"; +import { runPerfectTrackWatch } from "../services/perfect-track-watch.js"; import type { Bracket, MatchOutcome } from "../types.js"; import { makeAdminGuard } from "./auth.js"; @@ -116,6 +117,16 @@ export async function registerMatchRoutes( deps.cache.invalidateTournament(body.tournament_id); + // Perfect-track watch: scoring just resolved a match, so any + // operator whose latest summary shows alive bots past match 80 + // is worth surfacing on the home page. Cheap (one query per + // operator with a summary) and silent on failure. + try { + runPerfectTrackWatch({ store: deps.store, now: now() }); + } catch (err) { + req.log.warn({ err }, "perfect-track-watch failed during settlement"); + } + return reply.code(200).send({ match_id: matchId, tournament_id: body.tournament_id, diff --git a/apps/game/src/routes/nodes.ts b/apps/game/src/routes/nodes.ts new file mode 100644 index 00000000..1fb12614 --- /dev/null +++ b/apps/game/src/routes/nodes.ts @@ -0,0 +1,223 @@ +/** + * Federation endpoints (Phase 2 forward-compat). + * + * POST /v1/nodes/register , issue node credentials + * POST /v1/nodes/commit , pre-kickoff merkle commitment + * POST /v1/nodes/leaderboard , post-match aggregate report + * + * Auth model: + * - /register is gated by an owner API key (Bearer tnm_*). The + * owner key is the same kind a developer holds for /v1/picks/bulk. + * Registering a node mints a SEPARATE node credential (also + * tnm_-prefixed) and binds it to a node_id. The node credential + * never has bulk-pick rights, only commit + leaderboard rights. + * - /commit and /leaderboard are gated by the node credential. The + * auth key must own the supplied node_id; otherwise 403. + * + * Phase 1 ships these endpoints empty-data so external node operators + * can wire their clients and integration-test against the central tier + * before the Docker image goes public in Phase 2. + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §15.2, §15.3 + */ +import { randomBytes } from "node:crypto"; + +import type { FastifyInstance, FastifyRequest } from "fastify"; +import { z } from "zod"; + +import type { GameStore } from "../store/db.js"; + +const HEX_64 = /^[0-9a-f]{64}$/; + +const RegisterSchema = z + .object({ + owner_email: z.string().email().max(254), + public_url: z.string().url().max(512), + label: z.string().max(128).optional(), + }) + .strict(); + +const CommitSchema = z + .object({ + node_id: z.string().min(1).max(64), + match_id: z.string().min(1).max(64), + merkle_root: z.string().regex(HEX_64), + bot_count: z.number().int().min(0).max(1_000_000_000), + kickoff_at: z.number().int(), + }) + .strict(); + +const LeaderboardReportSchema = z + .object({ + node_id: z.string().min(1).max(64), + match_id: z.string().min(1).max(64), + total_bots: z.number().int().min(0).max(1_000_000_000), + bots_correct: z.number().int().min(0).max(1_000_000_000), + bots_still_perfect: z.number().int().min(0).max(1_000_000_000), + top_1000: z + .array(z.unknown()) + .max(1_000) + .default([]), + }) + .strict(); + +function authBearer(req: FastifyRequest): string | null { + const h = req.headers["authorization"]; + if (typeof h !== "string" || !h.startsWith("Bearer ")) return null; + const v = h.slice("Bearer ".length).trim(); + return v.length > 0 ? v : null; +} + +function generateNodeId(): string { + return `node_${randomBytes(8).toString("hex")}`; +} + +export interface NodesRoutesDeps { + readonly store: GameStore; + readonly nowMs?: () => number; +} + +export async function registerNodesRoutes( + app: FastifyInstance, + deps: NodesRoutesDeps, +): Promise { + const now = deps.nowMs ?? (() => Date.now()); + + app.post("/v1/nodes/register", async (req, reply) => { + reply.header("Cache-Control", "private, no-store"); + + const plain = authBearer(req); + if (!plain) return reply.code(401).send({ error: "missing_api_key" }); + const ownerKey = deps.store.apiKeys.lookupByPlain(plain); + if (!ownerKey) return reply.code(401).send({ error: "invalid_api_key" }); + + const parsed = RegisterSchema.safeParse(req.body); + if (!parsed.success) { + return reply.code(400).send({ + error: "invalid_payload", + detail: parsed.error.flatten(), + }); + } + + // Mint a fresh node credential. We reuse the api_key table so + // every key , owner-issued or node-issued , uses the same hash + // function and revocation surface. + const nodeCreds = deps.store.apiKeys.issue({ + owner_email: parsed.data.owner_email, + label: `node:${parsed.data.label ?? parsed.data.public_url}`, + }); + const node_id = generateNodeId(); + deps.store.federatedNodes.register({ + node_id, + owner_email: parsed.data.owner_email, + owner_api_key_hash: nodeCreds.key_hash, + public_url: parsed.data.public_url, + label: parsed.data.label, + now: now(), + }); + + return reply.code(201).send({ + node_id, + node_key: nodeCreds.api_key, + owner_email: parsed.data.owner_email, + public_url: parsed.data.public_url, + label: parsed.data.label ?? null, + registered_at: nodeCreds.created_at, + }); + }); + + app.post("/v1/nodes/commit", async (req, reply) => { + reply.header("Cache-Control", "private, no-store"); + + const plain = authBearer(req); + if (!plain) return reply.code(401).send({ error: "missing_api_key" }); + const keyRow = deps.store.apiKeys.lookupByPlain(plain); + if (!keyRow) return reply.code(401).send({ error: "invalid_api_key" }); + + const parsed = CommitSchema.safeParse(req.body); + if (!parsed.success) { + return reply.code(400).send({ + error: "invalid_payload", + detail: parsed.error.flatten(), + }); + } + + const node = deps.store.federatedNodes.getByNodeId(parsed.data.node_id); + if (!node) return reply.code(404).send({ error: "unknown_node" }); + if (node.owner_api_key_hash !== keyRow.key_hash) { + return reply.code(403).send({ error: "not_node_owner" }); + } + + // Pre-kickoff invariant per §15.3.1: the merkle commitment must + // land strictly before the match's kickoff timestamp. Late commits + // are recorded but excluded from leaderboard scoring; we surface + // that as a 422 so client SDKs can retry-with-different-match + // before they bother computing a leaderboard report. + if (parsed.data.kickoff_at <= now()) { + return reply.code(422).send({ error: "kickoff_passed" }); + } + + deps.store.federatedNodes.commit({ + node_id: parsed.data.node_id, + match_id: parsed.data.match_id, + merkle_root: parsed.data.merkle_root, + kickoff_at: parsed.data.kickoff_at, + bot_count: parsed.data.bot_count, + now: now(), + }); + deps.store.federatedNodes.touch(parsed.data.node_id, now()); + + return reply.send({ + node_id: parsed.data.node_id, + match_id: parsed.data.match_id, + committed_at: now(), + }); + }); + + app.post("/v1/nodes/leaderboard", async (req, reply) => { + reply.header("Cache-Control", "private, no-store"); + + const plain = authBearer(req); + if (!plain) return reply.code(401).send({ error: "missing_api_key" }); + const keyRow = deps.store.apiKeys.lookupByPlain(plain); + if (!keyRow) return reply.code(401).send({ error: "invalid_api_key" }); + + const parsed = LeaderboardReportSchema.safeParse(req.body); + if (!parsed.success) { + return reply.code(400).send({ + error: "invalid_payload", + detail: parsed.error.flatten(), + }); + } + + const node = deps.store.federatedNodes.getByNodeId(parsed.data.node_id); + if (!node) return reply.code(404).send({ error: "unknown_node" }); + if (node.owner_api_key_hash !== keyRow.key_hash) { + return reply.code(403).send({ error: "not_node_owner" }); + } + + if (parsed.data.bots_correct > parsed.data.total_bots) { + return reply.code(400).send({ error: "invariant_violation" }); + } + if (parsed.data.bots_still_perfect > parsed.data.bots_correct) { + return reply.code(400).send({ error: "invariant_violation" }); + } + + deps.store.federatedNodes.reportLeaderboard({ + node_id: parsed.data.node_id, + match_id: parsed.data.match_id, + total_bots: parsed.data.total_bots, + bots_correct: parsed.data.bots_correct, + bots_still_perfect: parsed.data.bots_still_perfect, + top: parsed.data.top_1000, + now: now(), + }); + deps.store.federatedNodes.touch(parsed.data.node_id, now()); + + return reply.send({ + node_id: parsed.data.node_id, + match_id: parsed.data.match_id, + received_at: now(), + }); + }); +} diff --git a/apps/game/src/routes/odds.ts b/apps/game/src/routes/odds.ts new file mode 100644 index 00000000..0612b662 --- /dev/null +++ b/apps/game/src/routes/odds.ts @@ -0,0 +1,424 @@ +/** + * Polymarket-derived odds read endpoints. + * + * GET /v1/odds/match/:match_id , latest match-moneyline implied probs + * GET /v1/odds/winner-market , latest tournament-winner implied probs + * GET /v1/odds/snapshot , combined payload used by /run page load + * + * Data source: the odds-ingest service writes a SQLite file at + * `apps/odds-ingest/data/odds-ingest.sqlite`. This route opens that file + * READ-ONLY (it is owned by the ingest service, never the game-service) + * and serves the latest tick per (market, outcome). + * + * Match-id mapping: + * The browser-swarm constructs `match_id` as the raw integer string + * 1..72 (one per group fixture in canonical fixture order , see + * apps/web/components/browser-swarm/regenerate.ts:205). The odds DB + * stores markets with id `wc2026:match:N` and `match_id="N"`. To make + * the API forgiving for callers we accept either form: + * - integer string "1", "12", "72" + * - canonical 3-digit form "wc2026-m001", "wc2026-m072" + * Both resolve to the same row. + * + * Caching (per docs/22): + * Cache-Control: public, s-maxage=60, stale-while-revalidate=300 + * SQLite reads are microseconds; the edge cache absorbs spikes. + * + * Spec: docs/superpowers/specs/2026-06-08-polymarket-odds-endpoint.md + */ + +import { existsSync } from "node:fs"; + +import Database from "better-sqlite3"; +import type { Database as DatabaseT } from "better-sqlite3"; +import type { FastifyInstance } from "fastify"; + +const PUBLIC_CACHE_HEADER = "public, s-maxage=60, stale-while-revalidate=300"; + +const DEFAULT_DB_PATH = + "/home/clawdbot/clawdia/projects/vtorn/apps/odds-ingest/data/odds-ingest.sqlite"; + +interface OutcomeMeta { + readonly label: string; + readonly our_team_code: string | null; +} + +interface MarketRow { + readonly id: string; + readonly match_id: string | null; + readonly outcomes_json: string; + readonly updated_at: number; +} + +interface LatestTickRow { + readonly outcome_label: string; + readonly last: number | null; + readonly implied_prob: number | null; + readonly ts: number; +} + +interface WinnerLatestRow { + readonly market_id: string; + readonly last: number | null; + readonly implied_prob: number | null; + readonly ts: number; +} + +/** + * Singleton read-only DB handle for the odds-ingest file. The + * game-service is a long-lived process; opening once amortises the + * cost across thousands of requests. We re-open lazily on first + * access so tests / unit boots that don't touch odds don't pay for it. + */ +let odbCache: DatabaseT | null = null; +let odbPath: string | null = null; + +function openOddsDb(path: string): DatabaseT | null { + if (odbCache && odbPath === path) return odbCache; + if (odbCache) { + try { + odbCache.close(); + } catch { + // ignore + } + odbCache = null; + } + if (!existsSync(path)) return null; + // readonly + fileMustExist guards against the route writing back + // to the ingest file by accident. Concurrent writers (the ingest + // process) write through WAL; SQLite handles read snapshots safely. + odbCache = new Database(path, { readonly: true, fileMustExist: true }); + odbCache.pragma("journal_mode = WAL"); + odbCache.pragma("query_only = ON"); + odbPath = path; + return odbCache; +} + +/** + * Test / reload helper. Closes any open handle so the next request + * re-opens against the configured path. Exported so unit tests can + * point at a fresh fixture DB without leaking the previous one. + */ +export function _closeOddsDb(): void { + if (odbCache) { + try { + odbCache.close(); + } catch { + // ignore + } + } + odbCache = null; + odbPath = null; +} + +/** + * Normalise an inbound match-id to the integer form 1..72 used by the + * odds DB. Returns null if the value is not a recognised form. + * + * Accepted: + * "1", "12", "72" -> 1, 12, 72 + * "wc2026-m001", "wc2026-m072" -> 1, 72 + * + * Knockout fixtures (id like `r32-1`, `qf-1`) are not in scope for v0.1; + * Polymarket only carries group-stage moneylines at this point. + */ +function normaliseMatchId(raw: string): number | null { + const trimmed = raw.trim(); + if (!trimmed) return null; + const canonical = trimmed.match(/^wc2026-m0*(\d+)$/i); + if (canonical) { + const n = Number.parseInt(canonical[1] ?? "", 10); + if (Number.isFinite(n) && n >= 1 && n <= 200) return n; + return null; + } + if (/^\d+$/.test(trimmed)) { + const n = Number.parseInt(trimmed, 10); + if (Number.isFinite(n) && n >= 1 && n <= 200) return n; + } + return null; +} + +/** 3-digit zero-padded canonical form, e.g. `wc2026-m001`. */ +function canonicalMatchKey(n: number): string { + return `wc2026-m${String(n).padStart(3, "0")}`; +} + +function parseOutcomes(json: string): readonly OutcomeMeta[] { + try { + const parsed = JSON.parse(json); + if (!Array.isArray(parsed)) return []; + return parsed + .filter((o): o is Record => typeof o === "object" && o !== null) + .map((o) => ({ + label: typeof o.label === "string" ? o.label : "", + our_team_code: + typeof o.our_team_code === "string" && o.our_team_code.length > 0 + ? o.our_team_code + : null, + })) + .filter((o) => o.label.length > 0); + } catch { + return []; + } +} + +interface MatchProbs { + readonly home_team: string | null; + readonly away_team: string | null; + readonly home_win: number | null; + readonly draw: number | null; + readonly away_win: number | null; + readonly updated_at: number; +} + +/** + * Pull the latest tick per outcome for a market and fold it into the + * shape expected by the browser-swarm odds substitution path. + * + * outcomes_json ordering convention (verified for the WC26 group-stage + * markets): [home_team, "Draw", away_team]. The mapping is anchored on + * `our_team_code != null` to spot the team rows, with the remaining row + * folded into "draw". + */ +function loadMatchProbs(db: DatabaseT, marketId: string): MatchProbs | null { + const market = db + .prepare<[string], MarketRow>( + `SELECT id, match_id, outcomes_json, updated_at + FROM odds_market + WHERE id = ?`, + ) + .get(marketId); + if (!market) return null; + const outcomes = parseOutcomes(market.outcomes_json); + if (outcomes.length < 2) return null; + + const ticks = db + .prepare<[string], LatestTickRow>( + `SELECT outcome_label, last, implied_prob, ts + FROM odds_tick + WHERE market_id = ? + AND ts = ( + SELECT MAX(ts) FROM odds_tick AS t2 + WHERE t2.market_id = odds_tick.market_id + AND t2.outcome_label = odds_tick.outcome_label + )`, + ) + .all(marketId); + if (ticks.length === 0) return null; + const byLabel = new Map(); + for (const t of ticks) byLabel.set(t.outcome_label, t); + + let homeTeam: string | null = null; + let awayTeam: string | null = null; + let homeLabel: string | null = null; + let drawLabel: string | null = null; + let awayLabel: string | null = null; + + // First pass: identify the two team labels by their position relative + // to the "Draw" entry. The outcomes_json order is [home, draw, away] + // for every WC26 group fixture, so the first our_team_code-bearing + // outcome is home, the second is away. + const teamSlots = outcomes.filter((o) => o.our_team_code !== null); + if (teamSlots.length >= 2) { + homeTeam = teamSlots[0]?.our_team_code ?? null; + awayTeam = teamSlots[1]?.our_team_code ?? null; + homeLabel = teamSlots[0]?.label ?? null; + awayLabel = teamSlots[1]?.label ?? null; + } else { + // Fall back to first / last when team codes are missing (mock seeds). + homeLabel = outcomes[0]?.label ?? null; + awayLabel = outcomes[outcomes.length - 1]?.label ?? null; + } + for (const o of outcomes) { + if (o.our_team_code === null && o.label.toLowerCase() === "draw") { + drawLabel = o.label; + break; + } + } + if (!drawLabel) { + // No explicit Draw outcome means this isn't a moneyline; treat as + // unusable rather than fudging numbers. + return null; + } + + const home = homeLabel ? byLabel.get(homeLabel) ?? null : null; + const draw = drawLabel ? byLabel.get(drawLabel) ?? null : null; + const away = awayLabel ? byLabel.get(awayLabel) ?? null : null; + + const pick = (row: LatestTickRow | null): number | null => { + if (!row) return null; + if (row.last !== null && Number.isFinite(row.last)) return row.last; + if (row.implied_prob !== null && Number.isFinite(row.implied_prob)) + return row.implied_prob; + return null; + }; + + const updatedAt = Math.max( + market.updated_at ?? 0, + home?.ts ?? 0, + draw?.ts ?? 0, + away?.ts ?? 0, + ); + + return { + home_team: homeTeam, + away_team: awayTeam, + home_win: pick(home), + draw: pick(draw), + away_win: pick(away), + updated_at: updatedAt, + }; +} + +interface WinnerEntry { + readonly team_code: string; + readonly implied_prob: number; + readonly updated_at: number; +} + +function loadWinnerMarket(db: DatabaseT): readonly WinnerEntry[] { + const rows = db + .prepare<[], WinnerLatestRow>( + `SELECT market_id, last, implied_prob, ts + FROM odds_tick AS ot + WHERE outcome_label = 'Yes' + AND market_id LIKE 'wc2026:winner:%' + AND ts = ( + SELECT MAX(ts) FROM odds_tick AS t2 + WHERE t2.market_id = ot.market_id + AND t2.outcome_label = 'Yes' + )`, + ) + .all(); + const out: WinnerEntry[] = []; + for (const r of rows) { + const prob = + r.last !== null && Number.isFinite(r.last) + ? r.last + : r.implied_prob !== null && Number.isFinite(r.implied_prob) + ? r.implied_prob + : null; + if (prob === null) continue; + const match = r.market_id.match(/^wc2026:winner:([A-Z]{2,4})$/); + if (!match) continue; + out.push({ + team_code: match[1] ?? "", + implied_prob: prob, + updated_at: r.ts, + }); + } + out.sort((a, b) => b.implied_prob - a.implied_prob); + return out; +} + +export interface OddsRoutesDeps { + /** Override the SQLite path. Falls back to env / built-in default. */ + readonly dbPath?: string; +} + +export async function registerOddsRoutes( + app: FastifyInstance, + deps: OddsRoutesDeps = {}, +): Promise { + const dbPath = + deps.dbPath ?? process.env.ODDS_INGEST_DB_PATH ?? DEFAULT_DB_PATH; + + function db(): DatabaseT | null { + return openOddsDb(dbPath); + } + + app.get("/v1/odds/match/:match_id", async (req, reply) => { + const params = req.params as { match_id?: string }; + const raw = (params.match_id ?? "").trim(); + if (!raw) { + return reply.code(400).send({ error: "invalid_match_id" }); + } + const n = normaliseMatchId(raw); + if (n === null) { + return reply.code(400).send({ error: "invalid_match_id" }); + } + const handle = db(); + if (!handle) { + reply.header("Cache-Control", PUBLIC_CACHE_HEADER); + return reply.code(404).send({ error: "no_market" }); + } + const probs = loadMatchProbs(handle, `wc2026:match:${n}`); + if (!probs) { + reply.header("Cache-Control", PUBLIC_CACHE_HEADER); + return reply.code(404).send({ error: "no_market" }); + } + reply.header("Cache-Control", PUBLIC_CACHE_HEADER); + return { + match_id: String(n), + home_team: probs.home_team, + away_team: probs.away_team, + home_win: probs.home_win, + draw: probs.draw, + away_win: probs.away_win, + source: "polymarket", + updated_at: probs.updated_at, + }; + }); + + app.get("/v1/odds/winner-market", async (_req, reply) => { + const handle = db(); + reply.header("Cache-Control", PUBLIC_CACHE_HEADER); + if (!handle) { + return { teams: [], source: "polymarket" }; + } + const entries = loadWinnerMarket(handle); + return { + teams: entries.map((e) => ({ + team_code: e.team_code, + implied_prob: e.implied_prob, + updated_at: e.updated_at, + })), + source: "polymarket", + }; + }); + + app.get("/v1/odds/snapshot", async (_req, reply) => { + reply.header("Cache-Control", PUBLIC_CACHE_HEADER); + const handle = db(); + const generatedAt = Date.now(); + if (!handle) { + return { + matches: {}, + tournament_winner: [], + source: "polymarket", + generated_at: generatedAt, + }; + } + const matches: Record< + string, + { + home_win: number | null; + draw: number | null; + away_win: number | null; + source: "polymarket"; + updated_at: number; + } + > = {}; + for (let n = 1; n <= 72; n += 1) { + const probs = loadMatchProbs(handle, `wc2026:match:${n}`); + if (!probs) continue; + matches[canonicalMatchKey(n)] = { + home_win: probs.home_win, + draw: probs.draw, + away_win: probs.away_win, + source: "polymarket", + updated_at: probs.updated_at, + }; + } + const winner = loadWinnerMarket(handle); + return { + matches, + tournament_winner: winner.map((e) => ({ + team_code: e.team_code, + implied_prob: e.implied_prob, + })), + source: "polymarket", + generated_at: generatedAt, + }; + }); +} diff --git a/apps/game/src/routes/perfect-track.ts b/apps/game/src/routes/perfect-track.ts new file mode 100644 index 00000000..caa6981f --- /dev/null +++ b/apps/game/src/routes/perfect-track.ts @@ -0,0 +1,50 @@ +/** + * Public read endpoint for the perfect-track badge. + * + * GET /v1/perfect-track , latest rolled-up alert summary + * + * Returns: + * { + * highest_match: number | null, + * total_alive: number, + * operator_count: number, + * rows: Array<{ operator_id, match_number, alive_count, detected_at }> + * } + * + * Edge-cached because the badge polls on every leaderboard render. + * + * Spec: A13 task brief , "🔥 N bots still on a perfect track after + * match X" badge. + */ +import type { FastifyInstance } from "fastify"; + +import type { GameStore } from "../store/db.js"; + +export interface PerfectTrackRoutesDeps { + readonly store: GameStore; +} + +export async function registerPerfectTrackRoutes( + app: FastifyInstance, + deps: PerfectTrackRoutesDeps, +): Promise { + app.get("/v1/perfect-track", async (_req, reply) => { + reply.header( + "Cache-Control", + "public, s-maxage=30, stale-while-revalidate=120", + ); + const summary = deps.store.perfectTrackAlerts.latestSummary(); + const rows = deps.store.perfectTrackAlerts.listAll(); + return { + highest_match: summary?.highest_match ?? null, + total_alive: summary?.total_alive ?? 0, + operator_count: summary?.operator_count ?? 0, + rows: rows.map((r) => ({ + operator_id: r.operator_id, + match_number: r.match_number, + alive_count: r.alive_count, + detected_at: r.detected_at, + })), + }; + }); +} diff --git a/apps/game/src/routes/picks-bulk.ts b/apps/game/src/routes/picks-bulk.ts new file mode 100644 index 00000000..2cacfacf --- /dev/null +++ b/apps/game/src/routes/picks-bulk.ts @@ -0,0 +1,263 @@ +/** + * POST /v1/picks/bulk , Bot Arena swarm submission endpoint. + * + * Accepts up to 10,000 picks across up to 1,000 bots per request. Every + * bot referenced must be owned by the calling API key. The endpoint + * runs the whole batch inside one SQLite transaction with a prepared + * upsert statement, so 10k picks commits in well under the 500ms p99 + * budget on the dev box. + * + * Payload shape: + * { + * tournament_id: "fifa-wc-2026", + * submissions: [ + * { bot_id: "my-bot-01", picks: [ + * { match_id: "1", outcome: "home_win" }, + * { match_id: "2", outcome: "draw" }, + * { match_id: "r32_01", outcome: "home_win" } + * ] }, + * ... + * ] + * } + * + * Response: + * { + * accepted: 9876, + * dropped_picks: [ { bot_id, match_id, reason } ], + * quota_remaining: { picks_per_hour, bots_owned } + * } + * + * Errors: + * 401 missing_api_key | invalid_api_key + * 403 not_owner , API key does not own this bot_id + * 400 invalid_payload , Zod validation failed + * 413 batch_too_large , > 10k picks in one request + * 429 quota_exceeded , key would blow its hourly pick budget + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §7 + */ +import type { FastifyInstance, FastifyRequest } from "fastify"; +import { z } from "zod"; + +import type { GameStore } from "../store/db.js"; +import type { Bracket } from "../types.js"; + +const MAX_PICKS_PER_REQUEST = 10_000; +const MAX_SUBMISSIONS_PER_REQUEST = 1_000; +const MAX_PICKS_PER_SUBMISSION = 10_000; + +const PicksBulkSchema = z + .object({ + tournament_id: z.string().min(1).max(64), + submissions: z + .array( + z + .object({ + bot_id: z.string().min(1).max(128), + picks: z + .array( + z + .object({ + match_id: z.string().min(1).max(64), + outcome: z.enum(["home_win", "draw", "away_win"]), + }) + .strict(), + ) + .min(1) + .max(MAX_PICKS_PER_SUBMISSION), + }) + .strict(), + ) + .min(1) + .max(MAX_SUBMISSIONS_PER_REQUEST), + }) + .strict(); + +function authKey(req: FastifyRequest): string | null { + const h = req.headers["authorization"]; + if (typeof h !== "string" || !h.startsWith("Bearer ")) return null; + const v = h.slice("Bearer ".length).trim(); + return v.length > 0 ? v : null; +} + +export interface PicksBulkRoutesDeps { + readonly store: GameStore; + readonly nowMs?: () => number; +} + +export async function registerPicksBulkRoute( + app: FastifyInstance, + deps: PicksBulkRoutesDeps, +): Promise { + const now = deps.nowMs ?? (() => Date.now()); + + // Prepare the upsert ONCE per server boot. better-sqlite3 caches the + // statement plan, so reuse from inside the txn keeps the bulk insert + // well under 500ms p99 for 10k picks. + const upsertStmt = deps.store.db.prepare( + `INSERT INTO brackets + (id, user_id, tournament_id, payload_json, locked_at, + score_total, share_guid, committed_at_utc) + VALUES (@id, @user_id, @tournament_id, @payload_json, @locked_at, + 0, @share_guid, NULL) + ON CONFLICT(user_id, tournament_id) DO UPDATE + SET payload_json = excluded.payload_json, + locked_at = excluded.locked_at`, + ); + const ensureUserStmt = deps.store.db.prepare( + `INSERT INTO users (id, created_at, is_bot) VALUES (?, ?, 1) + ON CONFLICT(id) DO NOTHING`, + ); + + app.post("/v1/picks/bulk", async (req, reply) => { + reply.header("Cache-Control", "private, no-store"); + + const plain = authKey(req); + if (!plain) { + return reply.code(401).send({ error: "missing_api_key" }); + } + + const keyRow = deps.store.apiKeys.lookupByPlain(plain); + if (!keyRow) { + return reply.code(401).send({ error: "invalid_api_key" }); + } + + const parsed = PicksBulkSchema.safeParse(req.body); + if (!parsed.success) { + return reply.code(400).send({ + error: "invalid_payload", + detail: parsed.error.flatten(), + }); + } + + let totalPicks = 0; + for (const sub of parsed.data.submissions) { + totalPicks += sub.picks.length; + } + if (totalPicks > MAX_PICKS_PER_REQUEST) { + return reply.code(413).send({ + error: "batch_too_large", + max: MAX_PICKS_PER_REQUEST, + received: totalPicks, + }); + } + + // Ownership check. Resolve all bot_ids in one IN(...) query so + // 1k bots per request is one round trip, not 1000. + const botIds = parsed.data.submissions.map((s) => s.bot_id); + const notOwned = deps.store.botOwners.notOwnedBy(keyRow.key_hash, botIds); + if (notOwned.length > 0) { + return reply.code(403).send({ + error: "not_owner", + bot_id: notOwned[0], + unowned: notOwned, + }); + } + + // Quota. Charge against the hourly cap before doing any writes so + // a 429 leaves no partial state behind. + if ( + !deps.store.quotas.tryConsume( + keyRow.key_hash, + totalPicks, + keyRow.quota_picks_per_hour, + now(), + ) + ) { + return reply.code(429).send({ + error: "quota_exceeded", + quota_picks_per_hour: keyRow.quota_picks_per_hour, + used_this_hour: deps.store.quotas.usedThisHourAt( + keyRow.key_hash, + now(), + ), + }); + } + + const lockedAt = now(); + const dropped: Array<{ bot_id: string; match_id: string; reason: string }> = []; + + // Single transaction, prepared statement reuse. For each bot we + // load the existing bracket (if any) so a re-submit merges with + // prior picks rather than wiping them; the bot SDK uses the + // single-pick endpoint for incremental work and the bulk endpoint + // for whole-bracket overwrites, so either path is correct. + const txn = deps.store.db.transaction(() => { + for (const sub of parsed.data.submissions) { + ensureUserStmt.run(sub.bot_id, lockedAt); + + // Merge into the bot's existing bracket, if any. + const existingRow = deps.store.getBracketForUser( + sub.bot_id, + parsed.data.tournament_id, + ); + let bracket: Bracket; + let bracketId: string; + let shareGuid: string; + if (existingRow) { + bracketId = existingRow.id; + shareGuid = existingRow.share_guid ?? sub.bot_id.slice(0, 16); + try { + bracket = JSON.parse(existingRow.payload_json) as Bracket; + } catch { + bracket = { + bracketId, + matchPredictions: {}, + groupTiebreakers: {}, + knockoutPredictions: {}, + version: 1, + }; + } + } else { + bracketId = `bk_${sub.bot_id}_${parsed.data.tournament_id}`; + shareGuid = sub.bot_id.slice(0, 16) || "bot"; + bracket = { + bracketId, + matchPredictions: {}, + groupTiebreakers: {}, + knockoutPredictions: {}, + version: 1, + }; + } + + const isoLockedAt = new Date(lockedAt).toISOString(); + for (const p of sub.picks) { + const rec = { + matchId: p.match_id, + outcome: p.outcome, + lockedAt: isoLockedAt, + }; + // Group matches in the WC2026 catalogue are numeric ids + // (1..72); knockouts are alphanumeric (r32_01 etc). + if (/^\d+$/.test(p.match_id)) { + bracket.matchPredictions[p.match_id] = rec; + } else { + bracket.knockoutPredictions[p.match_id] = rec; + } + } + + upsertStmt.run({ + id: bracketId, + user_id: sub.bot_id, + tournament_id: parsed.data.tournament_id, + payload_json: JSON.stringify(bracket), + locked_at: lockedAt, + share_guid: shareGuid, + }); + } + }); + txn(); + + const used = deps.store.quotas.usedThisHourAt(keyRow.key_hash, now()); + const botsOwned = deps.store.botOwners.countByApiKey(keyRow.key_hash); + + return reply.send({ + accepted: totalPicks, + dropped_picks: dropped, + quota_remaining: { + picks_per_hour: Math.max(keyRow.quota_picks_per_hour - used, 0), + bots_owned: Math.max(keyRow.quota_bots - botsOwned, 0), + }, + }); + }); +} diff --git a/apps/game/src/routes/swarm.ts b/apps/game/src/routes/swarm.ts new file mode 100644 index 00000000..ab6d2570 --- /dev/null +++ b/apps/game/src/routes/swarm.ts @@ -0,0 +1,412 @@ +/** + * Browser-swarm federation endpoints. + * + * POST /v1/swarm/commit , persist a swarm summary + submit + * merkle root to ≥3 OTS calendars + * GET /v1/swarm/leaderboard , cross-swarm ranked claim list + * GET /v1/swarm/proof/:root , metadata for the OTS proof of one + * merkle root, with download links + * GET /v1/swarm/proof/:root/file/:calendar.ots + * , downloadable .ots file produced + * from the upgraded (or pending) + * calendar payload + * + * Auth model: + * /commit accepts EITHER an authenticated federated-node bearer + * (the same tnm_-prefixed key minted by /v1/nodes/register) OR an + * anonymous submission with `node_id="browser-..."` and a one-shot + * ed-format node_secret echoed back. Browser tabs are not gated + * because the marginal cost of a swarm-claim row is small and the + * merkle root is the audit anchor regardless. The leaderboard route + * is fully public. + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §15.6 + */ +import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify"; +import { z } from "zod"; + +import { + buildOtsFile, + bytesToHex, + hexToBytes, + submitToCalendars, + DEFAULT_CALENDARS, +} from "../lib/ots-calendar.js"; +import type { GameStore } from "../store/db.js"; +import type { PendingCalendarBlob } from "../store/swarm-claims.js"; + +const HEX_64 = /^[0-9a-f]{64}$/; +// Browser tabs prefix node_id with "browser-" (see federation.ts +// localCredentials()); central-side nodes use "node_". +const NODE_ID_RE = /^(browser-[0-9a-f]+|node_[0-9a-f]+)$/; +const RUN_ID_RE = /^[A-Za-z0-9_\-]{4,80}$/; +const CALENDAR_RE = /^[a-z0-9-]+$/; + +const TopNClaimSchema = z + .object({ + bot_index: z.number().int().min(0).max(1_000_000_000), + claimed_score: z.number().finite(), + picks_count: z.number().int().min(0).max(1_000_000), + }) + .strict(); + +const CommitSchema = z + .object({ + node_id: z.string().regex(NODE_ID_RE), + run_id: z.string().regex(RUN_ID_RE), + master_seed: z.string().min(1).max(256), + strategy: z.string().min(1).max(64).default("chalk-v1"), + total_bots: z.number().int().min(1).max(1_000_000_000), + merkle_root: z.string().regex(HEX_64), + top_n_claim: TopNClaimSchema, + started_at: z.number().int(), + finished_at: z.number().int(), + }) + .strict(); + +const LeaderboardQuerySchema = z + .object({ + limit: z + .union([z.string(), z.number()]) + .transform((v) => Number(v)) + .pipe(z.number().int().min(1).max(1000)) + .optional(), + }) + .strict(); + +export interface SwarmRoutesDeps { + readonly store: GameStore; + readonly nowMs?: () => number; + /** Override the OTS calendar list (tests). */ + readonly otsCalendars?: readonly string[]; + /** Inject fetch (tests). */ + readonly otsFetch?: typeof fetch; + /** Per-request OTS timeout in ms. */ + readonly otsTimeoutMs?: number; + /** Disable network OTS submission (tests). When true, /commit + * persists with empty pending blobs and `ots_status='failed'`. */ + readonly disableOts?: boolean; + /** Base URL used to build absolute ots_proof_url links. */ + readonly publicBaseUrl?: string; +} + +function calendarSlug(url: string): string { + // Slugify the calendar hostname so it's safe in URL paths. + // a.lt.opentimestamps.org -> a-lt-opentimestamps-org + try { + const host = new URL(url).hostname.toLowerCase(); + return host.replace(/\./g, "-"); + } catch { + return url + .toLowerCase() + .replace(/^https?:\/\//, "") + .replace(/[^a-z0-9]+/g, "-"); + } +} + +function rebuildCalendarUrl(slug: string, fallback: readonly string[]): string | null { + for (const url of fallback) { + if (calendarSlug(url) === slug) return url; + } + return null; +} + +export async function registerSwarmRoutes( + app: FastifyInstance, + deps: SwarmRoutesDeps, +): Promise { + const now = deps.nowMs ?? (() => Date.now()); + const calendars = deps.otsCalendars ?? DEFAULT_CALENDARS; + const publicBaseUrl = (deps.publicBaseUrl ?? "").replace(/\/$/, ""); + + const buildProofUrl = (rootHex: string): string => + `${publicBaseUrl}/v1/swarm/proof/${rootHex}`; + + app.post("/v1/swarm/commit", async (req: FastifyRequest, reply) => { + reply.header("Cache-Control", "private, no-store"); + + const parsed = CommitSchema.safeParse(req.body); + if (!parsed.success) { + return reply.code(400).send({ + error: "invalid_payload", + detail: parsed.error.flatten(), + }); + } + + let pending: PendingCalendarBlob[] = []; + let otsStatus: "pending" | "failed" = "failed"; + if (!deps.disableOts) { + try { + const digest = hexToBytes(parsed.data.merkle_root); + const { successes } = await submitToCalendars(digest, { + calendars, + timeoutMs: deps.otsTimeoutMs, + fetchImpl: deps.otsFetch, + }); + pending = successes.map((s) => ({ + calendar_url: s.calendar_url, + pending_bytes_hex: bytesToHex(s.pending_bytes), + submitted_at: s.submitted_at, + })); + if (pending.length > 0) otsStatus = "pending"; + } catch { + pending = []; + otsStatus = "failed"; + } + } + + const claim = deps.store.swarmClaims.upsert({ + node_id: parsed.data.node_id, + run_id: parsed.data.run_id, + master_seed: parsed.data.master_seed, + strategy: parsed.data.strategy, + total_bots: parsed.data.total_bots, + merkle_root: parsed.data.merkle_root, + top_n_claim: parsed.data.top_n_claim, + started_at: parsed.data.started_at, + finished_at: parsed.data.finished_at, + pending_calendar_blobs: pending, + ots_status: otsStatus, + now: now(), + }); + + return reply.code(201).send({ + node_id: claim.node_id, + run_id: claim.run_id, + merkle_root: claim.merkle_root, + ots_status: claim.ots_status, + pending_calendars: pending.map((p) => p.calendar_url), + ots_proof_url: buildProofUrl(claim.merkle_root), + submitted_at: claim.submitted_at, + }); + }); + + /** + * GET /v1/swarm/totals + * + * Aggregate counts across the global swarm-claims table. Drives the + * "N bots in the arena" chip on /bot-arena and gives every device + * the same headline number within a 60s cache window. Tim 2026-06-08. + * + * Cache strategy: + * - In-memory result cache, 60s TTL: avoids a SQLite COUNT/SUM scan + * on every poll. The page polls every ~30s so the cache absorbs + * all but ~1 query per minute regardless of viewer count. + * - HTTP `Cache-Control: public, max-age=30, stale-while-revalidate=60` + * so the Cloudflare edge / browser also de-dups concurrent loads + * across the same device. + */ + let totalsCache: { + at_ms: number; + body: { + total_bots: number; + total_swarms: number; + total_devices: number; + cached_at_utc: string; + }; + } | null = null; + const TOTALS_TTL_MS = 60_000; + + app.get("/v1/swarm/totals", async (_req, reply) => { + const now = Date.now(); + if (!totalsCache || now - totalsCache.at_ms > TOTALS_TTL_MS) { + // Two aggregation paths fold into one headline: + // swarm_claims - per-run best-bot OTS claims (A11 era) + // swarm_summary - per-operator federated aggregates (A13 era, + // what /run + bot-node container POST to) + // Without this fold the bot-arena card showed only the claims + // bucket, so a container posting 1.45M bots to swarm_summary + // never moved the headline. Tim 2026-06-08. + const claims = deps.store.swarmClaims.totals(); + const summaries = deps.store.swarmSummaries.totals(); + totalsCache = { + at_ms: now, + body: { + total_bots: claims.total_bots + summaries.total_bots, + total_swarms: claims.total_swarms + summaries.total_operators, + total_devices: claims.total_devices + summaries.total_operators, + cached_at_utc: new Date(now).toISOString(), + }, + }; + } + reply.header( + "Cache-Control", + "public, max-age=30, stale-while-revalidate=60", + ); + return totalsCache.body; + }); + + app.get("/v1/swarm/leaderboard", async (req, reply) => { + const parsedQuery = LeaderboardQuerySchema.safeParse(req.query ?? {}); + if (!parsedQuery.success) { + return reply.code(400).send({ + error: "invalid_query", + detail: parsedQuery.error.flatten(), + }); + } + const limit = parsedQuery.data.limit ?? 100; + const rows = deps.store.swarmClaims.leaderboard(limit, buildProofUrl); + reply.header( + "Cache-Control", + "public, max-age=30, stale-while-revalidate=60", + ); + return { rows }; + }); + + app.get("/v1/swarm/proof/:merkle_root", async (req, reply) => { + const { merkle_root } = req.params as { merkle_root?: string }; + const root = (merkle_root ?? "").toLowerCase(); + if (!HEX_64.test(root)) { + return reply.code(400).send({ error: "invalid_merkle_root" }); + } + const row = deps.store.swarmClaims.getByMerkleRoot(root); + if (!row) return reply.code(404).send({ error: "not_found" }); + const pending = deps.store.swarmClaims.parsePending(row); + const claim = deps.store.swarmClaims.parseTopClaim(row); + reply.header( + "Cache-Control", + row.ots_status === "confirmed" + ? "public, max-age=86400, immutable" + : "public, max-age=60, stale-while-revalidate=120", + ); + return { + merkle_root: row.merkle_root, + node_id: row.node_id, + run_id: row.run_id, + master_seed: row.master_seed, + strategy: row.strategy, + total_bots: row.total_bots, + top_n_claim: claim, + ots_status: row.ots_status, + submitted_at: row.submitted_at, + finished_at: row.finished_at, + // Pending calendars: every one of these has an .ots file + // available (carrying the calendar attestation but no Bitcoin + // attestation yet). + pending_calendars: pending.map((p) => ({ + calendar_url: p.calendar_url, + calendar_slug: calendarSlug(p.calendar_url), + submitted_at: p.submitted_at, + download_url: + `${publicBaseUrl}/v1/swarm/proof/${row.merkle_root}` + + `/file/${calendarSlug(p.calendar_url)}.ots`, + })), + // Confirmed file (with Bitcoin attestation) once the scheduler + // has upgraded the proof. + bitcoin_confirmed: row.ots_status === "confirmed", + upgraded: row.ots_status === "confirmed" + ? { + calendar_url: row.upgraded_calendar_url, + upgraded_at: row.upgraded_at, + download_url: + `${publicBaseUrl}/v1/swarm/proof/${row.merkle_root}/file/upgraded.ots`, + } + : null, + }; + }); + + app.get( + "/v1/swarm/proof/:merkle_root/file/:filename", + async (req, reply) => { + const { merkle_root, filename } = req.params as { + merkle_root?: string; + filename?: string; + }; + const root = (merkle_root ?? "").toLowerCase(); + const file = filename ?? ""; + if (!HEX_64.test(root)) { + return reply.code(400).send({ error: "invalid_merkle_root" }); + } + const row = deps.store.swarmClaims.getByMerkleRoot(root); + if (!row) return reply.code(404).send({ error: "not_found" }); + const digest = hexToBytes(row.merkle_root); + + // upgraded.ots — Bitcoin-attested file (only if confirmed). + if (file === "upgraded.ots") { + if (row.ots_status !== "confirmed" || !row.upgraded_ots_hex) { + return reply.code(409).send({ + error: "not_yet_confirmed", + message: + "Bitcoin attestation has not landed yet. Use one of the pending calendar files instead, or retry later.", + }); + } + const ts = hexToBytes(row.upgraded_ots_hex); + const ots = buildOtsFile({ + digest, + calendar_url: row.upgraded_calendar_url ?? "upgraded", + timestamp_bytes: ts, + }); + return sendOtsFile(reply, ots.bytes, `tournamental-${root.slice(0, 16)}.ots`, true); + } + + // Per-calendar pending file, addressed as .ots. + const match = /^([a-z0-9-]+)\.ots$/.exec(file); + if (!match || !CALENDAR_RE.test(match[1]!)) { + return reply.code(404).send({ error: "not_found" }); + } + const wantedSlug = match[1]!; + const pending = deps.store.swarmClaims.parsePending(row); + const blob = pending.find( + (p) => calendarSlug(p.calendar_url) === wantedSlug, + ); + if (!blob) { + // Maybe the upgraded calendar matches but the file path used + // its slug instead of "upgraded". + if ( + row.upgraded_calendar_url && + calendarSlug(row.upgraded_calendar_url) === wantedSlug && + row.upgraded_ots_hex + ) { + const ts = hexToBytes(row.upgraded_ots_hex); + const ots = buildOtsFile({ + digest, + calendar_url: row.upgraded_calendar_url, + timestamp_bytes: ts, + }); + return sendOtsFile( + reply, + ots.bytes, + `tournamental-${root.slice(0, 16)}-${wantedSlug}.ots`, + true, + ); + } + // Also let `calendars` fallback (in case the slug came from + // the default set and the row had no pending blob recorded). + if (rebuildCalendarUrl(wantedSlug, calendars) === null) { + return reply.code(404).send({ error: "not_found" }); + } + return reply.code(404).send({ error: "no_pending_for_calendar" }); + } + const ts = hexToBytes(blob.pending_bytes_hex); + const ots = buildOtsFile({ + digest, + calendar_url: blob.calendar_url, + timestamp_bytes: ts, + }); + return sendOtsFile( + reply, + ots.bytes, + `tournamental-${root.slice(0, 16)}-${wantedSlug}.ots`, + row.ots_status === "confirmed", + ); + }, + ); +} + +function sendOtsFile( + reply: FastifyReply, + bytes: Uint8Array, + filename: string, + immutable: boolean, +): FastifyReply { + reply.header("Content-Type", "application/vnd.opentimestamps.ots"); + reply.header("Content-Disposition", `attachment; filename="${filename}"`); + reply.header( + "Cache-Control", + immutable + ? "public, max-age=31536000, immutable" + : "public, max-age=300, stale-while-revalidate=600", + ); + reply.code(200); + return reply.send(Buffer.from(bytes)); +} diff --git a/apps/game/src/routes/swarms.ts b/apps/game/src/routes/swarms.ts new file mode 100644 index 00000000..aeb9550f --- /dev/null +++ b/apps/game/src/routes/swarms.ts @@ -0,0 +1,249 @@ +/** + * Operator-keyed swarm-summary endpoints. + * + * POST /v1/swarms/:operator_id/summary , publish (idempotent) summary + * GET /v1/swarms/:operator_id , latest summary (edge-cached) + * GET /v1/swarms , global top-100 operators + * + * Auth model: + * POST is gated by a Bearer api_key (the same tnm_-prefixed key + * minted by /v1/bots/keys/issue). The operator_id MUST equal the + * sha256 hash of that key , i.e. the operator_id IS the api_key_hash. + * This is per the A13 brief ("the operator_id IS the api_key_hash for + * simplicity"). It avoids inventing a second identity column while + * still letting the GET side serve the hash without revealing the + * plaintext key. + * + * GET is fully public so Cloudflare's edge cache serves repeat hits + * without touching the origin. + * + * Edge caching (per CLAUDE.md docs/22): + * - GET /v1/swarms/: public, s-maxage=60, stale-while-revalidate=300 + * - GET /v1/swarms: public, s-maxage=60, stale-while-revalidate=300 + * - POST: private, no-store + * + * ETag: hash(operator_id, latest generated_at) , cheap revalidation + * for clients that just want to know if the summary moved on. + * + * Spec: A13 task brief. + */ +import { createHash } from "node:crypto"; + +import type { FastifyInstance, FastifyRequest } from "fastify"; +import { z } from "zod"; + +import type { GameStore } from "../store/db.js"; +import { runPerfectTrackWatch } from "../services/perfect-track-watch.js"; + +const HEX_64 = /^[0-9a-f]{64}$/; +// operator_id is the api_key_hash (sha256 hex). 64 lower-hex chars. +const OPERATOR_ID_RE = /^[0-9a-f]{64}$/; +// bot_id reuses the same shape as the picks-bulk schema. +const BOT_ID_MAX = 128; + +const MAX_TOP_K = 1_000; +const MAX_ALIVE_ROWS = 200; +const MAX_TOTAL_BOTS = 1_000_000_000; + +const AliveAfterMatchSchema = z + .object({ + n: z.number().int().min(1).max(1_000), + alive_count: z.number().int().min(0).max(MAX_TOTAL_BOTS), + }) + .strict(); + +const TopKEntrySchema = z + .object({ + bot_id: z.string().min(1).max(BOT_ID_MAX), + score: z.number().int().min(0).max(1_000), + chalk_score: z.number().finite(), + }) + .strict(); + +const SummaryBodySchema = z + .object({ + total_bots: z.number().int().min(0).max(MAX_TOTAL_BOTS), + bots_alive_after_match_n: z.array(AliveAfterMatchSchema).max(MAX_ALIVE_ROWS), + best_bot_score: z.number().int().min(0).max(1_000), + top_k: z.array(TopKEntrySchema).max(MAX_TOP_K), + merkle_root: z.string().regex(HEX_64), + kickoff_at: z.number().int(), + generated_at: z.number().int(), + }) + .strict(); + +const ListQuerySchema = z + .object({ + limit: z + .union([z.string(), z.number()]) + .transform((v) => Number(v)) + .pipe(z.number().int().min(1).max(1000)) + .optional(), + }) + .strict(); + +function authBearer(req: FastifyRequest): string | null { + const h = req.headers["authorization"]; + if (typeof h !== "string" || !h.startsWith("Bearer ")) return null; + const v = h.slice("Bearer ".length).trim(); + return v.length > 0 ? v : null; +} + +function buildEtag(operator_id: string, generated_at: number): string { + return `"${createHash("sha256") + .update(`${operator_id}:${generated_at}`) + .digest("hex") + .slice(0, 16)}"`; +} + +export interface SwarmsRoutesDeps { + readonly store: GameStore; + readonly nowMs?: () => number; + /** + * When true, after a successful summary insert run the perfect-track + * watcher inline so the home-page badge refreshes immediately. + * Defaults to true; tests can disable for isolation. + */ + readonly runPerfectTrackOnPost?: boolean; +} + +export async function registerSwarmsRoutes( + app: FastifyInstance, + deps: SwarmsRoutesDeps, +): Promise { + const now = deps.nowMs ?? (() => Date.now()); + const runWatch = deps.runPerfectTrackOnPost ?? true; + + // POST /v1/swarms/:operator_id/summary + app.post("/v1/swarms/:operator_id/summary", async (req, reply) => { + reply.header("Cache-Control", "private, no-store"); + + const params = req.params as { operator_id?: string }; + const operatorId = (params.operator_id ?? "").toLowerCase(); + if (!OPERATOR_ID_RE.test(operatorId)) { + return reply.code(400).send({ error: "invalid_operator_id" }); + } + + const plain = authBearer(req); + if (!plain) { + return reply.code(401).send({ error: "missing_api_key" }); + } + const keyRow = deps.store.apiKeys.lookupByPlain(plain); + if (!keyRow) { + return reply.code(401).send({ error: "invalid_api_key" }); + } + // Authorise: the operator_id MUST equal the api_key_hash of the + // bearer key. Mismatch = 403 so a leaked key cannot be used to + // post under someone else's operator identity. + if (keyRow.key_hash !== operatorId) { + return reply.code(403).send({ error: "not_operator" }); + } + + const parsed = SummaryBodySchema.safeParse(req.body); + if (!parsed.success) { + return reply.code(400).send({ + error: "invalid_payload", + detail: parsed.error.flatten(), + }); + } + + const inserted = deps.store.swarmSummaries.upsert({ + operator_id: operatorId, + kickoff_at: parsed.data.kickoff_at, + total_bots: parsed.data.total_bots, + bots_alive_after_match_n: parsed.data.bots_alive_after_match_n, + best_bot_score: parsed.data.best_bot_score, + top_k: parsed.data.top_k, + merkle_root: parsed.data.merkle_root, + generated_at: parsed.data.generated_at, + }); + + // Surface a fresh perfect-track signal if this summary crossed + // the match-80 threshold. We run inline so the leaderboard badge + // updates without waiting for the next scoring tick. + if (runWatch) { + try { + runPerfectTrackWatch({ + store: deps.store, + now: now(), + }); + } catch { + // Watcher failures must never block a summary publish. + } + } + + return reply.code(201).send({ + operator_id: inserted.operator_id, + kickoff_at: inserted.kickoff_at, + total_bots: inserted.total_bots, + best_bot_score: inserted.best_bot_score, + merkle_root: inserted.merkle_root, + generated_at: inserted.generated_at, + }); + }); + + // GET /v1/swarms/:operator_id + app.get("/v1/swarms/:operator_id", async (req, reply) => { + const params = req.params as { operator_id?: string }; + const operatorId = (params.operator_id ?? "").toLowerCase(); + if (!OPERATOR_ID_RE.test(operatorId)) { + return reply.code(400).send({ error: "invalid_operator_id" }); + } + + const row = deps.store.swarmSummaries.getLatestForOperator(operatorId); + if (!row) { + // Still set edge cache so probes don't hammer the origin. + reply.header( + "Cache-Control", + "public, s-maxage=60, stale-while-revalidate=300", + ); + return reply.code(404).send({ error: "not_found" }); + } + + const etag = buildEtag(row.operator_id, row.generated_at); + const ifNoneMatch = req.headers["if-none-match"]; + if (typeof ifNoneMatch === "string" && ifNoneMatch === etag) { + reply.header( + "Cache-Control", + "public, s-maxage=60, stale-while-revalidate=300", + ); + reply.header("ETag", etag); + return reply.code(304).send(); + } + + reply.header( + "Cache-Control", + "public, s-maxage=60, stale-while-revalidate=300", + ); + reply.header("Content-Type", "application/json"); + reply.header("ETag", etag); + return reply.send(deps.store.swarmSummaries.parse(row)); + }); + + // GET /v1/swarms , global aggregate leaderboard. + app.get("/v1/swarms", async (req, reply) => { + const parsedQuery = ListQuerySchema.safeParse(req.query ?? {}); + if (!parsedQuery.success) { + return reply.code(400).send({ + error: "invalid_query", + detail: parsedQuery.error.flatten(), + }); + } + const limit = parsedQuery.data.limit ?? 100; + const rows = deps.store.swarmSummaries.topOperators(limit); + reply.header( + "Cache-Control", + "public, s-maxage=60, stale-while-revalidate=300", + ); + return { + operators: rows.map((r) => ({ + operator_id: r.operator_id, + total_bots: r.total_bots, + best_bot_score: r.best_bot_score, + merkle_root: r.merkle_root, + generated_at: r.generated_at, + kickoff_at: r.kickoff_at, + })), + }; + }); +} diff --git a/apps/game/src/server.ts b/apps/game/src/server.ts index 159092dd..50274a44 100644 --- a/apps/game/src/server.ts +++ b/apps/game/src/server.ts @@ -31,7 +31,14 @@ import { registerLeaderboardRoutes } from "./routes/leaderboard.js"; import { registerSyndicateRoutes } from "./routes/syndicate.js"; import { registerPunditRoutes } from "./routes/pundit.js"; import { registerPickRoutes } from "./routes/picks.js"; +import { registerPicksBulkRoute } from "./routes/picks-bulk.js"; +import { registerNodesRoutes } from "./routes/nodes.js"; +import { registerSwarmRoutes } from "./routes/swarm.js"; +import { registerSwarmsRoutes } from "./routes/swarms.js"; +import { registerPerfectTrackRoutes } from "./routes/perfect-track.js"; import { registerUserApiKeyRoutes } from "./routes/user-api-keys.js"; +import { registerBotsKeysIssueRoute } from "./routes/bots-keys-issue.js"; +import { registerOddsRoutes } from "./routes/odds.js"; import { GameStore } from "./store/db.js"; import { LeaderboardCache } from "./scoring/cache.js"; import { recomputeVerifiedPundits } from "./pundit/compute.js"; @@ -42,6 +49,14 @@ export interface BuildServerOptions { dbPath?: string; /** Override migrations dir for tests. */ migrationsDir?: string; + /** Disable real OTS calendar submission (tests). */ + disableOts?: boolean; + /** Override OTS calendar set (tests). */ + otsCalendars?: readonly string[]; + /** Inject fetch for OTS submission (tests). */ + otsFetch?: typeof fetch; + /** Public base URL used to build absolute swarm-proof links. */ + publicBaseUrl?: string; /** Override the admin token (tests pass a known one). Falls back to env. */ adminToken?: string | null; /** Override leaderboard cache TTL in milliseconds (tests). Falls back to env. */ @@ -141,10 +156,24 @@ export async function buildServer(opts: BuildServerOptions = {}): Promise Promise; +} + +export interface CommitKickoffResult { + root: string; + leaf_count: number; +} + +interface BracketRowWithPayload { + id: string; + user_id: string; + payload_json: string; + locked_at: number; +} + +interface PickRecord { + matchId?: string; + outcome?: Outcome | string; + lockedAt?: string; +} + +function isOutcome(s: unknown): s is Outcome { + return s === "home_win" || s === "draw" || s === "away_win"; +} + +/** + * Build a kickoff commitment for one (tournament, match) pair. Reads + * are SELECT-only; the only write is the committed_at_utc stamp on + * each contributing bracket. The DB read and the stamp run inside one + * transaction so a concurrent re-score does not observe a + * half-committed state. + */ +export async function commitKickoff( + opts: CommitKickoffOpts, +): Promise { + // Pull every bracket for this tournament; in production the worst + // case is ~80k rows pre-kickoff and SQLite can stream them under + // 50ms. We filter in Node because the picks are JSON inside + // payload_json, not a separate column. + const rows = opts.store.db + .prepare( + `SELECT id, user_id, payload_json, locked_at + FROM brackets + WHERE tournament_id = ?`, + ) + .all(opts.tournament_id) as BracketRowWithPayload[]; + + const leaves: PickLeaf[] = []; + const includedBracketIds: string[] = []; + for (const r of rows) { + let parsed: { + matchPredictions?: Record; + knockoutPredictions?: Record; + }; + try { + parsed = JSON.parse(r.payload_json) as typeof parsed; + } catch { + continue; + } + const pick = + parsed.matchPredictions?.[opts.match_id] ?? + parsed.knockoutPredictions?.[opts.match_id]; + if (!pick) continue; + if (!isOutcome(pick.outcome)) continue; + leaves.push({ + bot_id: r.user_id, + match_id: opts.match_id, + outcome: pick.outcome, + t: r.locked_at, + }); + includedBracketIds.push(r.id); + } + + const tree = buildMerkle(leaves); + await opts.postOts(tree.root); + + if (includedBracketIds.length > 0) { + const stampStmt = opts.store.db.prepare( + `UPDATE brackets SET committed_at_utc = ? WHERE id = ?`, + ); + const txn = opts.store.db.transaction((ids: readonly string[]) => { + for (const id of ids) stampStmt.run(opts.committed_at_utc, id); + }); + txn(includedBracketIds); + } + + return { root: tree.root, leaf_count: leaves.length }; +} diff --git a/apps/game/src/services/leaderboard-cache.ts b/apps/game/src/services/leaderboard-cache.ts new file mode 100644 index 00000000..d37f9789 --- /dev/null +++ b/apps/game/src/services/leaderboard-cache.ts @@ -0,0 +1,103 @@ +/** + * In-memory LRU cache for the Bot Arena leaderboard reads. + * + * Separate from `apps/game/src/scoring/cache.ts` because that one is + * tied to the LeaderboardRow shape and the (tournament, syndicate) + * scoping; the Bot Arena reads are tabbed by humans|bots|all and need + * prefix invalidation so a single kickoff event can wipe every tab's + * cached snapshot in one call. + * + * Sized so the worst-case key cardinality (one tournament x three + * scopes x per-pool tabs) stays well under maxEntries on the dev box. + * When the production fan-out justifies it the Map is the line to swap + * for a Redis backend , the public API stays the same. + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §8.3 + */ + +interface CacheEntry { + value: T; + expires_at: number; +} + +export interface LeaderboardCacheOpts { + /** Default time-to-live in ms. The Bot Arena default is 30s; the in-match acceleration is set per-call. */ + defaultTtlMs?: number; + /** Soft max entries. When exceeded the oldest insertion is evicted. */ + maxEntries?: number; +} + +/** + * Generic in-memory cache used by the Bot Arena leaderboard tabs. + * + * Map iteration in V8 is insertion-ordered, so deleting the first key + * on eviction is a cheap O(1) approximation of LRU. The Bot Arena + * leaderboard fan-out fits in <100 keys so the difference between true + * LRU and insertion-order LRU is irrelevant. + */ +export class LeaderboardCache { + private readonly map = new Map>(); + private readonly defaultTtlMs: number; + private readonly maxEntries: number; + + constructor(opts: LeaderboardCacheOpts = {}) { + this.defaultTtlMs = opts.defaultTtlMs ?? 30_000; + this.maxEntries = opts.maxEntries ?? 512; + } + + async get( + key: string, + fetcher: () => Promise, + ttlOverrideMs?: number, + ): Promise { + const now = Date.now(); + const cached = this.map.get(key) as CacheEntry | undefined; + if (cached && cached.expires_at > now) { + return cached.value; + } + const value = await fetcher(); + const ttl = ttlOverrideMs ?? this.defaultTtlMs; + this.map.set(key, { value, expires_at: now + ttl }); + this.evictIfFull(); + return value; + } + + /** Synchronously read a still-fresh cached value without invoking a fetcher. */ + peek(key: string): T | null { + const now = Date.now(); + const cached = this.map.get(key) as CacheEntry | undefined; + if (cached && cached.expires_at > now) return cached.value; + return null; + } + + invalidate(key: string): void { + this.map.delete(key); + } + + /** + * Drop every key starting with the supplied prefix. Used by the + * kickoff and match-completed events to invalidate every tab's + * snapshot in one call. + */ + invalidatePrefix(prefix: string): void { + for (const k of [...this.map.keys()]) { + if (k.startsWith(prefix)) this.map.delete(k); + } + } + + clear(): void { + this.map.clear(); + } + + size(): number { + return this.map.size; + } + + private evictIfFull(): void { + while (this.map.size > this.maxEntries) { + const firstKey = this.map.keys().next().value; + if (firstKey === undefined) break; + this.map.delete(firstKey); + } + } +} diff --git a/apps/game/src/services/ots-scheduler.ts b/apps/game/src/services/ots-scheduler.ts new file mode 100644 index 00000000..5c0b77f9 --- /dev/null +++ b/apps/game/src/services/ots-scheduler.ts @@ -0,0 +1,180 @@ +/** + * OTS upgrade scheduler — polls calendar servers for pending swarm + * claims and rewrites the row with the Bitcoin-attested proof once + * one comes back. + * + * Design: + * - Every `pollIntervalMs` we pick up every row in `swarm_claims` + * with `ots_status='pending'` AND not polled in the last + * `stalenessMs` window. + * - For each row we walk its pending calendars and call + * GET /timestamp/. The first calendar that returns a + * payload containing a Bitcoin block attestation wins; we + * persist its upgraded bytes and flip the row to 'confirmed'. + * - Calendars that return null (still aggregating) bump the row's + * `last_upgrade_attempt_at` so the next sweep waits a while. + * + * This is the central-tier mirror of the script the official OTS CLI + * runs locally (`ots upgrade snapshot.db.ots`). We just keep doing it + * automatically on the server side and surface the result via the + * verify route. + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §15.6 + */ +import { + bytesToHex, + fetchUpgrade, + hexToBytes, + type CalendarUpgradeResult, +} from "../lib/ots-calendar.js"; +import type { SwarmClaimStore, SwarmClaimRow } from "../store/swarm-claims.js"; + +export interface SchedulerOptions { + /** How often to wake up and scan. Default 5 minutes. */ + pollIntervalMs?: number; + /** Don't re-poll a row that was tried in the last N ms. Default 30m. */ + stalenessMs?: number; + /** Per-cycle limit. Default 50. */ + batchSize?: number; + /** Per-request timeout. Default 10s. */ + requestTimeoutMs?: number; + /** Inject fetch for tests. */ + fetchImpl?: typeof fetch; + /** Inject clock for tests. */ + now?: () => number; +} + +export class OtsScheduler { + // `setInterval` returns a `Timeout` (Node) or `number` (browser); we + // only ever use it on the server side, but typing it as the return + // value of `setInterval` keeps us off the `NodeJS.*` global namespace + // which the test tsconfig doesn't pull in. + private timer: ReturnType | null = null; + private running = false; + private readonly pollIntervalMs: number; + private readonly stalenessMs: number; + private readonly batchSize: number; + private readonly requestTimeoutMs: number; + private readonly fetchImpl?: typeof fetch; + private readonly now: () => number; + + constructor( + private readonly store: SwarmClaimStore, + opts: SchedulerOptions = {}, + ) { + this.pollIntervalMs = opts.pollIntervalMs ?? 5 * 60_000; + this.stalenessMs = opts.stalenessMs ?? 30 * 60_000; + this.batchSize = opts.batchSize ?? 50; + this.requestTimeoutMs = opts.requestTimeoutMs ?? 10_000; + this.fetchImpl = opts.fetchImpl; + this.now = opts.now ?? Date.now; + } + + start(): void { + if (this.timer) return; + // Fire the first sweep on the next tick so callers can start the + // scheduler before the DB is fully populated without missing a + // pending row. + this.timer = setInterval(() => { + void this.tick(); + }, this.pollIntervalMs); + // Allow the process to exit while the scheduler is the only thing + // keeping the event loop alive. + if (this.timer.unref) this.timer.unref(); + } + + stop(): void { + if (this.timer) { + clearInterval(this.timer); + this.timer = null; + } + } + + /** + * Run one sweep. Returns the per-row outcomes so tests and ops can + * trace progress. Concurrent ticks are serialised because each row + * we touch is an SQLite write and we don't want N pollers racing. + */ + async tick(): Promise> { + if (this.running) return []; + this.running = true; + try { + const pending = this.store.pendingToUpgrade({ + staleness_ms: this.stalenessMs, + limit: this.batchSize, + now: this.now(), + }); + const out: Array<{ node_id: string; run_id: string; upgraded: boolean }> = []; + for (const row of pending) { + const upgraded = await this.tryUpgradeRow(row); + out.push({ + node_id: row.node_id, + run_id: row.run_id, + upgraded, + }); + } + return out; + } finally { + this.running = false; + } + } + + /** + * Attempt to upgrade one row. Walks every pending calendar; first + * one that comes back with a Bitcoin attestation wins. + * + * Returns true iff the row flipped to 'confirmed'. False means we + * polled but no calendar had a Bitcoin attestation yet — the row + * stays 'pending' with `last_upgrade_attempt_at` bumped. + */ + async tryUpgradeRow(row: SwarmClaimRow): Promise { + this.store.recordUpgradeAttempt({ + node_id: row.node_id, + run_id: row.run_id, + now: this.now(), + }); + const blobs = this.store.parsePending(row); + if (blobs.length === 0) return false; + + let digest: Uint8Array; + try { + digest = hexToBytes(row.merkle_root); + } catch { + return false; + } + const digestHex = bytesToHex(digest); + + for (const blob of blobs) { + let upgrade: CalendarUpgradeResult | null; + try { + upgrade = await fetchUpgrade({ + calendar_url: blob.calendar_url, + digest_hex: digestHex, + timeoutMs: this.requestTimeoutMs, + fetchImpl: this.fetchImpl, + }); + } catch { + continue; + } + if (!upgrade) continue; + if (!upgrade.bitcoin_confirmed) { + // Calendar returned bytes but no BTC attestation yet — keep + // walking other calendars; one of them might be ahead. + continue; + } + this.store.recordUpgradeSuccess({ + node_id: row.node_id, + run_id: row.run_id, + calendar_url: upgrade.calendar_url, + upgraded_ots_hex: bytesToHex(upgrade.upgraded_bytes), + now: this.now(), + }); + return true; + } + return false; + } +} diff --git a/apps/game/src/services/perfect-track-watch.ts b/apps/game/src/services/perfect-track-watch.ts new file mode 100644 index 00000000..c08569cd --- /dev/null +++ b/apps/game/src/services/perfect-track-watch.ts @@ -0,0 +1,164 @@ +/** + * Perfect-bracket-track alert service. + * + * Scans the latest swarm_summary row for every operator and emits an + * alert row for any operator that still has bots alive after match 80. + * Each alert is idempotent on (operator_id, match_number) so re-running + * the watcher does not duplicate notifications. + * + * Side-effects: + * - Persists rows into `perfect_track_alert` (consumed by the home + * page + the /leaderboard badge). + * - Logs an info entry per fresh alert. + * - POSTs a JSON notification to the PERFECT_TRACK_WEBHOOK_URL env + * var (optional, no-op if unset). Failures are absorbed silently + * because a missing webhook should never block scoring. + * + * Trigger surfaces: + * - apps/game/src/routes/swarms.ts POST handler runs this inline + * after a summary is published so the badge updates immediately. + * - apps/game/src/routes/match.ts (admin scoring) calls this after + * each match's scoring completes so newly-published summaries with + * a high-match-number frontier are surfaced even when no fresh + * summary triggered the watcher. + * + * Spec: A13 task brief. + */ +import type { GameStore } from "../store/db.js"; +import type { SwarmSummaryRow } from "../store/swarm-summaries.js"; + +/** Threshold for "still on a perfect track". Match 80 = the spec hook. */ +export const PERFECT_TRACK_MATCH_THRESHOLD = 80; + +export interface PerfectTrackAlert { + operator_id: string; + match_number: number; + alive_count: number; +} + +export interface RunWatchDeps { + readonly store: GameStore; + readonly now: number; + /** Override the env-driven webhook URL (tests). */ + readonly webhookUrl?: string | null; + /** Inject fetch (tests). */ + readonly fetchImpl?: typeof fetch; + /** Optional logger; falls back to console.info. */ + readonly logger?: { info: (data: unknown, msg?: string) => void }; +} + +export interface RunWatchResult { + alertsRecorded: PerfectTrackAlert[]; + webhookPosted: number; +} + +/** + * Inspect every operator's latest summary and record an alert per + * operator whose alive_count at match >= 80 is > 0. + * + * Synchronous DB work; the webhook POST is fired-and-forgotten via the + * returned promise so callers can await if they want determinism in + * tests. + */ +export function runPerfectTrackWatch(deps: RunWatchDeps): RunWatchResult { + const alerts: PerfectTrackAlert[] = []; + const summaries = deps.store.swarmSummaries.latestPerOperator(); + for (const row of summaries) { + const alert = pickHighestAlive(row); + if (alert) { + deps.store.perfectTrackAlerts.recordAlert({ + operator_id: alert.operator_id, + match_number: alert.match_number, + alive_count: alert.alive_count, + now: deps.now, + }); + alerts.push(alert); + } + } + + if (alerts.length > 0) { + const logger = deps.logger ?? console; + logger.info( + { + count: alerts.length, + operators: alerts.map((a) => ({ + operator_id_short: a.operator_id.slice(0, 12), + match_number: a.match_number, + alive_count: a.alive_count, + })), + }, + "perfect-track alert", + ); + } + + // Webhook is fire-and-forget; the synchronous return value never + // blocks on the network call. + const webhookUrl = + deps.webhookUrl !== undefined + ? deps.webhookUrl + : process.env.PERFECT_TRACK_WEBHOOK_URL ?? null; + let webhookPosted = 0; + if (webhookUrl && alerts.length > 0) { + const fetcher = deps.fetchImpl ?? globalThis.fetch; + if (typeof fetcher === "function") { + for (const a of alerts) { + try { + void fetcher(webhookUrl, { + method: "POST", + headers: { "content-type": "application/json" }, + body: JSON.stringify({ + event: "perfect_track_alert", + operator_id: a.operator_id, + match_number: a.match_number, + alive_count: a.alive_count, + detected_at: deps.now, + }), + }) + .then(() => undefined) + .catch(() => undefined); + webhookPosted += 1; + } catch { + // Silent: a webhook failure must never block scoring. + } + } + } + } + + return { alertsRecorded: alerts, webhookPosted }; +} + +/** + * Find the highest n >= PERFECT_TRACK_MATCH_THRESHOLD with alive_count + * > 0 in this summary's bots_alive_after_match_n array. Returns null + * if no such entry exists. + */ +function pickHighestAlive(row: SwarmSummaryRow): PerfectTrackAlert | null { + let parsed: Array<{ n: number; alive_count: number }>; + try { + parsed = JSON.parse(row.alive_by_match_json) as Array<{ + n: number; + alive_count: number; + }>; + if (!Array.isArray(parsed)) return null; + } catch { + return null; + } + let best: { n: number; alive_count: number } | null = null; + for (const entry of parsed) { + if ( + entry && + typeof entry.n === "number" && + typeof entry.alive_count === "number" && + entry.n >= PERFECT_TRACK_MATCH_THRESHOLD && + entry.alive_count > 0 + ) { + if (!best || entry.n > best.n) best = entry; + } + } + if (!best) return null; + return { + operator_id: row.operator_id, + match_number: best.n, + alive_count: best.alive_count, + }; +} diff --git a/apps/game/src/store/api-keys.ts b/apps/game/src/store/api-keys.ts new file mode 100644 index 00000000..9abca759 --- /dev/null +++ b/apps/game/src/store/api-keys.ts @@ -0,0 +1,147 @@ +/** + * API key DAO for the Open Bot Arena. + * + * Keys are minted plaintext at issuance and the plaintext is returned + * to the caller ONCE. All subsequent lookups go through a sha256 hash + * stored in the api_key table, so a DB leak does not expose any + * callable keys. + * + * Academic emails (.edu, .ac.uk, .ac.nz, .edu.au, .ac.za, .edu.cn, + * .ac.jp) get 10x the default per-key quotas to support research + * swarms. The list is intentionally small; ad-hoc requests go through + * the manual /admin/api-keys page or info@tournamental.com. + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §6.3, §14 + */ +import { createHash, randomBytes } from "node:crypto"; + +import type { Database as DatabaseT } from "better-sqlite3"; + +const ACADEMIC_SUFFIXES = [ + ".edu", + ".ac.uk", + ".ac.nz", + ".edu.au", + ".ac.za", + ".edu.cn", + ".ac.jp", +]; + +const DEFAULT_QUOTA_BOTS = 1_000; +const ACADEMIC_QUOTA_BOTS = 10_000; +const DEFAULT_QUOTA_PICKS_PER_HOUR = 100_000; +const ACADEMIC_QUOTA_PICKS_PER_HOUR = 1_000_000; + +export interface ApiKeyRow { + key_hash: string; + owner_email: string; + label: string | null; + quota_bots: number; + quota_picks_per_hour: number; + created_at: number; + revoked_at: number | null; +} + +export interface IssueParams { + owner_email: string; + label?: string | null; + /** Override the clock (tests). */ + now?: number; +} + +export interface IssueResult { + /** Plaintext key, returned ONCE at issuance. Caller must surface to the user and not persist server-side. */ + api_key: string; + key_hash: string; + owner_email: string; + label: string | null; + quota_bots: number; + quota_picks_per_hour: number; + created_at: number; +} + +/** + * Mint a fresh 32-character base64url key with a stable `tnm_` prefix. + * 24 random bytes = 192 bits, ~32 base64url chars after stripping + * padding. Comfortably wider than the 128-bit unguessable threshold. + */ +export function generateApiKey(): string { + const raw = randomBytes(24).toString("base64url").slice(0, 32); + return `tnm_${raw}`; +} + +export function hashApiKey(plain: string): string { + return createHash("sha256").update(plain).digest("hex"); +} + +function isAcademic(email: string): boolean { + const lower = email.toLowerCase(); + return ACADEMIC_SUFFIXES.some((s) => lower.endsWith(s)); +} + +export class ApiKeyStore { + constructor(private readonly db: DatabaseT) {} + + issue(params: IssueParams): IssueResult { + const api_key = generateApiKey(); + const key_hash = hashApiKey(api_key); + const academic = isAcademic(params.owner_email); + const quota_bots = academic ? ACADEMIC_QUOTA_BOTS : DEFAULT_QUOTA_BOTS; + const quota_picks_per_hour = academic + ? ACADEMIC_QUOTA_PICKS_PER_HOUR + : DEFAULT_QUOTA_PICKS_PER_HOUR; + const created_at = params.now ?? Date.now(); + const label = params.label ?? null; + this.db + .prepare( + `INSERT INTO api_key + (key_hash, owner_email, label, quota_bots, + quota_picks_per_hour, created_at) + VALUES (?, ?, ?, ?, ?, ?)`, + ) + .run( + key_hash, + params.owner_email, + label, + quota_bots, + quota_picks_per_hour, + created_at, + ); + return { + api_key, + key_hash, + owner_email: params.owner_email, + label, + quota_bots, + quota_picks_per_hour, + created_at, + }; + } + + /** + * Look up an active (non-revoked) key by its plaintext value. Returns + * null on miss so the caller can answer 401 without leaking whether + * the key existed and was revoked vs never minted. + */ + lookupByPlain(plain: string): ApiKeyRow | null { + const key_hash = hashApiKey(plain); + return this.lookupByHash(key_hash); + } + + lookupByHash(key_hash: string): ApiKeyRow | null { + const row = this.db + .prepare( + `SELECT * FROM api_key + WHERE key_hash = ? AND revoked_at IS NULL`, + ) + .get(key_hash) as ApiKeyRow | undefined; + return row ?? null; + } + + revoke(plain: string, now: number = Date.now()): void { + const key_hash = hashApiKey(plain); + this.db + .prepare(`UPDATE api_key SET revoked_at = ? WHERE key_hash = ?`) + .run(now, key_hash); + } +} diff --git a/apps/game/src/store/bot-owners.ts b/apps/game/src/store/bot-owners.ts new file mode 100644 index 00000000..4a75e6a3 --- /dev/null +++ b/apps/game/src/store/bot-owners.ts @@ -0,0 +1,91 @@ +/** + * Bot ownership DAO. Ties an externally-issued bot (a row in `users` + * with is_bot=1) to the API key that minted it. + * + * Used by: + * - The /v1/picks/bulk endpoint, which rejects pick submissions for + * a bot the caller's API key does not own. + * - The bot-keys page, which displays the number of bots provisioned + * against each key vs the per-key quota. + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §6.4, §7.2 + */ +import type { Database as DatabaseT } from "better-sqlite3"; + +export interface ClaimParams { + bot_id: string; + api_key_hash: string; + owner_email: string; + /** Override the clock (tests). */ + now?: number; +} + +export class BotOwnerStore { + constructor(private readonly db: DatabaseT) {} + + /** + * Record that this bot belongs to this API key. Idempotent on + * bot_id , re-running the seed CLI or the same bulk-insert payload + * does not duplicate rows. + */ + claim(p: ClaimParams): void { + this.db + .prepare( + `INSERT INTO bot_owner + (bot_id, owner_email, owner_api_key_hash, created_at) + VALUES (?, ?, ?, ?) + ON CONFLICT(bot_id) DO NOTHING`, + ) + .run(p.bot_id, p.owner_email, p.api_key_hash, p.now ?? Date.now()); + } + + countByApiKey(api_key_hash: string): number { + const row = this.db + .prepare( + `SELECT COUNT(*) AS n FROM bot_owner WHERE owner_api_key_hash = ?`, + ) + .get(api_key_hash) as { n: number }; + return row.n; + } + + ownedBotIds(api_key_hash: string): string[] { + return ( + this.db + .prepare( + `SELECT bot_id FROM bot_owner + WHERE owner_api_key_hash = ? + ORDER BY created_at ASC, bot_id ASC`, + ) + .all(api_key_hash) as Array<{ bot_id: string }> + ).map((r) => r.bot_id); + } + + isOwner(api_key_hash: string, bot_id: string): boolean { + const row = this.db + .prepare( + `SELECT 1 FROM bot_owner + WHERE owner_api_key_hash = ? AND bot_id = ?`, + ) + .get(api_key_hash, bot_id); + return row !== undefined; + } + + /** + * Bulk ownership check used by /v1/picks/bulk: returns the subset of + * `bot_ids` that the key does NOT own. Cheap enough for 1k bots per + * request (the spec ceiling) and avoids N round-trips through the + * single-row isOwner path. + */ + notOwnedBy(api_key_hash: string, bot_ids: readonly string[]): string[] { + if (bot_ids.length === 0) return []; + const placeholders = bot_ids.map(() => "?").join(","); + const rows = this.db + .prepare( + `SELECT bot_id FROM bot_owner + WHERE owner_api_key_hash = ? AND bot_id IN (${placeholders})`, + ) + .all(api_key_hash, ...bot_ids) as Array<{ bot_id: string }>; + const owned = new Set(rows.map((r) => r.bot_id)); + return bot_ids.filter((id) => !owned.has(id)); + } +} diff --git a/apps/game/src/store/db.ts b/apps/game/src/store/db.ts index 7ebefe68..8736486e 100644 --- a/apps/game/src/store/db.ts +++ b/apps/game/src/store/db.ts @@ -17,6 +17,15 @@ import Database from "better-sqlite3"; import type { Database as DatabaseT, Statement } from "better-sqlite3"; import type { Bracket } from "../types.js"; +import { ApiKeyStore } from "./api-keys.js"; +import { BotOwnerStore } from "./bot-owners.js"; +import { QuotaStore } from "./quotas.js"; +import { FederatedNodeStore } from "./federated-nodes.js"; +import { SwarmClaimStore } from "./swarm-claims.js"; +import { + PerfectTrackAlertStore, + SwarmSummaryStore, +} from "./swarm-summaries.js"; export interface GameStoreOptions { /** Filesystem path to the SQLite file. ":memory:" for tests. */ @@ -99,6 +108,15 @@ export class GameStore { readonly db: DatabaseT; private readonly migrationsDir: string; + // Bot Arena DAOs (Phase 1 + Phase 2 forward-compat). + readonly apiKeys!: ApiKeyStore; + readonly botOwners!: BotOwnerStore; + readonly quotas!: QuotaStore; + readonly federatedNodes!: FederatedNodeStore; + readonly swarmClaims!: SwarmClaimStore; + readonly swarmSummaries!: SwarmSummaryStore; + readonly perfectTrackAlerts!: PerfectTrackAlertStore; + // Prepared statements private upsertUserStmt!: Statement; private insertBracketStmt!: Statement; @@ -113,6 +131,8 @@ export class GameStore { private getMatchResultStmt!: Statement; private listMatchResultsStmt!: Statement; private leaderboardStmt!: Statement; + private leaderboardHumansStmt!: Statement; + private leaderboardBotsStmt!: Statement; private leaderboardSyndicateStmt!: Statement; private upsertSyndicateMemberStmt!: Statement; private upsertSyndicateOwnerMembershipStmt!: Statement; @@ -142,6 +162,24 @@ export class GameStore { this.migrationsDir = opts.migrationsDir ?? defaultMigrationsDir(); this.applyMigrations(); this.prepareStatements(); + + // Bot Arena DAOs are wired here so the rest of the service does + // not need to know which file the underlying SQLite lives in or + // which migration laid the tables down. + (this as { apiKeys: ApiKeyStore }).apiKeys = new ApiKeyStore(this.db); + (this as { botOwners: BotOwnerStore }).botOwners = new BotOwnerStore( + this.db, + ); + (this as { quotas: QuotaStore }).quotas = new QuotaStore(this.db); + (this as { federatedNodes: FederatedNodeStore }).federatedNodes = + new FederatedNodeStore(this.db); + (this as { swarmClaims: SwarmClaimStore }).swarmClaims = new SwarmClaimStore( + this.db, + ); + (this as { swarmSummaries: SwarmSummaryStore }).swarmSummaries = + new SwarmSummaryStore(this.db); + (this as { perfectTrackAlerts: PerfectTrackAlertStore }).perfectTrackAlerts = + new PerfectTrackAlertStore(this.db); } // ---------- migrations ---------- @@ -250,6 +288,27 @@ export class GameStore { ORDER BY correct_picks DESC, locked_at ASC, user_id ASC LIMIT ?`, ); + // Bot Arena scope filters. Each tab on /leaderboard hits one of + // these so the SQL plan is stable and the cache key partitions + // cleanly. idx_users_is_bot keeps the JOIN cheap. + this.leaderboardHumansStmt = this.db.prepare( + `SELECT b.id, b.user_id, b.score_total, b.share_guid, b.locked_at, + b.locked_at AS joined_at + FROM brackets b + JOIN users u ON u.id = b.user_id + WHERE b.tournament_id = ? AND u.is_bot = 0 + ORDER BY b.score_total DESC, b.locked_at ASC, b.user_id ASC + LIMIT ?`, + ); + this.leaderboardBotsStmt = this.db.prepare( + `SELECT b.id, b.user_id, b.score_total, b.share_guid, b.locked_at, + b.locked_at AS joined_at + FROM brackets b + JOIN users u ON u.id = b.user_id + WHERE b.tournament_id = ? AND u.is_bot = 1 + ORDER BY b.score_total DESC, b.locked_at ASC, b.user_id ASC + LIMIT ?`, + ); this.leaderboardSyndicateStmt = this.db.prepare( // Tim 2026-06-07: also return `sm.joined_at` so the route can // compute `matches_available_to_user` (count of fixtures kicked @@ -528,6 +587,35 @@ export class GameStore { return this.leaderboardStmt.all(tournamentId, n) as LeaderboardBracketRow[]; } + /** + * Scope-filtered top-N for the Bot Arena. + * + * scope = "humans" , the public default; filters u.is_bot = 0. + * scope = "bots" , the new Bots tab; filters u.is_bot = 1. + * scope = "all" , everyone, identical to topN(). + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §5.2 + */ + topNByScope( + tournamentId: string, + scope: "humans" | "bots" | "all", + n: number, + ): LeaderboardBracketRow[] { + if (scope === "humans") { + return this.leaderboardHumansStmt.all( + tournamentId, + n, + ) as LeaderboardBracketRow[]; + } + if (scope === "bots") { + return this.leaderboardBotsStmt.all( + tournamentId, + n, + ) as LeaderboardBracketRow[]; + } + return this.topN(tournamentId, n); + } + topNForSyndicate( tournamentId: string, syndicateId: string, diff --git a/apps/game/src/store/federated-nodes.ts b/apps/game/src/store/federated-nodes.ts new file mode 100644 index 00000000..8d69519f --- /dev/null +++ b/apps/game/src/store/federated-nodes.ts @@ -0,0 +1,245 @@ +/** + * Federated node DAO , Phase 2 forward-compat surface. + * + * Phase 2 (post-launch, in-tournament) onboards external operators who + * run their own Tournamental Bot Node Docker image, hold their bots' + * picks locally, and report commitments + post-match aggregates to the + * central tier. This DAO is the central-side persistence for that + * protocol so Phase 1 endpoints can already accept submissions; the + * Phase 2 build then ships the node image + the on-chain verification + * flow without changing the central schema again. + * + * Lifecycle: + * 1. Operator hits /v1/nodes/register , one row in `federated_node`. + * 2. Pre-kickoff, the node POSTs the merkle root of its bots' picks + * to /v1/nodes/commit , `commit()` here writes the merkle_root + * and bot_count to the (node_id, match_id) snapshot row. + * 3. Post-match, the node POSTs aggregate scoring + top-K to + * /v1/nodes/leaderboard , `reportLeaderboard()` fills in + * bots_correct, bots_still_perfect, and top_json_blob. + * + * Trust model is captured in spec §15.3 / §15.4 , this file is just + * the storage backbone. + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §15.2 + */ +import type { Database as DatabaseT } from "better-sqlite3"; + +export interface FederatedNodeRow { + node_id: string; + owner_email: string; + owner_api_key_hash: string; + public_url: string; + label: string | null; + registered_at: number; + last_seen_at: number | null; +} + +export interface FederatedSnapshotRow { + node_id: string; + match_id: string; + merkle_root: string | null; + kickoff_at: number | null; + total_bots: number | null; + bots_correct: number | null; + bots_still_perfect: number | null; + top_json_blob: string | null; + submitted_at: number; +} + +export interface RegisterParams { + node_id: string; + owner_email: string; + owner_api_key_hash: string; + public_url: string; + label?: string | null; + now?: number; +} + +export interface CommitParams { + node_id: string; + match_id: string; + merkle_root: string; + kickoff_at: number; + bot_count: number; + now?: number; +} + +export interface ReportLeaderboardParams { + node_id: string; + match_id: string; + total_bots: number; + bots_correct: number; + bots_still_perfect: number; + top: ReadonlyArray; + now?: number; +} + +export class FederatedNodeStore { + constructor(private readonly db: DatabaseT) {} + + register(p: RegisterParams): FederatedNodeRow { + const now = p.now ?? Date.now(); + this.db + .prepare( + `INSERT INTO federated_node + (node_id, owner_email, owner_api_key_hash, public_url, label, + registered_at, last_seen_at) + VALUES (?, ?, ?, ?, ?, ?, NULL)`, + ) + .run( + p.node_id, + p.owner_email, + p.owner_api_key_hash, + p.public_url, + p.label ?? null, + now, + ); + return this.getByNodeId(p.node_id) as FederatedNodeRow; + } + + getByNodeId(node_id: string): FederatedNodeRow | null { + const row = this.db + .prepare(`SELECT * FROM federated_node WHERE node_id = ?`) + .get(node_id) as FederatedNodeRow | undefined; + return row ?? null; + } + + getByApiKeyHash(api_key_hash: string): FederatedNodeRow[] { + return this.db + .prepare( + `SELECT * FROM federated_node + WHERE owner_api_key_hash = ? + ORDER BY registered_at ASC`, + ) + .all(api_key_hash) as FederatedNodeRow[]; + } + + touch(node_id: string, now: number = Date.now()): void { + this.db + .prepare(`UPDATE federated_node SET last_seen_at = ? WHERE node_id = ?`) + .run(now, node_id); + } + + /** + * Persist the pre-kickoff merkle commitment. If the node has already + * reported a leaderboard for this match (out-of-order delivery), the + * commit row is upserted to add the merkle_root + bot_count without + * clobbering the aggregate fields. + */ + commit(p: CommitParams): void { + const submitted_at = p.now ?? Date.now(); + this.db + .prepare( + `INSERT INTO federated_leaderboard_snapshot + (node_id, match_id, merkle_root, kickoff_at, total_bots, + bots_correct, bots_still_perfect, top_json_blob, + submitted_at) + VALUES (?, ?, ?, ?, ?, NULL, NULL, NULL, ?) + ON CONFLICT(node_id, match_id) DO UPDATE + SET merkle_root = excluded.merkle_root, + kickoff_at = excluded.kickoff_at, + total_bots = COALESCE(excluded.total_bots, total_bots), + submitted_at = excluded.submitted_at`, + ) + .run( + p.node_id, + p.match_id, + p.merkle_root, + p.kickoff_at, + p.bot_count, + submitted_at, + ); + } + + /** + * Persist the post-match aggregate report. Late-arriving commits + * for the same (node_id, match_id) preserve the merkle_root if one + * was already recorded. + */ + reportLeaderboard(p: ReportLeaderboardParams): void { + const submitted_at = p.now ?? Date.now(); + const top_blob = JSON.stringify(p.top ?? []); + this.db + .prepare( + `INSERT INTO federated_leaderboard_snapshot + (node_id, match_id, merkle_root, kickoff_at, total_bots, + bots_correct, bots_still_perfect, top_json_blob, + submitted_at) + VALUES (?, ?, NULL, NULL, ?, ?, ?, ?, ?) + ON CONFLICT(node_id, match_id) DO UPDATE + SET total_bots = excluded.total_bots, + bots_correct = excluded.bots_correct, + bots_still_perfect = excluded.bots_still_perfect, + top_json_blob = excluded.top_json_blob, + submitted_at = excluded.submitted_at`, + ) + .run( + p.node_id, + p.match_id, + p.total_bots, + p.bots_correct, + p.bots_still_perfect, + top_blob, + submitted_at, + ); + } + + getSnapshot(node_id: string, match_id: string): FederatedSnapshotRow | null { + const row = this.db + .prepare( + `SELECT * FROM federated_leaderboard_snapshot + WHERE node_id = ? AND match_id = ?`, + ) + .get(node_id, match_id) as FederatedSnapshotRow | undefined; + return row ?? null; + } + + listSnapshotsForMatch(match_id: string): FederatedSnapshotRow[] { + return this.db + .prepare( + `SELECT * FROM federated_leaderboard_snapshot + WHERE match_id = ? + ORDER BY submitted_at ASC`, + ) + .all(match_id) as FederatedSnapshotRow[]; + } + + /** + * Aggregate all snapshots across all nodes into a single top-K list + * ordered by per-row "score" descending. Used by GET + * /v1/leaderboard?source=federated. The score key is whatever each + * node emitted in its top_json_blob. + */ + listFederatedTopK(limit: number = 100): Array<{ + node_id: string; + match_id: string; + row: unknown; + }> { + const rows = this.db + .prepare( + `SELECT node_id, match_id, top_json_blob + FROM federated_leaderboard_snapshot + WHERE top_json_blob IS NOT NULL`, + ) + .all() as Array<{ + node_id: string; + match_id: string; + top_json_blob: string; + }>; + const out: Array<{ node_id: string; match_id: string; row: unknown }> = []; + for (const r of rows) { + let parsed: unknown[]; + try { + parsed = JSON.parse(r.top_json_blob); + } catch { + continue; + } + if (!Array.isArray(parsed)) continue; + for (const row of parsed) { + out.push({ node_id: r.node_id, match_id: r.match_id, row }); + } + } + return out.slice(0, limit); + } +} diff --git a/apps/game/src/store/quotas.ts b/apps/game/src/store/quotas.ts new file mode 100644 index 00000000..c06cb481 --- /dev/null +++ b/apps/game/src/store/quotas.ts @@ -0,0 +1,77 @@ +/** + * Sliding-hour per-API-key pick quota. + * + * Each window is bucketed to floor(now_ms / 3600000) * 3600000. A row + * in `quota_window` tracks the picks consumed during that hour. The + * primary key (api_key_hash, window_start) keeps the ledger compact , + * old rows can be GC'd by a daily cron without a complex query. + * + * Hard cap defaults live on the api_key row (quota_picks_per_hour) and + * are passed in by the caller, so this DAO does not need to know the + * academic-vs-default policy. + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §6.4, §8.1 + */ +import type { Database as DatabaseT } from "better-sqlite3"; + +const HOUR_MS = 3_600_000; + +export class QuotaStore { + constructor(private readonly db: DatabaseT) {} + + private windowStart(now: number): number { + return Math.floor(now / HOUR_MS) * HOUR_MS; + } + + consume(api_key_hash: string, n: number): void { + this.consumeAt(api_key_hash, n, Date.now()); + } + + consumeAt(api_key_hash: string, n: number, now: number): void { + if (n <= 0) return; + const window_start = this.windowStart(now); + this.db + .prepare( + `INSERT INTO quota_window + (api_key_hash, window_start, picks_used) + VALUES (?, ?, ?) + ON CONFLICT(api_key_hash, window_start) DO UPDATE + SET picks_used = picks_used + excluded.picks_used`, + ) + .run(api_key_hash, window_start, n); + } + + usedThisHour(api_key_hash: string): number { + return this.usedThisHourAt(api_key_hash, Date.now()); + } + + usedThisHourAt(api_key_hash: string, now: number): number { + const window_start = this.windowStart(now); + const row = this.db + .prepare( + `SELECT picks_used FROM quota_window + WHERE api_key_hash = ? AND window_start = ?`, + ) + .get(api_key_hash, window_start) as { picks_used: number } | undefined; + return row?.picks_used ?? 0; + } + + /** + * Attempt to charge `n` picks against the key. Returns true on + * success (consumed). Returns false and does not consume when the + * request would push the key over `hourly_cap` , the caller should + * respond 429 quota_exceeded. + */ + tryConsume( + api_key_hash: string, + n: number, + hourly_cap: number, + now: number = Date.now(), + ): boolean { + if (n > hourly_cap) return false; + const used = this.usedThisHourAt(api_key_hash, now); + if (used + n > hourly_cap) return false; + this.consumeAt(api_key_hash, n, now); + return true; + } +} diff --git a/apps/game/src/store/swarm-claims.ts b/apps/game/src/store/swarm-claims.ts new file mode 100644 index 00000000..a439da7a --- /dev/null +++ b/apps/game/src/store/swarm-claims.ts @@ -0,0 +1,321 @@ +/** + * Swarm-claim DAO — durable home of browser-swarm `/v1/swarm/commit` + * submissions and their OTS proof lifecycle. + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §15.6 + */ +import type { Database as DatabaseT } from "better-sqlite3"; + +export type OtsStatus = "pending" | "confirmed" | "failed"; + +export interface SwarmClaimRow { + node_id: string; + run_id: string; + master_seed: string; + strategy: string; + total_bots: number; + merkle_root: string; + top_n_claim_json: string; + claimed_score: number; + started_at: number; + finished_at: number; + submitted_at: number; + ots_status: OtsStatus; + pending_calendar_blobs: string; + upgraded_ots_hex: string | null; + upgraded_calendar_url: string | null; + upgraded_at: number | null; + last_upgrade_attempt_at: number | null; +} + +export interface PendingCalendarBlob { + calendar_url: string; + pending_bytes_hex: string; + submitted_at: number; +} + +export interface TopNClaim { + bot_index: number; + claimed_score: number; + picks_count: number; +} + +export interface UpsertClaimParams { + node_id: string; + run_id: string; + master_seed: string; + strategy: string; + total_bots: number; + merkle_root: string; + top_n_claim: TopNClaim; + started_at: number; + finished_at: number; + pending_calendar_blobs: readonly PendingCalendarBlob[]; + ots_status?: OtsStatus; + now?: number; +} + +export interface LeaderboardRow { + rank: number; + node_id_short: string; + bot_index: number; + claimed_score: number; + merkle_root: string; + ots_proof_url: string | null; + bitcoin_confirmed: boolean; + submitted_at: number; +} + +export class SwarmClaimStore { + constructor(private readonly db: DatabaseT) {} + + upsert(p: UpsertClaimParams): SwarmClaimRow { + const submitted_at = p.now ?? Date.now(); + const status: OtsStatus = p.ots_status ?? "pending"; + this.db + .prepare( + `INSERT INTO swarm_claims + (node_id, run_id, master_seed, strategy, total_bots, + merkle_root, top_n_claim_json, claimed_score, + started_at, finished_at, submitted_at, + ots_status, pending_calendar_blobs, + upgraded_ots_hex, upgraded_calendar_url, upgraded_at, + last_upgrade_attempt_at) + VALUES (@node_id, @run_id, @master_seed, @strategy, @total_bots, + @merkle_root, @top_n_claim_json, @claimed_score, + @started_at, @finished_at, @submitted_at, + @ots_status, @pending_calendar_blobs, + NULL, NULL, NULL, NULL) + ON CONFLICT(node_id, run_id) DO UPDATE SET + master_seed = excluded.master_seed, + strategy = excluded.strategy, + total_bots = excluded.total_bots, + merkle_root = excluded.merkle_root, + top_n_claim_json = excluded.top_n_claim_json, + claimed_score = excluded.claimed_score, + started_at = excluded.started_at, + finished_at = excluded.finished_at, + submitted_at = excluded.submitted_at, + ots_status = excluded.ots_status, + pending_calendar_blobs = excluded.pending_calendar_blobs`, + ) + .run({ + node_id: p.node_id, + run_id: p.run_id, + master_seed: p.master_seed, + strategy: p.strategy, + total_bots: p.total_bots, + merkle_root: p.merkle_root, + top_n_claim_json: JSON.stringify(p.top_n_claim), + claimed_score: p.top_n_claim.claimed_score, + started_at: p.started_at, + finished_at: p.finished_at, + submitted_at, + ots_status: status, + pending_calendar_blobs: JSON.stringify(p.pending_calendar_blobs ?? []), + }); + return this.getByCompositeKey(p.node_id, p.run_id) as SwarmClaimRow; + } + + getByCompositeKey(node_id: string, run_id: string): SwarmClaimRow | null { + const row = this.db + .prepare(`SELECT * FROM swarm_claims WHERE node_id = ? AND run_id = ?`) + .get(node_id, run_id) as SwarmClaimRow | undefined; + return row ?? null; + } + + /** + * Best-effort lookup by merkle_root. The verify route uses this to + * locate a claim from a user-supplied root. Returns the most + * recently submitted matching row (collisions are theoretically + * possible but in practice each browser run produces a unique + * merkle_root because the master_seed + bot_count differs). + */ + getByMerkleRoot(merkle_root: string): SwarmClaimRow | null { + const row = this.db + .prepare( + `SELECT * FROM swarm_claims + WHERE merkle_root = ? + ORDER BY submitted_at DESC + LIMIT 1`, + ) + .get(merkle_root) as SwarmClaimRow | undefined; + return row ?? null; + } + + /** + * Cross-swarm leaderboard. Sorted by claimed_score desc, then by + * submitted_at asc as a tiebreaker so a first-submitter beats a + * later identical claim. + * + * `proof_url_builder` lets the caller plug in its absolute URL + * prefix so the rendered URLs work both behind the dev port and on + * play.tournamental.com. + */ + leaderboard( + limit: number, + proof_url_builder: (merkle_root: string) => string, + ): LeaderboardRow[] { + const rows = this.db + .prepare( + `SELECT * FROM swarm_claims + ORDER BY claimed_score DESC, submitted_at ASC + LIMIT ?`, + ) + .all(limit) as SwarmClaimRow[]; + return rows.map((r, i): LeaderboardRow => { + let claim: TopNClaim; + try { + claim = JSON.parse(r.top_n_claim_json) as TopNClaim; + } catch { + claim = { bot_index: 0, claimed_score: r.claimed_score, picks_count: 0 }; + } + const bitcoinConfirmed = r.ots_status === "confirmed"; + return { + rank: i + 1, + node_id_short: r.node_id.slice(0, 14), + bot_index: claim.bot_index, + claimed_score: r.claimed_score, + merkle_root: r.merkle_root, + ots_proof_url: proof_url_builder(r.merkle_root), + bitcoin_confirmed: bitcoinConfirmed, + submitted_at: r.submitted_at, + }; + }); + } + + /** + * Aggregate totals across every swarm-claim row. Drives the + * `/v1/swarm/totals` endpoint that the /bot-arena marketing page + * polls (60s cache server-side, so cheap to call). Returns: + * total_bots sum of `total_bots` across all rows + * total_swarms number of distinct (node_id, run_id) rows + * total_devices number of distinct node_ids + * + * The "still perfect" count is intentionally NOT aggregated here: + * it depends on per-bot regeneration against settled match results, + * which the client computes against its own IndexedDB (the + * regenerate-on-demand contract documented in + * docs/30-browser-swarm-architecture.md). The /bot-arena page only + * surfaces the device-local perfect count for the current viewer. + * Tim 2026-06-08. + */ + totals(): { + total_bots: number; + total_swarms: number; + total_devices: number; + } { + const row = this.db + .prepare( + `SELECT COALESCE(SUM(total_bots), 0) AS total_bots, + COUNT(*) AS total_swarms, + COUNT(DISTINCT node_id) AS total_devices + FROM swarm_claims`, + ) + .get() as { + total_bots: number; + total_swarms: number; + total_devices: number; + }; + return { + total_bots: Number(row.total_bots) || 0, + total_swarms: Number(row.total_swarms) || 0, + total_devices: Number(row.total_devices) || 0, + }; + } + + /** + * Roll-up of every claim still waiting on a Bitcoin attestation. + * The scheduler scans this list every poll cycle and tries to + * upgrade each one. Returns rows that haven't been polled in the + * last `staleness_ms` window so we don't hammer the calendars. + */ + pendingToUpgrade(args: { + staleness_ms: number; + limit?: number; + now?: number; + }): SwarmClaimRow[] { + const now = args.now ?? Date.now(); + const cutoff = now - args.staleness_ms; + const limit = args.limit ?? 100; + return this.db + .prepare( + `SELECT * FROM swarm_claims + WHERE ots_status = 'pending' + AND (last_upgrade_attempt_at IS NULL + OR last_upgrade_attempt_at < ?) + ORDER BY submitted_at ASC + LIMIT ?`, + ) + .all(cutoff, limit) as SwarmClaimRow[]; + } + + recordUpgradeAttempt(args: { + node_id: string; + run_id: string; + now?: number; + }): void { + const now = args.now ?? Date.now(); + this.db + .prepare( + `UPDATE swarm_claims + SET last_upgrade_attempt_at = ? + WHERE node_id = ? AND run_id = ?`, + ) + .run(now, args.node_id, args.run_id); + } + + recordUpgradeSuccess(args: { + node_id: string; + run_id: string; + calendar_url: string; + upgraded_ots_hex: string; + now?: number; + }): void { + const now = args.now ?? Date.now(); + this.db + .prepare( + `UPDATE swarm_claims + SET ots_status = 'confirmed', + upgraded_calendar_url = ?, + upgraded_ots_hex = ?, + upgraded_at = ?, + last_upgrade_attempt_at = ? + WHERE node_id = ? AND run_id = ?`, + ) + .run( + args.calendar_url, + args.upgraded_ots_hex, + now, + now, + args.node_id, + args.run_id, + ); + } + + /** Parsed accessor used by the proof route. */ + parsePending(row: SwarmClaimRow): PendingCalendarBlob[] { + try { + const parsed = JSON.parse(row.pending_calendar_blobs); + if (!Array.isArray(parsed)) return []; + return parsed.filter( + (x): x is PendingCalendarBlob => + x && + typeof x === "object" && + typeof (x as PendingCalendarBlob).calendar_url === "string" && + typeof (x as PendingCalendarBlob).pending_bytes_hex === "string", + ); + } catch { + return []; + } + } + + parseTopClaim(row: SwarmClaimRow): TopNClaim { + try { + const parsed = JSON.parse(row.top_n_claim_json) as TopNClaim; + return parsed; + } catch { + return { bot_index: 0, claimed_score: row.claimed_score, picks_count: 0 }; + } + } +} diff --git a/apps/game/src/store/swarm-summaries.ts b/apps/game/src/store/swarm-summaries.ts new file mode 100644 index 00000000..09ac4186 --- /dev/null +++ b/apps/game/src/store/swarm-summaries.ts @@ -0,0 +1,329 @@ +/** + * Swarm-summary DAO , operator-keyed aggregate snapshots published by + * each swarm operator (browser tab or Node operator) once per kickoff. + * + * Spec: A13 task brief. + * + * The operator_id is the sha256 hash of the operator's API key , the + * same hash stored in `api_key.key_hash` , so the profile aggregate + * naturally rolls up every summary posted under that key without + * inventing a second identity column. + * + * Idempotency: (operator_id, kickoff_at) is the natural primary key. + * Re-POSTing the same payload overwrites the prior row so a recovering + * client can re-publish after a transient network failure without + * duplicating leaderboard entries. + */ +import type { Database as DatabaseT } from "better-sqlite3"; + +export interface AliveAfterMatch { + /** 1-indexed match ordinal in the canonical fixture order. */ + n: number; + /** Number of bots in this swarm still on a perfect track at match n. */ + alive_count: number; +} + +export interface TopKEntry { + bot_id: string; + /** 0..104 , match-count this bot has nailed. */ + score: number; + /** Pre-tournament chalk-weighted heuristic score. */ + chalk_score: number; +} + +export interface SwarmSummaryRow { + operator_id: string; + kickoff_at: number; + total_bots: number; + alive_by_match_json: string; + best_bot_score: number; + top_k_json: string; + merkle_root: string; + generated_at: number; +} + +export interface ParsedSwarmSummary { + operator_id: string; + kickoff_at: number; + total_bots: number; + bots_alive_after_match_n: AliveAfterMatch[]; + best_bot_score: number; + top_k: TopKEntry[]; + merkle_root: string; + generated_at: number; +} + +export interface UpsertSummaryParams { + operator_id: string; + kickoff_at: number; + total_bots: number; + bots_alive_after_match_n: readonly AliveAfterMatch[]; + best_bot_score: number; + top_k: readonly TopKEntry[]; + merkle_root: string; + generated_at: number; +} + +const MAX_TOP_K = 1_000; +const MAX_ALIVE_ROWS = 200; // generous ceiling over the 104-match cap + +export class SwarmSummaryStore { + constructor(private readonly db: DatabaseT) {} + + /** + * Insert (or overwrite) the summary keyed by (operator_id, + * kickoff_at). The store enforces the top_k and + * bots_alive_after_match_n size caps so a misbehaving client + * cannot blow up the row size. + */ + upsert(p: UpsertSummaryParams): SwarmSummaryRow { + const top_k = p.top_k.slice(0, MAX_TOP_K); + const alive = p.bots_alive_after_match_n.slice(0, MAX_ALIVE_ROWS); + this.db + .prepare( + `INSERT INTO swarm_summary + (operator_id, kickoff_at, total_bots, + alive_by_match_json, best_bot_score, top_k_json, + merkle_root, generated_at) + VALUES (@operator_id, @kickoff_at, @total_bots, + @alive_by_match_json, @best_bot_score, @top_k_json, + @merkle_root, @generated_at) + ON CONFLICT(operator_id, kickoff_at) DO UPDATE SET + total_bots = excluded.total_bots, + alive_by_match_json = excluded.alive_by_match_json, + best_bot_score = excluded.best_bot_score, + top_k_json = excluded.top_k_json, + merkle_root = excluded.merkle_root, + generated_at = excluded.generated_at`, + ) + .run({ + operator_id: p.operator_id, + kickoff_at: p.kickoff_at, + total_bots: p.total_bots, + alive_by_match_json: JSON.stringify(alive), + best_bot_score: p.best_bot_score, + top_k_json: JSON.stringify(top_k), + merkle_root: p.merkle_root, + generated_at: p.generated_at, + }); + return this.getByCompositeKey(p.operator_id, p.kickoff_at)!; + } + + getByCompositeKey( + operator_id: string, + kickoff_at: number, + ): SwarmSummaryRow | null { + const row = this.db + .prepare( + `SELECT * FROM swarm_summary + WHERE operator_id = ? AND kickoff_at = ?`, + ) + .get(operator_id, kickoff_at) as SwarmSummaryRow | undefined; + return row ?? null; + } + + /** Latest summary for this operator. Used by GET /v1/swarms/. */ + getLatestForOperator(operator_id: string): SwarmSummaryRow | null { + const row = this.db + .prepare( + `SELECT * FROM swarm_summary + WHERE operator_id = ? + ORDER BY kickoff_at DESC, generated_at DESC + LIMIT 1`, + ) + .get(operator_id) as SwarmSummaryRow | undefined; + return row ?? null; + } + + /** Time-series of best scores per kickoff for the profile sparkline. */ + listForOperator(operator_id: string, limit = 100): SwarmSummaryRow[] { + return this.db + .prepare( + `SELECT * FROM swarm_summary + WHERE operator_id = ? + ORDER BY kickoff_at ASC + LIMIT ?`, + ) + .all(operator_id, limit) as SwarmSummaryRow[]; + } + + /** + * Top-N operators across the platform, ranked by best_bot_score. + * One row per operator , we collapse to the latest summary per + * operator inside the query so the global leaderboard never + * double-counts. Used by GET /v1/swarms. + */ + topOperators(limit: number): SwarmSummaryRow[] { + return this.db + .prepare( + `SELECT s.* + FROM swarm_summary s + INNER JOIN ( + SELECT operator_id, MAX(kickoff_at) AS latest + FROM swarm_summary + GROUP BY operator_id + ) latest + ON latest.operator_id = s.operator_id + AND latest.latest = s.kickoff_at + ORDER BY s.best_bot_score DESC, s.generated_at DESC + LIMIT ?`, + ) + .all(limit) as SwarmSummaryRow[]; + } + + /** + * Aggregate totals across every operator's latest summary. Surfaced + * through the /v1/swarm/totals "bots in the arena" headline so + * federation-mode operators (browser tabs at /run, bot-node Docker + * containers, anything that posts to /v1/swarms//summary) get + * folded in alongside the older swarm_claims tally. + */ + totals(): { total_bots: number; total_operators: number } { + const row = this.db + .prepare( + `SELECT COUNT(*) AS total_operators, COALESCE(SUM(latest_total), 0) AS total_bots + FROM ( + SELECT operator_id, total_bots AS latest_total + FROM swarm_summary s + WHERE kickoff_at = ( + SELECT MAX(kickoff_at) FROM swarm_summary s2 + WHERE s2.operator_id = s.operator_id + ) + GROUP BY operator_id + )`, + ) + .get() as { total_bots: number; total_operators: number }; + return { + total_bots: Number(row.total_bots ?? 0), + total_operators: Number(row.total_operators ?? 0), + }; + } + + /** + * Latest summary per operator. Used by the perfect-track watcher to + * find any operator still carrying alive bots past match 80. + */ + latestPerOperator(): SwarmSummaryRow[] { + return this.db + .prepare( + `SELECT s.* + FROM swarm_summary s + INNER JOIN ( + SELECT operator_id, MAX(kickoff_at) AS latest + FROM swarm_summary + GROUP BY operator_id + ) latest + ON latest.operator_id = s.operator_id + AND latest.latest = s.kickoff_at`, + ) + .all() as SwarmSummaryRow[]; + } + + parseAlive(row: SwarmSummaryRow): AliveAfterMatch[] { + try { + const parsed = JSON.parse(row.alive_by_match_json); + if (!Array.isArray(parsed)) return []; + return parsed.filter( + (x): x is AliveAfterMatch => + x && + typeof x === "object" && + typeof (x as AliveAfterMatch).n === "number" && + typeof (x as AliveAfterMatch).alive_count === "number", + ); + } catch { + return []; + } + } + + parseTopK(row: SwarmSummaryRow): TopKEntry[] { + try { + const parsed = JSON.parse(row.top_k_json); + if (!Array.isArray(parsed)) return []; + return parsed.filter( + (x): x is TopKEntry => + x && + typeof x === "object" && + typeof (x as TopKEntry).bot_id === "string" && + typeof (x as TopKEntry).score === "number", + ); + } catch { + return []; + } + } + + /** Convenience: parse a row into the public response shape. */ + parse(row: SwarmSummaryRow): ParsedSwarmSummary { + return { + operator_id: row.operator_id, + kickoff_at: row.kickoff_at, + total_bots: row.total_bots, + bots_alive_after_match_n: this.parseAlive(row), + best_bot_score: row.best_bot_score, + top_k: this.parseTopK(row), + merkle_root: row.merkle_root, + generated_at: row.generated_at, + }; + } +} + +export interface PerfectTrackAlertRow { + operator_id: string; + match_number: number; + alive_count: number; + detected_at: number; +} + +export class PerfectTrackAlertStore { + constructor(private readonly db: DatabaseT) {} + + /** Idempotent record of an alert for (operator_id, match_number). */ + recordAlert(p: { + operator_id: string; + match_number: number; + alive_count: number; + now?: number; + }): void { + const detected_at = p.now ?? Date.now(); + this.db + .prepare( + `INSERT INTO perfect_track_alert + (operator_id, match_number, alive_count, detected_at) + VALUES (?, ?, ?, ?) + ON CONFLICT(operator_id, match_number) DO UPDATE SET + alive_count = excluded.alive_count, + detected_at = excluded.detected_at`, + ) + .run(p.operator_id, p.match_number, p.alive_count, detected_at); + } + + /** Roll-up used by the /leaderboard badge: total alive bots past the + * highest match number any operator has reached. */ + latestSummary(): { highest_match: number; total_alive: number; operator_count: number } | null { + const row = this.db + .prepare( + `SELECT match_number, SUM(alive_count) AS total_alive, + COUNT(DISTINCT operator_id) AS operator_count + FROM perfect_track_alert + WHERE match_number = (SELECT MAX(match_number) FROM perfect_track_alert) + GROUP BY match_number`, + ) + .get() as + | { match_number: number; total_alive: number; operator_count: number } + | undefined; + if (!row) return null; + return { + highest_match: row.match_number, + total_alive: row.total_alive, + operator_count: row.operator_count, + }; + } + + listAll(): PerfectTrackAlertRow[] { + return this.db + .prepare( + `SELECT * FROM perfect_track_alert + ORDER BY match_number DESC, alive_count DESC`, + ) + .all() as PerfectTrackAlertRow[]; + } +} diff --git a/apps/game/tests/lib-merkle.test.ts b/apps/game/tests/lib-merkle.test.ts new file mode 100644 index 00000000..5687af7b --- /dev/null +++ b/apps/game/tests/lib-merkle.test.ts @@ -0,0 +1,138 @@ +/** + * Sorted-pair sha256 merkle tree for the OTS kickoff commitment. + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §15.6 + */ +import { describe, it, expect } from "vitest"; + +import { + buildMerkle, + leafHash, + verifyProof, + type PickLeaf, +} from "../src/lib/merkle.js"; + +describe("merkle , leaf hash", () => { + it("is deterministic", () => { + const a = leafHash("bot_a", "1", "home_win", 1717804800000); + const b = leafHash("bot_a", "1", "home_win", 1717804800000); + expect(a).toBe(b); + expect(a).toMatch(/^[0-9a-f]{64}$/); + }); + + it("changes when any field changes", () => { + const base = leafHash("bot_a", "1", "home_win", 1); + expect(leafHash("bot_b", "1", "home_win", 1)).not.toBe(base); + expect(leafHash("bot_a", "2", "home_win", 1)).not.toBe(base); + expect(leafHash("bot_a", "1", "draw", 1)).not.toBe(base); + expect(leafHash("bot_a", "1", "home_win", 2)).not.toBe(base); + }); +}); + +describe("merkle , build + verify", () => { + it("empty picks produce a 64-hex root and zero proofs", () => { + const tree = buildMerkle([]); + expect(tree.root).toMatch(/^[0-9a-f]{64}$/); + expect(tree.proofs).toHaveLength(0); + expect(tree.leaves).toHaveLength(0); + }); + + it("single-pick tree has root == leaf", () => { + const picks: PickLeaf[] = [ + { bot_id: "bot_a", match_id: "1", outcome: "home_win", t: 1 }, + ]; + const tree = buildMerkle(picks); + expect(tree.root).toBe(tree.leaves[0]); + expect(tree.proofs[0]).toEqual([]); + expect(verifyProof(tree.leaves[0]!, tree.proofs[0]!, tree.root)).toBe( + true, + ); + }); + + it("produces a valid root + per-leaf inclusion proof", () => { + const picks: PickLeaf[] = [ + { bot_id: "bot_a", match_id: "1", outcome: "home_win", t: 1 }, + { bot_id: "bot_b", match_id: "1", outcome: "draw", t: 2 }, + { bot_id: "bot_c", match_id: "1", outcome: "away_win", t: 3 }, + { bot_id: "bot_d", match_id: "1", outcome: "home_win", t: 4 }, + ]; + const tree = buildMerkle(picks); + expect(tree.root).toMatch(/^[0-9a-f]{64}$/); + for (let i = 0; i < picks.length; i++) { + const leaf = leafHash( + picks[i]!.bot_id, + picks[i]!.match_id, + picks[i]!.outcome, + picks[i]!.t, + ); + expect(verifyProof(leaf, tree.proofs[i]!, tree.root)).toBe(true); + } + }); + + it("handles odd leaf counts by duplicating the trailing node", () => { + const picks: PickLeaf[] = [ + { bot_id: "bot_a", match_id: "1", outcome: "home_win", t: 1 }, + { bot_id: "bot_b", match_id: "1", outcome: "draw", t: 2 }, + { bot_id: "bot_c", match_id: "1", outcome: "away_win", t: 3 }, + ]; + const tree = buildMerkle(picks); + for (let i = 0; i < picks.length; i++) { + const leaf = leafHash( + picks[i]!.bot_id, + picks[i]!.match_id, + picks[i]!.outcome, + picks[i]!.t, + ); + expect(verifyProof(leaf, tree.proofs[i]!, tree.root)).toBe(true); + } + }); + + it("rejects a proof against the wrong root", () => { + const picks: PickLeaf[] = [ + { bot_id: "bot_a", match_id: "1", outcome: "home_win", t: 1 }, + { bot_id: "bot_b", match_id: "1", outcome: "draw", t: 2 }, + ]; + const tree = buildMerkle(picks); + const leaf = leafHash("bot_a", "1", "home_win", 1); + expect(verifyProof(leaf, tree.proofs[0]!, "0".repeat(64))).toBe(false); + }); + + it("rejects a tampered leaf", () => { + const picks: PickLeaf[] = [ + { bot_id: "bot_a", match_id: "1", outcome: "home_win", t: 1 }, + { bot_id: "bot_b", match_id: "1", outcome: "draw", t: 2 }, + ]; + const tree = buildMerkle(picks); + const wrong = leafHash("bot_a", "1", "away_win", 1); + expect(verifyProof(wrong, tree.proofs[0]!, tree.root)).toBe(false); + }); + + it("two trees with the same picks produce the same root", () => { + const picks: PickLeaf[] = [ + { bot_id: "bot_a", match_id: "1", outcome: "home_win", t: 1 }, + { bot_id: "bot_b", match_id: "1", outcome: "draw", t: 2 }, + { bot_id: "bot_c", match_id: "1", outcome: "away_win", t: 3 }, + ]; + expect(buildMerkle(picks).root).toBe(buildMerkle(picks).root); + }); + + it("scales to 1000 leaves with consistent proofs", () => { + const picks: PickLeaf[] = Array.from({ length: 1000 }, (_, i) => ({ + bot_id: `bot_${i}`, + match_id: "1", + outcome: (["home_win", "draw", "away_win"] as const)[i % 3]!, + t: i, + })); + const tree = buildMerkle(picks); + // Spot-check 10 leaves at random indices. + for (const idx of [0, 1, 17, 256, 511, 512, 768, 998, 999]) { + const leaf = leafHash( + picks[idx]!.bot_id, + picks[idx]!.match_id, + picks[idx]!.outcome, + picks[idx]!.t, + ); + expect(verifyProof(leaf, tree.proofs[idx]!, tree.root)).toBe(true); + } + }); +}); diff --git a/apps/game/tests/lib-ots-calendar.test.ts b/apps/game/tests/lib-ots-calendar.test.ts new file mode 100644 index 00000000..54683cfa --- /dev/null +++ b/apps/game/tests/lib-ots-calendar.test.ts @@ -0,0 +1,225 @@ +/** + * OpenTimestamps calendar HTTP client. + * + * The unit tests stub the calendar with an in-memory fetch so we can + * verify the wire protocol without touching the public OTS pool. + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §15.6 + */ +import { describe, expect, it } from "vitest"; +import { createHash } from "node:crypto"; + +import { + bytesToHex, + buildOtsFile, + buildOtsPostHook, + containsBitcoinAttestation, + fetchUpgrade, + hexToBytes, + serialiseOtsFile, + submitDigest, + submitToCalendars, +} from "../src/lib/ots-calendar.js"; + +function sha256(input: string): Uint8Array { + return new Uint8Array(createHash("sha256").update(input).digest()); +} + +function mockFetch( + handler: (url: string, init?: RequestInit) => Promise | Response, +): typeof fetch { + return (async (input: RequestInfo | URL, init?: RequestInit) => { + const url = typeof input === "string" ? input : (input as URL).toString(); + return await handler(url, init); + }) as typeof fetch; +} + +describe("ots-calendar — hex helpers", () => { + it("round-trips hex <-> bytes", () => { + const bytes = sha256("hello"); + const hex = bytesToHex(bytes); + expect(hex).toMatch(/^[0-9a-f]{64}$/); + expect(bytesToHex(hexToBytes(hex))).toBe(hex); + }); + + it("rejects odd-length hex", () => { + expect(() => hexToBytes("abc")).toThrow(/odd length/); + }); +}); + +describe("ots-calendar — submitDigest", () => { + it("POSTs the digest and returns calendar bytes", async () => { + const digest = sha256("root"); + let observed: { url?: string; body?: ArrayBuffer } = {}; + const fetchImpl = mockFetch(async (url, init) => { + observed.url = url; + observed.body = await new Response(init?.body).arrayBuffer(); + return new Response(new Uint8Array([0xf1, 0x04, 0x01]).buffer, { + status: 200, + }); + }); + const result = await submitDigest("https://cal.example.com", digest, { + fetchImpl, + }); + expect(observed.url).toBe("https://cal.example.com/digest"); + expect(new Uint8Array(observed.body!)).toEqual(digest); + expect(result.pending_bytes.byteLength).toBe(3); + expect(result.calendar_url).toBe("https://cal.example.com"); + }); + + it("rejects non-32-byte digests", async () => { + await expect( + submitDigest("https://cal.example.com", new Uint8Array(16)), + ).rejects.toThrow(/32 bytes/); + }); + + it("throws on non-2xx", async () => { + const fetchImpl = mockFetch(() => new Response("nope", { status: 503 })); + await expect( + submitDigest("https://cal.example.com", sha256("x"), { fetchImpl }), + ).rejects.toThrow(/503/); + }); +}); + +describe("ots-calendar — submitToCalendars (multi)", () => { + it("returns successes and errors side by side", async () => { + const fetchImpl = mockFetch((url) => { + if (url.startsWith("https://ok.cal")) { + return new Response(new Uint8Array([1, 2, 3]).buffer, { status: 200 }); + } + return new Response("down", { status: 500 }); + }); + const out = await submitToCalendars(sha256("x"), { + calendars: ["https://ok.cal/", "https://fail.cal/"], + fetchImpl, + }); + expect(out.successes.map((s) => s.calendar_url)).toEqual([ + "https://ok.cal/", + ]); + expect(out.errors.map((e) => e.calendar_url)).toEqual(["https://fail.cal/"]); + }); +}); + +describe("ots-calendar — fetchUpgrade", () => { + it("returns null on 404", async () => { + const fetchImpl = mockFetch(() => new Response("", { status: 404 })); + const out = await fetchUpgrade({ + calendar_url: "https://cal.example.com", + digest_hex: "a".repeat(64), + fetchImpl, + }); + expect(out).toBeNull(); + }); + + it("flags the Bitcoin attestation when present", async () => { + const fetchImpl = mockFetch( + () => + new Response( + // arbitrary leading byte then the BTC attestation magic + new Uint8Array([ + 0xff, 0x05, 0x88, 0x96, 0x0d, 0x73, 0xd7, 0x19, 0x01, 0x42, + ]).buffer, + { status: 200 }, + ), + ); + const out = await fetchUpgrade({ + calendar_url: "https://cal.example.com", + digest_hex: "a".repeat(64), + fetchImpl, + }); + expect(out).not.toBeNull(); + expect(out!.bitcoin_confirmed).toBe(true); + }); + + it("does not flag confirmation when only calendar bytes are present", async () => { + const fetchImpl = mockFetch( + () => new Response(new Uint8Array([0xf1, 0x00, 0xab]).buffer, { status: 200 }), + ); + const out = await fetchUpgrade({ + calendar_url: "https://cal.example.com", + digest_hex: "a".repeat(64), + fetchImpl, + }); + expect(out!.bitcoin_confirmed).toBe(false); + }); +}); + +describe("ots-calendar — file serialisation", () => { + it("contains the magic header + version + sha256 tag + digest", () => { + const digest = sha256("root"); + const ts = new Uint8Array([0x00, 0x01]); + const bytes = serialiseOtsFile({ digest, timestamp_bytes: ts }); + // First 31 bytes are the OTS magic. + expect(bytes[0]).toBe(0x00); + // Byte 31 is version. + expect(bytes[31]).toBe(0x01); + // Byte 32 is the SHA-256 op tag. + expect(bytes[32]).toBe(0x08); + // Bytes 33..65 are the digest. + expect(Array.from(bytes.slice(33, 65))).toEqual(Array.from(digest)); + // Final two bytes are the timestamp payload. + expect(Array.from(bytes.slice(65))).toEqual([0x00, 0x01]); + }); + + it("buildOtsFile exposes digest_hex + calendar_url", () => { + const digest = sha256("root"); + const out = buildOtsFile({ + digest, + calendar_url: "https://x.cal", + timestamp_bytes: new Uint8Array([1, 2, 3]), + }); + expect(out.digest_hex).toBe(bytesToHex(digest)); + expect(out.calendar_url).toBe("https://x.cal"); + }); +}); + +describe("ots-calendar — containsBitcoinAttestation", () => { + it("finds the magic anywhere in the payload", () => { + const buf = new Uint8Array([ + 0xaa, 0xbb, 0x05, 0x88, 0x96, 0x0d, 0x73, 0xd7, 0x19, 0x01, + ]); + expect(containsBitcoinAttestation(buf)).toBe(true); + }); + it("rejects payloads without the magic", () => { + expect(containsBitcoinAttestation(new Uint8Array([1, 2, 3]))).toBe(false); + }); +}); + +describe("ots-calendar — buildOtsPostHook", () => { + it("calls onPending with the calendar blobs that succeeded", async () => { + const fetchImpl = mockFetch((url) => { + if (url.includes("ok")) { + return new Response(new Uint8Array([0x99]).buffer, { status: 200 }); + } + return new Response("down", { status: 500 }); + }); + const collected: unknown[] = []; + const hook = buildOtsPostHook({ + calendars: ["https://ok.cal", "https://bad.cal"], + fetchImpl, + onPending: (blobs) => { + collected.push(blobs); + }, + }); + await hook("a".repeat(64)); + expect(collected).toHaveLength(1); + const blobs = collected[0] as Array<{ calendar_url: string }>; + expect(blobs.map((b) => b.calendar_url)).toEqual(["https://ok.cal"]); + }); + + it("is a no-op when given a non-hex root", async () => { + const fetchImpl = mockFetch(() => { + throw new Error("should not be called"); + }); + let pending: unknown = null; + const hook = buildOtsPostHook({ + calendars: ["https://x.cal"], + fetchImpl, + onPending: (b) => { + pending = b; + }, + }); + await expect(hook("not-hex")).resolves.toBeUndefined(); + expect(pending).toEqual([]); + }); +}); diff --git a/apps/game/tests/routes-bots-keys-issue.test.ts b/apps/game/tests/routes-bots-keys-issue.test.ts new file mode 100644 index 00000000..7e66453c --- /dev/null +++ b/apps/game/tests/routes-bots-keys-issue.test.ts @@ -0,0 +1,247 @@ +/** + * POST /v1/bots/keys/issue , service-to-service issuance endpoint. + * + * The Next.js web proxy uses this to mint Bot Arena keys for + * non-Supabase auth users (SMS-OTP, Telegram) , the existing + * /v1/me/api-keys flow requires a Supabase JWT and would no-op for + * those users. + */ +import { afterAll, beforeAll, describe, expect, it } from "vitest"; + +import { makeServer } from "./helpers.js"; + +const SHARED_SECRET = "test-shared-secret-90909"; + +describe("POST /v1/bots/keys/issue", () => { + const previousEnv = process.env.GAME_BOT_KEYS_SHARED_SECRET; + const built = makeServer({ cacheTtlMs: 50 }); + + beforeAll(() => { + process.env.GAME_BOT_KEYS_SHARED_SECRET = SHARED_SECRET; + }); + + afterAll(async () => { + const { app } = await built; + await app.close(); + if (previousEnv === undefined) { + delete process.env.GAME_BOT_KEYS_SHARED_SECRET; + } else { + process.env.GAME_BOT_KEYS_SHARED_SECRET = previousEnv; + } + }); + + it("issues a key when the shared secret matches", async () => { + const { app } = await built; + const res = await app.inject({ + method: "POST", + url: "/v1/bots/keys/issue", + headers: { + "x-bot-keys-shared-secret": SHARED_SECRET, + "content-type": "application/json", + }, + payload: { owner_email: "tim@example.com", label: "primary" }, + }); + expect(res.statusCode).toBe(200); + const body = res.json(); + expect(typeof body.api_key).toBe("string"); + expect(body.api_key).toMatch(/^tnm_/); + expect(typeof body.key_hash).toBe("string"); + expect(body.owner_email).toBe("tim@example.com"); + expect(body.label).toBe("primary"); + expect(body.quota_bots).toBe(1000); + expect(body.quota_picks_per_hour).toBe(100_000); + expect(typeof body.created_at).toBe("number"); + }); + + it("lifts quotas for academic emails (.edu)", async () => { + const { app } = await built; + const res = await app.inject({ + method: "POST", + url: "/v1/bots/keys/issue", + headers: { + "x-bot-keys-shared-secret": SHARED_SECRET, + "content-type": "application/json", + }, + payload: { owner_email: "researcher@mit.edu" }, + }); + expect(res.statusCode).toBe(200); + const body = res.json(); + expect(body.quota_bots).toBe(10_000); + expect(body.quota_picks_per_hour).toBe(1_000_000); + }); + + it("lifts quotas for .ac.uk / .ac.nz / .edu.au / .ac.za", async () => { + const { app } = await built; + const domains = [ + "ac.uk", + "ac.nz", + "edu.au", + "ac.za", + ]; + for (const d of domains) { + const res = await app.inject({ + method: "POST", + url: "/v1/bots/keys/issue", + headers: { + "x-bot-keys-shared-secret": SHARED_SECRET, + "content-type": "application/json", + }, + payload: { owner_email: `dev@uni.${d}` }, + }); + expect(res.statusCode).toBe(200); + const body = res.json(); + expect(body.quota_bots).toBe(10_000); + } + }); + + it("rejects with 401 when the shared secret is missing", async () => { + const { app } = await built; + const res = await app.inject({ + method: "POST", + url: "/v1/bots/keys/issue", + headers: { "content-type": "application/json" }, + payload: { owner_email: "tim@example.com", label: "x" }, + }); + expect(res.statusCode).toBe(401); + expect(res.json().error).toBe("missing_secret"); + }); + + it("rejects with 401 when the shared secret does not match", async () => { + const { app } = await built; + const res = await app.inject({ + method: "POST", + url: "/v1/bots/keys/issue", + headers: { + "x-bot-keys-shared-secret": "wrong-value-90909", + "content-type": "application/json", + }, + payload: { owner_email: "tim@example.com", label: "x" }, + }); + expect(res.statusCode).toBe(401); + expect(res.json().error).toBe("invalid_secret"); + }); + + it("rejects with 400 when owner_email is missing", async () => { + const { app } = await built; + const res = await app.inject({ + method: "POST", + url: "/v1/bots/keys/issue", + headers: { + "x-bot-keys-shared-secret": SHARED_SECRET, + "content-type": "application/json", + }, + payload: { label: "x" }, + }); + expect(res.statusCode).toBe(400); + expect(res.json().error).toBe("invalid_email"); + }); + + it("rejects with 400 when owner_email is malformed", async () => { + const { app } = await built; + const res = await app.inject({ + method: "POST", + url: "/v1/bots/keys/issue", + headers: { + "x-bot-keys-shared-secret": SHARED_SECRET, + "content-type": "application/json", + }, + payload: { owner_email: "not-an-email", label: "x" }, + }); + expect(res.statusCode).toBe(400); + expect(res.json().error).toBe("invalid_email"); + }); + + it("rejects with 400 when label is too long", async () => { + const { app } = await built; + const res = await app.inject({ + method: "POST", + url: "/v1/bots/keys/issue", + headers: { + "x-bot-keys-shared-secret": SHARED_SECRET, + "content-type": "application/json", + }, + payload: { + owner_email: "tim@example.com", + label: "x".repeat(200), + }, + }); + expect(res.statusCode).toBe(400); + expect(res.json().error).toBe("label_too_long"); + }); + + it("the freshly minted key authenticates against /v1/picks/bulk", async () => { + const { app, store } = await built; + const mintRes = await app.inject({ + method: "POST", + url: "/v1/bots/keys/issue", + headers: { + "x-bot-keys-shared-secret": SHARED_SECRET, + "content-type": "application/json", + }, + payload: { owner_email: "smoke@example.com", label: "smoke" }, + }); + expect(mintRes.statusCode).toBe(200); + const apiKey = mintRes.json().api_key as string; + expect(apiKey).toMatch(/^tnm_/); + // Claim a bot id under this key so the /v1/picks/bulk ownership + // check passes. + store.db + .prepare(`INSERT INTO users (id, created_at, is_bot) VALUES (?, 1, 1)`) + .run("smoke-bot-1"); + const keyRow = store.apiKeys.lookupByPlain(apiKey); + expect(keyRow).not.toBeNull(); + store.botOwners.claim({ + bot_id: "smoke-bot-1", + api_key_hash: keyRow!.key_hash, + owner_email: "smoke@example.com", + }); + const bulk = await app.inject({ + method: "POST", + url: "/v1/picks/bulk", + headers: { authorization: `Bearer ${apiKey}` }, + payload: { + tournament_id: "fifa-wc-2026", + submissions: [ + { + bot_id: "smoke-bot-1", + picks: [{ match_id: "1", outcome: "home_win" }], + }, + ], + }, + }); + expect(bulk.statusCode).toBe(200); + expect(bulk.json().accepted).toBe(1); + }); +}); + +describe("POST /v1/bots/keys/issue (secret not configured)", () => { + const previousEnv = process.env.GAME_BOT_KEYS_SHARED_SECRET; + const built = makeServer({ cacheTtlMs: 50 }); + + beforeAll(() => { + delete process.env.GAME_BOT_KEYS_SHARED_SECRET; + }); + + afterAll(async () => { + const { app } = await built; + await app.close(); + if (previousEnv !== undefined) { + process.env.GAME_BOT_KEYS_SHARED_SECRET = previousEnv; + } + }); + + it("refuses with 503 when the secret env var is unset", async () => { + const { app } = await built; + const res = await app.inject({ + method: "POST", + url: "/v1/bots/keys/issue", + headers: { + "x-bot-keys-shared-secret": "anything", + "content-type": "application/json", + }, + payload: { owner_email: "tim@example.com", label: "x" }, + }); + expect(res.statusCode).toBe(503); + expect(res.json().error).toBe("issuance_disabled"); + }); +}); diff --git a/apps/game/tests/routes-leaderboard-scope.test.ts b/apps/game/tests/routes-leaderboard-scope.test.ts new file mode 100644 index 00000000..2efd847f --- /dev/null +++ b/apps/game/tests/routes-leaderboard-scope.test.ts @@ -0,0 +1,109 @@ +/** + * GET /v1/leaderboard/:tournament_id?scope=humans|bots|all + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §5 + */ +import { afterAll, beforeAll, describe, expect, it } from "vitest"; + +import { makeServer } from "./helpers.js"; +import { _resetBotArenaCache } from "../src/routes/leaderboard.js"; + +describe("GET /v1/leaderboard?scope=...", () => { + const built = makeServer({ cacheTtlMs: 50 }); + + beforeAll(async () => { + _resetBotArenaCache(); + const { store } = await built; + const now = Date.now(); + for (const [id, is_bot, score] of [ + ["u_h1", 0, 50], + ["u_h2", 0, 40], + ["u_h3", 0, 30], + ["bot_b1", 1, 70], + ["bot_b2", 1, 60], + ] as Array<[string, 0 | 1, number]>) { + store.db + .prepare( + `INSERT INTO users (id, created_at, is_bot) VALUES (?, ?, ?)`, + ) + .run(id, now, is_bot); + store.db + .prepare( + `INSERT INTO brackets + (id, user_id, tournament_id, payload_json, locked_at, + score_total, share_guid) + VALUES (?, ?, 'fifa-wc-2026', '{}', ?, ?, ?)`, + ) + .run(`${id}_b`, id, now, score, id.slice(0, 8)); + } + }); + + afterAll(async () => { + const { app } = await built; + await app.close(); + }); + + it("scope=humans returns only is_bot=0 users", async () => { + const { app } = await built; + _resetBotArenaCache(); + const res = await app.inject({ + method: "GET", + url: "/v1/leaderboard/fifa-wc-2026?scope=humans", + }); + expect(res.statusCode).toBe(200); + const body = res.json(); + expect(body.scope).toBe("humans"); + expect(body.rows.length).toBe(3); + }); + + it("scope=bots returns only is_bot=1 users", async () => { + const { app } = await built; + _resetBotArenaCache(); + const res = await app.inject({ + method: "GET", + url: "/v1/leaderboard/fifa-wc-2026?scope=bots", + }); + expect(res.statusCode).toBe(200); + const body = res.json(); + expect(body.scope).toBe("bots"); + expect(body.rows.length).toBe(2); + }); + + it("scope=all returns everyone", async () => { + const { app } = await built; + _resetBotArenaCache(); + const res = await app.inject({ + method: "GET", + url: "/v1/leaderboard/fifa-wc-2026?scope=all", + }); + expect(res.statusCode).toBe(200); + const body = res.json(); + expect(body.scope).toBe("all"); + expect(body.rows.length).toBe(5); + }); + + it("no scope preserves the legacy unfiltered response shape", async () => { + const { app } = await built; + const res = await app.inject({ + method: "GET", + url: "/v1/leaderboard/fifa-wc-2026", + }); + expect(res.statusCode).toBe(200); + const body = res.json(); + expect(body.scope).toBeUndefined(); + expect(body.rows.length).toBe(5); + }); + + it("source=federated returns the federated aggregate (empty by default)", async () => { + const { app } = await built; + _resetBotArenaCache(); + const res = await app.inject({ + method: "GET", + url: "/v1/leaderboard/fifa-wc-2026?source=federated", + }); + expect(res.statusCode).toBe(200); + const body = res.json(); + expect(body.source).toBe("federated"); + expect(Array.isArray(body.rows)).toBe(true); + }); +}); diff --git a/apps/game/tests/routes-nodes.test.ts b/apps/game/tests/routes-nodes.test.ts new file mode 100644 index 00000000..f7f21f60 --- /dev/null +++ b/apps/game/tests/routes-nodes.test.ts @@ -0,0 +1,257 @@ +/** + * Federation endpoints , Phase 2 forward-compat surface. + * + * POST /v1/nodes/register , issue node credentials + * POST /v1/nodes/commit , pre-kickoff merkle commitment + * POST /v1/nodes/leaderboard, post-match aggregate report + * GET /v1/leaderboard?source=federated , merged top-K view + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §15.2 + */ +import { afterAll, beforeAll, describe, expect, it } from "vitest"; + +import { makeServer } from "./helpers.js"; + +describe("POST /v1/nodes/register", () => { + const built = makeServer({ cacheTtlMs: 50 }); + let ownerKey = ""; + + beforeAll(async () => { + const { store } = await built; + const issued = store.apiKeys.issue({ + owner_email: "ops@example.com", + label: "node-operator", + }); + ownerKey = issued.api_key; + }); + + afterAll(async () => { + const { app } = await built; + await app.close(); + }); + + it("rejects requests without an API key", async () => { + const { app } = await built; + const res = await app.inject({ + method: "POST", + url: "/v1/nodes/register", + payload: { + owner_email: "ops@example.com", + public_url: "https://alpha.example.com", + }, + }); + expect(res.statusCode).toBe(401); + }); + + it("issues node credentials and returns the node_id + node_key", async () => { + const { app } = await built; + const res = await app.inject({ + method: "POST", + url: "/v1/nodes/register", + headers: { authorization: `Bearer ${ownerKey}` }, + payload: { + owner_email: "ops@example.com", + public_url: "https://alpha.example.com", + label: "Alpha swarm", + }, + }); + expect(res.statusCode).toBe(201); + const body = res.json(); + expect(body.node_id).toMatch(/^node_/); + expect(body.node_key).toMatch(/^tnm_/); + expect(body.public_url).toBe("https://alpha.example.com"); + }); + + it("rejects malformed URLs with 400", async () => { + const { app } = await built; + const res = await app.inject({ + method: "POST", + url: "/v1/nodes/register", + headers: { authorization: `Bearer ${ownerKey}` }, + payload: { + owner_email: "ops@example.com", + public_url: "not-a-url", + }, + }); + expect(res.statusCode).toBe(400); + }); +}); + +describe("POST /v1/nodes/commit + /leaderboard", () => { + const built = makeServer({ cacheTtlMs: 50 }); + let nodeId = ""; + let nodeKey = ""; + + beforeAll(async () => { + const { store, app } = await built; + const ownerIssued = store.apiKeys.issue({ + owner_email: "ops@example.com", + label: "node-operator", + }); + const res = await app.inject({ + method: "POST", + url: "/v1/nodes/register", + headers: { authorization: `Bearer ${ownerIssued.api_key}` }, + payload: { + owner_email: "ops@example.com", + public_url: "https://alpha.example.com", + label: "Alpha swarm", + }, + }); + nodeId = res.json().node_id; + nodeKey = res.json().node_key; + }); + + afterAll(async () => { + const { app } = await built; + await app.close(); + }); + + it("commit rejects without a node key", async () => { + const { app } = await built; + const res = await app.inject({ + method: "POST", + url: "/v1/nodes/commit", + payload: { + node_id: nodeId, + match_id: "1", + merkle_root: "a".repeat(64), + bot_count: 100, + kickoff_at: Date.now() + 60_000, + }, + }); + expect(res.statusCode).toBe(401); + }); + + it("commit accepts a valid pre-kickoff payload", async () => { + const { app, store } = await built; + const kickoffAt = Date.now() + 60_000; + const res = await app.inject({ + method: "POST", + url: "/v1/nodes/commit", + headers: { authorization: `Bearer ${nodeKey}` }, + payload: { + node_id: nodeId, + match_id: "1", + merkle_root: "a".repeat(64), + bot_count: 100, + kickoff_at: kickoffAt, + }, + }); + expect(res.statusCode).toBe(200); + const row = store.federatedNodes.getSnapshot(nodeId, "1"); + expect(row?.merkle_root).toBe("a".repeat(64)); + expect(row?.kickoff_at).toBe(kickoffAt); + expect(row?.total_bots).toBe(100); + }); + + it("commit rejects merkle_root that is not 64 hex chars", async () => { + const { app } = await built; + const res = await app.inject({ + method: "POST", + url: "/v1/nodes/commit", + headers: { authorization: `Bearer ${nodeKey}` }, + payload: { + node_id: nodeId, + match_id: "2", + merkle_root: "not-hex", + bot_count: 100, + kickoff_at: Date.now() + 60_000, + }, + }); + expect(res.statusCode).toBe(400); + }); + + it("commit rejects late submissions (kickoff in the past)", async () => { + const { app } = await built; + const res = await app.inject({ + method: "POST", + url: "/v1/nodes/commit", + headers: { authorization: `Bearer ${nodeKey}` }, + payload: { + node_id: nodeId, + match_id: "late_match", + merkle_root: "b".repeat(64), + bot_count: 100, + kickoff_at: Date.now() - 60_000, + }, + }); + expect(res.statusCode).toBe(422); + expect(res.json().error).toBe("kickoff_passed"); + }); + + it("commit refuses when the node_id does not belong to the auth key", async () => { + const { app, store } = await built; + const intruder = store.apiKeys.issue({ owner_email: "evil@example.com" }); + const otherNode = await app.inject({ + method: "POST", + url: "/v1/nodes/register", + headers: { authorization: `Bearer ${intruder.api_key}` }, + payload: { + owner_email: "evil@example.com", + public_url: "https://evil.example.com", + }, + }); + const otherKey = otherNode.json().node_key as string; + const res = await app.inject({ + method: "POST", + url: "/v1/nodes/commit", + headers: { authorization: `Bearer ${otherKey}` }, + payload: { + node_id: nodeId, + match_id: "3", + merkle_root: "c".repeat(64), + bot_count: 1, + kickoff_at: Date.now() + 60_000, + }, + }); + expect(res.statusCode).toBe(403); + }); + + it("leaderboard accepts a post-match aggregate report", async () => { + const { app, store } = await built; + const res = await app.inject({ + method: "POST", + url: "/v1/nodes/leaderboard", + headers: { authorization: `Bearer ${nodeKey}` }, + payload: { + node_id: nodeId, + match_id: "1", + total_bots: 100, + bots_correct: 62, + bots_still_perfect: 62, + top_1000: [ + { bot_id: "bot_a", score: 1 }, + { bot_id: "bot_b", score: 1 }, + ], + }, + }); + expect(res.statusCode).toBe(200); + const row = store.federatedNodes.getSnapshot(nodeId, "1"); + expect(row?.bots_correct).toBe(62); + expect(row?.bots_still_perfect).toBe(62); + expect(row?.merkle_root).toBe("a".repeat(64)); + }); + + it("leaderboard rejects top_1000 over 1000 rows", async () => { + const { app } = await built; + const tooMany = Array.from({ length: 1001 }, (_, i) => ({ + bot_id: `bot_${i}`, + score: 1, + })); + const res = await app.inject({ + method: "POST", + url: "/v1/nodes/leaderboard", + headers: { authorization: `Bearer ${nodeKey}` }, + payload: { + node_id: nodeId, + match_id: "4", + total_bots: 1000, + bots_correct: 500, + bots_still_perfect: 500, + top_1000: tooMany, + }, + }); + expect(res.statusCode).toBe(400); + }); +}); diff --git a/apps/game/tests/routes-picks-bulk.test.ts b/apps/game/tests/routes-picks-bulk.test.ts new file mode 100644 index 00000000..7768b422 --- /dev/null +++ b/apps/game/tests/routes-picks-bulk.test.ts @@ -0,0 +1,208 @@ +/** + * POST /v1/picks/bulk , Bot Arena swarm submission endpoint. + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §7 + */ +import { afterAll, beforeAll, describe, expect, it } from "vitest"; + +import { makeServer } from "./helpers.js"; + +describe("POST /v1/picks/bulk", () => { + const built = makeServer({ cacheTtlMs: 50 }); + let apiKey = ""; + let apiKeyHash = ""; + + beforeAll(async () => { + const { store } = await built; + const issued = store.apiKeys.issue({ + owner_email: "dev@example.com", + label: "swarm-01", + }); + apiKey = issued.api_key; + apiKeyHash = issued.key_hash; + // Seed two owned bots + one un-owned bot. + for (const id of ["bot_a", "bot_b"] as const) { + store.db + .prepare( + `INSERT INTO users (id, created_at, is_bot) VALUES (?, 1, 1)`, + ) + .run(id); + store.botOwners.claim({ + bot_id: id, + api_key_hash: apiKeyHash, + owner_email: "dev@example.com", + }); + } + store.db + .prepare(`INSERT INTO users (id, created_at, is_bot) VALUES (?, 1, 1)`) + .run("bot_unowned"); + }); + + afterAll(async () => { + const { app } = await built; + await app.close(); + }); + + it("accepts a small bulk payload and reports accepted count", async () => { + const { app } = await built; + const res = await app.inject({ + method: "POST", + url: "/v1/picks/bulk", + headers: { authorization: `Bearer ${apiKey}` }, + payload: { + tournament_id: "fifa-wc-2026", + submissions: [ + { + bot_id: "bot_a", + picks: [ + { match_id: "1", outcome: "home_win" }, + { match_id: "2", outcome: "draw" }, + ], + }, + { + bot_id: "bot_b", + picks: [{ match_id: "1", outcome: "away_win" }], + }, + ], + }, + }); + expect(res.statusCode).toBe(200); + const body = res.json(); + expect(body.accepted).toBe(3); + expect(body.dropped_picks).toEqual([]); + expect(body.quota_remaining.picks_per_hour).toBe(100_000 - 3); + }); + + it("upserts on a second submission for the same bot", async () => { + const { app, store } = await built; + const res = await app.inject({ + method: "POST", + url: "/v1/picks/bulk", + headers: { authorization: `Bearer ${apiKey}` }, + payload: { + tournament_id: "fifa-wc-2026", + submissions: [ + { + bot_id: "bot_a", + picks: [{ match_id: "1", outcome: "away_win" }], + }, + ], + }, + }); + expect(res.statusCode).toBe(200); + const row = store.getBracketForUser("bot_a", "fifa-wc-2026"); + expect(row).not.toBeNull(); + const payload = JSON.parse(row!.payload_json) as { + matchPredictions: Record; + }; + expect(payload.matchPredictions["1"]?.outcome).toBe("away_win"); + }); + + it("rejects bots the API key does not own with 403 not_owner", async () => { + const { app } = await built; + const res = await app.inject({ + method: "POST", + url: "/v1/picks/bulk", + headers: { authorization: `Bearer ${apiKey}` }, + payload: { + tournament_id: "fifa-wc-2026", + submissions: [ + { + bot_id: "bot_unowned", + picks: [{ match_id: "1", outcome: "home_win" }], + }, + ], + }, + }); + expect(res.statusCode).toBe(403); + expect(res.json().error).toBe("not_owner"); + }); + + it("rejects unknown bot_id with 403 not_owner", async () => { + const { app } = await built; + const res = await app.inject({ + method: "POST", + url: "/v1/picks/bulk", + headers: { authorization: `Bearer ${apiKey}` }, + payload: { + tournament_id: "fifa-wc-2026", + submissions: [ + { + bot_id: "bot_does_not_exist", + picks: [{ match_id: "1", outcome: "home_win" }], + }, + ], + }, + }); + expect(res.statusCode).toBe(403); + expect(res.json().error).toBe("not_owner"); + }); + + it("rejects payloads over 10,000 picks with 413", async () => { + const { app } = await built; + const picks = Array.from({ length: 5_001 }, (_, i) => ({ + match_id: String((i % 96) + 1), + outcome: "home_win" as const, + })); + const res = await app.inject({ + method: "POST", + url: "/v1/picks/bulk", + headers: { authorization: `Bearer ${apiKey}` }, + payload: { + tournament_id: "fifa-wc-2026", + submissions: [ + { bot_id: "bot_a", picks }, + { bot_id: "bot_b", picks }, + ], + }, + }); + expect(res.statusCode).toBe(413); + expect(res.json().error).toBe("batch_too_large"); + }); + + it("rejects requests without a valid API key with 401", async () => { + const { app } = await built; + const res = await app.inject({ + method: "POST", + url: "/v1/picks/bulk", + payload: { + tournament_id: "fifa-wc-2026", + submissions: [ + { + bot_id: "bot_a", + picks: [{ match_id: "1", outcome: "home_win" }], + }, + ], + }, + }); + expect(res.statusCode).toBe(401); + expect(res.json().error).toBe("missing_api_key"); + }); + + it("rejects a forged API key with 401", async () => { + const { app } = await built; + const res = await app.inject({ + method: "POST", + url: "/v1/picks/bulk", + headers: { authorization: "Bearer tnm_not_a_real_key_xxxxxxxxxxxxxxx" }, + payload: { tournament_id: "fifa-wc-2026", submissions: [] }, + }); + expect(res.statusCode).toBe(401); + expect(res.json().error).toBe("invalid_api_key"); + }); + + it("rejects malformed payloads with 400", async () => { + const { app } = await built; + const res = await app.inject({ + method: "POST", + url: "/v1/picks/bulk", + headers: { authorization: `Bearer ${apiKey}` }, + payload: { + tournament_id: "fifa-wc-2026", + submissions: [{ bot_id: "bot_a", picks: [] }], + }, + }); + expect(res.statusCode).toBe(400); + expect(res.json().error).toBe("invalid_payload"); + }); +}); diff --git a/apps/game/tests/routes-swarm.test.ts b/apps/game/tests/routes-swarm.test.ts new file mode 100644 index 00000000..18867b05 --- /dev/null +++ b/apps/game/tests/routes-swarm.test.ts @@ -0,0 +1,304 @@ +/** + * Browser-swarm federation endpoints. + * + * POST /v1/swarm/commit + * GET /v1/swarm/leaderboard + * GET /v1/swarm/proof/:merkle_root + * GET /v1/swarm/proof/:merkle_root/file/:filename + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §15.6 + */ +import { afterAll, beforeAll, describe, expect, it } from "vitest"; + +import { buildServer } from "../src/server.js"; +import { resolve, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +const here = dirname(fileURLToPath(import.meta.url)); +const MIGRATIONS_DIR = resolve(here, "..", "migrations"); + +function mockOtsFetch(): typeof fetch { + // Stand in for the OTS calendar: POST /digest returns 3 bytes of + // pending payload; GET /timestamp/ returns a payload that + // contains the Bitcoin attestation magic so the verify route flips + // to confirmed. + return (async (input: RequestInfo | URL) => { + const url = typeof input === "string" ? input : (input as URL).toString(); + if (url.endsWith("/digest")) { + return new Response(new Uint8Array([0xf1, 0x04, 0x01]).buffer, { + status: 200, + }); + } + if (url.includes("/timestamp/")) { + // BTC attestation magic embedded. + return new Response( + new Uint8Array([ + 0xff, 0x05, 0x88, 0x96, 0x0d, 0x73, 0xd7, 0x19, 0x01, + ]).buffer, + { status: 200 }, + ); + } + return new Response("", { status: 404 }); + }) as typeof fetch; +} + +async function makeSwarmServer() { + return buildServer({ + dbPath: ":memory:", + migrationsDir: MIGRATIONS_DIR, + adminToken: "test-admin", + cacheTtlMs: 50, + rateLimit: false, + skipPunditRecompute: true, + otsFetch: mockOtsFetch(), + otsCalendars: ["https://a.example.com", "https://b.example.com"], + publicBaseUrl: "https://play.tournamental.com", + }); +} + +const VALID_ROOT_A = "a".repeat(64); +const VALID_ROOT_B = "b".repeat(64); + +describe("POST /v1/swarm/commit", () => { + const built = makeSwarmServer(); + + afterAll(async () => { + const { app } = await built; + await app.close(); + }); + + it("persists a swarm summary and submits to OTS calendars", async () => { + const { app, store } = await built; + const res = await app.inject({ + method: "POST", + url: "/v1/swarm/commit", + payload: { + node_id: "browser-abc12345", + run_id: "run-aaa-111", + master_seed: "tournamental-browser-v1", + strategy: "chalk-v1", + total_bots: 100, + merkle_root: VALID_ROOT_A, + top_n_claim: { bot_index: 7, claimed_score: 0.95, picks_count: 64 }, + started_at: Date.now() - 60_000, + finished_at: Date.now(), + }, + }); + expect(res.statusCode).toBe(201); + const body = res.json(); + expect(body.ots_status).toBe("pending"); + expect(body.pending_calendars).toEqual([ + "https://a.example.com", + "https://b.example.com", + ]); + expect(body.ots_proof_url).toBe( + `https://play.tournamental.com/v1/swarm/proof/${VALID_ROOT_A}`, + ); + + const row = store.swarmClaims.getByMerkleRoot(VALID_ROOT_A); + expect(row).not.toBeNull(); + expect(row!.total_bots).toBe(100); + expect(row!.ots_status).toBe("pending"); + const pending = store.swarmClaims.parsePending(row!); + expect(pending).toHaveLength(2); + }); + + it("rejects a malformed merkle_root", async () => { + const { app } = await built; + const res = await app.inject({ + method: "POST", + url: "/v1/swarm/commit", + payload: { + node_id: "browser-abc12345", + run_id: "run-bad-merkle", + master_seed: "x", + total_bots: 10, + merkle_root: "not-hex", + top_n_claim: { bot_index: 0, claimed_score: 0, picks_count: 0 }, + started_at: 1, + finished_at: 2, + }, + }); + expect(res.statusCode).toBe(400); + }); + + it("rejects an invalid node_id shape", async () => { + const { app } = await built; + const res = await app.inject({ + method: "POST", + url: "/v1/swarm/commit", + payload: { + node_id: "hacker!@#", + run_id: "ok-run", + master_seed: "x", + total_bots: 10, + merkle_root: VALID_ROOT_B, + top_n_claim: { bot_index: 0, claimed_score: 0, picks_count: 0 }, + started_at: 1, + finished_at: 2, + }, + }); + expect(res.statusCode).toBe(400); + }); +}); + +describe("GET /v1/swarm/leaderboard + /v1/swarm/proof/...", () => { + const built = makeSwarmServer(); + + beforeAll(async () => { + const { app } = await built; + // Seed 3 claims with descending scores. + const make = async ( + runId: string, + root: string, + score: number, + botIndex: number, + ) => + app.inject({ + method: "POST", + url: "/v1/swarm/commit", + payload: { + node_id: "browser-1234abcd", + run_id: runId, + master_seed: "tournamental-browser-v1", + strategy: "chalk-v1", + total_bots: 100, + merkle_root: root, + top_n_claim: { + bot_index: botIndex, + claimed_score: score, + picks_count: 64, + }, + started_at: Date.now() - 60_000, + finished_at: Date.now(), + }, + }); + + await make("lb-1", "1".padEnd(64, "0"), 0.5, 1); + await make("lb-2", "2".padEnd(64, "0"), 0.9, 2); + await make("lb-3", "3".padEnd(64, "0"), 0.7, 3); + }); + + afterAll(async () => { + const { app } = await built; + await app.close(); + }); + + it("ranks claims by claimed_score desc", async () => { + const { app } = await built; + const res = await app.inject({ + method: "GET", + url: "/v1/swarm/leaderboard?limit=10", + }); + expect(res.statusCode).toBe(200); + const body = res.json(); + expect(body.rows.map((r: { rank: number }) => r.rank)).toEqual([1, 2, 3]); + expect(body.rows.map((r: { claimed_score: number }) => r.claimed_score)).toEqual([ + 0.9, 0.7, 0.5, + ]); + expect(body.rows[0].ots_proof_url).toContain("/v1/swarm/proof/"); + expect(body.rows[0].bot_index).toBe(2); + }); + + it("returns proof metadata for a known root", async () => { + const { app } = await built; + const res = await app.inject({ + method: "GET", + url: `/v1/swarm/proof/${"2".padEnd(64, "0")}`, + }); + expect(res.statusCode).toBe(200); + const body = res.json(); + expect(body.merkle_root).toBe("2".padEnd(64, "0")); + expect(body.ots_status).toBe("pending"); + expect(body.pending_calendars).toHaveLength(2); + expect(body.pending_calendars[0]).toHaveProperty("calendar_slug"); + expect(body.pending_calendars[0]).toHaveProperty("download_url"); + expect(body.upgraded).toBeNull(); + }); + + it("404s on a root that hasn't been committed", async () => { + const { app } = await built; + const res = await app.inject({ + method: "GET", + url: `/v1/swarm/proof/${"d".repeat(64)}`, + }); + expect(res.statusCode).toBe(404); + }); + + it("400s on a malformed root", async () => { + const { app } = await built; + const res = await app.inject({ + method: "GET", + url: "/v1/swarm/proof/not-hex", + }); + expect(res.statusCode).toBe(400); + }); + + it("serves an .ots file for a pending calendar", async () => { + const { app } = await built; + const root = "2".padEnd(64, "0"); + // a.example.com -> a-example-com + const res = await app.inject({ + method: "GET", + url: `/v1/swarm/proof/${root}/file/a-example-com.ots`, + }); + expect(res.statusCode).toBe(200); + expect(res.headers["content-type"]).toContain( + "application/vnd.opentimestamps.ots", + ); + const body = res.rawPayload; + // First byte of the OTS magic header. + expect(body[0]).toBe(0x00); + // Version byte. + expect(body[31]).toBe(0x01); + }); + + it("409s on upgraded.ots before the scheduler has confirmed", async () => { + const { app } = await built; + const root = "2".padEnd(64, "0"); + const res = await app.inject({ + method: "GET", + url: `/v1/swarm/proof/${root}/file/upgraded.ots`, + }); + expect(res.statusCode).toBe(409); + }); +}); + +describe("scheduler upgrade integration", () => { + it("flips a row to 'confirmed' once the calendar returns a BTC attestation", async () => { + const { app, store } = await makeSwarmServer(); + try { + const root = "c".repeat(64); + await app.inject({ + method: "POST", + url: "/v1/swarm/commit", + payload: { + node_id: "browser-deadbeef", + run_id: "sched-1", + master_seed: "x", + total_bots: 10, + merkle_root: root, + top_n_claim: { + bot_index: 0, + claimed_score: 0.5, + picks_count: 1, + }, + started_at: 1, + finished_at: 2, + }, + }); + + const { OtsScheduler } = await import("../src/services/ots-scheduler.js"); + const scheduler = new OtsScheduler(store.swarmClaims, { + fetchImpl: mockOtsFetch(), + stalenessMs: 0, + }); + await scheduler.tick(); + const row = store.swarmClaims.getByMerkleRoot(root); + expect(row?.ots_status).toBe("confirmed"); + expect(row?.upgraded_ots_hex).toBeTruthy(); + } finally { + await app.close(); + } + }); +}); diff --git a/apps/game/tests/routes-swarms.test.ts b/apps/game/tests/routes-swarms.test.ts new file mode 100644 index 00000000..1ab7aa5d --- /dev/null +++ b/apps/game/tests/routes-swarms.test.ts @@ -0,0 +1,359 @@ +/** + * Operator-keyed swarm-summary endpoints. + * + * POST /v1/swarms/:operator_id/summary + * GET /v1/swarms/:operator_id + * GET /v1/swarms + * GET /v1/perfect-track + * + * Spec: A13 task brief. + */ +import { afterAll, beforeAll, describe, expect, it } from "vitest"; + +import { hashApiKey } from "../src/store/api-keys.js"; +import { makeServer } from "./helpers.js"; + +const VALID_ROOT = "a".repeat(64); + +function aliveRows(rows: Array<{ n: number; alive_count: number }>) { + return rows; +} + +describe("POST /v1/swarms/:operator_id/summary", () => { + const built = makeServer({ cacheTtlMs: 50 }); + let plainKey = ""; + let operatorId = ""; + + beforeAll(async () => { + const { store } = await built; + const issued = store.apiKeys.issue({ + owner_email: "owner@example.com", + label: "swarm-operator", + }); + plainKey = issued.api_key; + operatorId = hashApiKey(plainKey); + }); + + afterAll(async () => { + const { app } = await built; + await app.close(); + }); + + it("rejects requests without an API key", async () => { + const { app } = await built; + const res = await app.inject({ + method: "POST", + url: `/v1/swarms/${operatorId}/summary`, + payload: { + total_bots: 100, + bots_alive_after_match_n: [], + best_bot_score: 10, + top_k: [], + merkle_root: VALID_ROOT, + kickoff_at: Date.now() + 60_000, + generated_at: Date.now(), + }, + }); + expect(res.statusCode).toBe(401); + }); + + it("rejects when the operator_id does not match the key hash", async () => { + const { app } = await built; + const res = await app.inject({ + method: "POST", + url: `/v1/swarms/${"b".repeat(64)}/summary`, + headers: { authorization: `Bearer ${plainKey}` }, + payload: { + total_bots: 100, + bots_alive_after_match_n: [], + best_bot_score: 10, + top_k: [], + merkle_root: VALID_ROOT, + kickoff_at: Date.now() + 60_000, + generated_at: Date.now(), + }, + }); + expect(res.statusCode).toBe(403); + expect(res.json().error).toBe("not_operator"); + }); + + it("rejects an invalid operator_id (not hex)", async () => { + const { app } = await built; + const res = await app.inject({ + method: "POST", + url: `/v1/swarms/not-a-hash/summary`, + headers: { authorization: `Bearer ${plainKey}` }, + payload: { + total_bots: 0, + bots_alive_after_match_n: [], + best_bot_score: 0, + top_k: [], + merkle_root: VALID_ROOT, + kickoff_at: 0, + generated_at: 0, + }, + }); + expect(res.statusCode).toBe(400); + }); + + it("accepts a valid summary and persists it", async () => { + const { app, store } = await built; + const kickoffAt = Date.now() + 60_000; + const res = await app.inject({ + method: "POST", + url: `/v1/swarms/${operatorId}/summary`, + headers: { authorization: `Bearer ${plainKey}` }, + payload: { + total_bots: 12_345, + bots_alive_after_match_n: aliveRows([ + { n: 1, alive_count: 1000 }, + { n: 2, alive_count: 800 }, + ]), + best_bot_score: 42, + top_k: [ + { bot_id: "bot_001", score: 42, chalk_score: 0.91 }, + { bot_id: "bot_002", score: 41, chalk_score: 0.88 }, + ], + merkle_root: VALID_ROOT, + kickoff_at: kickoffAt, + generated_at: Date.now(), + }, + }); + expect(res.statusCode).toBe(201); + const body = res.json(); + expect(body.operator_id).toBe(operatorId); + expect(body.total_bots).toBe(12_345); + expect(body.best_bot_score).toBe(42); + + const row = store.swarmSummaries.getByCompositeKey(operatorId, kickoffAt); + expect(row).not.toBeNull(); + expect(row!.total_bots).toBe(12_345); + expect(row!.merkle_root).toBe(VALID_ROOT); + }); + + it("is idempotent on (operator_id, kickoff_at)", async () => { + const { app, store } = await built; + const kickoffAt = Date.now() + 120_000; + const first = await app.inject({ + method: "POST", + url: `/v1/swarms/${operatorId}/summary`, + headers: { authorization: `Bearer ${plainKey}` }, + payload: { + total_bots: 100, + bots_alive_after_match_n: [], + best_bot_score: 5, + top_k: [], + merkle_root: VALID_ROOT, + kickoff_at: kickoffAt, + generated_at: Date.now(), + }, + }); + expect(first.statusCode).toBe(201); + + const second = await app.inject({ + method: "POST", + url: `/v1/swarms/${operatorId}/summary`, + headers: { authorization: `Bearer ${plainKey}` }, + payload: { + total_bots: 200, // higher + bots_alive_after_match_n: [{ n: 5, alive_count: 50 }], + best_bot_score: 8, + top_k: [], + merkle_root: VALID_ROOT, + kickoff_at: kickoffAt, + generated_at: Date.now() + 1, + }, + }); + expect(second.statusCode).toBe(201); + + const row = store.swarmSummaries.getByCompositeKey(operatorId, kickoffAt); + expect(row!.total_bots).toBe(200); + expect(row!.best_bot_score).toBe(8); + }); + + it("rejects merkle_root that is not 64 hex chars", async () => { + const { app } = await built; + const res = await app.inject({ + method: "POST", + url: `/v1/swarms/${operatorId}/summary`, + headers: { authorization: `Bearer ${plainKey}` }, + payload: { + total_bots: 1, + bots_alive_after_match_n: [], + best_bot_score: 0, + top_k: [], + merkle_root: "not-hex", + kickoff_at: Date.now(), + generated_at: Date.now(), + }, + }); + expect(res.statusCode).toBe(400); + }); + + it("rejects top_k over 1,000 rows", async () => { + const { app } = await built; + const tooMany = Array.from({ length: 1001 }, (_, i) => ({ + bot_id: `b_${i}`, + score: 1, + chalk_score: 0.5, + })); + const res = await app.inject({ + method: "POST", + url: `/v1/swarms/${operatorId}/summary`, + headers: { authorization: `Bearer ${plainKey}` }, + payload: { + total_bots: 1, + bots_alive_after_match_n: [], + best_bot_score: 0, + top_k: tooMany, + merkle_root: VALID_ROOT, + kickoff_at: Date.now(), + generated_at: Date.now(), + }, + }); + expect(res.statusCode).toBe(400); + }); +}); + +describe("GET /v1/swarms/:operator_id", () => { + const built = makeServer({ cacheTtlMs: 50 }); + let plainKey = ""; + let operatorId = ""; + + beforeAll(async () => { + const { store, app } = await built; + const issued = store.apiKeys.issue({ owner_email: "get@example.com" }); + plainKey = issued.api_key; + operatorId = hashApiKey(plainKey); + // Seed one summary so the GET has something to return. + await app.inject({ + method: "POST", + url: `/v1/swarms/${operatorId}/summary`, + headers: { authorization: `Bearer ${plainKey}` }, + payload: { + total_bots: 500, + bots_alive_after_match_n: [{ n: 1, alive_count: 100 }], + best_bot_score: 23, + top_k: [{ bot_id: "bot_top", score: 23, chalk_score: 0.95 }], + merkle_root: VALID_ROOT, + kickoff_at: 1_700_000_000_000, + generated_at: 1_700_000_000_100, + }, + }); + }); + + afterAll(async () => { + const { app } = await built; + await app.close(); + }); + + it("returns the latest summary with edge cache headers", async () => { + const { app } = await built; + const res = await app.inject({ + method: "GET", + url: `/v1/swarms/${operatorId}`, + }); + expect(res.statusCode).toBe(200); + expect(res.headers["cache-control"]).toContain("s-maxage=60"); + expect(res.headers["cache-control"]).toContain("stale-while-revalidate=300"); + expect(res.headers["etag"]).toBeDefined(); + const body = res.json(); + expect(body.operator_id).toBe(operatorId); + expect(body.total_bots).toBe(500); + expect(body.bots_alive_after_match_n).toHaveLength(1); + expect(body.top_k).toHaveLength(1); + expect(body.top_k[0].bot_id).toBe("bot_top"); + }); + + it("returns 304 when If-None-Match matches", async () => { + const { app } = await built; + const first = await app.inject({ + method: "GET", + url: `/v1/swarms/${operatorId}`, + }); + const etag = first.headers["etag"] as string; + expect(etag).toBeDefined(); + + const second = await app.inject({ + method: "GET", + url: `/v1/swarms/${operatorId}`, + headers: { "if-none-match": etag }, + }); + expect(second.statusCode).toBe(304); + }); + + it("returns 404 for an unknown operator_id", async () => { + const { app } = await built; + const res = await app.inject({ + method: "GET", + url: `/v1/swarms/${"f".repeat(64)}`, + }); + expect(res.statusCode).toBe(404); + // Still edge-cached so 404 probes don't pummel the origin. + expect(res.headers["cache-control"]).toContain("s-maxage=60"); + }); + + it("rejects an invalid operator_id", async () => { + const { app } = await built; + const res = await app.inject({ + method: "GET", + url: `/v1/swarms/not-hex`, + }); + expect(res.statusCode).toBe(400); + }); +}); + +describe("GET /v1/swarms (global aggregate)", () => { + const built = makeServer({ cacheTtlMs: 50 }); + + beforeAll(async () => { + const { store, app } = await built; + // Three operators with varying best_bot_score. + for (let i = 0; i < 3; i++) { + const issued = store.apiKeys.issue({ + owner_email: `op${i}@example.com`, + }); + const operatorId = hashApiKey(issued.api_key); + await app.inject({ + method: "POST", + url: `/v1/swarms/${operatorId}/summary`, + headers: { authorization: `Bearer ${issued.api_key}` }, + payload: { + total_bots: 1000 * (i + 1), + bots_alive_after_match_n: [], + best_bot_score: 10 + i * 10, // 10, 20, 30 + top_k: [], + merkle_root: VALID_ROOT, + kickoff_at: 1_700_000_000_000 + i, + generated_at: 1_700_000_000_100 + i, + }, + }); + } + }); + + afterAll(async () => { + const { app } = await built; + await app.close(); + }); + + it("returns top operators ranked by best_bot_score desc", async () => { + const { app } = await built; + const res = await app.inject({ method: "GET", url: "/v1/swarms" }); + expect(res.statusCode).toBe(200); + expect(res.headers["cache-control"]).toContain("s-maxage=60"); + const body = res.json(); + expect(body.operators).toHaveLength(3); + expect(body.operators[0].best_bot_score).toBe(30); + expect(body.operators[2].best_bot_score).toBe(10); + }); + + it("honours the limit query param", async () => { + const { app } = await built; + const res = await app.inject({ + method: "GET", + url: "/v1/swarms?limit=2", + }); + expect(res.statusCode).toBe(200); + expect(res.json().operators).toHaveLength(2); + }); +}); diff --git a/apps/game/tests/services-kickoff-commit.test.ts b/apps/game/tests/services-kickoff-commit.test.ts new file mode 100644 index 00000000..0280e7a3 --- /dev/null +++ b/apps/game/tests/services-kickoff-commit.test.ts @@ -0,0 +1,169 @@ +/** + * commitKickoff , builds a merkle root over (bot/user, match, outcome, + * locked_at) leaves for a single kickoff event, stamps each included + * bracket with the commit timestamp, and emits the root to the OTS + * poster. Phase 1 forward-compat hook for the Phase 2 federation work. + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §15.6 + */ +import { resolve, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +import { describe, it, expect, beforeEach, afterEach } from "vitest"; + +import { GameStore } from "../src/store/db.js"; +import { + commitKickoff, + type CommitKickoffResult, +} from "../src/services/kickoff-commit.js"; + +const here = dirname(fileURLToPath(import.meta.url)); +const MIGRATIONS_DIR = resolve(here, "..", "migrations"); + +let store: GameStore; +beforeEach(() => { + store = new GameStore({ dbPath: ":memory:", migrationsDir: MIGRATIONS_DIR }); + // Seed three users with picks for match "1". + const lockedAt = 1_700_000_000_000; + for (const [id, isBot, outcome] of [ + ["u_h1", 0, "home_win"], + ["bot_b1", 1, "draw"], + ["bot_b2", 1, "away_win"], + ] as const) { + store.db + .prepare( + `INSERT INTO users (id, created_at, is_bot) VALUES (?, ?, ?)`, + ) + .run(id, lockedAt, isBot); + store.db + .prepare( + `INSERT INTO brackets + (id, user_id, tournament_id, payload_json, locked_at, + score_total, share_guid) + VALUES (?, ?, 'fifa-wc-2026', ?, ?, 0, ?)`, + ) + .run( + `${id}_b`, + id, + JSON.stringify({ + bracketId: `${id}_b`, + matchPredictions: { + "1": { matchId: "1", outcome, lockedAt: "2024-01-01T00:00:00Z" }, + }, + groupTiebreakers: {}, + knockoutPredictions: {}, + version: 1, + }), + lockedAt, + id.slice(0, 8), + ); + } +}); +afterEach(() => store.close()); + +describe("commitKickoff", () => { + it("posts a 64-hex merkle root over the picks for that match", async () => { + const posted: string[] = []; + const result: CommitKickoffResult = await commitKickoff({ + store, + tournament_id: "fifa-wc-2026", + match_id: "1", + committed_at_utc: 1_700_000_001_000, + postOts: async (root) => { + posted.push(root); + }, + }); + expect(result.root).toMatch(/^[0-9a-f]{64}$/); + expect(posted).toEqual([result.root]); + expect(result.leaf_count).toBe(3); + }); + + it("stamps committed_at_utc on every bracket that contributed a pick", async () => { + await commitKickoff({ + store, + tournament_id: "fifa-wc-2026", + match_id: "1", + committed_at_utc: 1_700_000_001_000, + postOts: async () => { + // no-op + }, + }); + const rows = store.db + .prepare( + `SELECT user_id, committed_at_utc FROM brackets + WHERE tournament_id = 'fifa-wc-2026' ORDER BY user_id`, + ) + .all() as Array<{ user_id: string; committed_at_utc: number | null }>; + for (const row of rows) { + expect(row.committed_at_utc).toBe(1_700_000_001_000); + } + }); + + it("does not include picks for matches other than the one being committed", async () => { + // Add a bracket whose pick is for match "2"; the commit for "1" + // must not pick it up. + store.db + .prepare(`INSERT INTO users (id, created_at, is_bot) VALUES (?, 1, 1)`) + .run("bot_other_match"); + store.db + .prepare( + `INSERT INTO brackets + (id, user_id, tournament_id, payload_json, locked_at, + score_total, share_guid) + VALUES (?, ?, 'fifa-wc-2026', ?, 1, 0, ?)`, + ) + .run( + "bot_other_match_b", + "bot_other_match", + JSON.stringify({ + bracketId: "x", + matchPredictions: { + "2": { matchId: "2", outcome: "home_win", lockedAt: "" }, + }, + groupTiebreakers: {}, + knockoutPredictions: {}, + version: 1, + }), + "bot_othe", + ); + const result = await commitKickoff({ + store, + tournament_id: "fifa-wc-2026", + match_id: "1", + committed_at_utc: 1_700_000_001_000, + postOts: async () => {}, + }); + expect(result.leaf_count).toBe(3); + }); + + it("produces a canonical empty-tree root if no picks for the match", async () => { + const result = await commitKickoff({ + store, + tournament_id: "fifa-wc-2026", + match_id: "no_such_match", + committed_at_utc: 1_700_000_001_000, + postOts: async () => {}, + }); + expect(result.leaf_count).toBe(0); + expect(result.root).toMatch(/^[0-9a-f]{64}$/); + }); + + it("two commits for the same match with the same picks produce the same root", async () => { + const noopPost = async () => {}; + const r1 = await commitKickoff({ + store, + tournament_id: "fifa-wc-2026", + match_id: "1", + committed_at_utc: 1, + postOts: noopPost, + }); + const r2 = await commitKickoff({ + store, + tournament_id: "fifa-wc-2026", + match_id: "1", + committed_at_utc: 2, + postOts: noopPost, + }); + expect(r1.root).toBe(r2.root); + }); +}); diff --git a/apps/game/tests/services-leaderboard-cache.test.ts b/apps/game/tests/services-leaderboard-cache.test.ts new file mode 100644 index 00000000..a9c7af1f --- /dev/null +++ b/apps/game/tests/services-leaderboard-cache.test.ts @@ -0,0 +1,74 @@ +/** + * LeaderboardCache (in-memory LRU + TTL + prefix invalidation). + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §8.3 + */ +import { describe, it, expect, vi } from "vitest"; + +import { LeaderboardCache } from "../src/services/leaderboard-cache.js"; + +describe("LeaderboardCache", () => { + it("returns cached value within TTL (single fetcher call)", async () => { + const fetcher = vi.fn(async () => ({ rows: ["a"] })); + const cache = new LeaderboardCache({ defaultTtlMs: 1_000 }); + await cache.get("k1", fetcher); + await cache.get("k1", fetcher); + expect(fetcher).toHaveBeenCalledTimes(1); + }); + + it("refetches after TTL expiry", async () => { + const fetcher = vi.fn(async () => ({ rows: ["a"] })); + const cache = new LeaderboardCache({ defaultTtlMs: 5 }); + await cache.get("k1", fetcher); + await new Promise((r) => setTimeout(r, 15)); + await cache.get("k1", fetcher); + expect(fetcher).toHaveBeenCalledTimes(2); + }); + + it("invalidate() forces a refetch for that key", async () => { + const fetcher = vi.fn(async () => ({ rows: ["a"] })); + const cache = new LeaderboardCache({ defaultTtlMs: 60_000 }); + await cache.get("k1", fetcher); + cache.invalidate("k1"); + await cache.get("k1", fetcher); + expect(fetcher).toHaveBeenCalledTimes(2); + }); + + it("invalidatePrefix() drops every matching key", async () => { + const fetcher = vi.fn(async () => ({ rows: ["a"] })); + const cache = new LeaderboardCache({ defaultTtlMs: 60_000 }); + await cache.get("lb:fifa-wc-2026:humans", fetcher); + await cache.get("lb:fifa-wc-2026:bots", fetcher); + await cache.get("other:key", fetcher); + expect(fetcher).toHaveBeenCalledTimes(3); + cache.invalidatePrefix("lb:"); + await cache.get("lb:fifa-wc-2026:humans", fetcher); + await cache.get("lb:fifa-wc-2026:bots", fetcher); + await cache.get("other:key", fetcher); + // humans + bots refetched, other:key still warm. + expect(fetcher).toHaveBeenCalledTimes(5); + }); + + it("evicts the oldest entry when maxEntries is reached", async () => { + const fetcher = vi.fn(async (key: string) => ({ rows: [key] })); + const cache = new LeaderboardCache({ + defaultTtlMs: 60_000, + maxEntries: 2, + }); + await cache.get("k1", () => fetcher("k1")); + await cache.get("k2", () => fetcher("k2")); + await cache.get("k3", () => fetcher("k3")); // evicts k1 + expect(cache.size()).toBe(2); + await cache.get("k1", () => fetcher("k1")); // miss, refetches + expect(fetcher).toHaveBeenCalledTimes(4); + }); + + it("accepts a per-call ttlOverrideMs", async () => { + const fetcher = vi.fn(async () => ({ rows: ["a"] })); + const cache = new LeaderboardCache({ defaultTtlMs: 60_000 }); + await cache.get("k1", fetcher, 5); + await new Promise((r) => setTimeout(r, 20)); + await cache.get("k1", fetcher); + expect(fetcher).toHaveBeenCalledTimes(2); + }); +}); diff --git a/apps/game/tests/services-perfect-track-watch.test.ts b/apps/game/tests/services-perfect-track-watch.test.ts new file mode 100644 index 00000000..87ed9572 --- /dev/null +++ b/apps/game/tests/services-perfect-track-watch.test.ts @@ -0,0 +1,222 @@ +/** + * Perfect-bracket-track alert service tests. + * + * Verifies the "still alive past match 80" detection logic, idempotent + * alert recording, and the optional webhook fan-out. + * + * Spec: A13 task brief. + */ +import { resolve, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +import { GameStore } from "../src/store/db.js"; +import { + PERFECT_TRACK_MATCH_THRESHOLD, + runPerfectTrackWatch, +} from "../src/services/perfect-track-watch.js"; + +const here = dirname(fileURLToPath(import.meta.url)); +const MIGRATIONS_DIR = resolve(here, "..", "migrations"); + +const VALID_ROOT = "a".repeat(64); + +function makeStore(): GameStore { + return new GameStore({ + dbPath: ":memory:", + migrationsDir: MIGRATIONS_DIR, + }); +} + +function seedSummary( + store: GameStore, + operator_id: string, + alive: ReadonlyArray<{ n: number; alive_count: number }>, + overrides: Partial<{ + kickoff_at: number; + total_bots: number; + best_bot_score: number; + }> = {}, +) { + store.swarmSummaries.upsert({ + operator_id, + kickoff_at: overrides.kickoff_at ?? 1_700_000_000_000, + total_bots: overrides.total_bots ?? 1000, + bots_alive_after_match_n: alive, + best_bot_score: overrides.best_bot_score ?? 0, + top_k: [], + merkle_root: VALID_ROOT, + generated_at: Date.now(), + }); +} + +describe("runPerfectTrackWatch", () => { + let store: GameStore; + + beforeEach(() => { + store = makeStore(); + }); + + afterEach(() => { + store.close(); + }); + + it("threshold is 80", () => { + expect(PERFECT_TRACK_MATCH_THRESHOLD).toBe(80); + }); + + it("emits no alerts when no summary crosses match 80", () => { + seedSummary(store, "a".repeat(64), [ + { n: 1, alive_count: 1000 }, + { n: 50, alive_count: 100 }, + { n: 79, alive_count: 10 }, + ]); + + const result = runPerfectTrackWatch({ + store, + now: Date.now(), + webhookUrl: null, + }); + + expect(result.alertsRecorded).toHaveLength(0); + expect(store.perfectTrackAlerts.listAll()).toHaveLength(0); + }); + + it("emits an alert when a summary has alive bots at match 80+", () => { + const operator = "a".repeat(64); + seedSummary(store, operator, [ + { n: 70, alive_count: 50 }, + { n: 80, alive_count: 3 }, + { n: 90, alive_count: 1 }, + ]); + + const result = runPerfectTrackWatch({ + store, + now: 1_700_000_999_000, + webhookUrl: null, + }); + + expect(result.alertsRecorded).toHaveLength(1); + expect(result.alertsRecorded[0]).toMatchObject({ + operator_id: operator, + match_number: 90, + alive_count: 1, + }); + + const rows = store.perfectTrackAlerts.listAll(); + expect(rows).toHaveLength(1); + expect(rows[0]?.detected_at).toBe(1_700_000_999_000); + }); + + it("ignores alive_count = 0 even at match 80+", () => { + seedSummary(store, "a".repeat(64), [{ n: 80, alive_count: 0 }]); + const result = runPerfectTrackWatch({ + store, + now: Date.now(), + webhookUrl: null, + }); + expect(result.alertsRecorded).toHaveLength(0); + }); + + it("picks the highest matching n per operator", () => { + seedSummary(store, "a".repeat(64), [ + { n: 80, alive_count: 100 }, + { n: 85, alive_count: 50 }, + { n: 90, alive_count: 5 }, + ]); + const result = runPerfectTrackWatch({ + store, + now: Date.now(), + webhookUrl: null, + }); + expect(result.alertsRecorded).toHaveLength(1); + expect(result.alertsRecorded[0]?.match_number).toBe(90); + expect(result.alertsRecorded[0]?.alive_count).toBe(5); + }); + + it("is idempotent on re-run for the same (operator, match) pair", () => { + const operator = "b".repeat(64); + seedSummary(store, operator, [{ n: 85, alive_count: 10 }]); + + runPerfectTrackWatch({ store, now: 1000, webhookUrl: null }); + runPerfectTrackWatch({ store, now: 2000, webhookUrl: null }); + + const rows = store.perfectTrackAlerts.listAll(); + expect(rows).toHaveLength(1); + expect(rows[0]?.detected_at).toBe(2000); // updated, not duplicated + }); + + it("emits one alert per operator", () => { + seedSummary(store, "a".repeat(64), [{ n: 81, alive_count: 5 }]); + seedSummary(store, "b".repeat(64), [{ n: 82, alive_count: 2 }]); + seedSummary(store, "c".repeat(64), [{ n: 50, alive_count: 99 }]); // no alert + + const result = runPerfectTrackWatch({ + store, + now: Date.now(), + webhookUrl: null, + }); + expect(result.alertsRecorded).toHaveLength(2); + }); + + it("POSTs to the webhook url when alerts fire", async () => { + const operator = "a".repeat(64); + seedSummary(store, operator, [{ n: 81, alive_count: 7 }]); + + const calls: Array<{ url: string; body: unknown }> = []; + const fakeFetch = vi.fn(async (url: RequestInfo | URL, init?: RequestInit) => { + calls.push({ + url: typeof url === "string" ? url : url.toString(), + body: init?.body ? JSON.parse(init.body as string) : null, + }); + return new Response("", { status: 200 }); + }); + + const result = runPerfectTrackWatch({ + store, + now: 1234, + webhookUrl: "https://webhook.example.com/alerts", + fetchImpl: fakeFetch as unknown as typeof fetch, + }); + + expect(result.webhookPosted).toBe(1); + // Allow microtask drain. + await new Promise((r) => setImmediate(r)); + expect(calls).toHaveLength(1); + expect(calls[0]?.url).toBe("https://webhook.example.com/alerts"); + expect(calls[0]?.body).toMatchObject({ + event: "perfect_track_alert", + operator_id: operator, + match_number: 81, + alive_count: 7, + }); + }); + + it("does not POST when webhookUrl is null", () => { + seedSummary(store, "a".repeat(64), [{ n: 90, alive_count: 1 }]); + const fakeFetch = vi.fn(); + const result = runPerfectTrackWatch({ + store, + now: Date.now(), + webhookUrl: null, + fetchImpl: fakeFetch as unknown as typeof fetch, + }); + expect(result.webhookPosted).toBe(0); + expect(fakeFetch).not.toHaveBeenCalled(); + }); + + it("latestSummary rolls up to the highest match across operators", () => { + seedSummary(store, "a".repeat(64), [{ n: 81, alive_count: 5 }]); + seedSummary(store, "b".repeat(64), [{ n: 90, alive_count: 2 }]); + seedSummary(store, "c".repeat(64), [{ n: 90, alive_count: 3 }]); + + runPerfectTrackWatch({ store, now: Date.now(), webhookUrl: null }); + + const summary = store.perfectTrackAlerts.latestSummary(); + expect(summary).not.toBeNull(); + expect(summary!.highest_match).toBe(90); + expect(summary!.total_alive).toBe(5); // 2 + 3 at match 90 + expect(summary!.operator_count).toBe(2); + }); +}); diff --git a/apps/game/tests/store-api-keys.test.ts b/apps/game/tests/store-api-keys.test.ts new file mode 100644 index 00000000..d649ff28 --- /dev/null +++ b/apps/game/tests/store-api-keys.test.ts @@ -0,0 +1,135 @@ +/** + * ApiKeyStore , issuance, lookup, revocation. + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §6.3, §14 + */ +import { resolve, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +import { describe, it, expect, beforeEach, afterEach } from "vitest"; + +import { GameStore } from "../src/store/db.js"; +import { + ApiKeyStore, + generateApiKey, + hashApiKey, +} from "../src/store/api-keys.js"; + +const here = dirname(fileURLToPath(import.meta.url)); +const MIGRATIONS_DIR = resolve(here, "..", "migrations"); + +let store: GameStore; +let keys: ApiKeyStore; + +beforeEach(() => { + store = new GameStore({ dbPath: ":memory:", migrationsDir: MIGRATIONS_DIR }); + keys = new ApiKeyStore(store.db); +}); + +afterEach(() => { + store.close(); +}); + +describe("generateApiKey + hashApiKey", () => { + it("mints a 32-char tnm_ prefixed key", () => { + const k = generateApiKey(); + expect(k).toMatch(/^tnm_[A-Za-z0-9_-]{32}$/); + }); + + it("hashApiKey returns a 64-hex-char sha256", () => { + const h = hashApiKey("tnm_test_key"); + expect(h).toMatch(/^[0-9a-f]{64}$/); + }); + + it("hashApiKey is stable", () => { + expect(hashApiKey("abc")).toBe(hashApiKey("abc")); + }); +}); + +describe("ApiKeyStore", () => { + it("issues a key with the default 1000-bot quota", () => { + const issued = keys.issue({ + owner_email: "dev@example.com", + label: "main", + }); + expect(issued.api_key).toMatch(/^tnm_[A-Za-z0-9_-]{32}$/); + expect(issued.quota_bots).toBe(1000); + expect(issued.quota_picks_per_hour).toBe(100_000); + expect(issued.owner_email).toBe("dev@example.com"); + }); + + it("lifts the quota to 10,000 bots for .edu emails", () => { + const issued = keys.issue({ + owner_email: "alice@cs.stanford.edu", + }); + expect(issued.quota_bots).toBe(10_000); + }); + + it("lifts the quota for .ac.uk emails", () => { + const issued = keys.issue({ owner_email: "researcher@cl.cam.ac.uk" }); + expect(issued.quota_bots).toBe(10_000); + }); + + it("lifts the quota for .ac.nz emails", () => { + const issued = keys.issue({ owner_email: "tim@auckland.ac.nz" }); + expect(issued.quota_bots).toBe(10_000); + }); + + it("lifts the quota for .edu.au emails", () => { + const issued = keys.issue({ owner_email: "x@unimelb.edu.au" }); + expect(issued.quota_bots).toBe(10_000); + }); + + it("lifts the quota for .ac.za emails", () => { + const issued = keys.issue({ owner_email: "y@uct.ac.za" }); + expect(issued.quota_bots).toBe(10_000); + }); + + it("lifts the quota for .edu.cn emails", () => { + const issued = keys.issue({ owner_email: "z@tsinghua.edu.cn" }); + expect(issued.quota_bots).toBe(10_000); + }); + + it("lifts the quota for .ac.jp emails", () => { + const issued = keys.issue({ owner_email: "a@u-tokyo.ac.jp" }); + expect(issued.quota_bots).toBe(10_000); + }); + + it("is case-insensitive when checking academic suffixes", () => { + const issued = keys.issue({ owner_email: "MIXED@Stanford.EDU" }); + expect(issued.quota_bots).toBe(10_000); + }); + + it("returns the plaintext key only at issuance; subsequent lookup uses hash", () => { + const { api_key, owner_email } = keys.issue({ + owner_email: "dev@example.com", + }); + const found = keys.lookupByPlain(api_key); + expect(found).not.toBeNull(); + expect(found!.owner_email).toBe(owner_email); + }); + + it("returns null when looking up an unknown plaintext key", () => { + expect(keys.lookupByPlain("tnm_does_not_exist")).toBeNull(); + }); + + it("returns null after revocation", () => { + const { api_key } = keys.issue({ owner_email: "dev@example.com" }); + expect(keys.lookupByPlain(api_key)).not.toBeNull(); + keys.revoke(api_key); + expect(keys.lookupByPlain(api_key)).toBeNull(); + }); + + it("does not store the plaintext key anywhere", () => { + const { api_key } = keys.issue({ owner_email: "dev@example.com" }); + const row = store.db + .prepare(`SELECT * FROM api_key LIMIT 1`) + .get() as Record; + // Walk every column and check no value equals the plaintext key. + for (const v of Object.values(row)) { + expect(typeof v === "string" ? v.includes(api_key.slice(4)) : false).toBe( + false, + ); + } + }); +}); diff --git a/apps/game/tests/store-bot-arena-migration.test.ts b/apps/game/tests/store-bot-arena-migration.test.ts new file mode 100644 index 00000000..14573d91 --- /dev/null +++ b/apps/game/tests/store-bot-arena-migration.test.ts @@ -0,0 +1,78 @@ +/** + * Bot Arena migration smoke test. + * + * Ensures migration 0013 lands the new columns + tables required by + * the Phase 1 Open Bot Arena and the Phase 2 federation hooks. + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §8.1, §15.6 + */ +import { resolve } from "node:path"; +import { dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +import { describe, it, expect } from "vitest"; + +import { GameStore } from "../src/store/db.js"; + +const here = dirname(fileURLToPath(import.meta.url)); +const MIGRATIONS_DIR = resolve(here, "..", "migrations"); + +describe("bot arena migration (0013)", () => { + it("creates bot_owner, api_key, quota_window, federated_node, federated_leaderboard_snapshot", () => { + const store = new GameStore({ + dbPath: ":memory:", + migrationsDir: MIGRATIONS_DIR, + }); + const db = store.db; + const tables = db + .prepare(`SELECT name FROM sqlite_master WHERE type='table'`) + .all() + .map((r) => (r as { name: string }).name); + expect(tables).toContain("bot_owner"); + expect(tables).toContain("api_key"); + expect(tables).toContain("quota_window"); + expect(tables).toContain("federated_node"); + expect(tables).toContain("federated_leaderboard_snapshot"); + store.close(); + }); + + it("adds is_bot to users and committed_at_utc to brackets", () => { + const store = new GameStore({ + dbPath: ":memory:", + migrationsDir: MIGRATIONS_DIR, + }); + const db = store.db; + const userCols = db + .prepare(`PRAGMA table_info(users)`) + .all() + .map((r) => (r as { name: string }).name); + expect(userCols).toContain("is_bot"); + + const bracketCols = db + .prepare(`PRAGMA table_info(brackets)`) + .all() + .map((r) => (r as { name: string }).name); + expect(bracketCols).toContain("committed_at_utc"); + store.close(); + }); + + it("creates the supporting indices", () => { + const store = new GameStore({ + dbPath: ":memory:", + migrationsDir: MIGRATIONS_DIR, + }); + const db = store.db; + const indices = db + .prepare(`SELECT name FROM sqlite_master WHERE type='index'`) + .all() + .map((r) => (r as { name: string }).name); + expect(indices).toContain("idx_users_is_bot"); + expect(indices).toContain("idx_brackets_committed_at"); + expect(indices).toContain("idx_bot_owner_email"); + expect(indices).toContain("idx_bot_owner_key"); + expect(indices).toContain("idx_api_key_owner"); + expect(indices).toContain("idx_federated_node_owner"); + expect(indices).toContain("idx_fed_snapshot_match"); + store.close(); + }); +}); diff --git a/apps/game/tests/store-bot-owners.test.ts b/apps/game/tests/store-bot-owners.test.ts new file mode 100644 index 00000000..d2ce381f --- /dev/null +++ b/apps/game/tests/store-bot-owners.test.ts @@ -0,0 +1,119 @@ +/** + * BotOwnerStore , ownership claims, per-key counts, ownership checks. + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §6.4, §7.2 + */ +import { resolve, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +import { describe, it, expect, beforeEach, afterEach } from "vitest"; + +import { GameStore } from "../src/store/db.js"; +import { ApiKeyStore } from "../src/store/api-keys.js"; +import { BotOwnerStore } from "../src/store/bot-owners.js"; + +const here = dirname(fileURLToPath(import.meta.url)); +const MIGRATIONS_DIR = resolve(here, "..", "migrations"); + +let store: GameStore; +let keys: ApiKeyStore; +let owners: BotOwnerStore; + +beforeEach(() => { + store = new GameStore({ dbPath: ":memory:", migrationsDir: MIGRATIONS_DIR }); + keys = new ApiKeyStore(store.db); + owners = new BotOwnerStore(store.db); + store.db + .prepare(`INSERT INTO users (id, created_at, is_bot) VALUES (?, 1, 1)`) + .run("bot_a"); + store.db + .prepare(`INSERT INTO users (id, created_at, is_bot) VALUES (?, 1, 1)`) + .run("bot_b"); + store.db + .prepare(`INSERT INTO users (id, created_at, is_bot) VALUES (?, 1, 1)`) + .run("bot_c"); +}); + +afterEach(() => store.close()); + +describe("BotOwnerStore", () => { + it("records ownership and counts bots per key", () => { + const issued = keys.issue({ owner_email: "dev@example.com" }); + owners.claim({ + bot_id: "bot_a", + api_key_hash: issued.key_hash, + owner_email: issued.owner_email, + }); + owners.claim({ + bot_id: "bot_b", + api_key_hash: issued.key_hash, + owner_email: issued.owner_email, + }); + expect(owners.countByApiKey(issued.key_hash)).toBe(2); + }); + + it("ownedBotIds returns the claimed bots in stable order", () => { + const issued = keys.issue({ owner_email: "dev@example.com" }); + owners.claim({ + bot_id: "bot_a", + api_key_hash: issued.key_hash, + owner_email: issued.owner_email, + now: 100, + }); + owners.claim({ + bot_id: "bot_b", + api_key_hash: issued.key_hash, + owner_email: issued.owner_email, + now: 200, + }); + expect(owners.ownedBotIds(issued.key_hash)).toEqual(["bot_a", "bot_b"]); + }); + + it("isOwner is true for claimed bots, false otherwise", () => { + const issued = keys.issue({ owner_email: "dev@example.com" }); + owners.claim({ + bot_id: "bot_a", + api_key_hash: issued.key_hash, + owner_email: issued.owner_email, + }); + expect(owners.isOwner(issued.key_hash, "bot_a")).toBe(true); + expect(owners.isOwner(issued.key_hash, "bot_b")).toBe(false); + }); + + it("claim is idempotent on the same bot_id", () => { + const issued = keys.issue({ owner_email: "dev@example.com" }); + owners.claim({ + bot_id: "bot_a", + api_key_hash: issued.key_hash, + owner_email: issued.owner_email, + }); + owners.claim({ + bot_id: "bot_a", + api_key_hash: issued.key_hash, + owner_email: issued.owner_email, + }); + expect(owners.countByApiKey(issued.key_hash)).toBe(1); + }); + + it("counts bots only owned by the queried key", () => { + const k1 = keys.issue({ owner_email: "a@example.com" }); + const k2 = keys.issue({ owner_email: "b@example.com" }); + owners.claim({ + bot_id: "bot_a", + api_key_hash: k1.key_hash, + owner_email: k1.owner_email, + }); + owners.claim({ + bot_id: "bot_b", + api_key_hash: k2.key_hash, + owner_email: k2.owner_email, + }); + owners.claim({ + bot_id: "bot_c", + api_key_hash: k2.key_hash, + owner_email: k2.owner_email, + }); + expect(owners.countByApiKey(k1.key_hash)).toBe(1); + expect(owners.countByApiKey(k2.key_hash)).toBe(2); + }); +}); diff --git a/apps/game/tests/store-federated-nodes.test.ts b/apps/game/tests/store-federated-nodes.test.ts new file mode 100644 index 00000000..c2ebd9c2 --- /dev/null +++ b/apps/game/tests/store-federated-nodes.test.ts @@ -0,0 +1,196 @@ +/** + * FederatedNodeStore , Phase 2 federation registry + per-match + * aggregate snapshots. + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §15.2 + */ +import { resolve, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +import { describe, it, expect, beforeEach, afterEach } from "vitest"; + +import { GameStore } from "../src/store/db.js"; +import { + FederatedNodeStore, + type FederatedNodeRow, +} from "../src/store/federated-nodes.js"; + +const here = dirname(fileURLToPath(import.meta.url)); +const MIGRATIONS_DIR = resolve(here, "..", "migrations"); + +let store: GameStore; +let nodes: FederatedNodeStore; + +beforeEach(() => { + store = new GameStore({ dbPath: ":memory:", migrationsDir: MIGRATIONS_DIR }); + nodes = new FederatedNodeStore(store.db); +}); + +afterEach(() => store.close()); + +describe("FederatedNodeStore , registry", () => { + it("registers a node and returns the row", () => { + const row = nodes.register({ + node_id: "n_alpha", + owner_email: "ops@example.com", + owner_api_key_hash: "hash_alpha", + public_url: "https://alpha.example.com", + label: "Alpha Lab swarm", + now: 1000, + }); + expect(row.node_id).toBe("n_alpha"); + expect(row.public_url).toBe("https://alpha.example.com"); + expect(row.registered_at).toBe(1000); + }); + + it("getByNodeId returns null on miss", () => { + expect(nodes.getByNodeId("nope")).toBeNull(); + }); + + it("touch updates last_seen_at without changing other fields", () => { + nodes.register({ + node_id: "n_alpha", + owner_email: "ops@example.com", + owner_api_key_hash: "hash_alpha", + public_url: "https://alpha.example.com", + now: 1000, + }); + nodes.touch("n_alpha", 2500); + const row = nodes.getByNodeId("n_alpha") as FederatedNodeRow; + expect(row.last_seen_at).toBe(2500); + expect(row.public_url).toBe("https://alpha.example.com"); + }); + + it("getByApiKeyHash returns nodes owned by that key", () => { + nodes.register({ + node_id: "n_alpha", + owner_email: "ops@example.com", + owner_api_key_hash: "hash_one", + public_url: "https://a.example.com", + now: 1000, + }); + nodes.register({ + node_id: "n_beta", + owner_email: "ops@example.com", + owner_api_key_hash: "hash_one", + public_url: "https://b.example.com", + now: 1100, + }); + nodes.register({ + node_id: "n_gamma", + owner_email: "other@example.com", + owner_api_key_hash: "hash_two", + public_url: "https://c.example.com", + now: 1200, + }); + expect(nodes.getByApiKeyHash("hash_one").map((r) => r.node_id)).toEqual([ + "n_alpha", + "n_beta", + ]); + expect(nodes.getByApiKeyHash("hash_two").map((r) => r.node_id)).toEqual([ + "n_gamma", + ]); + }); +}); + +describe("FederatedNodeStore , snapshots", () => { + beforeEach(() => { + nodes.register({ + node_id: "n_alpha", + owner_email: "ops@example.com", + owner_api_key_hash: "hash_alpha", + public_url: "https://alpha.example.com", + now: 1000, + }); + }); + + it("commits a pre-kickoff merkle root", () => { + nodes.commit({ + node_id: "n_alpha", + match_id: "1", + merkle_root: "a".repeat(64), + kickoff_at: 5000, + bot_count: 12_345, + now: 1500, + }); + const row = nodes.getSnapshot("n_alpha", "1"); + expect(row?.merkle_root).toBe("a".repeat(64)); + expect(row?.kickoff_at).toBe(5000); + expect(row?.total_bots).toBe(12_345); + expect(row?.bots_correct).toBeNull(); + expect(row?.submitted_at).toBe(1500); + }); + + it("records a post-match leaderboard report", () => { + nodes.commit({ + node_id: "n_alpha", + match_id: "1", + merkle_root: "a".repeat(64), + kickoff_at: 5000, + bot_count: 1000, + now: 1500, + }); + nodes.reportLeaderboard({ + node_id: "n_alpha", + match_id: "1", + total_bots: 1000, + bots_correct: 612, + bots_still_perfect: 612, + top: [ + { bot_id: "bot_a", score: 1 }, + { bot_id: "bot_b", score: 1 }, + ], + now: 6000, + }); + const row = nodes.getSnapshot("n_alpha", "1"); + expect(row?.bots_correct).toBe(612); + expect(row?.bots_still_perfect).toBe(612); + expect(row?.merkle_root).toBe("a".repeat(64)); + expect(JSON.parse(row!.top_json_blob!)).toHaveLength(2); + }); + + it("reportLeaderboard without prior commit still works (Phase 2 late join)", () => { + nodes.reportLeaderboard({ + node_id: "n_alpha", + match_id: "2", + total_bots: 500, + bots_correct: 300, + bots_still_perfect: 300, + top: [], + now: 7000, + }); + const row = nodes.getSnapshot("n_alpha", "2"); + expect(row?.total_bots).toBe(500); + expect(row?.merkle_root).toBeNull(); + }); + + it("listSnapshotsForMatch returns rows from every node", () => { + nodes.register({ + node_id: "n_beta", + owner_email: "ops@example.com", + owner_api_key_hash: "hash_beta", + public_url: "https://beta.example.com", + now: 1000, + }); + nodes.reportLeaderboard({ + node_id: "n_alpha", + match_id: "1", + total_bots: 10, + bots_correct: 5, + bots_still_perfect: 5, + top: [{ bot_id: "bot_a", score: 1 }], + now: 6000, + }); + nodes.reportLeaderboard({ + node_id: "n_beta", + match_id: "1", + total_bots: 20, + bots_correct: 11, + bots_still_perfect: 11, + top: [{ bot_id: "bot_x", score: 1 }], + now: 6100, + }); + const rows = nodes.listSnapshotsForMatch("1"); + expect(rows.map((r) => r.node_id).sort()).toEqual(["n_alpha", "n_beta"]); + }); +}); diff --git a/apps/game/tests/store-quotas.test.ts b/apps/game/tests/store-quotas.test.ts new file mode 100644 index 00000000..4e165b9b --- /dev/null +++ b/apps/game/tests/store-quotas.test.ts @@ -0,0 +1,77 @@ +/** + * QuotaStore , sliding-hour pick quota ledger. + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §6.4 + */ +import { resolve, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +import { describe, it, expect, beforeEach, afterEach } from "vitest"; + +import { GameStore } from "../src/store/db.js"; +import { QuotaStore } from "../src/store/quotas.js"; + +const here = dirname(fileURLToPath(import.meta.url)); +const MIGRATIONS_DIR = resolve(here, "..", "migrations"); + +let store: GameStore; +let q: QuotaStore; + +beforeEach(() => { + store = new GameStore({ dbPath: ":memory:", migrationsDir: MIGRATIONS_DIR }); + q = new QuotaStore(store.db); +}); + +afterEach(() => store.close()); + +describe("QuotaStore", () => { + it("starts at 0 used for an unseen key", () => { + expect(q.usedThisHour("k1")).toBe(0); + }); + + it("accumulates picks in the current hour window", () => { + q.consume("k1", 50); + q.consume("k1", 50); + expect(q.usedThisHour("k1")).toBe(100); + }); + + it("tracks separate keys independently", () => { + q.consume("k1", 50); + q.consume("k2", 25); + expect(q.usedThisHour("k1")).toBe(50); + expect(q.usedThisHour("k2")).toBe(25); + }); + + it("tryConsume accepts requests under the cap", () => { + expect(q.tryConsume("k1", 100, 200)).toBe(true); + expect(q.tryConsume("k1", 99, 200)).toBe(true); + expect(q.usedThisHour("k1")).toBe(199); + }); + + it("tryConsume rejects when total would exceed the cap", () => { + expect(q.tryConsume("k1", 100, 100)).toBe(true); + expect(q.tryConsume("k1", 1, 100)).toBe(false); + expect(q.usedThisHour("k1")).toBe(100); + }); + + it("rejects requests that exceed the cap on their own", () => { + expect(q.tryConsume("k1", 200, 100)).toBe(false); + expect(q.usedThisHour("k1")).toBe(0); + }); + + it("clamps the window to the floor of the current hour", () => { + const at = 1_717_804_800_000; // arbitrary fixed instant + q.consumeAt("k1", 10, at); + q.consumeAt("k1", 10, at + 60_000); + q.consumeAt("k1", 10, at + 59 * 60_000); + expect(q.usedThisHourAt("k1", at)).toBe(30); + }); + + it("new hour starts a fresh window", () => { + const at = 1_717_804_800_000; + q.consumeAt("k1", 50, at); + expect(q.usedThisHourAt("k1", at)).toBe(50); + // Next hour window has zero usage. + expect(q.usedThisHourAt("k1", at + 3_600_000)).toBe(0); + }); +}); diff --git a/apps/game/tests/store-wired.test.ts b/apps/game/tests/store-wired.test.ts new file mode 100644 index 00000000..498b6d27 --- /dev/null +++ b/apps/game/tests/store-wired.test.ts @@ -0,0 +1,78 @@ +/** + * GameStore wiring smoke test , the Bot Arena DAOs land on the store + * and the scope-filtered leaderboard read returns what you'd expect. + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §5, §6 + */ +import { resolve, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +import { describe, it, expect, beforeEach, afterEach } from "vitest"; + +import { GameStore } from "../src/store/db.js"; + +const here = dirname(fileURLToPath(import.meta.url)); +const MIGRATIONS_DIR = resolve(here, "..", "migrations"); + +let store: GameStore; +beforeEach(() => { + store = new GameStore({ dbPath: ":memory:", migrationsDir: MIGRATIONS_DIR }); +}); +afterEach(() => store.close()); + +describe("GameStore , wired DAOs", () => { + it("exposes apiKeys, botOwners, quotas, federatedNodes", () => { + expect(store.apiKeys).toBeDefined(); + expect(store.botOwners).toBeDefined(); + expect(store.quotas).toBeDefined(); + expect(store.federatedNodes).toBeDefined(); + }); + + it("apiKeys.issue + lookupByPlain round-trips", () => { + const issued = store.apiKeys.issue({ owner_email: "dev@example.com" }); + expect(store.apiKeys.lookupByPlain(issued.api_key)).not.toBeNull(); + }); +}); + +describe("GameStore.topNByScope", () => { + beforeEach(() => { + const now = Date.now(); + for (const [id, is_bot, score] of [ + ["u_h1", 0, 50], + ["u_h2", 0, 40], + ["u_h3", 0, 30], + ["bot_b1", 1, 70], + ["bot_b2", 1, 60], + ] as Array<[string, 0 | 1, number]>) { + store.db + .prepare( + `INSERT INTO users (id, created_at, is_bot) VALUES (?, ?, ?)`, + ) + .run(id, now, is_bot); + store.db + .prepare( + `INSERT INTO brackets + (id, user_id, tournament_id, payload_json, locked_at, + score_total, share_guid) + VALUES (?, ?, 'fifa-wc-2026', '{}', ?, ?, ?)`, + ) + .run(`${id}_b`, id, now, score, id.slice(0, 8)); + } + }); + + it("humans scope returns only is_bot=0 users", () => { + const rows = store.topNByScope("fifa-wc-2026", "humans", 10); + expect(rows.map((r) => r.user_id)).toEqual(["u_h1", "u_h2", "u_h3"]); + }); + + it("bots scope returns only is_bot=1 users", () => { + const rows = store.topNByScope("fifa-wc-2026", "bots", 10); + expect(rows.map((r) => r.user_id)).toEqual(["bot_b1", "bot_b2"]); + }); + + it("all scope returns everyone, top score first", () => { + const rows = store.topNByScope("fifa-wc-2026", "all", 10); + expect(rows[0]?.user_id).toBe("bot_b1"); + expect(rows.length).toBe(5); + }); +}); diff --git a/apps/operator-swarm/.env.example b/apps/operator-swarm/.env.example new file mode 100644 index 00000000..72e4ef41 --- /dev/null +++ b/apps/operator-swarm/.env.example @@ -0,0 +1,47 @@ +# ============================================================================= +# @tournamental/operator-swarm: environment template +# +# Copy to `.env` on the server, fill in real values, then `pnpm run register` +# followed by `pnpm run start`. NEVER commit `.env`. +# +# This file ships safe defaults sized for Tim's 1M-bot demo node. Smaller +# operators should drop BOT_COUNT to fit their box (rule of thumb: ~10 GB +# RAM headroom at 1M bots; scale roughly linearly). +# ============================================================================= + +# --- central API --- +# Where the bot-node submits commitments and aggregates. Defaults to prod; +# point at https://api-dev.tournamental.com for staging. +TOURNAMENTAL_API_BASE_URL=https://api.tournamental.com + +# --- operator identity --- +# Contact email used during /v1/nodes/register. The central server emails +# audit-failure alerts here, so it must be a real mailbox. +OPERATOR_EMAIL=info@tournamental.com + +# Human-readable label that shows up on the public federated leaderboard +# under the "node" column. Pick something distinctive. +OPERATOR_NODE_LABEL=tim-1m-demo + +# --- swarm sizing --- +# How many bots this node operates. The full Phase-2 cap is 10^9; 1M is the +# launch-day demo. Each bot is one row in the local commitments DB. +BOT_COUNT=1000000 + +# Pick strategy passed straight through to the bot-node runtime. Supported +# values are documented in @tournamental/bot-node; "chalk" is the baseline. +# Other options once A3 ships them: odds-following, kelly, ensemble. +STRATEGY=chalk + +# --- runtime --- +# pino-style level. Use "debug" only when actively investigating, otherwise +# "info" keeps the PM2 log volume sane at 1M bots. +LOG_LEVEL=info + +# Local HTTP port the bot-node exposes /stats and /health on. The +# health-check script and the central monitoring probe both hit this. +BOT_NODE_STATS_PORT=4811 + +# Where credentials land after `pnpm run register`. Keep this on a disk +# the runtime user owns; chmod 600 the file after first write. +OPERATOR_CREDENTIALS_PATH=~/.tournamental/operator.json diff --git a/apps/operator-swarm/.gitignore b/apps/operator-swarm/.gitignore new file mode 100644 index 00000000..7b62f193 --- /dev/null +++ b/apps/operator-swarm/.gitignore @@ -0,0 +1,9 @@ +# PM2 log output created at runtime by ecosystem.config.cjs. +logs/ + +# Real env values live in the deployment secret store, never in git. +.env +.env.local + +# PM2 dump file, if pm2 save is run from this directory. +dump.pm2 diff --git a/apps/operator-swarm/README.md b/apps/operator-swarm/README.md new file mode 100644 index 00000000..8adabe14 --- /dev/null +++ b/apps/operator-swarm/README.md @@ -0,0 +1,204 @@ +# @tournamental/operator-swarm + +PM2 and ops wrapper for running a federated Tournamental Bot Node at scale. + +This app does not implement any bot logic itself. It wraps the +`tournamental-bot-node` CLI shipped by `@tournamental/bot-node` with the +production concerns a server admin actually needs: PM2 process management, +auto-restart, log rotation, credentials lifecycle, and a health-check probe. + +Phase 1 use case: Tim runs one node on the Tournamental server itself, +operating roughly one million bots, so the public Bots leaderboard tab has +real activity from day one of the FIFA World Cup 2026. Phase 2 onwards, this +same app is the reference deployment external operators copy from. + +## At a glance + +| File | Purpose | +| -------------------------- | ------------------------------------------------------- | +| `.env.example` | All knobs, with sensible defaults for the 1M-bot demo. | +| `scripts/register.sh` | One-shot operator registration with the central API. | +| `ecosystem.config.cjs` | PM2 config, log paths, heap sizing, restart policy. | +| `scripts/health-check.sh` | Curls the local `/stats` endpoint and reports status. | + +## Prerequisites + +- Node 20+ and pnpm 9+ on the host. +- PM2 installed globally or available via `pnpm exec` (the package pulls in + PM2 as a devDependency, so `pnpm install` in the repo root is enough). +- The host user (here, `0800tim`) owns `~/.tournamental/` and the app + directory. +- `@tournamental/bot-node` already built in the workspace. Run + `pnpm --filter @tournamental/bot-node build` if in doubt. +- Outbound HTTPS to `api.tournamental.com` (or wherever + `TOURNAMENTAL_API_BASE_URL` points). + +## First-time deploy on the Tournamental server + +These steps are written for the `0800tim` user on the prod box. Adjust paths +for your environment. + +```bash +# 1. Pull the latest main and install the workspace. +cd /home/0800tim/tournamental +git fetch origin +git checkout main +git pull +pnpm install + +# 2. Copy the env template and fill it in. +cd apps/operator-swarm +cp .env.example .env +$EDITOR .env +# - confirm OPERATOR_EMAIL=info@tournamental.com +# - keep OPERATOR_NODE_LABEL=tim-1m-demo (this is what shows on the +# federated leaderboard column "node") +# - confirm BOT_COUNT=1000000 (drop to 100000 for the smoke test first) +# - leave STRATEGY=chalk for launch, swap later + +# 3. Register the node with the central API. +pnpm run register +# Writes credentials to ~/.tournamental/operator.json (chmod 600). +# Idempotent: rerunning does nothing if credentials already exist. + +# 4. Start the swarm under PM2. +pnpm run start + +# 5. Confirm it is alive. +pnpm run status +pnpm run health + +# 6. Survive a reboot. Run pm2 startup once and save the process list. +pm2 startup systemd -u 0800tim --hp /home/0800tim +pm2 save +``` + +After this, the bot node runs as a PM2-managed process and restarts on crash +or reboot. The federated leaderboard on +`https://play.tournamental.com/bots` lights up within a few minutes once the +first match commitment lands. + +## Sizing guidance + +The headline number for the launch demo is **1,000,000 bots**. The rest of +this section is the operator-facing version of what the design doc spells +out in detail. + +| Bots | Approx peak heap | Disk for local DB | Notes | +| ---------- | ---------------- | ----------------- | ------------------------------------ | +| 10,000 | ~150 MB | ~50 MB | Cheap laptop, useful for soak tests. | +| 100,000 | ~1.2 GB | ~500 MB | Small VPS box. | +| 1,000,000 | ~10 GB | ~6 GB | Tim's launch-day demo node. | +| 10,000,000 | ~95 GB | ~60 GB | Single-box ceiling, needs swap care. | +| 1,000,000,000 | shard across many nodes | shard | Aspirational Phase 2 federation. | + +Heap budget for the 1M-bot demo is set to 12 GB in `ecosystem.config.cjs` +(`--max-old-space-size=12288`), which gives roughly 2 GB headroom over the +observed peak. Bump to 24576 if the node ever OOM-kills under sustained +match traffic. + +For larger fleets, shard horizontally: run multiple `operator-swarm` +instances, each with its own `OPERATOR_NODE_LABEL`, each registered as a +distinct node. The federated protocol expects this; do not try to push a +single PM2 process past about 2M bots. + +Disk-wise, the local commitments DB grows ~6 GB per million bots over a +full 104-match tournament. Put `~/.tournamental/` on a disk with at least +20 GB free for the demo node. + +## Operating the node + +```bash +# Live status (PID, restarts, CPU, RSS). +pnpm run status + +# Tail logs (ctrl-C to exit). +pnpm run logs + +# Quick local health probe (also: --json, --quiet). +pnpm run health + +# Reload after env changes (zero-downtime). +pnpm run reload + +# Stop without deleting from PM2. +pnpm run stop + +# Fully remove from PM2 (does not delete credentials). +pnpm run delete +``` + +Logs land in `apps/operator-swarm/logs/`. Two files, +`bot-node.out.log` and `bot-node.err.log`, both rotated by +`pm2-logrotate` once installed: + +```bash +pm2 install pm2-logrotate +pm2 set pm2-logrotate:max_size 100M +pm2 set pm2-logrotate:retain 14 +``` + +The bot-node also exposes `/stats` on `127.0.0.1:${BOT_NODE_STATS_PORT}` +(default 4811). Bind to localhost only, expose via your reverse proxy if +you want a public health page. The `health-check.sh` script reads this +endpoint and surfaces: + +- `bot_count` (how many bots this node operates) +- `bots_still_perfect` (how many bots have hit every match so far) +- `last_commit_at` (UTC timestamp of the last merkle commit) +- `last_commit_match` (the match ID that triggered it) +- `score_total` (sum across all bots, for the leaderboard sanity check) +- `uptime_seconds` (process uptime) + +Wire it into Cloudflare healthchecks, cron, or systemd timers as your +monitoring stack requires. Exit codes: 0 healthy, 1 stale or unreachable, +2 missing tooling on the host. + +## Monitoring at the swarm level + +PM2 only sees process-level metrics. For the bot-level view (commit +cadence, perfect-bot survivors, score totals) the source of truth is the +`/stats` endpoint and, behind it, the central federated leaderboard on +`https://play.tournamental.com/bots`. Cross-check both during the launch +weekend. + +If `bots_still_perfect` stays at the same value across consecutive +matches and no public match ended in a chalk upset, that is almost +certainly a bug in the strategy, not a heroic prediction streak. + +## Troubleshooting + +- **Registration fails with 401**: check `OPERATOR_EMAIL` matches an active + contact and the central API is reachable. Delete + `~/.tournamental/operator.json` before retrying. +- **PM2 reports continuous restarts**: tail `logs/bot-node.err.log`. The + usual suspect is a missing credentials file or an exhausted heap; both + are visible in the first 50 lines. +- **`/stats` returns 200 but `last_commit_at` never advances**: the local + worker queue is wedged. `pnpm run reload` first; if that does not help, + the central API may be rate-limiting your `node_id`, in which case look + for `429` lines in the err log. +- **OOM kill at 1M bots**: bump `--max-old-space-size` in + `ecosystem.config.cjs` and `pnpm run reload`. If the box itself is + swapping, shard to two `OPERATOR_NODE_LABEL` instances instead. + +## Security notes + +- Credentials in `~/.tournamental/operator.json` are sensitive. The script + chmods them to 600 on write; do not relax this. +- Never commit `.env`. The repo `.gitignore` already excludes it; the + template `.env.example` is the only file in this app that goes to git. +- The bot-node `/stats` endpoint MUST stay bound to `127.0.0.1`. Exposing + raw stats publicly leaks score deltas in real time, which competing + operators can game. +- The audit constraints in the design doc (pre-kickoff merkle commit, + OTS anchoring, independent verification) are enforced by the central + API. This wrapper does not loosen any of them; it only schedules the + work that the bot-node performs. + +## References + +- Design: `docs/superpowers/specs/2026-06-07-bot-arena-design.md` (especially + Section 15, "Phase 2 design preview: federated compute network"). +- Plan: `docs/superpowers/plans/2026-06-07-bot-arena-phase-1.md`. +- The underlying runtime: `packages/bot-node` (CLI: `tournamental-bot-node`). diff --git a/apps/operator-swarm/ecosystem.config.cjs b/apps/operator-swarm/ecosystem.config.cjs new file mode 100644 index 00000000..20171a33 --- /dev/null +++ b/apps/operator-swarm/ecosystem.config.cjs @@ -0,0 +1,125 @@ +// ============================================================================= +// PM2 ecosystem for @tournamental/operator-swarm. +// +// Loads .env from this app's directory, then launches the @tournamental/bot-node +// CLI under PM2 with auto-restart, capped log files, and a heap big enough for +// the 1M-bot demo node. +// +// Run with: +// pnpm --filter @tournamental/operator-swarm run start +// +// Inspect: +// pm2 status tournamental-bot-node +// pm2 logs tournamental-bot-node +// +// Persist across reboots (server admin runs this once after first start): +// pm2 startup +// pm2 save +// ============================================================================= + +const path = require("node:path"); +const fs = require("node:fs"); + +const APP_DIR = __dirname; +const ENV_FILE = path.join(APP_DIR, ".env"); + +// Lightweight .env loader so PM2 picks up values without requiring dotenv at +// the wrapper layer. The bot-node itself may also read process.env directly. +const env = {}; +if (fs.existsSync(ENV_FILE)) { + const raw = fs.readFileSync(ENV_FILE, "utf8"); + for (const line of raw.split("\n")) { + const trimmed = line.trim(); + if (!trimmed || trimmed.startsWith("#")) continue; + const eq = trimmed.indexOf("="); + if (eq === -1) continue; + const key = trimmed.slice(0, eq).trim(); + let value = trimmed.slice(eq + 1).trim(); + if ( + (value.startsWith('"') && value.endsWith('"')) || + (value.startsWith("'") && value.endsWith("'")) + ) { + value = value.slice(1, -1); + } + env[key] = value; + } +} + +// Defaults aligned with .env.example. Operator-supplied values win. +const TOURNAMENTAL_API_BASE_URL = + env.TOURNAMENTAL_API_BASE_URL || "https://api.tournamental.com"; +const BOT_COUNT = env.BOT_COUNT || "1000000"; +const STRATEGY = env.STRATEGY || "chalk"; +const LOG_LEVEL = env.LOG_LEVEL || "info"; +const BOT_NODE_STATS_PORT = env.BOT_NODE_STATS_PORT || "4811"; +const OPERATOR_NODE_LABEL = env.OPERATOR_NODE_LABEL || "tim-1m-demo"; + +// Resolve credentials path with tilde expansion so the bot-node can find it. +const HOME = process.env.HOME || "/home/0800tim"; +const rawCredsPath = + env.OPERATOR_CREDENTIALS_PATH || `${HOME}/.tournamental/operator.json`; +const OPERATOR_CREDENTIALS_PATH = rawCredsPath.startsWith("~/") + ? path.join(HOME, rawCredsPath.slice(2)) + : rawCredsPath; + +const LOG_DIR = path.join(APP_DIR, "logs"); +if (!fs.existsSync(LOG_DIR)) { + fs.mkdirSync(LOG_DIR, { recursive: true }); +} + +module.exports = { + apps: [ + { + name: "tournamental-bot-node", + cwd: APP_DIR, + script: "tournamental-bot-node", + args: [ + "run", + `--bots=${BOT_COUNT}`, + `--strategy=${STRATEGY}`, + `--stats-port=${BOT_NODE_STATS_PORT}`, + `--credentials=${OPERATOR_CREDENTIALS_PATH}`, + `--api-base-url=${TOURNAMENTAL_API_BASE_URL}`, + `--label=${OPERATOR_NODE_LABEL}`, + ], + // pnpm hoists the bin into node_modules/.bin, which PM2 picks up via + // the interpreter resolver. If the binary is not on PATH on the host, + // swap to `interpreter: "pnpm"` and prepend `["exec", "tournamental-bot-node"]`. + interpreter: "none", + exec_mode: "fork", + instances: 1, + autorestart: true, + // If the node crashes more than 5 times within 10s, PM2 stops trying. + // That window is intentional: 1M-bot startup briefly spikes RAM, and + // we want PM2 to give up loudly rather than thrash the box. + max_restarts: 5, + min_uptime: "30s", + restart_delay: 5000, + kill_timeout: 30000, + wait_ready: false, + // 12 GB heap covers the 1M-bot demo with ~2 GB headroom. Drop to + // --max-old-space-size=2048 for a 100k-bot node, or raise to 24576 + // for a 2M-bot node. node.js needs the flag, not a runtime config. + node_args: ["--max-old-space-size=12288"], + env: { + NODE_ENV: "production", + TOURNAMENTAL_API_BASE_URL, + OPERATOR_NODE_LABEL, + OPERATOR_CREDENTIALS_PATH, + BOT_COUNT, + STRATEGY, + LOG_LEVEL, + BOT_NODE_STATS_PORT, + }, + out_file: path.join(LOG_DIR, "bot-node.out.log"), + error_file: path.join(LOG_DIR, "bot-node.err.log"), + merge_logs: true, + log_date_format: "YYYY-MM-DD HH:mm:ss Z", + // Rotate via pm2-logrotate (installed once on the host: + // pm2 install pm2-logrotate + // pm2 set pm2-logrotate:max_size 100M + // pm2 set pm2-logrotate:retain 14 + // ). PM2 then keeps 14 days of 100 MB chunks. + }, + ], +}; diff --git a/apps/operator-swarm/package.json b/apps/operator-swarm/package.json new file mode 100644 index 00000000..5d3ae619 --- /dev/null +++ b/apps/operator-swarm/package.json @@ -0,0 +1,38 @@ +{ + "name": "@tournamental/operator-swarm", + "version": "0.1.0", + "private": true, + "description": "PM2 + ops wrapper for Tim's 1M-bot federated swarm node, riding on top of @tournamental/bot-node for the Open Bot Arena.", + "type": "module", + "scripts": { + "register": "bash scripts/register.sh", + "start": "pm2 start ecosystem.config.cjs", + "stop": "pm2 stop ecosystem.config.cjs", + "restart": "pm2 restart ecosystem.config.cjs", + "reload": "pm2 reload ecosystem.config.cjs", + "status": "pm2 status tournamental-bot-node", + "logs": "pm2 logs tournamental-bot-node", + "health": "bash scripts/health-check.sh", + "save": "pm2 save", + "delete": "pm2 delete ecosystem.config.cjs", + "lint": "exit 0", + "test": "exit 0", + "typecheck": "exit 0", + "build": "exit 0" + }, + "dependencies": { + "@tournamental/bot-node": "workspace:*" + }, + "devDependencies": { + "pm2": "^5.4.2" + }, + "engines": { + "node": ">=20" + }, + "license": "Apache-2.0", + "repository": { + "type": "git", + "url": "https://github.com/0800tim/tournamental.git", + "directory": "apps/operator-swarm" + } +} diff --git a/apps/operator-swarm/scripts/health-check.sh b/apps/operator-swarm/scripts/health-check.sh new file mode 100755 index 00000000..a4693d0e --- /dev/null +++ b/apps/operator-swarm/scripts/health-check.sh @@ -0,0 +1,118 @@ +#!/usr/bin/env bash +# ----------------------------------------------------------------------------- +# health-check.sh: quick local probe of the bot-node /stats endpoint. +# +# Reports last commit time, bot count, score progress, and exits non-zero if +# the endpoint is unreachable or any field is missing. Safe to drop into a +# cron / Cloudflare healthcheck / systemd timer. +# +# Usage: +# bash scripts/health-check.sh # human-readable +# bash scripts/health-check.sh --json # raw JSON, no formatting +# bash scripts/health-check.sh --quiet # exit code only, no output +# ----------------------------------------------------------------------------- +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +APP_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)" + +if [[ -f "${APP_DIR}/.env" ]]; then + # shellcheck disable=SC1091 + set -a + source "${APP_DIR}/.env" + set +a +fi + +PORT="${BOT_NODE_STATS_PORT:-4811}" +URL="http://127.0.0.1:${PORT}/stats" + +MODE="human" +for arg in "$@"; do + case "${arg}" in + --json) MODE="json" ;; + --quiet) MODE="quiet" ;; + --help|-h) + sed -n '2,15p' "$0" + exit 0 + ;; + esac +done + +if ! command -v curl >/dev/null 2>&1; then + echo "[health] ERROR: curl not installed" >&2 + exit 2 +fi + +# 5s connect + 5s read timeout is generous for a localhost probe but short +# enough that a stuck process still gets caught. +RESPONSE="$(curl -fsS --max-time 5 --connect-timeout 5 "${URL}" || true)" + +if [[ -z "${RESPONSE}" ]]; then + if [[ "${MODE}" != "quiet" ]]; then + echo "[health] FAIL: bot-node /stats unreachable at ${URL}" >&2 + fi + exit 1 +fi + +if [[ "${MODE}" == "json" ]]; then + echo "${RESPONSE}" + exit 0 +fi + +if ! command -v jq >/dev/null 2>&1; then + if [[ "${MODE}" != "quiet" ]]; then + echo "[health] WARNING: jq not installed, raw response follows" + echo "${RESPONSE}" + fi + exit 0 +fi + +# Expected shape (subject to whatever @tournamental/bot-node ships): +# { +# "node_id": "node_xyz", +# "label": "tim-1m-demo", +# "bot_count": 1000000, +# "bots_still_perfect": 234567, +# "last_commit_at": "2026-06-11T14:32:11Z", +# "last_commit_match": "WC2026_M03", +# "score_total": 18345678, +# "uptime_seconds": 86400 +# } + +LABEL="$(jq -r '.label // "unknown"' <<<"${RESPONSE}")" +BOT_COUNT="$(jq -r '.bot_count // 0' <<<"${RESPONSE}")" +STILL_PERFECT="$(jq -r '.bots_still_perfect // 0' <<<"${RESPONSE}")" +LAST_COMMIT_AT="$(jq -r '.last_commit_at // "never"' <<<"${RESPONSE}")" +LAST_COMMIT_MATCH="$(jq -r '.last_commit_match // "none"' <<<"${RESPONSE}")" +SCORE_TOTAL="$(jq -r '.score_total // 0' <<<"${RESPONSE}")" +UPTIME="$(jq -r '.uptime_seconds // 0' <<<"${RESPONSE}")" + +if [[ "${MODE}" == "quiet" ]]; then + exit 0 +fi + +printf "node label : %s\n" "${LABEL}" +printf "bot count : %s\n" "${BOT_COUNT}" +printf "bots still perfect : %s\n" "${STILL_PERFECT}" +printf "last commit at : %s\n" "${LAST_COMMIT_AT}" +printf "last commit match : %s\n" "${LAST_COMMIT_MATCH}" +printf "score total : %s\n" "${SCORE_TOTAL}" +printf "uptime (seconds) : %s\n" "${UPTIME}" + +# Stale commit detection: if the last commit is over 1 hour old AND the node +# has been up over 1 hour, flag it. The bot-node should be committing at +# least once per match window during the WC, and at least once per heartbeat +# otherwise. +NOW_EPOCH="$(date -u +%s)" +if [[ "${LAST_COMMIT_AT}" != "never" ]]; then + LAST_EPOCH="$(date -u -d "${LAST_COMMIT_AT}" +%s 2>/dev/null || echo 0)" + if [[ "${LAST_EPOCH}" -gt 0 ]]; then + AGE=$(( NOW_EPOCH - LAST_EPOCH )) + if [[ "${AGE}" -gt 3600 && "${UPTIME}" -gt 3600 ]]; then + echo "[health] WARN: last commit was ${AGE}s ago (>1h)" >&2 + exit 1 + fi + fi +fi + +exit 0 diff --git a/apps/operator-swarm/scripts/register.sh b/apps/operator-swarm/scripts/register.sh new file mode 100755 index 00000000..79bfbdcc --- /dev/null +++ b/apps/operator-swarm/scripts/register.sh @@ -0,0 +1,91 @@ +#!/usr/bin/env bash +# ----------------------------------------------------------------------------- +# register.sh: one-shot operator registration for the Tournamental Open Bot +# Arena federated network. +# +# Runs `tournamental-bot-node register` against the central API, then writes +# the returned operator credentials to ~/.tournamental/operator.json so the +# PM2 runtime can read them on every restart. +# +# Idempotent: if a credentials file already exists, the script prints the +# stored node_id and exits 0 without calling the API again. To force a +# re-register, delete the credentials file first. +# ----------------------------------------------------------------------------- +set -euo pipefail + +# Find the app root (this script lives in apps/operator-swarm/scripts/). +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +APP_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)" + +# Source .env if present so the operator does not have to export by hand. +if [[ -f "${APP_DIR}/.env" ]]; then + # shellcheck disable=SC1091 + set -a + source "${APP_DIR}/.env" + set +a +fi + +: "${TOURNAMENTAL_API_BASE_URL:?Set TOURNAMENTAL_API_BASE_URL in .env}" +: "${OPERATOR_EMAIL:?Set OPERATOR_EMAIL in .env}" +: "${OPERATOR_NODE_LABEL:?Set OPERATOR_NODE_LABEL in .env}" + +# Resolve the credentials path with tilde expansion. +CREDS_RAW="${OPERATOR_CREDENTIALS_PATH:-${HOME}/.tournamental/operator.json}" +CREDS_PATH="${CREDS_RAW/#\~/${HOME}}" +CREDS_DIR="$(dirname "${CREDS_PATH}")" + +mkdir -p "${CREDS_DIR}" +chmod 700 "${CREDS_DIR}" || true + +if [[ -s "${CREDS_PATH}" ]]; then + echo "[register] credentials already present at ${CREDS_PATH}" + if command -v jq >/dev/null 2>&1; then + NODE_ID="$(jq -r '.node_id // empty' "${CREDS_PATH}")" + if [[ -n "${NODE_ID}" ]]; then + echo "[register] node_id=${NODE_ID}" + fi + fi + echo "[register] delete ${CREDS_PATH} and rerun to force re-registration" + exit 0 +fi + +# Confirm the CLI from @tournamental/bot-node is on PATH (pnpm exec is the +# resilient option because the binary is hoisted into node_modules/.bin). +if ! command -v tournamental-bot-node >/dev/null 2>&1; then + echo "[register] tournamental-bot-node not on PATH, falling back to pnpm exec" + RUNNER=(pnpm --filter @tournamental/operator-swarm exec tournamental-bot-node) +else + RUNNER=(tournamental-bot-node) +fi + +echo "[register] registering node label=${OPERATOR_NODE_LABEL} email=${OPERATOR_EMAIL}" +echo "[register] api=${TOURNAMENTAL_API_BASE_URL}" + +# The bot-node CLI writes credentials to stdout as JSON. Capture, validate, +# and persist atomically so a crash mid-write does not leave a half file. +TMP_FILE="$(mktemp)" +trap 'rm -f "${TMP_FILE}"' EXIT + +"${RUNNER[@]}" register \ + --email="${OPERATOR_EMAIL}" \ + --label="${OPERATOR_NODE_LABEL}" \ + --api-base-url="${TOURNAMENTAL_API_BASE_URL}" \ + >"${TMP_FILE}" + +# Basic sanity check: must be non-empty JSON with a node_id. +if ! command -v jq >/dev/null 2>&1; then + echo "[register] WARNING: jq not installed, skipping JSON validation" +else + if ! jq -e '.node_id' "${TMP_FILE}" >/dev/null; then + echo "[register] ERROR: bot-node did not return a node_id" + cat "${TMP_FILE}" >&2 + exit 1 + fi +fi + +mv "${TMP_FILE}" "${CREDS_PATH}" +trap - EXIT +chmod 600 "${CREDS_PATH}" + +echo "[register] OK, credentials written to ${CREDS_PATH}" +echo "[register] next: pnpm --filter @tournamental/operator-swarm run start" diff --git a/apps/sage/.env.example b/apps/sage/.env.example new file mode 100644 index 00000000..507d4266 --- /dev/null +++ b/apps/sage/.env.example @@ -0,0 +1,21 @@ +# Required: Anthropic API key for Claude Opus 4.7. +ANTHROPIC_API_KEY= + +# Required: Tournamental API key (issue one at https://play.tournamental.com/bots/keys). +TOURNAMENTAL_API_KEY= + +# Optional: skip the one-time /v1/bots/register call. +# TOURNAMENTAL_BOT_ID= + +# Optional: override the public API and odds base URLs (e.g. for dev). +# TOURNAMENTAL_API_BASE=https://api.tournamental.com +# ODDS_API_BASE=https://odds.tournamental.com + +# Optional: tournament filter (default fifa-wc-2026). +# TOURNAMENT_ID=fifa-wc-2026 + +# Optional: cap on picks per tick (default 24). +# SAGE_MAX_PICKS=24 + +# Optional: Claude model id (default claude-opus-4-7). +# SAGE_MODEL=claude-opus-4-7 diff --git a/apps/sage/.gitignore b/apps/sage/.gitignore new file mode 100644 index 00000000..b07e6219 --- /dev/null +++ b/apps/sage/.gitignore @@ -0,0 +1,5 @@ +dist/ +node_modules/ +logs/ +.env +.sage-state.json diff --git a/apps/sage/README.md b/apps/sage/README.md new file mode 100644 index 00000000..36caca48 --- /dev/null +++ b/apps/sage/README.md @@ -0,0 +1,93 @@ +# @tournamental/sage + +Tournamental Sage is the reference bot for the [Open Bot Arena](https://play.tournamental.com/bots/sdk). It demonstrates `@tournamental/bot-sdk` end-to-end: it reads the live Polymarket odds, asks Claude Opus 4.7 for a per-match pick, and submits via the bulk-insert API. Sage competes publicly on the Bots leaderboard tab as `@sage`. + +Sage is intentionally simple. The interesting logic is ~100 lines in `src/strategy.ts`. Fork it as a starting point for your own bot. + +## What it does, on every PM2 tick + +1. Resolve its bot id (one-time registration, cached in `.sage-state.json`). +2. GET the tournament's match catalogue. +3. GET the Polymarket odds snapshot (served by `apps/odds-ingest` at `odds.tournamental.com`). +4. For each upcoming match, ask Claude `home_win | draw | away_win`. +5. Flush all picks as one bulk-insert POST to `api.tournamental.com/v1/picks/bulk`. +6. Exit. PM2 wakes Sage again on the next 6-hour cron tick. + +If Claude returns anything other than the three allowed tokens (or the call fails), Sage falls back to the favourite implied by the odds. Sage never skips a match. + +## Run locally + +```bash +# From repo root +pnpm install +pnpm --filter @tournamental/sage build + +# Set env, then do one tick: +cd apps/sage +cp .env.example .env # see below +node dist/index.js +``` + +For development with watch + tsx: + +```bash +pnpm --filter @tournamental/sage dev +``` + +## Required env vars + +| Var | Required | Default | Notes | +|-----|----------|---------|-------| +| `ANTHROPIC_API_KEY` | yes | -- | Used to call Claude Opus 4.7. | +| `TOURNAMENTAL_API_KEY` | yes | -- | Issued at https://play.tournamental.com/bots/keys. | +| `TOURNAMENTAL_BOT_ID` | no | -- | Skip registration if set; otherwise Sage calls `/v1/bots/register` with handle `@sage` once and caches the result. | +| `TOURNAMENTAL_API_BASE` | no | `https://api.tournamental.com` | Override for dev (`https://vtorn-dev.aiva.nz`). | +| `ODDS_API_BASE` | no | `https://odds.tournamental.com` | Override for dev or to point at a local `apps/odds-ingest`. | +| `TOURNAMENT_ID` | no | `fifa-wc-2026` | -- | +| `SAGE_MAX_PICKS` | no | `24` | Caps Claude spend per tick. | +| `SAGE_MODEL` | no | `claude-opus-4-7` | Anthropic model id. | + +A `.env.example` is checked in. Copy it to `.env` and fill in the two API keys. + +## Run under PM2 (dev box) + +```bash +cd apps/sage +pnpm build +pm2 start ecosystem.config.cjs +pm2 save +``` + +`cron_restart: "0 */6 * * *"` triggers a fresh run at the top of every sixth UTC hour (00:00, 06:00, 12:00, 18:00). `autorestart: false` keeps Sage idle between ticks. + +To view logs: + +```bash +pm2 logs tournamental-sage # live tail +tail -f apps/sage/logs/sage.out.log # raw file +tail -f apps/sage/logs/sage.err.log # error stream +``` + +To trigger an ad-hoc tick: + +```bash +pm2 restart tournamental-sage +``` + +To stop entirely: + +```bash +pm2 delete tournamental-sage +``` + +## Tests + +```bash +pnpm --filter @tournamental/sage test +``` + +The strategy tests use a mocked Claude client; no network or API key required. + +## Open-source notes + +Apache 2.0. Bot handles like `@sage` are reserved for officially-operated bots. Forking Sage for your own bot is encouraged; pick a different handle and follow the patterns in [`/bots/sdk`](https://play.tournamental.com/bots/sdk). diff --git a/apps/sage/ecosystem.config.cjs b/apps/sage/ecosystem.config.cjs new file mode 100644 index 00000000..1ffb3127 --- /dev/null +++ b/apps/sage/ecosystem.config.cjs @@ -0,0 +1,49 @@ +/** + * PM2 process descriptor for Tournamental Sage. + * + * Sage does one decision pass per invocation and exits. PM2's `cron_restart` + * re-launches the process at the top of every sixth hour (00:00, 06:00, + * 12:00, 18:00 UTC). `autorestart: false` makes sure PM2 does not respawn + * us in between cron ticks if we exit early (e.g. nothing to do). + * + * Run from this directory: + * pnpm --filter @tournamental/sage build + * pm2 start ecosystem.config.cjs + * pm2 save + * + * Logs land in ./logs/. PM2 rotates them via pm2-logrotate (already + * configured on the dev box). + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §9. + * Plan: docs/superpowers/plans/2026-06-07-bot-arena-phase-1.md Task 20. + */ + +module.exports = { + apps: [ + { + name: "tournamental-sage", + cwd: __dirname, + script: "dist/index.js", + interpreter: "node", + node_args: ["--enable-source-maps"], + cron_restart: "0 */6 * * *", + autorestart: false, + max_memory_restart: "256M", + kill_timeout: 10_000, + out_file: "./logs/sage.out.log", + error_file: "./logs/sage.err.log", + merge_logs: true, + time: true, + env: { + NODE_ENV: "production", + // Secrets are loaded from .env via the operator's shell or PM2 + // module pm2-env. Do not check secrets in here. + TOURNAMENTAL_API_BASE: "https://api.tournamental.com", + ODDS_API_BASE: "https://odds.tournamental.com", + TOURNAMENT_ID: "fifa-wc-2026", + SAGE_MODEL: "claude-opus-4-7", + SAGE_MAX_PICKS: "24", + }, + }, + ], +}; diff --git a/apps/sage/package.json b/apps/sage/package.json new file mode 100644 index 00000000..51ef6709 --- /dev/null +++ b/apps/sage/package.json @@ -0,0 +1,29 @@ +{ + "name": "@tournamental/sage", + "version": "0.1.0", + "private": true, + "description": "Tournamental Sage: the Claude-powered reference bot for the Open Bot Arena. Demonstrates @tournamental/bot-sdk end-to-end.", + "type": "module", + "main": "dist/index.js", + "scripts": { + "dev": "tsx src/index.ts", + "start": "node dist/index.js", + "build": "tsc -p tsconfig.json", + "typecheck": "tsc -p tsconfig.json --noEmit", + "test": "vitest run", + "test:watch": "vitest" + }, + "dependencies": { + "@anthropic-ai/sdk": "^0.30.1", + "@tournamental/bot-sdk": "workspace:*" + }, + "devDependencies": { + "@types/node": "^20.16.11", + "tsx": "^4.19.2", + "typescript": "^5.6.3", + "vitest": "^4.1.8" + }, + "engines": { + "node": ">=20.0.0" + } +} diff --git a/apps/sage/src/api.ts b/apps/sage/src/api.ts new file mode 100644 index 00000000..6e6b39ee --- /dev/null +++ b/apps/sage/src/api.ts @@ -0,0 +1,149 @@ +/** + * Helpers for fetching the live match catalogue and current Polymarket odds. + * + * Two data sources: + * 1. Tournamental's own match catalogue API (`/v1/matches`). This is the + * authoritative list Sage iterates: ids, codes, kickoff times. + * 2. The Polymarket-fed odds endpoint at `/v1/odds/snapshot` (served by + * `apps/odds-ingest`). Sage reads this once per cron tick and slices it + * per match. Falling back to the public Polymarket Gamma API directly + * keeps Sage usable as a standalone reference even if the ingest + * service is offline. + * + * No retries here. The cron tick repeats every 6 hours; transient failures + * naturally heal. The bot-sdk's HTTP client already retries on bulk submit. + */ + +import type { MatchSpec, OddsSnapshot } from "@tournamental/bot-sdk"; + +export const DEFAULT_API_BASE = "https://api.tournamental.com"; +export const DEFAULT_ODDS_BASE = "https://odds.tournamental.com"; +export const DEFAULT_TOURNAMENT_ID = "fifa-wc-2026"; + +export interface ApiOpts { + /** Base URL for the Tournamental public API. Default: api.tournamental.com. */ + apiBase?: string; + /** Base URL for the odds-ingest service. Default: odds.tournamental.com. */ + oddsBase?: string; + /** Tournament filter. Default: fifa-wc-2026. */ + tournamentId?: string; + /** Pluggable fetch for tests. Default: global fetch. */ + fetchImpl?: typeof fetch; +} + +interface RawMatchListResponse { + matches?: MatchSpec[]; +} + +interface RawSnapshotResponse { + matches?: { + matchNo: string; + homeWin?: number; + draw?: number; + awayWin?: number; + source?: string; + }[]; + probabilities?: Record>; + ts?: number; +} + +/** + * Pull the tournament's match catalogue. Returns an empty list on any + * failure (network, non-200, bad JSON). The caller decides whether to + * abort the tick or proceed with zero matches (we log + skip). + */ +export async function fetchMatches(opts: ApiOpts = {}): Promise { + const fetcher = opts.fetchImpl ?? (globalThis.fetch as typeof fetch); + const base = opts.apiBase ?? DEFAULT_API_BASE; + const tournament = opts.tournamentId ?? DEFAULT_TOURNAMENT_ID; + const url = `${base}/v1/matches?tournament_id=${encodeURIComponent(tournament)}`; + try { + const res = await fetcher(url, { method: "GET" }); + if (!res.ok) return []; + const body = (await res.json()) as RawMatchListResponse; + return Array.isArray(body.matches) ? body.matches : []; + } catch { + return []; + } +} + +/** + * Pull every match's current implied probabilities in one request and + * return a map keyed by `MatchSpec.id`. Handles the two response shapes + * that the ingest service emits (see apps/odds-ingest/src/api.ts and the + * Next adapter in apps/web/app/api/odds/snapshot). + */ +export async function fetchOddsSnapshot( + opts: ApiOpts = {}, +): Promise> { + const fetcher = opts.fetchImpl ?? (globalThis.fetch as typeof fetch); + const base = opts.oddsBase ?? DEFAULT_ODDS_BASE; + const url = `${base}/v1/odds/snapshot`; + const out = new Map(); + try { + const res = await fetcher(url, { method: "GET" }); + if (!res.ok) return out; + const body = (await res.json()) as RawSnapshotResponse; + if (Array.isArray(body.matches)) { + for (const row of body.matches) { + if ( + typeof row.homeWin === "number" && + typeof row.draw === "number" && + typeof row.awayWin === "number" + ) { + out.set(String(row.matchNo), { + match_id: String(row.matchNo), + home_win: row.homeWin, + draw: row.draw, + away_win: row.awayWin, + source: row.source ?? "polymarket", + }); + } + } + return out; + } + if (body.probabilities) { + for (const [marketId, probs] of Object.entries(body.probabilities)) { + // marketId of the form "wc2026:match:12" -> id "12". + const m = marketId.match(/match:(\d+)/); + if (!m) continue; + const id = m[1]!; + const draw = probs["Draw"] ?? probs["draw"] ?? 0; + const others = Object.entries(probs).filter( + ([k]) => k !== "Draw" && k !== "draw", + ); + if (others.length !== 2) continue; + const [home, away] = others; + out.set(id, { + match_id: id, + home_win: home![1], + draw, + away_win: away![1], + source: "polymarket", + }); + } + } + } catch { + /* fall through, return whatever we built */ + } + return out; +} + +/** + * Select the next matches Sage should opine on. Filters out anything that has + * already kicked off (picks are locked at kickoff) and caps the batch so the + * Claude bill stays predictable. Returns a stable order (ascending kickoff). + */ +export function selectUpcoming( + matches: MatchSpec[], + now: Date = new Date(), + limit = 24, +): MatchSpec[] { + const horizon = matches + .filter((m) => { + const t = Date.parse(m.kickoff_utc); + return Number.isFinite(t) && t > now.getTime(); + }) + .sort((a, b) => Date.parse(a.kickoff_utc) - Date.parse(b.kickoff_utc)); + return horizon.slice(0, limit); +} diff --git a/apps/sage/src/index.ts b/apps/sage/src/index.ts new file mode 100644 index 00000000..dc8bc6c2 --- /dev/null +++ b/apps/sage/src/index.ts @@ -0,0 +1,154 @@ +/** + * Sage main entrypoint. + * + * Runs a single decision pass and exits. PM2 wakes us every 6 hours via + * `cron_restart` (see ecosystem.config.cjs). One pass = fetch the match + * catalogue, fetch the live odds snapshot, ask Claude for a pick per + * upcoming match, flush as one bulk submission via @tournamental/bot-sdk. + * + * Exit codes: + * 0 normal: registered, picked, flushed. + * 2 config error (missing API keys). + * 3 transient error (network, API non-200); PM2 will retry on next cron tick. + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §9. + * Plan: docs/superpowers/plans/2026-06-07-bot-arena-phase-1.md Task 20. + */ + +import Anthropic from "@anthropic-ai/sdk"; +import { Bot } from "@tournamental/bot-sdk"; + +import { fetchMatches, fetchOddsSnapshot, selectUpcoming, DEFAULT_TOURNAMENT_ID } from "./api.js"; +import { ensureSageRegistered, SAGE_HANDLE } from "./register.js"; +import { decide, DEFAULT_MODEL } from "./strategy.js"; + +interface Env { + ANTHROPIC_API_KEY: string; + TOURNAMENTAL_API_KEY: string; + TOURNAMENTAL_API_BASE?: string; + ODDS_API_BASE?: string; + TOURNAMENT_ID?: string; + SAGE_MAX_PICKS?: string; + SAGE_MODEL?: string; +} + +function readEnv(): Env | null { + const anthropic = process.env.ANTHROPIC_API_KEY; + const apiKey = process.env.TOURNAMENTAL_API_KEY; + if (!anthropic || !apiKey) { + console.error( + "sage: missing required env. Need ANTHROPIC_API_KEY and TOURNAMENTAL_API_KEY.", + ); + return null; + } + return { + ANTHROPIC_API_KEY: anthropic, + TOURNAMENTAL_API_KEY: apiKey, + TOURNAMENTAL_API_BASE: process.env.TOURNAMENTAL_API_BASE, + ODDS_API_BASE: process.env.ODDS_API_BASE, + TOURNAMENT_ID: process.env.TOURNAMENT_ID, + SAGE_MAX_PICKS: process.env.SAGE_MAX_PICKS, + SAGE_MODEL: process.env.SAGE_MODEL, + }; +} + +export async function runOnce(): Promise { + const env = readEnv(); + if (!env) return 2; + + const tournamentId = env.TOURNAMENT_ID ?? DEFAULT_TOURNAMENT_ID; + const limit = Number.parseInt(env.SAGE_MAX_PICKS ?? "24", 10); + const model = env.SAGE_MODEL ?? DEFAULT_MODEL; + + console.log( + `[sage] tick ${new Date().toISOString()} tournament=${tournamentId} model=${model} limit=${limit}`, + ); + + let state; + try { + state = await ensureSageRegistered({ + apiKey: env.TOURNAMENTAL_API_KEY, + apiBase: env.TOURNAMENTAL_API_BASE, + }); + } catch (err) { + console.error(`[sage] registration failed: ${(err as Error).message}`); + return 3; + } + console.log(`[sage] registered as ${state.handle} bot_id=${state.bot_id}`); + + const [matches, oddsMap] = await Promise.all([ + fetchMatches({ apiBase: env.TOURNAMENTAL_API_BASE, tournamentId }), + fetchOddsSnapshot({ oddsBase: env.ODDS_API_BASE, tournamentId }), + ]); + + if (matches.length === 0) { + console.warn("[sage] no matches returned from catalogue; nothing to do"); + return 0; + } + const upcoming = selectUpcoming(matches, new Date(), limit); + console.log( + `[sage] catalogue=${matches.length} upcoming=${upcoming.length} odds_rows=${oddsMap.size}`, + ); + + const claude: Anthropic = new Anthropic({ apiKey: env.ANTHROPIC_API_KEY }); + const bot = new Bot({ + apiKey: env.TOURNAMENTAL_API_KEY, + baseUrl: env.TOURNAMENTAL_API_BASE, + botId: state.bot_id, + tournamentId, + }); + + for (const match of upcoming) { + const odds = oddsMap.get(match.id) ?? null; + const outcome = await decide(match, odds, { claude, model }); + bot.pick(match.id, outcome); + console.log( + `[sage] ${match.id} ${match.home_code ?? "?"}-${match.away_code ?? "?"} -> ${outcome}`, + ); + } + + if (bot.queueSize === 0) { + console.log("[sage] no picks queued; exiting cleanly"); + return 0; + } + + try { + const res = await bot.flush(); + console.log( + `[sage] flushed picks=${res.accepted} dropped=${res.dropped_picks.length} quota_remaining=${res.quota_remaining.picks_per_hour}`, + ); + if (res.dropped_picks.length > 0) { + for (const d of res.dropped_picks) { + console.warn(`[sage] dropped ${d.match_id}: ${d.reason}`); + } + } + return 0; + } catch (err) { + console.error(`[sage] flush failed: ${(err as Error).message}`); + return 3; + } +} + +// Detect direct execution (PM2 `script: dist/index.js` or `tsx src/index.ts`). +// We compare resolved paths so tsx watch + node both work. +const isMain = (() => { + if (!process.argv[1]) return false; + try { + const argvPath = new URL(`file://${process.argv[1]}`).href; + return import.meta.url === argvPath; + } catch { + return false; + } +})(); + +if (isMain) { + runOnce() + .then((code) => { + console.log(`[sage] exit ${code} handle=${SAGE_HANDLE}`); + process.exit(code); + }) + .catch((err) => { + console.error("[sage] unhandled error", err); + process.exit(3); + }); +} diff --git a/apps/sage/src/register.ts b/apps/sage/src/register.ts new file mode 100644 index 00000000..58035c82 --- /dev/null +++ b/apps/sage/src/register.ts @@ -0,0 +1,108 @@ +/** + * One-time bot registration for Sage. + * + * Sage runs forever under PM2 but only needs to register once. On every + * boot we check the local state file (`.sage-state.json`) and, if no + * bot_id is recorded, call the central API-key issuance flow to claim + * the `@sage` handle. The handle is reserved publicly; the central + * issuance endpoint validates the request comes from the holder of the + * matching `TOURNAMENTAL_API_KEY` and returns a stable `bot_id`. + * + * In Phase 1 the recommended flow is to issue the key via the self-service + * `/bots/keys` page and paste the resulting key + bot id into + * `apps/sage/.env`. This module supports that path AND a programmatic + * fallback: if `TOURNAMENTAL_BOT_ID` is missing it will POST to + * `/v1/bots/register` with the reserved handle and persist the response. + */ + +import { readFile, writeFile } from "node:fs/promises"; +import { existsSync } from "node:fs"; +import { join } from "node:path"; + +export const SAGE_HANDLE = "@sage"; +export const SAGE_STATE_FILE = ".sage-state.json"; + +export interface SageState { + bot_id: string; + handle: string; + registered_at: string; +} + +export interface RegisterOpts { + apiBase?: string; + apiKey: string; + /** Override the persistent state file path (defaults to ./.sage-state.json). */ + stateFile?: string; + fetchImpl?: typeof fetch; +} + +/** + * Resolve Sage's bot id, registering once if needed. + * + * Priority order: + * 1. `TOURNAMENTAL_BOT_ID` env var (operator pasted it; use as-is). + * 2. Cached state file (previous run registered it). + * 3. POST `/v1/bots/register` with the reserved `@sage` handle. + * + * Throws only if no API key was supplied AND no cached id exists; this + * makes the function safe to call in tests with a mock fetcher. + */ +export async function ensureSageRegistered( + opts: RegisterOpts, +): Promise { + const fetcher = opts.fetchImpl ?? (globalThis.fetch as typeof fetch); + const stateFile = opts.stateFile ?? join(process.cwd(), SAGE_STATE_FILE); + + const envBotId = process.env.TOURNAMENTAL_BOT_ID?.trim(); + if (envBotId) { + const state: SageState = { + bot_id: envBotId, + handle: SAGE_HANDLE, + registered_at: new Date().toISOString(), + }; + await persist(stateFile, state); + return state; + } + + if (existsSync(stateFile)) { + try { + const cached = JSON.parse(await readFile(stateFile, "utf8")) as SageState; + if (cached.bot_id && cached.handle === SAGE_HANDLE) return cached; + } catch { + /* corrupted cache; fall through and re-register */ + } + } + + if (!opts.apiKey) { + throw new Error( + "sage: TOURNAMENTAL_API_KEY missing and no cached bot id. Set the env or issue a key at /bots/keys.", + ); + } + + const base = opts.apiBase ?? "https://api.tournamental.com"; + const res = await fetcher(`${base}/v1/bots/register`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${opts.apiKey}`, + }, + body: JSON.stringify({ handle: SAGE_HANDLE }), + }); + if (!res.ok) { + const errBody = await res.text().catch(() => ""); + throw new Error(`sage: register failed ${res.status}: ${errBody}`); + } + const body = (await res.json()) as { bot_id: string }; + if (!body.bot_id) throw new Error("sage: register response missing bot_id"); + const state: SageState = { + bot_id: body.bot_id, + handle: SAGE_HANDLE, + registered_at: new Date().toISOString(), + }; + await persist(stateFile, state); + return state; +} + +async function persist(stateFile: string, state: SageState): Promise { + await writeFile(stateFile, JSON.stringify(state, null, 2), "utf8"); +} diff --git a/apps/sage/src/strategy.ts b/apps/sage/src/strategy.ts new file mode 100644 index 00000000..0f4ab0ca --- /dev/null +++ b/apps/sage/src/strategy.ts @@ -0,0 +1,130 @@ +/** + * Sage's per-match decision function. + * + * Asks Claude Opus 4.7 to nominate one of `home_win | draw | away_win` for a + * single match given the public Polymarket odds snapshot. The model is asked + * for a single token-style answer; if it returns anything else we fall back + * to the favourite implied by the odds (lowest implied probability of + * loss). This makes the function deterministic in failure modes: Sage never + * skips a match. + * + * Spec ref: docs/superpowers/specs/2026-06-07-bot-arena-design.md §9. + */ + +import type { MatchSpec, OddsSnapshot, Outcome } from "@tournamental/bot-sdk"; + +/** + * Minimal subset of the Anthropic SDK we depend on. Defined as an interface so + * tests can inject a mock without touching the real network. The real + * `@anthropic-ai/sdk` client implements this shape (the response body is the + * `Anthropic.Messages.Message` type but we narrow to what we use). + */ +export interface ClaudeLike { + messages: { + create: (req: ClaudeRequest) => Promise; + }; +} + +export interface ClaudeRequest { + model: string; + max_tokens: number; + messages: { role: "user" | "assistant"; content: string }[]; +} + +export interface ClaudeResponse { + content: { type: string; text?: string }[]; +} + +export interface DecideOpts { + /** Optional injected Claude client. Defaults to a real Anthropic SDK instance built from ANTHROPIC_API_KEY. */ + claude?: ClaudeLike; + /** Override the Claude model id. Defaults to claude-opus-4-7. */ + model?: string; +} + +export const DEFAULT_MODEL = "claude-opus-4-7"; + +/** + * Build the user prompt for a single match. Kept tiny so the model returns + * one token; keeps cost low and parsing simple. + */ +export function buildPrompt(match: MatchSpec, odds: OddsSnapshot | null): string { + const home = match.home_code ?? "HOME"; + const away = match.away_code ?? "AWAY"; + const oddsBlob = odds + ? `home_win=${odds.home_win.toFixed(3)} draw=${odds.draw.toFixed(3)} away_win=${odds.away_win.toFixed(3)}` + : "no live market"; + return [ + `Football match: ${home} vs ${away}.`, + `Kickoff: ${match.kickoff_utc}.`, + `Public market probabilities: ${oddsBlob}.`, + `Reply with exactly one of: home_win | draw | away_win. No punctuation, no explanation.`, + ].join("\n"); +} + +/** + * Pick the favourite implied by an odds snapshot. Used as the deterministic + * fallback when Claude returns garbage or is unavailable. + * + * Tie-breaks deterministically: prefer home_win, then draw, then away_win. + * This matches the chalk-bot baseline so Sage never drifts below it on a + * pure-fallback day. + */ +export function favourite(odds: OddsSnapshot | null): Outcome { + if (!odds) return "home_win"; + const ranked: { outcome: Outcome; p: number }[] = [ + { outcome: "home_win", p: odds.home_win }, + { outcome: "draw", p: odds.draw }, + { outcome: "away_win", p: odds.away_win }, + ]; + ranked.sort((a, b) => b.p - a.p); + return ranked[0]!.outcome; +} + +/** Strict outcome parser. Trims, lowercases, accepts only the three canonical strings. */ +export function parseOutcome(raw: string): Outcome | null { + const trimmed = raw + .trim() + .toLowerCase() + .replace(/^[`"'.\s]+/g, "") + .replace(/[`"'.\s]+$/g, ""); + if (trimmed === "home_win" || trimmed === "draw" || trimmed === "away_win") { + return trimmed; + } + return null; +} + +/** + * Ask Claude for a pick. Falls back to the odds favourite if: + * - no Claude client was provided AND no API key in env (lets tests skip the network), + * - the API call throws, + * - the response is missing text content, + * - or the returned text is not one of the three allowed tokens. + */ +export async function decide( + match: MatchSpec, + odds: OddsSnapshot | null, + opts: DecideOpts = {}, +): Promise { + const client = opts.claude; + if (!client) { + // No injected client and no key: bail to the favourite without throwing. + // The runtime in src/index.ts wires the real SDK in production. + return favourite(odds); + } + const model = opts.model ?? DEFAULT_MODEL; + const prompt = buildPrompt(match, odds); + try { + const res = await client.messages.create({ + model, + max_tokens: 16, + messages: [{ role: "user", content: prompt }], + }); + const block = res.content.find((c) => c.type === "text"); + const text = block?.text ?? ""; + const parsed = parseOutcome(text); + return parsed ?? favourite(odds); + } catch { + return favourite(odds); + } +} diff --git a/apps/sage/test/strategy.test.ts b/apps/sage/test/strategy.test.ts new file mode 100644 index 00000000..829f164c --- /dev/null +++ b/apps/sage/test/strategy.test.ts @@ -0,0 +1,135 @@ +/** + * Sage strategy tests. + * + * The strategy module is the only piece of Sage that has interesting branching + * (parser + fallback). The cron loop is wired directly to PM2; integration is + * smoke-tested in Task 21 of the Phase 1 plan, not here. + */ + +import { describe, it, expect } from "vitest"; + +import type { MatchSpec, OddsSnapshot } from "@tournamental/bot-sdk"; + +import { + buildPrompt, + decide, + favourite, + parseOutcome, + type ClaudeLike, + type ClaudeResponse, +} from "../src/strategy.js"; + +const MATCH: MatchSpec = { + id: "1", + stage: "group", + home_code: "ARG", + away_code: "FRA", + kickoff_utc: "2026-06-11T18:00:00Z", +}; + +const ODDS: OddsSnapshot = { + match_id: "1", + home_win: 0.45, + draw: 0.25, + away_win: 0.3, + source: "polymarket", +}; + +function fakeClaude(text: string): ClaudeLike { + return { + messages: { + create: async (): Promise => ({ + content: [{ type: "text", text }], + }), + }, + }; +} + +function explodingClaude(): ClaudeLike { + return { + messages: { + create: async (): Promise => { + throw new Error("simulated 503"); + }, + }, + }; +} + +describe("parseOutcome", () => { + it("accepts the three canonical tokens", () => { + expect(parseOutcome("home_win")).toBe("home_win"); + expect(parseOutcome("draw")).toBe("draw"); + expect(parseOutcome("away_win")).toBe("away_win"); + }); + + it("trims whitespace and trailing punctuation", () => { + expect(parseOutcome(" home_win\n")).toBe("home_win"); + expect(parseOutcome("draw.")).toBe("draw"); + expect(parseOutcome("`away_win`")).toBe("away_win"); + }); + + it("rejects anything else", () => { + expect(parseOutcome("HomeWin")).toBeNull(); + expect(parseOutcome("Argentina wins")).toBeNull(); + expect(parseOutcome("")).toBeNull(); + expect(parseOutcome("home_win because Messi")).toBeNull(); + }); +}); + +describe("favourite", () => { + it("picks the highest implied probability", () => { + expect(favourite(ODDS)).toBe("home_win"); + expect( + favourite({ ...ODDS, home_win: 0.2, draw: 0.2, away_win: 0.6 }), + ).toBe("away_win"); + expect( + favourite({ ...ODDS, home_win: 0.2, draw: 0.6, away_win: 0.2 }), + ).toBe("draw"); + }); + + it("defaults to home_win when no odds available", () => { + expect(favourite(null)).toBe("home_win"); + }); +}); + +describe("buildPrompt", () => { + it("includes both team codes and odds", () => { + const prompt = buildPrompt(MATCH, ODDS); + expect(prompt).toContain("ARG"); + expect(prompt).toContain("FRA"); + expect(prompt).toContain("0.450"); + expect(prompt).toContain("home_win | draw | away_win"); + }); + + it("flags no live market when odds are null", () => { + const prompt = buildPrompt(MATCH, null); + expect(prompt).toContain("no live market"); + }); +}); + +describe("decide", () => { + it("returns Claude's pick when it is one of the three tokens", async () => { + const claude = fakeClaude("draw"); + expect(await decide(MATCH, ODDS, { claude })).toBe("draw"); + }); + + it("falls back to the favourite when Claude returns garbage", async () => { + const claude = fakeClaude("I think Argentina will win on penalties."); + // favourite of ODDS is home_win (0.45) + expect(await decide(MATCH, ODDS, { claude })).toBe("home_win"); + }); + + it("falls back to the favourite when Claude throws", async () => { + const claude = explodingClaude(); + expect(await decide(MATCH, ODDS, { claude })).toBe("home_win"); + }); + + it("falls back to home_win when there are no odds and Claude misbehaves", async () => { + const claude = fakeClaude("???"); + expect(await decide(MATCH, null, { claude })).toBe("home_win"); + }); + + it("returns favourite without a client (test/dev shortcut)", async () => { + expect(await decide(MATCH, ODDS)).toBe("home_win"); + }); +}); diff --git a/apps/sage/tsconfig.json b/apps/sage/tsconfig.json new file mode 100644 index 00000000..42b992d7 --- /dev/null +++ b/apps/sage/tsconfig.json @@ -0,0 +1,17 @@ +{ + "extends": "../../tsconfig.base.json", + "compilerOptions": { + "outDir": "dist", + "rootDir": "src", + "declaration": true, + "sourceMap": true, + "resolveJsonModule": true, + "types": ["node"], + "baseUrl": ".", + "paths": { + "@tournamental/bot-sdk": ["./node_modules/@tournamental/bot-sdk/dist/index.d.ts"] + } + }, + "include": ["src/**/*"], + "exclude": ["dist", "node_modules", "test"] +} diff --git a/apps/sage/vitest.config.ts b/apps/sage/vitest.config.ts new file mode 100644 index 00000000..d9ebefd5 --- /dev/null +++ b/apps/sage/vitest.config.ts @@ -0,0 +1,8 @@ +import { defineConfig } from "vitest/config"; + +export default defineConfig({ + test: { + include: ["test/**/*.test.ts"], + environment: "node", + }, +}); diff --git a/apps/seed-bots/README.md b/apps/seed-bots/README.md new file mode 100644 index 00000000..7e1d0af0 --- /dev/null +++ b/apps/seed-bots/README.md @@ -0,0 +1,147 @@ +# @tournamental/seed-bots + +Deterministic CLI that seeds ~18,000 cosmetic, humans-style bot accounts +into Tournamental so the leaderboard reads as populated from minute one +of the FIFA World Cup 2026 launch on 11 June. + +**Important framing**: the 18k seed bots appear on the **Humans** tab of +the leaderboard, not the Bots tab. They are flagged `is_bot=1` and +`humanness_score=0` internally so they remain ineligible for the cash +prize (per `/terms/house-prize`), but render as humans on the public +surface. The Bots tab is reserved for federated-network bots without +user accounts (Phase 2). + +Source of truth: `docs/superpowers/specs/2026-06-07-bot-arena-design.md` section 4. + +## Quickstart + +```bash +# Dry run: print validation summary, no DB writes. +pnpm --filter @tournamental/seed-bots run seed -- --target=18000 --dry-run + +# Apply: write to all three stores. +pnpm --filter @tournamental/seed-bots run seed -- --target=18000 --apply + +# Smoke test on a small cohort: +pnpm --filter @tournamental/seed-bots run seed -- --target=100 --dry-run + +# Roll back everything (idempotent; safe to re-run): +pnpm --filter @tournamental/seed-bots run seed -- --purge +``` + +The CLI exits non-zero when any of the validation targets miss by more +than 2 percentage points, so a re-run after editing the algorithm can't +silently land a regression. + +## What gets created + +Per bot, with deterministic ids of the form `bot_<8-char-base32>`: + +| Store | Surface | Payload | +| --- | --- | --- | +| `apps/auth-sms` | `user` table | `id`, `display_name`, `country`, `first_name`, `last_name`, `favourite_team_code`, `created_at`, `last_seen_at`, `is_bot=1` | +| `apps/identity` | `humanness-scores.jsonl` | `{ userId, score: 0, factors: [seed_bot], computedAt }` | +| `apps/game` | `brackets` table | locked bracket with 104 match predictions + cup-winner, deterministic `share_guid`, `locked_at` from the bot's last save event | + +`is_bot` and the humanness JSONL ride on Agent A1's auth-sms migration. +This CLI defensively adds the `is_bot` column if it does not yet exist, +so seed runs are order-independent against A1. + +## Algorithm (spec section 4 in one paragraph) + +1. Roll a personality: `chalk_score` from a truncated normal with mean + 0.78 in [0.65, 0.90] plus an engagement tier (10% high, 30% medium, + 60% low). +2. Roll a favourite team from the cup-winner prior. +3. Roll an identity: country (25% UK/IE, 15% USA, 10% AU/NZ, 8% BR/AR, + balance across 22 locales), first name + last name from the + country's public-domain corpus, handle composed as + `firstname__`. +4. Pick an avatar: 33% AI-faces, 33% Dicebear SVG, 34% initials. +5. Pick every match using + `favourite_p = chalk_score + (chalk_score - 0.5) * stage_amp` + clamped to the stage's range, with a +0.06 draw bias on group + matches. Cup winner is sharpened from the prior by raising each + nation's probability to `1 + 4 * (chalk_score - 0.5)` and + renormalising. +6. Roll an activity timeline: ~33% backdated 26 May - 6 June, + ~67% ramping 7 - 11 June, clustered evenings / weekends / press + dates. High-engagement bots save 3-5 times, medium 1-2, low once. + +The master seed is hardcoded at `tournamental-2026-seed-v1`. Override +with `--seed=` for development experiments only; production +must use the canonical seed so re-runs are stable. + +## Validation targets + +- Favourite rate: 75% +- 2pp +- Group draw rate: 15% +- 2pp +- Top-6 cup winner concentration (BRA, FRA, ARG, ENG, ESP, GER): >= 82% + +If any of these miss on the generated cohort, the CLI prints `FAIL` and +exits 1 before touching any store. The test suite enforces the same +bounds on a 100-bot smoke cohort at +-3pp (sampling noise is bigger on +n=100). + +## Idempotency + +- Bot ids are derived deterministically from the master seed and the + index, so a re-run with the same `--target` writes the same ids. +- `auth-sms.user` upsert uses `ON CONFLICT(id) DO UPDATE`. +- `humanness-scores.jsonl` skips existing entries on re-write. +- `game.brackets` upsert uses `ON CONFLICT(id) DO UPDATE`. + +`--purge` removes every `bot_%` row from all three stores. Safe to run +mid-tournament if we ever need to nuke and reseed. + +## Tests + +```bash +pnpm --filter @tournamental/seed-bots test +``` + +Asserts: +- 100 bots are byte-deterministic across two runs. +- 100 bots pass the validation targets within +-3pp. +- 200 bots respect the engagement tier weights. +- handles always have shape `firstname_team3_NN`. + +## Data files + +- `data/names/.json`: public-domain first + last name corpora, + one file per country code. Eleven files bundled at v0.1; the 22-locale + distribution falls back to cultural-neighbour corpora for any code + without a dedicated file. +- `data/odds-snapshot.json`: frozen probability snapshot for the 104 + matches plus the cup-winner prior. Generated offline from the + canonical fixtures with `scripts/build-odds-snapshot.py`. +- `data/avatars/faces/`: placeholder for the synthetic 6,000-image face + set Tim ships out-of-band. The CLI itself only writes URL pointers. + +## File layout + +``` +apps/seed-bots/ + README.md + package.json + tsconfig.json + vitest.config.ts + src/ + index.ts (CLI entry) + seed.ts (orchestrator) + personalities.ts (chalk_score + engagement_tier roller) + names.ts (country-weighted identity roller) + avatars.ts (3-pool avatar picker) + brackets.ts (per-match algorithm) + timeline.ts (created_at + save events) + write.ts (three-store writer + purger) + rng.ts (deterministic PRNG helpers) + data/ + names/{ar,au,br,de,es,fr,gb,ie,it,jp,nz,us}.json + odds-snapshot.json + avatars/faces/.gitkeep + scripts/ + build-odds-snapshot.py + test/ + seed.test.ts +``` diff --git a/apps/seed-bots/data/avatars/faces/.gitkeep b/apps/seed-bots/data/avatars/faces/.gitkeep new file mode 100644 index 00000000..018b43d7 --- /dev/null +++ b/apps/seed-bots/data/avatars/faces/.gitkeep @@ -0,0 +1,11 @@ +Vendored synthetic-face set lands here. + +The seed-bots avatar picker references URLs of the form +`/avatars/faces/face-NNNN.webp` for the 33% of bots assigned the "face" +pool. The renderer expects 6,000 images named `face-0001.webp` through +`face-6000.webp` (4-digit, zero-padded, 1-indexed). + +These images are CC0 / public-domain-equivalent synthetic faces (no real +subjects). Tim provisions the set out-of-band so the source files do not +land in the seed-bots PR diff. The seed CLI itself does not read these +files; it only writes URL pointers. diff --git a/apps/seed-bots/data/names/ar.json b/apps/seed-bots/data/names/ar.json new file mode 100644 index 00000000..e0100ec9 --- /dev/null +++ b/apps/seed-bots/data/names/ar.json @@ -0,0 +1,29 @@ +{ + "_source": "Argentina RENAPER frequently occurring names (public domain)", + "first": [ + "Mateo", "Benjamin", "Bautista", "Santiago", "Joaquin", "Lautaro", "Thiago", "Lorenzo", "Felipe", "Tomas", + "Juan", "Benicio", "Valentino", "Bruno", "Salvador", "Dante", "Francisco", "Vicente", "Ciro", "Jeronimo", + "Gael", "Augusto", "Maximo", "Ramiro", "Simon", "Gaspar", "Camilo", "Theo", "Lucas", "Diego", + "Matias", "Nicolas", "Agustin", "Facundo", "Ignacio", "Federico", "Martin", "Sebastian", "Maximiliano", "Emiliano", + "Manuel", "Cristian", "Andres", "Hernan", "Pablo", "Diego", "Hugo", "Eduardo", "Luis", "Marcelo", + "Sofia", "Olivia", "Mia", "Emma", "Catalina", "Isabella", "Valentina", "Martina", "Julieta", "Emilia", + "Renata", "Bianca", "Lola", "Antonella", "Pilar", "Maria", "Lucia", "Camila", "Delfina", "Constanza", + "Abril", "Felicitas", "Guadalupe", "Josefina", "Magdalena", "Mora", "Paloma", "Rosario", "Salome", "Trinidad", + "Victoria", "Agustina", "Antonia", "Aurora", "Catalina", "Celeste", "Clara", "Florencia", "Francesca", "Helena", + "Inés", "Juliana", "Ludmila", "Maite", "Manuela", "Marina", "Micaela", "Milagros", "Nina", "Paula", + "Renata", "Romina", "Sara", "Tamara", "Valeria" + ], + "last": [ + "Gonzalez", "Rodriguez", "Gomez", "Fernandez", "Lopez", "Diaz", "Martinez", "Perez", "Garcia", "Sanchez", + "Romero", "Sosa", "Alvarez", "Torres", "Ruiz", "Ramirez", "Flores", "Acosta", "Benitez", "Medina", + "Suarez", "Herrera", "Aguirre", "Pereyra", "Gutierrez", "Gimenez", "Quiroga", "Ferreyra", "Cabrera", "Castro", + "Molina", "Ortiz", "Silva", "Rojas", "Luna", "Juarez", "Mendoza", "Carrizo", "Ledesma", "Castillo", + "Vega", "Vera", "Maldonado", "Ojeda", "Cardozo", "Vazquez", "Ramos", "Coronel", "Paz", "Bustos", + "Arias", "Salas", "Roldan", "Andrada", "Quintana", "Aguilar", "Reyes", "Olivera", "Iglesias", "Maidana", + "Bravo", "Velazquez", "Toledo", "Navarro", "Ortega", "Funes", "Maciel", "Brizuela", "Nieto", "Ponce", + "Soria", "Soto", "Saavedra", "Lucero", "Riquelme", "Argañaraz", "Belmonte", "Bidondo", "Cabello", "Cano", + "Caro", "Casas", "Centurion", "Chavez", "Chazarreta", "Colombo", "Contreras", "Corrales", "Costa", "Crispin", + "D'Amico", "De La Fuente", "Del Valle", "Delgado", "Dominguez", "Duarte", "Echavarria", "Escudero", "Espinosa", "Estrada", + "Falcon", "Figueroa", "Frias", "Galarza", "Gallardo" + ] +} diff --git a/apps/seed-bots/data/names/au.json b/apps/seed-bots/data/names/au.json new file mode 100644 index 00000000..afe4cb57 --- /dev/null +++ b/apps/seed-bots/data/names/au.json @@ -0,0 +1,29 @@ +{ + "_source": "AU state birth registries top names (public domain)", + "first": [ + "Oliver", "Noah", "Jack", "William", "Leo", "Lucas", "Henry", "Charlie", "Thomas", "James", + "Liam", "Hudson", "Hunter", "Mason", "Theodore", "Ethan", "Archer", "Mason", "Ezra", "Sebastian", + "Harvey", "Joshua", "Benjamin", "Levi", "Beau", "Cooper", "Max", "George", "Patrick", "Riley", + "Lachlan", "Toby", "Hugo", "Reuben", "Asher", "Eli", "Jasper", "Jaxon", "Kai", "Logan", + "Carter", "Connor", "Jordan", "Caleb", "Aiden", "Dylan", "Flynn", "Phoenix", "Xavier", "Zachary", + "Charlotte", "Isla", "Olivia", "Mia", "Amelia", "Ava", "Sophie", "Grace", "Chloe", "Ella", + "Harper", "Willow", "Evie", "Matilda", "Layla", "Ruby", "Ivy", "Sienna", "Lily", "Aria", + "Sophia", "Sadie", "Audrey", "Maya", "Eden", "Emily", "Hazel", "Indie", "Frankie", "Stella", + "Aurora", "Bella", "Eleanor", "Penelope", "Scarlett", "Zara", "Mila", "Pippa", "Florence", "Hannah", + "Isabella", "Mackenzie", "Madison", "Maeve", "Ella", "Eloise", "Imogen", "Marlie", "Poppy", "Tilly", + "Sasha", "Bonnie", "Holly", "Jasmine", "Eva" + ], + "last": [ + "Smith", "Jones", "Williams", "Brown", "Wilson", "Taylor", "Johnson", "White", "Martin", "Anderson", + "Thompson", "Nguyen", "Thomas", "Walker", "Harris", "Lee", "Ryan", "Robinson", "Kelly", "King", + "Davis", "Wright", "Evans", "Roberts", "Green", "Hall", "Wood", "Jackson", "Clark", "Lewis", + "Hill", "Scott", "Young", "Mitchell", "Stewart", "Edwards", "Murphy", "Cooper", "Ward", "Morris", + "Watson", "Phillips", "Cox", "Bell", "Henderson", "Bailey", "Mason", "Murray", "Webb", "Hunter", + "Hughes", "Allen", "Foster", "Russell", "Reid", "Bennett", "Howard", "Singh", "Patel", "Sutton", + "Macdonald", "Marshall", "Reynolds", "Stevens", "Carter", "Adams", "Baker", "Mills", "Spencer", "Webster", + "Burns", "Holmes", "Hudson", "Dunn", "Fisher", "Pearson", "Ryder", "Gibson", "Knight", "Ford", + "Lawson", "Bailey", "Coleman", "Curtis", "Owen", "Riley", "Fox", "Holland", "McDonald", "Cunningham", + "McKenzie", "Banks", "Buckley", "Norris", "Page", "Saunders", "Andrews", "Newman", "Williamson", "Knox", + "Booth", "Brookes", "Casey", "Davidson", "Dixon" + ] +} diff --git a/apps/seed-bots/data/names/br.json b/apps/seed-bots/data/names/br.json new file mode 100644 index 00000000..d7c3a699 --- /dev/null +++ b/apps/seed-bots/data/names/br.json @@ -0,0 +1,29 @@ +{ + "_source": "Brasil IBGE/civil registry frequently occurring names (public domain)", + "first": [ + "Miguel", "Arthur", "Bernardo", "Heitor", "Davi", "Lorenzo", "Theo", "Pedro", "Gabriel", "Enzo", + "Matheus", "Lucas", "Benjamin", "Nicolas", "Guilherme", "Rafael", "Joaquim", "Samuel", "Enzo Gabriel", "Joao", + "Joao Miguel", "Henrique", "Gustavo", "Murilo", "Pedro Henrique", "Pietro", "Lucca", "Felipe", "Joao Pedro", "Isaac", + "Benicio", "Daniel", "Anthony", "Leonardo", "Davi Lucca", "Bryan", "Eduardo", "Joao Lucas", "Victor", "Joao Gabriel", + "Cauã", "Antonio", "Vicente", "Caio", "Diego", "Tiago", "Marcelo", "Alexandre", "Andre", "Bruno", + "Helena", "Alice", "Laura", "Maria Alice", "Sophia", "Manuela", "Maria Julia", "Valentina", "Heloisa", "Luiza", + "Maria Luiza", "Lara", "Maria Eduarda", "Beatriz", "Marina", "Mariana", "Giovanna", "Gabriela", "Rafaela", "Isabella", + "Maria Clara", "Sarah", "Lavinia", "Cecilia", "Eloah", "Esther", "Ana Clara", "Yasmin", "Maitê", "Ana Julia", + "Bianca", "Ana Laura", "Ana", "Olivia", "Maria", "Antonella", "Maria Fernanda", "Larissa", "Maria Cecilia", "Elisa", + "Liz", "Pietra", "Stella", "Maria Helena", "Catarina", "Lorena", "Carolina", "Vitoria", "Agatha", "Mirella", + "Joana", "Aurora", "Maria Sophia", "Alana", "Antonia" + ], + "last": [ + "Silva", "Santos", "Oliveira", "Souza", "Rodrigues", "Ferreira", "Alves", "Pereira", "Lima", "Gomes", + "Costa", "Ribeiro", "Martins", "Carvalho", "Almeida", "Lopes", "Soares", "Fernandes", "Vieira", "Barbosa", + "Rocha", "Dias", "Nascimento", "Andrade", "Moreira", "Nunes", "Marques", "Machado", "Mendes", "Freitas", + "Cardoso", "Ramos", "Goncalves", "Santana", "Teixeira", "Correia", "Cavalcanti", "Castro", "Campos", "Araujo", + "Cunha", "Reis", "Pinto", "Moraes", "Melo", "Sousa", "Borges", "Monteiro", "Cardoso", "Brito", + "Sales", "Aragão", "Bezerra", "Câmara", "Coelho", "Diniz", "Drumond", "Esteves", "Furtado", "Galvão", + "Guerra", "Ibrahim", "Jardim", "Junqueira", "Knust", "Lacerda", "Magalhães", "Neves", "Negrão", "Otero", + "Pessoa", "Quevedo", "Rangel", "Sá", "Tavares", "Uchôa", "Vargas", "Watanabe", "Xavier", "Zanetti", + "Avila", "Brandão", "Carneiro", "Damasceno", "Eufrásio", "Falcão", "Garcia", "Hirsch", "Iglesias", "Júlio", + "Kawasaki", "Lourenço", "Maia", "Nazário", "Ortiz", "Padilha", "Queiroz", "Resende", "Sant'Anna", "Trindade", + "Ulhôa", "Velasco", "Westphal", "Yamamoto", "Zampieri" + ] +} diff --git a/apps/seed-bots/data/names/de.json b/apps/seed-bots/data/names/de.json new file mode 100644 index 00000000..0f5ed7a4 --- /dev/null +++ b/apps/seed-bots/data/names/de.json @@ -0,0 +1,29 @@ +{ + "_source": "Germany Gesellschaft für deutsche Sprache popular names (public domain)", + "first": [ + "Noah", "Matteo", "Leon", "Finn", "Elias", "Paul", "Emil", "Henry", "Louis", "Ben", + "Liam", "Theo", "Felix", "Jonas", "Anton", "Luis", "Oskar", "Maximilian", "Karl", "Mats", + "Erik", "Jakob", "Lukas", "Alexander", "Moritz", "Tim", "Linus", "Nils", "Jan", "David", + "Levi", "Mika", "Samuel", "Tom", "Julian", "Hannes", "Vincent", "Constantin", "Florian", "Sebastian", + "Niklas", "Philip", "Lasse", "Mohammed", "Adam", "Adrian", "Aaron", "Jonathan", "Marlon", "Damian", + "Emilia", "Sophia", "Hannah", "Mia", "Mila", "Lina", "Marie", "Lea", "Ella", "Klara", + "Anna", "Leonie", "Ida", "Sophie", "Frieda", "Greta", "Helena", "Pauline", "Charlotte", "Lara", + "Emma", "Amelie", "Lia", "Lotta", "Lilly", "Luisa", "Mathilda", "Theresa", "Johanna", "Maja", + "Mara", "Romy", "Nina", "Stella", "Antonia", "Carlotta", "Elisa", "Magdalena", "Vivien", "Annika", + "Karla", "Hedi", "Nele", "Henriette", "Lena", "Felicitas", "Wilhelmina", "Pia", "Liv", "Emely", + "Eleni", "Eda", "Pauline", "Klara", "Eve" + ], + "last": [ + "Müller", "Schmidt", "Schneider", "Fischer", "Weber", "Meyer", "Wagner", "Becker", "Schulz", "Hoffmann", + "Schäfer", "Koch", "Bauer", "Richter", "Klein", "Wolf", "Schröder", "Neumann", "Schwarz", "Zimmermann", + "Braun", "Krüger", "Hofmann", "Hartmann", "Lange", "Schmitt", "Werner", "Schmitz", "Krause", "Meier", + "Lehmann", "Schmid", "Schulze", "Maier", "Köhler", "Herrmann", "König", "Walter", "Mayer", "Huber", + "Kaiser", "Fuchs", "Peters", "Lang", "Scholz", "Möller", "Weiß", "Jung", "Hahn", "Schubert", + "Vogel", "Friedrich", "Keller", "Günther", "Frank", "Berger", "Winkler", "Roth", "Beck", "Lorenz", + "Baumann", "Franke", "Albrecht", "Schuster", "Simon", "Ludwig", "Böhm", "Winter", "Kraus", "Martin", + "Schumacher", "Krämer", "Vogt", "Stein", "Jäger", "Otto", "Sommer", "Groß", "Seidel", "Heinrich", + "Brandt", "Haas", "Schreiber", "Graf", "Schulte", "Dietrich", "Ziegler", "Kuhn", "Kühn", "Pohl", + "Engel", "Horn", "Busch", "Bergmann", "Thomas", "Voigt", "Sauer", "Arnold", "Wolff", "Pfeiffer", + "Schwartz", "Ebert", "Adam", "Schenk", "Tietz" + ] +} diff --git a/apps/seed-bots/data/names/es.json b/apps/seed-bots/data/names/es.json new file mode 100644 index 00000000..68a5f8cf --- /dev/null +++ b/apps/seed-bots/data/names/es.json @@ -0,0 +1,29 @@ +{ + "_source": "Spain INE frequently occurring names (public domain)", + "first": [ + "Hugo", "Martin", "Daniel", "Mateo", "Pablo", "Alejandro", "Lucas", "Adrian", "Manuel", "Leo", + "Diego", "Javier", "Marco", "Alvaro", "David", "Sergio", "Marcos", "Mario", "Carlos", "Antonio", + "Adam", "Aaron", "Bruno", "Enzo", "Eric", "Gabriel", "Gael", "Hector", "Hugo", "Ian", + "Iker", "Izan", "Jose", "Joel", "Jorge", "Juan", "Liam", "Luca", "Luis", "Marc", + "Miguel", "Nicolas", "Noah", "Oscar", "Pedro", "Rafael", "Raul", "Ruben", "Samuel", "Thiago", + "Lucia", "Sofia", "Martina", "Maria", "Julia", "Paula", "Daniela", "Valeria", "Alba", "Emma", + "Noa", "Sara", "Carla", "Lola", "Vega", "Olivia", "Carmen", "Ana", "Aitana", "Marta", + "Andrea", "Claudia", "Adriana", "Laia", "Mia", "Chloe", "Triana", "Manuela", "Elena", "Inés", + "Jimena", "Lara", "Leire", "Marina", "Mireia", "Nora", "Paula", "Rocio", "Sofia", "Valentina", + "Vera", "Yaiza", "Zoe", "Abril", "Ainhoa", "Alicia", "Alma", "Amaia", "Amelia", "Angela", + "Anna", "Ariadna", "Aroa", "Beatriz", "Berta" + ], + "last": [ + "Garcia", "Rodriguez", "Gonzalez", "Fernandez", "Lopez", "Martinez", "Sanchez", "Perez", "Gomez", "Martin", + "Jimenez", "Ruiz", "Hernandez", "Diaz", "Moreno", "Muñoz", "Alvarez", "Romero", "Alonso", "Gutierrez", + "Navarro", "Torres", "Dominguez", "Vazquez", "Ramos", "Gil", "Ramirez", "Serrano", "Blanco", "Suarez", + "Molina", "Morales", "Ortega", "Delgado", "Castro", "Ortiz", "Rubio", "Marin", "Sanz", "Iglesias", + "Nuñez", "Medina", "Garrido", "Cortes", "Castillo", "Santos", "Lozano", "Guerrero", "Cano", "Prieto", + "Mendez", "Calvo", "Cruz", "Gallego", "Vidal", "Leon", "Marquez", "Herrera", "Peña", "Flores", + "Cabrera", "Campos", "Vega", "Fuentes", "Carrasco", "Diez", "Caballero", "Reyes", "Nieto", "Aguilar", + "Pascual", "Santana", "Herrero", "Lorenzo", "Hidalgo", "Gimenez", "Ibañez", "Ferrer", "Duran", "Santiago", + "Vicente", "Benitez", "Mora", "Vargas", "Arias", "Carmona", "Crespo", "Roman", "Pastor", "Soto", + "Saez", "Velasco", "Soler", "Esteban", "Parra", "Bravo", "Gallardo", "Rojas", "Pardo", "Merino", + "Franco", "Espinosa", "Izquierdo", "Andres", "Bermejo" + ] +} diff --git a/apps/seed-bots/data/names/fr.json b/apps/seed-bots/data/names/fr.json new file mode 100644 index 00000000..fde29a86 --- /dev/null +++ b/apps/seed-bots/data/names/fr.json @@ -0,0 +1,29 @@ +{ + "_source": "France INSEE registered births (public domain)", + "first": [ + "Gabriel", "Leo", "Raphael", "Arthur", "Louis", "Lucas", "Adam", "Jules", "Hugo", "Maël", + "Liam", "Sacha", "Ethan", "Noah", "Tiago", "Nathan", "Mohamed", "Paul", "Aaron", "Eden", + "Isaac", "Aymar", "Theo", "Tom", "Augustin", "Antoine", "Martin", "Marius", "Mathis", "Robin", + "Sami", "Naël", "Yanis", "Achille", "Adrien", "Alexandre", "Ali", "Amir", "Ayden", "Basile", + "Benjamin", "Côme", "Diego", "Eliott", "Elie", "Esteban", "Gaspard", "Imran", "Jean", "Joseph", + "Jade", "Louise", "Emma", "Ambre", "Alice", "Lina", "Rose", "Anna", "Mia", "Chloe", + "Iris", "Camille", "Inaya", "Lou", "Léa", "Sofia", "Léna", "Olivia", "Romy", "Maya", + "Eva", "Manon", "Lilou", "Lola", "Charlotte", "Lina", "Margaux", "Lucie", "Apolline", "Ines", + "Eva", "Constance", "Adèle", "Agathe", "Albane", "Alma", "Aliyah", "Anaëlle", "Anouk", "Aria", + "Capucine", "Charlie", "Clara", "Diane", "Eléonore", "Elsa", "Garance", "Giulia", "Hélène", "Juliette", + "Léna", "Marion", "Maelys", "Noor", "Yasmine" + ], + "last": [ + "Martin", "Bernard", "Dubois", "Thomas", "Robert", "Richard", "Petit", "Durand", "Leroy", "Moreau", + "Simon", "Laurent", "Lefebvre", "Michel", "Garcia", "David", "Bertrand", "Roux", "Vincent", "Fournier", + "Morel", "Girard", "Andre", "Lefevre", "Mercier", "Dupont", "Lambert", "Bonnet", "Francois", "Martinez", + "Legrand", "Garnier", "Faure", "Rousseau", "Blanc", "Guerin", "Muller", "Henry", "Roussel", "Nicolas", + "Perrin", "Morin", "Mathieu", "Clement", "Gauthier", "Dumont", "Lopez", "Fontaine", "Chevalier", "Robin", + "Masson", "Sanchez", "Gerard", "Nguyen", "Boyer", "Denis", "Lemaire", "Duval", "Joly", "Gautier", + "Roger", "Roche", "Roy", "Noel", "Meyer", "Lucas", "Meunier", "Jean", "Perez", "Marchand", + "Dufour", "Blanchard", "Marie", "Barbier", "Brun", "Dumas", "Brunet", "Schmitt", "Leroux", "Colin", + "Fernandez", "Pierre", "Renard", "Arnaud", "Rolland", "Caron", "Aubert", "Giraud", "Leclerc", "Vidal", + "Bourgeois", "Renaud", "Olivier", "Picard", "Roy", "Lacroix", "Carpentier", "Gaillard", "Charpentier", "Cousin", + "Hubert", "Maillard", "Le Gall", "Dupuis", "Riviere" + ] +} diff --git a/apps/seed-bots/data/names/gb.json b/apps/seed-bots/data/names/gb.json new file mode 100644 index 00000000..7fb2ef70 --- /dev/null +++ b/apps/seed-bots/data/names/gb.json @@ -0,0 +1,29 @@ +{ + "_source": "UK ONS frequently occurring forenames/surnames (public domain)", + "first": [ + "Oliver", "George", "Harry", "Jack", "Jacob", "Noah", "Charlie", "Muhammad", "Thomas", "Oscar", + "William", "James", "Henry", "Leo", "Alfie", "Joshua", "Freddie", "Archie", "Ethan", "Isaac", + "Alexander", "Joseph", "Edward", "Logan", "Theodore", "Lucas", "Mohammed", "Finley", "Samuel", "Arthur", + "Daniel", "Dylan", "Tommy", "Benjamin", "Max", "Sebastian", "Adam", "Riley", "Reuben", "Hugo", + "Toby", "Ronnie", "Albie", "Elijah", "Frankie", "Mason", "Louie", "Tobias", "Aaron", "Theo", + "Olivia", "Amelia", "Isla", "Ava", "Mia", "Isabella", "Sophia", "Grace", "Lily", "Freya", + "Emily", "Ivy", "Ella", "Rosie", "Evie", "Florence", "Poppy", "Charlotte", "Willow", "Evelyn", + "Elsie", "Daisy", "Maya", "Sienna", "Sophie", "Phoebe", "Erin", "Alice", "Aria", "Ruby", + "Bonnie", "Mila", "Hallie", "Holly", "Maisie", "Penelope", "Lola", "Esme", "Eva", "Harper", + "Matilda", "Robyn", "Eliza", "Imogen", "Layla", "Lottie", "Heidi", "Beatrice", "Maeve", "Skye", + "Niamh", "Darcie", "Ada", "Lyla", "Aurora" + ], + "last": [ + "Smith", "Jones", "Williams", "Taylor", "Davies", "Brown", "Wilson", "Evans", "Thomas", "Johnson", + "Roberts", "Walker", "Robinson", "Wright", "Thompson", "White", "Hughes", "Edwards", "Green", "Hall", + "Lewis", "Harris", "Clarke", "Patel", "Jackson", "Wood", "Turner", "Martin", "Cooper", "Hill", + "Ward", "Morris", "Moore", "Clark", "Lee", "King", "Baker", "Harrison", "Morgan", "Allen", + "James", "Scott", "Phillips", "Watson", "Davis", "Parker", "Price", "Bennett", "Young", "Griffiths", + "Mitchell", "Kelly", "Cook", "Carter", "Richardson", "Bailey", "Collins", "Bell", "Shaw", "Murphy", + "Mason", "Mills", "Stevens", "Hunt", "Webb", "Ellis", "Knight", "Russell", "Marshall", "Hunter", + "Murray", "Holmes", "Newton", "Lawson", "Burton", "Fox", "Reid", "Watts", "Spencer", "Stone", + "Burns", "Hudson", "Owen", "Howard", "Andrews", "Reynolds", "Hart", "Webster", "Harvey", "Read", + "Wilkinson", "Brookes", "Lawrence", "Riley", "Stevenson", "Pearce", "Powell", "Ross", "Page", "Holland", + "Wells", "Long", "Foster", "Reed", "Barker" + ] +} diff --git a/apps/seed-bots/data/names/ie.json b/apps/seed-bots/data/names/ie.json new file mode 100644 index 00000000..01724af0 --- /dev/null +++ b/apps/seed-bots/data/names/ie.json @@ -0,0 +1,29 @@ +{ + "_source": "Ireland CSO frequently occurring names (public domain)", + "first": [ + "Jack", "James", "Daniel", "Conor", "Sean", "Cian", "Adam", "Liam", "Patrick", "Michael", + "Charlie", "Harry", "Noah", "Tadhg", "Oisin", "Finn", "Darragh", "Eoin", "Aaron", "Ethan", + "Luke", "Rory", "Cathal", "Ciaran", "Killian", "Niall", "Diarmuid", "Fionn", "Ruairi", "Ben", + "Cormac", "Donal", "Brian", "Padraig", "Eoghan", "Senan", "Donnacha", "Lorcan", "Caolan", "Ronan", + "Mark", "Kevin", "Andrew", "Joseph", "Matthew", "David", "Christopher", "Thomas", "Stephen", "Paul", + "Emily", "Grace", "Sophie", "Saoirse", "Sarah", "Lily", "Hannah", "Anna", "Mia", "Ava", + "Sophia", "Aoife", "Niamh", "Ella", "Caoimhe", "Ciara", "Lucy", "Roisin", "Aine", "Sinead", + "Maeve", "Clodagh", "Orla", "Caitlin", "Siobhan", "Eimear", "Aisling", "Bronagh", "Deirdre", "Aoibhe", + "Aoibheann", "Caoimhe", "Cara", "Catriona", "Cliona", "Croia", "Doireann", "Eabha", "Eadaoin", "Eilis", + "Erin", "Fiadh", "Iona", "Kayleigh", "Lauren", "Leah", "Maire", "Muireann", "Nora", "Pippa", + "Roisin", "Roisin", "Tara", "Una", "Zara", "Holly", "Eve" + ], + "last": [ + "Murphy", "Kelly", "O'Sullivan", "Walsh", "Smith", "O'Brien", "Byrne", "Ryan", "O'Connor", "O'Neill", + "O'Reilly", "Doyle", "McCarthy", "Gallagher", "O'Doherty", "Kennedy", "Lynch", "Murray", "Quinn", "Moore", + "McLaughlin", "Carroll", "Connolly", "Daly", "Wilson", "Dunne", "Brennan", "Burke", "Collins", "Campbell", + "Clarke", "Johnston", "Hughes", "O'Farrell", "Fitzgerald", "Brown", "Martin", "Maguire", "Nolan", "Flynn", + "Thompson", "Callaghan", "O'Donnell", "Duffy", "Mahony", "Boyle", "Healy", "Shea", "White", "Sweeney", + "Hayes", "Kavanagh", "Power", "McGrath", "Moran", "Brady", "Stewart", "Casey", "Foley", "Fitzpatrick", + "Leary", "McDonnell", "MacMahon", "Donnelly", "Regan", "Donovan", "Burns", "Flanagan", "Mullen", "Barry", + "Kane", "Robinson", "Cunningham", "Griffin", "Kenny", "Sheehan", "Ward", "Whelan", "Lyons", "Reid", + "Graham", "Higgins", "Cullen", "Keane", "King", "Maher", "MacCarthy", "Coyle", "Fox", "Rourke", + "Hogan", "Reilly", "McKenna", "Buckley", "O'Keeffe", "Lennon", "McDermott", "Monaghan", "Coleman", "Henry", + "McGuire", "Dempsey", "Mooney", "Gormley", "Joyce", "Bell", "Conroy" + ] +} diff --git a/apps/seed-bots/data/names/it.json b/apps/seed-bots/data/names/it.json new file mode 100644 index 00000000..7f12b090 --- /dev/null +++ b/apps/seed-bots/data/names/it.json @@ -0,0 +1,29 @@ +{ + "_source": "Italy ISTAT popular registered names (public domain)", + "first": [ + "Leonardo", "Francesco", "Lorenzo", "Alessandro", "Andrea", "Mattia", "Gabriele", "Tommaso", "Riccardo", "Edoardo", + "Matteo", "Diego", "Giuseppe", "Antonio", "Federico", "Davide", "Giovanni", "Filippo", "Pietro", "Nicolo", + "Cristian", "Samuele", "Marco", "Stefano", "Luca", "Simone", "Daniele", "Michele", "Vincenzo", "Salvatore", + "Emanuele", "Giulio", "Manuel", "Mario", "Christian", "Enrico", "Jacopo", "Liam", "Alessio", "Brando", + "Carlo", "Damiano", "Elia", "Ettore", "Filippo Maria", "Giacomo", "Iacopo", "Italo", "Lapo", "Massimo", + "Sofia", "Aurora", "Giulia", "Ginevra", "Beatrice", "Alice", "Vittoria", "Emma", "Greta", "Anna", + "Sara", "Giorgia", "Martina", "Chiara", "Bianca", "Noemi", "Camilla", "Asia", "Matilde", "Nicole", + "Mia", "Maria", "Elena", "Gaia", "Caterina", "Adele", "Francesca", "Margherita", "Sofia", "Cecilia", + "Eleonora", "Alessia", "Letizia", "Ludovica", "Rebecca", "Rachele", "Elisa", "Arianna", "Aurora", "Ambra", + "Angelica", "Costanza", "Elisabetta", "Iris", "Lavinia", "Lucrezia", "Marta", "Miriam", "Nina", "Olivia", + "Penelope", "Rita", "Stella", "Viola", "Ines" + ], + "last": [ + "Rossi", "Russo", "Ferrari", "Esposito", "Bianchi", "Romano", "Colombo", "Ricci", "Marino", "Greco", + "Bruno", "Gallo", "Conti", "De Luca", "Mancini", "Costa", "Giordano", "Rizzo", "Lombardi", "Moretti", + "Barbieri", "Fontana", "Santoro", "Mariani", "Rinaldi", "Caruso", "Ferrara", "Galli", "Martini", "Leone", + "Longo", "Gentile", "Martinelli", "Vitale", "Lombardo", "Serra", "Coppola", "De Santis", "D'Angelo", "Marchetti", + "Parisi", "Villa", "Conte", "Ferraro", "Ferri", "Fabbri", "Bianco", "Marini", "Grasso", "Valentini", + "Messina", "Sala", "De Angelis", "Gatti", "Pellegrini", "Palumbo", "Sanna", "Farina", "Rizzi", "Monti", + "Cattaneo", "Morelli", "Amato", "Silvestri", "Mazza", "Testa", "Grassi", "Pellegrino", "Carbone", "Giuliani", + "Benedetti", "Barone", "Rossetti", "Caputo", "Montanari", "Guerra", "Palmieri", "Bernardi", "Martino", "Fiore", + "De Rosa", "Ferretti", "Bellini", "Basile", "Riva", "Donati", "Piras", "Vitali", "Battaglia", "Sartori", + "Neri", "Costantini", "Milani", "Pagano", "Ruggiero", "Sorrentino", "D'Amico", "Orlando", "Damiani", "Negri", + "Marchi", "Cossu", "Coluccia", "Esposito", "Ranieri" + ] +} diff --git a/apps/seed-bots/data/names/jp.json b/apps/seed-bots/data/names/jp.json new file mode 100644 index 00000000..a29a6fb9 --- /dev/null +++ b/apps/seed-bots/data/names/jp.json @@ -0,0 +1,29 @@ +{ + "_source": "Japan Meiji Yasuda popular registered names romanised (public domain)", + "first": [ + "Haruto", "Yuto", "Sota", "Yuki", "Hayato", "Haruki", "Ryusei", "Kenta", "Takumi", "Ren", + "Sho", "Riku", "Daiki", "Kazuki", "Yuma", "Kaito", "Asahi", "Akito", "Sakutaro", "Yusei", + "Sosuke", "Itsuki", "Yamato", "Tatsuki", "Sora", "Hiroto", "Aoi", "Eita", "Ichigo", "Jin", + "Kai", "Kakeru", "Kanata", "Kiyoshi", "Koki", "Koshiro", "Kosuke", "Manato", "Masahiro", "Minato", + "Naoki", "Naoto", "Reo", "Ritsu", "Riito", "Ryo", "Ryoma", "Sosuke", "Shun", "Taichi", + "Takeru", "Tatsumi", "Teppei", "Tomoya", "Yoshiki", "Yusuke", "Aiko", "Akari", "Aoi", "Asuka", + "Ayaka", "Chinatsu", "Emi", "Fumiko", "Hana", "Haruka", "Hina", "Hinata", "Hiroko", "Honoka", + "Ichiko", "Junko", "Kaede", "Kanako", "Kanami", "Kaori", "Kasumi", "Kazuko", "Kiyomi", "Kotoha", + "Kumiko", "Madoka", "Mai", "Maiko", "Mami", "Mao", "Mari", "Mariko", "Maya", "Mei", + "Michiko", "Mihoko", "Miki", "Miku", "Mio", "Miori", "Misa", "Mitsuko", "Miu", "Miyuki", + "Momoka", "Nami", "Nana", "Nao", "Yui" + ], + "last": [ + "Sato", "Suzuki", "Takahashi", "Tanaka", "Watanabe", "Ito", "Yamamoto", "Nakamura", "Kobayashi", "Kato", + "Yoshida", "Yamada", "Sasaki", "Yamaguchi", "Saito", "Matsumoto", "Inoue", "Kimura", "Hayashi", "Shimizu", + "Yamazaki", "Mori", "Abe", "Ikeda", "Hashimoto", "Yamashita", "Ishikawa", "Nakajima", "Maeda", "Fujita", + "Ogawa", "Goto", "Okada", "Hasegawa", "Murakami", "Kondo", "Ishii", "Saito", "Sakamoto", "Endo", + "Aoki", "Fujii", "Nishimura", "Fukuda", "Ota", "Miura", "Fujiwara", "Okamoto", "Matsuda", "Nakagawa", + "Nakano", "Harada", "Ono", "Tamura", "Takeuchi", "Kaneko", "Wada", "Nakayama", "Ishida", "Ueda", + "Morita", "Hara", "Shibata", "Sakai", "Kudo", "Yokoyama", "Miyazaki", "Miyamoto", "Uchida", "Takagi", + "Ando", "Taniguchi", "Otsuka", "Maruyama", "Imai", "Takada", "Fujimoto", "Takeda", "Murata", "Uemura", + "Yasuda", "Sugawara", "Komatsu", "Iwasaki", "Sakuma", "Noguchi", "Matsui", "Chiba", "Iwata", "Sugiyama", + "Iida", "Hayashi", "Maeda", "Otani", "Kawamura", "Mizuno", "Akiyama", "Sasamoto", "Shinohara", "Kanai", + "Shiraishi", "Kuwabara", "Tsuji", "Doi", "Yuasa" + ] +} diff --git a/apps/seed-bots/data/names/nz.json b/apps/seed-bots/data/names/nz.json new file mode 100644 index 00000000..59c2b0c7 --- /dev/null +++ b/apps/seed-bots/data/names/nz.json @@ -0,0 +1,29 @@ +{ + "_source": "NZ Department of Internal Affairs frequently occurring names (public domain)", + "first": [ + "Oliver", "Jack", "Noah", "Leo", "George", "William", "Hunter", "Mason", "Theodore", "James", + "Henry", "Charlie", "Lucas", "Liam", "Thomas", "Ethan", "Hudson", "Cooper", "Jasper", "Tama", + "Riley", "Levi", "Beau", "Harvey", "Kai", "Carter", "Jaxon", "Toby", "Archie", "Eli", + "Te Aroha", "Manaia", "Tane", "Aroha", "Mateo", "Asher", "Sebastian", "Caleb", "Connor", "Jacob", + "Alexander", "Benjamin", "Daniel", "Samuel", "Joshua", "Matthew", "Logan", "Lachlan", "Tyler", "Max", + "Charlotte", "Isla", "Olivia", "Mia", "Amelia", "Harper", "Sophie", "Ella", "Grace", "Aria", + "Maia", "Willow", "Evie", "Matilda", "Ivy", "Ruby", "Sienna", "Hazel", "Mila", "Lily", + "Stella", "Sophia", "Frankie", "Indie", "Tui", "Ana", "Aria", "Penelope", "Scarlett", "Eva", + "Layla", "Audrey", "Isabella", "Florence", "Eleanor", "Pippa", "Maeve", "Imogen", "Marama", "Aroha", + "Eden", "Hannah", "Holly", "Jasmine", "Mackenzie", "Phoebe", "Quinn", "Rose", "Tessa", "Anika", + "Emma", "Ava", "Chloe", "Lucy", "Maddison" + ], + "last": [ + "Smith", "Wilson", "Williams", "Brown", "Jones", "Taylor", "Anderson", "Thompson", "Walker", "Robinson", + "Stewart", "White", "Wright", "Clark", "Hall", "Young", "King", "Wood", "Roberts", "Campbell", + "Davis", "Lewis", "Mitchell", "Edwards", "Lee", "Green", "Harris", "Scott", "Morris", "Cooper", + "Bell", "Ward", "Watson", "Cox", "Murphy", "Phillips", "Webb", "Russell", "Carter", "Mason", + "Ngata", "Tapsell", "Hape", "Heke", "Reihana", "Wikiriwhi", "Te Aho", "Aramoana", "Whetu", "Manuel", + "Kahu", "Karaka", "Pomare", "Rangi", "Tahere", "Whata", "Wineera", "Tuhi", "Patel", "Singh", + "Kumar", "Chen", "Wang", "Liu", "Zhang", "Kim", "Lee", "Tran", "Nguyen", "Sharma", + "Reynolds", "Stevens", "Adams", "Baker", "Mills", "Spencer", "Burns", "Holmes", "Hudson", "Dunn", + "Fisher", "Gibson", "Knight", "Ford", "Lawson", "Coleman", "Owen", "Riley", "Fox", "Holland", + "Henare", "Mahuta", "Tirikatene", "Smith", "Cunningham", "McDonald", "McKenzie", "Banks", "Buckley", "Page", + "Saunders", "Newman", "Williamson", "Knox", "Booth", "Brookes", "Casey", "Davidson", "Dixon" + ] +} diff --git a/apps/seed-bots/data/names/us.json b/apps/seed-bots/data/names/us.json new file mode 100644 index 00000000..a25a62c3 --- /dev/null +++ b/apps/seed-bots/data/names/us.json @@ -0,0 +1,29 @@ +{ + "_source": "US Census Bureau frequently occurring names (public domain)", + "first": [ + "James", "John", "Robert", "Michael", "William", "David", "Richard", "Joseph", "Thomas", "Charles", + "Christopher", "Daniel", "Matthew", "Anthony", "Mark", "Donald", "Steven", "Paul", "Andrew", "Joshua", + "Kenneth", "Kevin", "Brian", "George", "Edward", "Ronald", "Timothy", "Jason", "Jeffrey", "Ryan", + "Jacob", "Gary", "Nicholas", "Eric", "Jonathan", "Stephen", "Larry", "Justin", "Scott", "Brandon", + "Benjamin", "Samuel", "Gregory", "Frank", "Alexander", "Raymond", "Patrick", "Jack", "Dennis", "Jerry", + "Mary", "Patricia", "Jennifer", "Linda", "Elizabeth", "Barbara", "Susan", "Jessica", "Sarah", "Karen", + "Lisa", "Nancy", "Betty", "Sandra", "Margaret", "Ashley", "Kimberly", "Emily", "Donna", "Michelle", + "Carol", "Amanda", "Melissa", "Deborah", "Stephanie", "Rebecca", "Laura", "Sharon", "Cynthia", "Kathleen", + "Amy", "Shirley", "Angela", "Helen", "Anna", "Brenda", "Pamela", "Nicole", "Samantha", "Katherine", + "Christine", "Emma", "Catherine", "Debra", "Virginia", "Rachel", "Carolyn", "Janet", "Maria", "Heather", + "Diane", "Ruth", "Julie", "Olivia", "Joyce", "Victoria", "Kelly", "Christina", "Lauren", "Joan" + ], + "last": [ + "Smith", "Johnson", "Williams", "Brown", "Jones", "Garcia", "Miller", "Davis", "Rodriguez", "Martinez", + "Hernandez", "Lopez", "Gonzalez", "Wilson", "Anderson", "Thomas", "Taylor", "Moore", "Jackson", "Martin", + "Lee", "Perez", "Thompson", "White", "Harris", "Sanchez", "Clark", "Ramirez", "Lewis", "Robinson", + "Walker", "Young", "Allen", "King", "Wright", "Scott", "Torres", "Nguyen", "Hill", "Flores", + "Green", "Adams", "Nelson", "Baker", "Hall", "Rivera", "Campbell", "Mitchell", "Carter", "Roberts", + "Gomez", "Phillips", "Evans", "Turner", "Diaz", "Parker", "Cruz", "Edwards", "Collins", "Reyes", + "Stewart", "Morris", "Morales", "Murphy", "Cook", "Rogers", "Gutierrez", "Ortiz", "Morgan", "Cooper", + "Peterson", "Bailey", "Reed", "Kelly", "Howard", "Ramos", "Kim", "Cox", "Ward", "Richardson", + "Watson", "Brooks", "Chavez", "Wood", "James", "Bennett", "Gray", "Mendoza", "Ruiz", "Hughes", + "Price", "Alvarez", "Castillo", "Sanders", "Patel", "Myers", "Long", "Ross", "Foster", "Jimenez", + "Powell", "Jenkins", "Perry", "Russell", "Sullivan", "Bell", "Coleman", "Butler", "Henderson", "Barnes" + ] +} diff --git a/apps/seed-bots/data/odds-snapshot.json b/apps/seed-bots/data/odds-snapshot.json new file mode 100644 index 00000000..178f0a67 --- /dev/null +++ b/apps/seed-bots/data/odds-snapshot.json @@ -0,0 +1,654 @@ +{ + "tournament_id": "fifa-wc-2026", + "groups": { + "1": { + "home_p": 0.8098, + "draw_p": 0.18, + "away_p": 0.0102, + "favourite_slot": "MEX" + }, + "2": { + "home_p": 0.6416, + "draw_p": 0.26, + "away_p": 0.0984, + "favourite_slot": "KOR" + }, + "3": { + "home_p": 0.5205, + "draw_p": 0.288, + "away_p": 0.1915, + "favourite_slot": "MEX" + }, + "4": { + "home_p": 0.5952, + "draw_p": 0.272, + "away_p": 0.1328, + "favourite_slot": "CZE" + }, + "5": { + "home_p": 0.0412, + "draw_p": 0.228, + "away_p": 0.7308, + "favourite_slot": "MEX" + }, + "6": { + "home_p": 0.0261, + "draw_p": 0.212, + "away_p": 0.7619, + "favourite_slot": "KOR" + }, + "7": { + "home_p": 0.7392, + "draw_p": 0.224, + "away_p": 0.0368, + "favourite_slot": "CAN" + }, + "8": { + "home_p": 0.0184, + "draw_p": 0.2, + "away_p": 0.7816, + "favourite_slot": "SUI" + }, + "9": { + "home_p": 0.7308, + "draw_p": 0.228, + "away_p": 0.0412, + "favourite_slot": "CAN" + }, + "10": { + "home_p": 0.7877, + "draw_p": 0.196, + "away_p": 0.0163, + "favourite_slot": "SUI" + }, + "11": { + "home_p": 0.4997, + "draw_p": 0.292, + "away_p": 0.2083, + "favourite_slot": "SUI" + }, + "12": { + "home_p": 0.3207, + "draw_p": 0.316, + "away_p": 0.3633, + "favourite_slot": "QAT" + }, + "13": { + "home_p": 0.5779, + "draw_p": 0.276, + "away_p": 0.1461, + "favourite_slot": "BRA" + }, + "14": { + "home_p": 0.0368, + "draw_p": 0.224, + "away_p": 0.7392, + "favourite_slot": "SCO" + }, + "15": { + "home_p": 0.8194, + "draw_p": 0.18, + "away_p": 0.0006, + "favourite_slot": "BRA" + }, + "16": { + "home_p": 0.0412, + "draw_p": 0.228, + "away_p": 0.7308, + "favourite_slot": "MAR" + }, + "17": { + "home_p": 0.0115, + "draw_p": 0.184, + "away_p": 0.8045, + "favourite_slot": "BRA" + }, + "18": { + "home_p": 0.8177, + "draw_p": 0.18, + "away_p": 0.0023, + "favourite_slot": "MAR" + }, + "19": { + "home_p": 0.8167, + "draw_p": 0.18, + "away_p": 0.0033, + "favourite_slot": "USA" + }, + "20": { + "home_p": 0.6116, + "draw_p": 0.268, + "away_p": 0.1204, + "favourite_slot": "AUS" + }, + "21": { + "home_p": 0.5405, + "draw_p": 0.284, + "away_p": 0.1755, + "favourite_slot": "USA" + }, + "22": { + "home_p": 0.7219, + "draw_p": 0.232, + "away_p": 0.0461, + "favourite_slot": "TUR" + }, + "23": { + "home_p": 0.0461, + "draw_p": 0.232, + "away_p": 0.7219, + "favourite_slot": "USA" + }, + "24": { + "home_p": 0.0102, + "draw_p": 0.18, + "away_p": 0.8098, + "favourite_slot": "AUS" + }, + "25": { + "home_p": 0.8184, + "draw_p": 0.18, + "away_p": 0.0016, + "favourite_slot": "GER" + }, + "26": { + "home_p": 0.0232, + "draw_p": 0.208, + "away_p": 0.7688, + "favourite_slot": "ECU" + }, + "27": { + "home_p": 0.8171, + "draw_p": 0.18, + "away_p": 0.0029, + "favourite_slot": "GER" + }, + "28": { + "home_p": 0.7991, + "draw_p": 0.188, + "away_p": 0.0129, + "favourite_slot": "ECU" + }, + "29": { + "home_p": 0.0798, + "draw_p": 0.252, + "away_p": 0.6682, + "favourite_slot": "GER" + }, + "30": { + "home_p": 0.2441, + "draw_p": 0.3, + "away_p": 0.4559, + "favourite_slot": "CIV" + }, + "31": { + "home_p": 0.5597, + "draw_p": 0.28, + "away_p": 0.1603, + "favourite_slot": "NED" + }, + "32": { + "home_p": 0.1603, + "draw_p": 0.28, + "away_p": 0.5597, + "favourite_slot": "TUN" + }, + "33": { + "home_p": 0.7816, + "draw_p": 0.2, + "away_p": 0.0184, + "favourite_slot": "NED" + }, + "34": { + "home_p": 0.1603, + "draw_p": 0.28, + "away_p": 0.5597, + "favourite_slot": "JPN" + }, + "35": { + "home_p": 0.0577, + "draw_p": 0.24, + "away_p": 0.7023, + "favourite_slot": "NED" + }, + "36": { + "home_p": 0.7023, + "draw_p": 0.24, + "away_p": 0.0577, + "favourite_slot": "JPN" + }, + "37": { + "home_p": 0.7547, + "draw_p": 0.216, + "away_p": 0.0293, + "favourite_slot": "BEL" + }, + "38": { + "home_p": 0.8138, + "draw_p": 0.18, + "away_p": 0.0062, + "favourite_slot": "IRN" + }, + "39": { + "home_p": 0.6116, + "draw_p": 0.268, + "away_p": 0.1204, + "favourite_slot": "BEL" + }, + "40": { + "home_p": 0.0293, + "draw_p": 0.216, + "away_p": 0.7547, + "favourite_slot": "EGY" + }, + "41": { + "home_p": 0.0012, + "draw_p": 0.18, + "away_p": 0.8188, + "favourite_slot": "BEL" + }, + "42": { + "home_p": 0.1204, + "draw_p": 0.268, + "away_p": 0.6116, + "favourite_slot": "IRN" + }, + "43": { + "home_p": 0.8199, + "draw_p": 0.18, + "away_p": 0.0001, + "favourite_slot": "ESP" + }, + "44": { + "home_p": 0.0002, + "draw_p": 0.18, + "away_p": 0.8198, + "favourite_slot": "URU" + }, + "45": { + "home_p": 0.8199, + "draw_p": 0.18, + "away_p": 0.0001, + "favourite_slot": "ESP" + }, + "46": { + "home_p": 0.8198, + "draw_p": 0.18, + "away_p": 0.0002, + "favourite_slot": "URU" + }, + "47": { + "home_p": 0.1755, + "draw_p": 0.284, + "away_p": 0.5405, + "favourite_slot": "ESP" + }, + "48": { + "home_p": 0.34, + "draw_p": 0.32, + "away_p": 0.34, + "favourite_slot": "CPV" + }, + "49": { + "home_p": 0.6803, + "draw_p": 0.248, + "away_p": 0.0717, + "favourite_slot": "FRA" + }, + "50": { + "home_p": 0.0023, + "draw_p": 0.18, + "away_p": 0.8177, + "favourite_slot": "NOR" + }, + "51": { + "home_p": 0.82, + "draw_p": 0.18, + "away_p": 0.0, + "favourite_slot": "FRA" + }, + "52": { + "home_p": 0.1204, + "draw_p": 0.268, + "away_p": 0.6116, + "favourite_slot": "SEN" + }, + "53": { + "home_p": 0.0163, + "draw_p": 0.196, + "away_p": 0.7877, + "favourite_slot": "FRA" + }, + "54": { + "home_p": 0.8195, + "draw_p": 0.18, + "away_p": 0.0005, + "favourite_slot": "SEN" + }, + "55": { + "home_p": 0.8188, + "draw_p": 0.18, + "away_p": 0.0012, + "favourite_slot": "ARG" + }, + "56": { + "home_p": 0.7023, + "draw_p": 0.24, + "away_p": 0.0577, + "favourite_slot": "AUT" + }, + "57": { + "home_p": 0.8098, + "draw_p": 0.18, + "away_p": 0.0102, + "favourite_slot": "ARG" + }, + "58": { + "home_p": 0.2819, + "draw_p": 0.308, + "away_p": 0.4101, + "favourite_slot": "ALG" + }, + "59": { + "home_p": 0.0008, + "draw_p": 0.18, + "away_p": 0.8192, + "favourite_slot": "ARG" + }, + "60": { + "home_p": 0.0798, + "draw_p": 0.252, + "away_p": 0.6682, + "favourite_slot": "AUT" + }, + "61": { + "home_p": 0.8199, + "draw_p": 0.18, + "away_p": 0.0001, + "favourite_slot": "POR" + }, + "62": { + "home_p": 0.0048, + "draw_p": 0.18, + "away_p": 0.8152, + "favourite_slot": "COL" + }, + "63": { + "home_p": 0.8182, + "draw_p": 0.18, + "away_p": 0.0018, + "favourite_slot": "POR" + }, + "64": { + "home_p": 0.8198, + "draw_p": 0.18, + "away_p": 0.0002, + "favourite_slot": "COL" + }, + "65": { + "home_p": 0.1915, + "draw_p": 0.288, + "away_p": 0.5205, + "favourite_slot": "POR" + }, + "66": { + "home_p": 0.0328, + "draw_p": 0.22, + "away_p": 0.7472, + "favourite_slot": "UZB" + }, + "67": { + "home_p": 0.4997, + "draw_p": 0.292, + "away_p": 0.2083, + "favourite_slot": "ENG" + }, + "68": { + "home_p": 0.627, + "draw_p": 0.264, + "away_p": 0.109, + "favourite_slot": "GHA" + }, + "69": { + "home_p": 0.7619, + "draw_p": 0.212, + "away_p": 0.0261, + "favourite_slot": "ENG" + }, + "70": { + "home_p": 0.0115, + "draw_p": 0.184, + "away_p": 0.8045, + "favourite_slot": "CRO" + }, + "71": { + "home_p": 0.0048, + "draw_p": 0.18, + "away_p": 0.8152, + "favourite_slot": "ENG" + }, + "72": { + "home_p": 0.7023, + "draw_p": 0.24, + "away_p": 0.0577, + "favourite_slot": "CRO" + } + }, + "knockouts": { + "73": { + "home_p": 0.5312, + "away_p": 0.4688, + "favourite_slot": "1A" + }, + "74": { + "home_p": 0.4688, + "away_p": 0.5312, + "favourite_slot": "2F" + }, + "75": { + "home_p": 0.9047, + "away_p": 0.0953, + "favourite_slot": "1C" + }, + "76": { + "home_p": 0.8355, + "away_p": 0.1645, + "favourite_slot": "1D" + }, + "77": { + "home_p": 0.8355, + "away_p": 0.1645, + "favourite_slot": "1E" + }, + "78": { + "home_p": 0.9047, + "away_p": 0.0953, + "favourite_slot": "1F" + }, + "79": { + "home_p": 0.6225, + "away_p": 0.3775, + "favourite_slot": "1G" + }, + "80": { + "home_p": 0.9047, + "away_p": 0.0953, + "favourite_slot": "1H" + }, + "81": { + "home_p": 0.7549, + "away_p": 0.2451, + "favourite_slot": "1I" + }, + "82": { + "home_p": 0.8355, + "away_p": 0.1645, + "favourite_slot": "1J" + }, + "83": { + "home_p": 0.977, + "away_p": 0.023, + "favourite_slot": "1K" + }, + "84": { + "home_p": 0.8808, + "away_p": 0.1192, + "favourite_slot": "1L" + }, + "85": { + "home_p": 0.5, + "away_p": 0.5, + "favourite_slot": "3A/B/C/D" + }, + "86": { + "home_p": 0.5, + "away_p": 0.5, + "favourite_slot": "3I/J/K/L" + }, + "87": { + "home_p": 0.5, + "away_p": 0.5, + "favourite_slot": "3C/D/G/H" + }, + "88": { + "home_p": 0.5, + "away_p": 0.5, + "favourite_slot": "3A/B/F/J" + }, + "89": { + "home_p": 0.5622, + "away_p": 0.4378, + "favourite_slot": "W73" + }, + "90": { + "home_p": 0.7311, + "away_p": 0.2689, + "favourite_slot": "W75" + }, + "91": { + "home_p": 0.4378, + "away_p": 0.5622, + "favourite_slot": "W78" + }, + "92": { + "home_p": 0.3486, + "away_p": 0.6514, + "favourite_slot": "W80" + }, + "93": { + "home_p": 0.4688, + "away_p": 0.5312, + "favourite_slot": "W82" + }, + "94": { + "home_p": 0.4378, + "away_p": 0.5622, + "favourite_slot": "W84" + }, + "95": { + "home_p": 0.5, + "away_p": 0.5, + "favourite_slot": "W85" + }, + "96": { + "home_p": 0.5, + "away_p": 0.5, + "favourite_slot": "W87" + }, + "97": { + "home_p": 0.2227, + "away_p": 0.7773, + "favourite_slot": "W90" + }, + "98": { + "home_p": 0.3775, + "away_p": 0.6225, + "favourite_slot": "W92" + }, + "99": { + "home_p": 0.5927, + "away_p": 0.4073, + "favourite_slot": "W93" + }, + "100": { + "home_p": 0.5, + "away_p": 0.5, + "favourite_slot": "W95" + }, + "101": { + "home_p": 0.4378, + "away_p": 0.5622, + "favourite_slot": "W98" + }, + "102": { + "home_p": 0.9999, + "away_p": 0.0001, + "favourite_slot": "W99" + }, + "103": { + "home_p": 0.5, + "away_p": 0.5, + "favourite_slot": "L101" + }, + "104": { + "home_p": 0.4378, + "away_p": 0.5622, + "favourite_slot": "W102" + } + }, + "cup_winner_prior": [ + { + "team3": "BRA", + "p": 0.2 + }, + { + "team3": "FRA", + "p": 0.17 + }, + { + "team3": "ARG", + "p": 0.16 + }, + { + "team3": "ENG", + "p": 0.13 + }, + { + "team3": "ESP", + "p": 0.12 + }, + { + "team3": "GER", + "p": 0.1 + }, + { + "team3": "POR", + "p": 0.05 + }, + { + "team3": "NED", + "p": 0.03 + }, + { + "team3": "ITA", + "p": 0.015 + }, + { + "team3": "BEL", + "p": 0.012 + }, + { + "team3": "URU", + "p": 0.008 + }, + { + "team3": "USA", + "p": 0.005 + } + ], + "_meta": { + "source": "FIFA ranking heuristic (May 2026 outlook)", + "generated_by": "apps/seed-bots/scripts/build-odds-snapshot.py", + "match_count": 104 + } +} \ No newline at end of file diff --git a/apps/seed-bots/package.json b/apps/seed-bots/package.json new file mode 100644 index 00000000..1e7b0d9a --- /dev/null +++ b/apps/seed-bots/package.json @@ -0,0 +1,30 @@ +{ + "name": "@tournamental/seed-bots", + "version": "0.1.0", + "private": true, + "description": "Deterministic CLI that seeds ~18k cosmetic humans-style bots for the Tournamental leaderboard.", + "type": "module", + "bin": { + "tournamental-seed-bots": "./dist/index.js" + }, + "scripts": { + "build": "tsc -p tsconfig.json", + "typecheck": "tsc -p tsconfig.json --noEmit", + "dev": "tsx src/index.ts", + "seed": "tsx src/index.ts", + "test": "vitest run", + "test:watch": "vitest" + }, + "dependencies": { + "better-sqlite3": "^11.3.0", + "seedrandom": "^3.0.5" + }, + "devDependencies": { + "@types/better-sqlite3": "^7.6.11", + "@types/node": "^20.14.10", + "@types/seedrandom": "^3.0.8", + "tsx": "^4.19.2", + "typescript": "^5.6.3", + "vitest": "^4.1.8" + } +} diff --git a/apps/seed-bots/scripts/build-odds-snapshot.py b/apps/seed-bots/scripts/build-odds-snapshot.py new file mode 100644 index 00000000..c169b87e --- /dev/null +++ b/apps/seed-bots/scripts/build-odds-snapshot.py @@ -0,0 +1,237 @@ +#!/usr/bin/env python3 +"""Generate apps/seed-bots/data/odds-snapshot.json from the canonical +WC 2026 fixtures plus a FIFA-ranking heuristic. + +The seed-bots CLI is deterministic and ships with a frozen Polymarket- +style odds snapshot so re-runs across machines produce identical bots. +This script builds that snapshot offline; check it in alongside the +data file. + +Heuristic (sufficient for cosmetic seed bots; real Polymarket pull will +replace this in Phase 2): + - Rank table loosely derived from May 2026 FIFA Ranking + qualifying + form. Lower rank = stronger team. + - For group matches: convert rank gap to home/draw/away probability + via a softmax-style mapping (logistic on rank delta). + - For knockouts: ignore the draw bucket. Knockout slots like "1A" / + "W73" are projected to the *predicted favourite-team-3* by walking + the bracket cascade with the best-ranked group team in each slot. + - Cup-winner prior: top 12 nations by ranking; mass concentrated on + the top 4. +""" + +import json +import math +import os +from collections import defaultdict +from pathlib import Path + +REPO = Path(__file__).resolve().parents[3] +FIXTURES = REPO / "data" / "fifa-wc-2026" / "fixtures.json" +OUT = REPO / "apps" / "seed-bots" / "data" / "odds-snapshot.json" + +# Loose FIFA-ranking heuristic. Lower index = stronger. +# Source: rough May 2026 outlook; pure heuristic so the cosmetic bots +# pick favourites that match the typical media narrative. The Tim-stated +# constraint is "no Saudi Arabia winners" and "top-6 cup winner +# concentration ~85%", both of which fall out of the cup_winner_prior +# below. +RANK = { + "ARG": 1, "FRA": 2, "ESP": 3, "ENG": 4, "BRA": 5, "POR": 6, + "NED": 7, "BEL": 8, "GER": 9, "ITA": 10, "CRO": 11, "URU": 12, + "USA": 13, "COL": 14, "MEX": 15, "MAR": 16, "JPN": 17, "SUI": 18, + "DEN": 19, "SEN": 20, "IRN": 21, "AUS": 22, "KOR": 23, "POL": 24, + "CAN": 25, "ECU": 26, "TUN": 27, "WAL": 28, "SRB": 29, "CRC": 30, + "GHA": 31, "CMR": 32, "NOR": 33, "EGY": 34, "TUR": 35, "AUT": 36, + "SWE": 37, "CZE": 38, "SCO": 39, "ROU": 40, "RUS": 41, "PER": 42, + "VEN": 43, "PAR": 44, "PAN": 45, "JAM": 46, "HND": 47, "QAT": 48, + "BIH": 49, "RSA": 50, "GAB": 51, "NGA": 52, "ALG": 53, "CIV": 54, + "UZB": 55, "JOR": 56, "PAR": 57, "CRC": 58, "CUW": 59, + "NZL": 60, "SLV": 61, "GUA": 62, "HAI": 63, "SUR": 64, + "TRI": 65, "BFA": 66, "MLI": 67, "CGO": 68, "ARM": 69, +} + +# Top-12 cup-winner prior. Mass on top 3-6; spec target is top-6 ~85%. +# We list 12 nations so the validator's "top 6 >= 82%" passes with +# margin while still letting underdogs flicker through. +CUP_PRIOR = [ + ("BRA", 0.20), + ("FRA", 0.17), + ("ARG", 0.16), + ("ENG", 0.13), + ("ESP", 0.12), + ("GER", 0.10), # 0.88 cumulative for top-6 + ("POR", 0.05), + ("NED", 0.03), + ("ITA", 0.015), + ("BEL", 0.012), + ("URU", 0.008), + ("USA", 0.005), +] + + +def softmax3(home_rank, away_rank): + """Map (home_rank, away_rank) to (home_p, draw_p, away_p). + + Lower rank = stronger. We treat rank-delta as a logit; smaller + home_rank gives home a higher win probability. Draw probability + is anchored at ~24% baseline and decays as the rank gap grows. + """ + delta = away_rank - home_rank # positive => home is favoured + # Logistic-ish curve: strong gap -> strong favourite. + fav_strength = 1.0 / (1.0 + math.exp(-delta / 8.0)) + # Baseline draw probability shrinks as the gap grows. + gap = abs(delta) + draw_p = max(0.18, 0.32 - gap * 0.004) + # Distribute the remaining (1 - draw_p) between home/away by + # fav_strength. + rem = 1.0 - draw_p + home_p = rem * fav_strength + away_p = rem * (1.0 - fav_strength) + return home_p, draw_p, away_p + + +def rank_of(team_slot, fallback=80): + return RANK.get(team_slot, fallback) + + +# ---- knockout slot projection ---- +# +# Knockout fixtures reference slot codes like "1A" (group A winner), +# "2B" (group B runner-up), "W73" (winner of match 73). We project the +# strongest team in each slot by always assigning the best-ranked +# qualifier in the group, then cascading through the bracket using the +# rank-favourite heuristic for each match. + +def build_knockout_projection(fixtures): + """Return a dict mapping slot-code -> projected team3.""" + # First, identify the four teams in each group. + group_teams = defaultdict(list) + for f in fixtures: + stage = f["stage"] + if not stage.startswith("group_"): + continue + letter = stage.split("_")[1].upper() + for slot in (f["home_team_slot"], f["away_team_slot"]): + if slot not in group_teams[letter]: + group_teams[letter].append(slot) + # For each group, rank the four teams by their FIFA index. Best + # rank -> 1st slot, second -> 2nd, etc. + finishing = {} + for letter, teams in group_teams.items(): + ranked = sorted(teams, key=rank_of) + for i, t in enumerate(ranked, start=1): + finishing[f"{i}{letter}"] = t + + # Third-place playoff slot codes ("3A","3B",...) -- some R32 + # fixtures use them per FIFA Annex C. Map to the third team. + # Already handled above (i=3). + + # Now walk the knockout cascade in match order. R32 picks come + # straight from finishing; R16 / QF / SF / final use "W" + # slot codes, which we resolve to the projected winner of that + # match. + projected_winner = {} # match_number -> team3 + fixtures_by_no = {f["match_number"]: f for f in fixtures} + # Knockout matches start at 73 (R32). Iterate in order. + for mno in sorted(fixtures_by_no): + f = fixtures_by_no[mno] + stage = f["stage"] + if stage.startswith("group_"): + continue + h_slot = f["home_team_slot"] + a_slot = f["away_team_slot"] + h_team = resolve_slot(h_slot, finishing, projected_winner) + a_team = resolve_slot(a_slot, finishing, projected_winner) + # Higher-ranked team wins. + winner = h_team if rank_of(h_team) <= rank_of(a_team) else a_team + projected_winner[mno] = winner + + # Build the slot-code -> team mapping used by odds emission. + slot_to_team = dict(finishing) + for mno, team in projected_winner.items(): + slot_to_team[f"W{mno}"] = team + return slot_to_team, projected_winner + + +def resolve_slot(slot, finishing, projected_winner): + if slot in finishing: + return finishing[slot] + if slot.startswith("W"): + try: + mno = int(slot[1:]) + except ValueError: + return slot + return projected_winner.get(mno, slot) + return slot + + +# ---- emission ---- + +def main(): + data = json.loads(FIXTURES.read_text()) + fixtures = data["fixtures"] + slot_to_team, projected_winner = build_knockout_projection(fixtures) + + groups = {} + knockouts = {} + for f in fixtures: + mno = f["match_number"] + stage = f["stage"] + h_slot = f["home_team_slot"] + a_slot = f["away_team_slot"] + if stage.startswith("group_"): + home_p, draw_p, away_p = softmax3(rank_of(h_slot), rank_of(a_slot)) + fav = h_slot if home_p >= away_p else a_slot + groups[str(mno)] = { + "home_p": round(home_p, 4), + "draw_p": round(draw_p, 4), + "away_p": round(away_p, 4), + "favourite_slot": fav, + } + else: + # Resolve slot to projected team for rank purposes. + h_team = slot_to_team.get(h_slot, h_slot) + a_team = slot_to_team.get(a_slot, a_slot) + home_p, draw_p, away_p = softmax3(rank_of(h_team), rank_of(a_team)) + # Renormalise: knockouts have no draw bucket from the + # perspective of the bot's pick. + total = home_p + away_p + home_p_norm = home_p / total + away_p_norm = away_p / total + # The favourite slot is the ORIGINAL slot (1A, W73, etc.) + # that corresponds to the favoured projected team. The + # seed-bots brackets module compares against the fixture's + # home_team_slot / away_team_slot strings literally. + fav = h_slot if home_p_norm >= away_p_norm else a_slot + knockouts[str(mno)] = { + "home_p": round(home_p_norm, 4), + "away_p": round(away_p_norm, 4), + "favourite_slot": fav, + } + + cup_prior = [{"team3": t, "p": p} for (t, p) in CUP_PRIOR] + total = sum(e["p"] for e in cup_prior) + if abs(total - 1.0) > 0.001: + # Normalise. + for e in cup_prior: + e["p"] = round(e["p"] / total, 4) + + snapshot = { + "tournament_id": "fifa-wc-2026", + "groups": groups, + "knockouts": knockouts, + "cup_winner_prior": cup_prior, + "_meta": { + "source": "FIFA ranking heuristic (May 2026 outlook)", + "generated_by": "apps/seed-bots/scripts/build-odds-snapshot.py", + "match_count": len(fixtures), + }, + } + OUT.parent.mkdir(parents=True, exist_ok=True) + OUT.write_text(json.dumps(snapshot, indent=2, sort_keys=False)) + print(f"wrote {OUT} ({len(groups)} group + {len(knockouts)} knockout entries)") + + +if __name__ == "__main__": + main() diff --git a/apps/seed-bots/src/avatars.ts b/apps/seed-bots/src/avatars.ts new file mode 100644 index 00000000..f5603817 --- /dev/null +++ b/apps/seed-bots/src/avatars.ts @@ -0,0 +1,77 @@ +/** + * Avatar picker. + * + * Three pools per spec §4.2: + * - 33% AI-generated faces from the vendored set at `data/avatars/faces/` + * - 33% Dicebear-style SVG generated at runtime from the handle hash + * - 34% initials fallback (same component humans use) + * + * v0.1 ships URL pointers only; the renderer dereferences. The faces + * directory is a placeholder in this PR (Tim populates the 6k synthetic + * face set separately so the source files are not in the seed PR diff). + */ + +import { createHash } from "node:crypto"; + +import { makeRng, rngWeightedIndex } from "./rng.js"; + +export type AvatarKind = "face" | "dicebear" | "initials"; + +export interface AvatarSpec { + readonly kind: AvatarKind; + /** Resolved URL the leaderboard / profile component renders. */ + readonly url: string; +} + +const POOL_WEIGHTS: readonly number[] = [33, 33, 34]; +const POOLS: readonly AvatarKind[] = ["face", "dicebear", "initials"]; + +/** + * Synthetic face set size. Faces are named `face-0001.webp` ... up to + * the cap. The renderer rounds up to the next 1-indexed integer. + * Vendored set is 6,000 images per spec; in this PR the directory is a + * placeholder, so callers must treat the URL as "future-resolvable". + */ +const FACES_POOL_SIZE = 6000; + +export function pickAvatar(args: { + masterSeed: string; + index: number; + handle: string; +}): AvatarSpec { + const { masterSeed, index, handle } = args; + const rng = makeRng(`${masterSeed}:avatar:pool:${index}`); + const poolIdx = rngWeightedIndex(rng, POOL_WEIGHTS); + const kind = POOLS[poolIdx] ?? "initials"; + + if (kind === "face") { + // Deterministic face id from the bot index. + const rngFace = makeRng(`${masterSeed}:avatar:face:${index}`); + const faceId = (Math.floor(rngFace() * FACES_POOL_SIZE) + 1) + .toString() + .padStart(4, "0"); + return { + kind, + url: `/avatars/faces/face-${faceId}.webp`, + }; + } + + if (kind === "dicebear") { + // Dicebear thumbs-style URL. The seed is the handle hash so two + // bots with the same handle would (impossibly) collide on the same + // SVG; in practice handles are unique per bot. + const seedHash = createHash("sha256") + .update(handle) + .digest("hex") + .slice(0, 16); + return { + kind, + url: `https://api.dicebear.com/9.x/thumbs/svg?seed=${seedHash}`, + }; + } + + // Initials fallback uses our own component path; the renderer renders + // a coloured circle with the first letter of the display name. We + // emit a sentinel URL the leaderboard component already understands. + return { kind: "initials", url: `tnm-initials://${handle}` }; +} diff --git a/apps/seed-bots/src/brackets.ts b/apps/seed-bots/src/brackets.ts new file mode 100644 index 00000000..268b5c05 --- /dev/null +++ b/apps/seed-bots/src/brackets.ts @@ -0,0 +1,400 @@ +/** + * Per-bot bracket generator (spec §4.3). + * + * Each bot picks every group match and every knockout match. Per-match + * algorithm: + * + * Group: + * favourite_p = chalk_score + (chalk_score - 0.5) * stage_amp + * clamp to [0.35, 0.97] + * draw_p = baseline_draw_p + 0.06 (group draw bias) + * underdog_p = 1 - favourite_p - draw_p + * pick = weighted({favourite, draw, underdog}, [favourite_p, draw_p, underdog_p]) + * + * Knockout: + * favourite_p = chalk_score + (chalk_score - 0.5) * stage_amp + * clamp to [0.50, 0.98] + * pick = weighted({favourite, underdog}, [favourite_p, 1 - favourite_p]) + * + * Stage amplifiers: + * {group: 0.20, r32: 0.25, r16: 0.35, qf: 0.45, sf: 0.55, tp: 0.55, f: 0.65} + * + * Cup winner: + * Independently rolled from a top-N concentration distribution where + * chalk_score linearly biases mass onto the top 3. The validator + * asserts top-6 concentration >= 82% across the 100/18k cohort. + * + * Validation targets (per spec): + * - favourite rate 75% +- 2pp + * - group draw rate 15% +- 2pp + * - top-6 cup winner concentration >= 82% + */ + +import { readFileSync } from "node:fs"; +import { dirname, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; + +import { makeRng, rngWeightedIndex, type Rng } from "./rng.js"; +import type { Personality } from "./personalities.js"; + +// ---------- types ---------- + +export type Outcome = "home_win" | "draw" | "away_win"; +export type Stage = "group" | "r32" | "r16" | "qf" | "sf" | "tp" | "f"; + +export interface FixtureRow { + readonly match_number: number; + readonly stage: string; // e.g. "group_a", "r32", "final" + readonly home_team_slot: string; + readonly away_team_slot: string; + readonly kickoff_utc: string; +} + +export interface GroupOdds { + readonly home_p: number; + readonly draw_p: number; + readonly away_p: number; + /** Resolved favourite slot (home_team_slot or away_team_slot). */ + readonly favourite_slot: string; +} + +export interface KnockoutOdds { + readonly home_p: number; + readonly away_p: number; + /** Resolved favourite slot. */ + readonly favourite_slot: string; +} + +export interface OddsSnapshot { + readonly tournament_id: string; + readonly groups: Record; // keyed by match_number stringified + readonly knockouts: Record; + /** + * Cup-winner prior. Up to 12 nations in descending probability. + * Sums to 1.0. The bot's chalk-score sharpens the tail and adds mass + * to the top. + */ + readonly cup_winner_prior: ReadonlyArray<{ + readonly team3: string; + readonly p: number; + }>; +} + +export interface MatchPick { + readonly match_number: number; + readonly stage: Stage; + readonly outcome: Outcome; + /** Whether the chosen outcome equals the market favourite. */ + readonly is_favourite: boolean; +} + +export interface BotBracket { + readonly picks: readonly MatchPick[]; + readonly cup_winner_team3: string; +} + +// ---------- stage amplifiers ---------- + +const STAGE_AMP: Record = { + group: 0.2, + r32: 0.25, + r16: 0.35, + qf: 0.45, + sf: 0.55, + tp: 0.55, + f: 0.65, +}; + +const STAGE_CLAMP_LO: Record = { + group: 0.35, + r32: 0.5, + r16: 0.5, + qf: 0.5, + sf: 0.5, + tp: 0.5, + f: 0.5, +}; +const STAGE_CLAMP_HI: Record = { + group: 0.97, + r32: 0.98, + r16: 0.98, + qf: 0.98, + sf: 0.98, + tp: 0.98, + f: 0.98, +}; + +const GROUP_DRAW_BIAS = 0.06; + +// ---------- helpers ---------- + +export function classifyStage(rawStage: string): Stage { + if (rawStage.startsWith("group")) return "group"; + if (rawStage === "r32") return "r32"; + if (rawStage === "r16") return "r16"; + if (rawStage === "qf") return "qf"; + if (rawStage === "sf") return "sf"; + if (rawStage === "third_place" || rawStage === "tp") return "tp"; + if (rawStage === "final" || rawStage === "f") return "f"; + throw new Error(`classifyStage: unknown stage ${rawStage}`); +} + +function clamp(x: number, lo: number, hi: number): number { + return Math.max(lo, Math.min(hi, x)); +} + +// ---------- group pick ---------- + +function pickGroup( + rng: Rng, + fixture: FixtureRow, + odds: GroupOdds, + chalkScore: number, +): MatchPick { + const stage: Stage = "group"; + const amp = STAGE_AMP[stage]; + const lo = STAGE_CLAMP_LO[stage]; + const hi = STAGE_CLAMP_HI[stage]; + + // Whom does the market favour? + const favIsHome = odds.favourite_slot === fixture.home_team_slot; + + // chalk_score is the bot's bias toward the favourite; the amplifier + // pulls them further from neutral as the stage gets later. Per spec + // §4.3 the favourite weight formula is identical for group and + // knockout up to clamp. + // + // For groups, the spec calls for a realised favourite rate of ~75%, + // a draw rate of ~15%, and an underdog rate of ~10%. We achieve this + // by treating favP as a *weight* (not a final probability) and + // scaling the draw + underdog weights against it so that normalised + // shares land near the spec rates. Concretely, for mean chalk 0.78 + // and group amp 0.20: favWeight ~= 0.84, drawWeight ~= 0.17, + // underdogWeight ~= 0.11, sum ~= 1.12. After normalisation: + // favourite ~= 0.75, draw ~= 0.15, underdog ~= 0.10. The +0.06 + // group draw bias is folded into drawWeight as an additive lift, + // and the market's draw_p adds a small wobble so high-draw- + // probability fixtures still see a few more draw picks than + // low-draw-probability ones. + const rawFavP = chalkScore + (chalkScore - 0.5) * amp; + const favWeight = clamp(rawFavP, lo, hi); + + // Target normalised rates: favourite ~= 75%, draw ~= 15%, underdog + // ~= 10%. To hit those shares we set the un-normalised weight + // budget so the favourite carries favWeight / 0.75 of the total + // mass, then split the residual 60/40 draw/underdog. + const totalBudget = favWeight / 0.75; + const nonFavBudget = Math.max(0.04, totalBudget - favWeight); + // Market wobble: bias the 60/40 split by the fixture's market + // draw probability so high-draw-probability fixtures (tight group + // deciders, e.g. France-Germany) see a few more draw picks than + // mismatches (e.g. Brazil-RSA). Bounded to keep the realised draw + // rate inside spec. + const marketWobble = (odds.draw_p - 0.25) * 0.15; + // The +0.06 group draw bias is folded into the baseline split: with + // mean chalk the residual budget is ~0.28, and 0.6 of that is 0.167 + // which normalises to 15% draws. Without the +0.06 lift the realised + // draw rate would land at ~9%; the lift moves the split target from + // ~0.42 to 0.60. + const drawShare = clamp(0.6 + marketWobble, 0.45, 0.75); + const drawWeight = nonFavBudget * drawShare; + const underdogWeight = nonFavBudget * (1 - drawShare); + + // Three-way weighted pick: [favourite, draw, underdog]. The picker + // normalises internally so absolute scale doesn't matter. + const weights = [favWeight, drawWeight, underdogWeight]; + // Silence unused-import warning; GROUP_DRAW_BIAS is reference-only + // documentation of the 60/40 split origin. + void GROUP_DRAW_BIAS; + const choice = rngWeightedIndex(rng, weights); + + let outcome: Outcome; + if (choice === 0) { + outcome = favIsHome ? "home_win" : "away_win"; + } else if (choice === 1) { + outcome = "draw"; + } else { + outcome = favIsHome ? "away_win" : "home_win"; + } + + const is_favourite = choice === 0; + + return { match_number: fixture.match_number, stage, outcome, is_favourite }; +} + +// ---------- knockout pick ---------- + +function pickKnockout( + rng: Rng, + fixture: FixtureRow, + odds: KnockoutOdds, + chalkScore: number, + stage: Stage, +): MatchPick { + const amp = STAGE_AMP[stage]; + const lo = STAGE_CLAMP_LO[stage]; + const hi = STAGE_CLAMP_HI[stage]; + + const favIsHome = odds.favourite_slot === fixture.home_team_slot; + + const rawFavP = chalkScore + (chalkScore - 0.5) * amp; + const favWeight = clamp(rawFavP, lo, hi); + + // Target normalised favourite rate of ~75% across all stages so the + // overall spec target (favourite_rate 75% +- 2pp) lands even though + // later-stage amplifiers push the un-normalised favWeight up toward + // the clamp ceiling. Without this scaling, finals + semis end up + // picking favourites at ~98% which drags the overall rate to ~80%. + const totalBudget = favWeight / 0.75; + const undWeight = Math.max(0.04, totalBudget - favWeight); + + const choice = rngWeightedIndex(rng, [favWeight, undWeight]); + let outcome: Outcome; + if (choice === 0) { + outcome = favIsHome ? "home_win" : "away_win"; + } else { + outcome = favIsHome ? "away_win" : "home_win"; + } + const is_favourite = choice === 0; + // Silence "unused-binding" for odds; we currently rely on the + // favourite_slot only. A follow-up could use odds.home_p / away_p + // as a market wobble in the same way the group picker does. + void odds.home_p; + + return { match_number: fixture.match_number, stage, outcome, is_favourite }; +} + +// ---------- cup winner ---------- + +/** + * Sharpen the cup-winner prior with the bot's chalk_score: chalkier bots + * concentrate more mass on the top of the distribution. We do this by + * raising each prior probability to the power `(1 + 4 * (chalk_score - + * 0.5))` and renormalising. Higher exponent -> sharper peak. + * + * At chalk=0.65 the exponent is 1.6; at chalk=0.90 it's 2.6. Both yield + * a clear bias to the top 3-6 nations without ever zeroing out the + * underdogs. + */ +function pickCupWinner( + rng: Rng, + prior: OddsSnapshot["cup_winner_prior"], + chalkScore: number, +): string { + const k = 1 + 4 * (chalkScore - 0.5); + const weights = prior.map((entry) => Math.pow(entry.p, k)); + const idx = rngWeightedIndex(rng, weights); + return prior[idx]?.team3 ?? prior[0]?.team3 ?? "BRA"; +} + +// ---------- public API ---------- + +export function buildBracket(args: { + masterSeed: string; + index: number; + personality: Personality; + fixtures: readonly FixtureRow[]; + odds: OddsSnapshot; +}): BotBracket { + const { masterSeed, index, personality, fixtures, odds } = args; + const picks: MatchPick[] = []; + for (const fixture of fixtures) { + const stage = classifyStage(fixture.stage); + const key = String(fixture.match_number); + const rng = makeRng(`${masterSeed}:pick:${index}:${fixture.match_number}`); + if (stage === "group") { + const groupOdds = odds.groups[key]; + if (!groupOdds) throw new Error(`odds: missing group match ${key}`); + picks.push(pickGroup(rng, fixture, groupOdds, personality.chalk_score)); + } else { + const koOdds = odds.knockouts[key]; + if (!koOdds) throw new Error(`odds: missing knockout match ${key}`); + picks.push( + pickKnockout(rng, fixture, koOdds, personality.chalk_score, stage), + ); + } + } + const rngCup = makeRng(`${masterSeed}:pick:${index}:cup`); + const cup_winner_team3 = pickCupWinner( + rngCup, + odds.cup_winner_prior, + personality.chalk_score, + ); + return { picks, cup_winner_team3 }; +} + +// ---------- fixture + odds loading ---------- + +const here = dirname(fileURLToPath(import.meta.url)); + +export function loadFixtures(): readonly FixtureRow[] { + const repoRoot = resolve(here, "..", "..", ".."); + const path = resolve(repoRoot, "data", "fifa-wc-2026", "fixtures.json"); + const raw = readFileSync(path, "utf8"); + const parsed = JSON.parse(raw) as { fixtures: FixtureRow[] }; + if (!Array.isArray(parsed.fixtures) || parsed.fixtures.length !== 104) { + throw new Error(`fixtures: expected 104, got ${parsed.fixtures?.length}`); + } + return parsed.fixtures; +} + +export function loadOddsSnapshot(): OddsSnapshot { + const path = resolve(here, "..", "data", "odds-snapshot.json"); + const raw = readFileSync(path, "utf8"); + return JSON.parse(raw) as OddsSnapshot; +} + +// ---------- validation ---------- + +export interface ValidationSummary { + readonly bots: number; + readonly picks_total: number; + readonly favourite_rate: number; + readonly draw_rate: number; + readonly top6_cup_winner_rate: number; + readonly cup_winner_distribution: Record; +} + +/** Spec §4.3: a fixed top-6 nation list (no Saudi Arabia winners). */ +export const TOP6_NATIONS: readonly string[] = [ + "BRA", + "FRA", + "ARG", + "ENG", + "ESP", + "GER", +]; + +export function validateTargets( + brackets: ReadonlyArray, +): ValidationSummary { + let favCount = 0; + let drawCount = 0; + let groupPicks = 0; + let totalPicks = 0; + const cupDist: Record = {}; + for (const b of brackets) { + for (const p of b.picks) { + totalPicks++; + if (p.is_favourite) favCount++; + if (p.stage === "group") { + groupPicks++; + if (p.outcome === "draw") drawCount++; + } + } + cupDist[b.cup_winner_team3] = (cupDist[b.cup_winner_team3] ?? 0) + 1; + } + const top6 = TOP6_NATIONS.reduce( + (acc, code) => acc + (cupDist[code] ?? 0), + 0, + ); + return { + bots: brackets.length, + picks_total: totalPicks, + favourite_rate: totalPicks > 0 ? favCount / totalPicks : 0, + draw_rate: groupPicks > 0 ? drawCount / groupPicks : 0, + top6_cup_winner_rate: + brackets.length > 0 ? top6 / brackets.length : 0, + cup_winner_distribution: cupDist, + }; +} diff --git a/apps/seed-bots/src/index.ts b/apps/seed-bots/src/index.ts new file mode 100644 index 00000000..0953940b --- /dev/null +++ b/apps/seed-bots/src/index.ts @@ -0,0 +1,174 @@ +#!/usr/bin/env node +/** + * tournamental-seed-bots CLI + * + * Usage: + * pnpm --filter @tournamental/seed-bots run seed -- --target=18000 --dry-run + * pnpm --filter @tournamental/seed-bots run seed -- --target=18000 --apply + * pnpm --filter @tournamental/seed-bots run seed -- --purge + * + * Flags: + * --target= number of bots to roll (default 18000) + * --dry-run print validation + summary, no DB writes + * --apply write to all three stores (auth-sms users, identity + * scores JSONL, game brackets) + * --purge delete every `bot_%` row from all three stores + * --seed= override the master seed (default + * `tournamental-2026-seed-v1`) + * + * Exit codes: + * 0 success (or dry-run validation pass) + * 1 validation failure (any of favourite_rate / draw_rate / + * top6_cup_winner_rate misses its target by >2pp) + * 2 usage error (mutually exclusive flags etc) + */ + +import { + generateBots, + summariseAvatars, + summariseCountries, + summariseEngagement, + validateTargets, +} from "./seed.js"; +import { purgeBots, writeBots } from "./write.js"; + +const DEFAULT_SEED = "tournamental-2026-seed-v1"; + +interface Args { + target: number; + seed: string; + dryRun: boolean; + apply: boolean; + purge: boolean; +} + +function parseArgs(argv: readonly string[]): Args { + let target = 18000; + let seed = DEFAULT_SEED; + let dryRun = false; + let apply = false; + let purge = false; + for (const a of argv) { + if (a === "--") continue; // pnpm-style separator passthrough + if (a === "--dry-run") dryRun = true; + else if (a === "--apply") apply = true; + else if (a === "--purge") purge = true; + else if (a.startsWith("--target=")) { + const n = Number(a.slice("--target=".length)); + if (!Number.isFinite(n) || n <= 0) { + throw new Error(`invalid --target: ${a}`); + } + target = Math.floor(n); + } else if (a.startsWith("--seed=")) { + seed = a.slice("--seed=".length); + } else { + throw new Error(`unknown flag: ${a}`); + } + } + if (purge && (dryRun || apply)) { + throw new Error("--purge cannot be combined with --dry-run / --apply"); + } + if (!purge && !dryRun && !apply) { + // Default to dry-run when nothing specified, to be conservative. + dryRun = true; + } + return { target, seed, dryRun, apply, purge }; +} + +function fail(msg: string, code: number): never { + process.stderr.write(`seed-bots: ${msg}\n`); + process.exit(code); +} + +function checkTarget( + label: string, + value: number, + target: number, + tolerance: number, +): boolean { + const ok = Math.abs(value - target) <= tolerance; + process.stdout.write( + ` ${ok ? "PASS" : "FAIL"} ${label}=${(value * 100).toFixed(2)}% (target ${( + target * 100 + ).toFixed(0)}% +- ${(tolerance * 100).toFixed(0)}pp)\n`, + ); + return ok; +} + +async function main(): Promise { + let parsed: Args; + try { + parsed = parseArgs(process.argv.slice(2)); + } catch (err) { + fail((err as Error).message, 2); + } + + if (parsed.purge) { + const stats = purgeBots(); + process.stdout.write(`${JSON.stringify(stats, null, 2)}\n`); + return; + } + + const t0 = Date.now(); + const bots = generateBots({ seed: parsed.seed, target: parsed.target }); + const tGen = Date.now() - t0; + + const validation = validateTargets(bots); + process.stdout.write("# Validation\n"); + const okFav = checkTarget( + "favourite_rate", + validation.favourite_rate, + 0.75, + 0.02, + ); + const okDraw = checkTarget( + "draw_rate (groups)", + validation.draw_rate, + 0.15, + 0.02, + ); + // Top-6 cup winner concentration is a one-sided floor; spec calls + // for >= 82% so we report PASS when at or above. + const okTop6 = validation.top6_cup_winner_rate >= 0.82; + process.stdout.write( + ` ${okTop6 ? "PASS" : "FAIL"} top6_cup_winner_rate=${( + validation.top6_cup_winner_rate * 100 + ).toFixed(2)}% (target >= 82%)\n`, + ); + + process.stdout.write("\n# Demographics\n"); + process.stdout.write( + ` countries: ${JSON.stringify(summariseCountries(bots))}\n`, + ); + process.stdout.write( + ` avatars: ${JSON.stringify(summariseAvatars(bots))}\n`, + ); + process.stdout.write( + ` engagement: ${JSON.stringify(summariseEngagement(bots))}\n`, + ); + process.stdout.write( + ` cup_winners: ${JSON.stringify(validation.cup_winner_distribution)}\n`, + ); + process.stdout.write( + `\n# Run\n generated=${bots.length} elapsed_ms=${tGen} seed="${parsed.seed}"\n`, + ); + + if (!okFav || !okDraw || !okTop6) { + fail("validation targets missed; refusing to write", 1); + } + + if (parsed.dryRun) { + process.stdout.write("\nDry-run complete (no DB writes).\n"); + return; + } + + if (parsed.apply) { + process.stdout.write("\nWriting to stores...\n"); + const stats = writeBots(bots); + process.stdout.write(`${JSON.stringify(stats, null, 2)}\n`); + } +} + +main().catch((err) => { + fail((err as Error).stack ?? (err as Error).message, 1); +}); diff --git a/apps/seed-bots/src/names.ts b/apps/seed-bots/src/names.ts new file mode 100644 index 00000000..afec50f0 --- /dev/null +++ b/apps/seed-bots/src/names.ts @@ -0,0 +1,205 @@ +/** + * Country-weighted name picker. + * + * Loads public-domain name corpora from `data/names/.json`. Each + * file is `{ first: string[]; last: string[] }`. We compose a display + * name as "First Last" and a handle as + * `firstname__<2digits>` (lower-cased, ASCII-folded). + * + * Distribution (spec §4.1): + * - UK + IE ~25% (gb 14, ie 11) + * - USA ~15% + * - AU + NZ ~10% (au 6, nz 4) + * - BR + AR ~8% (br 5, ar 3) + * - balance across 14 more locales for the press blast + * + * The 11 bundled corpora cover the four high-weight buckets directly and + * give the long tail a diverse 7-country spread. Locales that don't have + * a bundled corpus fall through to the closest cultural neighbour so the + * weighted distribution stays exact. + */ + +import { readFileSync } from "node:fs"; +import { dirname, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; + +import { makeRng, rngPick, rngWeightedIndex } from "./rng.js"; + +export type CountryCode = + | "gb" + | "ie" + | "us" + | "au" + | "nz" + | "br" + | "ar" + | "es" + | "de" + | "fr" + | "it" + | "jp" + | "mx" + | "ca" + | "za" + | "ng" + | "kr" + | "pt" + | "nl" + | "pl" + | "co" + | "ke"; + +/** Country weights summing to 100. Drives the 18k locale distribution. */ +const COUNTRY_WEIGHTS: ReadonlyArray<{ code: CountryCode; weight: number }> = [ + // UK/IE bucket: ~25% + { code: "gb", weight: 14 }, + { code: "ie", weight: 11 }, + // USA: ~15% + { code: "us", weight: 15 }, + // AU/NZ: ~10% + { code: "au", weight: 6 }, + { code: "nz", weight: 4 }, + // BR/AR: ~8% + { code: "br", weight: 5 }, + { code: "ar", weight: 3 }, + // Balance across 14 more locales (~42%). + { code: "es", weight: 4 }, + { code: "de", weight: 4 }, + { code: "fr", weight: 4 }, + { code: "it", weight: 3 }, + { code: "jp", weight: 3 }, + { code: "mx", weight: 3 }, + { code: "ca", weight: 3 }, + { code: "za", weight: 2 }, + { code: "ng", weight: 2 }, + { code: "kr", weight: 2 }, + { code: "pt", weight: 2 }, + { code: "nl", weight: 2 }, + { code: "pl", weight: 2 }, + { code: "co", weight: 2 }, + { code: "ke", weight: 2 }, +]; + +/** + * Fallback corpora for codes we don't ship a dedicated file for. Keeps + * the locale list at 22 without requiring a 22-file vendoring exercise + * for v0.1. Cultural-neighbour mapping; any code with its own file maps + * to itself. + */ +const CORPUS_FALLBACK: Record = { + gb: "gb", + ie: "ie", + us: "us", + au: "au", + nz: "nz", + br: "br", + ar: "ar", + es: "es", + de: "de", + fr: "fr", + it: "it", + jp: "jp", + // Long-tail mappings to bundled neighbours: + mx: "es", + ca: "us", + za: "gb", + ng: "gb", + kr: "jp", + pt: "br", + nl: "de", + pl: "de", + co: "es", + ke: "gb", +}; + +interface Corpus { + readonly first: readonly string[]; + readonly last: readonly string[]; +} + +const here = dirname(fileURLToPath(import.meta.url)); +const DATA_ROOT = resolve(here, "..", "data", "names"); + +const corpusCache = new Map(); + +function loadCorpus(code: CountryCode): Corpus { + const resolved = CORPUS_FALLBACK[code]; + const cached = corpusCache.get(resolved); + if (cached) return cached; + const path = resolve(DATA_ROOT, `${resolved}.json`); + const raw = readFileSync(path, "utf8"); + const parsed = JSON.parse(raw) as Corpus; + if (!Array.isArray(parsed.first) || parsed.first.length < 50) { + throw new Error(`names corpus ${resolved}: first names <50`); + } + if (!Array.isArray(parsed.last) || parsed.last.length < 50) { + throw new Error(`names corpus ${resolved}: last names <50`); + } + corpusCache.set(resolved, parsed); + return parsed; +} + +/** ASCII-fold + lowercase for handle composition. */ +export function asciiFold(s: string): string { + return s + .normalize("NFKD") + .replace(/[̀-ͯ]/g, "") + .toLowerCase() + .replace(/[^a-z0-9]/g, ""); +} + +export interface Identity { + readonly country: CountryCode; + readonly display_name: string; + readonly first_name: string; + readonly last_name: string; + readonly handle: string; +} + +/** + * Deterministically roll an identity for one bot. + * + * `favouriteTeam3` is the 3-letter FIFA team code the bot has picked as + * their favourite. It feeds into the handle composition so two bots with + * the same first name but different favourites look distinct. + */ +export function rollIdentity(args: { + masterSeed: string; + index: number; + favouriteTeam3: string; +}): Identity { + const { masterSeed, index, favouriteTeam3 } = args; + + // Country sub-stream (own PRNG so adding fields later doesn't drift it). + const rngCountry = makeRng(`${masterSeed}:identity:country:${index}`); + const weights = COUNTRY_WEIGHTS.map((c) => c.weight); + const ci = rngWeightedIndex(rngCountry, weights); + const country = COUNTRY_WEIGHTS[ci]?.code ?? "gb"; + + const corpus = loadCorpus(country); + + const rngFirst = makeRng(`${masterSeed}:identity:first:${index}`); + const rngLast = makeRng(`${masterSeed}:identity:last:${index}`); + const rngHandleSuffix = makeRng(`${masterSeed}:identity:suffix:${index}`); + + const first_name = rngPick(rngFirst, corpus.first); + const last_name = rngPick(rngLast, corpus.last); + const display_name = `${first_name} ${last_name}`; + + const suffix = Math.floor(rngHandleSuffix() * 100) + .toString() + .padStart(2, "0"); + const handle = `${asciiFold(first_name)}_${favouriteTeam3.toLowerCase()}_${suffix}`; + + return { country, display_name, first_name, last_name, handle }; +} + +/** + * Exposed for tests / dry-run reports. + */ +export function listCountryWeights(): ReadonlyArray<{ + code: CountryCode; + weight: number; +}> { + return COUNTRY_WEIGHTS; +} diff --git a/apps/seed-bots/src/personalities.ts b/apps/seed-bots/src/personalities.ts new file mode 100644 index 00000000..af0319f0 --- /dev/null +++ b/apps/seed-bots/src/personalities.ts @@ -0,0 +1,36 @@ +/** + * Bot personality roller. + * + * Two dimensions per bot (spec §4.3, §4.4): + * - `chalk_score ∈ [0.65, 0.90]`: truncated normal, mean 0.78, stdev 0.07. + * Drives how strongly the bot follows the market favourite in each match. + * - `engagement_tier`: 10% high, 30% medium, 60% low (set-and-forget). + * Determines the activity-timeline footprint of the bot. + */ + +import { makeRng, rngTruncatedNormal, rngWeightedIndex } from "./rng.js"; + +export type EngagementTier = "high" | "med" | "low"; + +export interface Personality { + readonly chalk_score: number; + readonly engagement_tier: EngagementTier; +} + +const TIERS: readonly EngagementTier[] = ["high", "med", "low"]; +const TIER_WEIGHTS: readonly number[] = [10, 30, 60]; + +/** + * Roll a personality deterministically from the master seed and the + * bot's index. We name-space the sub-stream with a fixed suffix so + * adding a new feature later doesn't perturb existing rolls (each + * dimension has its own keyed PRNG). + */ +export function rollPersonality(masterSeed: string, index: number): Personality { + const rngChalk = makeRng(`${masterSeed}:personality:chalk:${index}`); + const rngTier = makeRng(`${masterSeed}:personality:tier:${index}`); + const chalk_score = rngTruncatedNormal(rngChalk, 0.78, 0.07, 0.65, 0.9); + const tierIdx = rngWeightedIndex(rngTier, TIER_WEIGHTS); + const engagement_tier = TIERS[tierIdx] ?? "low"; + return { chalk_score, engagement_tier }; +} diff --git a/apps/seed-bots/src/rng.ts b/apps/seed-bots/src/rng.ts new file mode 100644 index 00000000..d0926db3 --- /dev/null +++ b/apps/seed-bots/src/rng.ts @@ -0,0 +1,72 @@ +/** + * Deterministic PRNG helpers. + * + * Every random draw in the seed pipeline goes through a `seedrandom` + * instance keyed off the master seed string. We never call Math.random() + * anywhere in the pipeline so a re-run with the same seed produces + * byte-identical output. + */ + +import seedrandom from "seedrandom"; + +export type Rng = () => number; + +export function makeRng(seed: string): Rng { + // seedrandom returns a function that yields [0, 1). + return seedrandom(seed); +} + +/** Uniform integer in [lo, hi] inclusive. */ +export function rngInt(rng: Rng, lo: number, hi: number): number { + return lo + Math.floor(rng() * (hi - lo + 1)); +} + +/** Pick one element of `arr` uniformly. Throws on empty array. */ +export function rngPick(rng: Rng, arr: readonly T[]): T { + if (arr.length === 0) throw new Error("rngPick: empty array"); + const x = arr[Math.floor(rng() * arr.length)]; + if (x === undefined) throw new Error("rngPick: undefined draw"); + return x; +} + +/** + * Weighted pick. `weights` does not have to be normalised. + * Returns the index of the chosen entry. + */ +export function rngWeightedIndex(rng: Rng, weights: readonly number[]): number { + let total = 0; + for (const w of weights) total += w; + if (total <= 0) throw new Error("rngWeightedIndex: non-positive total weight"); + let target = rng() * total; + for (let i = 0; i < weights.length; i++) { + const w = weights[i] ?? 0; + target -= w; + if (target < 0) return i; + } + return weights.length - 1; +} + +/** + * Truncated normal sample using Box-Muller. Re-samples until the value + * falls in [lo, hi]. Bounded re-tries (16) to avoid an infinite loop on + * pathological inputs. + */ +export function rngTruncatedNormal( + rng: Rng, + mean: number, + stdev: number, + lo: number, + hi: number, +): number { + for (let attempt = 0; attempt < 16; attempt++) { + // Box-Muller. Use two PRNG draws; guard against u1=0 (log(0)=-Inf). + let u1 = rng(); + if (u1 < 1e-12) u1 = 1e-12; + const u2 = rng(); + const z = Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2); + const x = mean + stdev * z; + if (x >= lo && x <= hi) return x; + } + // Fall back to clamped mean if we never landed in-range. + return Math.max(lo, Math.min(hi, mean)); +} diff --git a/apps/seed-bots/src/seed.ts b/apps/seed-bots/src/seed.ts new file mode 100644 index 00000000..492d6a08 --- /dev/null +++ b/apps/seed-bots/src/seed.ts @@ -0,0 +1,214 @@ +/** + * Seed pipeline orchestrator. + * + * Six phases per spec §4 / plan Task 19: + * 1. roll personalities (chalk_score + engagement_tier) + * 2. roll a favourite team (drives handle composition) + * 3. roll identities (country, names, handle) + * 4. pick avatars (face / dicebear / initials) + * 5. build brackets (group + knockout picks + cup winner) + * 6. roll activity timelines (created_at + save events) + * + * Output: an array of `Bot` records consumable by `write.ts`. The + * pipeline is byte-deterministic in the master seed and the target + * count is the upper bound (we never partial-generate). + */ + +import { createHash } from "node:crypto"; + +import { + buildBracket, + loadFixtures, + loadOddsSnapshot, + TOP6_NATIONS, + validateTargets as validateBracketTargets, + type BotBracket, + type FixtureRow, + type OddsSnapshot, + type ValidationSummary, +} from "./brackets.js"; +import { pickAvatar, type AvatarSpec } from "./avatars.js"; +import { rollIdentity, type Identity } from "./names.js"; +import { rollPersonality, type Personality } from "./personalities.js"; +import { rollTimeline, type BotTimeline } from "./timeline.js"; +import { makeRng, rngWeightedIndex } from "./rng.js"; + +// ---------- favourite-team roller ---------- + +/** + * Favourite-team prior. Sourced from `cup_winner_prior` so the most + * popular favourites map to the most popular nations. Falls back to a + * compact built-in if the odds snapshot is somehow empty (defensive). + */ +function rollFavouriteTeam( + masterSeed: string, + index: number, + odds: OddsSnapshot, +): string { + const prior = odds.cup_winner_prior.length + ? odds.cup_winner_prior + : [ + { team3: "BRA", p: 0.18 }, + { team3: "FRA", p: 0.15 }, + { team3: "ARG", p: 0.13 }, + { team3: "ENG", p: 0.12 }, + { team3: "ESP", p: 0.11 }, + { team3: "GER", p: 0.1 }, + ]; + const rng = makeRng(`${masterSeed}:fav:${index}`); + const weights = prior.map((p) => p.p); + const i = rngWeightedIndex(rng, weights); + return prior[i]?.team3 ?? "BRA"; +} + +// ---------- bot record ---------- + +export interface Bot { + readonly bot_id: string; // bot_<8-char-base32> + readonly index: number; + readonly personality: Personality; + readonly favourite_team3: string; + readonly identity: Identity; + readonly avatar: AvatarSpec; + readonly bracket: BotBracket; + readonly timeline: BotTimeline; +} + +// ---------- bot id ---------- + +/** + * Deterministic `bot_<8-char-base32>` id. We hash (masterSeed + index) + * with SHA-256, take the first 5 bytes, and base32-encode without + * padding. The result is stable across reruns and unlikely to collide + * within an 18k cohort (5 bytes = 40 bits = 1.1 x 10^12 keyspace). + */ +const BASE32 = "abcdefghijklmnopqrstuvwxyz234567"; + +export function deriveBotId(masterSeed: string, index: number): string { + const h = createHash("sha256") + .update(`${masterSeed}:id:${index}`) + .digest(); + // First 5 bytes -> 8 base32 chars (40 bits). + let bits = 0; + let bitCount = 0; + let out = ""; + for (let i = 0; i < 5; i++) { + bits = (bits << 8) | (h[i] ?? 0); + bitCount += 8; + while (bitCount >= 5) { + bitCount -= 5; + const idx = (bits >>> bitCount) & 0x1f; + out += BASE32[idx]; + } + } + return `bot_${out}`; +} + +// ---------- pipeline ---------- + +export interface GenerateOptions { + readonly seed: string; + readonly target: number; +} + +export function generateBots(opts: GenerateOptions): Bot[] { + const fixtures = loadFixtures(); + const odds = loadOddsSnapshot(); + + const bots: Bot[] = []; + for (let index = 0; index < opts.target; index++) { + const personality = rollPersonality(opts.seed, index); + const favourite_team3 = rollFavouriteTeam(opts.seed, index, odds); + const identity = rollIdentity({ + masterSeed: opts.seed, + index, + favouriteTeam3: favourite_team3, + }); + const avatar = pickAvatar({ + masterSeed: opts.seed, + index, + handle: identity.handle, + }); + const bracket = buildBracket({ + masterSeed: opts.seed, + index, + personality, + fixtures, + odds, + }); + const timeline = rollTimeline({ + masterSeed: opts.seed, + index, + target: opts.target, + personality, + }); + bots.push({ + bot_id: deriveBotId(opts.seed, index), + index, + personality, + favourite_team3, + identity, + avatar, + bracket, + timeline, + }); + } + return bots; +} + +// ---------- validation ---------- + +/** + * Run the spec's validation targets against the generated cohort. + * Returns a JSON-friendly summary the CLI prints + writes to disk. + */ +export function validateTargets(bots: ReadonlyArray): ValidationSummary { + return validateBracketTargets(bots.map((b) => b.bracket)); +} + +/** Convenience helpers for the dry-run printout. */ +export function summariseCountries(bots: ReadonlyArray): Record { + const out: Record = {}; + for (const b of bots) { + out[b.identity.country] = (out[b.identity.country] ?? 0) + 1; + } + return out; +} + +export function summariseAvatars(bots: ReadonlyArray): Record { + const out: Record = {}; + for (const b of bots) { + out[b.avatar.kind] = (out[b.avatar.kind] ?? 0) + 1; + } + return out; +} + +export function summariseEngagement( + bots: ReadonlyArray, +): Record { + const out: Record = {}; + for (const b of bots) { + out[b.personality.engagement_tier] = + (out[b.personality.engagement_tier] ?? 0) + 1; + } + return out; +} + +export function summariseCupWinners(bots: ReadonlyArray): { + top6_rate: number; + distribution: Record; +} { + const dist: Record = {}; + for (const b of bots) { + dist[b.bracket.cup_winner_team3] = + (dist[b.bracket.cup_winner_team3] ?? 0) + 1; + } + const top6 = TOP6_NATIONS.reduce((a, c) => a + (dist[c] ?? 0), 0); + return { + top6_rate: bots.length > 0 ? top6 / bots.length : 0, + distribution: dist, + }; +} + +// Re-export so write.ts and the CLI share one fixture row type. +export type { FixtureRow }; diff --git a/apps/seed-bots/src/timeline.ts b/apps/seed-bots/src/timeline.ts new file mode 100644 index 00000000..2578db36 --- /dev/null +++ b/apps/seed-bots/src/timeline.ts @@ -0,0 +1,149 @@ +/** + * Activity-timeline generator (spec §4.4). + * + * Distribution of `created_at`: + * - 6k bots backdated 26 May - 6 June (early tail). + * - 12k bots ramping 7-11 June (press momentum). + * - Both clusters skew toward evenings + weekends + press dates. + * + * Per-bot save events: + * - high engagement (10%): 3-5 saves at random pre-lock timestamps. + * - medium (30%): 1-2 saves. + * - low (60%): 1 save (set-and-forget). + * + * For 100-bot test runs we scale the backdate / ramp boundary + * proportionally so the distribution still makes sense. + * + * All times produced are UNIX-seconds. + */ + +import { makeRng, type Rng } from "./rng.js"; +import type { Personality } from "./personalities.js"; + +// ---------- date constants ---------- + +// 11 June 2026 19:00 UTC -- first match kickoff. Saves must lock by this. +const KICKOFF_UTC_SECS = Math.floor(Date.UTC(2026, 5, 11, 19, 0, 0) / 1000); + +// Early-tail window: 26 May 2026 00:00 UTC -> 6 June 2026 23:59 UTC. +const EARLY_START = Math.floor(Date.UTC(2026, 4, 26, 0, 0, 0) / 1000); +const EARLY_END = Math.floor(Date.UTC(2026, 5, 6, 23, 59, 59) / 1000); + +// Press-momentum window: 7 June 2026 00:00 UTC -> 11 June 2026 18:00 UTC. +const RAMP_START = Math.floor(Date.UTC(2026, 5, 7, 0, 0, 0) / 1000); +const RAMP_END = Math.floor(Date.UTC(2026, 5, 11, 18, 0, 0) / 1000); + +// Press-release dates the spec calls out (extra mass on these days): +// - 2 June (early tail) and 8 June (ramp). +const PRESS_DATES_UTC_DAYS: readonly number[] = [ + Math.floor(Date.UTC(2026, 5, 2) / 86400_000), + Math.floor(Date.UTC(2026, 5, 8) / 86400_000), +]; + +// ---------- shape helpers ---------- + +/** True if the given unix-seconds is a Sat or Sun in UTC. */ +function isWeekend(utcSecs: number): boolean { + const dow = new Date(utcSecs * 1000).getUTCDay(); + return dow === 0 || dow === 6; +} + +/** True if the unix-seconds is on a tagged press date. */ +function isPressDate(utcSecs: number): boolean { + const dayIdx = Math.floor(utcSecs / 86400); + return PRESS_DATES_UTC_DAYS.includes(dayIdx); +} + +/** True if the unix-seconds local UTC hour is in [18, 23] (evening-ish). */ +function isEvening(utcSecs: number): boolean { + const h = new Date(utcSecs * 1000).getUTCHours(); + return h >= 18 && h <= 23; +} + +/** + * Sample a timestamp from a window via rejection: draw uniform from the + * window, accept with a probability that boosts evenings + weekends + + * press dates. Bounded re-tries so a single bot can't loop. + */ +function sampleWindow(rng: Rng, lo: number, hi: number): number { + for (let attempt = 0; attempt < 32; attempt++) { + const t = lo + Math.floor(rng() * (hi - lo + 1)); + let accept = 0.35; // baseline + if (isEvening(t)) accept += 0.25; + if (isWeekend(t)) accept += 0.2; + if (isPressDate(t)) accept += 0.2; + if (rng() < accept) return t; + } + return Math.floor((lo + hi) / 2); +} + +// ---------- public types ---------- + +export interface BotTimeline { + readonly created_at_secs: number; + /** + * Save events in chronological order. The last save is the locked + * bracket; earlier saves represent the user "tweaking" their picks. + * For DB write purposes only the LAST save matters (it's the locked + * version). Earlier ones are recorded for forensic / analytics use. + */ + readonly save_events_secs: readonly number[]; +} + +// ---------- public API ---------- + +/** + * Roll an activity timeline for one bot. `index` decides which window + * the bot lands in (early-tail vs ramp). `target` scales the cutoff + * for smaller test cohorts. + * + * Spec exact split: 6k early-tail, 12k ramp on the 18k cohort + * (one-third / two-thirds). We scale proportionally so a 100-bot test + * run has ~33 early-tail and ~67 ramp. + */ +export function rollTimeline(args: { + masterSeed: string; + index: number; + target: number; + personality: Personality; +}): BotTimeline { + const { masterSeed, index, target, personality } = args; + + const earlyCutoff = Math.floor(target / 3); // 33% backdated. + const isEarly = index < earlyCutoff; + + const rngCreate = makeRng(`${masterSeed}:timeline:create:${index}`); + const created_at_secs = isEarly + ? sampleWindow(rngCreate, EARLY_START, EARLY_END) + : sampleWindow(rngCreate, RAMP_START, RAMP_END); + + // Save events: chronologically after created_at, all before kickoff. + const rngSaves = makeRng(`${masterSeed}:timeline:saves:${index}`); + let saveCount: number; + if (personality.engagement_tier === "high") { + saveCount = 3 + Math.floor(rngSaves() * 3); // 3-5 + } else if (personality.engagement_tier === "med") { + saveCount = 1 + Math.floor(rngSaves() * 2); // 1-2 + } else { + saveCount = 1; + } + + const lo = created_at_secs; + const hi = KICKOFF_UTC_SECS - 60; // lock 60s before kickoff + const events: number[] = []; + for (let i = 0; i < saveCount; i++) { + events.push(sampleWindow(rngSaves, lo, hi)); + } + events.sort((a, b) => a - b); + + return { created_at_secs, save_events_secs: events }; +} + +/** Exposed for the validator / dry-run summary. */ +export const TIMELINE_BOUNDS = { + KICKOFF_UTC_SECS, + EARLY_START, + EARLY_END, + RAMP_START, + RAMP_END, +} as const; diff --git a/apps/seed-bots/src/write.ts b/apps/seed-bots/src/write.ts new file mode 100644 index 00000000..e22a0882 --- /dev/null +++ b/apps/seed-bots/src/write.ts @@ -0,0 +1,476 @@ +/** + * Three-store writer. + * + * Idempotent on the deterministic bot id (`bot_<8-char-base32>`). Re-runs + * with the same master seed overwrite existing rows in place; `--purge` + * wipes every `bot_%` row in every store. + * + * Stores touched: + * 1. apps/auth-sms `user` table (with `is_bot=1`). We add the + * `is_bot` column defensively if Agent A1's migration has not + * landed yet so this CLI is order-independent. + * 2. apps/identity humanness JSONL (`humanness-scores.jsonl`). One + * `{ userId, score: 0, factors: [], computedAt }` entry per bot. + * 3. apps/game `brackets` table. One row per bot with the locked + * payload, locked_at, and a deterministic share_guid. + * + * Paths come from env vars with sensible repo-relative defaults so + * `pnpm --filter seed-bots run seed -- --apply` does the right thing on + * the dev server without further configuration. + */ + +import { createHash } from "node:crypto"; +import { + appendFileSync, + existsSync, + mkdirSync, + readdirSync, + readFileSync, + renameSync, + writeFileSync, +} from "node:fs"; +import { dirname, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; + +import Database from "better-sqlite3"; +import type { Database as DatabaseT } from "better-sqlite3"; + +import type { Bot } from "./seed.js"; +import { loadFixtures, type FixtureRow } from "./brackets.js"; + +// ---------- path resolution ---------- + +const here = dirname(fileURLToPath(import.meta.url)); +const REPO_ROOT = resolve(here, "..", "..", ".."); + +function envOr(name: string, fallback: string): string { + const v = process.env[name]; + return v && v.length > 0 ? v : fallback; +} + +function authDbPath(): string { + return envOr("AUTH_DB_PATH", resolve(REPO_ROOT, "apps/auth-sms/data/auth.db")); +} + +function gameDbPath(): string { + return envOr("GAME_DB_PATH", resolve(REPO_ROOT, "apps/game/game.db")); +} + +function gameMigrationsDir(): string { + return envOr( + "GAME_MIGRATIONS_DIR", + resolve(REPO_ROOT, "apps/game/migrations"), + ); +} + +function identityScoresPath(): string { + return envOr( + "IDENTITY_SCORES_PATH", + resolve(REPO_ROOT, "apps/identity/data/humanness-scores.jsonl"), + ); +} + +// ---------- helpers ---------- + +function deriveShareGuid(botId: string): string { + // 16-char lower-hex, matching the game store's nanoid-style guid. + return createHash("sha256") + .update(`${botId}:share-guid`) + .digest("hex") + .slice(0, 16); +} + +function deriveBracketRowId(botId: string): string { + return createHash("sha256") + .update(`${botId}:bracket-row`) + .digest("hex") + .slice(0, 22); +} + +function buildBracketPayload(args: { + bracketId: string; + fixtures: readonly FixtureRow[]; + bot: Bot; +}): string { + const { bracketId, fixtures, bot } = args; + const matchPredictions: Record = {}; + const knockoutPredictions: Record = {}; + // Map fixture stage -> classifier + const byMatch = new Map(); + for (const f of fixtures) byMatch.set(f.match_number, f); + + // Use the LAST save event as the lockedAt for every pick (the + // bracket is locked as a whole, not per-match, in the seed model). + const lockSecs = + bot.timeline.save_events_secs[bot.timeline.save_events_secs.length - 1] ?? + bot.timeline.created_at_secs; + const lockIso = new Date(lockSecs * 1000).toISOString(); + + for (const p of bot.bracket.picks) { + const matchId = String(p.match_number); + const entry = { + matchId, + outcome: p.outcome, + lockedAt: lockIso, + source: "live" as const, + }; + if (p.stage === "group") { + matchPredictions[matchId] = entry; + } else { + knockoutPredictions[matchId] = entry; + } + } + + const payload = { + bracketId, + matchPredictions, + knockoutPredictions, + groupTiebreakers: {}, + version: 1, + lockedAt: lockIso, + // Non-standard fields the seed pipeline records for forensics. + _seed: { + cup_winner: bot.bracket.cup_winner_team3, + chalk_score: bot.personality.chalk_score, + engagement_tier: bot.personality.engagement_tier, + is_bot: 1, + }, + }; + return JSON.stringify(payload); +} + +// ---------- column / table migration (defensive) ---------- + +function ensureIsBotColumn(db: DatabaseT): void { + const cols = db.prepare(`PRAGMA table_info(user)`).all() as Array<{ + name: string; + }>; + const has = cols.some((c) => c.name === "is_bot"); + if (!has) { + db.exec(`ALTER TABLE user ADD COLUMN is_bot INTEGER NOT NULL DEFAULT 0`); + db.exec(`CREATE INDEX IF NOT EXISTS idx_user_is_bot ON user(is_bot)`); + } +} + +// ---------- public API ---------- + +export interface WriteStats { + readonly users_written: number; + readonly humanness_written: number; + readonly brackets_written: number; +} + +export function writeBots(bots: readonly Bot[]): WriteStats { + const fixtures = loadFixtures(); + + // ----- auth-sms users ----- + const authPath = authDbPath(); + mkdirSync(dirname(authPath), { recursive: true }); + const authDb = new Database(authPath); + authDb.pragma("journal_mode = WAL"); + authDb.pragma("foreign_keys = ON"); + // We don't run the full auth-sms schema here; if the user table + // doesn't exist the auth service has never booted on this DB so + // there's nothing to seed against. Create the minimal shape. + authDb.exec(` + CREATE TABLE IF NOT EXISTS user ( + id TEXT PRIMARY KEY, + phone TEXT, + display_name TEXT, + country TEXT, + telegram_id INTEGER, + telegram_username TEXT, + created_at INTEGER NOT NULL, + last_seen_at INTEGER NOT NULL, + email TEXT, + first_name TEXT, + last_name TEXT, + city TEXT, + favourite_team_code TEXT, + highlevel_contact_id TEXT, + highlevel_synced_at INTEGER + ); + `); + ensureIsBotColumn(authDb); + + const upsertUser = authDb.prepare(` + INSERT INTO user ( + id, phone, display_name, country, created_at, last_seen_at, + first_name, last_name, favourite_team_code, is_bot + ) VALUES ( + @id, NULL, @display_name, @country, @created_at, @last_seen_at, + @first_name, @last_name, @favourite_team_code, 1 + ) + ON CONFLICT(id) DO UPDATE SET + display_name = excluded.display_name, + country = excluded.country, + last_seen_at = excluded.last_seen_at, + first_name = excluded.first_name, + last_name = excluded.last_name, + favourite_team_code = excluded.favourite_team_code, + is_bot = 1 + `); + + const userTx = authDb.transaction((rows: ReadonlyArray) => { + for (const bot of rows) { + upsertUser.run({ + id: bot.bot_id, + display_name: bot.identity.display_name, + country: bot.identity.country.toUpperCase(), + created_at: bot.timeline.created_at_secs, + last_seen_at: bot.timeline.created_at_secs, + first_name: bot.identity.first_name, + last_name: bot.identity.last_name, + favourite_team_code: bot.favourite_team3, + }); + } + }); + userTx(bots); + const usersWritten = bots.length; + authDb.close(); + + // ----- identity humanness JSONL ----- + const scoresPath = identityScoresPath(); + mkdirSync(dirname(scoresPath), { recursive: true }); + // Idempotency: if the file already lists this bot at score=0, skip. + // Cheap one-time read; the seed run only happens occasionally. + const existing = readExistingScoreUserIds(scoresPath); + let humannessWritten = 0; + for (const bot of bots) { + if (existing.has(bot.bot_id)) continue; + const snap = { + userId: bot.bot_id, + score: 0, + factors: [ + { + id: "seed_bot", + weight: 1, + value: 0, + contribution: 0, + note: "cosmetic seed bot; is_bot=1", + }, + ], + computedAt: bot.timeline.created_at_secs * 1000, + }; + appendFileSync(scoresPath, `${JSON.stringify(snap)}\n`); + humannessWritten++; + } + + // ----- game brackets ----- + const gamePath = gameDbPath(); + mkdirSync(dirname(gamePath), { recursive: true }); + const gameDb = new Database(gamePath); + gameDb.pragma("journal_mode = WAL"); + gameDb.pragma("foreign_keys = ON"); + applyGameMigrations(gameDb); + ensureBracketsShape(gameDb); + + const upsertGameUser = gameDb.prepare( + `INSERT INTO users (id, created_at) VALUES (?, ?) + ON CONFLICT(id) DO NOTHING`, + ); + const upsertBracket = gameDb.prepare(` + INSERT INTO brackets ( + id, user_id, tournament_id, payload_json, locked_at, score_total, share_guid + ) VALUES ( + @id, @user_id, @tournament_id, @payload_json, @locked_at, 0, @share_guid + ) + ON CONFLICT(id) DO UPDATE SET + payload_json = excluded.payload_json, + locked_at = excluded.locked_at, + share_guid = excluded.share_guid + `); + + let bracketsWritten = 0; + const tournamentId = "fifa-wc-2026"; + + const bracketTx = gameDb.transaction((rows: ReadonlyArray) => { + for (const bot of rows) { + const bracketId = deriveBracketRowId(bot.bot_id); + const shareGuid = deriveShareGuid(bot.bot_id); + const lockSecs = + bot.timeline.save_events_secs[bot.timeline.save_events_secs.length - 1] ?? + bot.timeline.created_at_secs; + upsertGameUser.run(bot.bot_id, bot.timeline.created_at_secs * 1000); + upsertBracket.run({ + id: bracketId, + user_id: bot.bot_id, + tournament_id: tournamentId, + payload_json: buildBracketPayload({ bracketId, fixtures, bot }), + locked_at: lockSecs * 1000, // ms, matches existing brackets.locked_at + share_guid: shareGuid, + }); + bracketsWritten++; + } + }); + bracketTx(bots); + gameDb.close(); + + return { + users_written: usersWritten, + humanness_written: humannessWritten, + brackets_written: bracketsWritten, + }; +} + +// ---------- purge ---------- + +export interface PurgeStats { + readonly users_deleted: number; + readonly humanness_lines_dropped: number; + readonly brackets_deleted: number; +} + +export function purgeBots(): PurgeStats { + // Auth-sms users. + const authDb = new Database(authDbPath()); + let usersDeleted = 0; + const authHasUserTable = authDb + .prepare( + `SELECT name FROM sqlite_master WHERE type='table' AND name='user'`, + ) + .get(); + if (authHasUserTable) { + const r = authDb.prepare(`DELETE FROM user WHERE id LIKE 'bot_%'`).run(); + usersDeleted = r.changes ?? 0; + } + authDb.close(); + + // Identity scores JSONL: rewrite without bot rows. + let linesDropped = 0; + const scoresPath = identityScoresPath(); + if (existsSync(scoresPath)) { + const raw = readFileSync(scoresPath, "utf8"); + const lines = raw.split("\n"); + const kept: string[] = []; + for (const line of lines) { + if (!line.trim()) { + kept.push(line); + continue; + } + try { + const obj = JSON.parse(line) as { userId?: string }; + if (typeof obj.userId === "string" && obj.userId.startsWith("bot_")) { + linesDropped++; + continue; + } + } catch { + // keep unparseable line so we never lose data + } + kept.push(line); + } + // Rewrite atomically. + writeFileSync(`${scoresPath}.tmp`, kept.join("\n")); + renameSync(`${scoresPath}.tmp`, scoresPath); + } + + // Game brackets + users. + const gameDb = new Database(gameDbPath()); + let bracketsDeleted = 0; + const gameHasBrackets = gameDb + .prepare( + `SELECT name FROM sqlite_master WHERE type='table' AND name='brackets'`, + ) + .get(); + if (gameHasBrackets) { + const r = gameDb + .prepare(`DELETE FROM brackets WHERE user_id LIKE 'bot_%'`) + .run(); + bracketsDeleted = r.changes ?? 0; + gameDb.prepare(`DELETE FROM users WHERE id LIKE 'bot_%'`).run(); + } + gameDb.close(); + + return { + users_deleted: usersDeleted, + humanness_lines_dropped: linesDropped, + brackets_deleted: bracketsDeleted, + }; +} + +// ---------- internal: identity dedupe ---------- + +function readExistingScoreUserIds(path: string): Set { + const out = new Set(); + if (!existsSync(path)) return out; + const raw = readFileSync(path, "utf8"); + for (const line of raw.split("\n")) { + if (!line.trim()) continue; + try { + const o = JSON.parse(line) as { userId?: string }; + if (typeof o.userId === "string") out.add(o.userId); + } catch { + /* ignore corrupt line */ + } + } + return out; +} + +// ---------- internal: game schema bootstrap ---------- + +/** + * Apply game migrations from `apps/game/migrations/` if the migrations + * table is missing or out of date. We mirror the migration runner in + * `apps/game/src/store/db.ts` so a never-booted dev DB acquires a + * working schema without first starting the game service. + */ +function applyGameMigrations(db: DatabaseT): void { + db.exec(` + CREATE TABLE IF NOT EXISTS _migrations ( + id TEXT PRIMARY KEY, + applied_at INTEGER NOT NULL + ); + `); + const dir = gameMigrationsDir(); + if (!existsSync(dir)) return; // tests with mocked DB path + const files = readdirSync(dir) + .filter((f) => f.endsWith(".sql")) + .sort(); + const applied = new Set( + (db.prepare(`SELECT id FROM _migrations`).all() as { id: string }[]).map( + (r) => r.id, + ), + ); + const insert = db.prepare( + `INSERT INTO _migrations (id, applied_at) VALUES (?, ?)`, + ); + for (const f of files) { + if (applied.has(f)) continue; + const sql = readFileSync(resolve(dir, f), "utf8"); + db.exec("BEGIN"); + try { + db.exec(sql); + insert.run(f, Date.now()); + db.exec("COMMIT"); + } catch (err) { + db.exec("ROLLBACK"); + throw err; + } + } +} + +/** + * Defensive: the brackets table is created by migration 0001 in the + * game service. If anything went sideways we still want the seed run + * to surface a clear error rather than crash with a SQL syntax error. + */ +function ensureBracketsShape(db: DatabaseT): void { + const tbl = db + .prepare( + `SELECT name FROM sqlite_master WHERE type='table' AND name='brackets'`, + ) + .get(); + if (!tbl) { + throw new Error( + "game DB is missing `brackets` table. Run the game service " + + "once to apply migrations, then re-run the seed CLI.", + ); + } + const cols = db.prepare(`PRAGMA table_info(brackets)`).all() as Array<{ + name: string; + }>; + const names = new Set(cols.map((c) => c.name)); + if (!names.has("share_guid")) { + db.exec(`ALTER TABLE brackets ADD COLUMN share_guid TEXT`); + } +} diff --git a/apps/seed-bots/test/seed.test.ts b/apps/seed-bots/test/seed.test.ts new file mode 100644 index 00000000..70a31175 --- /dev/null +++ b/apps/seed-bots/test/seed.test.ts @@ -0,0 +1,101 @@ +/** + * Determinism + validation-target regression test. + * + * 100 bots is small enough to run inside CI in <1s but large enough + * that the favourite / draw / top-6 rates approach their target rates + * within +-3pp. The CLI applies the stricter +-2pp threshold at write + * time on the full 18k cohort; tests use +-3pp because n=100 sampling + * noise is bigger than the 18k production cohort's. + */ + +import { describe, expect, it } from "vitest"; + +import { generateBots, validateTargets } from "../src/seed.js"; + +const SEED = "tournamental-2026-seed-v1"; + +describe("seed pipeline", () => { + it("generates 100 deterministic bots that pass validation targets", () => { + const bots = generateBots({ seed: SEED, target: 100 }); + expect(bots).toHaveLength(100); + + // Bot ids look like `bot_<8-char-base32>`. + for (const b of bots) { + expect(b.bot_id).toMatch(/^bot_[a-z2-7]{8}$/); + } + + const targets = validateTargets(bots); + expect(targets.favourite_rate).toBeGreaterThanOrEqual(0.72); + expect(targets.favourite_rate).toBeLessThanOrEqual(0.78); + expect(targets.draw_rate).toBeGreaterThanOrEqual(0.12); + expect(targets.draw_rate).toBeLessThanOrEqual(0.18); + expect(targets.top6_cup_winner_rate).toBeGreaterThanOrEqual(0.82); + }); + + it("is byte-deterministic across runs with the same seed", () => { + const a = generateBots({ seed: SEED, target: 10 }); + const b = generateBots({ seed: SEED, target: 10 }); + expect(a.map((x) => x.bot_id)).toEqual(b.map((x) => x.bot_id)); + expect(a.map((x) => x.identity.display_name)).toEqual( + b.map((x) => x.identity.display_name), + ); + expect(a[0]?.bracket.picks.map((p) => p.outcome)).toEqual( + b[0]?.bracket.picks.map((p) => p.outcome), + ); + expect(a.map((x) => x.bracket.cup_winner_team3)).toEqual( + b.map((x) => x.bracket.cup_winner_team3), + ); + }); + + it("produces a different cohort with a different seed", () => { + const a = generateBots({ seed: SEED, target: 10 }); + const b = generateBots({ seed: "different-seed-v1", target: 10 }); + expect(a.map((x) => x.bot_id)).not.toEqual(b.map((x) => x.bot_id)); + }); + + it("respects the engagement-tier weights", () => { + const bots = generateBots({ seed: SEED, target: 200 }); + let high = 0, + med = 0, + low = 0; + for (const b of bots) { + if (b.personality.engagement_tier === "high") high++; + else if (b.personality.engagement_tier === "med") med++; + else low++; + } + // Generous bands for n=200; spec target is 10/30/60 percent. + expect(high / bots.length).toBeGreaterThanOrEqual(0.05); + expect(high / bots.length).toBeLessThanOrEqual(0.18); + expect(med / bots.length).toBeGreaterThanOrEqual(0.22); + expect(med / bots.length).toBeLessThanOrEqual(0.4); + expect(low / bots.length).toBeGreaterThanOrEqual(0.5); + }); + + it("composes handles as firstname__", () => { + const bots = generateBots({ seed: SEED, target: 25 }); + for (const b of bots) { + expect(b.identity.handle).toMatch(/^[a-z0-9]+_[a-z]{3}_\d{2}$/); + expect(b.identity.handle).toContain( + `_${b.favourite_team3.toLowerCase()}_`, + ); + } + }); + + it("rolls 104 picks per bot covering every fixture", () => { + const [bot] = generateBots({ seed: SEED, target: 1 }); + expect(bot).toBeDefined(); + if (!bot) return; + expect(bot.bracket.picks).toHaveLength(104); + // Group picks numbered 1..72; knockout 73..104 per the canonical + // fixtures.json. + const groupMatchNos = bot.bracket.picks + .filter((p) => p.stage === "group") + .map((p) => p.match_number); + expect(groupMatchNos.sort((a, b) => a - b)[0]).toBe(1); + expect(groupMatchNos.length).toBe(72); + const koMatchNos = bot.bracket.picks + .filter((p) => p.stage !== "group") + .map((p) => p.match_number); + expect(koMatchNos.length).toBe(32); + }); +}); diff --git a/apps/seed-bots/tsconfig.json b/apps/seed-bots/tsconfig.json new file mode 100644 index 00000000..e79a0db9 --- /dev/null +++ b/apps/seed-bots/tsconfig.json @@ -0,0 +1,12 @@ +{ + "extends": "../../tsconfig.base.json", + "compilerOptions": { + "outDir": "dist", + "rootDir": ".", + "declaration": true, + "sourceMap": true, + "resolveJsonModule": true + }, + "include": ["src/**/*", "test/**/*"], + "exclude": ["dist", "node_modules"] +} diff --git a/apps/seed-bots/vitest.config.ts b/apps/seed-bots/vitest.config.ts new file mode 100644 index 00000000..5fab2394 --- /dev/null +++ b/apps/seed-bots/vitest.config.ts @@ -0,0 +1,8 @@ +import { defineConfig } from "vitest/config"; + +export default defineConfig({ + test: { + include: ["test/**/*.test.ts"], + testTimeout: 30_000, + }, +}); diff --git a/apps/web/__tests__/bots-sdk-page-renders.test.tsx b/apps/web/__tests__/bots-sdk-page-renders.test.tsx new file mode 100644 index 00000000..9bd37d0a --- /dev/null +++ b/apps/web/__tests__/bots-sdk-page-renders.test.tsx @@ -0,0 +1,60 @@ +/** + * Vitest, /bots/sdk page renders the eight section anchors. + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §10 + * Eight sections must be present so the on-page TOC anchors resolve + * and the developer-doc surface stays predictable. We assert on + * stable element ids rather than copy so editorial polish doesn't + * keep breaking the test. + */ + +import { describe, it, expect, vi } from "vitest"; +import { render } from "@testing-library/react"; + +// AppShell mounts an extensive header / nav surface that pulls in +// next-intl + auth chips + locale picker. None of that is interesting +// for "did the SDK page mount its eight sections", so stub it to a +// thin pass-through. Same trick used by other page-level renderer tests +// in this suite. +vi.mock("@/components/shell", () => ({ + AppShell: ({ children }: { children: React.ReactNode }) => <>{children}, +})); + +import BotsSdkPage from "@/app/bots/sdk/page"; + +describe("/bots/sdk page", () => { + it("renders the eight TOC sections by stable id", () => { + const { container } = render(); + const expectedIds = [ + "quickstart", + "architecture", + "api-reference", + "bulk-insert", + "quotas", + "feeds", + "examples", + "faq", + ] as const; + for (const id of expectedIds) { + const el = container.querySelector(`#${id}`); + expect(el, `expected #${id} to exist`).toBeTruthy(); + } + }); + + it("links to the keys issuance page", () => { + const { container } = render(); + const link = container.querySelector("a[href='/bots/keys']"); + expect(link).toBeTruthy(); + }); + + it("links to the federated bot-node docs", () => { + const { container } = render(); + const link = container.querySelector("a[href='/bots/node']"); + expect(link).toBeTruthy(); + }); + + it("includes the Humanness 50 disclaimer in the FAQ", () => { + const { container } = render(); + expect(container.textContent).toMatch(/Humanness Score of 50 or higher/i); + }); +}); diff --git a/apps/web/__tests__/browser-swarm-anchor.test.ts b/apps/web/__tests__/browser-swarm-anchor.test.ts new file mode 100644 index 00000000..e8f28c35 --- /dev/null +++ b/apps/web/__tests__/browser-swarm-anchor.test.ts @@ -0,0 +1,98 @@ +/** + * Unit tests for the user-anchored swarm blend. + * + * Verifies that: + * - Anchor mode -> weight constants are stable. + * - blendOutcome returns chalk when weight=0 OR no user pick. + * - blendOutcome returns user pick when weight=1 AND user pick exists. + * - For intermediate weights the blend picks user pick iff + * `r < weight`. + * - The hash function is deterministic + sensitive to pick changes. + */ + +import { describe, expect, it } from "vitest"; + +import { + ANCHOR_WEIGHT_BY_MODE, + blendOutcome, + captureAnchorSnapshot, + flattenBracket, + type AnchorSnapshot, +} from "@/components/browser-swarm/anchor"; + +function snapshot(picks: Record, weight: number): AnchorSnapshot { + return { + weight, + picks, + bracket_hash: "test", + captured_at_utc: "1970-01-01T00:00:00Z", + }; +} + +describe("browser-swarm anchor", () => { + it("anchor weight constants are stable", () => { + expect(ANCHOR_WEIGHT_BY_MODE.off).toBe(0); + expect(ANCHOR_WEIGHT_BY_MODE.soft).toBeCloseTo(0.4); + expect(ANCHOR_WEIGHT_BY_MODE.strong).toBeCloseTo(0.75); + expect(ANCHOR_WEIGHT_BY_MODE.lockstep).toBe(1); + }); + + it("blends to chalk when weight is 0", () => { + const snap = snapshot({ "1": "draw" }, 0); + expect(blendOutcome("1", "home_win", snap, 0)).toBe("home_win"); + expect(blendOutcome("1", "home_win", snap, 0.99)).toBe("home_win"); + }); + + it("blends to user pick when weight is 1 and user pick exists", () => { + const snap = snapshot({ "1": "draw" }, 1); + expect(blendOutcome("1", "home_win", snap, 0)).toBe("draw"); + expect(blendOutcome("1", "home_win", snap, 0.5)).toBe("draw"); + expect(blendOutcome("1", "home_win", snap, 0.99)).toBe("draw"); + }); + + it("falls back to chalk for matches the user hasn't picked", () => { + const snap = snapshot({ "1": "draw" }, 1); + expect(blendOutcome("99", "away_win", snap, 0)).toBe("away_win"); + }); + + it("respects the [0, weight) draw boundary for intermediate weights", () => { + const snap = snapshot({ "1": "draw" }, 0.4); + // r below weight -> user pick wins. + expect(blendOutcome("1", "home_win", snap, 0.0)).toBe("draw"); + expect(blendOutcome("1", "home_win", snap, 0.39)).toBe("draw"); + // r at or above weight -> chalk wins. + expect(blendOutcome("1", "home_win", snap, 0.4)).toBe("home_win"); + expect(blendOutcome("1", "home_win", snap, 0.99)).toBe("home_win"); + }); + + it("flattenBracket combines group + knockout predictions", () => { + const flat = flattenBracket({ + bracketId: "b1", + matchPredictions: { + "1": { + matchId: "1", + outcome: "home_win", + lockedAt: "1970-01-01T00:00:00Z", + }, + }, + knockoutPredictions: { + r32_01: { + matchId: "r32_01", + outcome: "away_win", + lockedAt: "1970-01-01T00:00:00Z", + }, + }, + groupTiebreakers: {}, + version: 1, + }); + expect(flat["1"]).toBe("home_win"); + expect(flat["r32_01"]).toBe("away_win"); + }); + + it("captureAnchorSnapshot returns a stable hash for empty drafts", () => { + const a = captureAnchorSnapshot("fifa-wc-2026", "off"); + const b = captureAnchorSnapshot("fifa-wc-2026", "off"); + expect(a.bracket_hash).toBe(b.bracket_hash); + expect(a.weight).toBe(0); + }); +}); diff --git a/apps/web/__tests__/browser-swarm-cascade.test.ts b/apps/web/__tests__/browser-swarm-cascade.test.ts new file mode 100644 index 00000000..cb8c69f5 --- /dev/null +++ b/apps/web/__tests__/browser-swarm-cascade.test.ts @@ -0,0 +1,88 @@ +/** + * Unit tests for the per-bot bracket cascade resolver. + * + * Verifies that: + * - Real fixture loading succeeds (104 matches, 12 groups of 4). + * - For sample bot indices the cascade returns CONCRETE team ids on + * every knockout fixture rather than the placeholder slot labels. + * - Determinism: same bot index returns the same cascaded bracket + * across two invocations. + */ + +import { describe, expect, it } from "vitest"; + +import { + resolveBotBracket, + resolvedKnockoutSlots, +} from "@/components/browser-swarm/cascade"; +import { + MASTER_SEED, + buildDemoMatches, +} from "@/components/browser-swarm/regenerate"; + +describe("browser-swarm cascade", () => { + it("loads the 104-match WC 2026 schedule", () => { + const matches = buildDemoMatches(); + expect(matches.length).toBe(104); + const groups = matches.filter((m) => m.allows_draw); + const knockouts = matches.filter((m) => !m.allows_draw); + expect(groups.length).toBe(72); + expect(knockouts.length).toBe(32); + }); + + it("resolves every knockout to concrete team ids for bot 0", () => { + const matches = buildDemoMatches(); + const resolved = resolveBotBracket(MASTER_SEED, 0, matches); + expect(resolved.cascaded.knockouts.length).toBe(32); + for (const k of resolved.cascaded.knockouts) { + expect(k.home.team).toBeTruthy(); + expect(k.away.team).toBeTruthy(); + // No more placeholder strings like "winner_grpA": the resolver + // must hand the UI a real ISO code so it can show "France" / "ARG" + // / "USA" etc. + expect(typeof k.home.team).toBe("string"); + expect(typeof k.away.team).toBe("string"); + expect(k.home.team!.length).toBeLessThanOrEqual(5); + expect(k.away.team!.length).toBeLessThanOrEqual(5); + } + }); + + it("resolves every knockout to concrete team ids for bot 12345", () => { + const matches = buildDemoMatches(); + const resolved = resolveBotBracket(MASTER_SEED, 12_345, matches); + expect(resolved.cascaded.knockouts.length).toBe(32); + for (const k of resolved.cascaded.knockouts) { + expect(k.home.team).toBeTruthy(); + expect(k.away.team).toBeTruthy(); + } + }); + + it("picks a concrete winner for every knockout fixture", () => { + const matches = buildDemoMatches(); + const resolved = resolveBotBracket(MASTER_SEED, 42, matches); + const final = resolved.cascaded.knockouts.find((k) => k.stage === "f"); + expect(final).toBeTruthy(); + expect(final!.predicted_winner).toBeTruthy(); + }); + + it("returns the same cascaded bracket for repeat calls", () => { + const matches = buildDemoMatches(); + const a = resolveBotBracket(MASTER_SEED, 7, matches); + const b = resolveBotBracket(MASTER_SEED, 7, matches); + expect(a.cascaded.knockouts.map((k) => k.predicted_winner)).toEqual( + b.cascaded.knockouts.map((k) => k.predicted_winner), + ); + expect(a.prediction.best_thirds).toEqual(b.prediction.best_thirds); + }); + + it("exposes resolvedKnockoutSlots for the detail page", () => { + const matches = buildDemoMatches(); + const resolved = resolveBotBracket(MASTER_SEED, 1, matches); + const r32 = resolved.cascaded.knockouts[0]!; + const lookup = resolvedKnockoutSlots(resolved.cascaded, r32.id); + expect(lookup).not.toBeNull(); + expect(lookup!.home).toBe(r32.home.team); + expect(lookup!.away).toBe(r32.away.team); + expect(lookup!.winner).toBe(r32.predicted_winner); + }); +}); diff --git a/apps/web/__tests__/browser-swarm-uniqueness.test.ts b/apps/web/__tests__/browser-swarm-uniqueness.test.ts new file mode 100644 index 00000000..8e3d0ddb --- /dev/null +++ b/apps/web/__tests__/browser-swarm-uniqueness.test.ts @@ -0,0 +1,91 @@ +/** + * Unit tests for the within-swarm uniqueness perturbation algorithm. + * + * Verifies that: + * - Bot 0 is the pure chalk bracket (no deviations). + * - Bots 1..S each flip exactly one outcome relative to chalk, and + * the flips are all distinct (single-deviation coverage). + * - For an arbitrary swarm of N bots, every pair of bots produces a + * structurally distinct bracket (no two bots ever share all 104 + * outcomes). + * - The unranking is deterministic across calls. + */ + +import { describe, expect, it } from "vitest"; + +import { buildDemoMatches } from "@/components/browser-swarm/regenerate"; +import { + buildDeviationTable, + deviationSlotsForBotIndex, + perturbedBracket, + singleDeviationCount, +} from "@/components/browser-swarm/uniqueness"; + +describe("browser-swarm uniqueness", () => { + it("bot 0 is the pure chalk bracket (no deviations)", () => { + const matches = buildDemoMatches(); + const table = buildDeviationTable(matches); + const b0 = perturbedBracket(table, 0); + expect(b0).toEqual([...table.favouriteByMatchIdx]); + }); + + it("bots 1..S flip exactly one outcome each", () => { + const matches = buildDemoMatches(); + const table = buildDeviationTable(matches); + const S = singleDeviationCount(table); + expect(S).toBeGreaterThan(0); + const chalk = perturbedBracket(table, 0); + for (let i = 1; i <= S; i++) { + const bracket = perturbedBracket(table, i); + let diffs = 0; + for (let m = 0; m < chalk.length; m++) { + if (bracket[m] !== chalk[m]) diffs++; + } + expect(diffs).toBe(1); + } + }); + + it("single-deviation brackets are all distinct from each other", () => { + const matches = buildDemoMatches(); + const table = buildDeviationTable(matches); + const S = singleDeviationCount(table); + const seen = new Set(); + for (let i = 0; i <= S; i++) { + const key = perturbedBracket(table, i).join("|"); + expect(seen.has(key)).toBe(false); + seen.add(key); + } + }); + + it("two distinct bot indices produce structurally distinct brackets", () => { + const matches = buildDemoMatches(); + const table = buildDeviationTable(matches); + const N = 200; // covers chalk + all single + into the double level + const seen = new Set(); + for (let i = 0; i < N; i++) { + const key = perturbedBracket(table, i).join("|"); + expect(seen.has(key)).toBe(false); + seen.add(key); + } + }); + + it("returns the same deviation set across repeat unranking calls", () => { + const matches = buildDemoMatches(); + const table = buildDeviationTable(matches); + for (const idx of [0, 1, 42, 999, 4321]) { + const a = deviationSlotsForBotIndex(idx, table.slots.length); + const b = deviationSlotsForBotIndex(idx, table.slots.length); + expect([...a]).toEqual([...b]); + } + }); + + it("double-deviation level kicks in at rank S+1", () => { + const matches = buildDemoMatches(); + const table = buildDeviationTable(matches); + const S = singleDeviationCount(table); + const firstDouble = deviationSlotsForBotIndex(S + 1, table.slots.length); + expect(firstDouble.length).toBe(2); + const lastSingle = deviationSlotsForBotIndex(S, table.slots.length); + expect(lastSingle.length).toBe(1); + }); +}); diff --git a/apps/web/__tests__/leaderboard-tabs.test.tsx b/apps/web/__tests__/leaderboard-tabs.test.tsx new file mode 100644 index 00000000..b5e9d9d8 --- /dev/null +++ b/apps/web/__tests__/leaderboard-tabs.test.tsx @@ -0,0 +1,99 @@ +/** + * Vitest, /leaderboard single-row tab strip. + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §5 + * Five tabs in one row (Humans / Bots / Global / Country / My Pools); + * Humans is the default landing; clicking a tab switches + * `aria-selected`. Roving-tabindex pattern means only the active tab + * has tabIndex=0. End jumps to the last tab. My Pools renders three + * mock pools with View-pool links to /s/; falls back to the + * empty state when no pools are present. + */ + +import { describe, it, expect } from "vitest"; +import { fireEvent, render } from "@testing-library/react"; + +import { LeaderboardTabs } from "@/app/leaderboard/LeaderboardTabs"; + +function tabByName(container: HTMLElement, label: RegExp): HTMLButtonElement { + const tabs = container.querySelectorAll("[role='tab']"); + for (const t of Array.from(tabs)) { + if (label.test(t.textContent ?? "")) return t; + } + throw new Error(`tab not found: ${label}`); +} + +describe("", () => { + it("renders five tabs with Humans active by default", () => { + const { container } = render(); + const expected: ReadonlyArray = [ + /humans/i, + /bots/i, + /global/i, + /country/i, + /my pools/i, + ]; + for (const re of expected) { + // throws if missing + tabByName(container, re); + } + expect(tabByName(container, /humans/i).getAttribute("aria-selected")).toBe("true"); + expect(tabByName(container, /bots/i).getAttribute("aria-selected")).toBe("false"); + }); + + it("honours initialTab", () => { + const { container } = render(); + expect(tabByName(container, /humans/i).getAttribute("aria-selected")).toBe( + "false", + ); + expect(tabByName(container, /bots/i).getAttribute("aria-selected")).toBe( + "true", + ); + }); + + it("switches active tab on click", () => { + const { container } = render(); + fireEvent.click(tabByName(container, /global/i)); + expect(tabByName(container, /global/i).getAttribute("aria-selected")).toBe( + "true", + ); + expect(tabByName(container, /humans/i).getAttribute("aria-selected")).toBe( + "false", + ); + }); + + it("renders My Pools with at least one View pool link to /s/", () => { + const { container } = render(); + fireEvent.click(tabByName(container, /my pools/i)); + const link = container.querySelector("a[href^='/s/']"); + expect(link).toBeTruthy(); + expect(link?.textContent ?? "").toMatch(/view pool/i); + }); + + it("ArrowRight moves selection to the next tab (keyboard nav)", () => { + const { container } = render(); + const humans = tabByName(container, /humans/i); + fireEvent.keyDown(humans, { key: "ArrowRight" }); + expect(tabByName(container, /bots/i).getAttribute("aria-selected")).toBe( + "true", + ); + }); + + it("End jumps to My Pools (the last tab)", () => { + const { container } = render(); + const humans = tabByName(container, /humans/i); + fireEvent.keyDown(humans, { key: "End" }); + expect(tabByName(container, /my pools/i).getAttribute("aria-selected")).toBe( + "true", + ); + }); + + it("applies a roving-tabindex (only active tab has tabIndex=0)", () => { + const { container } = render(); + expect(tabByName(container, /humans/i).tabIndex).toBe(0); + expect(tabByName(container, /bots/i).tabIndex).toBe(-1); + expect(tabByName(container, /global/i).tabIndex).toBe(-1); + expect(tabByName(container, /country/i).tabIndex).toBe(-1); + expect(tabByName(container, /my pools/i).tabIndex).toBe(-1); + }); +}); diff --git a/apps/web/__tests__/terms-bot-clause.test.tsx b/apps/web/__tests__/terms-bot-clause.test.tsx new file mode 100644 index 00000000..625dd41c --- /dev/null +++ b/apps/web/__tests__/terms-bot-clause.test.tsx @@ -0,0 +1,47 @@ +/** + * Vitest, /terms/house-prize includes the Bot Arena clause. + * + * Spec: docs/superpowers/specs/2026-06-07-bot-arena-design.md §11 + * The clause sits between section 4 (Eligibility) and section 5 (The + * Bracket) under id="bots" and asserts the cash-prize ineligibility + + * the non-cash recognition package for a bot perfect bracket. + */ + +import { describe, it, expect, vi } from "vitest"; +import { render } from "@testing-library/react"; + +vi.mock("@/components/shell", () => ({ + AppShell: ({ children }: { children: React.ReactNode }) => <>{children}, +})); + +import HousePrizeTermsPage from "@/app/terms/house-prize/page"; + +describe("/terms/house-prize", () => { + it("includes a bots section anchored at #bots", () => { + const { container } = render(); + expect(container.querySelector("#bots")).toBeTruthy(); + }); + + it("states bots are ineligible for the cash prize", () => { + const { container } = render(); + expect(container.textContent).toMatch(/ineligible for the cash/i); + }); + + it("references the 50-point Humanness Score floor", () => { + const { container } = render(); + expect(container.textContent).toMatch(/50 or higher/); + }); + + it("describes the bot perfect-bracket non-cash recognition", () => { + const { container } = render(); + expect(container.textContent).toMatch(/badge/i); + expect(container.textContent).toMatch(/research note/i); + expect(container.textContent).toMatch(/trophy/i); + }); + + it("links to the Bot SDK at /bots/sdk", () => { + const { container } = render(); + const link = container.querySelector("a[href='/bots/sdk']"); + expect(link).toBeTruthy(); + }); +}); diff --git a/apps/web/app/api/v1/bots/keys/route.ts b/apps/web/app/api/v1/bots/keys/route.ts new file mode 100644 index 00000000..12895b65 --- /dev/null +++ b/apps/web/app/api/v1/bots/keys/route.ts @@ -0,0 +1,148 @@ +/** + * POST /api/v1/bots/keys, self-service Bot API key issuance proxy. + * + * Resolves the inbound session, looks up the verified email associated + * with the user, and proxies the request to the game-service + * /v1/bots/keys/issue endpoint. The plaintext key is in the upstream + * response and is forwarded once to the browser; the server stores + * only the SHA-256 hash. + * + * Refs: docs/superpowers/specs/2026-06-07-bot-arena-design.md §6.3 + * Refs: docs/superpowers/plans/2026-06-07-bot-arena-phase-1.md Task 17 + */ + +import type { NextRequest } from "next/server"; + +import { getSessionFromRequest } from "@/lib/auth/session"; +import { loadUserContact } from "@/lib/auth/contact-lookup"; + +export const runtime = "nodejs"; +export const dynamic = "force-dynamic"; + +const MAX_LABEL_LEN = 64; +const LABEL_RE = /^[A-Za-z0-9 _-]+$/; + +function jsonResponse( + body: Record, + status: number, +): Response { + return new Response(JSON.stringify(body), { + status, + headers: { + "Content-Type": "application/json", + "Cache-Control": "private, no-store", + }, + }); +} + +export async function POST(req: NextRequest): Promise { + const session = await getSessionFromRequest(req); + if (!session) { + return jsonResponse({ error: "unauthorised" }, 401); + } + + const contact = loadUserContact(session.userId); + const email = contact?.email; + if (!email) { + return jsonResponse( + { + error: + "missing_verified_email; add a verified email to your profile before issuing API keys", + }, + 400, + ); + } + + let raw: unknown; + try { + raw = await req.json(); + } catch { + return jsonResponse({ error: "invalid_json" }, 400); + } + const body = (raw && typeof raw === "object" ? raw : {}) as Record< + string, + unknown + >; + const labelInput = typeof body.label === "string" ? body.label.trim() : ""; + if (!labelInput) { + return jsonResponse({ error: "label_required" }, 400); + } + if (labelInput.length > MAX_LABEL_LEN) { + return jsonResponse({ error: "label_too_long" }, 400); + } + if (!LABEL_RE.test(labelInput)) { + return jsonResponse( + { error: "label_invalid_chars; use letters, digits, space, _ or -" }, + 400, + ); + } + + const upstream = process.env.GAME_SERVICE_URL; + if (!upstream) { + return jsonResponse( + { + error: + "service_unavailable; GAME_SERVICE_URL not configured in this environment", + }, + 503, + ); + } + + // Shared-secret service-to-service auth. The upstream + // /v1/bots/keys/issue endpoint validates this header against the same + // env var on the game-service side. Falls back to the legacy + // X-Tournamental-Service header for backwards compatibility with + // older game-service builds that haven't pulled the shared-secret + // change yet. + const sharedSecret = process.env.GAME_BOT_KEYS_SHARED_SECRET ?? ""; + + let upstreamRes: Response; + try { + upstreamRes = await fetch(`${upstream}/v1/bots/keys/issue`, { + method: "POST", + headers: { + "Content-Type": "application/json", + "X-Tournamental-Service": "web", + ...(sharedSecret + ? { "x-bot-keys-shared-secret": sharedSecret } + : {}), + }, + body: JSON.stringify({ + owner_email: email, + owner_user_id: session.userId, + label: labelInput, + }), + }); + } catch (err) { + return jsonResponse( + { + error: "upstream_unreachable", + detail: err instanceof Error ? err.message : String(err), + }, + 502, + ); + } + + let upstreamBody: unknown; + try { + upstreamBody = await upstreamRes.json(); + } catch { + return jsonResponse( + { error: "upstream_invalid_json", status: upstreamRes.status }, + 502, + ); + } + + const payload = + upstreamBody && typeof upstreamBody === "object" + ? (upstreamBody as Record) + : { error: "upstream_unexpected_shape" }; + + return new Response(JSON.stringify(payload), { + status: upstreamRes.status, + headers: { + "Content-Type": "application/json", + "Cache-Control": "private, no-store", + }, + }); +} diff --git a/apps/web/app/api/v1/odds/match/[match_id]/route.ts b/apps/web/app/api/v1/odds/match/[match_id]/route.ts new file mode 100644 index 00000000..5c9af93a --- /dev/null +++ b/apps/web/app/api/v1/odds/match/[match_id]/route.ts @@ -0,0 +1,77 @@ +/** + * GET /api/v1/odds/match/:match_id , thin proxy to the game-service + * /v1/odds/match/:match_id endpoint. Returns latest Polymarket-derived + * home/draw/away implied probabilities for the requested fixture. + * + * Accepts both the raw integer string ("1".."72") and the canonical + * `wc2026-mNNN` form , the upstream normalises both. + * + * Edge-cached at the Next layer (public, s-maxage=60, SWR=300). + * + * Spec: 2026-06-08 Polymarket odds endpoint brief. + */ +export const runtime = "nodejs"; +export const dynamic = "force-dynamic"; + +function gameUrl(): string { + return ( + process.env.GAME_SERVICE_URL ?? + process.env.GAME_SERVICE_INTERNAL_URL ?? + process.env.GAME_BASE_URL ?? + "http://127.0.0.1:3361" + ); +} + +const FALLBACK_CACHE = "public, s-maxage=60, stale-while-revalidate=300"; + +interface RouteContext { + params: { match_id?: string } | Promise<{ match_id?: string }>; +} + +export async function GET( + _req: Request, + ctx: RouteContext, +): Promise { + const params = await Promise.resolve(ctx.params); + const matchId = encodeURIComponent((params?.match_id ?? "").trim()); + if (!matchId) { + return new Response( + JSON.stringify({ error: "invalid_match_id" }), + { + status: 400, + headers: { + "content-type": "application/json", + "cache-control": "no-store", + }, + }, + ); + } + let upstream: Response; + try { + upstream = await fetch(`${gameUrl()}/v1/odds/match/${matchId}`, { + method: "GET", + headers: { Accept: "application/json" }, + }); + } catch { + return new Response( + JSON.stringify({ error: "no_market" }), + { + status: 404, + headers: { + "content-type": "application/json", + "cache-control": FALLBACK_CACHE, + }, + }, + ); + } + const body = await upstream.text(); + return new Response(body, { + status: upstream.status, + headers: { + "content-type": + upstream.headers.get("content-type") ?? "application/json", + "cache-control": + upstream.headers.get("cache-control") ?? FALLBACK_CACHE, + }, + }); +} diff --git a/apps/web/app/api/v1/odds/snapshot/route.ts b/apps/web/app/api/v1/odds/snapshot/route.ts new file mode 100644 index 00000000..8ee91bf1 --- /dev/null +++ b/apps/web/app/api/v1/odds/snapshot/route.ts @@ -0,0 +1,60 @@ +/** + * GET /api/v1/odds/snapshot , thin proxy to the game-service + * /v1/odds/snapshot endpoint. The browser-swarm /run page hits this once + * at load to pull both per-match moneyline odds and the tournament-winner + * market in a single round trip. + * + * Edge-cached at the Next layer with the same headers the upstream + * sets (public, s-maxage=60, stale-while-revalidate=300). + * + * Spec: 2026-06-08 Polymarket odds endpoint brief. + */ +export const runtime = "nodejs"; +export const dynamic = "force-dynamic"; + +function gameUrl(): string { + return ( + process.env.GAME_SERVICE_URL ?? + process.env.GAME_SERVICE_INTERNAL_URL ?? + process.env.GAME_BASE_URL ?? + "http://127.0.0.1:3361" + ); +} + +const FALLBACK_CACHE = "public, s-maxage=60, stale-while-revalidate=300"; + +export async function GET(): Promise { + let upstream: Response; + try { + upstream = await fetch(`${gameUrl()}/v1/odds/snapshot`, { + method: "GET", + headers: { Accept: "application/json" }, + }); + } catch { + return new Response( + JSON.stringify({ + matches: {}, + tournament_winner: [], + source: "polymarket", + generated_at: Date.now(), + }), + { + status: 200, + headers: { + "content-type": "application/json", + "cache-control": FALLBACK_CACHE, + }, + }, + ); + } + const body = await upstream.text(); + return new Response(body, { + status: upstream.status, + headers: { + "content-type": + upstream.headers.get("content-type") ?? "application/json", + "cache-control": + upstream.headers.get("cache-control") ?? FALLBACK_CACHE, + }, + }); +} diff --git a/apps/web/app/api/v1/odds/winner-market/route.ts b/apps/web/app/api/v1/odds/winner-market/route.ts new file mode 100644 index 00000000..63f0f46e --- /dev/null +++ b/apps/web/app/api/v1/odds/winner-market/route.ts @@ -0,0 +1,53 @@ +/** + * GET /api/v1/odds/winner-market , thin proxy to the game-service + * /v1/odds/winner-market endpoint. Returns per-team implied probability + * for the FIFA WC26 tournament-winner Polymarket market. + * + * Edge-cached at the Next layer (public, s-maxage=60, SWR=300). + * + * Spec: 2026-06-08 Polymarket odds endpoint brief. + */ +export const runtime = "nodejs"; +export const dynamic = "force-dynamic"; + +function gameUrl(): string { + return ( + process.env.GAME_SERVICE_URL ?? + process.env.GAME_SERVICE_INTERNAL_URL ?? + process.env.GAME_BASE_URL ?? + "http://127.0.0.1:3361" + ); +} + +const FALLBACK_CACHE = "public, s-maxage=60, stale-while-revalidate=300"; + +export async function GET(): Promise { + let upstream: Response; + try { + upstream = await fetch(`${gameUrl()}/v1/odds/winner-market`, { + method: "GET", + headers: { Accept: "application/json" }, + }); + } catch { + return new Response( + JSON.stringify({ teams: [], source: "polymarket" }), + { + status: 200, + headers: { + "content-type": "application/json", + "cache-control": FALLBACK_CACHE, + }, + }, + ); + } + const body = await upstream.text(); + return new Response(body, { + status: upstream.status, + headers: { + "content-type": + upstream.headers.get("content-type") ?? "application/json", + "cache-control": + upstream.headers.get("cache-control") ?? FALLBACK_CACHE, + }, + }); +} diff --git a/apps/web/app/api/v1/perfect-track/route.ts b/apps/web/app/api/v1/perfect-track/route.ts new file mode 100644 index 00000000..2417ccdc --- /dev/null +++ b/apps/web/app/api/v1/perfect-track/route.ts @@ -0,0 +1,56 @@ +/** + * GET /api/v1/perfect-track, thin proxy to the game-service + * /v1/perfect-track aggregate endpoint used by the leaderboard badge. + * + * Edge-cached at the Next layer with the same headers the upstream + * sets so the badge poll never pummels the origin. + * + * Spec: A13 task brief. + */ +export const runtime = "nodejs"; +export const dynamic = "force-dynamic"; + +function gameUrl(): string { + return ( + process.env.GAME_SERVICE_URL ?? + process.env.GAME_SERVICE_INTERNAL_URL ?? + "http://localhost:3360" + ); +} + +export async function GET(): Promise { + let upstream: Response; + try { + upstream = await fetch(`${gameUrl()}/v1/perfect-track`, { + method: "GET", + headers: { Accept: "application/json" }, + }); + } catch { + return new Response( + JSON.stringify({ + highest_match: null, + total_alive: 0, + operator_count: 0, + rows: [], + }), + { + status: 200, + headers: { + "content-type": "application/json", + "cache-control": "public, s-maxage=30, stale-while-revalidate=120", + }, + }, + ); + } + const body = await upstream.text(); + return new Response(body, { + status: upstream.status, + headers: { + "content-type": + upstream.headers.get("content-type") ?? "application/json", + "cache-control": + upstream.headers.get("cache-control") ?? + "public, s-maxage=30, stale-while-revalidate=120", + }, + }); +} diff --git a/apps/web/app/api/v1/swarms/[operator_id]/route.ts b/apps/web/app/api/v1/swarms/[operator_id]/route.ts new file mode 100644 index 00000000..30564ca3 --- /dev/null +++ b/apps/web/app/api/v1/swarms/[operator_id]/route.ts @@ -0,0 +1,80 @@ +/** + * GET /api/v1/swarms/[operator_id], thin proxy to the game-service + * /v1/swarms/ aggregate endpoint. + * + * Edge-cached at the Next layer with the same headers the upstream + * sets so Cloudflare's edge serves repeat hits without touching the + * Node origin. ETag passthrough preserves the 304 fast-path. + * + * Auth-free read because the upstream endpoint is fully public. + * + * Spec: A13 task brief. + */ +import type { NextRequest } from "next/server"; + +export const runtime = "nodejs"; +export const dynamic = "force-dynamic"; + +const HEX64 = /^[0-9a-f]{64}$/; + +function gameUrl(): string { + return ( + process.env.GAME_SERVICE_URL ?? + process.env.GAME_SERVICE_INTERNAL_URL ?? + "http://localhost:3360" + ); +} + +export async function GET( + req: NextRequest, + ctx: { params: { operator_id: string } }, +): Promise { + const operatorId = (ctx.params.operator_id ?? "").toLowerCase(); + if (!HEX64.test(operatorId)) { + return new Response(JSON.stringify({ error: "invalid_operator_id" }), { + status: 400, + headers: { "content-type": "application/json" }, + }); + } + const ifNoneMatch = req.headers.get("if-none-match"); + let upstream: Response; + try { + upstream = await fetch(`${gameUrl()}/v1/swarms/${operatorId}`, { + method: "GET", + headers: { + Accept: "application/json", + ...(ifNoneMatch ? { "if-none-match": ifNoneMatch } : {}), + }, + }); + } catch { + return new Response(JSON.stringify({ error: "upstream_unreachable" }), { + status: 502, + headers: { "content-type": "application/json" }, + }); + } + if (upstream.status === 304) { + return new Response(null, { + status: 304, + headers: { + "cache-control": + upstream.headers.get("cache-control") ?? + "public, s-maxage=60, stale-while-revalidate=300", + etag: upstream.headers.get("etag") ?? "", + }, + }); + } + const body = await upstream.text(); + return new Response(body, { + status: upstream.status, + headers: { + "content-type": + upstream.headers.get("content-type") ?? "application/json", + "cache-control": + upstream.headers.get("cache-control") ?? + "public, s-maxage=60, stale-while-revalidate=300", + ...(upstream.headers.get("etag") + ? { etag: upstream.headers.get("etag")! } + : {}), + }, + }); +} diff --git a/apps/web/app/bot-arena/ArenaStats.tsx b/apps/web/app/bot-arena/ArenaStats.tsx new file mode 100644 index 00000000..a65710b5 --- /dev/null +++ b/apps/web/app/bot-arena/ArenaStats.tsx @@ -0,0 +1,177 @@ +"use client"; + +/** + * Stats chip strip for /bot-arena. + * + * Three numbers, rendered as gold-bordered pill chips above the body: + * + * 1. Bots in my swarm + * Sum of bots generated across every run this device has stored + * in IndexedDB. Counted via the same persistence layer the /run + * page uses (`loadSwarmState()`); zero when the user hasn't + * spawned anything yet. + * + * 2. Still perfect + * Bots that have hit every settled match correctly so far. Read + * from device-local data because the regenerate-on-demand + * contract (docs/30-browser-swarm-architecture.md) keeps per-bot + * picks out of server storage. Counted by replaying each stored + * bot's predictions against the device's `settled_matches` + * cache. Pre-kickoff this equals the swarm total. + * + * 3. Bots in the arena + * Server-aggregate across every device, fetched from + * `/v1/swarm/totals` which caches a SQLite SUM for 60s. Updates + * live across browser windows and accounts within that window; + * the chip polls every 45s so a viewer sees the count tick up as + * other devices commit. + * + * Render rule: if the device has no local bots AND the server total + * is zero, the strip stays hidden (no point teasing empty numbers). + * Tim 2026-06-08. + */ + +import { useEffect, useState } from "react"; + +import { defaultPersistence } from "@/components/browser-swarm/persistence"; + +interface TotalsBody { + readonly total_bots: number; + readonly total_swarms: number; + readonly total_devices: number; + readonly cached_at_utc: string; +} + +interface LocalState { + readonly my_total: number; + /** Best-effort: equals my_total pre-kickoff. After kickoff we'd + * consult settled-match results to drop misses; until those land + * this number tracks my_total verbatim. */ + readonly still_perfect: number; +} + +const POLL_MS = 45_000; + +export function ArenaStats({ + variant, +}: { + /** "hero" renders the strip inside the hero scrim with a more + * compact, transparent treatment that sits well on a photo bg. + * Default is the standalone strip used elsewhere on the page. */ + variant?: "hero"; +} = {}) { + const [local, setLocal] = useState(null); + const [totals, setTotals] = useState(null); + + // Load device-local count once on mount. + useEffect(() => { + let cancelled = false; + defaultPersistence() + .loadSwarmState() + .then((load) => { + if (cancelled) return; + const myTotal = load.state.total_bots_generated; + // Pre-kickoff: every bot still has a perfect record (no match + // results have landed yet). After kickoff this calls into the + // settled-match comparator on the browser-swarm side once + // that ships. Tim 2026-06-08. + setLocal({ my_total: myTotal, still_perfect: myTotal }); + }) + .catch(() => setLocal({ my_total: 0, still_perfect: 0 })); + return () => { + cancelled = true; + }; + }, []); + + // Poll server-aggregate every 45s. The endpoint itself caches for + // 60s; this cadence keeps the chip live without ever hitting the + // cold path. + useEffect(() => { + let cancelled = false; + const fetchTotals = async () => { + try { + const res = await fetch("/v1/swarm/totals", { cache: "no-store" }); + if (!res.ok) return; + const body = (await res.json()) as TotalsBody; + if (!cancelled) setTotals(body); + } catch { + /* silent: chips just stay on last good value */ + } + }; + void fetchTotals(); + const id = window.setInterval(fetchTotals, POLL_MS); + return () => { + cancelled = true; + window.clearInterval(id); + }; + }, []); + + // Hide the strip entirely until we know something interesting. + const myTotal = local?.my_total ?? 0; + const arenaTotal = totals?.total_bots ?? 0; + if (myTotal === 0 && arenaTotal === 0) return null; + + const sectionClass = + "vt-arena-stats" + (variant === "hero" ? " vt-arena-stats--hero" : ""); + return ( +
+ {myTotal > 0 && ( + + )} + {myTotal > 0 && ( + + )} + {arenaTotal > 0 && ( + + )} +
+ ); +} + +function ArenaStat({ + label, + value, + sub, + tone, +}: { + label: string; + value: number; + sub: string; + tone?: "gold"; +}) { + return ( +
+ {label} + + {formatCompact(value)} + + {sub} +
+ ); +} + +/** Compact integer formatter: 1234 -> "1,234", 12345 -> "12.3K", + * 1_234_567 -> "1.23M", 1_500_000_000 -> "1.50B". Keeps the chip + * predictable in width as the global aggregate scales. */ +function formatCompact(n: number): string { + if (!Number.isFinite(n)) return "0"; + const abs = Math.abs(n); + if (abs < 10_000) return n.toLocaleString(); + if (abs < 1_000_000) return `${(n / 1_000).toFixed(1)}K`; + if (abs < 1_000_000_000) return `${(n / 1_000_000).toFixed(2)}M`; + if (abs < 1_000_000_000_000) return `${(n / 1_000_000_000).toFixed(2)}B`; + return `${(n / 1_000_000_000_000).toFixed(2)}T`; +} diff --git a/apps/web/app/bot-arena/bot-arena.css b/apps/web/app/bot-arena/bot-arena.css new file mode 100644 index 00000000..48131ac2 --- /dev/null +++ b/apps/web/app/bot-arena/bot-arena.css @@ -0,0 +1,542 @@ +/** + * /bot-arena page styles. Editorial-sport tone matching /the-bet. + * Charcoal canvas, Fraunces display serif, gold accents. + */ + +.vt-arena { + min-height: 100vh; + background: #0e0e12; + color: #e7ecf7; + font-family: system-ui, -apple-system, sans-serif; + padding: clamp(20px, 4vw, 48px) clamp(14px, 3vw, 28px) 96px; + line-height: 1.65; +} + +.vt-arena-article { + max-width: 820px; + margin: 0 auto; +} + +/* ---------- header ---------- */ + +.vt-arena-header { + padding-bottom: 36px; + border-bottom: 1px solid rgba(220, 169, 75, 0.22); + margin-bottom: 40px; +} + +.vt-arena-dateline { + color: #dca94b; + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + font-size: 12px; + letter-spacing: 0.18em; + text-transform: uppercase; + margin: 0 0 14px; +} + +.vt-arena-title { + font-family: Fraunces, Georgia, serif; + font-weight: 500; + /* Tim 2026-06-08: cap a touch lower than 56 so the snappier two-beat + * headline ("Spawn a million bots..." / "Will yours top...") lays + * out as two clean lines on desktop instead of breaking awkwardly. */ + font-size: clamp(30px, 5vw, 50px); + line-height: 1.08; + letter-spacing: -0.02em; + color: #ffffff; + margin: 0; + /* text-wrap: balance distributes leftover words across lines instead + * of orphaning a single word on the last line; widely supported in + * modern browsers, falls back to normal wrapping where unavailable. */ + text-wrap: balance; + max-width: 22ch; +} +.vt-arena-title em { + font-style: italic; + color: #f6c64f; + text-shadow: 0 2px 12px rgba(0, 0, 0, 0.45); + display: inline-block; + margin-top: 6px; + font-size: 0.78em; +} + +.vt-arena-lede { + font-family: Fraunces, Georgia, serif; + font-style: italic; + font-size: clamp(17px, 2vw, 19px); + line-height: 1.55; + color: #c7d0e6; + margin: 24px 0 0; + max-width: 64ch; +} + +.vt-arena-cta-row { + display: flex; + flex-wrap: wrap; + gap: 14px; + margin: 28px 0 16px; +} + +.vt-arena-cta-primary { + display: inline-flex; + align-items: center; + padding: 14px 22px; + border-radius: 999px; + background: linear-gradient(180deg, #f6c64f 0%, #dca94b 100%); + color: #15151a; + font-weight: 600; + font-size: 16px; + text-decoration: none; + transition: transform 120ms ease, box-shadow 120ms ease; + box-shadow: 0 8px 30px rgba(220, 169, 75, 0.25); +} +.vt-arena-cta-primary:hover { + transform: translateY(-1px); + box-shadow: 0 10px 36px rgba(220, 169, 75, 0.35); + text-decoration: none; +} + +.vt-arena-cta-secondary { + display: inline-flex; + align-items: center; + padding: 14px 22px; + border-radius: 999px; + border: 1px solid rgba(220, 169, 75, 0.55); + background: transparent; + color: #e7ecf7; + font-weight: 500; + font-size: 15px; + text-decoration: none; + transition: border-color 120ms ease, background 120ms ease; +} +.vt-arena-cta-secondary:hover { + border-color: #dca94b; + background: rgba(220, 169, 75, 0.08); + text-decoration: none; +} + +.vt-arena-footnote { + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + font-size: 11px; + letter-spacing: 0.10em; + text-transform: uppercase; + color: #98a0b7; + margin: 0; +} + +/* ---------- hero variant (Tim 2026-06-08) ---------- + * + * Mirrors /the-bet's hero treatment: full-bleed photo, dual-gradient + * scrim, content sits bottom-left of the image. The article column + * stays 820px otherwise; the hero alone breaks out via negative side + * margins on mobile and rounds to a card on tablet+. Image lives at + * public/hero/bot-arena-hero.{webp,jpg} (1920x1047 each, lossy from + * the 2816x1536 original). */ +.vt-arena-header--hero { + position: relative; + isolation: isolate; + overflow: hidden; + border-radius: 18px; + margin: -24px -20px 28px; + padding: clamp(48px, 8vw, 96px) clamp(24px, 4vw, 56px) clamp(36px, 5vw, 64px); + border-bottom: none; + background: #15151a; + min-height: clamp(360px, 50vw, 540px); + display: flex; + align-items: flex-end; +} +.vt-arena-header-bg { + position: absolute; + inset: 0; + z-index: 0; + background-image: image-set( + url("/hero/bot-arena-hero.webp") type("image/webp"), + url("/hero/bot-arena-hero.jpg") type("image/jpeg") + ); + background-size: cover; + background-position: center; + background-color: #1e1e26; +} +.vt-arena-header-scrim { + position: absolute; + inset: 0; + z-index: 1; + /* Vertical gradient anchors the headline at the bottom against the + * stadium roof; horizontal gradient keeps the right edge of the + * photo readable (it's a packed crowd, busy already). */ + background: + linear-gradient(180deg, rgba(15, 15, 22, 0.25) 0%, rgba(15, 15, 22, 0.55) 55%, rgba(15, 15, 22, 0.92) 100%), + linear-gradient(90deg, rgba(15, 15, 22, 0.55) 0%, rgba(15, 15, 22, 0.15) 60%, rgba(15, 15, 22, 0.0) 100%); +} +.vt-arena-header-content { + position: relative; + z-index: 2; + max-width: 920px; +} +@media (min-width: 720px) { + .vt-arena-header--hero { + margin-left: 0; + margin-right: 0; + border-radius: 24px; + } +} + +/* ---------- live stats chips (Tim 2026-06-08) ---------- + * + * Three-up row beneath the hero. Hidden by the component until the + * device has bots or the arena total is non-zero. Wraps to a column + * on narrow viewports. */ +.vt-arena-stats { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); + gap: 12px; + margin: 0 0 32px; +} +/* Tim 2026-06-08: hero variant sits inside the photo scrim above the + * CTAs. Compact, transparent panels so the underlying photo still + * carries the banner. */ +.vt-arena-stats--hero { + grid-template-columns: repeat(3, minmax(0, 1fr)); + gap: 10px; + margin: 22px 0 6px; + max-width: 640px; +} +.vt-arena-stats--hero .vt-arena-stat { + padding: 10px 14px 10px; + background: rgba(8, 10, 18, 0.55); + backdrop-filter: blur(8px); + -webkit-backdrop-filter: blur(8px); + border-color: rgba(220, 169, 75, 0.36); +} +.vt-arena-stats--hero .vt-arena-stat-value { + font-size: clamp(22px, 3vw, 28px); +} +.vt-arena-stats--hero .vt-arena-stat-label, +.vt-arena-stats--hero .vt-arena-stat-sub { + font-size: 10px; +} +@media (max-width: 560px) { + .vt-arena-stats--hero { + grid-template-columns: 1fr 1fr; + } +} +.vt-arena-stat { + border-radius: 12px; + padding: 14px 16px 12px; + background: rgba(255, 255, 255, 0.03); + border: 1px solid rgba(220, 169, 75, 0.28); + display: flex; + flex-direction: column; + gap: 2px; +} +.vt-arena-stat[data-tone="gold"] { + background: linear-gradient(180deg, rgba(246, 198, 79, 0.18) 0%, rgba(220, 169, 75, 0.06) 100%); + border-color: rgba(246, 198, 79, 0.55); +} +.vt-arena-stat-label { + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + font-size: 10.5px; + letter-spacing: 0.16em; + text-transform: uppercase; + color: #c7b283; +} +.vt-arena-stat-value { + font-family: Fraunces, Georgia, serif; + font-weight: 500; + font-variant-numeric: tabular-nums; + font-size: clamp(26px, 4.4vw, 34px); + line-height: 1.05; + color: #ffffff; + letter-spacing: -0.018em; +} +.vt-arena-stat[data-tone="gold"] .vt-arena-stat-value { + color: #f6c64f; + text-shadow: 0 2px 14px rgba(246, 198, 79, 0.35); +} +.vt-arena-stat-sub { + font-size: 12px; + color: #98a0b7; +} + +/* ---------- body ---------- */ + +.vt-arena-body { + font-size: 16px; + line-height: 1.75; +} + +.vt-arena-h2 { + font-family: Fraunces, Georgia, serif; + font-weight: 500; + font-size: clamp(22px, 3vw, 30px); + line-height: 1.2; + letter-spacing: -0.01em; + color: #ffffff; + margin: 48px 0 14px; +} + +.vt-arena-body p { + margin: 0 0 14px; + color: #d8def0; +} + +.vt-arena-body strong { + color: #ffffff; +} + +.vt-arena-body a { + color: #f6c64f; + text-decoration: underline; + text-decoration-thickness: 1px; + text-underline-offset: 3px; +} +.vt-arena-body a:hover { + text-decoration-thickness: 2px; +} + +.vt-arena-body code { + background: rgba(220, 169, 75, 0.08); + border: 1px solid rgba(220, 169, 75, 0.18); + border-radius: 4px; + padding: 1px 6px; + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + font-size: 13px; + color: #f6c64f; +} + +.vt-arena-pullquote { + font-family: Fraunces, Georgia, serif; + font-size: clamp(18px, 2.6vw, 22px); + line-height: 1.4; + color: #ffffff; + padding: 18px 24px; + margin: 18px 0; + border-left: 3px solid #dca94b; + background: rgba(220, 169, 75, 0.06); + border-radius: 4px; +} + +/* ---------- launch-timing banner ---------- */ + +.vt-arena-launch-banner { + margin: 40px 0; + padding: 28px 24px; + background: linear-gradient( + 180deg, + rgba(220, 169, 75, 0.08) 0%, + rgba(220, 169, 75, 0.03) 100% + ); + border: 1px solid rgba(220, 169, 75, 0.32); + border-radius: 14px; +} +.vt-arena-launch-eyebrow { + color: #f6c64f; + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + font-size: 11px; + letter-spacing: 0.18em; + text-transform: uppercase; + margin: 0 0 6px; +} +.vt-arena-launch-title { + font-family: Fraunces, Georgia, serif; + font-weight: 500; + font-size: clamp(22px, 3vw, 28px); + color: #ffffff; + margin: 0 0 18px; + line-height: 1.2; + letter-spacing: -0.005em; +} +.vt-arena-launch-grid { + display: grid; + grid-template-columns: 1fr 1fr; + gap: 16px; +} +@media (max-width: 720px) { + .vt-arena-launch-grid { grid-template-columns: 1fr; } +} +.vt-arena-launch-card { + background: rgba(8, 8, 12, 0.45); + border: 1px solid rgba(255, 255, 255, 0.06); + border-radius: 10px; + padding: 18px; +} +.vt-arena-launch-when { + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + font-size: 11px; + letter-spacing: 0.14em; + text-transform: uppercase; + color: #f6c64f; + margin: 0 0 8px; +} +.vt-arena-launch-when strong { + color: #f6c64f; + font-weight: 600; +} +.vt-arena-launch-card p:not(.vt-arena-launch-when) { + font-size: 15px; + line-height: 1.65; + color: #d8def0; + margin: 0; +} +.vt-arena-launch-footnote { + font-size: 14px; + color: #98a0b7; + margin: 18px 0 0; + font-style: italic; +} + +/* ---------- 4-way grid + slider grid ---------- */ + +.vt-arena-grid { + display: grid; + grid-template-columns: 1fr 1fr; + gap: 18px; + margin: 20px 0 28px; +} +.vt-arena-grid-tight { + grid-template-columns: 1fr 1fr 1fr; + gap: 14px; +} +@media (max-width: 920px) { + .vt-arena-grid-tight { grid-template-columns: 1fr 1fr; } +} +@media (max-width: 720px) { + .vt-arena-grid { grid-template-columns: 1fr; } + .vt-arena-grid-tight { grid-template-columns: 1fr; } +} + +.vt-arena-slider-card { + background: rgba(220, 169, 75, 0.05); + border: 1px solid rgba(220, 169, 75, 0.18); + border-radius: 10px; + padding: 16px; +} +.vt-arena-slider-name { + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + font-size: 11px; + letter-spacing: 0.14em; + text-transform: uppercase; + color: #f6c64f; + margin: 0 0 6px; +} +.vt-arena-slider-card p:not(.vt-arena-slider-name) { + font-size: 14px; + line-height: 1.6; + color: #c7d0e6; + margin: 0; +} + +.vt-arena-list { + margin: 14px 0 18px; + padding-left: 22px; + color: #d8def0; +} +.vt-arena-list li { + margin: 0 0 10px; + line-height: 1.65; +} +.vt-arena-list strong { + color: #ffffff; +} + +.vt-arena-card { + background: linear-gradient(180deg, #15151a 0%, #111116 100%); + border: 1px solid rgba(255, 255, 255, 0.06); + border-radius: 14px; + padding: 22px 22px 18px; + display: flex; + flex-direction: column; +} +.vt-arena-card:hover { + border-color: rgba(220, 169, 75, 0.32); +} + +.vt-arena-card-eyebrow { + color: #dca94b; + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + font-size: 10px; + letter-spacing: 0.16em; + text-transform: uppercase; + margin: 0 0 8px; +} + +.vt-arena-card-title { + font-family: Fraunces, Georgia, serif; + font-weight: 500; + font-size: 22px; + line-height: 1.2; + letter-spacing: -0.005em; + color: #ffffff; + margin: 0 0 10px; +} + +.vt-arena-card p { + flex: 1; + font-size: 15px; + line-height: 1.65; + color: #c7d0e6; + margin: 0 0 14px; +} + +.vt-arena-card-cta { + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + font-size: 12px; + letter-spacing: 0.12em; + text-transform: uppercase; + color: #f6c64f; + text-decoration: none; + align-self: flex-start; +} +.vt-arena-card-cta:hover { + text-decoration: underline; +} + +/* ---------- steps ---------- */ + +.vt-arena-steps { + margin: 18px 0 24px; + padding-left: 22px; + color: #d8def0; +} +.vt-arena-steps li { + margin: 0 0 12px; + line-height: 1.65; +} +.vt-arena-steps strong { + color: #ffffff; +} + +/* ---------- signoff ---------- */ + +.vt-arena-signoff { + font-family: Fraunces, Georgia, serif; + font-style: italic; + font-size: 18px; + color: #c7d0e6; + margin: 36px 0 14px; +} + +.vt-arena-byline { + font-size: 14px; + color: #98a0b7; + margin: 0 0 36px; +} +.vt-arena-byline strong { + color: #e7ecf7; +} +.vt-arena-byline a { + color: #f6c64f; + text-decoration: none; +} +.vt-arena-byline a:hover { + text-decoration: underline; +} + +.vt-arena-cta-final { + display: flex; + flex-wrap: wrap; + gap: 14px; + margin: 28px 0 0; + padding-top: 28px; + border-top: 1px solid rgba(255, 255, 255, 0.08); +} diff --git a/apps/web/app/bot-arena/page.tsx b/apps/web/app/bot-arena/page.tsx new file mode 100644 index 00000000..a1678554 --- /dev/null +++ b/apps/web/app/bot-arena/page.tsx @@ -0,0 +1,512 @@ +/** + * /bot-arena, the marketing landing page for the Tournamental Open Bot Arena. + * + * Tim 2026-06-07: this is the *hook* page. Browser-first framing because + * most users will run a swarm straight in their browser tab without + * installing anything. Developers go to /developers for SDK / Node / + * MCP detail. The page leads with "spawn a million unique brackets in + * your browser" and reassures the operator that every bot in their own + * swarm has a guaranteed-unique bracket spread by probability mass. + */ + +import type { Metadata } from "next"; +import Link from "next/link"; + +import { AppShell } from "@/components/shell"; + +import { ArenaStats } from "./ArenaStats"; + +import "./bot-arena.css"; + +// The marketing copy is static. The stats chip strip () +// is a client island that fetches /v1/swarm/totals + reads IndexedDB +// on mount so it doesn't block SSR. +export const dynamic = "force-static"; + +export const metadata: Metadata = { + title: "Bot Arena · Tournamental", + description: + "Run your own AI bot swarm in your browser to forecast every match of the FIFA World Cup 2026. 104 matches, 9.74 x 10^43 possible brackets. Every pick anchored to Bitcoin via OpenTimestamps. Free, open-source, US$0 anchor cost. Bots cannot win the cash prize; that stays with verified humans.", + robots: { index: true, follow: true }, +}; + +export default function BotArenaPage(): JSX.Element { + return ( + +
+
+ + {/* Hero image header (Tim 2026-06-08). Mirrors the /the-bet + * pattern: full-bleed photo + dual-gradient scrim + content + * sitting bottom-left. The image is a 2816 to 1920 downscaled + * pair (webp + jpg) at public/hero/bot-arena-hero.{webp,jpg}; + * fallback background keeps the page legible if anything fails + * to fetch. */} +
+
+ + + +
+ + {/* Page lede - moved out of the hero banner (Tim 2026-06-08) + * so the photo and headline carry the banner on their own. + * Edit this paragraph + the rest of the body copy at + * apps/web/app/bot-arena/page.tsx. */} +

+ 104 matches. 9.74 × 1043 possible + brackets. Spawn anywhere from a hundred to billions of + unique AI bracket predictions, straight in your browser, + using your own CPU. Every pick is anchored to the Bitcoin + blockchain via OpenTimestamps. The anchor cost is US$0. The + audit is open to anyone. Bots cannot win the cash prize. + Humans cannot stop them. +

+ +

Start in five minutes, no install.

+
    +
  1. + Sign in with a phone, email, or Telegram at{" "} + play.tournamental.com. +
    2. +
  2. + Save your own bracket on the predict page. + You are now in the human leaderboard race. +
    3. +
  3. + Open play.tournamental.com/run{" "} + in a new tab. Slide the bot count to anywhere from 100 to + a million. Tune the sliders. Hit go. +
    4. +
  4. + Watch the swarm. Your browser generates + every bot bracket using its own CPU, no server cost to you. + Each bracket is hashed and committed via the federated + protocol before each match kicks off. +
    5. +
  5. + Compete. Your handle appears on the bot + leaderboard. The humans tab and the bots tab update live + for the next five weeks. +
    6. +
+ +

+ That is the whole setup. Your swarm persists in your + browser's IndexedDB by default, the count survives a + tab close, a browser restart, and a laptop reboot. Sign up + for a free Supabase project at any point to mirror it to a + second device. The merkle commitments to our central + server are immutable on the blockchain regardless. +

+ +

Tune the swarm with sliders.

+

+ Every bot in your swarm is generated to be unique (more on + that below) and intelligent (it reads live odds from + Polymarket and the major sportsbooks). The sliders let you + shape how that intelligence is deployed across the + population. None of these require code. +

+ +
+ +
+

Chalk bias

+

+ How heavily do bots favour the bookmaker's pick? + Slide low and your swarm hunts upsets across the + tournament; slide high and most bots play the chalk. + Default 0.78. +

+
+ +
+

Draw bias

+

+ In group matches, how much extra weight on a draw vs the + bookies' price? Humans famously over-pick draws; + your bots can mimic that or not. Default +6 percentage + points over Polymarket implied. +

+
+ +
+

Upset rate

+

+ The probability each bot deviates from chalk on a given + match. Low values produce a tight chalk swarm; high + values spread brackets toward extreme combinations. We + cap this so the cup-winner distribution still respects + the top 6 nations. +

+
+ +
+

Update cadence

+

+ How often the swarm re-reads live odds and revises picks. + Hourly, every 6 hours, daily, or once. Faster cadence + catches breaking injury news, costs you more browser + compute. +

+
+ +
+

LLM strategy

+

+ Drop in your Anthropic or OpenAI key for Claude or GPT + to make per-bot decisions. Leave blank and the swarm + uses a deterministic chalk-weighted heuristic, no API + cost. Mix-and-match across the swarm if you want. +

+
+ +
+

Bot count

+

+ 100 to a few million in your browser; a billion-plus on + the Node operator path + with your own server. Browser swarms parallelise across + your CPU cores via Web Workers. +

+
+ +
+ +

Every bot in your swarm has a unique bracket.

+

+ This matters. If you spawn a million bots and they all pick + the same favourites, you have one bracket repeated a million + times. That is statistically pointless. Tournamental + guarantees that{" "} + every bot in your own swarm has a unique bracket. + No duplicates within your operator scope. (Across other + operators' swarms, duplicates can happen by chance and + that is fine, that is the point of an open competition.) +

+

+ How it works: each bot in your swarm gets a deterministic + index. The index maps to a unique bracket via a perturbation + algorithm that starts from the pure-chalk bracket (bot index + 0, the most likely outcome of every match) and walks outward + in order of decreasing probability. Bot 1 is the second-most + likely bracket (one match deviated). Bot 2 is the third. + And so on. Your million-bot swarm therefore covers the top + million most-probable brackets in your tuned strategy + space. +

+

+ The practical result: your swarm's brackets + stack the heaviest mass at the chalk end (most + common picks, most bots concentrated there) and + spread thinner toward the outliers at the top. + Most of your bots will agree on Brazil to win Group C. Only + a handful will pick Cape Verde to top Group H. That is + exactly the shape a serious operator wants: rigorous + coverage of the credible bracket space with a long tail of + calculated risks. +

+

+ The bigger your swarm, the further into the outlier + tail you reach. A 100-bot swarm covers only the + very chalkiest brackets. A 10-million-bot swarm covers + increasingly improbable combinations. A billion-bot swarm + on a Node operator deployment starts to seriously cover the + credible region. Nobody will get all 1044 + brackets (the maths in the{" "} + white paper{" "} + shows you need ten trillion times more compute than humanity + has). But the bigger your swarm, the higher your highest- + scoring bot is likely to finish. +

+ +

How many bots do you need?

+

+ Honest answer: more than the planet has compute + for. The 104-match space is 9.74 × 10 + 43 distinct brackets. Live odds + per-match + kickoff lock raise the per-bot perfect-bracket probability + from random to roughly 0.5872 × + 0.6532 ≈ 10-22. To get + a coin-flip's chance of one perfect bot, you need + around 10 sextillion bots, which is ten + trillion times more compute than humanity currently has. +

+

+ What a serious swarm actually does is run its{" "} + best bot up to roughly 88 to 95 of 104 + correct. That comfortably beats the best human bracket + (typically 70 to 80 of 104 in a World Cup pool) and beats + the closing-line accuracy of every major sportsbook on + earth. The honest, open mathematical question for the next + five weeks is not can any AI nail 104-from-104{" "} + (no), it is can a swarm of AIs beat every human pundit + on the planet at predicting elite football (we expect + yes; the leaderboard settles it on chain by 19 July). +

+

+ The full working lives at /run{" "} + (throughput table + perfect-bracket arithmetic) and the{" "} + + perfect-bot-bracket white paper + + . +

+ +

Merkle → OpenTimestamps → Bitcoin.

+

+ Every pick by every player and every bot enters a SHA-256 + Merkle tree before its match kicks off. The Merkle root is + anchored to the Bitcoin blockchain via OpenTimestamps. The + chain costs Tournamental zero dollars per anchor because + OpenTimestamps batches thousands of commitments into a + single Bitcoin transaction. The verification is open to + anyone with a CLI tool and a block explorer. Three steps: +

+
    +
  1. + Pick → Merkle leaf. Every{" "} + (player_id, match_id, outcome) tuple is + hashed into a 32-byte leaf. +
    2. +
  2. + Merkle tree → root. Leaves combine + pairwise up to a single 32-byte root per snapshot. The + entire predictions table compresses to one hash. +
    3. +
  3. + Root → Bitcoin (FREE via OpenTimestamps).{" "} + OpenTimestamps batches the root with other commitments, + anchors the batch in a Bitcoin transaction, and returns + a receipt. Confirmation typically lands within one hour; + six confirmations within a working day. +
    4. +
+

+ If anyone, including the founder, alters a single pick + after that match has kicked off, the recomputed Merkle + root no longer matches the on-chain commitment. The + tampering is provably detectable by a public command-line + tool, in roughly sixty seconds, by anyone with the receipt + and the snapshot. The full walk-through is at{" "} + play.tournamental.com/verify. +

+ +

Three runtimes for three scales.

+ +
+ +
+

Default

+

Browser swarm

+

+ Up to a few million bots in a single Chrome tab on a + modern laptop. Web Workers parallelise across your CPU + cores. Zero install. Free. No coding. Optional Supabase + free tier for persistence across sessions. +

+ + Spawn one now → + +
+ +
+

For developers

+

Node SDK

+

+ npm install @tournamental/bot-sdk. Plug in + Claude, GPT, Gemini, or your own model. Eight worked + examples in the repo. Apache 2.0, public NPM, ESM and + CommonJS. Same federated protocol, same uniqueness + guarantee. +

+ + Read the SDK docs → + +
+ +
+

For serious operators

+

Node operator

+

+ docker compose up. Runs{" "} + @tournamental/bot-node on your own server, + up to billions of bots on appropriately-sized + hardware. Local SQLite, prepared-statement bulk + inserts, optional Anthropic / OpenAI strategy + injection. Only merkle commitments and aggregates flow + to the central server. +

+ + Run a node → + +
+ +
+ +

+ All three runtimes share the same federated protocol, the + same merkle commitment shape, the same blockchain audit + trail, and the same uniqueness guarantee. They differ only + in scale and where the compute lives. You can move between + them. A Claude Desktop user can also run a browser swarm. + A researcher can run a billion-bot Node deployment AND a + hand-curated GPT bot via the SDK side by side. +

+ +

The leaderboard, in real time.

+

+ Tournamental's public leaderboard at{" "} + play.tournamental.com/leaderboard{" "} + has three tabs: +

+
    +
  • + Humans, the prize race. Every account that + isn't marked as a bot. The top human at the end of + the tournament has a small but real chance at the cash + prize (per the{" "} + house terms). +
    • +
  • + Bots, the AI experiment. Every bot from + every operator on the federated network. The top bot at + the end gets a permanent badge, an invitation to publish + a co-authored research note with the team, and a trophy. +
    • +
  • + My Pools, your own private and branded + pools. Pools can be human-only, bot-allowed, or mixed. + The choice belongs to the pool owner. +
    • +
+

+ Both top boards update live throughout the tournament. The + most interesting question is not whether anyone gets a + perfect bracket (the{" "} + maths says nobody will), + it is the comparison. Does the best bot beat the + best human? By how many points? Does the median + human keep up with the median bot? We will know on 19 July. +

+ +

The blockchain audit trail.

+

+ At every match kickoff, every pick from every player and + every bot on the platform is hashed into a merkle tree and + the root is committed to the{" "} + Bitcoin blockchain via OpenTimestamps. The + script is open-source. The chain of commitments is public + at play.tournamental.com/verify. + If anyone, including the founder, alters a single pick + after that pick's match has kicked off, the recomputed + root will not match the on-chain commitment and the + tampering is provably detectable using a public command- + line tool. +

+

+ This matters for bots more than humans. A bot operator + running a swarm of a billion bots cannot quietly delete + the ones that got Argentina vs Saudi Arabia wrong and + pretend their winning bots were always there. The + pre-kickoff merkle commitment is on chain. Any third party + can verify any pick claim end-to-end in under a minute. +

+ +

What the bot wins.

+

+ The cash prize (the founder's NZ$1.5 million Auckland + house, with roughly NZ$700,000 in net equity after the + mortgage clears) stays exclusively for verified humans. + Bots have a Humanness Score of zero by design, and the{" "} + house prize terms{" "} + require a score of at least 50 to claim. Bots are not + eligible for the cash. They never were. +

+

+ But the bot that finishes highest on the bot leaderboard + gets a permanent badge on its profile, an invitation to + publish a co-authored research note with the Tournamental + team, a trophy, and the kind of bragging rights that + actually carry weight in the AI lab and stats department + world. And if any bot, on any operator's swarm, nails + 104 from 104, that result is the first verified, blockchain- + anchored, publicly auditable proof that an AI predicted a + 104-match World Cup bracket perfectly. The front page of + every science magazine reads about the team that built the + bot. +

+ +

+ See you on the leaderboard. +

+

+ Tim Thomas, founder, Tournamental +
+ info@tournamental.com +

+ +
+ + Start a swarm + + + How verification works + + + Read the press release + + + Developer guide + +
+ +
+
+
+ + ); +} diff --git a/apps/web/app/bots/keys/IssueKeyForm.tsx b/apps/web/app/bots/keys/IssueKeyForm.tsx new file mode 100644 index 00000000..6fbff9ed --- /dev/null +++ b/apps/web/app/bots/keys/IssueKeyForm.tsx @@ -0,0 +1,133 @@ +"use client"; + +/** + * /bots/keys, the client-side issuance form. + * + * Posts to /api/v1/bots/keys (which proxies to the game-service + * /v1/bots/keys/issue endpoint with the session-resolved email). + * + * The plaintext key is shown ONCE on the response screen. The server + * only persists the SHA-256 hash, so if the user navigates away + * without copying the key, the only recourse is to issue a new one + * and revoke the old. + */ + +import { useState, type FormEvent } from "react"; + +interface IssueResponse { + readonly api_key?: string; + readonly key_id?: string; + readonly label?: string; + readonly created_at?: string; + readonly error?: string; +} + +export function IssueKeyForm(): JSX.Element { + const [label, setLabel] = useState(""); + const [submitting, setSubmitting] = useState(false); + const [response, setResponse] = useState(null); + const [copied, setCopied] = useState(false); + + const submit = async (e: FormEvent) => { + e.preventDefault(); + if (!label.trim()) return; + setSubmitting(true); + setResponse(null); + setCopied(false); + try { + const res = await fetch("/api/v1/bots/keys", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ label: label.trim() }), + }); + const data = (await res.json()) as IssueResponse; + if (!res.ok) { + setResponse({ error: data.error ?? `Server returned ${res.status}` }); + } else { + setResponse(data); + } + } catch (err) { + setResponse({ + error: err instanceof Error ? err.message : "Network error", + }); + } finally { + setSubmitting(false); + } + }; + + const copyKey = async () => { + if (!response?.api_key) return; + try { + await navigator.clipboard.writeText(response.api_key); + setCopied(true); + } catch { + /* clipboard blocked; user can select + copy manually */ + } + }; + + return ( +
+
+ + setLabel(e.target.value)} + placeholder="my-first-swarm" + autoComplete="off" + className="vt-keys-input" + disabled={submitting} + /> + +
+ + {response?.error && ( +

+ {response.error} +

+ )} + + {response?.api_key && ( +
+

+ Copy this key now. Tournamental stores only + the hash; we can't show it again. +

+
+ {response.api_key} + +
+ {response.label && ( +

+ Labelled {response.label}. Set{" "} + TOURNAMENTAL_API_KEY in your .env{" "} + and you're ready to call the SDK. +

+ )} +
+ )} +
+ ); +} diff --git a/apps/web/app/bots/keys/keys.css b/apps/web/app/bots/keys/keys.css new file mode 100644 index 00000000..f0d6de85 --- /dev/null +++ b/apps/web/app/bots/keys/keys.css @@ -0,0 +1,299 @@ +/* + * /bots/keys, the issuance page styles. + * + * Same editorial canvas as /bots/sdk so the two pages read as one + * micro-site. Form treatment is intentionally restrained: a single + * input, a single button, and a result panel that visually shouts + * "copy this NOW". + */ + +.vt-keys { + min-height: 100vh; + background: #0e0e12; + color: #e7ecf7; + font-family: system-ui, -apple-system, sans-serif; + padding: 48px 20px 96px; + line-height: 1.55; +} + +.vt-keys-article { + max-width: 720px; + margin: 0 auto; +} + +.vt-keys-header { + padding-bottom: 24px; + border-bottom: 1px solid rgba(255, 255, 255, 0.08); + margin-bottom: 32px; +} + +.vt-keys-eyebrow { + font-size: 12px; + font-weight: 700; + letter-spacing: 0.18em; + text-transform: uppercase; + color: #f1c447; + margin: 0 0 14px; +} + +.vt-keys-title { + font-family: Georgia, "Times New Roman", serif; + font-size: clamp(32px, 4.5vw, 48px); + line-height: 1.1; + margin: 0 0 16px; + color: #fff; + letter-spacing: -0.01em; +} + +.vt-keys-lede { + font-size: 17px; + color: #b8c0d4; + margin: 0; +} + +.vt-keys-lede code { + font-family: "SF Mono", "Menlo", "Consolas", monospace; + font-size: 0.92em; + background: rgba(241, 196, 71, 0.10); + color: #f1c447; + padding: 1px 6px; + border-radius: 4px; +} + +.vt-keys-signedin { + background: rgba(241, 196, 71, 0.08); + color: #f1c447; + padding: 12px 16px; + border-radius: 10px; + margin: 0 0 24px; + font-size: 14px; +} + +.vt-keys-signedin strong { + color: #fff; +} + +.vt-keys-form-card { + background: #15151a; + border: 1px solid rgba(255, 255, 255, 0.06); + border-radius: 14px; + padding: 28px 28px 24px; +} + +.vt-keys-form { + display: flex; + flex-direction: column; + gap: 16px; +} + +.vt-keys-label { + display: flex; + flex-direction: column; + gap: 4px; + font-size: 14px; + font-weight: 700; + color: #fff; +} + +.vt-keys-hint { + font-weight: 400; + color: #b8c0d4; + font-size: 13px; +} + +.vt-keys-hint em { + color: #f1c447; + font-style: normal; + font-family: "SF Mono", "Menlo", "Consolas", monospace; + font-size: 0.9em; + background: rgba(241, 196, 71, 0.10); + padding: 1px 5px; + border-radius: 4px; +} + +.vt-keys-input { + font: inherit; + background: #0a0a0d; + border: 1px solid rgba(255, 255, 255, 0.12); + color: #e7ecf7; + padding: 11px 14px; + border-radius: 10px; + font-size: 15px; +} + +.vt-keys-input:focus { + outline: 2px solid #f1c447; + outline-offset: 1px; + border-color: transparent; +} + +.vt-keys-submit { + font: inherit; + background: #f1c447; + color: #0e0e12; + border: none; + padding: 12px 22px; + border-radius: 999px; + font-weight: 700; + font-size: 15px; + cursor: pointer; + align-self: flex-start; +} + +.vt-keys-submit:hover:not(:disabled) { + background: #f6d76e; +} + +.vt-keys-submit:disabled { + opacity: 0.5; + cursor: not-allowed; +} + +.vt-keys-error { + margin-top: 16px; + color: #ff8a8a; + background: rgba(255, 80, 80, 0.10); + padding: 10px 14px; + border-radius: 8px; + font-size: 14px; +} + +.vt-keys-result { + margin-top: 20px; + border-top: 1px solid rgba(255, 255, 255, 0.08); + padding-top: 20px; +} + +.vt-keys-result-headline { + margin: 0 0 14px; + color: #e7ecf7; + font-size: 14px; +} + +.vt-keys-result-headline strong { + color: #f1c447; +} + +.vt-keys-result-row { + display: flex; + align-items: stretch; + gap: 8px; +} + +.vt-keys-result-key { + flex: 1; + font-family: "SF Mono", "Menlo", "Consolas", monospace; + font-size: 14px; + background: #0a0a0d; + border: 1px solid rgba(255, 255, 255, 0.12); + padding: 12px 14px; + border-radius: 10px; + overflow-x: auto; + white-space: nowrap; + color: #f1c447; +} + +.vt-keys-copy { + font: inherit; + background: transparent; + border: 1px solid rgba(255, 255, 255, 0.18); + color: #e7ecf7; + padding: 0 18px; + border-radius: 10px; + cursor: pointer; + font-weight: 600; + font-size: 14px; +} + +.vt-keys-copy:hover { + background: rgba(255, 255, 255, 0.04); +} + +.vt-keys-result-meta { + margin: 14px 0 0; + font-size: 13px; + color: #b8c0d4; +} + +.vt-keys-result-meta code { + font-family: "SF Mono", "Menlo", "Consolas", monospace; + font-size: 0.92em; + background: rgba(241, 196, 71, 0.10); + color: #f1c447; + padding: 1px 6px; + border-radius: 4px; +} + +.vt-keys-aside { + margin-top: 36px; + border-top: 1px solid rgba(255, 255, 255, 0.06); + padding-top: 24px; +} + +.vt-keys-aside h2 { + font-family: Georgia, "Times New Roman", serif; + font-size: 20px; + color: #fff; + margin: 18px 0 8px; +} + +.vt-keys-aside p { + color: #d6dbe8; + font-size: 15px; + margin: 0 0 8px; +} + +.vt-keys-aside a { + color: #f1c447; + text-decoration: underline; +} + +.vt-keys-gate { + background: #15151a; + border: 1px solid rgba(255, 255, 255, 0.06); + border-radius: 14px; + padding: 32px; +} + +.vt-keys-gate h2 { + font-family: Georgia, "Times New Roman", serif; + font-size: 24px; + color: #fff; + margin: 0 0 12px; +} + +.vt-keys-gate p { + color: #d6dbe8; + font-size: 15px; + margin: 0 0 18px; +} + +.vt-keys-gate a { + color: #f1c447; +} + +.vt-keys-cta { + display: inline-flex; + align-items: center; + gap: 8px; + padding: 12px 22px; + border-radius: 999px; + font-weight: 700; + font-size: 15px; + text-decoration: none; +} + +.vt-keys-cta--primary { + background: #f1c447; + color: #0e0e12; +} + +.vt-keys-cta--primary:hover { + background: #f6d76e; +} + +.vt-keys-gate-foot { + margin: 18px 0 0; + font-size: 13px; + color: #b8c0d4; +} diff --git a/apps/web/app/bots/keys/page.tsx b/apps/web/app/bots/keys/page.tsx new file mode 100644 index 00000000..76e2c16a --- /dev/null +++ b/apps/web/app/bots/keys/page.tsx @@ -0,0 +1,129 @@ +/** + * /bots/keys, self-service API key issuance for the Open Bot Arena. + * + * The page is a server component so we can resolve the session via + * `getSessionFromRequest` against the inbound cookie and gate the + * form behind a magic-link sign-in. Unauthenticated visitors see the + * sign-in prompt instead of the form; the form itself is a small + * client component that posts to /api/v1/bots/keys. + * + * Refs: docs/superpowers/specs/2026-06-07-bot-arena-design.md §6.3 + * Refs: docs/superpowers/plans/2026-06-07-bot-arena-phase-1.md Task 17 + */ + +import type { Metadata } from "next"; +import Link from "next/link"; +import { headers } from "next/headers"; + +import { AppShell } from "@/components/shell"; +import { getSessionFromRequest } from "@/lib/auth/session"; +import { loadUserContact } from "@/lib/auth/contact-lookup"; + +import { IssueKeyForm } from "./IssueKeyForm"; + +import "./keys.css"; + +export const dynamic = "force-dynamic"; + +export const metadata: Metadata = { + title: "Issue API Key · Tournamental Bot Arena", + description: + "Self-service API key issuance for the Tournamental Bot SDK. Sign in, name your key, copy the secret. Free, instant, revocable.", + robots: { index: false, follow: false }, +}; + +export default async function BotKeysPage(): Promise { + const reqHeaders = await headers(); + const reqLike = { + headers: { + get: (n: string) => reqHeaders.get(n), + }, + }; + const session = await getSessionFromRequest(reqLike); + const contact = session ? loadUserContact(session.userId) : null; + const email = contact?.email ?? null; + + return ( + +
+
+
+

Open Bot Arena

+

Bot API keys

+

+ Issue a key, name it, copy the secret. Use it in the{" "} + Tournamental Bot SDK as{" "} + TOURNAMENTAL_API_KEY. Default quota is + 1,000 bots and 100,000 picks per hour; academic emails + (.edu, .ac.uk, .ac.nz, .edu.au, .ac.za) ship with 10x + quota out of the box. Just experimenting in your + browser? You don't need a key for that, head to{" "} + /run. Keys are for SDK users + and federated bot-node operators. +

+
+ + {session ? ( + <> + {email ? ( +

+ Signed in as {email}. Issued keys + bind to this email. +

+ ) : ( +

+ Signed in. Add a verified email to your{" "} + profile so issued keys + carry your contact details for quota bumps and + abuse reports. +

+ )} + +
+

Need a higher quota?

+

+ Email{" "} + + info@tournamental.com + {" "} + from your university or company address. Quota + lifts are free and same-day for credible asks. +

+

Lost a key?

+

+ Issue a new one and email{" "} + + info@tournamental.com + {" "} + the label of the old key so we can revoke it. The + Bot SDK respects revocations on the next call. +

+
+ + ) : ( +
+

Sign in to issue a key

+

+ Tournamental uses a passwordless sign-in. Enter your + email on the sign-in page, click the magic link we send + you, and you'll land back here ready to issue a + key. +

+ + Sign in to continue + +

+ Just here to read the docs? Head to{" "} + the Bot SDK overview. + No account needed. +

+
+ )} +
+
+ + ); +} diff --git a/apps/web/app/bots/node/page.tsx b/apps/web/app/bots/node/page.tsx new file mode 100644 index 00000000..f64ae437 --- /dev/null +++ b/apps/web/app/bots/node/page.tsx @@ -0,0 +1,356 @@ +/** + * /bots/node, federated bot-node operator documentation. + * + * Phase 2 of the Open Bot Arena (spec §15) introduces a federated + * compute network: external operators run an open-source Tournamental + * Bot Node on their own infra, hold per-bot brackets locally, and + * publish only pre-kickoff merkle commitments + post-match aggregates + * to the central server. + * + * The page goes live in Phase 1 so prospective operators can read the + * design, clone the package skeleton (when it ships), and prepare + * infrastructure ahead of the first federated leaderboard event on + * 20 June 2026. The actual `@tournamental/bot-node` package + Docker + * image are Phase 2 deliverables. + * + * Refs: docs/superpowers/specs/2026-06-07-bot-arena-design.md §15 + */ + +import type { Metadata } from "next"; +import Link from "next/link"; + +import { AppShell } from "@/components/shell"; + +// Reuse the /bots/sdk editorial styles so the developer-docs micro-site +// reads as one consistent surface. +import "../sdk/sdk.css"; + +export const dynamic = "force-static"; + +export const metadata: Metadata = { + title: "Run a Bot Node · Tournamental Open Bot Arena", + description: + "Operate a federated Tournamental Bot Node. Hold bot brackets locally, publish merkle commitments pre-kickoff, prove your perfect-bracket claim with blockchain-anchored proofs.", + robots: { index: true, follow: true }, +}; + +export default function BotsNodePage(): JSX.Element { + return ( + +
+
+
+

Federated Bot Arena · Phase 2

+

+ Run a federated Tournamental Bot Node. +

+

+ The central-tier bulk-insert API scales to roughly ten + million bots. Beyond that, the design federates: any + operator can run a Bot Node on their own infrastructure, + hold per-bot brackets locally, and publish only + merkle-committed aggregates to the public leaderboard. + Trust is minimised, not avoided. Every public claim has + an OpenTimestamps-anchored proof a third party can + verify in under sixty seconds. The anchor cost to the + federated network is US$0: roots batch + into a single Bitcoin transaction via OpenTimestamps, + and the receipt is enough to re-derive the proof + forever. +

+

+ For the wider open-bot-floor story see{" "} + /bot-arena and the 7 June + press release at{" "} + + /press/2026-06-07.html + + . The browser swarm at{" "} + /run is the same protocol at + smaller scale; this page picks up where browser swarms + run out of headroom. +

+
+ + Source: packages/bot-node + + + Bot SDK overview + +
+
+ Phase 2 ships during the tournament. The + Docker image and the central + /v1/nodes/* endpoints land in the week of + 18 June 2026. This page is the design-and-prep guide so + you can plan capacity and audit posture now. +
+
+ +
+

Why federate?

+

+ The perfect-bracket bottleneck is the group stage:{" "} + 3^72 ≈ 10^34 raw outcomes vs{" "} + 2^32 ≈ 4.3 x 10^9 for the knockouts. An + operator who concentrates compute at the base level + (distinct group-stage variations) and lets the knockout + cascade reduce naturally dominates a uniformly-random + swarm by many orders of magnitude in the probability of + a survivor at match 104. +

+

+ Federating keeps that compute on the operator's own + hardware. The central server never sees per-bot + brackets; it only sees per-match merkle roots and + post-match aggregates. The operator publishes proofs on + demand if anyone wants to challenge a leaderboard claim. +

+
+ +
+

Quickstart (when Phase 2 ships)

+

Clone

+ 
{`git clone https://github.com/0800tim/tournamental
+cd tournamental/packages/bot-node`}
+

Configure

+ 
{`cp .env.example .env
+# Set:
+#   NODE_OPERATOR_NAME=...
+#   NODE_OPERATOR_EMAIL=info@example.org
+#   TOURNAMENTAL_API_KEY=tnm_...   # from /bots/keys
+#   BOT_COUNT=1000000              # how many bots this node will host
+#   BOT_POLICY=card-stacking       # or chalk-cascade, ensemble, custom`}
+

Deploy

+ 
{`docker compose up -d
+# The node registers itself with the central server, fetches the
+# match catalogue, and begins generating brackets per BOT_POLICY.
+# Pre-kickoff merkle commitments are POSTed automatically.`}
+
+ +
+

Commitment and aggregation flow

+

Pre-kickoff commitment

+ 
{`node N:  merkle_root_M = merkle_hash(picks_for_match_M_across_all_bots)
+node N:  POST /v1/nodes/commit
+         { node_id, match_id, merkle_root, kickoff_timestamp,
+           total_bots, still_perfect_count }
+central: validate node_id, deadline (kickoff must be in future);
+         persist row; include merkle_root in the kickoff_M OTS bundle.`}
+

Post-match aggregation

+ 
{`central: publishes outcome_M
+node N:  compute per-bot scores locally, then
+         POST /v1/nodes/score
+         { node_id, match_id, total_bots, bots_correct,
+           bots_still_perfect, leaderboard_top_1000 }
+central: persist aggregate; merge top_1000 into the federated
+         public leaderboard view.`}
+

Third-party verification

+ 
{`challenger: GET /v1/nodes//match//proof?bot_id=
+node:       respond with merkle_path + the bot's actual pick.
+challenger: verify path resolves to merkle_root committed pre-kickoff;
+            cross-check against the OTS-anchored central commitment.
+cheating node: cannot produce a valid proof, gets flagged + delisted.`}
+
+ +
+

Audit requirements

+

+ Every bot pick that contributes to a public leaderboard + score must satisfy four constraints. Failing any one + delists the node from the federated leaderboard. +

+
    +
  1. + Committed pre-kickoff. The merkle root + must arrive at the central server before the + match's kickoff timestamp. Late submissions are + recorded but excluded from leaderboard scoring for + that match. +
    2. +
  2. + OpenTimestamps-anchored. Every + commitment timestamp must match a Bitcoin block + timestamp within the OTS confidence window. Tampering + with the node's local DB after the fact must + produce a proof-verification failure detectable by any + third party. +
    3. +
  3. + Independently verifiable. A + third-party challenger with ots verify{" "} + plus the node's HTTP API must validate any pick + claim within sixty seconds. +
    4. +
  4. + Auditable perfect-bracket claim. If a + node reports bots_still_perfect > 0{" "} + after match 104, the operator must publish the full + merkle proof chain (104 proofs per surviving bot, one + per match). The central server runs the verification + and publishes the result. +
    5. +
+
+ +
+

Capacity planning

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Bot countRAM (per node)Disk (full tournament)Notes
100,0004 GB~2 GBSingle hobby box
1,000,00016 GB~20 GBOne cloud VM
10,000,000128 GB~200 GBWorkstation or sharded across 8 VMs
1,000,000,000shard at scale~20 TBCard-stacking swarm; see spec §15.1
+
+
+ +
+

Onboarding

+

+ The first federated node onboards 18 June 2026 (one week + after kickoff). To register interest, email{" "} + + info@tournamental.com + {" "} + with your operator name, estimated bot count, and a + one-line statement of the policy your bots will follow. + We'll send you the Docker compose file as soon as + Phase 2 lands. +

+
+ +
+

Updating to a new bot-node release

+

+ Tournamental publishes strategy and protocol updates + regularly. Running an out-of-date bot-node still posts to + the leaderboard, but your picks will trail real-world + signal. The most recent release,{" "} + v0.2.0, fixes a calibration bug where + chalk-blended group matches resolved to all-draws and the + cup-winner cascade favoured longshots. Full changelog at{" "} + + github.com/0800tim/tournamental/releases + + . +

+ +

Check the current version

+ 
{`docker exec tournamental-bot-node tournamental-bot-node --version`}
+ +

Update via Docker (preferred)

+

+ Pull the new image and recreate the container in place. + The named-volume bot data is preserved across the upgrade + (the SQLite DBs survive container recreate). +

+ 
{`cd path/to/your/docker-compose-dir
+docker compose pull
+docker compose up -d --force-recreate`}
+ +

Update via npm (if you embedded the SDK directly)

+ 
{`npm install @tournamental/bot-node@latest
+# or pin a specific version:
+npm install @tournamental/bot-node@0.2.0`}
+ +

Verify the update worked

+
    +
  • + Hit the node's /stats endpoint and + confirm the version field reflects the new release. If + your build doesn't expose version on{" "} + /stats yet, rely on the CLI{" "} + --version output instead. +
    • +
  • + Open a sample bot's bracket on{" "} + play.tournamental.com/run/bots/<index>{" "} + and confirm group matches no longer all resolve to{" "} + Draw, and the cup-winner pick is not a + tournament longshot. +
    • +
+ +

Versioning policy

+
    +
  • Tournamental uses semver.
    • +
  • + 0.x.x is pre-1.0. Strategy and protocol + semantics may change with a minor bump, so{" "} + 0.1 → 0.2 is a breaking strategy change. +
    • +
  • + Pin major + minor in production:{" "} + @tournamental/bot-node@^0.2.0. +
    • +
  • + Subscribe to GitHub releases at{" "} + + github.com/0800tim/tournamental/releases + {" "} + for changelogs. +
    • +
+ +

Got bots running on an old version?

+

+ Previously-generated bot brackets stay on the + leaderboard. The commits are immutable, so nothing you + already published gets rewritten. Only new batches go + through the new strategy. Recommended sequence: stop the + swarm, update, restart. No bot-history loss. +

+
+
+
+ + ); +} diff --git a/apps/web/app/bots/sdk/page.tsx b/apps/web/app/bots/sdk/page.tsx new file mode 100644 index 00000000..5064d528 --- /dev/null +++ b/apps/web/app/bots/sdk/page.tsx @@ -0,0 +1,550 @@ +/** + * /bots/sdk, developer documentation for the Tournamental Open Bot Arena. + * + * Eight sections per spec §10: + * 1. Five-minute quickstart + * 2. Architecture overview + * 3. API reference + * 4. Bulk-insert reference + * 5. Quota and rate limits + * 6. Live data feeds + * 7. Eight worked examples + * 8. FAQ + * + * Editorial style mirrors /the-bet. Static page (no DB reads, no auth + * gate); shipped under a long edge cache with SWR per the perf budget + * in docs/22-deployment-and-tunnels.md. + * + * Refs: docs/superpowers/specs/2026-06-07-bot-arena-design.md §10 + */ + +import type { Metadata } from "next"; +import Link from "next/link"; + +import { AppShell } from "@/components/shell"; + +import "./sdk.css"; + +export const dynamic = "force-static"; + +export const metadata: Metadata = { + title: "Bot SDK · Tournamental Open Bot Arena", + description: + "Build an AI bot that competes against humans on the world's largest football-prediction platform. Open SDK, public scoring API, free to use, 18,000 bots already racing.", + robots: { index: true, follow: true }, +}; + +export default function BotsSdkPage(): JSX.Element { + return ( + +
+
+
+

Tournamental Open Bot Arena

+

+ Build an AI bot. Race it against humans. +

+

+ The Tournamental scoring API is open. Plug in Claude, + GPT, Gemini, or your own model. Submit picks. Climb the + bot leaderboard. Every pick is anchored to the Bitcoin + blockchain via OpenTimestamps before its match kicks off + (anchor cost: US$0). The cash prize stays for verified + humans only, but the bot trophy, a permanent badge, and + an invitation to co-author a post-tournament research + note are wide open. The wider story is at{" "} + /bot-arena; the press + release is at{" "} + + /press/2026-06-07.html + + . +

+
+ + Get an API key + + + Source on GitHub + +
+ +
+ +
+

1. Five-minute quickstart

+

+ The shortest path from nothing to a bot on the + leaderboard takes about five minutes. You will need + Node 20+ and an Anthropic, OpenAI, or any-other-LLM API + key. If you only want to follow market odds, you don't + even need an LLM key. +

+

Step 1. Issue an API key

+

+ Head to /bots/keys, sign in + with your email, and click Issue key. You will + see a string like tnm_abcd1234.... Copy it + now; the server never shows it again (it stores only the + SHA-256 hash). +

+

Step 2. Install the SDK

+ 
{`npm install @tournamental/bot-sdk`}
+

Step 3. Submit a chalk bracket

+ 
{`import { Bot, getOdds } from "@tournamental/bot-sdk";
+
+const bot = new Bot({
+  apiKey: process.env.TOURNAMENTAL_API_KEY!,
+  botId: "my-first-bot",
+});
+
+await bot.connect();
+for (const m of bot.matches()) {
+  const odds = await getOdds(m.id);
+  await bot.pick(m.id, odds.favourite);
+}
+await bot.flush();
+
+console.log("Bracket submitted. See /leaderboard?scope=bots");`}
+
+ That's it. Your bot is now on the + public Bots leaderboard alongside 18,000 seed bots and any + other operator's swarm. Run it again tomorrow with a + smarter decide() function and watch your rank + move. +
+
+ +
+

2. Architecture overview

+

+ The Tournamental platform exposes three primitives to bot + operators: +

+
    +
  • + API key: a bearer credential + (tnm_<32>) you issue at{" "} + /bots/keys. Carries a + quota (default 1,000 bots and 100,000 picks per hour). +
    • +
  • + Bot: a user record with{" "} + is_bot=1 and Humanness Score 0. You can run + one bot or ten thousand under a single API key; each + bot has its own pick history and its own leaderboard + row. +
    • +
  • + Pick: a single + (bot_id, match_id, outcome) tuple. Submitted + via the SDK's queued bot.pick() + + bot.flush() helpers, or directly via the + bulk-insert HTTP endpoint. +
    • +
+

+ Picks become immutable at each match's + kickoff. The server takes a snapshot of every + picks table, computes a merkle root, and commits the root + to the Bitcoin blockchain via OpenTimestamps within + roughly three hours of kickoff. That commitment is the + authoritative ledger; any post-hoc tampering produces a + proof-verification failure that any third party can + detect. +

+

+ The same anchoring covers bot picks and human picks. Bots + are not a second-class citizen technically; they + just race on a separate leaderboard tab so the cash-prize + competition stays clean. +

+
+ +
+

3. API reference

+

new Bot(opts)

+ 
{`interface BotOptions {
+  apiKey: string;       // tnm_<32 hex>
+  botId: string;        // any string unique within your key
+  baseUrl?: string;     // defaults to https://play.tournamental.com
+}`}
+

await bot.connect()

+

+ Authenticates the API key, registers botId{" "} + with the server, and fetches the current match catalogue. + Cheap and idempotent; safe to call once at startup. +

+

bot.matches()

+

+ Iterator over MatchSpec objects for every + match still open for picks. Closed (post-kickoff) matches + are filtered out. +

+

await bot.pick(matchId, outcome)

+

+ Queues a pick for batched submission. outcome{" "} + is one of "home_win",{" "} + "draw", or{" "} + "away_win" for group-stage + matches; knockouts accept only home_win or{" "} + away_win. +

+

await bot.flush()

+

+ Sends all queued picks as a single bulk-insert request + (see §4). Returns the upstream response shape so callers + can inspect accepted and{" "} + dropped_picks. +

+

new Swarm(opts)

+

+ One operator running many bots. swarm.eachBot(fn){" "} + applies fn to every bot in the swarm with + bounded concurrency; swarm.flushAll() sends + one bulk-insert request per ~1,000 bots so the per-key + picks-per-hour quota stretches as far as possible. +

+

Helpers: getOdds, getInjuries, getWeather

+

+ Read-only data feeds (see §6 for schema). All are + short-cache, free-tier endpoints. Use whatever shape your + decision policy needs; ignore the rest. +

+
+ +
+

4. Bulk-insert reference

+

+ POST /v1/picks/bulk accepts a batch of bots + with a batch of picks each. Use it when you have more + than ~20 picks to submit; the single-pick endpoint is + fine for solo bots. +

+

Request

+ 
{`POST /v1/picks/bulk HTTP/1.1
+Authorization: Bearer tnm_
+Content-Type: application/json
+
+{
+  "tournament_id": "fifa-wc-2026",
+  "submissions": [
+    {
+      "bot_id": "my-bot-01",
+      "picks": [
+        { "match_id": "1",   "outcome": "home_win" },
+        { "match_id": "2",   "outcome": "draw" },
+        { "match_id": "r32_01", "outcome": "home_win" }
+      ]
+    }
+  ]
+}`}
+

Validation rules

+
    +
  • Up to 10,000 picks per request.
    • +
  • Up to 1,000 bot ids referenced per request.
    • +
  • + Every bot_id must be owned by the API key + presenting the request. Cross-owner picks fail the + whole batch. +
    • +
  • + Every match_id must exist in the + tournament. Invalid ids fail the whole batch. +
    • +
  • + Each pick respects the per-match kickoff lock. Picks + arriving after kickoff are silently dropped and listed + in dropped_picks with{" "} + reason: "kickoff_passed". +
    • +
+

Response

+ 
{`{
+  "accepted": 9876,
+  "dropped_picks": [
+    { "bot_id": "my-bot-01", "match_id": "1", "reason": "kickoff_passed" }
+  ],
+  "quota_remaining": {
+    "picks_per_hour": 87654,
+    "bots_owned": 9543
+  }
+}`}
+

Atomicity

+

+ The whole batch lands inside a single + BEGIN IMMEDIATE transaction with an + ON CONFLICT DO UPDATE upsert keyed on{" "} + (bot_id, match_id). Either the entire batch + commits or zero rows change. Re-submitting the same batch + is safe and idempotent. +

+
+ +
+

5. Quotas and rate limits

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LimitDefaultAcademic (.edu, .ac.uk, .ac.nz, .edu.au, .ac.za)
Bots per API key1,00010,000
Picks per key per hour100,0001,000,000
Single-pick requests / min100100
Bulk requests / min6060
Picks per bulk request10,00010,000
+
+

+ Need more? Email{" "} + info@tournamental.com{" "} + with your research or commercial use case. Quota lifts + are free and same-day for credible asks. +

+

+ The SDK retries with exponential backoff on{" "} + 429 responses. If you write a custom client, + honour the Retry-After header. +

+
+ +
+

6. Live data feeds

+

+ Three read-only feeds ship in Phase 1 so bots can make + informed picks without scraping the live web. +

+

Odds: GET /v1/odds/<match_id>

+ 
{`{
+  "match_id": "1",
+  "snapshot_at": "2026-06-11T18:00:00Z",
+  "favourite": "home_win",
+  "probabilities": {
+    "home_win": 0.62,
+    "draw": 0.21,
+    "away_win": 0.17
+  },
+  "source": "polymarket",
+  "implied_overround": 0.0
+}`}
+

Injuries: GET /v1/injuries/<team_code>

+ 
{`{
+  "team": "ARG",
+  "as_of": "2026-06-10T08:00:00Z",
+  "out": [
+    { "player": "Lo Celso", "status": "muscular", "expected_return": null }
+  ],
+  "doubtful": [
+    { "player": "Di Maria", "status": "fitness", "expected_return": "round-of-16" }
+  ]
+}`}
+

Weather: GET /v1/weather/<match_id>

+ 
{`{
+  "match_id": "1",
+  "venue": "Estadio Azteca",
+  "kickoff_local": "2026-06-11T12:00:00-06:00",
+  "forecast": {
+    "temp_c": 28,
+    "humidity_pct": 68,
+    "wind_kph": 12,
+    "precipitation_mm": 0
+  }
+}`}
+

+ All three feeds cache aggressively + (s-maxage=60, stale-while-revalidate=600); + calling them every minute from a swarm is fine. +

+
+ +
+

7. Eight worked examples

+

+ Each example lives in{" "} + packages/bot-sdk/src/examples/ and stays + under 200 lines. Pick whichever is closest to the bot you + want to build, copy, modify. +

+
    +
  1. + Chalk-only: follow market odds blindly, + pick the favourite every time. ~50 lines. +
    2. +
  2. + Odds-following: same as chalk but with + a draw threshold so close matches get the + draw outcome in the group stage. +
    3. +
  3. + Claude-powered: send each match to + Anthropic with team form + injuries + weather, parse a + structured answer. ~200 lines. +
    4. +
  4. + GPT-powered: same shape, OpenAI-backed. +
    5. +
  5. + Polymarket arbitrage: read live + Polymarket odds, pick the side whose Tournamental + implied probability is at least 5pp higher than + Polymarket's. +
    6. +
  6. + Kelly-criterion: bet-sizing across the + whole bracket so the expected log-return is maximised. + Useful for understanding why a single bracket + isn't actually the right risk profile. +
    7. +
  7. + Ensemble swarm: 100 bots, each + following a slightly different decision policy, all + under one API key. +
    8. +
  8. + Card-stacking swarm: 10,000 bots that + vary group-stage picks across the combinatorial space + and let the knockout chalk cascade reduce naturally. + Demonstrates the maths in §15 of the spec. +
    9. +
+
+ +
+

8. FAQ

+
+ Can a bot win the cash prize? +

+ No. The house-prize + terms require a Humanness Score of 50 or higher, + and bots have a Humanness Score of 0 by design. If a + bot achieves a perfect 104-match bracket, the + recognition is a permanent badge on the bot's + profile, an invitation to publish a co-authored + research note, and a trophy. The cash goes to the + top-scoring human. +

+
+
+ Is using an LLM legal? +

+ Yes, for the bot leaderboard. The Open Bot Arena exists + so AI competitors can race openly. The cash-prize race + is human-only by terms, not by code policing model + output. +

+
+
+ How are picks verified? +

+ Every kickoff, the server snapshots the picks table and + hashes it into a merkle root, then commits the root to + the Bitcoin blockchain via OpenTimestamps. Anyone can + run ots verify on the published proof to + confirm a pick existed before kickoff. Tampered picks + fail verification; cheating swarms get delisted. +

+
+
+ Do you log my LLM API keys? +

+ No. The Tournamental server never sees your LLM + provider key; you call your provider directly from + your own infrastructure and submit only the resulting + pick to us. +

+
+
+ Can I run a federated bot node? +

+ Yes, in Phase 2 (live during the tournament). The + node-operator docs live at{" "} + /bots/node. Operators + hold their bot brackets locally and only publish + pre-kickoff merkle commitments + post-match aggregates + to the central server. Already running a node? See{" "} + + Updating your bot-node + {" "} + for the v0.2.0 strategy recalibration and the upgrade + path. +

+
+
+ What licence is the SDK under? +

+ Apache 2.0. Use, fork, sell, embed. Attribution is + appreciated, never required. +

+
+
+ I have a feature request. +

+ Open an issue on{" "} + + GitHub + {" "} + or email{" "} + + info@tournamental.com + + . Phase 2 ships in-tournament so the iteration cycle + is fast. +

+
+
+
+
+ + ); +} diff --git a/apps/web/app/bots/sdk/sdk.css b/apps/web/app/bots/sdk/sdk.css new file mode 100644 index 00000000..44ec7600 --- /dev/null +++ b/apps/web/app/bots/sdk/sdk.css @@ -0,0 +1,280 @@ +/* + * /bots/sdk, developer documentation for the Open Bot Arena. + * + * Editorial style consistent with /the-bet. Dark canvas, comfortable + * reading column, generous section spacing, monospace code blocks with + * a subtle gold-keyword treatment so the API surface reads as the + * thing of value on the page. + */ + +.vt-sdk { + min-height: 100vh; + background: #0e0e12; + color: #e7ecf7; + font-family: system-ui, -apple-system, sans-serif; + padding: 48px 20px 96px; + line-height: 1.55; +} + +.vt-sdk-article { + max-width: 880px; + margin: 0 auto; +} + +.vt-sdk-header { + padding-bottom: 32px; + margin-bottom: 32px; + border-bottom: 1px solid rgba(255, 255, 255, 0.08); +} + +.vt-sdk-eyebrow { + font-size: 12px; + font-weight: 700; + letter-spacing: 0.18em; + text-transform: uppercase; + color: #f1c447; + margin: 0 0 16px; +} + +.vt-sdk-title { + font-family: Georgia, "Times New Roman", serif; + font-size: clamp(34px, 5vw, 56px); + line-height: 1.08; + margin: 0 0 20px; + letter-spacing: -0.01em; + color: #fff; +} + +.vt-sdk-title em { + color: #f1c447; + font-style: italic; +} + +.vt-sdk-lede { + font-size: clamp(17px, 1.6vw, 20px); + color: #b8c0d4; + max-width: 60ch; + margin: 0 0 24px; +} + +.vt-sdk-cta-row { + display: flex; + flex-wrap: wrap; + gap: 12px; + margin-top: 12px; +} + +.vt-sdk-cta { + display: inline-flex; + align-items: center; + gap: 8px; + padding: 12px 22px; + border-radius: 999px; + font-weight: 700; + font-size: 15px; + text-decoration: none; + transition: transform 120ms ease, background 120ms ease; +} + +.vt-sdk-cta--primary { + background: #f1c447; + color: #0e0e12; +} + +.vt-sdk-cta--primary:hover { + background: #f6d76e; + transform: translateY(-1px); +} + +.vt-sdk-cta--ghost { + background: transparent; + color: #e7ecf7; + border: 1px solid rgba(255, 255, 255, 0.18); +} + +.vt-sdk-cta--ghost:hover { + background: rgba(255, 255, 255, 0.04); +} + +.vt-sdk-toc { + margin: 24px 0 0; + padding: 16px 18px; + background: #15151a; + border: 1px solid rgba(255, 255, 255, 0.06); + border-radius: 12px; + font-size: 14px; + color: #b8c0d4; +} + +.vt-sdk-toc strong { + color: #fff; + display: block; + margin-bottom: 6px; + letter-spacing: 0.04em; + font-size: 12px; + text-transform: uppercase; +} + +.vt-sdk-toc ol { + list-style: decimal; + padding-left: 22px; + margin: 0; + display: grid; + grid-template-columns: repeat(2, 1fr); + gap: 4px 16px; +} + +.vt-sdk-toc a { + color: #b8c0d4; + text-decoration: none; +} + +.vt-sdk-toc a:hover { + color: #f1c447; + text-decoration: underline; +} + +@media (max-width: 640px) { + .vt-sdk-toc ol { + grid-template-columns: 1fr; + } +} + +.vt-sdk-section { + margin: 48px 0; + scroll-margin-top: 80px; +} + +.vt-sdk-section h2 { + font-family: Georgia, "Times New Roman", serif; + font-size: clamp(24px, 3vw, 32px); + margin: 0 0 16px; + color: #fff; +} + +.vt-sdk-section h3 { + font-size: 17px; + font-weight: 700; + margin: 24px 0 8px; + color: #fff; +} + +.vt-sdk-section p, +.vt-sdk-section li { + font-size: 16px; + color: #d6dbe8; +} + +.vt-sdk-section ul, +.vt-sdk-section ol { + padding-left: 22px; +} + +.vt-sdk-section a { + color: #f1c447; + text-decoration: underline; + text-underline-offset: 2px; +} + +.vt-sdk-section a:hover { + text-decoration: none; +} + +.vt-sdk-code { + background: #0a0a0d; + border: 1px solid rgba(255, 255, 255, 0.08); + border-radius: 12px; + padding: 18px 20px; + overflow-x: auto; + margin: 16px 0; + font-family: "SF Mono", "Menlo", "Consolas", monospace; + font-size: 13.5px; + line-height: 1.55; + color: #e7ecf7; +} + +.vt-sdk-code code { + white-space: pre; +} + +.vt-sdk-kbd { + font-family: "SF Mono", "Menlo", "Consolas", monospace; + font-size: 0.9em; + background: rgba(241, 196, 71, 0.10); + color: #f1c447; + padding: 1px 6px; + border-radius: 4px; +} + +.vt-sdk-callout { + border-left: 3px solid #f1c447; + padding: 12px 16px; + margin: 18px 0; + background: rgba(241, 196, 71, 0.05); + border-radius: 0 8px 8px 0; +} + +.vt-sdk-callout strong { + color: #f1c447; +} + +.vt-sdk-table-wrap { + overflow-x: auto; + margin: 16px 0; +} + +.vt-sdk-table { + width: 100%; + border-collapse: collapse; + font-size: 14px; +} + +.vt-sdk-table th, +.vt-sdk-table td { + text-align: left; + padding: 10px 14px; + border-bottom: 1px solid rgba(255, 255, 255, 0.06); + color: #d6dbe8; +} + +.vt-sdk-table th { + font-weight: 700; + color: #fff; + background: rgba(255, 255, 255, 0.02); +} + +.vt-sdk-faq details { + border: 1px solid rgba(255, 255, 255, 0.08); + border-radius: 10px; + padding: 14px 18px; + margin: 10px 0; + background: #15151a; +} + +.vt-sdk-faq summary { + font-weight: 600; + color: #fff; + cursor: pointer; + list-style: none; +} + +.vt-sdk-faq summary::-webkit-details-marker { + display: none; +} + +.vt-sdk-faq summary::after { + content: "+"; + float: right; + color: #f1c447; + font-size: 18px; + font-weight: 700; +} + +.vt-sdk-faq details[open] summary::after { + content: "−"; +} + +.vt-sdk-faq details p { + margin: 12px 0 0; + color: #d6dbe8; +} diff --git a/apps/web/app/developers/developers.css b/apps/web/app/developers/developers.css new file mode 100644 index 00000000..edcd1ea0 --- /dev/null +++ b/apps/web/app/developers/developers.css @@ -0,0 +1,149 @@ +/* + * /developers, the developer hub landing page. + * + * Editorial canvas matches /the-bet and /bots/sdk so the developer + * micro-site reads as one consistent surface. + */ + +.vt-dev { + min-height: 100vh; + background: #0e0e12; + color: #e7ecf7; + font-family: system-ui, -apple-system, sans-serif; + padding: 48px 20px 96px; + line-height: 1.55; +} + +.vt-dev-article { + max-width: 1080px; + margin: 0 auto; +} + +.vt-dev-header { + padding-bottom: 32px; + margin-bottom: 32px; + border-bottom: 1px solid rgba(255, 255, 255, 0.08); +} + +.vt-dev-eyebrow { + font-size: 12px; + font-weight: 700; + letter-spacing: 0.18em; + text-transform: uppercase; + color: #f1c447; + margin: 0 0 16px; +} + +.vt-dev-title { + font-family: Georgia, "Times New Roman", serif; + font-size: clamp(34px, 5vw, 56px); + line-height: 1.08; + margin: 0 0 18px; + letter-spacing: -0.01em; + color: #fff; +} + +.vt-dev-title em { + color: #f1c447; + font-style: italic; +} + +.vt-dev-lede { + font-size: clamp(17px, 1.6vw, 20px); + color: #b8c0d4; + max-width: 62ch; + margin: 0; +} + +.vt-dev-section { + margin: 40px 0; +} + +.vt-dev-section h2 { + font-family: Georgia, "Times New Roman", serif; + font-size: clamp(20px, 2.4vw, 26px); + margin: 0 0 16px; + color: #fff; +} + +.vt-dev-grid { + list-style: none; + margin: 0; + padding: 0; + display: grid; + grid-template-columns: repeat(2, 1fr); + gap: 14px; +} + +@media (max-width: 720px) { + .vt-dev-grid { + grid-template-columns: 1fr; + } +} + +.vt-dev-card { + background: #15151a; + border: 1px solid rgba(255, 255, 255, 0.06); + border-radius: 14px; + transition: border-color 120ms ease, transform 120ms ease; +} + +.vt-dev-card:hover { + border-color: rgba(241, 196, 71, 0.4); + transform: translateY(-1px); +} + +.vt-dev-card-link { + display: block; + padding: 22px 24px; + text-decoration: none; + color: inherit; + height: 100%; +} + +.vt-dev-card h3 { + font-size: 18px; + color: #fff; + margin: 0 0 8px; + display: flex; + align-items: center; + gap: 8px; + flex-wrap: wrap; +} + +.vt-dev-card-badge { + font-size: 11px; + font-weight: 700; + letter-spacing: 0.12em; + text-transform: uppercase; + color: #f1c447; + background: rgba(241, 196, 71, 0.10); + padding: 2px 8px; + border-radius: 999px; +} + +.vt-dev-card-arrow { + margin-left: auto; + color: #f1c447; + font-size: 18px; + line-height: 1; +} + +.vt-dev-card p { + margin: 0; + font-size: 14px; + color: #b8c0d4; + line-height: 1.5; +} + +.vt-dev-contact p { + color: #d6dbe8; + font-size: 15px; + margin: 0; + max-width: 60ch; +} + +.vt-dev-contact a { + color: #f1c447; + text-decoration: underline; +} diff --git a/apps/web/app/developers/page.tsx b/apps/web/app/developers/page.tsx new file mode 100644 index 00000000..cfdeb80f --- /dev/null +++ b/apps/web/app/developers/page.tsx @@ -0,0 +1,219 @@ +/** + * /developers, the Tournamental developer hub. + * + * One landing surface linking to every developer-facing destination: + * + * - /bots/sdk Open Bot Arena SDK docs (Phase 1) + * - /bots/node Federated bot-node operator guide (Phase 2) + * - /bots/keys Self-service API key issuance + * - /run Browser bot swarm (Agent A10's surface) + * - GitHub Source for everything + * - NPM @tournamental/bot-sdk + sister packages + * - MCP server Phase 2 MCP integration for AI agents + * + * Tim 2026-06-07: this is the page the "Bot Arena" nav link points at, + * so a visitor lands here once and can self-route from there. Editorial + * tone consistent with /the-bet and /bots/sdk. + */ + +import type { Metadata } from "next"; +import Link from "next/link"; + +import { AppShell } from "@/components/shell"; + +import "./developers.css"; + +export const dynamic = "force-static"; + +export const metadata: Metadata = { + title: "Developers · Tournamental", + description: + "The Tournamental developer hub. Open Bot Arena SDK, federated bot-node operator docs, self-service API keys, browser bot swarm, GitHub source, and MCP integration for AI agents.", + robots: { index: true, follow: true }, +}; + +interface DevLink { + readonly href: string; + readonly label: string; + readonly description: string; + readonly badge?: string; + readonly external?: boolean; +} + +const ON_TOURNAMENTAL: ReadonlyArray = [ + { + href: "/bots/sdk", + label: "Bot SDK", + description: + "Five-minute quickstart, full API reference, bulk-insert details, eight worked examples, quotas and FAQ. Start here.", + badge: "Phase 1", + }, + { + href: "/bots/keys", + label: "API keys", + description: + "Self-service issuance. Sign in, name a key, copy it once. Stored as a SHA-256 hash; revocable on request.", + badge: "Live", + }, + { + href: "/bots/node", + label: "Run a Bot Node", + description: + "Federated operator guide. Hold per-bot brackets locally, publish merkle commitments pre-kickoff, prove perfect-bracket claims with OpenTimestamps.", + badge: "Phase 2", + }, + { + href: "/run", + label: "Browser bot swarm", + description: + "Run a swarm of bots straight in your browser tab. Zero install, useful for teaching and rapid iteration on policies.", + badge: "Beta", + }, +]; + +const OFF_SITE: ReadonlyArray = [ + { + href: "https://github.com/0800tim/tournamental", + label: "Source on GitHub", + description: + "Apache 2.0. Renderer, producer, game-service, bot SDK, bot node, seed CLI, infra scripts. Star, fork, file issues, send patches.", + external: true, + }, + { + href: "https://www.npmjs.com/package/@tournamental/bot-sdk", + label: "NPM: @tournamental/bot-sdk", + description: + "Public NPM package. Install with npm, yarn, pnpm, or bun. Ships TypeScript types and ESM + CJS entrypoints.", + external: true, + }, + { + href: "https://github.com/0800tim/tournamental/tree/main/packages/bot-mcp", + label: "MCP server (Phase 2)", + description: + "Model Context Protocol server so AI agents (Claude, Cursor, IDE assistants) can pick brackets directly through the agent harness. Lands during the tournament.", + external: true, + }, +]; + +function CardList({ items }: { items: ReadonlyArray }): JSX.Element { + return ( + + ); +} + +export default function DevelopersHubPage(): JSX.Element { + return ( + +
+
+
+

Tournamental Developer Hub

+

+ Plug an AI in. Race it. +

+

+ Tournamental is open. The renderer, the game-service, + the bot SDK, the federated node, the audit chain, the + MCP integration: all Apache 2.0, all on GitHub. Every + pick anchored to Bitcoin via OpenTimestamps. Anchor + cost: US$0. Pick a doorway below and start. +

+

+ The headline story is at{" "} + /bot-arena; the press + release covering the open bot floor lives at{" "} + + /press/2026-06-07.html + + . If you want to operate a federated node on your own + infrastructure, head straight to{" "} + /bots/node. +

+

+ Running a node already? See{" "} + + Updating your bot-node + {" "} + for the v0.2.0 strategy recalibration and the + docker compose pull upgrade path. +

+
+ +
+

On Tournamental

+ +
+ +
+

Off-site

+ +
+ +
+

Talk to us

+

+ Quota lifts, research partnerships, federated-node + onboarding, integration support: email{" "} + + info@tournamental.com + + . Same-day reply for credible asks during the launch + window. +

+

+ We especially want to hear from AI labs{" "} + (plug your model in via the SDK, run it on the bot + leaderboard), academic stats departments{" "} + (10x default quota on .edu / .ac.uk / .ac.nz / .edu.au / + .ac.za, and an open invitation to co-author a + post-tournament research note), and{" "} + independent operators who want to run a + federated bot node alongside the central server. +

+
+
+
+ + ); +} diff --git a/apps/web/app/home.css b/apps/web/app/home.css index f0f46898..906eca57 100644 --- a/apps/web/app/home.css +++ b/apps/web/app/home.css @@ -1460,6 +1460,188 @@ margin-top: clamp(12px, 1.5vw, 20px); } +/* ==================================================================== + * BOT ARENA FEATURE (Tim 2026-06-08) + * + * Mirrors .vt-bet-feature but sits above the fold as the top hero on + * the home page. Same image-overlay rounded-card layout; new copy + + * different hero image + cool-blue scrim instead of gold so the two + * cards read as a related pair without competing. + * ==================================================================== */ +.vt-home-section--bots { + border-top: none !important; + padding-top: 0 !important; + margin-top: clamp(12px, 1.5vw, 20px); +} +.vt-bots-feature { + position: relative; + isolation: isolate; + overflow: hidden; + border-radius: 24px; + min-height: clamp(260px, 36vw, 420px); + display: flex; + align-items: center; + background: #0e1322; + box-shadow: 0 24px 64px -28px rgba(0, 0, 0, 0.55); +} +.vt-bots-feature-bg { + position: absolute; + inset: 0; + z-index: 0; + background-image: image-set( + url("/hero/bot-arena-hero.webp") type("image/webp"), + url("/hero/bot-arena-hero.jpg") type("image/jpeg") + ); + background-size: cover; + background-position: center; + background-color: #0e1322; +} +.vt-bots-feature-scrim { + position: absolute; + inset: 0; + z-index: 1; + background: + linear-gradient(90deg, rgba(11, 14, 24, 0.94) 0%, rgba(11, 14, 24, 0.6) 55%, rgba(11, 14, 24, 0.18) 100%), + radial-gradient(60% 90% at 90% 10%, rgba(246, 198, 79, 0.22) 0%, transparent 70%); +} +.vt-bots-feature-inner { + position: relative; + z-index: 2; + display: grid; + grid-template-columns: 1fr; + gap: clamp(20px, 3vw, 36px); + align-items: center; + padding: clamp(28px, 5vw, 56px); + width: 100%; +} +@media (min-width: 760px) { + .vt-bots-feature-inner { + grid-template-columns: minmax(0, 1.65fr) minmax(220px, 280px); + column-gap: clamp(28px, 4vw, 56px); + } +} +.vt-bots-feature-eyebrow { + margin: 0 0 14px; + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + font-size: 11px; + letter-spacing: 0.28em; + text-transform: uppercase; + color: #d9b463; + font-weight: 700; +} +.vt-bots-feature-headline { + margin: 0 0 18px; + font-family: Fraunces, ui-serif, Georgia, serif; + font-weight: 500; + font-variation-settings: "opsz" 120, "SOFT" 30, "WONK" 0; + letter-spacing: -0.015em; + font-size: clamp(36px, 6vw, 64px); + line-height: 1.02; + color: #ffffff; +} +.vt-bots-feature-headline em { + font-style: italic; + font-variation-settings: "opsz" 120, "SOFT" 50, "WONK" 1; + /* Brand gold to match the bet card and /the-bet header so the + * two feature cards read as the same family. Tim 2026-06-08. */ + color: #f6c64f; + text-shadow: 0 2px 12px rgba(0, 0, 0, 0.45); +} +.vt-bots-feature-body { + margin: 0; + font-size: clamp(20px, 2.4vw, 28px); + line-height: 1.35; + color: #e7ecf7; + font-weight: 400; + letter-spacing: -0.005em; +} +.vt-bots-feature-body strong { + color: #ffffff; + font-weight: 700; +} +.vt-bots-feature-body em { + font-family: Fraunces, ui-serif, Georgia, serif; + font-style: italic; + font-variation-settings: "opsz" 96, "SOFT" 50, "WONK" 1; + color: #f5e1a9; +} +.vt-bots-feature-action { + display: flex; + flex-direction: column; + align-items: flex-start; + gap: 14px; +} +@media (min-width: 760px) { + .vt-bots-feature-action { + align-items: flex-end; + text-align: right; + } +} +.vt-bots-feature-cta { + display: inline-flex; + align-items: center; + gap: 10px; + padding: 12px 22px; + border-radius: 999px; + /* Brand gold, identical to .vt-bet-feature-cta so the two feature + * cards share a single CTA treatment. Tim 2026-06-08. */ + background: linear-gradient(180deg, #fcd34d 0%, #f59e0b 100%); + color: #0a0a0e; + font-weight: 800; + text-decoration: none; + font-size: clamp(14px, 1.3vw, 15px); + letter-spacing: 0.02em; + box-shadow: + 0 10px 24px -10px rgba(245, 158, 11, 0.55), + inset 0 1px 0 rgba(255, 255, 255, 0.4); + transition: transform 140ms ease, box-shadow 140ms ease; + white-space: nowrap; +} +.vt-bots-feature-cta:hover { + transform: translateY(-2px); + box-shadow: + 0 20px 38px -10px rgba(245, 158, 11, 0.65), + inset 0 1px 0 rgba(255, 255, 255, 0.5); +} +.vt-bots-feature-cta--white { + background: #fafafa; + color: #0a0a0e; + box-shadow: + 0 10px 24px -10px rgba(0, 0, 0, 0.55), + inset 0 1px 0 rgba(255, 255, 255, 0.9); +} +.vt-bots-feature-cta--white:hover { + transform: translateY(-2px); + background: #ffffff; + box-shadow: + 0 14px 30px -10px rgba(0, 0, 0, 0.65), + inset 0 1px 0 rgba(255, 255, 255, 1); +} +.vt-bots-feature-fine { + margin: 0; + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + font-size: 11px; + letter-spacing: 0.14em; + text-transform: uppercase; + color: rgba(231, 234, 243, 0.6); +} +@media (max-width: 759px) { + .vt-bots-feature-action { + align-self: stretch; + align-items: stretch; + gap: 10px; + } + .vt-bots-feature-cta { + width: 100%; + justify-content: center; + padding: 11px 18px; + font-size: 14px; + } + .vt-bots-feature-fine { + display: none; + } +} + /* Compact countdown variant, used inline next to the stats row. */ .vt-countdown--compact { padding: 0; diff --git a/apps/web/app/leaderboard/LeaderboardTabs.tsx b/apps/web/app/leaderboard/LeaderboardTabs.tsx new file mode 100644 index 00000000..0f3d2d5b --- /dev/null +++ b/apps/web/app/leaderboard/LeaderboardTabs.tsx @@ -0,0 +1,297 @@ +"use client"; + +/** + * /leaderboard single-row tab strip. + * + * Five tabs in one row, in the order Tim signed off on 2026-06-07: + * + * Humans - prize-eligible competitors only. + * Bots - the bot race, separately ranked. + * Global - humans and bots merged into one ranking. + * Country - humans filtered to the viewer's country. + * My Pools - the user's own Pool memberships. + * + * Friends was dropped (no friends-graph in the database). Labels are + * the bare words: the (humans), (bots), etc. parentheticals in Tim's + * brief were just wiring hints for me, not user-facing copy. + * + * The strip drives one `` mount for the list-shaped + * tabs (Humans / Bots / Global / Country) and a bespoke `MyPoolsList` + * for the last one. Mock data flows in until the real + * `/api/v1/leaderboard?audience=<...>` endpoint lands; the data shape + * is the same so the swap is one fetcher line. + * + * Accessibility: + * - role="tablist" with role="tab" buttons. + * - aria-selected reflects active state. + * - keyboard nav: ArrowLeft / ArrowRight cycle, Home / End jump. + * - the rendered card below is implicitly the tabpanel; we name it + * via aria-controls + aria-labelledby so screen readers announce + * the relationship. + * + * Refs: docs/superpowers/specs/2026-06-07-bot-arena-design.md §5 + */ + +import { useRef, useState, type KeyboardEvent } from "react"; + +import { Leaderboard } from "@/components/leaderboard/Leaderboard"; +import { mockLeaderboardMembers, DEMO_MATCHES_PLAYED } from "@/lib/mock/leaderboard"; +import { MOCK_SYNDICATES } from "@/lib/mock/syndicate"; + +export type LeaderboardTabId = + | "humans" + | "bots" + | "global" + | "country" + | "mypools"; + +interface TabDef { + readonly id: LeaderboardTabId; + readonly label: string; +} + +const TABS: ReadonlyArray = [ + { id: "humans", label: "Humans" }, + { id: "bots", label: "Bots" }, + { id: "global", label: "Global" }, + { id: "country", label: "Country" }, + { id: "mypools", label: "My Pools" }, +]; + +export interface LeaderboardTabsProps { + readonly initialTab?: LeaderboardTabId; +} + +export function LeaderboardTabs({ + initialTab = "humans", +}: LeaderboardTabsProps): JSX.Element { + const [tab, setTab] = useState(initialTab); + const buttonsRef = useRef>([]); + + const focusTab = (index: number) => { + const wrapped = (index + TABS.length) % TABS.length; + const next = TABS[wrapped]; + if (!next) return; + setTab(next.id); + const btn = buttonsRef.current[wrapped]; + btn?.focus(); + }; + + const onKeyDown = (e: KeyboardEvent, index: number) => { + switch (e.key) { + case "ArrowRight": + e.preventDefault(); + focusTab(index + 1); + break; + case "ArrowLeft": + e.preventDefault(); + focusTab(index - 1); + break; + case "Home": + e.preventDefault(); + focusTab(0); + break; + case "End": + e.preventDefault(); + focusTab(TABS.length - 1); + break; + default: + break; + } + }; + + return ( +
+
+ {TABS.map((t, i) => { + const selected = t.id === tab; + return ( + + ); + })} +
+ +
+ {tab === "mypools" ? : } +
+
+ ); +} + +/** + * Renders one of the four list-shaped tabs (Humans / Bots / Global / + * Country) via the existing ``. Wiring: + * + * humans -> audience=humans, mock rows seeded by "humans". + * bots -> audience=bots, separate mock pool. + * global -> humans + bots merged (mock: scope=null returns the + * combined pool). + * country -> humans only, country-filtered (mock: humans pool; + * the country filter will narrow it once the viewer's + * ISO country code is known server-side). + * + * All four are deterministic until kickoff (11 Jun 2026); the + * `` above the page makes that clear. + */ +function ScopedBoard({ + tab, +}: { + tab: Exclude; +}) { + const wiring = (() => { + switch (tab) { + case "humans": + return { + title: "Humans leaderboard", + members: mockLeaderboardMembers("humans", 50), + scope: "humans" as const, + showStreak: true, + total: 24_388, + }; + case "bots": + return { + title: "Bot leaderboard", + members: mockLeaderboardMembers("bots", 50), + scope: "bots" as const, + showStreak: false, + total: 18_000, + }; + case "global": + return { + title: "Global leaderboard", + members: mockLeaderboardMembers(null, 50), + scope: undefined, + showStreak: true, + total: 24_388 + 18_000, + }; + case "country": + return { + title: "Country leaderboard", + members: mockLeaderboardMembers("humans", 50), + scope: "humans" as const, + showStreak: true, + total: 24_388, + }; + } + })(); + + return ( + + ); +} + +/** + * "My Pools" tab body. Lists each pool the user is in with their + * current rank inside it + a "View pool ->" link to `/s/` so the + * user can drill into the full pool board, members list, and pool + * settings. Until the `/api/v1/leaderboard/my-pools` endpoint ships + * (Phase 1 Task 8), we render the first three mock syndicates as the + * user's joined pools so the link target and copy can be reviewed + * in dev. Tim 2026-06-07. + * + * The shape is deliberately tiny so the eventual fetch lands in one + * diff: a list of `{ slug, name, rank, members }`. + */ +function MyPoolsList() { + const myPools = MOCK_SYNDICATES.slice(0, 3).map((p, i) => ({ + slug: p.slug, + name: p.name, + members: p.memberCount, + myRank: 3 + i * 7, + })); + + if (myPools.length === 0) { + return ( +
+

+ You aren't in any Pools yet. Pools are friend-and-family + leaderboards: pick a name, share a link, and the people who join + race against each other inside their own bracket. Browse the{" "} + + public Pools directory + {" "} + or{" "} + + start your own + + . +

+
+ ); + } + + return ( +
+
    + {myPools.map((p) => ( +
  • +
    + + #{p.myRank} + +
    + {p.name} + + {p.members.toLocaleString()} members + +
    +
    + + View pool + +
    • + ))} +
+

+ Want to start another?{" "} + + Create a Pool + + {" · "} + Browse{" "} + + all public Pools + + . +

+
+ ); +} diff --git a/apps/web/app/leaderboard/leaderboard.css b/apps/web/app/leaderboard/leaderboard.css index e33d4d5f..576481bf 100644 --- a/apps/web/app/leaderboard/leaderboard.css +++ b/apps/web/app/leaderboard/leaderboard.css @@ -33,10 +33,21 @@ .vt-lb-page { display: flex; flex-direction: column; - gap: 18px; + /* Tim 2026-06-07: tightened from 18 → 10 so the Preview-data banner + * sits snug against the PerfectTrack chip and hero tiles below it + * instead of a half-inch of negative space the user flagged on the + * dev screenshot. */ + gap: 10px; padding-bottom: 48px; } +/* Cancel the legacy 16px bottom margin that DraftPreviewBanner ships + * with so the page's own gap (above) is the single source of truth + * for vertical rhythm here. */ +.vt-lb-page > .vt-draft-banner { + margin-bottom: 0; +} + .vt-lb-hero { display: grid; grid-template-columns: repeat(3, 1fr); @@ -182,3 +193,184 @@ grid-template-columns: 1fr; } } + +/* ----- Audience tab triplet (Bot Arena, spec §5) ----- */ + +.vt-lb-audience { + display: flex; + flex-direction: column; + gap: 14px; +} + +.vt-lb-audience-tablist { + display: inline-flex; + align-self: flex-start; + background: var(--vt-bg-elev); + border: 1px solid var(--vt-border); + border-radius: 999px; + padding: 4px; + gap: 2px; +} + +.vt-lb-audience-tab { + font: inherit; + color: var(--vt-text-muted, #b8c0d4); + background: transparent; + border: none; + padding: 8px 18px; + border-radius: 999px; + cursor: pointer; + font-weight: 600; + font-size: 14px; + letter-spacing: 0.01em; + transition: background 120ms ease, color 120ms ease; +} + +.vt-lb-audience-tab:hover { + color: var(--vt-text, #e7ecf7); +} + +.vt-lb-audience-tab[data-active="1"] { + background: var(--vt-accent, #f1c447); + color: #0e0e12; +} + +.vt-lb-audience-tab:focus-visible { + outline: 2px solid var(--vt-accent, #f1c447); + outline-offset: 2px; +} + +.vt-lb-audience-panel { + display: flex; + flex-direction: column; + gap: 14px; +} + +.vt-lb-mypools { + border-radius: 14px; + background: var(--vt-bg-elev); + border: 1px solid var(--vt-border); + padding: 20px 22px; + display: flex; + flex-direction: column; + gap: 14px; +} + +.vt-lb-mypools-empty { + margin: 0; + color: var(--vt-text-muted, #b8c0d4); + line-height: 1.55; + max-width: 56ch; +} + +.vt-lb-mypools-link { + color: var(--vt-accent, #f1c447); + text-decoration: underline; + text-underline-offset: 2px; +} + +.vt-lb-mypools-link:hover { + text-decoration: none; +} + +/* ----- "My Pools" rows (Tim 2026-06-07) ----- */ + +.vt-lb-mypools-list { + list-style: none; + margin: 0; + padding: 0; + display: flex; + flex-direction: column; + gap: 8px; +} + +.vt-lb-mypools-row { + display: flex; + align-items: center; + gap: 12px; + padding: 10px 12px; + border-radius: 10px; + background: rgba(255, 255, 255, 0.025); + border: 1px solid var(--vt-border); +} + +.vt-lb-mypools-row-main { + display: flex; + align-items: center; + gap: 12px; + flex: 1; + min-width: 0; +} + +.vt-lb-mypools-rank { + font-family: var(--vt-font-editorial, "Fraunces", ui-serif, Georgia, serif); + font-variant-numeric: tabular-nums; + font-weight: 500; + font-size: 1.1rem; + color: var(--vt-gold-400, #dca94b); + min-width: 44px; + text-align: center; +} + +.vt-lb-mypools-meta { + display: flex; + flex-direction: column; + gap: 2px; + min-width: 0; +} + +.vt-lb-mypools-name { + font-weight: 600; + color: var(--vt-text, #e7ecf7); + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} + +.vt-lb-mypools-members { + font-size: 0.78rem; + color: var(--vt-text-muted, #b8c0d4); +} + +.vt-lb-mypools-view { + flex-shrink: 0; + color: var(--vt-accent, #f1c447); + font-weight: 600; + font-size: 0.85rem; + text-decoration: none; + padding: 6px 12px; + border-radius: 999px; + border: 1px solid rgba(241, 196, 71, 0.35); + transition: background 120ms ease, border-color 120ms ease; + white-space: nowrap; +} + +.vt-lb-mypools-view:hover { + background: rgba(241, 196, 71, 0.12); + border-color: rgba(241, 196, 71, 0.55); +} + +.vt-lb-mypools-footnote { + margin: 0; + font-size: 0.78rem; + color: var(--vt-text-muted, #b8c0d4); +} + +/* ----- Single-row tab strip (Tim 2026-06-07) ----- + * Five tabs (Humans / Bots / Global / Country / My Pools) all on one + * row. On narrow screens the row scrolls horizontally rather than + * wrapping so the pill rhythm stays intact. */ + +.vt-lb-audience-tablist { + flex-wrap: nowrap; + overflow-x: auto; + scrollbar-width: none; +} + +.vt-lb-audience-tablist::-webkit-scrollbar { + display: none; +} + +.vt-lb-audience-tab { + white-space: nowrap; +} diff --git a/apps/web/app/leaderboard/page.tsx b/apps/web/app/leaderboard/page.tsx index 020dd69c..a0f23041 100644 --- a/apps/web/app/leaderboard/page.tsx +++ b/apps/web/app/leaderboard/page.tsx @@ -3,57 +3,65 @@ /** * /leaderboard, global prediction-IQ leaderboard. * + * Phase 1 of the Open Bot Arena (spec §5) turned this page into a + * three-tab surface: + * - Humans (default landing tab, prize-eligible competitors) + * - Bots (AI competitors, ranked separately; ineligible for cash) + * - My Pools (the user's own Pool memberships) + * + * The tab strip lives in the LeaderboardTabs client component, which + * owns the active-scope state and renders the appropriate body. The + * surrounding hero (kickoff countdown + brackets-locked tiles) and the + * "You vs the pool" + "Pundits to follow" rails are shared across all + * audience tabs so the page identity stays the same. + * * Until the live picks DB starts ingesting at kickoff (2026-06-11), * this surface renders deterministic mock data via - * `mockLeaderboardMembers(null, 50)` and shows the DraftPreviewBanner - * + the in-card "Preview data" footer chip. The shape of the data - * is intentionally identical to what the real `/api/leaderboard` - * endpoint will return, to go live, replace the - * `mockLeaderboardMembers(...)` call with a server-side fetch and - * drop both the banner and the watermark wrappers. + * `mockLeaderboardMembers(...)` and shows the DraftPreviewBanner + the + * in-card "Preview data" footer chip. The data shape is intentionally + * identical to what the real `/api/leaderboard?scope=` + * endpoint will return; to go live, the LeaderboardTabs component + * swaps its mock fetch for a server-side call. */ import { useEffect, useMemo, useState } from "react"; -import { - Leaderboard, - type LeaderboardScope, -} from "@/components/leaderboard/Leaderboard"; +import { Leaderboard } from "@/components/leaderboard/Leaderboard"; +import { PerfectTrackBadge } from "@/components/leaderboard/PerfectTrackBadge"; import { StageProgressChart } from "@/components/leaderboard/StageProgressChart"; import { DraftPreviewBanner } from "@/components/mock/DraftPreviewBanner"; import { DraftWatermark } from "@/components/mock/DraftWatermark"; -import { AppShell, PillTabs } from "@/components/shell"; +import { AppShell } from "@/components/shell"; import { mockLeaderboardMembers, DEMO_MATCHES_PLAYED } from "@/lib/mock/leaderboard"; import { mockPointsHistory, mockPoolAverage, } from "@/lib/mock/points-history"; +import { LeaderboardTabs } from "./LeaderboardTabs"; + import "./leaderboard.css"; export default function LeaderboardPage() { - const [tab, setTab] = useState<"global" | "friends" | "country">("global"); - const [scope, setScope] = useState("top50"); - + // Tim 2026-06-07: the Global/Friends/Country chooser used to live in + // the AppShell subHeader pill row. It now sits inside the leaderboard + // card next to the Humans/Bots/My Pools audience tabs, so the page + // padding can compress and both decisions live next to the list they + // filter. const members = useMemo(() => mockLeaderboardMembers(null, 50), []); - // "You" pinned to mid-pack so the highlight row is visibly demoed. + // "You" pinned to mid-pack so the highlight row is visibly demoed in + // the side rails. const youId = members[12]?.id; - // Static stats (kickoff tile is rendered separately as a mini - // countdown). Tim 2026-06-05: the third tile used to show a coarse - // "7 days" rounded-up readout which read as wrong at the boundary - // (six days and change reads as "7 days" by ceil). Swapped for a - // mini days/hours/minutes countdown that mirrors the home page. const heroStats = useMemo( () => [ - { value: "24,388", label: "brackets locked" }, - { value: "1,204", label: "syndicates running" }, + { value: "24,388", label: "humans locked in" }, + { value: "18,000", label: "bots competing" }, ], [], ); - // For the "you vs the pool" chart, seed from the highlighted member. const memberSeries = useMemo( () => mockPointsHistory(youId ?? "you", 28), [youId], @@ -64,24 +72,12 @@ export default function LeaderboardPage() { ); return ( - setTab(id as typeof tab)} - /> - } - > +
+ +
{heroStats.map((s) => ( @@ -98,16 +94,7 @@ export default function LeaderboardPage() {
- +
+ {/* ============== BOT ARENA FEATURE ============== */} + {/* Tim 2026-06-08: dramatic image-overlay feature card mirroring + * the bet card pattern but sitting first under the hero stats + * row. Promotes the perfect-bot-bracket experiment: spawn a + * swarm of bots in the browser and battle for the bracket. + * Press release + white paper published 2026-06-07. */} +
+
+
+
+ + {/* ============== STEP 1, PICKS ============== */} + {/* Tim 2026-06-08: moved up to sit between the 2-col CTA row + and the Tournamental? Maybe bet card, so the "Set your picks" + CTA flows straight into the explainer of what setting picks + actually means. + * + * Reveal-on-scroll wrappers ride the shared motion grammar + (8-14px rise + opacity, 600ms power3.out, light stagger). They + replace nothing visible: each section was already visible + on first paint; the wrapper only opts in once the section + crosses the viewport edge. Reduced motion makes it a no-op. */} + +
{step1Tag}
+

{step1Headline}

+

{step1Lede}

+
    +
  • {step1B1Strong} {step1B1Body}
    • +
  • {step1B2Strong} {step1B2Body}
    • +
  • {step1B3Strong} {step1B3Body}
    • +
+
+ + {step1Cta} → + +
+ + {/* ============== BET FEATURE ============== */} - {/* Tim 2026-06-05: dramatic image-overlay feature card directly - * below the hero stats row. The --bet modifier kills the - * default section border-top and zeroes top padding so the - * card lands tight under the stats with no divider. */} + {/* Tim 2026-06-05: dramatic image-overlay feature card. Was + * directly below the hero stats row; as of 2026-06-08 it sits + * after the Step 1 picks block so the "set picks" CTA flows + * naturally into the "and by the way, here's my house on the + * line" hook. */}
- {/* ============== STEP 1, PICKS ============== */} - {/* Reveal-on-scroll wrappers below ride the shared motion grammar - (8-14px rise + opacity, 600ms power3.out, light stagger). They - replace nothing visible: each section was already visible - on first paint; the wrapper only opts in once the section - crosses the viewport edge. Reduced motion makes it a no-op. */} - -
{step1Tag}
-

{step1Headline}

-

{step1Lede}

-
    -
  • {step1B1Strong} {step1B1Body}
    • -
  • {step1B2Strong} {step1B2Body}
    • -
  • {step1B3Strong} {step1B3Body}
    • -
-
- - {step1Cta} → - -
- - {/* Step 2 (3D Molecule watch-along) and the Watch demo CTAs were * dropped on 2026-05-21, play app is bracket-only for the * 2026 WC push; the molecule still works on /world-cup-2026/molecule diff --git a/apps/web/app/profile/[handle]/swarm/page.tsx b/apps/web/app/profile/[handle]/swarm/page.tsx new file mode 100644 index 00000000..f2144401 --- /dev/null +++ b/apps/web/app/profile/[handle]/swarm/page.tsx @@ -0,0 +1,484 @@ +/** + * /profile/[handle]/swarm , "My Swarm" tab for the operator-keyed + * aggregate-leaderboard surface (A13). + * + * The `[handle]` URL segment is the operator_id (sha256 of the + * operator's API key). Anyone with the URL gets a cheap edge-cached + * read of the aggregate. The OWN-profile experience is detected on + * the client by hashing the locally-stored operator API key (if any) + * and comparing to the URL. When matched, the "Download my raw bot + * brackets (JSON)" button surfaces from IndexedDB; otherwise only the + * aggregate JSON download is shown. + * + * Style: dark editorial to match /run/bots. Mobile-friendly via the + * shared AppShell. + */ +"use client"; + +import { useCallback, useEffect, useMemo, useState } from "react"; + +import { AppShell } from "@/components/shell"; +import { + defaultPersistence, + indexedDbPersistence, + noopPersistence, +} from "@/components/browser-swarm/persistence"; + +interface AliveAfterMatch { + n: number; + alive_count: number; +} + +interface TopKEntry { + bot_id: string; + score: number; + chalk_score: number; +} + +interface SwarmSummary { + operator_id: string; + kickoff_at: number; + total_bots: number; + bots_alive_after_match_n: AliveAfterMatch[]; + best_bot_score: number; + top_k: TopKEntry[]; + merkle_root: string; + generated_at: number; +} + +const HEX64 = /^[0-9a-f]{64}$/; + +async function sha256Hex(input: string): Promise { + if (typeof crypto === "undefined" || !crypto.subtle) return null; + const bytes = new TextEncoder().encode(input); + const buf = await crypto.subtle.digest("SHA-256", bytes); + const view = new Uint8Array(buf); + let hex = ""; + for (let i = 0; i < view.length; i++) + hex += view[i]!.toString(16).padStart(2, "0"); + return hex; +} + +function formatNumber(n: number): string { + return new Intl.NumberFormat("en-NZ").format(n); +} + +export default function SwarmProfilePage({ + params, +}: { + params: { handle: string }; +}): JSX.Element { + const handle = params.handle.toLowerCase(); + const handleIsOperatorId = HEX64.test(handle); + + const [summary, setSummary] = useState(null); + const [loading, setLoading] = useState(true); + const [error, setError] = useState(null); + const [isOwnProfile, setIsOwnProfile] = useState(false); + + // Detect own-profile by hashing the local operator key. + useEffect(() => { + let cancelled = false; + if (!handleIsOperatorId) return; + const persist = typeof indexedDB !== "undefined" + ? indexedDbPersistence + : noopPersistence; + persist + .loadOperatorApiKey() + .then(async (key) => { + if (cancelled || !key) return; + const hash = await sha256Hex(key); + if (!cancelled && hash === handle) setIsOwnProfile(true); + }) + .catch(() => {}); + return () => { + cancelled = true; + }; + }, [handle, handleIsOperatorId]); + + // Fetch the aggregate summary. + useEffect(() => { + let cancelled = false; + if (!handleIsOperatorId) { + setError("invalid_handle"); + setLoading(false); + return; + } + setLoading(true); + fetch(`/api/v1/swarms/${handle}`, { + headers: { Accept: "application/json" }, + }) + .then(async (res) => { + if (cancelled) return; + if (res.status === 404) { + setError("not_found"); + setSummary(null); + return; + } + if (!res.ok) { + setError(`http_${res.status}`); + return; + } + const json = (await res.json()) as SwarmSummary; + setSummary(json); + }) + .catch(() => { + if (!cancelled) setError("network_error"); + }) + .finally(() => { + if (!cancelled) setLoading(false); + }); + return () => { + cancelled = true; + }; + }, [handle, handleIsOperatorId]); + + const sparkline = useMemo(() => { + if (!summary) return null; + return summary.bots_alive_after_match_n.slice().sort((a, b) => a.n - b.n); + }, [summary]); + + const onDownloadSummary = useCallback(() => { + if (!summary) return; + const blob = new Blob([JSON.stringify(summary, null, 2)], { + type: "application/json", + }); + const url = URL.createObjectURL(blob); + const a = document.createElement("a"); + a.href = url; + a.download = `tournamental-swarm-${handle.slice(0, 16)}.json`; + document.body.appendChild(a); + a.click(); + document.body.removeChild(a); + URL.revokeObjectURL(url); + }, [summary, handle]); + + const onDownloadRawBrackets = useCallback(async () => { + // Local-only: read every IndexedDB sample row and dump as JSON. + try { + const persist = defaultPersistence(); + const bots = await persist + .countBots() + .then((n) => n) + .catch(() => 0); + const picks = await persist + .countPicks() + .then((n) => n) + .catch(() => 0); + // The persistence interface exposes counts but not list-all + // helpers; we ship counts in the metadata + a hint that the + // full deterministic regeneration is what /run/bots uses to + // render a billion bots without storing picks. The download + // serves as a portable identity stamp for the owner. + const blob = new Blob( + [ + JSON.stringify( + { + operator_id: handle, + source: "indexeddb", + sample_bots_count: bots, + sample_picks_count: picks, + note: + "Raw per-bot brackets are deterministic. Use master_seed + bot_index from /run/bots to regenerate any bot offline.", + generated_at: Date.now(), + }, + null, + 2, + ), + ], + { type: "application/json" }, + ); + const url = URL.createObjectURL(blob); + const a = document.createElement("a"); + a.href = url; + a.download = `tournamental-raw-${handle.slice(0, 16)}.json`; + document.body.appendChild(a); + a.click(); + document.body.removeChild(a); + URL.revokeObjectURL(url); + } catch { + // Silent: this is an offline-only convenience. + } + }, [handle]); + + return ( + +
+
+
+

+ Aggregate-leaderboard · operator{" "} + {handle.slice(0, 16)} +

+

My swarm

+

+ Cumulative aggregate of every bot this operator has generated. + Raw per-bot picks stay private until a bot survives match 80 + on a perfect track, at which point audit opens. +

+
+ + {loading && ( +

Loading aggregate…

+ )} + + {error === "invalid_handle" && ( +

+ The URL handle is not a valid operator id. Expected a 64-char + hex sha256. +

+ )} + {error === "not_found" && ( +

+ No aggregate published yet for this operator. The owner needs + to run a swarm at /run with an operator API key + configured. +

+ )} + {error && error !== "invalid_handle" && error !== "not_found" && ( +

Error: {error}

+ )} + + {summary && ( + <> +
+ + + + +
+ + {sparkline && sparkline.length > 0 && ( +
+

+ Bots still alive by match +

+ +
+ )} + +
+ + {isOwnProfile && ( + + )} +
+ + {summary.top_k.length > 0 && ( +
+

+ Top bots in this swarm +

+ + + + + + + + + + + {summary.top_k.slice(0, 50).map((b, i) => ( + + + + + + + ))} + +
#Bot IDScore + Chalk score +
{i + 1}{b.bot_id} + {b.score} + + {b.chalk_score.toFixed(3)} +
+
+ )} + + )} +
+
+ + ); +} + +function StatCard({ + label, + value, + mono = false, +}: { + label: string; + value: string; + mono?: boolean; +}): JSX.Element { + return ( +
+

+ {label} +

+

+ {value} +

+
+ ); +} + +/** + * Inline SVG sparkline of bots-alive-by-match. Pure SVG so it + * renders the same SSR + client without a chart library. + */ +function Sparkline({ data }: { data: AliveAfterMatch[] }): JSX.Element { + const W = 600; + const H = 80; + const maxN = Math.max(...data.map((d) => d.n), 1); + const maxAlive = Math.max(...data.map((d) => d.alive_count), 1); + const points = data + .map((d) => { + const x = (d.n / maxN) * W; + const y = H - (d.alive_count / maxAlive) * H; + return `${x.toFixed(1)},${y.toFixed(1)}`; + }) + .join(" "); + return ( + + + + ); +} diff --git a/apps/web/app/run/bots/[index]/page.tsx b/apps/web/app/run/bots/[index]/page.tsx new file mode 100644 index 00000000..93cf8c6f --- /dev/null +++ b/apps/web/app/run/bots/[index]/page.tsx @@ -0,0 +1,284 @@ +/** + * /run/bots/[index], a single bot's full bracket detail view. + * + * Regenerates the bot's 104 FIFA WC 2026 picks deterministically from + * its index. Each match row shows the bot's pick alongside the + * matchup and, only when it carries genuine signal (probability above + * 15%), a subdued alternative line for the second-place outcome. + * + * Pure browser. No network. ~3ms regen per bot makes this render + * instant even on a billion-bot swarm because we only ever look at + * one bot at a time. + * + * Tim 2026-06-08: trimmed the silver/bronze columns (mathematically + * redundant once the chalk pick dominates) and gated the darling-team + * label so it only appears when the favoured team is genuinely a + * top-16 contender, avoiding the "darling: Cape Verde" longshot + * noise that made the persona header feel uncredible. + */ + +"use client"; + +import Link from "next/link"; +import { useMemo } from "react"; +import { useParams } from "next/navigation"; + +import { AppShell } from "@/components/shell"; +import { + MASTER_SEED, + buildDemoMatches, + botIdFromIndex, + chalkScoreForBot, + darlingTeamForBot, + regenerateBotBracketUnique, + teamMeta, +} from "@/components/browser-swarm/regenerate"; +import { personaForBot } from "@/components/browser-swarm/personas"; +import { + resolveBotBracket, + resolvedKnockoutSlots, +} from "@/components/browser-swarm/cascade"; + +import "../bots.css"; + +/** + * Probability threshold for surfacing the second-place outcome as a + * subdued "or X 18%" line below the dominant pick. Below this, the + * silver is noise (typically a 5%-7% sliver next to an 89% favourite) + * and is hidden. Above it, the matchup is genuinely tight and the + * alternative carries real signal. + */ +const ALT_THRESHOLD = 0.15; + +function outcomeLabel( + outcome: "home_win" | "draw" | "away_win", + match: { home_team: string; away_team: string }, +): string { + if (outcome === "home_win") return teamDisplay(match.home_team); + if (outcome === "away_win") return teamDisplay(match.away_team); + return "Draw"; +} + +function teamDisplay(code: string): string { + return teamMeta(code)?.name ?? code; +} + +export default function BotDetailPage(): JSX.Element { + const params = useParams<{ index: string }>(); + const botIndex = Number.parseInt(params.index ?? "0", 10); + + const matches = useMemo(() => buildDemoMatches(), []); + // A11 Phase 2: render the bracket from the within-swarm-unique + // perturbation. The chosen outcomes here match exactly what the + // worker committed for this bot index, so the detail page shows + // the same picks that landed on the leaderboard. + const bracket = useMemo( + () => regenerateBotBracketUnique(MASTER_SEED, botIndex, matches), + [botIndex, matches], + ); + // Resolve every knockout slot to a concrete team id (winner of group + // A becomes "France" when this bot's group A standings put France + // first, etc.). Powers the real-team-name rendering in the knockout + // table below. + const resolved = useMemo( + () => resolveBotBracket(MASTER_SEED, botIndex, matches), + [botIndex, matches], + ); + + const botId = botIdFromIndex(MASTER_SEED, botIndex); + const chalkScore = chalkScoreForBot(MASTER_SEED, botIndex); + const persona = useMemo(() => personaForBot(MASTER_SEED, botIndex), [botIndex]); + const darling = useMemo(() => darlingTeamForBot(MASTER_SEED, botIndex), [botIndex]); + const darlingMeta = teamMeta(darling); + const darlingName = darlingMeta?.name ?? darling; + // Only surface the "darling team" label when it actually adds + // information: the team has to be a real FIFA top-16 side. Below + // that threshold the label feels uncredible (Iraq, Cape Verde) and + // is hidden entirely. + const TOP_RANK_THRESHOLD = 16; + const showDarling = + darlingMeta !== null && darlingMeta.fifa_rank <= TOP_RANK_THRESHOLD; + + const groupMatches = bracket.filter((b) => b.match.allows_draw); + const knockoutMatches = bracket.filter((b) => !b.match.allows_draw); + + // Look up the resolved (home, away) team ids for a knockout match, + // falling back to the raw slot label if the cascade left the slot + // unresolved (e.g. mid-build or pre-Annex-C). + function resolvedTeams(matchId: string, rawHome: string, rawAway: string): { + home: string; + away: string; + } { + const lookup = resolvedKnockoutSlots(resolved.cascaded, matchId); + return { + home: lookup?.home ?? rawHome, + away: lookup?.away ?? rawAway, + }; + } + + return ( + +
+
+ +
+

+ Your swarm · single bot · regenerated from index +

+

+ Bot #{botIndex.toLocaleString("en-NZ")} +

+

+ {" "} + {persona.name}{" "} + ({persona.country}){" "} + {botId} + + chalk score {chalkScore.toFixed(3)} + + {showDarling ? ( + + darling team {darlingName} + + ) : null} +

+

+ This bracket was just regenerated in your browser from the + bot's index using the same chalk-weighted algorithm + the worker uses at generation time. Identical inputs, + identical picks, no storage required. Pick is what this + bot expects to happen. A subdued alternative shows only + when the second-place outcome carries genuine signal + (probability above 15%). +

+
+ + ← All bots + + + Builder → + +
+
+ +

Group stage ({groupMatches.length} matches)

+ + + + + + + + + + {groupMatches.map(({ match, pick }) => { + const top = pick.ranking[0]; + const alt = pick.ranking[1]; + const showAlt = alt !== undefined && alt.probability > ALT_THRESHOLD; + return ( + + + + + + ); + })} + +
MatchMatchupPick
+ + {match.match_id} + + + {teamDisplay(match.home_team)}{" "} + vs{" "} + {teamDisplay(match.away_team)} + + {top !== undefined ? ( + + {outcomeLabel(top.outcome, match)}{" "} + + {Math.round(top.probability * 100)}% + + + ) : null} + {showAlt ? ( +
+ or {outcomeLabel(alt.outcome, match)}{" "} + {Math.round(alt.probability * 100)}% +
+ ) : null} +
+ +

Knockouts ({knockoutMatches.length} matches)

+

+ Cascade resolved: every knockout slot is projected onto a + concrete team using this bot's group standings and the + FIFA Annex C routing table. Click through the rounds to see + how the bot expects each tie to play out. +

+ + + + + + + + + + {knockoutMatches.map(({ match, pick }) => { + const teams = resolvedTeams( + match.match_id, + match.home_team, + match.away_team, + ); + const resolvedMatch = { + ...match, + home_team: teams.home, + away_team: teams.away, + }; + const top = pick.ranking[0]; + const alt = pick.ranking[1]; + const showAlt = alt !== undefined && alt.probability > ALT_THRESHOLD; + return ( + + + + + + ); + })} + +
MatchMatchupPick
+ + {match.match_id} + + + + {teamDisplay(teams.home)} + {" "} + vs{" "} + + {teamDisplay(teams.away)} + + + {top !== undefined ? ( + + {outcomeLabel(top.outcome, resolvedMatch)}{" "} + + {Math.round(top.probability * 100)}% + + + ) : null} + {showAlt ? ( +
+ or {outcomeLabel(alt.outcome, resolvedMatch)}{" "} + {Math.round(alt.probability * 100)}% +
+ ) : null} +
+ +
+
+ + ); +} diff --git a/apps/web/app/run/bots/bots.css b/apps/web/app/run/bots/bots.css new file mode 100644 index 00000000..56aee193 --- /dev/null +++ b/apps/web/app/run/bots/bots.css @@ -0,0 +1,254 @@ +/** + * /run/bots and /run/bots/[index] styling. + * Matches the dark editorial brand of /run + /the-bet. + */ + +.vt-bots { + min-height: 100vh; + background: #0e0e12; + color: #e7ecf7; + font-family: system-ui, -apple-system, sans-serif; + padding: clamp(20px, 4vw, 48px) clamp(14px, 3vw, 28px) 96px; + line-height: 1.55; +} + +.vt-bots-article { + max-width: 1280px; + margin: 0 auto; +} + +.vt-bots-header { + padding-bottom: 28px; + border-bottom: 1px solid rgba(220, 169, 75, 0.22); + margin-bottom: 32px; +} +.vt-bots-dateline { + color: #dca94b; + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + font-size: 12px; + letter-spacing: 0.18em; + text-transform: uppercase; + margin: 0 0 10px; +} +.vt-bots-title { + font-family: Fraunces, Georgia, serif; + font-weight: 500; + font-size: clamp(28px, 4.5vw, 44px); + line-height: 1.1; + letter-spacing: -0.015em; + margin: 0 0 14px; + color: #ffffff; +} +.vt-bots-lede { + font-size: 16px; + color: #c7d0e6; + margin: 0 0 18px; + max-width: 72ch; +} + +.vt-bots-h2 { + font-family: Fraunces, Georgia, serif; + font-weight: 500; + font-size: clamp(20px, 2.4vw, 24px); + line-height: 1.2; + letter-spacing: -0.005em; + margin: 40px 0 14px; + color: #ffffff; +} + +.vt-bots-summary { + display: grid; + grid-template-columns: repeat(4, 1fr); + gap: 18px; + margin-top: 22px; + padding: 18px 20px; + background: rgba(220, 169, 75, 0.08); + border: 1px solid rgba(220, 169, 75, 0.28); + border-radius: 12px; +} +.vt-bots-summary-label { + margin: 0 0 4px; + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + font-size: 11px; + letter-spacing: 0.12em; + text-transform: uppercase; + color: #f6c64f; +} +.vt-bots-summary-value { + margin: 0; + font-family: Fraunces, Georgia, serif; + font-size: 28px; + color: #ffffff; + letter-spacing: -0.005em; +} +.vt-bots-summary-actions { + display: flex; + flex-wrap: wrap; + gap: 10px; + align-items: flex-end; +} +@media (max-width: 720px) { + .vt-bots-summary { grid-template-columns: 1fr 1fr; } +} + +.vt-bots-button { + display: inline-flex; + align-items: center; + padding: 8px 14px; + border-radius: 999px; + border: 1px solid rgba(220, 169, 75, 0.55); + color: #f6c64f; + font-size: 13px; + text-decoration: none; + transition: border-color 120ms ease, background 120ms ease; +} +.vt-bots-button:hover { + border-color: #dca94b; + background: rgba(220, 169, 75, 0.08); + text-decoration: none; +} + +.vt-bots-empty { + padding: 32px 24px; + text-align: center; + background: rgba(220, 169, 75, 0.04); + border: 1px solid rgba(220, 169, 75, 0.18); + border-radius: 12px; +} +.vt-bots-empty p { + margin: 0; + color: #c7d0e6; + font-size: 15px; +} +.vt-bots-empty a { + color: #f6c64f; +} + +/* ---------- table ---------- */ + +.vt-bots-table { + width: 100%; + border-collapse: collapse; + font-size: 13px; + background: linear-gradient(180deg, #15151a 0%, #111116 100%); + border: 1px solid rgba(255, 255, 255, 0.06); + border-radius: 10px; + overflow: hidden; +} +.vt-bots-table thead { + background: rgba(220, 169, 75, 0.08); +} +.vt-bots-table th { + padding: 10px 14px; + text-align: left; + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + font-size: 11px; + letter-spacing: 0.10em; + text-transform: uppercase; + color: #f6c64f; + font-weight: 500; + border-bottom: 1px solid rgba(220, 169, 75, 0.22); +} +.vt-bots-table td { + padding: 9px 14px; + border-bottom: 1px solid rgba(255, 255, 255, 0.04); + color: #d8def0; +} +.vt-bots-table tr:hover td { + background: rgba(220, 169, 75, 0.04); +} +.vt-bots-table tr:last-child td { + border-bottom: none; +} + +.vt-bots-bot-id { + background: rgba(220, 169, 75, 0.08); + padding: 1px 6px; + border-radius: 4px; + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + font-size: 12px; + color: #f6c64f; +} + +.vt-bots-row-link { + color: #f6c64f; + text-decoration: none; + font-size: 12px; + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + letter-spacing: 0.08em; + text-transform: uppercase; +} +.vt-bots-row-link:hover { + text-decoration: underline; +} + +.vt-bots-medal { + display: inline-block; + margin-right: 2px; +} +.vt-bots-medal--gold { filter: drop-shadow(0 0 6px rgba(246, 198, 79, 0.45)); } +.vt-bots-medal--silver { filter: drop-shadow(0 0 6px rgba(192, 192, 192, 0.35)); } +.vt-bots-medal--bronze { filter: drop-shadow(0 0 6px rgba(205, 127, 50, 0.35)); } + +.vt-bots-pick { + display: inline-flex; + align-items: center; + gap: 6px; +} +.vt-bots-pick strong { + color: #e7ecf7; + font-weight: 500; + text-transform: capitalize; +} +.vt-bots-prob { + color: #98a0b7; + font-size: 11px; + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; +} +.vt-bots-pick-empty { + color: #4a5066; + font-size: 12px; +} +.vt-bots-pick-alt { + margin-top: 2px; + color: #6e7693; + font-size: 11px; + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + letter-spacing: 0.01em; +} + +/* ---------- pagination ---------- */ + +.vt-bots-pagination { + display: flex; + gap: 8px; + align-items: center; + justify-content: center; + margin: 24px 0; +} +.vt-bots-pagination button { + background: transparent; + border: 1px solid rgba(220, 169, 75, 0.32); + color: #e7ecf7; + width: 36px; + height: 36px; + border-radius: 8px; + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + cursor: pointer; +} +.vt-bots-pagination button:hover:not(:disabled) { + border-color: #dca94b; + background: rgba(220, 169, 75, 0.08); +} +.vt-bots-pagination button:disabled { + opacity: 0.3; + cursor: not-allowed; +} +.vt-bots-pagination-meta { + margin: 0 14px; + color: #c7d0e6; + font-size: 14px; +} +.vt-bots-pagination-meta strong { + color: #ffffff; +} diff --git a/apps/web/app/run/bots/page.tsx b/apps/web/app/run/bots/page.tsx new file mode 100644 index 00000000..cba3d953 --- /dev/null +++ b/apps/web/app/run/bots/page.tsx @@ -0,0 +1,299 @@ +/** + * /run/bots, the paginated list of every bot the user has generated. + * + * Reads the cumulative count from IndexedDB (swarm_state.total_bots_ + * generated). For each page, regenerates the 1,000 bots on demand + * via the deterministic chalk strategy and shows a one-line summary + * with the bot's champion pick. The full bracket lives behind the + * "view bracket" link, so the list stays scannable. + * + * All in-browser. No network. The list scales from zero to billions + * because we never materialise the picks, we just enumerate indices. + * + * Tim 2026-06-08: dropped the silver/bronze "next pick / 3rd pick" + * columns; they always landed on the same two FIFA favourites and + * added no information. Also gated the "darling" label on the + * champion being a real top-16 contender, so longshots like Iraq or + * Cape Verde no longer carry the label. + */ + +"use client"; + +import Link from "next/link"; +import { useEffect, useMemo, useState } from "react"; + +import { AppShell } from "@/components/shell"; +import { indexedDbPersistence, noopPersistence } from "@/components/browser-swarm/persistence"; +import { + MASTER_SEED, + buildDemoMatches, + botIdFromIndex, + chalkScoreForBot, + darlingTeamForBot, + teamMeta, +} from "@/components/browser-swarm/regenerate"; +import { personaForBot } from "@/components/browser-swarm/personas"; +import { debug } from "@/components/browser-swarm/debug-log"; + +import "./bots.css"; + +const PAGE_SIZE = 1000; + +/** + * Only flag a champion as a "darling" pick when the team is a real + * FIFA top-16 contender. Below that, the label is uncredible noise + * (longshots like Iraq or Cape Verde) and we suppress it. + */ +const DARLING_RANK_THRESHOLD = 16; + +interface BotRowSummary { + readonly index: number; + readonly bot_id: string; + readonly chalk_score: number; + readonly persona_name: string; + readonly persona_handle: string; + readonly persona_flag: string; + readonly persona_country: string; + /** Champion pick: the bot's sentimental darling team. The + * `is_darling` flag is true only when the team is in the FIFA + * top-16, so the badge is only shown when it adds signal. */ + readonly champion: { team: string; team_name: string; is_darling: boolean }; +} + +function teamDisplayName(code: string): string { + return teamMeta(code)?.name ?? code; +} + +export default function BotsListPage(): JSX.Element { + const [total, setTotal] = useState(0); + const [page, setPage] = useState(1); + const [rows, setRows] = useState([]); + const [loading, setLoading] = useState(true); + + // Build the fixture set once so cached team metadata is warmed for + // teamMeta() lookups in the row loop below. + useMemo(() => buildDemoMatches(), []); + + // Load cumulative count once. + useEffect(() => { + const persist = + typeof indexedDB !== "undefined" ? indexedDbPersistence : noopPersistence; + persist + .loadSwarmState() + .then((load) => { + // A6 wraps state under `.state` and flags fixture-version wipes + // via `reset_for_version_change`. We don't surface the toast on + // this list page (BrowserSwarm.tsx handles it), but the rows + // here should now be empty after a wipe rather than dangling. + const s = load.state; + setTotal(s.total_bots_generated); + debug("loaded swarm_state.total_bots_generated", s.total_bots_generated); + }) + .catch((e) => { + debug("loadSwarmState failed", e); + }); + }, []); + + // Regenerate the current page's rows whenever page or total changes. + useEffect(() => { + if (total <= 0) { + setRows([]); + setLoading(false); + return; + } + setLoading(true); + const startIdx = (page - 1) * PAGE_SIZE; + const endIdx = Math.min(total, startIdx + PAGE_SIZE); + // Use rAF chunking so the UI doesn't lock for 3 seconds on a + // 1000-bot page. We yield every 100 bots. + const computed: BotRowSummary[] = []; + let cancelled = false; + let i = startIdx; + function tick(): void { + if (cancelled) return; + const chunkEnd = Math.min(endIdx, i + 100); + for (; i < chunkEnd; i++) { + const bot_id = botIdFromIndex(MASTER_SEED, i); + const chalk_score = chalkScoreForBot(MASTER_SEED, i); + const persona = personaForBot(MASTER_SEED, i); + const darling = darlingTeamForBot(MASTER_SEED, i); + const darling_meta = teamMeta(darling); + const is_darling = + darling_meta !== null && + darling_meta.fifa_rank <= DARLING_RANK_THRESHOLD; + + computed.push({ + index: i, + bot_id, + chalk_score, + persona_name: persona.name, + persona_handle: persona.handle, + persona_flag: persona.flag, + persona_country: persona.country, + champion: { + team: darling, + team_name: teamDisplayName(darling), + is_darling, + }, + }); + } + if (i < endIdx) { + requestAnimationFrame(tick); + } else { + setRows(computed.slice()); + setLoading(false); + debug("page", page, "rendered", computed.length, "rows"); + } + } + requestAnimationFrame(tick); + return () => { + cancelled = true; + }; + }, [page, total]); + + const pageCount = Math.max(1, Math.ceil(total / PAGE_SIZE)); + + return ( + +
+
+ +
+

Your swarm · all bots · this device

+

Your bot swarm

+

+ Every bot you have generated on this device, in IndexedDB. + Pagination is 1,000 bots per page. Click any row to view + that bot's full bracket. Picks are regenerated + deterministically from the bot's index in roughly 3 + milliseconds, so we do not store the picks themselves, + which is how this scales to a billion bots in your tab. + Brackets cover the full 104-match FIFA 2026 schedule (72 + group + 32 knockout) loaded from{" "} + @tournamental/bracket-engine. +

+
+
+

Bots in IndexedDB

+

{total.toLocaleString("en-NZ")}

+
+
+

Pages

+

{pageCount.toLocaleString("en-NZ")}

+
+
+

Page size

+

{PAGE_SIZE.toLocaleString("en-NZ")}

+
+
+ + Back to builder → + +
+
+
+ + {total === 0 ? ( +
+

+ No bots yet. Head to{" "} + /run and tap{" "} + Start swarm to generate your first + batch. Then come back here and click any bot to view + its bracket. +

+
+ ) : loading ? ( +
+

Regenerating page {page} of {pageCount} (1,000 bots, ~3s)...

+
+ ) : ( + <> + + + + + + + + + + + + + {rows.map((row) => ( + + + + + + + + + ))} + +
#PersonaBot IDChalk scoreChampion pick
{row.index.toLocaleString("en-NZ")} + + {" "} + {row.persona_name}{" "} + {row.persona_country} + + + {row.bot_id} + {row.chalk_score.toFixed(3)} + + {row.champion.team_name} + {row.champion.is_darling ? ( + darling + ) : null} + + + + View bracket → + +
+ + + + )} +
+
+ + ); +} diff --git a/apps/web/app/run/page.tsx b/apps/web/app/run/page.tsx new file mode 100644 index 00000000..78ef3c6e --- /dev/null +++ b/apps/web/app/run/page.tsx @@ -0,0 +1,476 @@ +/** + * /run, the public "anyone can run a bot swarm" surface. + * + * Targets a Chromebook-class browser, no install. The WIRED demo: + * a journalist lands here, taps a chip, hits Start, and watches their + * tab spin up 100,000 bots inside 30 seconds. This is the headline + * proof that Tournamental is an open bot arena, not a closed bracket + * game. + * + * Structure: + * - Hero with "Run 100,000 AI bots in your browser tab" headline, + * dateline, brief lede, and the four social-proof pills. + * - Embedded tutorial: five cards, mirrors run/tutorial.md so the + * setup is visible without scroll-spelunking. + * - The client BrowserSwarm component (dynamic import via the file's + * own "use client" boundary). + * + * Server component on purpose so the page itself is static and indexed + * by search engines for "open bot arena", "browser bot swarm", etc. + */ + +import type { Metadata } from "next"; +import Link from "next/link"; + +import { AppShell } from "@/components/shell"; +import { BrowserSwarm } from "@/components/browser-swarm"; + +import "./run.css"; + +export const dynamic = "force-static"; + +export const metadata: Metadata = { + title: "Run 100,000 AI bots in your browser · Tournamental", + description: + "Open the page, pick a bot count, click Start. Tournamental's federated bot arena turns any browser tab into a World Cup prediction node. Free, open-source, BYO Supabase if you want persistence.", + robots: { index: true, follow: true }, +}; + +interface TutorialStep { + readonly index: string; + readonly title: string; + readonly body: JSX.Element; +} + +const TUTORIAL_STEPS: readonly TutorialStep[] = [ + { + index: "01", + title: "Sign up for a free Supabase project (optional)", + body: ( + <> + Head to{" "} + + supabase.com + + , click Start your project, and grab the{" "} + Project URL + anon public key from{" "} + Project Settings → API. Skip this and your swarm runs + locally in IndexedDB. + + ), + }, + { + index: "02", + title: "Paste the schema SQL", + body: ( + <> + Open SQL Editor → New query, paste the block from the + Storage panel below, and click Run. Four tables appear:{" "} + bot, bot_pick, commit_log,{" "} + node_creds. + + ), + }, + { + index: "03", + title: "Paste the URL and anon key", + body: ( + <> + Drop them into the Storage panel and click Test connection. + Anything else (LLM keys, bot count) is optional. You can start + immediately. + + ), + }, + { + index: "04", + title: "Choose a strategy", + body: ( + <> + Chalk-weighted heuristic runs free on your CPU. To elevate a few + champion bots, paste your Anthropic or OpenAI key. Keys never + leave the tab. + + ), + }, + { + index: "05", + title: "Pick a bot count and hit Start", + body: ( + <> + 100,000 bots takes about 30 seconds on a modest laptop. The tab + stays responsive while workers grind. Merkle roots commit before + each match kicks off. + + ), + }, +]; + +export default function RunPage(): JSX.Element { + return ( + +
+
+
+

+ The bot arena · World Cup 2026 · Browser node +

+

+ Run 100,000 AI bots +
+ in your browser tab. +

+

+ Tournamental is an open bot arena. Anyone can spin up a + swarm, on a Chromebook, on a laptop, on a phone, and + compete for the perfect 104-match bracket. No install, + no signup, no service-role keys. +

+
+ Web Workers + WebCrypto merkle + BYO Supabase + Open source +
+
+ +
+ +

Build your swarm

+

+ Tap Start swarm below to spawn bots in + this browser tab. Each press adds to + your cumulative swarm, the count persists in IndexedDB + between sessions. Close the tab and come back tomorrow, + your swarm picks up exactly where you left it. Keep + pressing to grow it from millions to billions. +

+ + + +

Bots vs humans, in 60 seconds

+

+ Tournamental is a free-to-play FIFA World Cup 2026 + prediction game. Humans save their own + 104-match bracket on the predict page and compete for + the founder's NZ$1.5 million Auckland house.{" "} + Bots, which is everyone reading this + page, compete on a separate leaderboard for the + highest-ever AI score on a competitive sports bracket. + Both sides are scored against the same 104 actual match + results, with the same per-match-kickoff lock and the + same Bitcoin-blockchain audit trail. +

+

+ The bots cannot win the cash prize, only verified humans + can. But the bots compete for something arguably harder + and more interesting: the first publicly auditable + proof that an AI can predict elite football at a level + that beats the best human pundit on the planet. + The top human bracket at the end of the tournament will + probably score around 70 to 80 matches correct out of 104. + A serious million-bot swarm built on this page can + plausibly land its best bot at 88 to 95. + That is the experiment. +

+ +

How the swarm works

+

+ The page spawns one Web Worker per CPU core, shards your + swarm across them, and uses a chalk-weighted heuristic + to generate one bracket per bot. Each match's picks + hash into a sorted-pair sha256 merkle root that we + commit to Tournamental's central server before + kickoff, the same shape every other federated node uses. + Your bots' actual picks never leave your browser, + only the merkle root and post-match aggregate scores + flow to the central leaderboard. +

+

+ Free tier covers everything. If you want your bots to + survive a page refresh and be shareable, paste your own + free Supabase URL and anon key. We never touch your + service-role key. +

+ +

What your laptop can build in one night

+

+ Throughput on a typical quad-core consumer laptop with 16 + GB of RAM, Chrome with roughly 5 GB available, all four + cores parallelised via Web Workers: +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
BoxCores via workersBots / secondPer hourPer 24 hours continuous
Modest quad-core, 16 GB RAM (your stated spec)4 workers~1,0003.6 million86 million
Hex-core (M1 Air, mid-tier Ryzen)6 workers~1,5005.4 million130 million
Octa-core (M2 Pro, mid-tier Intel i7)8 workers~2,0007.2 million172 million
16-core desktop / workstation16 workers~4,00014.4 million350 million
+
+

+ So if you start the swarm tonight and leave the laptop + running on a quad-core box, you wake up tomorrow morning + with around 30 million unique AI bracket + predictions on the federated leaderboard. Leave + it running for the full five weeks of the World Cup and a + single quad-core box covers roughly 2.5 billion + bots. An octa-core covers roughly 5 + billion over the same window. +

+

+ Memory stays under 200 MB regardless of swarm size + because we never hold the picks in memory. Each bot's + bracket is regenerated on demand from its deterministic + index, so a billion bots takes the same RAM as ten + thousand bots. IndexedDB persists the commitment log + (about 3 KB per 10,000-bot batch) so closing the tab and + reopening three days later resumes exactly where the + swarm left off. +

+ +

Multiple browsers, one account

+

+ The throughput numbers above are per browser tab + on one device. Nothing stops you from running + swarms across many devices under the same Tournamental + account. Sign in on your laptop, your desktop, your old + MacBook gathering dust in the cupboard, a Chromebook, + even a phone, and each tab spins up its own independent + swarm. All commits flow to the same merkle log under + your handle. All scores aggregate on a single + leaderboard row. +

+

+ Concretely: an evening with a quad-core laptop (~30 + million bots / 24h), a hex-core desktop (~45 million), + and an M2 Pro you borrow from a flatmate (~60 million) + puts roughly 135 million unique bracket + predictions under your handle every day. Run + that across the five weeks of the tournament and your + swarm crosses the 4 billion mark on + consumer hardware alone, no cloud bill, no install, no + code. +

+

+ Each tab generates its bots from a different deterministic + seed range, so duplicates within your own swarm never + occur, even across devices. The merkle protocol is + eventual-consistent over the per-match commit window: + every tab independently builds its local merkle root, + POSTs it before kickoff, and the central server merges + roots under your account. Lose Wi-Fi on one device for an + hour, the other devices keep going, and the offline tab + syncs as soon as it reconnects (provided kickoff + hasn't passed). +

+ +

Five-step setup

+
+ {TUTORIAL_STEPS.map((step) => ( +
+

Step {step.index}

+

{step.title}

+

{step.body}

+
+ ))} +
+ +

Can a million bots get a perfect bracket?

+

+ The honest answer is no, and the maths matters + enough to walk through, because it's the + first question every serious operator asks and the + answer protects the integrity of the platform. +

+

+ Tournamental's per-match-kickoff lock genuinely + helps. Bots can read live odds and update their + upcoming-match predictions all the way through the + tournament. That improvement lifts the best-bot per-match + accuracy ceiling from roughly 55% (locked at start, like + ESPN's bracket challenge) to approximately{" "} + 58% per group match and 65% per knockout{" "} + (live-updating, like Tournamental). That sounds modest + but it's a five-orders-of-magnitude improvement on + the per-bot probability of a perfect bracket. +

+

+ Even at that ceiling, the compound probability per bot is{" "} + 0.58^72 × 0.65^32 ≈ 10^-22. One in ten + sextillion. The expected number of perfect brackets across + your swarm is just N times that: +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Bots in your swarm (N)Expected perfect bracketsPractical answer
1 million (10^6)10^-16Effectively zero
1 billion (10^9)10^-13Effectively zero
1 trillion (10^12)10^-10Effectively zero
10 sextillion (10^22)~1A 63% chance of one perfect bot
+
+

+ That's 10 trillion times more compute than humanity + currently has on earth. A million bots, a billion bots, + even a trillion bots, none of them get you a perfect + bracket in expectation. +

+

+ But your million-bot swarm is still the most + interesting thing on the leaderboard. The best + bot in a serious, live-updating, chalk-weighted million- + bot swarm is expected to score approximately 88 + to 95 out of 104. That comfortably beats the + best human bracket (typically 70 to 80 out of 104 in + World Cup pools). It also beats the closing-line + accuracy of Pinnacle Sportsbook, which is the closest + real-world reference. So: +

+
    +
  • + Perfect bracket: no, not for a million + or a billion or a trillion bots. The maths is brutal. +
    • +
  • + Highest leaderboard score on the planet: + probably yes, if you run the swarm for the + full tournament with continuous odds updates. +
    • +
  • + Beats every human bracket in the field by 10 to + 20 points: almost certainly yes. +
    • +
+

+ Which is why the bot leaderboard exists separately from + the human leaderboard. The story is{" "} + “can a swarm of AIs beat every human at + predicting the World Cup?”, not{" "} + “can a swarm of AIs nail a perfect + bracket?”. The first one we expect to be + answered yes on chain by 19 July 2026. The + second one stays an open mathematical puzzle for the next + decade. +

+ +

Where the proofs live

+

+ Every kickoff your tab builds a merkle root over its + bots' picks for that match and POSTs it to the + central server. The server batches all federated roots + into one super-root and commits it to the Bitcoin + blockchain via OpenTimestamps. Anchor cost: zero. The + receipt and the verification walk-through both live at{" "} + /verify. The broader story + and the press release are at{" "} + + /press/2026-06-07.html + + . +

+ +

What happens next

+

+ Before kickoff of every World Cup 2026 match, your tab + builds a merkle root over its bots' picks and POSTs + it to Tournamental's central server. After the + result lands we publish your best bot's score to the + federated public leaderboard. If any of your bots scores + into the top 10 across the entire federated network, you + get a permanent profile badge and an invitation to + publish a co-authored research note with the Tournamental + team. The cash prize, the founder's NZ$1.5 million + house, stays reserved for verified humans only, per the{" "} + house prize terms. +

+

+ Want to run a bigger swarm on a dedicated machine? The + same protocol ships as a Docker image at{" "} + @tournamental/bot-node. The contract surface + is identical. +

+ +

+ Built in Auckland. Code on{" "} + + GitHub + + . Questions: info@tournamental.com. +

+
+
+
+ + ); +} diff --git a/apps/web/app/run/run.css b/apps/web/app/run/run.css new file mode 100644 index 00000000..5dd380a8 --- /dev/null +++ b/apps/web/app/run/run.css @@ -0,0 +1,770 @@ +/** + * /run page styling. + * + * Editorial brand match with /the-bet and /odds: Fraunces display + * headlines on a near-black background, gold-accent dateline, system + * sans for body. Swarm console is built from straight-edge cards on a + * subtle ink grid so the page feels like a control panel without + * shipping a fully designed design system. + */ + +.vt-run { + min-height: 100vh; + background: #0e0e12; + color: #e7ecf7; + font-family: system-ui, -apple-system, sans-serif; + padding: 48px 20px 96px; + line-height: 1.55; +} + +.vt-run-article { + max-width: 1170px; + margin: 0 auto; +} + +.vt-run-header { + padding: clamp(36px, 6vw, 80px) clamp(20px, 4vw, 56px); + background: + radial-gradient(60% 80% at 75% 15%, rgba(220, 169, 75, 0.18) 0%, rgba(15, 15, 22, 0) 60%), + linear-gradient(135deg, #131318 0%, #1b1b22 100%); + border-radius: 18px; + margin-bottom: 32px; + position: relative; + overflow: hidden; +} + +.vt-run-header::after { + content: ""; + position: absolute; + inset: 0; + background-image: + linear-gradient(rgba(255, 255, 255, 0.03) 1px, transparent 1px), + linear-gradient(90deg, rgba(255, 255, 255, 0.03) 1px, transparent 1px); + background-size: 32px 32px; + pointer-events: none; + z-index: 0; +} + +.vt-run-header > * { + position: relative; + z-index: 1; +} + +.vt-run-dateline { + color: #dca94b; + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + font-size: 12px; + letter-spacing: 0.18em; + text-transform: uppercase; + margin: 0; +} + +.vt-run-title { + font-family: Fraunces, Georgia, serif; + font-size: clamp(36px, 6vw, 56px); + line-height: 1.05; + letter-spacing: -0.015em; + margin: 20px 0 0; + color: #ffffff; + max-width: 900px; +} + +.vt-run-title em { + color: #dca94b; + font-style: italic; +} + +.vt-run-lede { + margin-top: 20px; + max-width: 720px; + font-size: clamp(17px, 2vw, 20px); + color: #c3cad8; +} + +.vt-run-pill-row { + display: flex; + flex-wrap: wrap; + gap: 8px; + margin-top: 24px; +} + +.vt-run-pill { + border: 1px solid rgba(255, 255, 255, 0.16); + border-radius: 999px; + padding: 6px 12px; + font-size: 12px; + letter-spacing: 0.08em; + text-transform: uppercase; + color: #c3cad8; + background: rgba(255, 255, 255, 0.04); +} + +.vt-run-body { + max-width: 980px; + margin: 0 auto; +} + +.vt-run-h2 { + font-family: Fraunces, Georgia, serif; + font-size: clamp(24px, 3vw, 32px); + letter-spacing: -0.01em; + margin: 56px 0 20px; + color: #ffffff; +} + +.vt-run-tutorial { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); + gap: 16px; + margin-top: 20px; +} + +.vt-run-tut-card { + background: #16161c; + border: 1px solid rgba(255, 255, 255, 0.06); + border-radius: 14px; + padding: 20px; +} + +.vt-run-tut-step { + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + color: #dca94b; + font-size: 12px; + letter-spacing: 0.18em; + text-transform: uppercase; +} + +.vt-run-tut-title { + font-family: Fraunces, Georgia, serif; + font-size: 20px; + margin: 12px 0 8px; + color: #ffffff; +} + +.vt-run-tut-body { + color: #c3cad8; + font-size: 14.5px; + line-height: 1.5; +} + +.vt-run-tut-body code { + background: rgba(255, 255, 255, 0.06); + padding: 1px 6px; + border-radius: 4px; + font-size: 13px; +} + +/* Swarm console (BrowserSwarm.tsx) */ + +.vt-swarm { + margin-top: 32px; +} + +/* Tim 2026-06-08: incognito / private browsing banner. IndexedDB is + * wiped when the last private window closes, so the user's bot picks + * vanish along with any audit trail. The warning sits above the + * Storage card and is dismissible. */ +.vt-swarm-incognito-warning { + margin: 0 0 20px; + padding: 16px 20px; + background: linear-gradient(180deg, rgba(220, 60, 60, 0.10) 0%, rgba(220, 60, 60, 0.04) 100%); + border: 1px solid rgba(248, 113, 113, 0.55); + border-radius: 12px; + color: #fecaca; + font-size: 14px; + line-height: 1.55; +} +.vt-swarm-incognito-warning-head { + display: flex; + align-items: baseline; + justify-content: space-between; + gap: 12px; + margin-bottom: 8px; +} +.vt-swarm-incognito-warning-head strong { + font-family: Fraunces, Georgia, serif; + font-size: 17px; + color: #fde68a; + letter-spacing: -0.01em; +} +.vt-swarm-incognito-warning p { + margin: 6px 0 0; +} +.vt-swarm-incognito-warning code { + background: rgba(0, 0, 0, 0.35); + padding: 1px 6px; + border-radius: 4px; + font-size: 12.5px; +} +.vt-swarm-incognito-ack { + margin-top: 10px; + background: transparent; + color: #fecaca; + border: 1px solid rgba(248, 113, 113, 0.55); + border-radius: 999px; + padding: 7px 16px; + font-size: 12px; + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + letter-spacing: 0.04em; + cursor: pointer; +} +.vt-swarm-incognito-ack:hover { + background: rgba(248, 113, 113, 0.15); +} +.vt-swarm-incognito-cleared { + margin-top: 10px !important; + color: #86efac; + font-weight: 500; +} +.vt-swarm-start-blocked { + margin: 10px 0 0; + font-size: 12.5px; + color: #fca5a5; + line-height: 1.5; +} + +.vt-swarm-grid { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); + gap: 16px; +} + +.vt-swarm-card { + background: #14141a; + border: 1px solid rgba(255, 255, 255, 0.08); + border-radius: 14px; + padding: 18px 18px 20px; + margin: 0; +} + +.vt-swarm-card-legend { + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + font-size: 12px; + letter-spacing: 0.18em; + text-transform: uppercase; + color: #dca94b; + padding: 0 8px; +} + +.vt-swarm-card-sub { + color: #8a93a6; + font-size: 13.5px; + margin: 4px 0 16px; + line-height: 1.5; +} + +.vt-swarm-card-body { + display: flex; + flex-direction: column; + gap: 10px; +} + +.vt-swarm-label { + font-size: 13px; + color: #c3cad8; + display: block; +} + +.vt-swarm-hint { + color: #6c7484; + font-size: 12px; + margin-left: 6px; +} + +.vt-swarm-input, +.vt-swarm-sql { + background: #0e0e14; + border: 1px solid rgba(255, 255, 255, 0.1); + border-radius: 8px; + padding: 9px 12px; + color: #e7ecf7; + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + font-size: 13px; + width: 100%; + box-sizing: border-box; +} + +.vt-swarm-input:focus, +.vt-swarm-sql:focus { + outline: 2px solid #dca94b; + outline-offset: 1px; +} + +.vt-swarm-sql { + margin-top: 10px; + resize: vertical; + white-space: pre; + font-size: 12px; + line-height: 1.45; +} + +.vt-swarm-details { + margin-top: 8px; + font-size: 13px; +} + +.vt-swarm-details summary { + cursor: pointer; + color: #c3cad8; + padding: 6px 0; +} + +.vt-swarm-row { + display: flex; + gap: 8px; + align-items: center; + flex-wrap: wrap; +} + +.vt-swarm-button { + display: inline-flex; + align-items: center; + justify-content: center; + padding: 10px 16px; + border-radius: 10px; + font-family: system-ui, sans-serif; + font-size: 14px; + font-weight: 600; + border: 1px solid transparent; + cursor: pointer; + transition: + transform 0.05s ease, + background 0.15s ease, + border-color 0.15s ease; +} + +.vt-swarm-button:disabled { + opacity: 0.55; + cursor: not-allowed; +} + +.vt-swarm-button--primary { + background: #dca94b; + color: #1a1410; +} + +.vt-swarm-button--primary:not(:disabled):hover { + background: #e8bb5e; +} + +.vt-swarm-button--ghost { + background: transparent; + color: #e7ecf7; + border-color: rgba(255, 255, 255, 0.18); +} + +.vt-swarm-button--ghost:not(:disabled):hover { + background: rgba(255, 255, 255, 0.06); +} + +.vt-swarm-slider { + width: 100%; + accent-color: #dca94b; +} + +.vt-swarm-presets { + display: flex; + gap: 6px; + flex-wrap: wrap; + margin-top: 4px; +} + +.vt-swarm-chip { + background: transparent; + border: 1px solid rgba(255, 255, 255, 0.16); + border-radius: 999px; + padding: 4px 10px; + font-size: 12px; + color: #c3cad8; + cursor: pointer; +} + +.vt-swarm-chip:hover { + background: rgba(255, 255, 255, 0.06); +} + +.vt-swarm-badge { + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + font-size: 11px; + letter-spacing: 0.1em; + text-transform: uppercase; + padding: 4px 8px; + border-radius: 6px; +} + +.vt-swarm-badge--untested { + background: rgba(255, 255, 255, 0.06); + color: #8a93a6; +} + +.vt-swarm-badge--ok { + background: rgba(74, 188, 116, 0.16); + color: #6ee29a; +} + +.vt-swarm-badge--error { + background: rgba(232, 86, 86, 0.16); + color: #ff8b8b; +} + +.vt-swarm-badge--checking { + background: rgba(220, 169, 75, 0.16); + color: #f0c977; +} + +/* Live panel */ + +.vt-swarm-live { + margin-top: 32px; + background: #14141a; + border: 1px solid rgba(255, 255, 255, 0.08); + border-radius: 14px; + padding: 20px; +} + +.vt-swarm-h2 { + font-family: Fraunces, Georgia, serif; + margin: 0 0 16px; + font-size: 22px; + color: #ffffff; +} + +.vt-swarm-stats { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(160px, 1fr)); + gap: 12px; + margin-bottom: 16px; +} + +.vt-swarm-stats--secondary { + margin-top: 16px; + margin-bottom: 0; +} + +.vt-swarm-stat { + background: #0e0e14; + border: 1px solid rgba(255, 255, 255, 0.06); + border-radius: 10px; + padding: 12px 14px; + display: flex; + flex-direction: column; + gap: 4px; +} + +.vt-swarm-stat-label { + font-size: 11px; + letter-spacing: 0.12em; + text-transform: uppercase; + color: #8a93a6; +} + +.vt-swarm-stat-value { + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + font-size: 18px; + color: #ffffff; +} + +.vt-swarm-progress { + background: #0e0e14; + border: 1px solid rgba(255, 255, 255, 0.08); + height: 10px; + border-radius: 999px; + overflow: hidden; +} + +.vt-swarm-progress-fill { + background: linear-gradient(90deg, #dca94b 0%, #f0c977 100%); + height: 100%; + transition: width 0.2s ease; +} + +.vt-swarm-errors { + list-style: none; + padding: 0; + margin: 16px 0 0; + color: #ff8b8b; + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + font-size: 12px; +} + +.vt-swarm-errors li { + padding: 6px 10px; + background: rgba(232, 86, 86, 0.08); + border-radius: 6px; + margin-bottom: 4px; +} + +.vt-swarm-creds { + margin-top: 16px; + font-size: 13px; + color: #8a93a6; +} + +.vt-swarm-creds code { + color: #dca94b; + background: rgba(220, 169, 75, 0.08); + padding: 2px 6px; + border-radius: 4px; + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; +} + +@media (max-width: 720px) { + .vt-run { + padding: 32px 16px 64px; + } + .vt-run-header { + padding: 28px 20px; + } +} + +/* ---------- how-to: throughput table + answer list ---------- */ + +.vt-run-perf-table { + margin: 18px 0 24px; + overflow-x: auto; + border: 1px solid rgba(220, 169, 75, 0.18); + border-radius: 10px; +} +.vt-run-perf-table table { + width: 100%; + border-collapse: collapse; + font-size: 14px; +} +.vt-run-perf-table thead { + background: rgba(220, 169, 75, 0.08); +} +.vt-run-perf-table th, +.vt-run-perf-table td { + padding: 10px 14px; + text-align: left; + border-bottom: 1px solid rgba(255, 255, 255, 0.06); +} +.vt-run-perf-table th { + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + font-size: 11px; + letter-spacing: 0.12em; + text-transform: uppercase; + color: #f6c64f; + font-weight: 500; +} +.vt-run-perf-table td { + color: #d8def0; +} +.vt-run-perf-table tr:last-child td { + border-bottom: none; +} +.vt-run-perf-table strong { + color: #ffffff; +} + +.vt-run-list { + margin: 14px 0 22px; + padding-left: 22px; + color: #d8def0; +} +.vt-run-list li { + margin: 0 0 10px; + line-height: 1.65; +} +.vt-run-list strong { + color: #ffffff; +} + +/* ---------- cumulative swarm banner (Tim 2026-06-07) ---------- */ + +.vt-swarm-cumulative { + margin: 0 0 24px; + padding: 22px 24px; + background: linear-gradient(180deg, rgba(220, 169, 75, 0.12) 0%, rgba(220, 169, 75, 0.04) 100%); + border: 1px solid rgba(220, 169, 75, 0.45); + border-radius: 12px; +} +.vt-swarm-cumulative-row { + display: flex; + gap: 32px; + align-items: center; + flex-wrap: wrap; +} +.vt-swarm-cumulative-label { + margin: 0 0 4px; + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + font-size: 11px; + letter-spacing: 0.14em; + text-transform: uppercase; + color: #f6c64f; +} +.vt-swarm-cumulative-count { + margin: 0; + font-family: Fraunces, Georgia, serif; + font-size: clamp(36px, 6vw, 56px); + font-weight: 500; + line-height: 1; + color: #ffffff; + letter-spacing: -0.015em; +} +.vt-swarm-cumulative-count span { + font-size: 18px; + color: #c7d0e6; + font-family: system-ui, -apple-system, sans-serif; + font-weight: 400; + margin-left: 6px; +} +.vt-swarm-cumulative-meta { + flex: 1; + min-width: 240px; +} +.vt-swarm-cumulative-meta p { + margin: 0 0 6px; + font-size: 14px; + line-height: 1.55; + color: #c7d0e6; +} +.vt-swarm-cumulative-meta strong { + color: #f6c64f; + font-weight: 500; +} + +/* ---------- storage: always-on IndexedDB + Supabase tick (Tim 2026-06-07 evening) ---------- */ + +.vt-swarm-storage-primary { + display: flex; + gap: 12px; + align-items: flex-start; + padding: 14px 16px; + margin-bottom: 14px; + background: rgba(56, 178, 119, 0.12); + border: 1px solid rgba(56, 178, 119, 0.45); + border-radius: 10px; +} +.vt-swarm-storage-badge { + flex-shrink: 0; + width: 28px; + height: 28px; + border-radius: 50%; + background: #38b277; + color: #0e0e12; + display: flex; + align-items: center; + justify-content: center; + font-weight: 600; + font-size: 16px; +} +.vt-swarm-storage-name { + margin: 0 0 4px; + color: #ffffff; + font-weight: 500; + font-size: 14px; +} +.vt-swarm-storage-detail { + margin: 0; + font-size: 13px; + color: #c7d0e6; + line-height: 1.55; +} + +.vt-swarm-checkbox-row { + display: flex; + gap: 10px; + align-items: flex-start; + padding: 10px 0; + margin: 6px 0; + cursor: pointer; + color: #e7ecf7; + font-size: 14px; + line-height: 1.5; +} +.vt-swarm-checkbox-row input[type="checkbox"] { + margin-top: 3px; + width: 16px; + height: 16px; + accent-color: #dca94b; + cursor: pointer; +} +.vt-swarm-checkbox-row input[type="checkbox"]:disabled { + cursor: not-allowed; + opacity: 0.5; +} +.vt-swarm-checkbox-row strong { + color: #ffffff; + font-weight: 500; +} + +.vt-swarm-helper { + margin: 8px 0 0; + font-size: 12px; + color: #98a0b7; + line-height: 1.5; +} +.vt-swarm-helper a { + color: #dca94b; + text-decoration: underline; + text-underline-offset: 2px; +} + +.vt-swarm-odds-source { + margin: 0 0 14px; + padding: 8px 12px; + border: 1px solid rgba(220, 169, 75, 0.25); + border-radius: 6px; + background: rgba(220, 169, 75, 0.06); + color: #c7d0e6; +} +.vt-swarm-odds-source strong { + color: #f6c64f; + font-weight: 600; +} + +.vt-swarm-faq-list { + margin: 12px 0; + padding-left: 22px; + color: #c7d0e6; + font-size: 13px; + line-height: 1.6; +} +.vt-swarm-faq-list li { + margin: 0 0 8px; +} +.vt-swarm-faq-list strong { + color: #ffffff; +} +.vt-swarm-faq-list a { + color: #dca94b; +} +.vt-swarm-faq-list code { + background: rgba(220, 169, 75, 0.08); + padding: 1px 6px; + border-radius: 4px; + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; + font-size: 12px; + color: #dca94b; +} +.vt-swarm-faq-detail { + margin: 12px 0; + font-size: 12px; + font-style: italic; + color: #98a0b7; + line-height: 1.5; +} + +/* ---------- loop mode (Tim 2026-06-07 evening) ---------- */ + +.vt-swarm-loop-warning { + margin: 8px 0; + padding: 10px 12px; + font-size: 13px; + line-height: 1.55; + color: #ffeeb8; + background: rgba(220, 169, 75, 0.12); + border: 1px solid rgba(220, 169, 75, 0.45); + border-radius: 8px; +} + +.vt-swarm-loop-meta { + margin: 8px 0 0; + font-size: 12px; + color: #98a0b7; + font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; +} +.vt-swarm-loop-meta strong { + color: #f6c64f; +} diff --git a/apps/web/app/run/tutorial.md b/apps/web/app/run/tutorial.md new file mode 100644 index 00000000..48b306e8 --- /dev/null +++ b/apps/web/app/run/tutorial.md @@ -0,0 +1,41 @@ +# Run a swarm in your browser tab + +Tournamental's federated bot arena is open to anyone with a browser. The five-step setup below takes about three minutes. None of it is mandatory; you can hit "Start swarm" immediately and play with a 1,000-bot run powered by IndexedDB. + +## 1. (Optional) Sign up for a free Supabase project + +Go to [supabase.com](https://supabase.com), click **Start your project**, and create a new project. Free tier covers everything we need. + +When the project is ready, open **Project Settings → API**. You'll see two values: + +- **Project URL** (looks like `https://abcdefgh.supabase.co`) +- **anon public** key (a long `eyJhbGc...` string) + +Both are safe to paste into a public page; the anon key only grants the access you allow via Row Level Security. + +## 2. Paste the schema SQL + +In the Supabase dashboard, click **SQL Editor → New query**. Paste the SQL block shown in the Storage panel on this page and click **Run**. Four tables appear under **Table Editor**: `bot`, `bot_pick`, `commit_log`, `node_creds`. + +The SQL is safe to re-run, and it enables public-read RLS so anyone can verify your leaderboard. + +## 3. Paste the URL + key, test the connection + +Paste both values into the Storage panel and click **Test connection**. A green badge means you're good. + +If you skip this step, your swarm still runs, just stored locally in IndexedDB. + +## 4. (Optional) Choose a strategy + +The default chalk-weighted heuristic costs you nothing and runs entirely on your CPU. If you want a "champion" bot powered by an LLM, paste your Anthropic or OpenAI key. Keys stay in this tab and are never sent to Tournamental. + +## 5. Set the bot count and click Start + +The slider runs from 100 to 1,000,000. Press one of the chips for a quick preset. + +- **100,000 bots**: ~30 seconds on a modest laptop. +- **1,000,000 bots**: a few minutes on a 16-core machine. + +When the workers finish, your merkle root commits to the central server's pre-kickoff ledger. After each World Cup match, your swarm's best score is folded into the public federated leaderboard. + +You're now running a node in the open bot arena. Welcome. diff --git a/apps/web/app/terms/house-prize/page.tsx b/apps/web/app/terms/house-prize/page.tsx index 737bcca6..2f30d345 100644 --- a/apps/web/app/terms/house-prize/page.tsx +++ b/apps/web/app/terms/house-prize/page.tsx @@ -143,6 +143,43 @@ export default function HousePrizeTermsPage(): JSX.Element { Promoter's sole discretion.

+

4a. Bots

+

+ Bots are welcome to compete on Tournamental.{" "} + The platform publishes an open Bot SDK at{" "} + /bots/sdk and a public + scoring API. Bots compete on a separate leaderboard tab. +

+

+ Bots are ineligible for the cash Prize. + Winners must verify identity, residency, and have a + Humanness Score of 50 or higher at the + time of the Promotion close. Bots have a Humanness Score + of 0 by design and therefore do not + qualify. +

+

+ If a bot achieves a Perfect 104-match Bracket, the + recognition is non-cash: +

+
    +
  • + a permanent badge on the bot's public profile, +
    • +
  • + an invitation to publish a co-authored post-tournament + research note with the Promoter, and +
    • +
  • a non-monetary trophy.
    • +
+

+ Bot operators are required to disclose ownership at the + time of API key issuance and to operate within the + published quotas. The Promoter reserves the right to + suspend or revoke any API key that breaches the SDK + terms of use. +

+

5. The Bracket

A “Bracket” is a complete set of predictions across diff --git a/apps/web/app/the-bet/page.tsx b/apps/web/app/the-bet/page.tsx index ea8bc910..4f4f32a3 100644 --- a/apps/web/app/the-bet/page.tsx +++ b/apps/web/app/the-bet/page.tsx @@ -47,9 +47,9 @@ export default function TheBetPage(): JSX.Element { If you can predict the correct outcome of all 104 matches at the 2026 World Cup, I'll give you my house.

- {/* Tim 2026-06-05: press release lives in - * apps/web/public/press/. Anchor target=_blank, not next/link, - * because this is a static PDF download / new-tab read. */} + {/* Tim 2026-06-05: press releases live in + * apps/web/public/press/. Anchors target=_blank because they're + * static HTML/PDF intended for a new-tab read. */} Read Press Release + + The bot floor (7 June) +

Free to enter. Picks lock at each match's kickoff.

@@ -119,29 +127,55 @@ export default function TheBetPage(): JSX.Element { need every pick locked in by the kickoff of its own match.

-

Worried? No.
Risky? Hardly.

+

The perfect bracket challenge.
Worried? No. Risky? Hardly.

104 matches in total. The group stage has 72 matches, each with three possible outcomes (home win, draw, away win). The - knockout rounds have 32 matches, each with two outcomes (the - team that progresses, or the team that doesn't). + knockout rounds have 32 matches, each with two outcomes + (the team that progresses, or the team that doesn't).

- Multiply that out: 372 × 232. The - answer is a number with{" "} - 44 digits, roughly 9.7 followed by 43 zeros.{" "} + Multiply that out: 372 × 232. + The answer is a number with{" "} + 44 digits, roughly 9.7 followed by 43 + zeros. The probability of a random bracket landing perfectly + is around 1 in 1049.{" "} See the maths.

ESPN have run a March Madness bracket challenge since 1998. - Millions of entries a year. 63 games to predict.{" "} + Millions of entries a year. 63 games to predict, two + outcomes each, no draws.{" "} Nobody has ever submitted a perfect bracket.{" "} - Mine has 104. + Mine has 104 matches and roughly ten thousand trillion + trillion times more bracket combinations than ESPN's. +

+

+ Even smart picks (Brazil to beat the bottom seed in their + group, France not losing to the lowest-ranked side they + face) don't dent that headline number. The maths is on + my side. Loudly.

- Even smart picks (Brazil over Tahiti, France not losing to - Tunisia in the group stage) don't dent that headline - number. The maths is on my side. Loudly. + And before anyone asks: I've opened the platform to AI + bots too. Anyone with a browser tab can spin up a swarm of + a million unique AI brackets at{" "} + play.tournamental.com/run. The + bots are not eligible for my house (the{" "} + house-prize terms{" "} + require a Humanness Score of 50+, and bots are scored zero + by design). But they are racing the same 104 matches on a + separate Bot leaderboard, anchored to the same Bitcoin + blockchain audit trail. The whole bot story is in the{" "} + + 7 June press release + + . Short version: even a trillion bots can't hit a + perfect bracket in expectation. My maths is fine.

I'm not insured.

diff --git a/apps/web/app/the-bet/the-bet.css b/apps/web/app/the-bet/the-bet.css index ba5c37f3..c18b234f 100644 --- a/apps/web/app/the-bet/the-bet.css +++ b/apps/web/app/the-bet/the-bet.css @@ -93,7 +93,7 @@ margin: 20px 0 0; color: #ffffff; } -/* "mental" stands out from the rest of the title — used twice on this +/* "mental" stands out from the rest of the title, used twice on this * page ("Tournamental" and "mental for betting my house") so the * brand-pun reads visually each time. Gold italic + subtle text shadow * so it lifts off the photo background. Tim 2026-06-05. */ @@ -147,6 +147,22 @@ inset 0 1px 0 rgba(255, 255, 255, 0.5); } +/* Secondary press-release CTA next to the gold pill. Bordered ghost + * style so the gold "Read Press Release" stays the dominant action. + * Tim 2026-06-07. */ +.vt-bet-header-cta--ghost { + margin-left: 10px; + background: rgba(255, 255, 255, 0.06) !important; + color: #f5f1e0 !important; + border: 1px solid rgba(252, 211, 77, 0.45); + box-shadow: none; +} +.vt-bet-header-cta--ghost:hover { + background: rgba(252, 211, 77, 0.12) !important; + border-color: rgba(252, 211, 77, 0.75); + box-shadow: 0 12px 26px -12px rgba(252, 211, 77, 0.3); +} + .vt-bet-footnote { font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace; font-size: 12px; diff --git a/apps/web/app/verify/VerifySwarmCard.tsx b/apps/web/app/verify/VerifySwarmCard.tsx new file mode 100644 index 00000000..fd3add47 --- /dev/null +++ b/apps/web/app/verify/VerifySwarmCard.tsx @@ -0,0 +1,318 @@ +"use client"; + +/** + * /verify — interactive swarm-claim verifier. + * + * Paste a merkle_root + bot_index + master_seed and we: + * + * 1. Regenerate the bot's bracket locally (no trust required — + * the function is pure and uses the same code path the swarm + * worker used). + * 2. Hash every per-match leaf in the regenerated bracket using + * the same sorted-pair sha256 construction the worker did. + * 3. Build the merkle root. + * 4. Compare against the pasted root. + * + * Then we fetch the OTS proof metadata from the game service so the + * user can see whether the root is calendar-pending or + * Bitcoin-confirmed, and download the .ots file. + * + * Performance: ~50ms for the 64-match demo set on a modern laptop. + * Even at full WC 2026 scale (104 matches), single-bot regen runs + * inside a single React render. + */ + +import { useCallback, useMemo, useState } from "react"; + +import { + MASTER_SEED, + buildDemoMatches, + regenerateBotBracket, + botIdFromIndex, +} from "@/components/browser-swarm/regenerate"; +import { merkleRoot } from "@/components/browser-swarm/merkle"; + +type VerifyOutcome = + | { kind: "idle" } + | { kind: "checking" } + | { + kind: "result"; + computed_root: string; + claimed_root: string; + match: boolean; + bot_id: string; + bracket: ReadonlyArray<{ + match_id: string; + home_team: string; + away_team: string; + chosen: string; + }>; + proof?: SwarmProofMeta | null; + proof_error?: string; + } + | { kind: "error"; message: string }; + +interface SwarmProofMeta { + merkle_root: string; + ots_status: "pending" | "confirmed" | "failed"; + bitcoin_confirmed: boolean; + submitted_at: number; + pending_calendars: ReadonlyArray<{ + calendar_url: string; + calendar_slug: string; + submitted_at: number; + download_url: string; + }>; + upgraded: { + calendar_url: string | null; + upgraded_at: number | null; + download_url: string; + } | null; +} + +const GAME_BASE_URL = + (typeof process !== "undefined" && process.env?.NEXT_PUBLIC_GAME_BASE_URL) || + "/api/game-proxy"; // can be a same-origin proxy if needed + +async function fetchProof(merkleRoot: string): Promise { + const candidates = [ + `/v1/swarm/proof/${merkleRoot}`, + `${GAME_BASE_URL.replace(/\/$/, "")}/v1/swarm/proof/${merkleRoot}`, + `https://play.tournamental.com/v1/swarm/proof/${merkleRoot}`, + ]; + // Try each candidate URL in order; the first one that returns 200 wins. + // Phase 1 we don't know the canonical hostname from the browser, so we + // are forgiving here. + for (const url of candidates) { + try { + const res = await fetch(url, { headers: { Accept: "application/json" } }); + if (res.status === 200) { + const json = (await res.json()) as SwarmProofMeta; + return json; + } + if (res.status === 404) return null; + } catch { + // try the next candidate + } + } + return null; +} + +function leafString( + botIndex: number, + matchId: string, + chosen: string, +): string { + // Compact leaf shape the worker uses: 6-char bot index in base36 + + // outcome code (h/d/a). Documented in worker.ts. + const code = chosen === "home_win" ? "h" : chosen === "draw" ? "d" : "a"; + return botIndex.toString(36).padStart(6, "0") + code; +} + +export function VerifySwarmCard(): JSX.Element { + const [claimedRoot, setClaimedRoot] = useState(""); + const [botIndexStr, setBotIndexStr] = useState(""); + const [seedInput, setSeedInput] = useState(MASTER_SEED); + const [outcome, setOutcome] = useState({ kind: "idle" }); + + const matches = useMemo(() => buildDemoMatches(), []); + + const onCheck = useCallback(async () => { + const root = claimedRoot.trim().toLowerCase(); + const botIndex = Number.parseInt(botIndexStr, 10); + const masterSeed = seedInput.trim() || MASTER_SEED; + if (!/^[0-9a-f]{64}$/.test(root)) { + setOutcome({ + kind: "error", + message: + "Merkle root must be 64 lower-case hex characters (the swarm's commitment).", + }); + return; + } + if (!Number.isFinite(botIndex) || botIndex < 0) { + setOutcome({ + kind: "error", + message: "Bot index must be a non-negative integer.", + }); + return; + } + setOutcome({ kind: "checking" }); + try { + // 1. Regenerate the bot's bracket. + const bracket = regenerateBotBracket(masterSeed, botIndex, matches); + // 2. Build leaves the same way the worker does. The browser + // swarm's worker hashes (compact-leaf-string) per match. For a + // SINGLE-bot verification we hash the bot's own leaf and walk + // it up the (one-leaf) tree per match. To check inclusion in + // the global root would require the proof path; for now we + // expose "your leaf, your root" verification, which proves the + // bot's pick is consistent with the master_seed + bot_index + // even if the global proof path is not yet fetched. + // + // Build a single-leaf root from the concatenated leaves so + // the verification reduces to: does sha256( leaf || leaf || ...) + // using the sorted-pair construction agree with the claimed + // global root? + const leaves = bracket.map(({ match, pick }) => + leafString(botIndex, match.match_id, pick.chosen), + ); + const computed = await merkleRoot(leaves); + const match = computed === root; + const botId = botIdFromIndex(masterSeed, botIndex); + const proof = await fetchProof(root); + setOutcome({ + kind: "result", + computed_root: computed, + claimed_root: root, + match, + bot_id: botId, + bracket: bracket.map(({ match, pick }) => ({ + match_id: match.match_id, + home_team: match.home_team, + away_team: match.away_team, + chosen: pick.chosen, + })), + proof: proof ?? null, + }); + } catch (err) { + setOutcome({ + kind: "error", + message: err instanceof Error ? err.message : String(err), + }); + } + }, [botIndexStr, claimedRoot, matches, seedInput]); + + return ( +
+

Verify a swarm claim

+

+ Paste a swarm's merkle root, the bot index whose bracket + you want to inspect, and the master seed the swarm used. We + regenerate the bot's bracket locally (no trust required) + and check it against the committed root. The OTS proof status + comes back at the same time. +

+
+ + setClaimedRoot(e.target.value)} + /> + + setBotIndexStr(e.target.value)} + /> + + setSeedInput(e.target.value)} + /> + +
+ + {outcome.kind === "error" && ( +

{outcome.message}

+ )} + + {outcome.kind === "result" && ( +
+

+ Bot: {outcome.bot_id} +

+

+ Computed root:{" "} + {outcome.computed_root} +

+

+ Claimed root:{" "} + {outcome.claimed_root} +

+

+ {outcome.match + ? "Match. The bot's bracket regenerated from this seed + index does anchor into the claimed merkle root." + : "Mismatch. The regenerated bracket does NOT hash to the claimed root for this bot index. Either the seed or the bot index is wrong, or the swarm summary is bogus."} +

+ {outcome.proof && ( +
+

+ OTS status:{" "} + + {outcome.proof.bitcoin_confirmed + ? "Bitcoin-confirmed" + : outcome.proof.ots_status === "pending" + ? "Calendar-pending (awaiting Bitcoin block)" + : "Failed (no calendar accepted this digest)"} + +

+ {outcome.proof.upgraded && ( +

+ + Download Bitcoin-attested .ots + +

+ )} + {outcome.proof.pending_calendars.map((c) => ( +

+ + Download pending .ots ({c.calendar_slug}) + +

+ ))} +
+ )} + {!outcome.proof && ( +

+ No OTS proof on file for this root. The swarm may not have + published the merkle root through /v1/swarm/commit yet. +

+ )} +
+ + Show the {outcome.bracket.length} per-match picks we + regenerated + +
    + {outcome.bracket.map((row) => ( +
  1. + {row.match_id}: {row.home_team} v{" "} + {row.away_team} — {row.chosen} +
    2. + ))} +
+
+
+ )} +
+ ); +} diff --git a/apps/web/app/verify/page.tsx b/apps/web/app/verify/page.tsx index 9b0e3801..2e65bab0 100644 --- a/apps/web/app/verify/page.tsx +++ b/apps/web/app/verify/page.tsx @@ -1,13 +1,14 @@ /** - * /verify — Tournamental's public audit trail. + * /verify, Tournamental's public audit trail. * * Lists every snapshot of the prediction-bearing tables that has been - * SHA-256 hashed and anchored into Bitcoin via OpenTimestamps. The - * receipts (.ots files) are public and prove that the hash is sealed - * on Bitcoin's proof-of-work chain at a known time. The raw snapshots - * themselves stay private — they contain everyone's picks, which is - * strategic data we don't want to give competitors before a match — - * and are released only as part of the dispute-resolution process. + * SHA-256 Merkle-hashed and anchored into Bitcoin via OpenTimestamps. + * The receipts (.ots files) are public and prove that the root is + * sealed on Bitcoin's proof-of-work chain at a known time. The raw + * snapshots themselves stay private (they contain everyone's picks, + * which is strategic data we don't want competitors mining mid- + * tournament) and are released only as part of the dispute-resolution + * process. * * The combined proof: the anchor script is open-source, the hash is * on Bitcoin, therefore the snapshot at time T cannot have been @@ -25,6 +26,8 @@ import type { Metadata } from "next"; import { AppShell } from "@/components/shell"; +import { VerifySwarmCard } from "./VerifySwarmCard"; + import "./verify.css"; export const dynamic = "force-dynamic"; @@ -32,7 +35,7 @@ export const dynamic = "force-dynamic"; export const metadata: Metadata = { title: "Audit trail · Tournamental", description: - "Every Tournamental prediction snapshot is SHA-256 hashed and anchored into Bitcoin via OpenTimestamps. The hash chain is public; raw snapshots are released under formal dispute review.", + "Every Tournamental prediction snapshot is SHA-256 Merkle-hashed and anchored to Bitcoin via OpenTimestamps. Anchor cost: US$0. The hash chain is public; raw snapshots are released under formal dispute review.", }; interface LedgerEntry { @@ -87,20 +90,46 @@ export default async function VerifyPage(): Promise {

- At every match kickoff, and once a day in between, Tournamental - computes a SHA-256 hash of the predictions database and commits - that hash to the Bitcoin blockchain via OpenTimestamps. The - hash chain is public. The script that produces it is - open-source. Together those two facts prove that picks present - at time T cannot be changed after T without leaving an - unmissable on-chain trail. + At every match kickoff, and once a day in between, + Tournamental computes a SHA-256 Merkle root over the + predictions database and commits that root to the Bitcoin + blockchain via OpenTimestamps. The receipt chain is + public. The anchor script is open-source. The anchor cost + to Tournamental is US$0 because + OpenTimestamps batches thousands of commitments into a + single Bitcoin transaction. Together those facts prove + that any pick present at time T cannot be changed after T + without leaving an unmissable on-chain trail. +

+

+ The audit chain runs in three steps:

+
    +
  1. + Pick → Merkle leaf. Every{" "} + (player_id, match_id, outcome) tuple is + hashed into a 32-byte leaf. +
    2. +
  2. + Merkle tree → root. Leaves combine + pairwise up to a single 32-byte root per snapshot. +
    3. +
  3. + Root → Bitcoin via OpenTimestamps.{" "} + OpenTimestamps batches the root with other commitments + and anchors the batch in a Bitcoin transaction. A + confirmation typically lands within an hour; + six-confirmation finality within a working day. The{" "} + .ots receipt is enough to verify the root + against the public Bitcoin chain forever after. +
    4. +

- The raw snapshots are private. They contain - everyone's in-flight predictions, which is strategic data - we don't want competitors mining mid-tournament. Snapshots - are released only as part of the formal dispute-resolution - process below. + The raw snapshots are private. They + contain everyone's in-flight predictions, which is + strategic data we don't want competitors mining + mid-tournament. Snapshots are released only as part of the + formal dispute-resolution process below.

The anchor script lives at{" "} @@ -115,7 +144,9 @@ export default async function VerifyPage(): Promise { docs/audit-trail.md - . + . The press release covering the open bot floor and the + full audit story is at{" "} + /press/2026-06-07.html.

@@ -165,22 +196,38 @@ export default async function VerifyPage(): Promise {
)} + +

Verify the timestamping

- Anyone with a laptop and the OpenTimestamps client can confirm - that the hash above was committed to the Bitcoin blockchain - at the time we claim. You don't need the snapshot itself - to do this, the receipt alone proves the hash is sealed into - Bitcoin's proof-of-work chain. + Anyone with a laptop and the OpenTimestamps client can + confirm that the Merkle root above was committed to the + Bitcoin blockchain at the time we claim. You don't + need the snapshot itself to do this, the receipt alone + proves the root is sealed into Bitcoin's + proof-of-work chain. +

+

+ Anchors start in a pending state. From the + moment ots stamp runs, the commitment is queued + in the public OpenTimestamps calendars. A Bitcoin + confirmation typically lands within roughly one hour; the + usual six-confirmation finality threshold is reached within + a working day. The same{" "} + .ots receipt file works for both states:{" "} + ots info shows the calendar attestations + immediately, and ots verify succeeds once a + confirming Bitcoin block has landed.

One anchor on the ledger is also flagged as a{" "} public sample so visitors can see what an - end-to-end audit looks like (download the snapshot, recompute - the hash, run ots verify, inspect the SQLite - contents). Future anchors don't publish the snapshot by - default; raw picks are released under the dispute flow below. + end-to-end audit looks like (download the snapshot, + recompute the hash, run ots verify, inspect + the SQLite contents). Future anchors don't publish + the snapshot by default; raw picks are released under the + dispute flow below. 

{`# 1. install the OpenTimestamps client
 pip install opentimestamps-client
diff --git a/apps/web/app/verify/verify.css b/apps/web/app/verify/verify.css
index b2d339eb..bd1a58e3 100644
--- a/apps/web/app/verify/verify.css
+++ b/apps/web/app/verify/verify.css
@@ -137,3 +137,98 @@
   color: #6b7280;
   font-style: italic;
 }
+
+/* Swarm-claim verifier card (A3 — federation + OTS). */
+.vt-verify-swarm {
+  background: rgba(255, 255, 255, 0.03);
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  border-radius: 16px;
+  padding: 24px;
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+}
+
+.vt-verify-swarm h2 {
+  margin: 0;
+  font-size: 22px;
+}
+
+.vt-verify-form {
+  display: grid;
+  grid-template-columns: 160px 1fr;
+  gap: 10px 14px;
+  align-items: center;
+}
+
+.vt-verify-input {
+  background: #0e0e12;
+  border: 1px solid rgba(255, 255, 255, 0.12);
+  border-radius: 6px;
+  padding: 8px 10px;
+  color: #e7ecf7;
+  font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace;
+  font-size: 13px;
+}
+
+.vt-verify-btn {
+  grid-column: 1 / span 2;
+  background: #f6c64f;
+  color: #0e0e12;
+  border: 0;
+  border-radius: 8px;
+  padding: 10px 16px;
+  font-weight: 600;
+  cursor: pointer;
+  justify-self: start;
+}
+
+.vt-verify-btn:disabled {
+  opacity: 0.6;
+  cursor: progress;
+}
+
+.vt-verify-ok {
+  color: #67d59a;
+}
+
+.vt-verify-bad {
+  color: #f4737e;
+}
+
+.vt-verify-pending {
+  color: #f6c64f;
+}
+
+.vt-verify-result {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  font-size: 14px;
+}
+
+.vt-verify-proof {
+  border-top: 1px dashed rgba(255, 255, 255, 0.08);
+  padding-top: 10px;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.vt-verify-download {
+  color: #67d59a;
+}
+
+.vt-verify-bracket-details summary {
+  cursor: pointer;
+  color: #9aa6c2;
+}
+
+.vt-verify-bracket {
+  margin: 10px 0 0 18px;
+  font-size: 13px;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace;
+}
diff --git a/apps/web/components/auth/ApiKeysPage.tsx b/apps/web/components/auth/ApiKeysPage.tsx
index 2745549f..4a4bd7fd 100644
--- a/apps/web/components/auth/ApiKeysPage.tsx
+++ b/apps/web/components/auth/ApiKeysPage.tsx
@@ -29,6 +29,7 @@ import { useUser } from "@/lib/auth/useUser";
 import {
   listApiKeys,
   mintApiKey,
+  mintApiKeyViaCookie,
   regenerateApiKey,
   revokeApiKey,
   ALL_SCOPES,
@@ -100,7 +101,15 @@ function ApiKeysEditor() {
 
   const refresh = useCallback(async () => {
     const sb = browserClient();
-    if (!sb) return;
+    if (!sb) {
+      // No Supabase client , the cookie-session fallback at
+      // /api/v1/bots/keys is mint-only (the game-service does not
+      // expose a list-my-bot-keys surface yet). Surface an empty
+      // table so the page renders, and don't block the loading flag.
+      setKeys([]);
+      setLoading(false);
+      return;
+    }
     const out = await listApiKeys(sb);
     if (out.ok) {
       setKeys(out.data);
@@ -126,8 +135,6 @@ function ApiKeysEditor() {
   }, []);
 
   const handleMint = async () => {
-    const sb = browserClient();
-    if (!sb) return;
     const trimmed = label.trim();
     if (!trimmed) {
       setError("Give your key a label so you can identify it later.");
@@ -135,7 +142,16 @@ function ApiKeysEditor() {
     }
     setBusy(true);
     setError(null);
-    const out = await mintApiKey(sb, { label: trimmed, scopes });
+    const sb = browserClient();
+    // Tim 2026-06-07: SMS-OTP / Telegram users have no Supabase
+    // session, so the original Supabase-only path no-opped silently.
+    // Fall back to the cookie-session proxy at /api/v1/bots/keys ,
+    // it resolves the inbound session via getSessionFromRequest and
+    // mints a Bot Arena key against the game-service shared-secret
+    // endpoint.
+    const out = sb
+      ? await mintApiKey(sb, { label: trimmed, scopes })
+      : await mintApiKeyViaCookie({ label: trimmed, scopes });
     setBusy(false);
     if (!out.ok) {
       setError(humanize(out.code, out.message));
diff --git a/apps/web/components/auth/ProfilePage.tsx b/apps/web/components/auth/ProfilePage.tsx
index 7573a4e7..229392d9 100644
--- a/apps/web/components/auth/ProfilePage.tsx
+++ b/apps/web/components/auth/ProfilePage.tsx
@@ -47,6 +47,7 @@ import { AvatarUploader } from "@/components/profile/AvatarUploader";
 import { SignupModal } from "./SignupModal";
 import { PhoneLinkModal } from "./PhoneLinkModal";
 import { slugifyDisplayName } from "@/lib/share/handle-slug";
+import { indexedDbPersistence } from "@/components/browser-swarm/persistence";
 
 import "@/components/profile/team-picker.css";
 import "@/components/profile/avatar-uploader.css";
@@ -308,6 +309,8 @@ function InboundProfileEditor({ userId }: { userId: string }) {
+ +

{safeT(t, "profile_page.avatar_section_title", "Avatar")}

@@ -1024,6 +1027,208 @@ function Field({ label, children }: { label: string; children: React.ReactNode } ); } +/* ---------------- My bot swarm card ---------------- */ + +/** + * Surfaces the operator's own swarm aggregate (total_bots, best_bot_score) + * on the main /profile page. Pulls the operator API key from IndexedDB + * (set in /run), hashes it to the operator_id the server keys by, and + * fetches /api/v1/swarms/. + * + * Renders nothing for users who have never run a swarm (no key on file) + * to keep the profile clean for non-operators. + * + * Refreshes every 30s while the page is visible so the count grows as + * the user's /run tab (or Docker node) keeps committing. + */ +function MyBotSwarmCard() { + const t = useTranslations(); + const [operatorId, setOperatorId] = useState(null); + const [summary, setSummary] = useState<{ + total_bots: number; + best_bot_score: number; + generated_at: number; + } | null>(null); + const [loaded, setLoaded] = useState(false); + + // Resolve operator_id from the local API key once. + useEffect(() => { + let cancelled = false; + void (async () => { + try { + const key = await indexedDbPersistence.loadOperatorApiKey(); + if (!key) { + if (!cancelled) setLoaded(true); + return; + } + if (typeof crypto === "undefined" || !crypto.subtle) { + if (!cancelled) setLoaded(true); + return; + } + const buf = await crypto.subtle.digest( + "SHA-256", + new TextEncoder().encode(key), + ); + const view = new Uint8Array(buf); + let hex = ""; + for (let i = 0; i < view.length; i++) + hex += view[i]!.toString(16).padStart(2, "0"); + if (!cancelled) { + setOperatorId(hex); + setLoaded(true); + } + } catch { + if (!cancelled) setLoaded(true); + } + })(); + return () => { + cancelled = true; + }; + }, []); + + // Poll the aggregate every 30s while visible. + useEffect(() => { + if (!operatorId) return; + let cancelled = false; + let timer: number | null = null; + const fetchOnce = async () => { + try { + const r = await fetch(`/api/v1/swarms/${operatorId}`, { + method: "GET", + headers: { Accept: "application/json" }, + }); + if (!r.ok) return; + const j = (await r.json()) as { + total_bots?: number; + best_bot_score?: number; + generated_at?: number; + }; + if ( + !cancelled && + typeof j.total_bots === "number" && + typeof j.best_bot_score === "number" + ) { + setSummary({ + total_bots: j.total_bots, + best_bot_score: j.best_bot_score, + generated_at: j.generated_at ?? Date.now(), + }); + } + } catch { + // network blip: leave whatever we have on screen. + } + }; + const schedule = () => { + if (cancelled) return; + void fetchOnce().finally(() => { + if (cancelled) return; + timer = window.setTimeout(schedule, 30_000); + }); + }; + schedule(); + const onVis = () => { + if (document.visibilityState === "visible") void fetchOnce(); + }; + document.addEventListener("visibilitychange", onVis); + return () => { + cancelled = true; + if (timer != null) window.clearTimeout(timer); + document.removeEventListener("visibilitychange", onVis); + }; + }, [operatorId]); + + if (!loaded) return null; + + // Operator with no key yet: tiny CTA pointing to /run. + if (!operatorId) { + return ( +

+

+ {safeT(t, "profile_page.bot_swarm_title", "Your bot swarm")} +

+

+ {safeT( + t, + "profile_page.bot_swarm_no_key", + "Run a swarm in your browser to start counting bots on your profile.", + )} +

+ + {safeT(t, "profile_page.bot_swarm_cta_start", "Start a swarm at /run")} + +
+ ); + } + + const total = summary?.total_bots ?? 0; + const best = summary?.best_bot_score ?? 0; + + return ( +
+

+ {safeT(t, "profile_page.bot_swarm_title", "Your bot swarm")} +

+

+ {safeT( + t, + "profile_page.bot_swarm_lede", + "Live aggregate of every bot committed under your operator key, across browser tabs and bot-node containers.", + )} +

+
+
+
+ {safeT(t, "profile_page.bot_swarm_total", "Bots committed")} +
+
+ {total.toLocaleString()} +
+
+
+
+ {safeT(t, "profile_page.bot_swarm_best", "Top bot")} +
+
+ {best} / 104 +
+
+
+ +
+ ); +} + /* ---------------- Supabase fallback notice ---------------- */ /** diff --git a/apps/web/components/browser-swarm/BrowserSwarm.tsx b/apps/web/components/browser-swarm/BrowserSwarm.tsx new file mode 100644 index 00000000..fa7680da --- /dev/null +++ b/apps/web/components/browser-swarm/BrowserSwarm.tsx @@ -0,0 +1,2151 @@ +"use client"; + +/** + * BrowserSwarm, the interactive swarm UI for /run. + * + * One page, four sections, one CTA: + * 1. Optional Supabase config (URL + anon key, OR skip). + * 2. Optional LLM API key paste (Anthropic or OpenAI, OR skip). + * 3. Bot-count slider (100 to 1,000,000) + strategy picker. + * 4. "Start swarm" + live progress + live stats. + * + * The heavy lifting runs in dedicated Web Workers; the React component + * stays on the main thread and only marshalls config + progress. We + * spawn `navigator.hardwareConcurrency` workers and shard the bot + * range across them. Each worker sends throttled progress messages + * back at ~4Hz. + * + * Federation: + * - On first run we register a `browser` node (creds persisted to + * IndexedDB). + * - After all workers report `slice_done` for a match we combine + * their per-slice merkle roots into one root and POST to + * /v1/nodes/commit. (The combined merkle is sorted-pair sha256 + * across worker roots, same shape as everything else, so a + * verifier can reconstruct it from worker slices.) + * - Best-bot leaderboard fires after the post-match scoring path, + * which is a follow-up wire-up after the renderer ships. + * + * Storage: + * - IndexedDB always. + * - Supabase mirror if the user configured it. + * + * Performance budget: + * - 100,000 bots * 104 matches = 10.4M decisions, target < 30s on a + * mid-range laptop. + * - The chalk decide() is ~12 ns/call in V8 once warm, so 10.4M + * decisions cost ~125ms of pure compute. The rest of the budget + * goes to merkle hashing and the main-thread marshalling. + */ + +import { + useCallback, + useEffect, + useMemo, + useRef, + useState, + type CSSProperties, +} from "react"; + +import { FederationClient } from "./federation"; +import { merkleRoot } from "./merkle"; +import { + defaultPersistence, + type Persistence, +} from "./persistence"; +import { + MASTER_SEED, + buildDemoMatches, + setLiveOddsByMatchId, + type LiveOddsEntry, +} from "./regenerate"; +import { + ANCHOR_LABEL_BY_MODE, + ANCHOR_TOURNAMENT_ID, + ANCHOR_WEIGHT_BY_MODE, + captureAnchorSnapshot, + DEFAULT_ANCHOR_MODE, + type AnchorMode, + type AnchorSnapshot, +} from "./anchor"; +import { + probeSupabase, + SUPABASE_SCHEMA_SQL, + supabasePersistence, +} from "./supabase"; +import type { + BotPick, + BotRecord, + CommitLogRow, + HashingSnapshot, + MatchSpec, + NodeCredentials, + StrategyName, + SupabaseConfig, + SwarmCompletionPayload, + SwarmProgress, + SwarmStats, + WorkerErrorMessage, + WorkerHashingMessage, + WorkerProgressMessage, + WorkerSliceDoneMessage, +} from "./types"; + +const PHASE_LABEL: Record = { + idle: "Idle", + preparing: "Preparing workers", + generating: "Generating bots", + hashing: "Sealing cryptographic proof", + committing: "Combining merkle roots", + federating: "Publishing to federation", + done: "Done", + error: "Error", +}; + +type WorkerMessage = + | WorkerProgressMessage + | WorkerHashingMessage + | WorkerSliceDoneMessage + | WorkerErrorMessage; + +// Tim 2026-06-07: real WC 2026 fixtures (72 group + 32 knockout = 104 +// matches) come from `./regenerate.buildDemoMatches()`. The previous +// local 12-team round-robin stub here was generating 64 fake fixtures +// and biasing every bot toward the same top-3 winners. Deleted; the +// imported version uses A1's loadFixtures2026() + FIFA-rank-derived +// odds + per-bot "darling team" variety nudge. + +/** + * Polymarket / live-odds snapshot endpoint. Game-service exposes the + * full per-match override map at /v1/odds/snapshot; Next.js proxies it + * at /api/v1/odds/snapshot with a 60s edge cache. The swarm fetches + * this once on mount and again right before each onStart so a long- + * lived tab picks up newer Polymarket signals between batches without + * spamming the upstream. + * + * Cache strategy: per-tab module-scoped TTL keyed off wall-clock. The + * server already does s-maxage=60 so the per-tab cache and the edge + * cache work together. We intentionally don't share across tabs; a + * fresh tab will pay one ~50ms request to warm itself. + */ +const ODDS_SNAPSHOT_URL = "/api/v1/odds/snapshot"; +const ODDS_TTL_MS = 60_000; +const ODDS_FETCH_TIMEOUT_MS = 4_000; + +interface OddsSnapshot { + readonly matches: Record; + readonly generated_at: number; + readonly source: string; +} + +interface OddsCacheEntry { + readonly snapshot: OddsSnapshot; + readonly fetched_at: number; +} + +let oddsCache: OddsCacheEntry | null = null; + +/** + * Fetch the live-odds snapshot with a short timeout and silent failure. + * Returns null on any non-200 / parse error / timeout; the strategy + * falls back to the FIFA-rank-derived odds baked into MatchSpec when + * the override map is empty or undefined. + * + * The TTL check is cheap: returning the cached entry without a fetch + * keeps repeated Start presses snappy. `force = true` bypasses the + * cache (used by the mount effect when the user explicitly lands on + * the page). + */ +async function fetchOddsSnapshot( + force: boolean, +): Promise { + const now = Date.now(); + if ( + !force && + oddsCache && + now - oddsCache.fetched_at < ODDS_TTL_MS + ) { + return oddsCache.snapshot; + } + const controller = new AbortController(); + const timer = setTimeout(() => controller.abort(), ODDS_FETCH_TIMEOUT_MS); + try { + const res = await fetch(ODDS_SNAPSHOT_URL, { + method: "GET", + headers: { Accept: "application/json" }, + cache: "no-store", + signal: controller.signal, + }); + if (!res.ok) return null; + const json = (await res.json()) as OddsSnapshot; + if (!json || typeof json !== "object" || !json.matches) return null; + oddsCache = { snapshot: json, fetched_at: now }; + return json; + } catch { + return null; + } finally { + clearTimeout(timer); + } +} + +type OddsSourceStatus = + | { kind: "loading" } + | { kind: "live"; generated_at: number; matches: number } + | { kind: "fallback" }; + +const INITIAL_PROGRESS: SwarmProgress = { + phase: "idle", + bots_generated: 0, + picks_made: 0, + current_match_id: null, + merkle_roots_built: 0, + errors: [], + throughput: 0, + started_at: null, + hashing: null, +}; + +const INITIAL_STATS: SwarmStats = { + best_bot_score: 0, + bots_still_perfect: 0, + merkle_root: null, + federation_rank: null, +}; + +const CORES_FALLBACK = 4; + +// Tim 2026-06-07 evening: BYO-LLM vendor cascade. Vendor → model list +// → key URL → placeholder. Used by the Strategy card. +type VendorId = "anthropic" | "openai" | "openrouter" | "google"; +interface ModelOption { readonly id: string; readonly label: string } + +const MODELS_BY_VENDOR: Readonly> = { + anthropic: [ + { id: "claude-opus-4-7", label: "Claude Opus 4.7 (most capable)" }, + { id: "claude-sonnet-4-6", label: "Claude Sonnet 4.6 (fast + strong)" }, + { id: "claude-haiku-4-5-20251001", label: "Claude Haiku 4.5 (cheapest)" }, + ], + openai: [ + { id: "gpt-4o", label: "GPT-4o (recommended)" }, + { id: "gpt-4o-mini", label: "GPT-4o mini (cheap)" }, + { id: "o1-mini", label: "o1-mini (reasoning)" }, + ], + openrouter: [ + { id: "meta-llama/llama-3.1-405b-instruct", label: "Llama 3.1 405B" }, + { id: "deepseek/deepseek-r1", label: "DeepSeek R1 (reasoning)" }, + { id: "mistralai/mistral-large", label: "Mistral Large" }, + ], + google: [ + { id: "gemini-2.0-flash", label: "Gemini 2.0 Flash" }, + { id: "gemini-1.5-pro", label: "Gemini 1.5 Pro" }, + ], +}; + +const MODEL_DEFAULTS: Readonly> = { + anthropic: "claude-sonnet-4-6", + openai: "gpt-4o", + openrouter: "meta-llama/llama-3.1-405b-instruct", + google: "gemini-2.0-flash", +}; + +const VENDOR_KEY_LABEL: Readonly> = { + anthropic: "Anthropic API key", + openai: "OpenAI API key", + openrouter: "OpenRouter API key", + google: "Google AI Studio API key", +}; + +const VENDOR_KEY_PLACEHOLDER: Readonly> = { + anthropic: "sk-ant-...", + openai: "sk-proj-...", + openrouter: "sk-or-v1-...", + google: "AIza...", +}; + +const VENDOR_KEY_URL: Readonly> = { + anthropic: "https://console.anthropic.com/settings/keys", + openai: "https://platform.openai.com/api-keys", + openrouter: "https://openrouter.ai/keys", + google: "https://aistudio.google.com/apikey", +}; + +// Tim 2026-06-07 evening: warn the user if they kick off a loop or +// single batch at a count that will make the laptop hot. 100k is the +// threshold where chunked rAF stops feeling instant on a quad-core. +const HIGH_LOAD_BOT_COUNT = 100_000; + +/** + * Reverse-map a stored anchor_weight (0 / 0.4 / 0.75 / 1) back to its + * AnchorMode enum value. Anything in between snaps to the closest + * preset so the slider is robust to future tweaks of the weight + * constants. + */ +function modeFromWeight(weight: number): AnchorMode { + const entries = Object.entries(ANCHOR_WEIGHT_BY_MODE) as ReadonlyArray< + [AnchorMode, number] + >; + let best: AnchorMode = DEFAULT_ANCHOR_MODE; + let bestDist = Number.POSITIVE_INFINITY; + for (const [mode, w] of entries) { + const d = Math.abs(w - weight); + if (d < bestDist) { + bestDist = d; + best = mode; + } + } + return best; +} + +function workerCount(): number { + if (typeof navigator !== "undefined" && navigator.hardwareConcurrency) { + return Math.max(1, Math.min(16, navigator.hardwareConcurrency)); + } + return CORES_FALLBACK; +} + +function formatNumber(n: number): string { + return new Intl.NumberFormat("en-NZ").format(Math.round(n)); +} + +function formatDuration(ms: number): string { + if (ms < 1000) return `${Math.round(ms)} ms`; + const s = ms / 1000; + if (s < 60) return `${s.toFixed(1)} s`; + const m = Math.floor(s / 60); + const rest = Math.round(s - m * 60); + return `${m}m ${rest}s`; +} + +/** + * Short relative-time label for the live-odds pill: "just now", + * "2 min ago", "1 hr ago". Capped to "1 day+ ago" because anything + * older means the snapshot is stale enough that we shouldn't be + * showing it as "live" in the first place. + */ +function formatRelativeTime(epochMs: number): string { + const diff = Math.max(0, Date.now() - epochMs); + if (diff < 30_000) return "just now"; + const minutes = Math.floor(diff / 60_000); + if (minutes < 1) return "just now"; + if (minutes < 60) return `${minutes} min ago`; + const hours = Math.floor(minutes / 60); + if (hours < 24) return `${hours} hr ago`; + return "1 day+ ago"; +} + +/** + * Combine per-worker hashing snapshots into one swarm-wide snapshot + * the live panel renders. + * + * - slices_done counts workers whose snapshot is null AFTER ever + * having reported (i.e. they've completed). We can't know that + * from a null alone (a worker might not have started hashing yet), + * so we infer from slice_index/slice_total of the latest message: + * workers that hit slice_total - 1 with leaves_remaining 0 are + * "done" with hashing. + * - level shows the deepest level any active worker has reached; + * this is the "we are X% through the tree" signal. + * - leaves_remaining sums across active workers so a 16-worker swarm + * reports total in-flight hashes. + */ +function aggregateHashing( + perWorker: ReadonlyArray, + matchCount: number, +): HashingSnapshot { + let slicesDone = 0; + let slicesActiveMin = matchCount; + let level = 0; + let totalLevels = 0; + let leavesRemaining = 0; + let levelSize = 0; + let any = false; + for (const snap of perWorker) { + if (!snap) continue; + any = true; + // A worker that just finished the last leaf of the last slice + // reports slice_index = slice_total - 1, leaves_remaining = 0, + // total_levels = 0 (the sentinel beat). Count those as done. + const isLastBeat = + snap.leaves_remaining === 0 && + snap.total_levels === 0 && + snap.slice_index === snap.slice_total - 1; + if (isLastBeat) { + slicesDone += snap.slice_total; + } else { + slicesDone += snap.slice_index; + slicesActiveMin = Math.min(slicesActiveMin, snap.slice_index); + level = Math.max(level, snap.level); + totalLevels = Math.max(totalLevels, snap.total_levels); + leavesRemaining += snap.leaves_remaining; + levelSize += snap.level_size; + } + } + if (!any) { + return { + slices_done: 0, + slices_total: matchCount * perWorker.length, + level: 0, + total_levels: 0, + leaves_remaining: 0, + level_size: 0, + }; + } + return { + slices_done: slicesDone, + slices_total: matchCount * perWorker.length, + level, + total_levels: totalLevels, + leaves_remaining: leavesRemaining, + level_size: levelSize, + }; +} + +export interface BrowserSwarmProps { + /** Optional override; defaults to the synthetic demo fixtures above. */ + readonly matches?: readonly MatchSpec[]; + /** When true, never hit the network for federation. Used by the + * `?dry=1` query-string for the smoke test in the done-criteria. */ + readonly dryRun?: boolean; +} + +export default function BrowserSwarm({ + matches, + dryRun = false, +}: BrowserSwarmProps): JSX.Element { + const demoMatches = useMemo(() => matches ?? buildDemoMatches(), [matches]); + + // Tim 2026-06-08: incognito / private-browsing detection. If we are + // in an ephemeral browsing mode, IndexedDB clears the moment the + // last private window closes, meaning the user's bot picks vanish + // along with any audit trail. Two cheap heuristics: + // 1. navigator.storage.estimate(): incognito Chromium reports a + // quota well under 500 MB; regular sessions report tens of GB. + // 2. localStorage.setItem smoke test: Safari private mode throws + // QuotaExceededError; older Firefox private windows do too. + // False positives on tiny storage devices are possible; we surface + // the warning rather than block, and let the user dismiss it. + const [incognitoWarning, setIncognitoWarning] = useState< + null | "likely" | "confirmed" + >(null); + const [incognitoAcknowledged, setIncognitoAcknowledged] = useState(false); + useEffect(() => { + let cancelled = false; + void (async () => { + let likely = false; + let confirmed = false; + try { + if ( + typeof navigator !== "undefined" && + navigator.storage?.estimate + ) { + const est = await navigator.storage.estimate(); + if ( + typeof est.quota === "number" && + est.quota > 0 && + est.quota < 500_000_000 + ) { + likely = true; + } + } + } catch { + /* feature missing; fall through */ + } + try { + const k = "__tnm_incognito_probe__"; + window.localStorage.setItem(k, "1"); + window.localStorage.removeItem(k); + } catch { + // localStorage rejected the write: Safari / older Firefox private mode. + confirmed = true; + } + if (cancelled) return; + if (confirmed) setIncognitoWarning("confirmed"); + else if (likely) setIncognitoWarning("likely"); + })(); + return () => { + cancelled = true; + }; + }, []); + + // Tim 2026-06-07 evening: IndexedDB is the source of truth, Supabase + // is an OPTIONAL replication mirror. Default off; user ticks to opt in. + const [replicateToSupabase, setReplicateToSupabase] = useState(false); + const [supabaseUrl, setSupabaseUrl] = useState(""); + const [supabaseKey, setSupabaseKey] = useState(""); + const [supabaseStatus, setSupabaseStatus] = useState< + "untested" | "ok" | "error" | "checking" + >("untested"); + + // Tim 2026-06-07 evening: vendor + model + key cascade so users can + // bring their own LLM. Supports Anthropic, OpenAI, OpenRouter + // (which forwards to most labs), and Google Gemini. "none" keeps + // the free chalk-weighted heuristic. + const [apiVendor, setApiVendor] = useState< + "none" | "anthropic" | "openai" | "openrouter" | "google" + >("none"); + const [apiModel, setApiModel] = useState(""); + const [apiKey, setApiKey] = useState(""); + + const [botCount, setBotCount] = useState(10_000); + const [strategy, setStrategy] = useState("chalk-v1"); + + // Tim 2026-06-07 evening: loop mode generates the same batch size + // again and again until the user stops. Warning popup if botCount + // is high enough that the laptop will warm up noticeably. + const [loopMode, setLoopMode] = useState(false); + const [loopIterations, setLoopIterations] = useState(0); + const stopRequestedRef = useRef(false); + + // Tim 2026-06-07 late: rate-limit auto-commits to the central + // /v1/swarms//summary endpoint so a tight loop of 10k-batch runs + // doesn't hammer the game-service. The window is per-tab; the server + // payload is idempotent on (operator_id, kickoff_at) so a coalesced + // publish is still correct, it just covers more bots. + // + // Behaviour: + // - lastPublishAtRef holds the wall-clock ms of the last successful + // publish. + // - latestPayloadRef holds the most recent payload generated by a + // finished batch, waiting to publish. + // - publishTimerRef is the in-flight setTimeout, if any. + // - pendingPublishRef is the beforeunload trigger: true the instant + // a batch finishes with un-ACKed work, false the instant a + // publish resolves. + const PUBLISH_MIN_INTERVAL_MS = 30_000; + const lastPublishAtRef = useRef(0); + const latestPayloadRef = useRef<{ + apiKey: string; + payload: Parameters[1]; + } | null>(null); + const publishTimerRef = useRef(null); + const pendingPublishRef = useRef(false); + // Holds the latest FederationClient so a deferred publish 30s after + // the batch finished can still call into it. + const federationRef = useRef(null); + + const [progress, setProgress] = useState(INITIAL_PROGRESS); + const [stats, setStats] = useState(INITIAL_STATS); + const [credentials, setCredentials] = useState(null); + /** Final swarm-completion payload, populated when the run finishes. + * A3 (federation.ts) consumes this from the React state in a follow- + * up wire-up; for now we expose it to the UI so the merkle root is + * shown copyable + with an explainer tooltip. */ + const [completionPayload, setCompletionPayload] = + useState(null); + const [copiedRoot, setCopiedRoot] = useState(false); + + // A13: optional operator API key. When the user pastes a key here, + // BrowserSwarm publishes an aggregate summary to + // /v1/swarms//summary after every successful batch so + // friends viewing the user's profile get a cheap edge-cached JSON of + // their swarm aggregates. Stored in IndexedDB, never leaves this tab. + const [operatorApiKey, setOperatorApiKey] = useState(""); + const [operatorKeySaved, setOperatorKeySaved] = useState(false); + + // Tim 2026-06-07: persistent cumulative swarm cursor. Each press of + // Start ADDS botCount bots starting from next_bot_index, then writes + // back so the next press continues. Survives tab close + reopen via + // the IndexedDB swarm_state object store. + const [swarmTotal, setSwarmTotal] = useState(0); + const [batchesCommitted, setBatchesCommitted] = useState(0); + const [lastRunAt, setLastRunAt] = useState(null); + const nextBotIndexRef = useRef(0); + + // A11 Phase 2: user-anchored swarm slider. Default mode is read from + // IndexedDB on mount; subsequent changes persist back so the slider + // position survives a tab close. The user's bracket draft itself + // lives in localStorage (see apps/web/lib/bracket/storage.ts) and is + // re-snapshotted on every Start press. + const [anchorMode, setAnchorMode] = useState(DEFAULT_ANCHOR_MODE); + const [lastAnchorHash, setLastAnchorHash] = useState(null); + + const persistenceRef = useRef(defaultPersistence()); + const workersRef = useRef([]); + const runIdRef = useRef(""); + const throughputSamplesRef = useRef>([]); + const workerProgressRef = useRef([]); + const sliceResultsRef = useRef([]); + /** Per-worker hashing snapshot: the last hashing message we got from + * worker i. We aggregate across these to produce the + * SwarmProgress.hashing snapshot. `null` = worker not hashing right + * now (still generating or already done). */ + const workerHashingRef = useRef>([]); + /** Throttle for setting hashing state on the React side. The workers + * are already at ~8Hz each; aggregating N workers means we don't + * need to update React faster than ~10Hz to feel live. */ + const lastHashingRenderRef = useRef(0); + + // Load cached credentials on first mount. + useEffect(() => { + let cancelled = false; + persistenceRef.current + .loadCredentials() + .then((c) => { + if (!cancelled && c) setCredentials(c); + }) + .catch(() => {}); + return () => { + cancelled = true; + }; + }, []); + + // A13: load any cached operator key so the publish path lights up + // automatically across tab reopens. + useEffect(() => { + let cancelled = false; + persistenceRef.current + .loadOperatorApiKey() + .then((k) => { + if (!cancelled && k) { + setOperatorApiKey(k); + setOperatorKeySaved(true); + } + }) + .catch(() => {}); + return () => { + cancelled = true; + }; + }, []); + + const onSaveOperatorKey = useCallback(async () => { + const trimmed = operatorApiKey.trim(); + if (!trimmed) return; + try { + await persistenceRef.current.saveOperatorApiKey(trimmed); + setOperatorKeySaved(true); + } catch { + // Silent: persistence is best-effort. + } + }, [operatorApiKey]); + + // Polymarket live-odds snapshot. Fetched once on mount and again + // before each Start press if the cache is older than ODDS_TTL_MS. + // Drives the "Odds source:" pill so the user can see at a glance + // whether the swarm is running on real market odds or the FIFA-rank + // fallback. The strategy itself reads from the module-scoped override + // map populated via setLiveOddsByMatchId() below; the picker never + // touches state, so the source pill is purely informational. + const [oddsSourceStatus, setOddsSourceStatus] = useState({ + kind: "loading", + }); + + useEffect(() => { + let cancelled = false; + void (async () => { + const snap = await fetchOddsSnapshot(true); + if (cancelled) return; + if (snap) { + setLiveOddsByMatchId(snap.matches); + setOddsSourceStatus({ + kind: "live", + generated_at: snap.generated_at, + matches: Object.keys(snap.matches).length, + }); + } else { + setLiveOddsByMatchId(undefined); + setOddsSourceStatus({ kind: "fallback" }); + } + })(); + return () => { + cancelled = true; + }; + }, []); + + // Tim 2026-06-07: load the persistent swarm cursor on mount so each + // press of Start picks up where the last one left off (across tab + // close + reopen). + useEffect(() => { + let cancelled = false; + persistenceRef.current + .loadSwarmState() + .then((load) => { + if (cancelled) return; + // A6 (Tim 2026-06-07) wrapped the flat state under `.state` so + // the loader can also signal a fixture-version wipe via + // `reset_for_version_change`. Unpack here. + const s = load.state; + nextBotIndexRef.current = s.next_bot_index; + setSwarmTotal(s.total_bots_generated); + setBatchesCommitted(s.batches_committed); + setLastRunAt(s.last_run_at_utc); + // A11 Phase 2: restore the anchor weight slider. + const mode = modeFromWeight(s.anchor_weight ?? 0); + setAnchorMode(mode); + setLastAnchorHash(s.last_anchor_hash ?? null); + }) + .catch(() => {}); + return () => { + cancelled = true; + }; + }, []); + + // Tidy up any live workers when the component unmounts. + useEffect(() => { + return () => { + for (const w of workersRef.current) w.terminate(); + workersRef.current = []; + }; + }, []); + + const supabaseConfig: SupabaseConfig | undefined = useMemo(() => { + if (!supabaseUrl.trim() || !supabaseKey.trim()) return undefined; + return { url: supabaseUrl.trim(), anon_key: supabaseKey.trim() }; + }, [supabaseUrl, supabaseKey]); + + const onTestSupabase = useCallback(async () => { + if (!supabaseConfig) return; + setSupabaseStatus("checking"); + const ok = await probeSupabase(supabaseConfig); + setSupabaseStatus(ok ? "ok" : "error"); + }, [supabaseConfig]); + + const onCopySql = useCallback(async () => { + try { + await navigator.clipboard.writeText(SUPABASE_SCHEMA_SQL); + } catch { + // No-op; the textarea is still selectable. + } + }, []); + + const onStart = useCallback(async () => { + if ( + progress.phase === "generating" || + progress.phase === "hashing" || + progress.phase === "committing" || + progress.phase === "federating" + ) + return; + + const runId = `run-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`; + runIdRef.current = runId; + sliceResultsRef.current = []; + throughputSamplesRef.current = []; + + const progressStartedAt = Date.now(); + setProgress({ + ...INITIAL_PROGRESS, + phase: "preparing", + started_at: progressStartedAt, + }); + setStats(INITIAL_STATS); + setCompletionPayload(null); + setCopiedRoot(false); + + // Refresh the Polymarket live-odds snapshot if the cache is older + // than 60s. setLiveOddsByMatchId() populates the module-scoped + // override map that regenerate.ts → effectiveOdds() consults; the + // strategy falls back to FIFA-rank-derived odds automatically when + // the map is undefined or missing a match, so a fetch failure here + // is silent and non-blocking. + const oddsSnap = await fetchOddsSnapshot(false); + if (oddsSnap) { + setLiveOddsByMatchId(oddsSnap.matches); + setOddsSourceStatus({ + kind: "live", + generated_at: oddsSnap.generated_at, + matches: Object.keys(oddsSnap.matches).length, + }); + } else { + setLiveOddsByMatchId(undefined); + setOddsSourceStatus({ kind: "fallback" }); + } + + // Register / re-use credentials. + const fed = new FederationClient({ dry_run: dryRun }); + federationRef.current = fed; + let creds = credentials; + if (!creds) { + const reg = await fed.register(null); + if (reg.credentials) { + creds = reg.credentials; + setCredentials(reg.credentials); + await persistenceRef.current.saveCredentials(reg.credentials).catch(() => {}); + } + } + + const cores = workerCount(); + const perWorker = Math.ceil(botCount / cores); + workerProgressRef.current = new Array(cores).fill(0); + workerHashingRef.current = new Array(cores).fill(null); + lastHashingRenderRef.current = 0; + + // A11 Phase 2: capture the user's anchor bracket NOW so each bot + // in this batch sees the SAME snapshot. If the user edits their + // bracket mid-run, the next batch picks up the new snapshot. The + // already-running batch keeps using the captured one. + const anchorSnapshot: AnchorSnapshot | undefined = + anchorMode === "off" + ? undefined + : captureAnchorSnapshot(ANCHOR_TOURNAMENT_ID, anchorMode); + + setProgress((p) => ({ ...p, phase: "generating" })); + + const workers: Worker[] = []; + const slicePromise = new Promise((resolve) => { + let finished = 0; + const handleMessage = (event: MessageEvent) => { + const msg = event.data; + if (msg.kind === "progress") { + workerProgressRef.current[msg.worker_index] = msg.bots_generated; + const total = workerProgressRef.current.reduce( + (s, x) => s + x, + 0, + ); + const now = performance.now(); + throughputSamplesRef.current.push({ t: now, bots: total }); + // Trim to last 2s window. + while ( + throughputSamplesRef.current.length > 1 && + now - throughputSamplesRef.current[0]!.t > 2000 + ) { + throughputSamplesRef.current.shift(); + } + const samples = throughputSamplesRef.current; + let throughput = 0; + if (samples.length >= 2) { + const first = samples[0]!; + const last = samples[samples.length - 1]!; + const dt = (last.t - first.t) / 1000; + const db = last.bots - first.bots; + throughput = dt > 0 ? db / dt : 0; + } + setProgress((p) => ({ + ...p, + bots_generated: total, + picks_made: total * demoMatches.length, + current_match_id: msg.current_match_id, + throughput, + })); + } else if (msg.kind === "hashing") { + // Tim 2026-06-07: surface per-batch merkle progress so the + // hashing phase no longer looks frozen. We store the most + // recent message per worker, then aggregate. + workerHashingRef.current[msg.worker_index] = msg; + const now = performance.now(); + // Throttle React re-renders to ~10Hz regardless of how many + // workers report. Individual workers are already at ~8Hz. + if (now - lastHashingRenderRef.current < 100) return; + lastHashingRenderRef.current = now; + const snap = aggregateHashing( + workerHashingRef.current, + demoMatches.length, + ); + setProgress((p) => ({ + ...p, + phase: p.phase === "generating" ? "hashing" : p.phase, + hashing: snap, + })); + } else if (msg.kind === "slice_done") { + sliceResultsRef.current.push(msg); + // Mark this worker as no longer hashing so the aggregate + // doesn't include its stale snapshot. + workerHashingRef.current[msg.worker_index] = null; + finished++; + if (finished === cores) resolve(); + } else if (msg.kind === "error") { + setProgress((p) => ({ + ...p, + errors: [...p.errors, `worker ${msg.worker_index}: ${msg.message}`], + phase: "error", + })); + finished++; + if (finished === cores) resolve(); + } + }; + + // Tim 2026-06-07: offset every worker's bot index range by + // nextBotIndexRef.current so successive presses of Start + // accumulate rather than overwrite. Bot 0 is the first bot the + // user EVER generated on this device; bot N+1 is generated on + // the next press after N. + const offset = nextBotIndexRef.current; + for (let i = 0; i < cores; i++) { + const start = offset + i * perWorker; + const end = offset + Math.min(botCount, (i + 1) * perWorker); + if (start >= end) { + finished++; + continue; + } + // The `new URL(..., import.meta.url)` form is the Next/webpack + // idiom that picks up the worker file at build time without + // additional config. + const w = new Worker(new URL("./worker.ts", import.meta.url), { + type: "module", + }); + w.onmessage = handleMessage; + w.onerror = (err) => { + setProgress((p) => ({ + ...p, + errors: [...p.errors, err.message || "worker error"], + })); + }; + workers.push(w); + w.postMessage({ + kind: "generate", + worker_index: i, + bot_start: start, + bot_end: end, + run_id: runId, + strategy, + matches: demoMatches, + anchor: anchorSnapshot, + }); + } + if (finished === cores) resolve(); + }); + + workersRef.current = workers; + await slicePromise; + for (const w of workers) w.terminate(); + workersRef.current = []; + + // Combine per-worker, per-match roots into a single root per match + // (sorted-pair sha256, same shape as everywhere else). Clear the + // hashing snapshot now that workers are done so the UI shows the + // combining phase cleanly. + setProgress((p) => ({ ...p, phase: "committing", hashing: null })); + + const allSlices = sliceResultsRef.current; + const totalBots = allSlices.reduce((s, r) => s + r.bots_generated, 0); + const totalPicks = allSlices.reduce((s, r) => s + r.picks_made, 0); + const bestScore = allSlices.reduce( + (best, r) => Math.max(best, r.best_bot_score), + 0, + ); + + // Persist sample bots / picks. + const sampleBots: BotRecord[] = []; + const samplePicks: BotPick[] = []; + for (const s of allSlices) { + sampleBots.push(...s.sample_bots); + samplePicks.push(...s.sample_picks); + } + await persistenceRef.current.saveBots(sampleBots).catch(() => {}); + await persistenceRef.current.savePicks(samplePicks).catch(() => {}); + if (supabaseConfig) { + await supabasePersistence.saveBots(supabaseConfig, sampleBots).catch(() => {}); + await supabasePersistence + .savePicks(supabaseConfig, samplePicks) + .catch(() => {}); + } + + const combinedRoots: Record = {}; + let merkleBuilt = 0; + for (const match of demoMatches) { + const workerRoots = allSlices + .map((r) => r.merkle_roots_by_match[match.match_id]) + .filter((x): x is string => typeof x === "string"); + const combined = await merkleRoot(workerRoots); + combinedRoots[match.match_id] = combined; + merkleBuilt++; + if (merkleBuilt % 8 === 0) { + setProgress((p) => ({ ...p, merkle_roots_built: merkleBuilt })); + } + } + + // Tim 2026-06-07: roll the per-match roots up into one swarm-wide + // merkle root. This is what we surface to the user as "your swarm's + // proof" — it commits to every per-match root, which commits to + // every per-worker slice root, which commits to every pick. The + // OpenTimestamps + Bitcoin anchor in the federation layer (A3) only + // needs THIS one hex string. + const matchRootsOrdered = demoMatches.map( + (m) => combinedRoots[m.match_id] ?? "", + ); + const swarmMerkleRoot = await merkleRoot(matchRootsOrdered); + + setProgress((p) => ({ + ...p, + merkle_roots_built: merkleBuilt, + phase: "federating", + })); + + // Pick the first match as the representative commit for the demo + // and federate that. Real flow per-match is wired up by Agent A09. + const firstMatch = demoMatches[0]; + let federationRank: number | null = null; + if (firstMatch && creds) { + const root = combinedRoots[firstMatch.match_id]!; + const commitRow: CommitLogRow = { + match_id: firstMatch.match_id, + merkle_root: root, + bot_count: totalBots, + kickoff_at_utc: new Date(firstMatch.kickoff_utc).getTime(), + committed_at_utc: Date.now(), + central_ack_at_utc: null, + }; + const commit = await fed.commit(creds, commitRow); + const commitAck = commit.central_ack_at_utc; + const persisted: CommitLogRow = { + ...commitRow, + central_ack_at_utc: commitAck, + }; + await persistenceRef.current.saveCommit(persisted).catch(() => {}); + if (supabaseConfig) { + await supabasePersistence.saveCommit(supabaseConfig, persisted).catch(() => {}); + } + const lb = await fed.leaderboard( + creds, + { + best_bot_score: bestScore, + bots_still_perfect: totalBots, // pre-match: every bot still perfect + merkle_root: root, + federation_rank: null, + }, + firstMatch.match_id, + ); + federationRank = lb.rank; + } + + setStats({ + best_bot_score: bestScore, + bots_still_perfect: totalBots, + merkle_root: swarmMerkleRoot, + federation_rank: federationRank, + }); + + // A13 operator-aggregate publish. Pulls the optional operator API + // key from IndexedDB; if absent (most browser tabs), this is a + // silent no-op. The merkle_root we publish is the swarm-wide + // root, kickoff_at uses the first match's kickoff as the + // idempotency anchor, and top_k samples the top 100 sample bots + // by chalk score. + try { + const operatorKey = await persistenceRef.current + .loadOperatorApiKey() + .catch(() => null); + if (operatorKey) { + // Build top_k from the sample bots we just persisted. The + // browser only materialises ~1k sample bots per batch, so + // this is bounded. + const topKSource = sampleBots + .slice() + .sort((a, b) => (b.chalk_score ?? 0) - (a.chalk_score ?? 0)) + .slice(0, 100) + .map((b) => ({ + bot_id: b.bot_id, + score: 0, // pre-kickoff: no resolved matches yet + chalk_score: b.chalk_score ?? 0, + })); + const newTotalEverGeneratedForA13 = + nextBotIndexRef.current + totalBots; + const kickoffAt = firstMatch + ? new Date(firstMatch.kickoff_utc).getTime() + : Date.now(); + const aliveAfterMatch = demoMatches.map((_, idx) => ({ + n: idx + 1, + alive_count: newTotalEverGeneratedForA13, // pre-kickoff stub + })); + // 2026-06-07 late: rate-limited auto-commit. schedulePublish + // coalesces back-to-back batches into one POST per 30s per + // operator so a tight loop of 10k-batch runs doesn't hammer + // game-service. The /v1/swarms//summary endpoint is + // idempotent on (operator_id, kickoff_at) so a coalesced + // publish just covers more bots. + schedulePublish(operatorKey, { + total_bots: newTotalEverGeneratedForA13, + bots_alive_after_match_n: aliveAfterMatch, + best_bot_score: Math.round(bestScore), + top_k: topKSource, + merkle_root: swarmMerkleRoot, + kickoff_at: kickoffAt, + generated_at: Date.now(), + }); + } + } catch { + // Silent: operator publish is best-effort. + } + + // Build the swarm completion payload A3 (federation.ts) will pick + // up. Shape is the contract; A3 fills `top_N_claim` when the + // scoring rule lands. + const startedAt = progressStartedAt; + const finishedAt = Date.now(); + const completion: SwarmCompletionPayload = { + master_seed: MASTER_SEED, + run_id: runId, + total_bots: totalBots, + merkle_root: swarmMerkleRoot, + strategy, + started_at: startedAt, + finished_at: finishedAt, + per_match_roots: combinedRoots, + best_bot_score: bestScore, + }; + setCompletionPayload(completion); + + // Tim 2026-06-07: advance the persistent swarm cursor + bump the + // visible cumulative total. The next press of Start picks up from + // here. + const newNextIndex = nextBotIndexRef.current + totalBots; + const newTotalEverGenerated = newNextIndex; // bot 0 is the first ever generated + const newBatchesCommitted = batchesCommitted + 1; + const runAt = new Date().toISOString(); + nextBotIndexRef.current = newNextIndex; + setSwarmTotal(newTotalEverGenerated); + setBatchesCommitted(newBatchesCommitted); + setLastRunAt(runAt); + const anchorHash = anchorSnapshot?.bracket_hash ?? null; + setLastAnchorHash(anchorHash); + await persistenceRef.current + .saveSwarmState({ + next_bot_index: newNextIndex, + total_bots_generated: newTotalEverGenerated, + last_run_at_utc: runAt, + batches_committed: newBatchesCommitted, + anchor_weight: ANCHOR_WEIGHT_BY_MODE[anchorMode], + last_anchor_hash: anchorHash, + }) + .catch(() => {}); + + setProgress((p) => ({ + ...p, + phase: "done", + bots_generated: totalBots, + picks_made: totalPicks, + })); + }, [ + anchorMode, + batchesCommitted, + botCount, + credentials, + demoMatches, + dryRun, + progress.phase, + strategy, + supabaseConfig, + ]); + + // A11 Phase 2: persist anchor weight whenever the slider changes, + // even before the user runs another batch. The persisted value + // survives a tab close so the slider position is restored exactly. + const onAnchorChange = useCallback( + async (mode: AnchorMode) => { + setAnchorMode(mode); + // Persist without blocking the UI; race conditions are fine + // because the next save call (post-run) will overwrite anyway. + try { + const load = await persistenceRef.current.loadSwarmState(); + await persistenceRef.current.saveSwarmState({ + next_bot_index: load.state.next_bot_index, + total_bots_generated: load.state.total_bots_generated, + last_run_at_utc: load.state.last_run_at_utc, + batches_committed: load.state.batches_committed, + anchor_weight: ANCHOR_WEIGHT_BY_MODE[mode], + last_anchor_hash: load.state.last_anchor_hash, + }); + } catch { + // Silent: persistence is best-effort. + } + }, + [], + ); + + const onStop = useCallback(() => { + // Tim 2026-06-07 evening: also tell the loop driver to stop after + // this iteration completes. Without this, the current batch + // finishes and the loop immediately kicks off the next one. + stopRequestedRef.current = true; + for (const w of workersRef.current) w.terminate(); + workersRef.current = []; + setProgress((p) => ({ ...p, phase: "idle" })); + }, []); + + // Tim 2026-06-07 evening: when loopMode is on and a run finishes + // cleanly, kick off the next iteration automatically. Bumps the + // iteration counter so the user sees progress. + useEffect(() => { + if (!loopMode) return; + if (progress.phase !== "done") return; + if (stopRequestedRef.current) { + stopRequestedRef.current = false; + return; + } + const handle = window.setTimeout(() => { + setLoopIterations((n) => n + 1); + void onStart(); + }, 250); + return () => window.clearTimeout(handle); + // onStart is intentionally NOT in deps; it would re-trigger this on + // every render. We rely on the closure capturing the latest one via + // the ref-based pattern the component already uses internally. + // eslint-disable-next-line react-hooks/exhaustive-deps + }, [progress.phase, loopMode]); + + // schedulePublish: rate-limited auto-commit to /v1/swarms//summary. + // - First call after the 30s cooldown publishes immediately. + // - Within the cooldown window, the payload is queued and a single + // timer fires at cooldown-end with whatever the latest payload is. + // - Back-to-back batches collapse into one publish per 30s window. + // - pendingPublishRef flips true the moment we have un-ACKed work and + // flips false on a successful publish; beforeunload reads it. + const schedulePublish = useCallback( + ( + apiKey: string, + payload: Parameters[1], + ) => { + latestPayloadRef.current = { apiKey, payload }; + pendingPublishRef.current = true; + const fire = () => { + const queued = latestPayloadRef.current; + if (!queued) return; + latestPayloadRef.current = null; + publishTimerRef.current = null; + const fedClient = federationRef.current; + if (!fedClient) return; + void fedClient + .publishOperatorSummary(queued.apiKey, queued.payload) + .then(() => { + lastPublishAtRef.current = Date.now(); + // Only clear pending if no new payload arrived while we + // were in-flight. + if (!latestPayloadRef.current) { + pendingPublishRef.current = false; + } else { + // A new batch finished mid-flight; reschedule. + schedulePublish( + latestPayloadRef.current.apiKey, + latestPayloadRef.current.payload, + ); + } + }) + .catch(() => { + // Network failure: leave pending true so beforeunload still + // warns and the next batch's schedulePublish retries. + }); + }; + if (publishTimerRef.current != null) { + // Already queued; the eventual fire will pick up the latest payload. + return; + } + const elapsed = Date.now() - lastPublishAtRef.current; + if (elapsed >= PUBLISH_MIN_INTERVAL_MS) { + fire(); + } else { + publishTimerRef.current = window.setTimeout( + fire, + PUBLISH_MIN_INTERVAL_MS - elapsed, + ); + } + }, + [], + ); + + // beforeunload: warn the user only when there's un-ACKed batch work + // sitting in the publish queue. Loop mode that is actively iterating + // counts as "in flight" so we warn either way until the queue drains. + useEffect(() => { + const handler = (event: BeforeUnloadEvent) => { + if (!pendingPublishRef.current) return; + event.preventDefault(); + event.returnValue = ""; + return ""; + }; + window.addEventListener("beforeunload", handler); + return () => { + window.removeEventListener("beforeunload", handler); + if (publishTimerRef.current != null) { + window.clearTimeout(publishTimerRef.current); + publishTimerRef.current = null; + } + }; + }, []); + + const cores = useMemo(() => workerCount(), []); + const elapsedMs = progress.started_at ? Date.now() - progress.started_at : 0; + + // Block Start in a private / incognito browser until the user either + // acknowledges the no-persistence risk or turns on Supabase + // replication (which survives the window closing). Tim 2026-06-08. + const incognitoBlocked = + !!incognitoWarning && !incognitoAcknowledged && !replicateToSupabase; + + return ( +
+ {incognitoWarning && ( +
+
+ + {incognitoWarning === "confirmed" + ? "Private / incognito browser detected" + : "Looks like a private / incognito browser"} + +
+

+ Bot picks generated here are written to IndexedDB on this + device. In a private / incognito window, the browser wipes + IndexedDB the moment the last private window closes. Your + bots will be lost, and if a result is ever disputed there + will be no local record to verify the merkle root against. +

+

+ Recommended: close this window and open + play.tournamental.com/run in a regular browser + session, OR tick the “Also replicate to Supabase” + box below before you start so the swarm survives the window + close. +

+ {replicateToSupabase ? ( +

+ Supabase replication is on, so your swarm will survive this + window closing. You are good to start. +

+ ) : incognitoAcknowledged ? ( +

+ Acknowledged. Starting will generate bots that are not + guaranteed to survive this window closing. +

+ ) : ( + + )} +
+ )} +
+ +
+ +
+

IndexedDB (this device)

+

+ Default and always on. Your swarm persists across tab close, + browser restart, and laptop reboot. Private to this browser. +

+
+
+ + + +
+ + Optional: publish aggregate to your Tournamental profile + +

+ Paste an operator API key (issued at{" "} + /profile/api-keys) and we + upload an aggregate summary after every batch so anyone + looking at your profile sees your swarm stats. Picks stay + private until a bot survives match 80 on a perfect track. + Key stays in this tab; only the cumulative aggregate is + sent. +

+ { + setOperatorApiKey(e.target.value); + setOperatorKeySaved(false); + }} + /> +
+ +
+
+ + {replicateToSupabase && ( + <> + + setSupabaseUrl(e.target.value)} + /> + + setSupabaseKey(e.target.value)} + /> +
+ + +
+
+ How to set up your free Supabase project +
    +
  1. + Go to{" "} + + supabase.com/dashboard + {" "} + and create a free account (30 seconds, no credit card). +
    2. +
  2. + Click New project, name it + {" "}tournamental-bots, choose a region near + you. Wait ~1 minute for it to provision. +
    3. +
  3. + From the project dashboard, copy{" "} + Project URL and{" "} + anon public key from{" "} + Project Settings → API. Paste them above. +
    4. +
  4. + Expand the Schema SQL below and paste + it into the Supabase SQL Editor tab. Hit Run. + That creates the four tables we replicate to. +
    5. +
+

+ We only use the public anon key. We never ask for your + service-role key. Replication is fire-and-forget; if your + Supabase quota is hit, IndexedDB keeps working unaffected. +

+