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
40 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: 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 realwsclient, client logic, bot harness, admin CLI).npm run openapileavesdocs/openapi.jsonunchanged (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 helpworks.- The deploy path from DEPLOY.md in a scratch directory, without systemd: first boot (migrations, world),
/healthz, signup, a build,admin.jsstatus/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 freshDB_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=1adds 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 exactcargoLost; several raids from one home no longer share the same free room, S6; trade accept is refused withno_room_for_goodswhen 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_openpush (sites are created lazily, E2); noincomingfor confederates and notownhint 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.idcan be reused after a full cleanup (S3, low); no recovery sweeper if anarrive/returnhandler 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-labels (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
alliedIncomingview, 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_statsnow 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.jsexists 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 withrules.resourcesAtfrom the server clock, hash routing. - Screens (
js/screens/): login/signup (invite field appears aftersignup_closed), POP (resource fields by type, infrastructure, build queue with countdowns and cancel, power panel, detail sheet with the server'snextplan, live affordability, rename), map (js/render.jscanvas: pan, pinch, wheel, keyboard, culling; chunkedGET /mapcache; 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-Keyper intent,ApiError.code, event emitter with apushevent (the WebSocket clientws.jscame 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);
/meexposes 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 anymorescreen 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.popSectionslets screens add cards to the POP screen (incoming banner, expansion card). - Shared state (
milstate.js):App.mil.moves(lastGET /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/mewithout the destructivesetSession, 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.trainPlanpreview, 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 bymilcore.moveOptions(greyed ones say why), unit pickers (slider + stepper + all), cargo for transport, settle with the wild-slot choice, latency/ETA/carry preview fromrules.movementMs,confirmEndProtectioncheckbox, exploit-kit target, an idempotency intent per opened dialog, server errors shown inline (invalid_targetreasons 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 toapi.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-i18nparity coversstrings/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, anincomingpush 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
alliedIncomingview 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 (
apiunauthorized). ready.serverTimeis 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 fromacceptableFrom(distance, transport time, stock, free links, why a POP is greyed out). New: live check withrules.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.moveOptionsgot atransportOnlyflag 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.moveOptionslanding 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 aworld_endederror (viaApp.errMsg), theworld_endedpush 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:
landingtype, 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;alliedIncomingwas already there and never counts in the red badge. - Alerts (
alertkinds.js, pure): every notification type the server writes (found by a test that grepsserver/) 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.jsnow iteratesCODESofserver/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
WebSocketundefined, 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 foralliedIncoming(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:reportpushes 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_openis only pushed on first touch (server E2): the countdown flips by the client clock atopensAt, 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/sharethrew a 500 when noreportCleanupevent was pending (ensureCleanupneedsctx.enqueue);reportSharenow wraps its ctx withctxOf, regression testtest/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,
completedon 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
minewith 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:
WebSocketremoved 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.jsnow 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 inrender()): now set inonShow(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, confederationalliedIncoming, rankings content, reports share to the alliance folder, settings devices list, Firefox/WebKit, real devices. Caveats: flights and trade legs are moved up withUPDATE movements/events+scheduler.arm(), not by waiting; the end-game world is made 100.5 days old by movingworlds.start_atand the 7 site rows come fromensureSites(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/logoutand 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-Forfor the per-IP cap); only the code paths ofnet.clientIpare 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
reportbut notownhint for their home POP; noincomingfor confederates; no APNs/FCM sender (thenotificationstable plusscheduler.onNotifyis where it would attach); no resume after a gap. - The ws tuning knobs (
wsPingMs,wsRate, ...) arecreateServeroptions 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
transportArrivedconsumer 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,tileAtwith 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,worldEndtwo world days later with a stored ranking snapshot and a frozen world,world_endedfor every game command,GET /worlds/:id/statusand/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),alliedIncominginGET /movements,buildDoneis 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-contestturns it off). Not built / not claimed: nocaptureLevelLoss(a taken site keeps its node level), no sitter,tools/admin.js inspect-towndoes 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_openpush 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
outand queued builds are left as they were (events cancelled, E3);tools/admin.js end-worldnow runs the realworldEndhandler (snapshot, escrow back, events cancelled; ops part below);reset-worldwipes 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.