Orbit Wars Docs

One doc per topic. Each row describes current implementation. Skim by section: pick the area, then the row.

Game basics

Doc	Owns	Open when
rules.md	Game mechanics: board, planets, fleets, combat, comets, scoring, win conditions	You need to understand what the game is
engine.md	Source-derived spec: constants, turn order, rotation/collision/comet formulas, edge cases	You're writing prediction or forward-simulation code
sim.md	Fast bit-identical local simulator (sim/): oracle driver, fast JIT hooks, state hashing, identity test tiers, current limits	You're using, extending, or validating the local simulator for rollouts or replay collection
agent.md	agent(obs) API: observation schema, action format, validity rules, local testing	You're writing or modifying main.py

Agent internals

Doc	Owns	Open when
main.md	Per-turn flow of main.py: how the entry point ties subsystems together	You're tracing the live agent's execution or adding a new pipeline stage
time_budget.md	Per-turn wall-clock management: hard turn deadline, front-loaded glidepath bank spend, turn-0 precompute slice; verified Kaggle time model	You're changing the per-turn deadline, optimizer budget, bank spend policy, or chasing Kaggle TIMEOUT DQs
time_management.md	Data-grounded bank-utilization workstreams (W1 offer-cap + W2 plan-horizon shipped 2026-06-10; W3 turn-0 overshoot + W4 telemetry pending): measured Kaggle baseline, saturation vs offer-limited classification; tool scripts/analyze_time_budget.py	You're deciding what time-budget change to make next, or re-measuring bank usage after a submission
dq_while_dominating_diagnosis.md	Resolved diagnosis: long-game DQ where involuntary drain (fleet-scaled, ≈ the old static 0.04 reserve even idle) outran the floor while the bank rode it; fixed by the measured adaptive drift reserve (drain EMA) in main.py	You're chasing an end-of-game bank → negative DQ, changing the drain EMA / drift-reserve clamps, or reading min_bank from battery calibrations
fleet_arrival_cache.md	Fleet-arrival materialization, exact in-flight prediction, and the cross-turn cache that removes duplicate fleet projection	You're changing observed-fleet arrival projection, comet invalidation, or pre-optimize fleet-spam overhead
predict_fleet_arrival_optimization.md	Implemented (6–13× measured, bit-exact): turn-invariant fleet_arrival_by_id cache on GameState + batched chunked numpy kernel (fleet_arrival_vec.py); exactness contract, touchpoints, parity tests	You're changing the batched arrival kernel or per-fleet arrival cache, or chasing fleet-spam / comet-spawn turn overruns on Kaggle
data_model.md	orbit_model.py state dataclasses and orbit_physics.py helpers	You're using GameState, projecting arrivals, or computing lead shots
precompute.md	Game-fingerprint precompute cache: pair classes, safe outer routes, shot cache, comet gate	You're modifying precomputed.py, orbit_physics.py fast paths, or Precomputed
turn0_precompute_resume.md	Resumable turn-0 moving-pair ETA table build and cache write/read semantics	You're changing the first-turn precompute path or investigating dead turns while ETA tables build
turn0_eta_optimization.md	Plan, phase 2 pending (phase 1 implemented, measured ~0×, reverted): vectorizing the turn-0 static→orbiting ETA solve so the sweep stops draining the Kaggle overage bank; touchpoints + parity tests	You're optimizing the turn-0 ETA build cost or chasing the eta-build share of a Kaggle TIMEOUT
symmetry.md	C4 rotational symmetry reduction of the turn-0 ETA sweep (live, bit-identical): symmetry-group detection, representative-pair plan, phase-shift copy; precomputed.py	You're changing _build_eta_plan / _build_symmetry_group, or the ETA sweep's pair enumeration
policy_dial_design.md	Authoritative spec of the live aggression/conservation dial: per-turn scalar from board state gating attack commitment in _compute_J; policy_dial.py, hooks in scoring_state.py/main.py	You're changing the policy dial's formula, gate, or counters (design exploration lives in archived/policy_dial.md)
scoring_state_spec.md	ScoringState facade: MLP-share objective J, feature/support caches, LOCAL-vs-EXACT recompute, query API, apply/revert/clone semantics	You're modifying scoring_state.py or tests/test_scoring_state.py
optimizer.md	Optimizer stack: beam seeds, VND polish, LNS escape, bundle generation, allocation, prior, budget	You're modifying optimizer.py, beam_search.py, vnd.py, lns.py, bundle_gen.py, allocation.py, optim_config.py, budget.py, or prior.py
policy_value_rerank_plan.md	Design / brainstorm (no code): replace the runtime search with bounded policy-propose (the_producer_v2 config-sweep + wave-enum + block crossover) + value-rerank (J argmax), reusing the VND/bundle operators as memetic mutation/repair; self-play J-as-ranker tuning; tiered rollout + validation plan	You're considering replacing beam/VND/LNS with policy-propose + value-rerank, or designing candidate generation / the self-play J retrain for it
policy_value_rerank_impl.md	Build plan, no code yet: staged implementation of the rerank design — Phase 0 scaffold + EXACT precommit-clone scorer, Phase 1 internal-entries→Allocation config sweep + precommit port, Phase 2 rerank loop + deadline/fallback/telemetry + decision gate, Phases 3–5 Tier A/B/C mutation/crossover/memetic, Phase 6 oracle-vs-J validation, Phase 7 gated self-play ranker; each phase with grounded touchpoints and tests	You're implementing propose-and-rerank and need the phase order, what each phase touches (rerank.py/rerank_config.py/candidate+mutate+crossover modules), and the test that proves it
repair.md	Final move-emission boundary: lazy reachability repair, carry pool, transition, projection	You're modifying repair.py, carry_pool.py, transition.py, or projection.py
capture_validation.md	Cheap arrival-time capture gate for attack candidates	You're fixing under-strength attacks or wasted shipments
midgame_hoarding_fix.md	Mid-game "death-ball" loss fix (evidence: replay 79716908): Phase 1 no-regret de-concentration tie-break + candidate-completeness check; Phase 2 value-net root-cause (turn-skew vs share-horizon), discriminating diagnostics, leverage-ranked fixes	You're addressing why the agent hoards ships on one planet and loses mid-game, or choosing between a policy rule and a value-net retrain to fix it
residual_share_net_plan.md	Chosen hoarding fix — Phase 1 LANDED (schema-3, share-CE 0.7638), Phase 2 pending: MLP₂ re-architected as a physically-structured residual (c_B + prod_alloc + MLP₂ residual, zero-init, relu-after-sum share readout); Phase 2 (replay relabel then TD/self-play target retarget) not started; principle = accurate ship-share, not imposed concavity	You're working on the structured residual share head (built), or implementing the Phase-2 target fix for the death-ball loss
residual_share_net_prod_alloc_fix.md	Landed scale fix the structured MLP₂ needed: own_prod_alloc was raw hold·π·L (O(6)) not ÷S like own_c_B, so the residual readout was drowned out — fix divides prod_alloc by the frozen per-turn s_total at every fill site (offline + runtime + LOCAL deltas) and rescales the aux-Huber label; touchpoints, invariants, parity tests	You're touching s_total plumbing, the prod_alloc normalization, or the aux-loss units in the share net
lead_aware_arrival_fix.md	Lead-blind shipment ETA fixes for orbiting targets: the arc-screen guard is implemented (rejects co-rotating stern chases); the deep fix is planned (route candidate-arrival ETA through the lead-aware eta_by_phase table); root cause (train/inference mismatch), scope, thresholds, placement trade-off, touchpoints, tests	You're implementing/reviewing the guard or the lead-aware arrival change, or chasing why the optimizer wastes ships on shipments to orbiting targets
value_net.md	Runtime value-net inference: live two-stage share MLP (load_share_mlp1/2, share_value, fill_prod_alloc_and_forward); legacy ValueWeights spline/gamma path (now vestigial in the agent, still used by TD training)	You're modifying value_net.py or gamma_torch.py
math.md	Complete mathematical specification of the value net: layered decomposition from win-probability output to every learned parameter	You need the exact formulas for any value-net component, or are cross-referencing code against math
value_init.md	Schema-v10 value-spline warm-start generation, gradient-alive initialization, resume semantics, and knot rebaseline workflow	You're regenerating models/value_spline_v3_init.npz, changing fit_value_spline.py --resume, or handling knot-drift warnings
td_training.md	One-step TD value-spline training: v7 dataset, schema-5 game cache, Branch R/A cache keys, loss form, alive-mask invariants, and the live primitive scorer for TD gradients	You're changing build_winprob_dataset.py, build_game_cache.py, prepare_td_data.py, or TD loss wiring in fit_value_spline.py
td_outer_loop.md	Fitted policy iteration driver (scripts/td_outer_loop.py): per-iter LR schedule, Stage 3/4 validation checks, promote/revert/abort logic, manifest layout	You're running, resuming, or tuning multi-iteration TD refresh runs
MLP_value_net.md	Design of the live two-stage weight-shared MLP value net (supersedes the archived production_share_head.md): MLP₁ hold-fraction + MLP₂ ship-share at horizon H+L (no win head), player-equivariant, neutral folded into P, source-attributed targets, feature layout / normalization / per-node deltas	You're changing the MLP share net's features, targets, normalization, or the no-win-head rationale
MLP_value_net_experiments.md	Empirical results for the share net: L-sweep root-cause test (MLP₂ edge over the ship-fraction baseline grows with horizon), w_aux aux-head sweep, end-to-end joint finetune (scripts/finetune_share_mlp.py), per-head diagnostics vs baselines	You're tuning L/q/w_aux, deciding whether the share head is feature- vs horizon-limited, or interpreting diagnose_share_mlp.py output
MLP_value_net_optimizer_integration.md	Wiring the share MLP into the live optimizer: runtime feature builder + golden-frame parity, LOCAL-vs-EXACT per-node recompute + support-delta cache with per-stage dirty-set policy (phases 1-3 done); marginal-ΔJ arc screen, %-of-source reinforcement bundles, spline dead-code removal (phase 4+ planned)	You're working on scoring_state.py/optimizer share wiring, the LOCAL/EXACT recompute, or the remaining candidate-gen/cleanup phases

