Box Score

Claim boxes against a server-side Jev opponent, then read the box score: every move, candidate and decision on the record.

Quick start · How it works · Analytics · Export and audit · Tests and benchmarks · Discord and ranked play · Repository layout · Contributing

---

Box Score is the classic connect-the-dots boxes game on a 4×4 board, played in one page against Jev, a server-side opponent. Its selling point is the stat sheet: each match keeps deterministic replays, hash-linked evidence for every decision and exports you can audit offline. It is part of jevplay.games.

[!NOTE] What is shipped and measured. The game runs without credentials in clearly labeled local-practice mode; real Jev requests need a TypeSafe API key and Discord sign-in needs your own Discord application. The included tests use mocked external services, and the bundled benchmark is a 12-game local smoke run, not evidence of Jev's playing strength. See Boundaries and limitations.

Quick start

Install Node.js 22.13 or newer, extract this folder, then run:

npm start

Open:

http://127.0.0.1:8787

There are no npm runtime dependencies and no installation or build step for local play. The development server uses Node's built-in SQLite module and stores its database in .data/game.sqlite. Node may print an experimental SQLite warning on some 22.x versions.

Choose a difficulty and opponent, then click a line or New game. Capturing a box earns another move. All 40 edges and 16 boxes are played; 8–8 is a draw.

The localhost development server is not a public production server. For hosting, use the supplied Cloudflare Worker/D1 configuration and read Deployment.

Enable Jev

Copy .env.example to .env:

# macOS / Linux
cp .env.example .env

# Windows PowerShell
Copy-Item .env.example .env

Set these values in .env, then restart the server:

TYPESAFE_API_KEY=your_actual_key
JEV_MODEL=jev-1.13.0

Choose Jev API in the opponent selector. The server sends a structured Choice question over legal edges; the browser never receives the key. The returned distribution and selected edge are validated before a move is committed.

A provider failure is not silently treated as Jev: the match is demoted to local practice, the cause is recorded, and ranked eligibility is removed. The failure continues to appear in the analytics export.

The configured model is pinned. A model, prompt, search-profile or source-revision change creates a separate ranking cohort. Do not change the model/version environment underneath an unfinished ranked match.

How it works

%%{init: {"themeVariables": {"lineColor": "#E551BA"}}}%%
flowchart LR
  B[Browser: board, analytics, replay] -->|move + CSRF| W[Worker API]
  W --> R[Authoritative rules + search]
  R -->|Jev mode| J[Structured Choice request to Jev]
  J --> V[Validate distribution and edge]
  R -->|local practice| V
  V --> E[Hash-linked event journal]
  E --> D[(D1 / SQLite)]
  D --> L[Leaderboards]
  E --> X[Exports and audit]
  class B,X ink
  class W,R,V,E pink
  class J,D,L grey
  classDef ink fill:#1E1E1E,stroke:#1E1E1E,color:#FEFEFE
  classDef pink fill:#F386A1,stroke:#1E1E1E,color:#1E1E1E
  classDef grey fill:#DEDEDE,stroke:#1E1E1E,color:#1E1E1E

What is included

Area	Implemented behavior
Game	4×4 boxes, both starting seats, double captures, extra moves, deterministic transitions
Interface	Responsive vanilla HTML/CSS/JS, keyboard edges, accessible move list, in-page rules
Opponents	Clearly labeled local practice; server-side Jev; Easy, Normal, Hard and Jev profiles
Decision evidence	Every legal candidate, tactical features, bounded search, selected edge, full valid probability distribution
Analytics	Live overview, score/latency charts, candidate inspector, expandable event timeline, metrics catalog
Replay	Scrubbing, playback, strict import, compact export, full evidence audit without provider calls
Identity	Discord authorization-code flow, identify scope, secure production session cookies, CSRF/origin checks
Communities	Signature-verified /play interaction, one-time user-bound launch code, recent guild/channel context
Rankings	World/Server/Channel, UTC month/all time, pinned-profile cohorts, seat-balanced score rates, shared ties, pagination
Integrity	Authoritative server moves, revision checks, idempotency, decision leases, replay verification, hash-linked evidence
Exports	Full JSON, JSONL journal, summary JSON, moves/decisions/candidates/attempts CSV, CLI batch export
Operations	Redacted API telemetry, opt-in client diagnostics, quotas, retention cleanup, administrative SQL queries
Research	Paired-seat benchmark, independent small-endgame solver tests, configuration provenance, exact-only regret

Analytics

The Overview displays actual recorded values, not prepopulated demonstration data. The Candidates tab lets you inspect any recorded opponent decision. The Event timeline exposes ordered event payloads. Exports retain more detail than the compact interface displays.

Recorded evidence includes:

• Pre/post-state hashes, actor, edge, captures, scores, extra-turn behavior and tactical board snapshots.
• Full legal candidate sets, capture opportunities, third-side creation, safe moves, components, search node budgets, cache hits, cutoffs and exactness.
• Jev request/state hashes, exact structured request, validated response, per-option probabilities, certainty, entropy, top-probability gap, selected action and decision source.
• Feature, provider, total-decision and commit timings; latency quantiles; request/response sizes; reported tokens; retries, timeouts and malformed-output failures.
• Versioned events, UTC timestamps, process-local monotonic clock domains, causal decision/request IDs, SHA-256 chaining and verification outcomes.
• Optional configured cost estimates with explicit unknown-usage and unknown-cost accounting.

