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

32 KiB

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.