Upstream/docs/NEXT.md
jvanvik cc0524de5e Smoke e2e, docs consistency pass, status summary
Built: e2e/run.js + lib.js (playwright-core, in-process server, temp DB): desktop flow, phone touch portrait/landscape, layout matrix on 5 viewports x pop/map/trade/world (overflow + console errors), WebSocket push incoming-banner without reload. 61/61 checks, ~54 s, identical over 4 runs; the push and overflow checks were shown to fail when the behaviour is removed.
Docs: fixed stale numbers/claims in DESIGN, DECISIONS, BALANCE, API (undocumented routes, rate limits, notification types), DEPLOY, NEXT (status-at-a-glance on top). Deploy path exercised in a scratch dir: migrations, healthz, signup/build, admin CLI, SIGKILL catch-up, backup restore.

Tested: npm test 207/207, npm run e2e 61/61, bot run 50x14d INVARIANTS OK.
NOT tested: Chromium only; no systemd/nginx Proxy Manager/Node 22.13 run; e2e does not cover units, alliances, messages, trade or end-game flows beyond empty-state rendering; no nb, PWA or polling-fallback e2e; docs/workflows/ still empty.

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

290 lines
32 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`: 207 tests pass in about 7 s (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`, Playwright): see the e2e section of this file, if present; not re-run for this status.
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:** nothing is tuned beyond B1/B2 (BALANCE.md). Open: a 3x world's end game is as long as a 1x world's; after the opening days
nobody can contest a built-up landing site (no garrisons, E1); raid loot is split evenly and destroyed on overflow (S4); trade escrow
refunds are clipped at the Rack hall cap without a notice (S2); 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; admin `end-world` is a flag flip without ranking snapshot (DEPLOY.md section 6).
- **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.
- **Docs:** `docs/workflows/` (planned stage workflows, CLAUDE.md layout) is empty: no stage workflow was ever written there.
- **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, screens refetch
on open and on manual refresh); 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 full Playwright suite (only the smoke e2e exists), 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).
## 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 (207 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).
- **No garrison at landing sites** (E1): defence is static, holders cannot station units. If the first world shows the race is decided by who
hits first, the next step is a small `site_units` table with reinforce-to-site and defenders in `landing.js`.
- 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` only flips the status (no snapshot, no event cancellation) and `reset-world`
wipes a world's rows; neither runs the real `worldEnd` event (see 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 is as long as a 1x world's (shipping is per sitting; `capacityPerLink x speed` needs the client to stop
reading the constant); trade escrow refunds are clipped at the Rack hall cap silently; raid loot is split evenly over resources and destroyed on overflow;
the capital runs out of things to build ~50 days before the backbone opens at 4 sittings a day; a built-up landing site is out of reach of any
single-POP army (no garrisons, E1), so there is no fight for a site after the first days.
## 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".
Not done / not claimed: nothing of it has run under systemd or on Debian 13 (DEPLOY.md lists what was and was not run); no load test with real sockets;
world lifecycle through the CLI is partial (above); no scheduled "create next world".
## Not done
- Stage 7 remainder: balance passes beyond B1/B2 with the open items above, a real world lifecycle (start, natural end, reset) driven from the CLI,
load test over HTTP/WebSocket, the full e2e suite and a human playtest. Everything else in CLAUDE.md "Working in stages" is built.