Upstream/docs/NEXT.md
jvanvik 3c23c51902 Phase 4: close loot/refund leaks, landing-site garrisons, speed-scaled shipping, update/offsite tooling, broad e2e
Built:
- Economy: raid loot capped to the room the raiders have at home (rest stays with the victim, "lootLeft" in the report); trade escrow reserves its room so refunds always fit; trade accept refuses with no_room_for_goods when the goods would not fit. Loot destroyed per 30-day run 31-61k -> ~1k, refunds clipped ~27k -> 0 (docs/BALANCE.md, 3 seeds).
- End game: members of the holding alliance garrison landing sites (migration 005_site_garrison.sql), garrison counts in site defence, 72 h capture shield, withdraw route, POP view lists garrisoned units. Shipping capacity scales with world speed (3x world: winner 76-98 -> ~30-36 days after sites open). Bot runs show real contests (84-194 attacks on held sites at 1x).
- Ops: deploy/update.sh (backup, stop, ff-merge, npm ci --ignore-scripts, health check, rollback), deploy/upstream-offsite (rsync only), admin end-world snapshots results, EPIPE fix, docs/workflows/ filled in.
- e2e 62 -> 163 checks: units, raids/reports, alliance+messages, trade, end game, nb, PWA, reconnect, slow polling fallback (opt-in). Two app bugs found: message push ignored, "New" button stayed English.

Tested: npm test 274/274, openapi check, npm run e2e 163/163 (137 s), bot runs 50x30d seeds 1-3 and 140-day/60-day speed-3 end-game runs INVARIANTS OK, adversarial review pass (findings fixed or documented).
NOT tested: update.sh on a real box (systemd, real npm, runuser; stubs only, shellcheck not installed), garrison card/loot text on a phone, Node 22.13, humans. Known leaks left open and documented (BALANCE S6): loot/shipments can still overflow when stock arrives in flight, bounced backbone shipments lose overflow (reported to the sender). Garrison numbers (heldDefenceMult 2, shield 72 h) are first guesses from 2 seeds. Not claimed: balanced.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q2MJaQ5LXAHzGnTDgceT14
2026-10-12 00:58:12 +02:00

336 lines
40 KiB
Markdown

