- POST /api/register: bot registration with URL + shared secret validation
- GET /api/job: worker polls for next pending match job (authenticated)
- POST /api/job/:id/result: worker submits match result (winner, replay JSON)
- GET /api/replay/🆔 serve replay JSON from R2 warm cache (falls back to B2)
- GET /api/bot/🆔 bot profile JSON (rating, elo, record, metadata)
- GET /api/bots: leaderboard snapshot with pagination
- POST /api/ui-feedback: accept Agentation UI feedback
Authentication via Bearer token (worker API key). Shared secrets encrypted
with AES-256-GCM using ACB_ENCRYPTION_KEY.
Corrected the full-K8s migration — the static site belongs on Cloudflare
Pages, not Nginx in K8s. The architecture is now:
- Cloudflare Pages: SPA + pre-computed JSON indexes (deployed by K8s
index builder via wrangler every ~90 min)
- Cloudflare R2: replays, per-match metadata, evolution live.json,
thumbnails, bot cards (uploaded by K8s workers via S3 API)
- apexalgo-iad K8s: Go API (Traefik ingress), PostgreSQL (CNPG),
Valkey (job queue), match workers, strategy bots, evolver,
index builder
Browser loads SPA from Pages, replays from R2, calls Go API on K8s.
No Nginx pod, no PersistentVolume for web data. R2 is the data bus
between K8s agents and the Cloudflare-served website.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
All periodic workloads now run as Deployments with internal sleep loops
that exit after a configurable lifetime (default 4h) for K8s to restart.
No CronJobs or Jobs used.
- Index builder: 15-min sleep loop, writes JSON to PV, exits after 4h
- Replay pruning: folded into index builder (weekly cycle check),
acb-replay-pruner container removed
- Evolver: already used this pattern (4h exit)
- Match workers: standard long-running Deployment (no periodic exit needed)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Major architecture change: everything now deploys to the apexalgo-iad
Kubernetes cluster via ArgoCD GitOps.
Replaced:
- Cloudflare Pages → Nginx container in Web Pod
- Cloudflare Workers → Go API container in Web Pod (same pod, shared PVC)
- Cloudflare D1 → CNPG PostgreSQL (cnpg-apexalgo cluster)
- Cloudflare R2 → SATA (Cinder CSI) PersistentVolume
- Rackspace Spot → K8s Deployments in ai-code-battle namespace
New infrastructure:
- Web Pod: 2-container pod (Nginx + Go API) sharing an RWO SATA PVC
- Match workers: K8s Deployment with configurable replicas
- Strategy bots: individual Deployments + Services
- Job queue: Valkey (Redis-compatible, existing cluster resource)
- Cron jobs: K8s CronJobs for index building, replay pruning, health checks
- CI/CD: Argo Workflows + Events (GitHub webhook triggers)
- Secrets: SealedSecrets encrypted in git
- TLS: Traefik IngressRoutes + cert-manager
- CDN: Cloudflare free plan as reverse proxy only (no CF services)
- D1 SQLite schema → PostgreSQL (proper types, FKs, indexes, JSONB)
Storage: SATA Cinder CSI (RWO). Web Pod and Index Builder CronJob
share the PVC via node affinity (both scheduled to same node).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- R2 Class A writes corrected from 44K to 101K/month (60 matches/hr
× 2 writes × 720h + 14.4K evolution live.json). Still 90% headroom.
- R2 Class B reads reconciled to 50K/month (was 30K in one place,
20K in another)
- Fixed §12 evolution meta reference → §10.2 MAP-Elites behavior grid
- Added community_hints.json to documented data paths in §14.2
- Normalized all SS notation to § throughout document (5 occurrences)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
secret storage, evolution throughput, predictions, enrichment, fairness,
lineage, crash ratings, cron model, core capture, replay pruning
Critical fixes:
- R2 write budget: replaced Worker cron index rebuilder (was ~1.6M
writes/mo, over 1M limit) with Rackspace index builder that deploys
to Pages every ~90 min (500 builds/mo). R2 now only for replays,
match metadata, and evolution live status (~44K writes/mo).
- D1 schema consolidated: all 13 tables in one place (§8.3), including
predictions, map_votes, replay_feedback, series, series_games, seasons
- Protocol schema examples updated with notes about future additive
fields (season_id, terrain, debug) per backward compatibility rules
High fixes:
- Shared secret storage: removed self-contradicting draft note, clean
statement of AES-256-GCM approach
- Predictions: changed predicted_winner INTEGER to predicted_bot_id TEXT
(tied to bot identity, not random player slot)
Medium fixes:
- Evolution throughput: configurable ladder/evolution ratio (70/30
default), container exits after 4h for Kubernetes redeploy
- Test harnesses added: game engine, bot protocol, evolution validation
- Enrichment: coding agent on Rackspace generates markdown play-by-play
- Map fairness: sample increased from 20 to 80 matches (~2% false
positive vs ~15%)
- Bot lineage: parent_ids TEXT column added to bots table
- Crash/timeout matches explicitly affect Glicko-2 ratings
- "Undefended core" defined at Phase CAPTURE
- Replay pruning: age-based 90-day, weekly Rackspace job, exemptions
for playlists/rivalries/series/seasons, acb-replay-pruner container
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
camera, PiP, performance trifecta, progressive disclosure, mobile
swipe playlists, theater mode, ambient awareness
10 UX/UI features in sections 15.9-15.18:
- Replay micro-animations: 60fps interpolation between game ticks,
particle deaths, energy starbursts, combat lines, core shockwaves
- Director Mode: adaptive auto-speed based on action density per turn,
cinematic tempo that slows for combat and speeds through exploration
- View mode morphing: 300ms cross-fade between dots/territory/influence
using dual off-screen Canvas buffers
- Follow Bot camera: viewport lerps to track one player's bounding box,
pairs with fog-of-war for first-person documentary feel
- Picture-in-picture: replay minimizes to 200x200 floating player on
navigation, Canvas reparented (not recreated), GPU-animated transitions
- Performance trifecta: hover preload (100ms delay), layout-matched
skeleton screens with shimmer, 5-page back-nav cache (0ms restore)
- Progressive disclosure: viewer XP tracks engagement, reveals controls
at levels 0/2/5/10/20, golden pulse + tooltip on new features
- Mobile swipe playlists: full-screen cards, auto-play Director Mode,
swipe-up to advance, background preload of next replay
- Theater mode: fullscreen chrome-free canvas, vignette + critical
moment pulse, auto-hiding controls, landscape trigger on mobile
- Ambient awareness: favicon badges, tab title updates, haptic on
critical moments, seasonal background hue shift, live match counter
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
New section 15 covers:
- Three audiences (spectator, participant, visitor) with distinct needs
- Information architecture: /watch, /compete, /leaderboard as primary hubs
- Homepage design: auto-playing featured replay, two CTAs, compact
leaderboard + playlists + season status + evolution mini
- Desktop top bar + mobile bottom tab bar navigation
- Responsive breakpoints (phone/tablet/desktop) with mobile-first
spectating, desktop-first building
- Mobile replay viewer: full-width canvas, pinch-to-zoom, tap play/pause,
swipe-to-scrub timeline, slide-up panels
- Sandbox is desktop-only (clear mobile message + "send to desktop" link)
- First-time visitor funnel: see → watch → engage → build
- Performance budget: <2s LCP, <200KB gzipped JS, code-split per route,
lazy WASM loading, stale-while-revalidate data fetching
- Design language: dark theme, minimal chrome, functional animation,
mono+sans-serif typography
- 11 reusable components covering all pages and breakpoints
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Pages serves the SPA shell only (~500-1000 files): HTML, JS, CSS, WASM,
docs. Changes only on code deploys. R2 serves all dynamic data via custom
domain: replays (~130K files at 90d retention), leaderboard, bot profiles,
matches, evolution status, blog posts, thumbnails, cards. R2 is also the
data bus for Rackspace agents — same files browsers read are what workers
write. Added detailed file layout for both, data loading pattern with
cache headers, and updated architecture diagram showing the three-way
data flow (Worker materializes D1→R2, Rackspace writes to R2, browser
reads from R2).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
evolution observatory, narrative engine
New section 14 + Phase 10:
- Weekly meta report as auto-generated blog posts on /blog with
LLM-enhanced narrative sections (~$0.05/week)
- Public match data as documented static JSON file paths in R2,
no Worker API needed; versioned replay format spec
- Accessibility suite: Tol color-blind palette, shape-per-player,
keyboard shortcuts, high contrast, reduced motion, screen reader
transcript, focus indicators
- Live evolution observatory: evolver writes live.json to R2 every
cycle (~20 writes/hr), page polls every 10s, renders island status
+ candidate pipeline + activity feed + lineage tree + meta chart
- Narrative engine: weekly story arc detection (rise, fall, rivalry,
upset, evolution, comeback), LLM-generated 200-word chronicles
published as blog posts (~$1.30/month)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
embeds, playlists, predictions, map evolution, series, event timeline,
seasons, bot cards
New section 13 (10 features) + Phase 9:
- Bot debug telemetry: optional structured debug field in move response,
rendered as targets/heatmaps/reasoning in the replay viewer
- Three replay view modes: dots, Voronoi territory, influence gradient
- Embeddable replay widget (~50KB iframe, OG tags, query params)
- Auto-curated playlists: Closest Finishes, Upsets, Comebacks, etc.
- Prediction system for non-coders (within CF free tier: ~864 writes/day)
- Map evolution with breeding, engagement scoring, positional fairness
monitoring, and user voting (upvote/downvote maps)
- Multi-game series (bo3/bo5/bo7) across different maps with spoiler toggle
- Match event timeline with clickable icon ribbon
- Seasonal rotations with backward-compatible rule versioning (additive
changes only: new optional fields, param tuning, new tile types that
old bots can ignore), championship brackets, season archives
- Bot profile cards as shareable PNGs with OG tags
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Reworked sandbox to use separate WASM modules per bot instead of JS
function callbacks. Each bot compiles to its own WASM with a standard
init/compute_moves/free_result interface. Supports Go, Rust, TS natively;
PHP/Java bots reimplemented in Go for WASM. Memory budget 30-105MB
depending on player count. Two user modes: TS quick-start in Monaco
or upload pre-compiled .wasm file.
Dropped what-if replay branching — good in theory but the split-pane
counterfactual UI is a power-user feature that would confuse casual
visitors. Not worth the complexity.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
AI commentary, clip maker, rival detection, community feedback
New section 12 covers seven features with Phase 8 for implementation:
- In-browser WASM sandbox (1 WASM engine + JS bots, ~30-50MB, <2s)
- Win probability graph via Monte Carlo rollout + critical moments
- What-if replay branching (single WASM, state injection, split-pane)
- Selective AI commentary for featured/rivalry/milestone replays
- Clip maker with GIF/MP4 export for Twitter, TikTok, IG, Discord
- Automatic rival detection with template-generated narratives
- Community replay feedback tagged by turn, feeding evolution hints
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Architecture split: Cloudflare Pages (static site), Worker (API + cron
scheduling), D1 (SQLite database), R2 (replays + JSON indexes, zero
egress) — all within the free tier with 95%+ headroom on every quota.
Rackspace Spot handles match workers, bot containers, and the evolution
pipeline — all stateless and interruptible. Includes D1 schema, Worker
cron design (matchmaker, indexer, health checker, reaper), R2 bucket
layout, free tier usage math, and graceful degradation model. Drops
infrastructure cost from ~$65-110/mo to ~$35-70/mo.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
All platform data is now JSON files on disk served directly by Nginx.
Workers submit results to the scheduler over Tailscale HTTP, scheduler
writes to the data directory. No object store, no S3 API. Scheduler
coordinates jobs via HTTP endpoints backed by SQLite. Data directory
is a persistent volume on the stable instance.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Major changes:
- Website is now a static site loading JSON from object store, no app server
- Removed PostgreSQL, Redis, PgBouncer, read replicas — replaced with Minio
(S3-compatible) for all data and SQLite on the scheduler for bookkeeping
- Registration is a minimal 3-endpoint API, no user accounts needed
- Match job coordination via file moves in Minio (no message broker)
- All user-facing data is pre-built JSON fetched client-side
- Single stable instance runs everything except match workers
- Spot workers are fully stateless — site stays up when all are reclaimed
- Added cost model (~$65-110/mo excluding LLM API)
- Simplified monitoring to match the architecture
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
New section 10 covers the full evolution pipeline: FunSearch-style island
model for population diversity, LLM ensemble (fast+strong) for candidate
generation, multi-stage validation (syntax, schema, nsjail sandbox),
evaluation arena, Nash equilibrium promotion gate (LLM-PSRO), automated
container build/deploy, retirement policy, and evolution dashboard with
lineage viewer and meta tracker. Phase 7 added to implementation plan.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Each of the six built-in strategy bots is now implemented in a different
language (Python, Go, Rust, PHP, TypeScript, Java) to demonstrate that
the HTTP protocol is truly language-agnostic. Added per-language container
templates, resource specs, and forkable starter kit repos for participants.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Covers game mechanics (toroidal grid, focus-fire combat, energy economy,
fog of war), HTTP communication protocol with HMAC authentication, six
built-in strategy bots as containers, Glicko-2 tournament system, compact
JSON replay format with Canvas-based browser viewer, web platform with
bot registration, and Rackspace Spot deployment architecture. Organized
into six implementation phases from core engine through production.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Research covers game mechanics, bot protocol, tournament/ranking,
replay system, infrastructure, and successor platforms. Requirements
document captures the HTTP-based bot communication model, 3-second
timeout, strict schema enforcement, and replay visualization needs.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
