feat: Bot Arena launch — smart strategy, Polymarket odds, federation, incognito gate

.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/

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/<service>/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-<ver>.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-<ver>.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 — <what changed>`. 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-<from>-to-<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.

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
 

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);

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.
    *

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);
+  });
+});

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"]