# NEXT
Honest status, updated at the end of every stage.
## Status at a glance (checked 2026-10-11, Node 24.21)
Where it stands: stages 0-6 are built on the server and in the web client (economy, world, military, expansion, social, trade, end game,
WebSocket push); stage 7 is partly done (bot harness + first balance pass, admin CLI, deploy files). **The game is not balanced, not
playtested by humans, and has never run on the real target (Debian LXC + systemd + nginx Proxy Manager).**
Runnable and checked just now:
- `npm test`: 264 tests pass in about 8 s (this tree) (rules as pure functions, commands/events/scheduler with a fake clock, REST over HTTP with every
response checked against its schema, push with a real `ws` client, client logic, bot harness, admin CLI). `npm run openapi` leaves
`docs/openapi.json` unchanged (it is in sync with the route table: 68 paths).
- `node tools/bot.js --players 50 --days 14 --speed 1`: about 3 s, `INVARIANTS OK`. `node tools/admin.js help` works.
- The deploy path from DEPLOY.md in a scratch directory, without systemd: first boot (migrations, world), `/healthz`, signup, a build,
`admin.js` status/worlds/users/inspect/events/replay/backup/verify-backup/ban/grant, SIGTERM + restart (state kept), SIGKILL + restart
after a build fell due (caught up in order), restore of a snapshot into a fresh `DB_PATH`.
- `npm run e2e` (`e2e/run.js` + `e2e/flows.js`, Playwright): 163 checks pass in about 137 s (smoke, units, movements + reports, reconnect, alliance + messages, trade, end game, nb, PWA); `E2E_SLOW=1` adds the 60 s polling-fallback suite. See "E2E" below.
Never run: real devices, Safari/iOS, a Proxmox LXC, a unit under systemd, the backup timer firing, nginx Proxy Manager (WebSocket upgrade,
idle timeouts, real client IPs), Let's Encrypt, a restore on the real box, load with many real sockets, any human player. Node 22.13 (the
stated minimum) was not run, only 24.21.
Known gaps, consolidated (the sections below have the detail and the reasoning):
- **Balance:** the first hour of a player who plays it all is limited by the 750 starting stock (about 12 builds), not by build time; a bigger stock was measured and not adopted (B4). nothing is tuned beyond B1, B2 and the B4 early-level build discount (BALANCE.md). The end game follows world speed since B7 (3x: 29 to 35 days after the sites open, was 77 to 98) and a held landing site can be contested since E6 (garrisons, a
light static defence for held sites, a 72 h capture shield); both are first guesses measured with bots on two seeds (BALANCE.md B7 and E6), no human has played them, the static
defence outgrows what one POP can send around world age 280, and the bots do not react to `backbone_incoming`. Open: (S2 and S4, trade refunds clipped and loot/incumbent bonus destroyed on overflow, are fixed by B6: escrow keeps its room in the Rack hall, loot is limited to what home can bank; transport deliveries onto a full store, and a bounced backbone shipment that finds the hall refilled, still lose the overflow, reported with exact `cargoLost`; several raids from one home no longer share the same free room, S6; trade accept is refused with `no_room_for_goods` when the projected hall has no room); the capital runs out of things to build long before the backbone opens;
the bots are not humans.
- **Game rules not built:** cancelling training, sitters, night protection, a command to choose a new capital, power draw for units in
transit, alliance rename/description, trade order book / price history / counter-offers, multi-link trade deals.
- **Server:** no `backbone_open` push (sites are created lazily, E2); no `incoming` for confederates and no `town` hint for reinforcing
owners; token revocation reaches an open socket only at the next 30 s ping; tokens never expire and there is no change-password route; no APNs/FCM
sender; `reports.id` can be reused after a full cleanup (S3, low); no recovery sweeper if an `arrive`/`return` handler ever throws (R1);
HTTP connections per IP are not capped.
- **Client:** no service worker (no offline mode), no light theme, no unit icons or battle simulator, no sound/system notifications; a few
one-tap destructive actions without confirmation; unread-badge state is partly in localStorage; ended-world locking is a DOM sweep.
Found by the e2e and NOT fixed: after switching language live, screens that were already drawn keep ~15 English `aria-label`s (map zoom/label, refresh buttons, tab groups; visible
text is fine, a reload fixes it); an alliance message raises the More badge by 2 (the alerts feed and the unread message are both summed; by design of the badge, perhaps not intended).
- **Docs:** `docs/workflows/` has a short note per stage (written after the fact from NEXT and the git history; NEXT stays authoritative).
- **Not run in a browser:** takeover/capture flows, the confederation `alliedIncoming` view, real devices (see the client sections).
## Done
- Stage 0 skeleton: db + migrations, clock, scheduler with catch-up, router, auth/tokens, error envelope, openapi generation, static server.
- Stage 1 economy (server): lazy resources, buildings, build queue, storage caps, power battery.
- Stage 2 world (server): seeded tiles, spawn ring, map viewport query.
## Stage 5 (partial): social, server only
Built (migration `003_social.sql`): alliances (found, invite/accept/decline/cancel, leave, kick, roles, leader transfer, disband,
pinned notes, member list with POP count and last online), diplomacy between alliances (war, neutral, NAP, confederation;
proposals; 24 h / speed pact cancel through the `diploChange` event; revoke), messages (DM, alliance broadcast, inbox/outbox/thread/
alliance feed, read, delete own copy, block list, DB-backed rate limit, text sanitising), rankings (operators, alliances, battles),
`alliance` in `/me` and `/map`, lookup helpers in `server/alliances.js` (`operatorRelation`, `atWar`, `confederated`, `pactPartners`).
Tests: `test/social-*.test.js` (pure rules, alliances, diplomacy with the fake clock and event queue, messages, rankings), every
response in them is checked against its declared schema (`createTestServer({ contract: true })` in `test/helpers.js`).
Not done:
- Marketplace / Internet exchange: DONE on the server, see "Trade, end game, gaps" below.
- Shared report folder and "see each other's incoming": DONE on the server (below). The pact effect "no attacks inside a NAP/confederation"
is enforced by the military stage (`pactBlocks`).
- Web client: see the client sections below; WebSocket push (stage 6) exists server-side and in the client.
- Message retention/cleanup of old rows, alliance rename/description, mass-mail abuse reporting, sitter accounts.
- Rankings: the footprint part has a 5 s per-world cache (review R1); battle rankings are filled from `operator_stats` now that the military stage writes it.
- Not run: Playwright, load; the social numbers in `SOCIAL` (limits, TTLs, role table) are first guesses (the bot runs only exercised alliances/NAP/confederation lightly).
## Stage 3/4: military and expansion (server only)
Built (migration `002_military.sql`: `town_units`, `stationed`, `town_research`, `town_power`, `movements`, `reports`, `report_recipients`,
`operator_stats`, `incumbent_takes`): 10 unit types and research in `data.js`/`rules.js`; training queue (`trainDone` per batch,
sequential per building); research (`researchDone`); movements scan/raid/attack/takeover/reinforce/settle/transport with latency, ETA,
recall (90 s), return legs with loot; combat resolved at arrival in the event queue (full attack, raid, firewall vs DDoS rigs, exploit
kits on a chosen building, loot with Rack hall cache, losses, reinforcements, research, battle points in `operator_stats`);
scans with intel and detection; takeover with loyalty, capital and last-POP protection, footprint gate; founding POPs with wild-slot
choice; incumbent sites (static defence growing with world age, one-time Hardware bonus, +10% research speed per site); beginner
protection (both directions, re-checked at arrival); power: offline units when the battery is empty, decommission after 24 h
(`powerCheck`); incoming warnings with hidden type; reports (shared row, per-user read flag, 14 day cleanup event); transport movement
and arrival hook (`movements.hooks.transportArrived`) for the trade stage. Routes: see docs/API.md, all in `docs/openapi.json`.
Tests: `test/military-*.test.js` (rules as pure functions, train queue order, raid end to end, event order and determinism, takeover and
its protections, offline units and decommission, restart catch-up from a reopened DB file, protection, settle, incumbent, transport,
recall, research, reports/cursor/retention, API smoke over HTTP). Fake clock, in-memory DB, port 0; no Playwright.
Not done / not claimed:
- **Nothing is balanced.** All unit stats, costs, research curves, incumbent defence and the 50-unit-scale combat numbers are first guesses;
there was no bot run when this was written (`tools/bot.js` exists now: see "Stage 7" below and BALANCE.md; most of these numbers are still untuned). Do not cite any of them as tuned.
- Training cannot be cancelled; no sitter, no night protection. (Report sharing and allied incoming: done, see below.)
- Units in transit draw no power from anyone; an operator cannot choose a new capital POP (no command); a captured POP keeps its footprint.
- Backbone landing sites and the Backbone node: see "Trade, end game, gaps" below.
## Client (stages 1-2 web client)
Built: `public/` vanilla JS, no build step, strict-CSP friendly (no inline scripts or handlers, no external requests).
- Shell (`js/main.js`): session, `App.registerScreen({id, titleKey, navKey, icon, hud, render, onShow, onHide, onLang})`, bottom nav
(left rail in landscape and on wide screens), live resource bar ticked with `rules.resourcesAt` from the server clock, hash routing.
- Screens (`js/screens/`): login/signup (invite field appears after `signup_closed`), POP (resource fields by type, infrastructure,
build queue with countdowns and cancel, power panel, detail sheet with the server's `next` plan, live affordability, rename),
map (`js/render.js` canvas: pan, pinch, wheel, keyboard, culling; chunked `GET /map` cache; tile info sheet), alerts
(`GET /notifications`), settings (language, device tokens + revoke, logout).
- `js/api.js`: bearer token, serverTime offset, retry/backoff (network, 429 + Retry-After, 502-504), `Idempotency-Key` per intent,
`ApiError.code`, event emitter with a `push` event (the WebSocket client `ws.js` came with the military client, below).
- `js/i18n.js`: en + nb, all player-facing names; `PWA`: manifest + icons (no service worker, so no offline mode).
- Tests: `test/client-i18n.test.js` (key parity, names, error codes, formatting), `test/client-api.test.js` (retry, idempotency, offset).
- Looked at with headless Chromium screenshots (phone portrait, phone landscape, desktop) and one scripted signup/build/cancel/map-tap
flow on a phone profile. Not run: real devices, Safari/iOS, Playwright suite.
Gaps: the unread badge is stored in localStorage (no "mark read" route); `/me` exposes the world seed which the client ignores;
no service worker (push was added later, see the WebSocket section), canvas has no inertia/fling, no light theme.
## Client: social (alliance, messages, rankings)
Built (all in the nav "More" group, `navGroup: 'more'`): `screens/alliance.js` (found with Peering office gate and translated server
errors; received invites accept/decline; overview with size, pinned notes add/remove, leave/disband; members with role, POPs,
footprint, last online, a member sheet for message / role / transfer / kick; invite by name, pending invites with cancel; diplomacy
with relations, proposals in/out, "new move" via directory search with only the moves `rules.diplomacyMove` allows, pact-cancel
and proposal countdowns, take-back), `screens/messages.js` (inbox with unread filter / mark all read, sent, alliance feed with
broadcast composer, per-operator thread with older-page cursor, compose by name, 2000 char counter, delete own copy, block list and
block/unblock, 429 shown as a countdown with the text kept, unread count on the nav via `App.setBadge`, polled every 60 s),
`screens/rankings.js` (operators, alliances, battles attack/defense/total, your row highlighted plus the server's `you` card, rank-offset
"load more"). Shared bits: `screens/social-ui.js` (`window.SocUI`: composer, confirm sheet, alliance profile sheet, error mapping),
`js/social.js` (pure logic: what to show per role via `rules.allianceCan/outranks`, diplomacy options, counters, cursor merges),
`js/strings/social.js` (en + nb), new sprite icons users / mail / trophy / back, `.soc-` CSS. All player text goes in with
`textContent` (a test fails on any `innerHTML` in these files).
Tests: `test/client-social.test.js` (pure logic, string coverage of every static key the screens use, error codes, no HTML sinks).
Looked at with headless Chromium (phone portrait/landscape, desktop) against the real server in-process, plus a scripted flow on
a phone profile (markup in a message stays text, counter/over-limit, 429 countdown, unknown recipient, leader vs member views, diplomacy
move sheet, name-taken error, nb). Not run: real devices, Safari, Playwright suite, a long-list scroll test (>100 ranks), accepting an
invite when the alliance is full, alliances at the size cap.
Gaps: alliance rename/description and note editing have no UI (server has edit-note); no operator profile page; blocking needs an existing
conversation or message (the API takes an operator id and there is no name lookup); no live refresh (push is not wired for the alliance screen, which refetches
on open and on manual refresh; Messages follows the `message` push since the e2e pass); the alliance screen does not auto-refresh countdowns' targets after they pass; `App.state.operator.alliance`
is refreshed from `/me` after alliance changes but is stale if you are kicked while away until the screen is opened.
## Client: military, expansion, WebSocket
Built (`public/`, same rules as before: no innerHTML for player text, no inline handlers):
- **Nav overflow** (`main.js`): 5 slots; `registerScreen({ navGroup: 'main' | 'more' })`, with any `more` screen the 5th slot is a
"More" sheet; `App.setBadge(screenId, n, 'alert'|'info')` (More sums its screens, red if any is an alert). Bar now: POP, Map, Units,
Moves, More (Reports, Alerts, Settings, the social screens). `App.alertKinds[type]` lets a screen describe its own notification types in
the Alerts feed; `App.popSections` lets screens add cards to the POP screen (incoming banner, expansion card).
- **Shared state** (`milstate.js`): `App.mil.moves` (last `GET /movements`: outgoing, incoming, alliedIncoming) is the one source for the
nav badge, POP banner, movements screen and map lines; `App.refreshMovements/refreshReportsUnread/refreshTowns` (the last refetches `/me`
without the destructive `setSession`, used after a settle/takeover); `[data-cd]` countdown elements driven by one ticker; refetch when
anything on the wire is overdue.
- **Units** (`screens/units.js`): home units with research-adjusted stats, reinforcements here (send home) and your units elsewhere (call
back), training queue with countdowns + train sheet (`rules.trainPlan` preview, max-affordable, queue-full), research list + sheet
(`rules.researchPlan`, lab level / cost / time / reason), offline warning with the decommission countdown.
- **Movements** (`screens/movements.js`): incoming list on top in red (origin + ETA only, as the API gives it), your outgoing legs with
progress and a Recall button for the first 90 s, allied incoming; the POP screen gets a pulsing banner, the nav button a red badge.
- **Send dialog** (`screens/send.js`, `App.openSend({x,y,fromTownId,type})`, from the map tile sheet, Units, Movements): `GET /map/tile`,
types filtered by `milcore.moveOptions` (greyed ones say why), unit pickers (slider + stepper + all), cargo for transport, settle with
the wild-slot choice, latency/ETA/carry preview from `rules.movementMs`, `confirmEndProtection` checkbox, exploit-kit target, an
idempotency intent per opened dialog, server errors shown inline (`invalid_target` reasons translated).
- **Reports** (`screens/reports.js`, in More): cursor-paginated list, unread highlight + badge, mark read on open, mark all read, detail
layouts for raid/attack/takeover (role-aware victory/defeat, units sent/lost/left per group, strength, loot, siege, takeover loyalty),
scan (+ incumbent intel), scan_detected, incumbent, settle (opens the new POP), reinforce, movement_failed; coordinates jump to the map.
- **Expansion** (`screens/expand.js`, `send.js`, `main.js`, `render.js`): POP switcher in the resource bar, expansion card on the POP screen
(crews at home, footprint gate, POP list), settle through the send dialog; map draws your/incoming/allied movement lines with markers,
a red ring on your POPs that something is heading for, and a Send button in the tile sheet.
- **WebSocket** (`ws.js`): `createSocketClient` (injectable WebSocket and timers) + browser wiring. Auth as first message, ping every 25 s with
an 8 s pong timeout, jittered backoff 1 s .. 60 s, PROTOCOL close codes (4401/4400/1009 stop, 4429 waits 30 s), refetch after every
re-`ready`. Pushes go to `api.emit('push')` and refetch the affected thing; slow REST poll (45 s with the socket down, 3 min with it up).
- Tests: `test/client-mil.test.js` (type filter, unit roles, previews, perspective, backoff), `test/client-ws.test.js` (auth, ping/pong, backoff,
close codes, no token, throwing constructor); `client-i18n` parity covers `strings/military.js`.
- Looked at: headless Chromium (phone portrait/landscape, desktop; en and nb on the phone) against the real server in-process with a real
clock, seeded units/movements/reports, plus scripted flows on a phone profile: real WebSocket `open`, an `incoming` push from another
operator adding a row and a toast without polling, recall, raid/attack/transport/settle sends through the dialog (protection checkbox
gates the button, exploit-kit target reaches the server), train, withdraw, offline warning, report details of every type, POP list after
a settle resolved (`refreshTowns`).
Not done / not claimed:
- Not run: real devices or Safari, throttled networks, a socket behind nginx Proxy Manager, long sessions, the Playwright suite. The settle and
takeover resolution was exercised by fast-forwarding movement times in the DB, not by waiting.
- Takeover and capture flows (town_lost/town_gained pushes, losing the current POP) and the confederation `alliedIncoming` view have no
browser run. The Hostile takeover button stays enabled on a capital / last POP (the client cannot know); the server's refusal is shown.
- Withdraw and "call back" are one-tap with no confirmation. No unit icons (role icons only), no battle simulator / odds preview, no
cancel of training (the server has none), no sound or system notifications, no reports search/filter.
- The exploit-kit target picker only offers infrastructure types (the server also takes field slots f1..f18). Report group labels for
reinforcements show `#<townId>` because the report carries no names.
- Close 4401 stops the socket but does not itself send the player to login: that happens on the next REST 401 (`api` `unauthorized`).
- `ready.serverTime` is not used for the clock offset (no round-trip estimate on the socket); REST responses keep doing that.
## Client: trade, end game, alerts (public/)
Built (More group; strings in `strings/{trade,world,alerts}.js`, en + nb):
- **Exchange** (`screens/trade.js`): tabs Offers / New / Mine / Send. Offers: filters give / want / POP, reach pills, "Take" sheet with a POP chooser
from `acceptableFrom` (distance, transport time, stock, free links, why a POP is greyed out). New: live check with `rules.tradeTermsCheck` (1:2 band,
1000 per link, distance), stock and free-link checks, the exchange level a taker needs, escrow/expiry rules in words. Mine: status chips, poster/acceptor
role, expiry countdown, cancel. Send: direct transport through the send dialog (`App.openSend({ type: 'transport' })`; `milcore.moveOptions` got a
`transportOnly` flag so a rival's POP can be the target) plus links in use per exchange POP. No exchange: empty state with the requirement (Core router 4).
- **Backbone race / ended world** (`screens/world.js`, `endcore.js`, `cargo-ui.js`): phase banner (countdown to the landing sites, leading alliance, winner,
ended), the 7 sites with holder / level / build progress / stockpile, Manage sheet for your alliance's sites (build next level, ship resources, ledger),
scan/attack through the send dialog (`milcore.moveOptions` landing branch), final ranking tabs after the end. Whole-client ended mode: `App.worldEnded()`,
pill in the top bar, card on the POP screen, action buttons (primary/danger/`[data-act]`, not `[data-keep]`) disabled by a MutationObserver; a stale page
learns it from a `world_ended` error (via `App.errMsg`), the `world_ended` push or `/me`.
- **Map**: landing sites drawn as a diamond with a level ring (gold = incumbent, cyan = yours, magenta = rival alliance), legend row, tile sheet (holder, level,
Backbone race button, send). **Reports**: `landing` type, scans of landing sites, share to alliance, Alliance tab (folder), remove from folder; shared reports
are told from nobody's side. **Movements**: shipments to a site are labelled; `alliedIncoming` was already there and never counts in the red badge.
- **Alerts** (`alertkinds.js`, pure): every notification type the server writes (found by a test that greps `server/`) has a describer; includes trade_*,
backbone_*, world_ended, alliance_*, diplomacy_*, message kinds.
- Tests: `test/client-world.test.js` (endcore, moveOptions, string coverage, no HTML sinks, every public script parses), `test/client-alerts.test.js`,
`test/client-i18n.test.js` now iterates `CODES` of `server/errors.js`. 203 tests green.
- Looked at in headless Chromium against the real server (real clock, in-memory DB; scratch scripts, not in the repo): screenshot sweep of every new screen on phone
portrait, phone landscape and desktop (en, plus nb for trade/world) in three world states (day 62, day 100+ with held sites, ended); scripted flows with DB
assertions (take an offer, post with live validation, cancel, transport to a rival by coordinates, ship, build, scan/attack dialog, tap a site on the map, share
and unshare a report, alerts feed, a stale page hitting `world_ended`).
- **Push, end to end in real browsers**: Alice raids Bob; Bob's page (real login, WebSocket open) showed the incoming banner, red Moves badge and toast 214 ms
after the launch with no reload; the banner went away and the Reports badge rose when the raid arrived. With `WebSocket` undefined, and with a socket that is
closed at once (reconnect loop, 7 attempts in the run), the same raid showed up after about 52 s through the REST poll (15 s tick, 45 s gap): worst case about a
minute. Confederate Carol gets no push for `alliedIncoming` (known server gap): it shows when the Moves screen is opened or the poll runs, and never in her badge.
Found and fixed in the client: `report` pushes now also refetch movements (the incoming banner used to linger up to a few seconds after the arrival).
Not done / not claimed:
- Not run: real devices, Safari, a socket behind nginx Proxy Manager, throttled networks, the combat/takeover/diplomacy flows in a browser, long lists (offers > 25 per
filter paged only up to what the sweep seeded).
- Ended-world locking is a DOM sweep, not per-button wiring: a new primary/danger button that is NOT a game command must carry `data-keep`. Messages, ranking and
settings screens are exempt by selector. Open send/trade sheets that were opened before the end stay usable until the next DOM change or a refused command.
- Trade: no order book or price history, no notification for new offers in reach, offers are listed per page of 25 with a cursor only. The landing-site manage sheet
does not poll while open (it reloads after your own actions and when the site screen refreshes). Ledger shows the top 15 contributors.
- Site numbers are `index + 1` ("Landing site 1..7"), not a name from the server. `backbone_open` is only pushed on first touch (server E2): the countdown flips
by the client clock at `opensAt`, the sites appear after the next status fetch.
- A transport to a rival's POP is a gift that warns its owner (`incoming`, type hidden); the UI says so, but nothing stops a griefing stream of them.
- Server bug found and fixed (tiny): `POST /reports/:id/share` threw a 500 when no `reportCleanup` event was pending (`ensureCleanup` needs `ctx.enqueue`);
`reportShare` now wraps its ctx with `ctxOf`, regression test `test/report-share-cleanup.test.js` (failed before).
## E2E (`e2e/`, run with `npm run e2e`)
`e2e/run.js` (smoke suites: desktop, phone, layout, push) and `e2e/flows.js` (feature flows) boot the real server in-process (temp SQLite, real clock, `WORLD_SPEED` 4000 or 1) and drive
headless Chromium through `playwright-core`; `e2e/lib.js` holds the shared plumbing (`bootServer`, `newPage` with console/HTTP error capture, `hurryMovement` / `hurryEvents`).
Default run: 163 checks, about 137 s, no console error or failed request tolerated; every page gets a default action timeout of 8 s (`lib.js`), the smoke suites included. `node e2e/run.js <suite...>` runs named suites; `slow` only by name or `E2E_SLOW=1`.
- **units**: train 2 script crews through the sheet (cost preview scales, queue row with count and countdown, count pill), the batch completes (event moved up), units appear in the home list and
the database, an unaffordable train is explained and disabled, hosted reinforcements are listed and "send home" removes them and starts the return.
- **movements**: scan and raid from the Moves screen send dialog (coordinates, type, unit picker, preview, send), both in the outgoing list with countdown and recall button; the defender's page gets
the banner and the Moves badge by push (type and units hidden), both arrive, report badges on both sides, the Reports list (unread, then read on open, server read flag), the raid and scan report
sheets, the defender-side report.
- **reconnect**: the page's socket is closed and new ones refused; a raid launched in the gap is not shown; on reconnect a NEW socket opens and the missed raid appears (refetch on ready); a second raid
then shows by push within 6 s with the socket open and no reload.
- **alliance**: found (button disabled until valid), invite by name, accept on the other page, a broadcast written in Messages > Alliance, the unread badge on the other page by push, the feed row
(unread, sender), mark read, a second broadcast appearing live.
- **trade**: post (escrow), the offer on the taker's Offers tab, Take with the POP picker, both legs in flight (moved up past the 10 minute minimum latency), goods swapped, `completed` on both
"mine" tabs, an alert.
- **endgame** (own world backdated to day 100.5): banner "appear in" + how-it-works before, "open" + 7 site cards after, the held site is `mine` with Manage, others show scan/attack, a non-member
sees no Manage; the Manage sheet, ship 300 fiber (toast, transport row marked as a site shipment, stock drops), it lands and the stockpile and ledger show it.
- **nb**: live switch after every screen was drawn in English (visible text), reload and fresh render (text, aria-label, placeholder, title), nav labels, dynamic keys (`err.*` in the train sheet,
`send.reason.*`), raw-key detector, English-leftover detector, and a check that no multi-word nb string is a verbatim copy of its English text. The same detector sweeps pages that hold real
data at the end of the movements, alliance, trade and endgame flows (reports and sheets, alliance tabs, messages tabs, trade tabs, site manage sheet and dialogs).
- **pwa**: manifest link, `application/manifest+json`, display standalone, start_url inside scope and serving the shell, theme colours equal to the meta tag, every icon 200 + image type + PNG
dimensions equal to the declared sizes, a maskable icon, apple-touch-icon, no service worker.
- **slow**: `WebSocket` removed from the page; the raid is not shown within 8 s, then shows by polling (59 s in the run, worst case about 60 s), no reload, socket never open.
How the checks were shown to be able to fail (each mutation applied, the named suite run, reverted): units queue never drawn (units), home list never drawn (units), reports never marked read
(movements), manifest served as octet-stream (pwa), no refetch on socket ready (reconnect), no reconnect scheduling (reconnect), alliance accept sends decline (alliance), trade accept with a wrong POP
(trade), open banner never drawn and ship endpoint misspelt (endgame), a copy-pasted English string in the nb table (nb), polling interval removed (slow); the nb detector additionally runs a planted raw
key, a planted English string and a deleted nb string on the live page, and a calibration run in English (it must see >= 8 English strings on the POP screen). Message push: the push check failed
on the tree before the fix below.
Real app bugs found: (1) `{type:'message'}` push was received and ignored (the unread badge and the open Messages list only moved on the 60 s poll or a tab switch): `messages.js` now refetches the unread
count and the visible inbox / alliance feed / open thread on that hint (regression: alliance flow, fails without it); (2) the "New" button of the Messages header stayed English after a live language
switch (built once in `render()`): now set in `onShow` (regression: nb flow, "switched live"). Not fixed, see the gaps above: stale aria-labels after a live switch; More badge double counts a message.
Not covered: takeover/capture, diplomacy moves, confederation `alliedIncoming`, rankings content, reports share to the alliance folder, settings devices list, Firefox/WebKit, real devices.
Caveats: flights and trade legs are moved up with `UPDATE movements/events` + `scheduler.arm()`, not by waiting; the end-game world is made 100.5 days old by moving `worlds.start_at` and
the 7 site rows come from `ensureSites` (what the first scan or attack does) with the holder written by SQL; the 60 s slow suite is not in the default run.
## Stage 6 (server half): WebSocket push
Built: `/ws` on the game's HTTP server (`server/push.js` transport, `server/pushHooks.js` routing), contract in `docs/PROTOCOL.md`.
Auth as first message (`ready` / close 4401), Origin check (`net.originAllowed`), per-IP cap `MAX_CONN_PER_IP` (HTTP 429), 1 KB frames,
10 s auth timeout (4408), per-socket token bucket (4429), bad-message budget (4400), ping/pong keepalive that terminates dead sockets and
re-checks the token on every tick (revoked/banned: 4401), graceful 1001 close inside `srv.close()`. Hints: `town`, `incoming`,
`notification`, `report`, `message`, `pong`. Every `notifications` row (via `scheduler.notify` -> post-commit outbox -> `onNotify`) pushes a
`notification` hint, plus the typed ones; finished events and committed commands push `town` to the owners of the POPs they touched.
Hints go out only after the transaction that caused them committed (a rolled-back event or command pushes nothing); identical hints of
one tick are merged. Small edits outside the new files: `scheduler.js` (outbox, `notify` returns the row id), `commands/index.js`
(`hooks.onCommand`, outbox flush/rollback), `index.js` (upgrade + shutdown).
Tests: `test/push-ws.test.js` (auth ok/bad/timeout, origin, path, per-IP cap and its release, rate limit, bad budget, oversize frame, dead
socket, revoked token, banned user, shutdown, REST with no socket) and `test/push-game.test.js` (build/train done, incoming only to the
defender, report/message/alliance invite hints, recall, coalescing, rollback). Real `ws` client, fake clock, port 0. `npm test`: 113 pass
when this was written (208 on 2026-10-11, whole suite).
Not done / not claimed:
- The client now exists (`public/js/ws.js`, see "Client: military, expansion, WebSocket") and was run against this server in a headless browser; not through a proxy.
- Revocation closes the socket at the next ping tick (default 30 s), not instantly: `POST /auth/logout` and token deletion do not call push.
- No load test (many sockets, large catch-ups), no test behind a real nginx Proxy Manager (upgrade headers, idle timeouts, `X-Forwarded-For`
for the per-IP cap); only the code paths of `net.clientIp` are reused. The proxy's idle timeout (NPM default 60 s) is above nothing we
send: the 30 s ping keeps sockets alive, but that is reasoning, not a measurement.
- Hint gaps: owners of reinforcements standing in an attacked POP get `report` but no `town` hint for their home POP; no `incoming` for
confederates; no APNs/FCM sender (the `notifications` table plus `scheduler.onNotify` is where it would attach); no resume after a gap.
- The ws tuning knobs (`wsPingMs`, `wsRate`, ...) are `createServer` options only, not environment variables.
## Trade, end game, gaps (server only; migration `004_trade_endgame.sql`)
Built and tested (`test/trade-*.test.js`, `test/endgame-*.test.js`; fake clock, in-memory db, port 0; contract-checked responses over HTTP):
- **Trade:** offers "give X of A for Y of B within Z tiles" with escrow, a link reserved per open offer, 1:2 ratio band, expiry event,
cancel, accept = two transports in one transaction (all or nothing), the `transportArrived` consumer completes the offer, void when the
POP is taken over. Conservation is asserted (every unit in POPs + escrow + on the road, before and after; the only loss is the existing
Rack hall overflow, asserted too). Routes under `/trade/offers`.
- **End game:** 7 seed-derived landing sites (`rules.backboneSites`, `tileAt` with the world age; spawn and settle refuse them from day 0),
open at world day 100 / speed, taken with scan/attack against a static heavy defence, node level 1..100 built from a stockpile fed by
transports (`/backbone/:id/ship`, `/build`), winner at level 100, `worldEnd` two world days later with a stored ranking snapshot and a frozen
world, `world_ended` for every game command, `GET /worlds/:id/status` and `/results`. One end-to-end test runs day 100 -> take -> ship ->
build -> win -> ended on a speed-2 world; the ended-world gate is also driven over HTTP.
- **Gaps closed:** shared report folder (`report_shares`, `/reports/:id/share`, `/alliances/:id/reports`), `alliedIncoming` in `GET /movements`,
`buildDone` is relative to the building's current level (test written first, failed before the fix).
Not done / not claimed:
- **Nothing here is balanced.** Defence multiplier 12 (+3% per level), node cost 4000 x 1.045^(L-1) (about 7.2 M of each resource in total),
node time 2 h x 1.025^(L-1) (about 36 world days), 48 h offer ttl, 10 tiles of reach per exchange level, 500-per-side offers: first guesses,
no bot run when written (now there is one: BALANCE.md section 5 says an 18-member alliance needs 55 to 78 days after the sites open with 1000 per link, and does not finish in 175 days with 500).
- **Garrisons at landing sites** (E6, migration 005 `site_stationed`, `server/military/garrison.js`, `POST /backbone/:id/withdraw`): built and tested (`test/endgame-garrison.test.js`,
`test/client-garrison.test.js`), bots garrison and assault (`tools/bot/endgame.js`, `--no-contest` turns it off). Not built / not claimed: no `captureLevelLoss`
(a taken site keeps its node level), no sitter, `tools/admin.js inspect-town` does not list garrison units, the site sheet was not opened in a real browser, a holder cannot send
a member's units away, confederates cannot garrison (members only).
- No `backbone_open` push at the moment the sites appear unless something touches a site first (E2); clients see the phase by polling status.
- Trade: no multi-link deals (each side <= 500), no price history or order book, no counter-offers, no notification when a new offer appears
in reach, offers are not hidden from enemies, the escrow of a taken-over POP goes to the conqueror.
- Ended worlds: movements still `out` and queued builds are left as they were (events cancelled, E3); `tools/admin.js end-world` now runs the real `worldEnd` handler (snapshot, escrow back, events cancelled; ops part below); `reset-world`
wipes a world's rows without it (DEPLOY.md section 6); several winners are impossible by design.
- The ranking snapshot is the same numbers as `/rankings`, computed once; `/rankings/*` after the end still compute live from the frozen state.
- Client for all of this: see "Client: trade, end game, alerts" above.
## Stage 7 (first part): bot harness and first balance pass
Built: `tools/bot.js` (+ `tools/bot/*`): N headless bots (builder, raider, conqueror, turtle, expander, trader, alliancer; a coordinated alliance
plays the end game) against the real server in-process (`createServer` with an in-memory DB and a FakeClock, bots drive `srv.commands.run`, no
HTTP), 50 players x 14 days in ~3 s, x 170 days in ~140 s. Per-day economy, progression, combat, trade, alliance, end game, performance and
error tables; `--json`, `--set PATH=VALUE` data overrides, `--sessions-per-day`, `--always-on`, `--speed`, `--strategy-mix`. Exit code 1 when an
invariant breaks: exact resource conservation (production measured at every settle, sinks from command results and notifications), exact unit
conservation, no negative stock, no failed events, no unexpected error codes. `docs/BALANCE.md` has the method, every run behind a number, what
was tuned and what was not.
Tuned (each with before/after runs in BALANCE.md): second build slot at Core router 3 (was 10), transport capacity 1000 per link (was 500).
Server fix found by the harness: bounced shipments reported no overflow (`events/return.js`).
Tests: `test/bot-run.test.js` (12 players x 6 days twice, identical stats, invariants, the checks catch tampering, a fast world reaches the end game),
`test/bot-server-fixes.test.js`.
Not done / not claimed: **the game is not balanced**; the bots are not humans (no reinforcement, recall, messages, sitters; fixed sittings). Open
items from the pass: (a 3x world's end game being as long as a 1x world's is fixed by B7, `rules.transportCapacity`); (trade escrow refund clipping and loot destruction on overflow were fixed afterwards by B6, BALANCE.md section 9);
the capital runs out of things to build ~50 days before the backbone opens at 4 sittings a day; (a built-up landing site being out of reach of any single-POP army is
answered by E6: garrisons and waves, BALANCE.md section 5).
## Stage 7 (ops part): admin CLI, deploy files
Built: `tools/admin.js` (status, migrate, worlds, create-world, end-world, users, operators, ban/unban/revoke-tokens, inspect-operator/-town, events,
replay-events [--simulate], backup/verify-backup (VACUUM INTO, verified, pruned), reset-world, grant), `deploy/` (service, backup service + timer,
`upstream-admin` wrapper), `docs/DEPLOY.md`. Tests: `test/admin-cli.test.js`. Run by hand on 2026-10-11 in a scratch directory: see "Status at a glance".
Added later: `end-world` runs the real `worldEnd` event handler (final ranking snapshot so `/worlds/:id/results` is available, trade escrow back,
the world's other pending events cancelled, `world_ended` notifications; overdue events of that world are processed first; refuses without `--yes`),
quiet on EPIPE (`admin.js ... | head`); `deploy/update.sh` (git fast-forward update on the box: tools checked up front, service STOPPED before the tree changes (review R2), verified snapshot of the stopped db, `npm ci --ignore-scripts` only when the lock
changed, optional `--test` on a `git archive` copy as the service user, health check, rollback to the old rev, `--dry-run`); `deploy/upstream-offsite` + `.service`/`.timer` (off-box copy of the newest
verified snapshot to `OFFSITE_DEST`, skipped unless configured). Tests: `test/admin-endworld.test.js`, `test/deploy-update.test.js` (stubbed systemctl/curl/npm),
`test/deploy-offsite.test.js` (local directory as destination; needs rsync; scp was removed in R2).
Not done / not claimed: nothing of it has run under systemd or on Debian 13 (DEPLOY.md lists what was and was not run); `update.sh` and the off-site
copy were run only against stubs / a local directory (no real ssh, rrsync, systemd, runuser, npm ci or /healthz; shellcheck and dash were not available); a migration cannot be rolled back by
`update.sh` (it prints the snapshot to restore); `end-world` cannot repair a world ended by the old flag-flip version (no snapshot); the notification
rows the CLI writes are not pushed by a running server; no load test with real sockets; no scheduled "create next world".
## Not done
- Stage 7 remainder: balance passes beyond B1, B2 and B4 with the open items above, a real world lifecycle (start, natural end, reset) driven from the CLI,
load test over HTTP/WebSocket, e2e for takeover/capture/diplomacy/confederation views, and a human playtest. Everything else in CLAUDE.md "Working in stages" is built.