Game-specific subsystems

Doc	Owns	Open when
comet_fix.md	Comet despawn scoring and hard precommit evacuation	You're fixing comet garrison credit, evacuation, or locked-source search
comet_spawn_safety_v2.md	Radial-band comet spawn risk filter for the pre-spawn blind window	You're modifying lead_shot, repair, carry-forward, or shot-cache code for imminent-spawn risk

Tooling and operations

Doc	Owns	Open when
scripts.md	Index of scripts/ — training pipeline, evaluation, submission, utilities	You're running training, tournaments, eval harness, or shipping a submission
agent_eval.md	Rank-faithful candidate eval (Stages 0–4 live: timing harness, curated pool, frozen battery build_battery.py, eval runner eval_agent.py, validation eval_validation.py; Stage 5 BO integration pending)	You're implementing or running the candidate eval / the BO inner objective against agent_pool/
agent_eval_stage1_decisions.md	Implementation record of eval Stage 1: extraction, behavior dedupe, and the manual selection of the final 10-agent pool	You're re-running the pool refresh and need the rationale behind its knobs and the curated pool membership
agent_eval_stage2_fidelity_fix.md	Implementation record (shipped): why Stage-2 calibration must run the packaged candidate, the _CONFIG guard, and the two-scale billing decision	You're seeing spurious local timing DQs in calibration/eval, or changing what agent build_battery.py runs
hyperparameter_search_methodology.md	Self-contained search design (measured): tournament/retrain timings, regret-per-wall-clock objective, racing+cheap-proposer engine (not GP-BO), the selection-signal tiers, the two-axis grouping, why bench J can't tune optimizer strength, full knob inventory, harness/Kaggle protocols, sweep order	You're deciding which knob to tune next, by which metric, or choosing the search algorithm/grouping. (Old archived plan superseded.)
hyperparameter_search_implementation_plan.md	Staged build plan for the search methodology: Phase A one-off calibration (local screen floor + Kaggle T4 provenance, offline freeze track, T3 instrument) before BO, Phase B racing-loop infra (ledger, race driver, rolling-data/submission scheduler), Phase C the sweeps — each stage with file touchpoints, new scripts, and tests	You're implementing the search harness and need the build order, what each stage touches, and the test that proves it
nested_BO_plan.md	Design of the nested G1/G2 search: asymmetric surrogates (inner G2 = RF/SMAC3 pooled across G1 via instance features + racing; outer G1 = contextual GP-BO/Ax pooled across dataset-version), the RF→GP de-biased handoff, the G1/G2 dimension+cost tables, and the 4.8 h × 30-window budget	You're designing the nested BO engine, deciding which surrogate goes where, or reconciling it with the methodology's "drop GP-BO" call
nested_BO_implementation.md	Implementation of the nested BO: the SMAC3 (inner) + Ax (outer) library stack and decision record, the eval_agent.py target-function adapter, ConfigSpace for the 21 G2 dims, instance-feature conditioning, the RF→GP handoff, ledger/scheduler wiring, and a staged build order with tests	You're building the nested BO harness, wiring SMAC/Ax, or de-risking the inner-loop integration
training_grid_random_search.md	Landed Stage-2b implementation note: random search (not Cartesian product) over training knobs on all ~900 games, build-dataset-once reuse, winner-transfer (2c) check, and the epochs-frozen-offline / fixed-in-BO policy (early stopping is discovery-time only)	You're running or modifying scripts/training_grid.py, scripts/retrain_share_net.py, or the frozen training-defaults workflow
normalize_j_units_bench_normalize_fix.md	Resolved Stage-2a blocker: normalize_j_units.py now re-attaches stale bench pickle caches before sampling single-bundle `	ΔJ
optimizer_eval_harness.md	Replay-based optimizer eval: state bench, wall-time calibration, JSONL diagnostics	You're benchmarking optimizer changes or analyzing tuning output
submit.md	Kaggle CLI workflow: package, submit, monitor, replay downloads, leaderboard	You're submitting to the competition or pulling replays
models/CANDIDATES.md	Candidate value-net artifact rankings and hyperparameters (untracked; local-only file, may not exist in fresh clones)	You're picking which exported model to load
TODO.md	Follow-up work not owned by a topic doc	You're picking the next task

Archived

Superseded designs, implementation plans, and one-off findings live under archived/. Not current implementation guidance — open only when an active doc points there or you need historical context.

• warp_linear_refactor_plan.md — completed linear-domain warp refactor plan; implementation is live in schema v10.
• MLP_value_net_impl.md — offline build plan (Stages A–E, P-bucket/N-pad batching, masked-gradient parity tests) for the now-live share net; pipeline has landed (see scripts.md).
• production_share_head.md / production_share_head_impl.md — superseded spline-based future-production share head proposal; replaced by MLP_value_net.md.
• gamma_collapse.md — why the γ hold-probability head collapsed under MC/TD training; motivated retiring the γ pathway for the share net.
• remove_warm_start_seed_plan.md — completed plan to remove the cross-turn warm-start beam seed (landed 6e447e3; stable_prior_seed and friends no longer exist).
• policy_dial.md — policy-dial design exploration (motivation, behavior matrix, rejected alternatives); final spec is policy_dial_design.md.