R2 warm cache tier removed. Cloudflare Pages holds replay data directly
until file count approaches 20k, at which point storage strategy should
be reassessed.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The plan previously specified ZoneShrinkStep=2, but the engine uses
ZoneShrinkStep=1 (per commit 0577fcd). The value of 1 was found to
improve combat density because it matches bot movement speed (1 tile/turn).
A value of 2 caused the zone to shrink faster than bots could move,
killing them before combat could occur.
Updated zone parameters table and rationale in §3.7.1.
Closes: bf-3mrj
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Plan §3.4 and §3.7.1 now reflect the actual engine values:
- 2-player attack_radius2: 36 → 25 (6 tiles → 5 tiles)
- 2-player zone_min_radius: 3 → 2 (diameter 6 → 4 tiles)
These changes were made in commits 04b7e89 and ceb2de4 to achieve
the target combat density (65-80% for 2-player). Verification confirms
85% combat density with gatherer+rusher bots.
Closes: bf-vrh2
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Updated plan §3.7.1 zone parameter table to reflect the proven
implementation in ConfigForPlayers(). The previous plan values
(ZoneStartTurn=20/15, ZoneShrinkInterval=2) did not achieve the
stated combat density targets. The current values
(ZoneStartTurn=10, ZoneShrinkInterval=1) achieve 77% combat density
for 2-player and 99% for 6-player (targets: 65-80% and 100%).
Also updated code comments in engine/types.go to remove outdated
references to the old plan values.
TestCombatDensityMetrics passes with these parameters.
Closes: bf-3og6
The zone parameters table in §3.7.1 showed ZoneMinRadius=3 for all player
counts, but the code was changed to ZoneMinRadius=1 for 3+ player in
commit c80a02f to force combat contact (zone diameter 2 < attack radius
3.5). The design rationale is updated to explain the difference: 2-player
has a larger attack radius (6 tiles) so ZoneMinRadius=3 works, while 3+
player has a smaller attack radius (3.5 tiles) requiring ZoneMinRadius=1
to guarantee bots are within attack range in the final zone.
Verification: 6-player matches achieve 100% combat_death rate per
scripts/verify-combat-density.sh.
Closes: bf-4h52
Plan §3.4 gap: default attack_radius2=12 only achieved 45% combat_death
rate for 2-player random vs random, below the 65-80% target.
Changes:
- Plan §3.4: specify per-player-count attack_radius2 values (36 for 2p, 12 for 3p+)
- engine/types.go: set AttackRadius2=36 for 2-player matches
- engine/match.go: fix misleading comment about attack radius
Verification (20 matches each):
- 2-player random: 75% (was 45%, target 65-80%) ✓
- 2-player aggressive: 100% (target 65-80%) ✓
- 6-player mixed: 100% (target 100%) ✓
The larger 6-tile attack radius for 2-player compensates for fewer
opponents and higher movement variance, while 3+ player matches use
the tighter 3.5-tile radius as player density provides sufficient contact.
Closes: bf-55ud
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The previous ZoneMinRadius=5 created a final zone diameter of 10 tiles,
which allowed bots to remain outside the 3.5-tile attack radius even when
both were inside the zone. This resulted in low combat_death rates for
passive bot strategies (~10% for random bots vs the 65-80% target).
With ZoneMinRadius=3, the final zone diameter is 6 tiles, forcing bots
into proximity where focus-fire combat triggers more consistently.
Also adds verify-combat-density.sh script for ongoing metrics tracking.
Closes: bf-4bj9
Verified combat density metrics through local testing:
- 2-player: ~65-80% matches with combat_deaths, ~1 death per 20 turns
- 6-player: 100% matches with combat_deaths, ~1 death per 5-6 turns
Zone parameters (tuned per player count):
- ZoneStartTurn: 20 (2p), 15 (3p+)
- ZoneShrinkInterval: 2
- ZoneShrinkStep: 2
- ZoneMinRadius: 5
The zone achieves its forcing function (bots must fight or die) while
maintaining strategic depth (early game positioning matters).
Closes: bf-nfmm
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The ZONE phase (shrinking zone that kills bots outside the safe radius)
exists in engine/turn.go but was not documented in plan §3.7 "Turn Structure".
This phase is a critical forcing function for combat density - it compresses
bots into contact range so focus-fire combat triggers.
Updated plan §3.7 to include the ZONE phase between COMBAT and CAPTURE
with appropriate description of its purpose and mechanics.
Closes: bf-50ph
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The plan documentation had stale values for attack_radius2 (5 instead of 12).
The implementation was changed as part of combat density work to use
AttackRadius2=12 (~3.46 tiles) for both 2-player and 3+ player configs.
Updated sections:
- Section 3.4 Combat: changed default value and tile radius description
- JSON examples in protocol sections: updated example config values
- Bot compatibility note: updated hardcoded value reference
Closes: bf-29j3
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Complete the file structure section by including csharp/ alongside the other 7 starter kits. The C# starter kit is already fully documented in §5.8 and §11.2 tables.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- Add acb-starter-csharp to §5.8 starter kit table
- Add acb-starter-csharp to §11.2 template repos table
- Update evolution validation test suite language list
The C# starter kit exists at starters/csharp/ with full implementation
including ASP.NET Core minimal API, HMAC auth, grid utilities, tests,
Dockerfile, and CI workflow. It was simply missing from plan documentation.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- Add `acb-starter-javascript` to §5.8 Starter Kit table
- Add javascript/ to file structure section
- Add `acb-starter-javascript` to published template repos table
The JavaScript starter already exists in starters/javascript/ with:
- Dockerfile, CI workflow, README, package.json
- Node.js built-in http module, zero dependencies
This registers it as an official starter kit alongside the other 6 languages.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Replace native alert() calls in replay.ts URL/file load error handlers
with inline error display in the no-replay div. Add combat attack
direction visualization to §16.9 of the plan: engine emits combat_death
events with killer bot list; viewer draws directed arrows on kills.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
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>