See Analytics definitions, the machine-readable metric catalog, event schema, and administrative SQL.

Interpretation matters: model certainty is not win probability. A cutoff estimate is not a solved final margin. Human elapsed time includes idle/network time. Exact regret remains null unless all alternatives were solved. Missing billing data is unknown, never assumed zero.

Export and audit

Use Export data in the interface, or save a full match JSON and run:

npm run audit -- path/to/full-match.json
npm run export -- path/to/full-match.json analytics-export

The audit exits nonzero for invalid evidence. The export creates summary.json, audit.json, manifest.json, five CSV tables, corresponding JSONL tables, and the original hash-linked journal.jsonl.

A compact replay can be audited for rules consistency, but does not establish provider provenance. Imported replays can never create official leaderboard results.

For a local administrator's operational report:

node scripts/ops-export.mjs .data/game.sqlite operations-export

That export deliberately excludes user/session/OAuth tables.

Tests and benchmarks

npm test
npm run benchmark -- --pairs 6 --mode local --opponent random --difficulty normal

The supplied Node test suite covers the engine, structured analytics, provider contract, retry/timeout behavior, API authorization, OAuth state binding, Discord signatures, concurrent requests, launch attribution, leaderboard isolation and pagination. It also enumerates every one-box move ordering for both starters and checks 1,000 seeded complete games.

The independent small-endgame oracle checks search values without relying on the search implementation's own evaluator.

For a live benchmark, explicitly select Jev:

npm run benchmark -- --pairs 20 --mode jev --opponent heuristic --difficulty normal
npm run benchmark -- --pairs 10 --mode jev --opponent jev --difficulty normal

Available baseline opponents: random, greedy, heuristic, search, jev. A live benchmark stops on provider failure rather than silently mixing fallback results into a Jev cohort. These commands incur provider usage when Jev is selected.

Benchmark methodology explains pairing, duplication risks and the limitations of the included small local smoke run.

Browser tests

Browser testing is optional and separate from application dependencies:

python -m pip install playwright
python -m playwright install chromium
# In one terminal: npm start
# In another:
python scripts/browser-test.py

The packaging environment blocked browser navigation by administrative policy. Its recorded UI check therefore used --embedded: actual HTML/CSS/JS was loaded into a browser document, HTTP was bridged to the real local API, and game interactions were exercised. This does not validate normal navigation, CSP enforcement, native cookie handling, OAuth redirects or downloads. The normal test path is included for an unrestricted development machine.

See Validation record. Screenshots are from the actual implemented interface, not an image-generation mockup.

Discord and ranked play

Read Deployment for the exact application settings, OAuth callback, interaction endpoint and command registration.

Ranked games require Discord authentication and Jev API mode. Starting seats alternate. World rankings contain all eligible ranked matches; server/channel rankings contain only matches launched through verified context. Client-supplied guild/channel IDs are ignored.

Each launch code is valid for ten minutes and one match. Recent community context is also time-limited; relaunch from Discord to refresh access. This is not continuous membership verification.

A rank requires ten settled games in each starting seat. The ranking metric is:

0.5 × [(wins + 0.5 × draws) / games when human starts]
+ 0.5 × [(wins + 0.5 × draws) / games when Jev starts]

Concessions count as losses while preserving actual partial board scores. Confirmed provider failures remove eligibility. Practice results do not become official retroactively. Equal score rates share the same rank.

Repository layout

public/                 Single-page interface, shared brand files and rules/analytics
  games/box-score/      Pure deterministic rules and search (shared by browser and Worker)
src/                    Web-standard Worker API, Jev, OAuth, Discord, matches
migrations/             SQLite / D1 schema and indexes
scripts/                Local server, SQLite adapter, audit/export/browser tools
bench/                  Reproducible paired evaluation runner
tests/                  Node tests and mock-service fixtures
docs/                   Architecture, security, analytics and deployment
reports/                Executed test output, local benchmark evidence, screenshots

Boundaries and limitations

This is a runnable implementation, not a claim of independently audited production security or proven Jev playing strength. Real TypeSafe inference, real Discord consent/interactions, and a Cloudflare deployment were not exercised during packaging. Search-assisted modes can require substantially more CPU than Easy/Normal; do not assume a free serverless tier is sufficient.

The hash chain detects changed evidence relative to a retained head; it is not an external signature or immutable public ledger. A database administrator capable of rewriting the entire chain is outside that guarantee. No lightweight browser game can prove the absence of external human solver assistance.

Required deployment configuration is deliberately left explicit rather than replaced with working credentials or fabricated service connections.

Contributing

Issues and pull requests are welcome. Run npm test before opening a pull request, keep the rules in public/games/box-score/ free of DOM and I/O, and do not change stored identifiers (replay format, match format, rules version, the model-facing game id) without a version bump: replays exported before the Box Score rename (game id dots-and-boxes) must keep importing. Licensed under the MIT License.